The Deployment Framework command: dfw

The command-line utility for working with the Caplin Deployment Framework is the command dfw. You can perform any Framework operation by running the dfw command with the appropriate parameters.

Contents:

Getting started

Before entering any dfw command as ./dfw <command-name>, make sure your current (working) directory is set to the Deployment Framework's topmost directory.

To get a list of all the possible Framework commands, type:

./dfw help

To get help on how to use a particular Framework command, type:

./dfw help <command-name>

To run a Framework command, type:

./dfw <command-name> <command-parameters>

When you run a dfw command that changes the configuration of any of the components and blades, it displays a message reminding you to restart the Deployment Framework:

The configuration has been updated. The new configuration will not be active until the Framework is restarted.

Completing dfw commands using the <tab> key

From the Deployment Framework 6.2, the dfw command supports tab-completion of dfw commands and context-sensitive completion of parameters.

Tab-completion for the dfw command is not enabled by default. To enable tab-completion, see Setting up dfw command completion.

Note: tab-completion is an optional convenience for the dfw command, but a requirement for using a relative file path with the logcat command's -f option.

Example: starting LiberatorDemoDataSource with tab-completion

When you type ./dfw TabTab, a list of all the dfw commands is displayed.

$ ./dfw
activate       delete         info           redeploy       validate 
clean          deploy         java           rollback       versions 
clean-nostop   dump           java32         start          veryclean 
cleanstart     erase          killAll        status         
cmc            help           logs           stop           
deactivate     hosts          mon            support
$ ./dfw

When you type ./dfw Tab, more than one command matches the partially-completed command, and a list of all commands beginning with 's' is displayed.

$ ./dfw s
start     status    stop      support
$ ./dfw s

When you type ./dfw staTab, only the start command matches the partially-completed command, and the command is completed.

$ ./dfw start

When you type ./dfw start TabTab, a list of all runnable blades is displayed. The list includes a virtual-blade 'servers' that can be used to refer to all core components (Liberator and Transformer) available in the Framework.

$ ./dfw start
Liberator                 servers                   
LiberatorDemoDataSource   Transformer
$ ./dfw start

When you type ./dfw start LiTab, all matching runnable blades share the common prefix 'Liberator', and the command is completed to the common prefix.

$ ./dfw start Liberator

When you type ./dfw start LiberatorTabTab, more than one runnable blade matches the partially-completed parameter, and a list of blades beginning with 'Liberator' is displayed.

$ ./dfw start Liberator
Liberator                 LiberatorDemoDataSource
$ ./dfw start Liberator

When you type ./dfw start LiberatorDemoTab, only the LiberatorDemoDataSource blade matches the partially-completed parameter, and the parameter is completed.

$ ./dfw start LiberatorDemoDataSource

Running dfw in debug mode

You can obtain more information about a dfw command error by running the dfw with the debug option -x. This displays all the commands that are run in the script underlying the dfw command.

The -x option must be the first option on the command line after ./dfw 

For example, say you run the command below and it generates an error:

./dfw start <Blade name>

To obtain more information about the error, run the command again as:

./dfw -x start <Blade name>

Note: When in debug (-x) mode, tab-completion is disabled.

dfw commands

Here are the dfw commands (in alphabetical order).

Command parameters shown inside square brackets [] are optional.

Click on a command name to get more detail about it:

  • activate <bladename1> <bladename2> ...
  • clean [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]
  • cleanstart [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]
  • cmc
  • deactivate [<bladename1> <bladename2> ...]
  • delete [<bladename1> <bladename2> ...]
  • deploy [-f] [<kitname1> <kitname2> ...]
  • dump [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] servers]
  • hosts
  • hosts {<bladename>|Liberator|Transformer} <primary-host> [<secondary-host>]
  • hosts all <primary host> [<secondary host>]
  • info 
  • java <JVM-location>
  • java32 <JVM32-location>
  • killAll
  • logs [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]
  • mon
  • redeploy [-f] [<kitname1> <kitname2> ...]
  • rollback [<kitname1> <kitname2> ...]
  • start [Liberator] [Transformer] [<bladename1> <bladename2> ...] [servers]
  • status​ 
  • stop [Liberator] [Transformer] [<bladename1> <bladename2> ...] [servers]
  • support [directory]
  • validate
  • versions
  • veryclean [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

activate

./dfw activate <bladename1> <bladename2> ...

Activates a blade or blades.

Important: Stop all components before activating blades.

You won't see the effects of activating the blade(s) until you restart the system (see ./dfw start). 

To get the names of all the available blades, use the command ./dfw versions, or enable tab-completion t.

clean

./dfw clean [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

Warning: this command stops the specified components, or all running components if no components are specified.

Removes all log files that have been produced by the deployed core components (Liberator and/or Transformer) and active Adapter blades.

  • If you don't give the command any parameters, it stops all the deployed components and active Adapter blades and cleans them.
  • If you specify one or more items (Liberator and/or Transformer and/or one or more Adapter blades) the command just stops and cleans those.
  • If you supply only the parameter called servers, the command just stops the deployed core components (Liberator or Transformer or both) and cleans them.

In Deployment Framework release 6.1 and earlier, when you explicitly or implicitly include Liberator in the command parameters, the command also removes the database files containing information about the Liberator users’ licence usage. To do the same in Deployment Framework release 6.2 and later, use the command ./dfw veryclean instead.

cleanstart

./dfw cleanstart [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

Warning: this command stops the specified components, or all running components if no components are specified.

Stops all the deployed components, removes log files (as for ./dfw clean), and starts the system again.

  • If you don't give the command any parameters, it stops, cleans, and starts everything.
  • If you specify one or more items (Liberator and/or Transformer and/or one or more Adapter blades) it just stops, cleans, and starts those.
  • If you supply only the parameter called servers, the command stops, cleans, and starts just the deployed core components (Liberator or Transfomer or both).
  • In Deployment Framework release 6.2 and later, the command stops all currently running items first, before restarting them.
    In releases 6.1 and earlier, it stops a running item and immediately restarts it, before moving on to stop and start the next item.

To start or restart the system without removing the log files, use the command ./dfw start

cmc

./dfw cmc

Starts the Caplin Management Console (CMC) if it's installed and there's a CMC configuration file available. (Use the command ./dfw mon to create the configuration file.)

If you are accessing the Deployment Framework remotely, there are additional requirements:

  • If you're using SSH to access a Deployment Framework on Linux or macOS, you must enable X11 forwarding on the remote SSH server before running the cmc command.
  • If you're using Windows Remote Desktop to access a Deployment Framework on Windows, you must change the value of the remote SESSIONNAME environment variable to 'Console' before running the cmc command. From a Cygwin or Git Bash command line on the remote Windows server, enter the following command to start the CMC:

    SESSIONNAME=Console ./dfw cmc

    Note: if the value of the remote SESSIONNAME environment variable is anything other than 'Console', then the CMC will fail to start and will throw the errors below:

    Error: Cannot start CMC from this terminal

    Error: Command <cmc> failed with code <141>

deactivate

./dfw deactivate [<bladename1> <bladename2> ...]

Deactivates a blade or blades.

Important: Stop all components before deactivating blades.

You won't see the effects of deactivating the blade(s) until you restart the system (see ./dfw start). 

To get the names of all the available blades, use the command ./dfw versions

delete

./dfw delete [<bladename1> <bladename2> ...]

Warning: this command stops all running components

Deactivates and deletes a blade or blades.

The blade kit isn't deleted from the archive directory (<Framework-root>/kits/archive/), so you can subsequently retrieve and redeploy the blade if you need to.

If a deleted blade has configuration overrides, they're deactivated but aren't removed.

deploy

./dfw deploy [-f] [<kitname1> <kitname2> ...]

Warning: this command stops all running components

Use this command to deploy core components and blade kits. The core components and all blades supplied by Caplin Systems are delivered in kit form. This command unpacks any kits that are in the Framework's kits directory and any kits provided on the command line, and activates each unpacked blade. When a kit has been deployed from the kits directory, the command moves the kit file to <Framework-root>/kits/archive/ directory.

If any kit location provided on the command line has spaces in the path, enclose the whole thing in double quotes ("). You can use wildcards in the pathnames.

Use the -f parameter to remove the Framework files relating to older kit versions without the command prompting you. However, if you do remove the files for an older kit version (either using -f or in response to a prompt), you can't subsequently revert to that kit using the rollback command - you'll have to redeploy the kit instead.

Also see the redeploy and rollback commands.

dump

./dfw dump [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

Warning: do not run this command when clients have access to the server. This command stops all running components, and then briefly runs components that are both activated and runnable in order to dump their configuration.

Stops the system (all the deployed components) and dumps configuration information for each deployed core component (Liberator and/or Transformer) and Adapter blade. The dumped information is in files in directories under global_config/dump. Each dumped file contains every original configuration line with its filename and line number, followed by the same lines with any configuration macros translated to their actual values.  All the configuration within any included files is listed in the same way.

  • If you don't give the command any parameters, all the deployed core components and Adapter blades are stopped and their configuration is dumped.
  • If you supply a list of core components and/or adapter blades, just those components and/or blades are stopped and their configuration is dumped.
  • If you specify the servers parameter, only the deployed core components are stopped and their configuration is dumped.

When you've changed the configuration of a production system, we recommend that you run the dump command immediately, before restarting the system. The most up-to-date configuration data will then be readily available if Caplin Support need it to help fix a problem with your running system. If you don't run dump before restarting, you'll have to stop the running system to get the configuration needed to diagnose a fault.

To dump the configuration to another location, define an environment variable called DFW_DUMP_DIR that specifies the location's path.

hosts

./dfw hosts

./dfw hosts {<blade_name>|Liberator|Transformer} <primary_host> [<secondary_host>]

./dfw hosts all <primary_host> [<secondary_host>]

where:

  • <blade_name> is the name of an adapter blade.
  • <primary_host> is the hostname of the primary server on which a specified component is to run.
  • <secondary_host> is the hostname of the secondary server on which a specified component is to run. This parameter is only required if you're setting up a Platform deployment that incorporates failover and/or load balancing.

This command updates the global-config/hosts-defns.conf file and the global-config/hosts.conf file with the hosts on which adapter blades and core components are to run. Do not edit the hosts.conf file directly, and only edit the hosts-defns.conf file directly to remove a line for an incorrectly spelled component (see later).

The first form of the command, without any parameters, lists the hosts on which adapter blades and core components are configured to run.

The second form of the command sets the host or hosts on which a specified adapter blade, Liberator, or Transformer is to run.

The third form of the command, with 'all' as the first parameter, is a convenience command for use in development. It creates host configuration for Liberator, Transformer, and all deployed adapter blades. Configuration is created for Liberator and Transformer regardless of whether they have been deployed, but configuration is only created for adapter blades that have been deployed. If you deploy new adapter blades after running this command, then re-run this command to generate host configuration for the new adapter blades.

For example, developers can use the convenience command below to set Liberator, Transformer, and all installed adapter blades to run on their local machines:

./dfw hosts all localhost

For detailed examples of setting up primary and secondary hosts for failover, see Change server hostnames.

Typing errors in a host address can be corrected by re-entering the ./dfw hosts command again with the correct host address.

Typing errors in the name of an adapter blade or core component can be corrected by re-entering the the ./dfw hosts command with the correct spelling; however, the entry with the incorrect spelling remains in the host-defns.conf file and continues to show when the ./dfw hosts command is run to list configuration entries. The incorrect entry will not affect the operation of the Deployment Framework, but if you wish to remove it for cosmetic reasons, then you can remove the line from the hosts-defns.conf file manually . This is the one operation for which you need to edit the hosts-defns.conf file directly; use the the ./dfw hosts command to make all other host configuration changes.

Tip: To avoid making typing errors in adapter-blade names, use dfw command completion. See Setting up dfw command completion.

info

./dfw info

Displays information about the core components (Transformer and/or Liberator) and the currently active blades. This includes:

  • The port numbers used by the core components
  • The port numbers used by the active blades
  • Java configuration information

java

./dfw java <JVM-location-and-name>

Sets up the location and name of the JVM (Java Virtual Machine) for use by Liberator and Transformer and any C-based Adapter blades. It defines this as a configuration macro called JVM_LOCATION (see Configuration macros and items).

The <JVM-location-and-name> parameter must be a Linux style pathname with forward slash (/) separators, even if it's a Windows path. Don't use Windows-style backslash (\) separators - the command won't find the path.

Example (for Windows):

./dfw java "C:/Program Files (x86)/Java/jre7/bin/client/jvm.dll"

If the path name in <JVM-location-and-name> contains spaces, enclose the whole thing in double quotes ("), or escape the spaces.

If you're using Deployment Framework release 6.2 or later, and you need to use a 32 bit JVM on Linux (for example, when you have a 32 bit C-Based Adapter blade that uses Java), set the JVM location using the command ./dfw java32.

To set up the location and name of the JVM (Java Virtual Machine) for use by Java-based Adapter blades, you need to explicitly define the configuration item jvm-location in the blade's configuration; see How can I... Configure a DataSource application's JVM

java32

./dfw java32 <JVM32-location-and-name>

Platform: Linux

Since: Deployment Framework 6.2

Sets up the location and name of the 32 bitJVM (Java Virtual Machine) in Linux environments, for use by 32 bit C-Based Adapter blades.  It defines this as a configuration macro called JVM_LOCATION32 (see Configuration macros and items).

If the path name in <JVM32-location-and-name> contains spaces, enclose the whole thing in double quotes ("), or escape the spaces.

Example:

./dfw java32 /usr/local/java/jre/lib/i386/server/libjvm.so

killAll

./dfw killAll

Platform: Not available in Git bash shell

Since: Deployment Framework 6.2

Kills all processes that were started from the dfw directory.  Run this command if ./dfw stop didn't stop all of the processes that were started by the ./dfw start or ./dfw cleanstart command.

logs

./dfw logs [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

Since: Deployment Framework release 6.2

Copies all log files produced by the Framework components to directories under <Framework-root>/global_config/logs/, removing any existing logs at the target location.

  • If you don't give the command any parameters, the log files of all the deployed core components (Transformer and/or Liberator) and Adapter blades are copied.
  • If you supply a list of core components and/or Adapter blades, the log files for just those components and/or blades are copied.
  • If you specify the servers parameter, only the log files of the deployed core components are copied.

To copy the log files to a different target location, define an environment variable called DFW_LOGS_DIR that specifies the location's path.

mon

./dfw mon

Creates a configuration file for the Caplin Management Console (CMC).  The file includes configuration relating to all the JMX-enabled DataSource peers that are currently deployed.

Important: Exit the CMC before executing this command. The CMC loads its configuration on startup and saves its configuration on exit. If the CMC is running when you execute the mon command, then the configuration changes written by mon will be lost when the CMC next exits.

redeploy

./dfw redeploy [-f] [<kitname1> <kitname2> ...]

Since: Deployment Framework 6.2.1

Warning: this command stops all running components.

This convenience command re-deploys one or more core components and/or blade kits that were previously deployed (see the deploy command). redploy obtains the kit(s) from the Deployment Framework's kits archive directory (<Framework-root>/kits/archive/); it saves you from having to look in the archive, find the full file names of the required kits and then supply these names to the deploy command.

The most convenient way to use this command is with tab completion to select each archived kit that you want to redeploy.

To revert to using another previously deployed kit without redeploying it, use the rollback command.

Use the -f parameter to remove the Framework files relating to older kit versions without the command prompting you. However, if you do remove the files for an older kit version (either using -f or in response to a prompt), you can't subsequently revert to that kit using the rollback command - you'll have to redeploy the kit instead.

rollback

./dfw rollback [<kitname1> <kitname2> ...]

Since: Deployment Framework 6.2.1

Warning: this command stops all running components

Rolls back one or more core components and/or blades to previously unpacked (deployed) kits. This command is useful when you've deployed a Platform component or blade that turns out to be faulty and you want to revert to a previous good version without having to redeploy it.

For example, assume that you originally deployed Liberator 6.2.5 and Transformer 6.2.4 and you then upgraded both these components by deploying the newer versions Liberator 6.2.6 and Transformer 6.2.5, keeping in place the files for the older versions. If you subsequently decide that you need to roll back to using the older versions, you would run the command:

./dfw rollback  Liberator-6.2.5-<build-no> Transformer-6.2.4-<build-no>

Note that unlike the deploy and redeploy commands, you don't supply a file extension in the kit name parameter (Liberator-6.2.5-<build-no> not Liberator-6.2.5-<build-no>.zip)

The rollback command doesn't unpack the selected kits again; it just changes the links that point to the currently deployed kits. In the above example, the link called Latest in <Framework-root>/kits/Liberator/ is changed, and so is the Latest link in <Framework-root>/kits/Transformer/

You can use the command to roll forwards as well as back. Following on from the previous example, to roll forward to the latest Liberator and Transformer that was previously deployed, you would run the command:

./dfw rollback  Liberator-6.2.6-<build-no> Transformer-6.2.5-<build-no>

The most convenient way to use this command is with tab completion, which will allow you to easily select the unpacked kits you want to restore.

If you want to revert to a kit for which you had previously removed the Framework files (for example, by running deploy or redeploy with the -f option), then the kit won't be available to the rollback command. You will have to redeploy the kit instead.

If there's only one version of a particular kit deployed, the command presents this kit as available to rollback to, but the rollback is a "null" operation.

start

./dfw start [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

Stops the core components (Transformer and/or Liberator) and Adapter blades and starts them up again. 

  • If you don't give the command any parameters, it stops and starts all the running components and Adapter blades.
  • If you specify one or more items (Liberator and/or Transformer and/or one or more Adapter blades) it just stops and starts those.
  • If you supply only the parameter called servers, the command stops and starts just the deployed core components (Liberator or Transfomer or both).
  • In Deployment Framework release 6.2 and later, the command stops all the specified currently running items first, before restarting them.
    In releases 6.1 and earlier, it stops a running item and immediately restarts it, before moving on to stop and start the next item. 

To clean the system and then start or restart it, use the convenience command ./dfw cleanstart.

When you've changed the configuration of a production system, we recommend that you run the ./dfw dump command immediately, before restarting the system. The most up-to-date configuration data will then be readily available if Caplin Support need it to help fix a problem with your running system. If you don't run dump before restarting, you'll have to stop the running system to get the configuration needed to diagnose a fault, or copy the configuration manually from the various directories where it's located.

status

./dfw status

Reports the status of the core components (Transformer and/or Liberator) and Adapter blades, showing the process id of each process running under the Framework.

stop

./dfw stop [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

Stops the core components (Transformer and/or Liberator) and Adapter blades.

  • If you don't give the command any parameters, it stops all the running components and Adapter blades.
  • If you specify one or more items (Liberator and/or Transformer and/or one or more Adapter blades) it just stops those.
  • If you supply only the parameter called servers, the command stops just the deployed core components (Liberator or Transfomer or both).

support

./dfw support [directory]

Since: Deployment Framework 7.0

Warning: this command shuts down all running components.

Collates diagnostic information for Caplin Support. The information is saved to the directory global_config/support directory, or to the directory parameter, if specified.

The following Deployment Framework information is collated:

  • Log files
  • Configuration dump
  • Output of the versions command
  • Output of the info command

If the zip command is found in the shell's PATH, the collated files will be automatically archived in a ZIP file.

validate

./dfw validate

Checks that the currently active blades are consistent with the list of active blades maintained by the Framework. This command also reports on any blades that have been copied directly into the <Framework-root>/active_blades/ directory instead of being activated using the command ./dfw activate.

versions

./dfw versions

Displays the versions of every deployed kit (including the Deployment Framework itself), and also which blades are active and inactive.

If multiple versions of the same kit have been deployed only the version of the most recent deployment is reported.

Note that the kit name for a blade includes the blade name but is not not necessarily identical to it. For example, the Caplin Permissioning Service blade is called PermissioningService but the associated kit is called CPB_PermissioningService-<version>.zip.

veryclean

./dfw veryclean [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> ...] [servers]

Since: Deployment Framework release 6.2

Warning: this command stops the specified components.

Removes all log files that have been produced by the deployed components and active Adapter blades. When you explicitly or implicitly include Liberator in the command parameters, the command also removes the database files containing information about the Liberator users’ licence usage. When you explicitly or implicitly include Transformer in the command parameters, the command also cleans up Transformer's memory file.

  • If you don't give the command any parameters, it stops all the deployed components and active adapter blades and cleans them.
  • If you specify one or more items (Liberator and/or Transformer and/or one or more Adapter blades) the command just stops and cleans those.
  • If you supply only the parameter called servers, the command just stops and the deployed core components (Liberator or Transformer or both) and cleans them.

If you don't want the licence database files to be removed, or Transformer's memory file to be cleaned up, use the command ./dfw clean instead.