# 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.

## 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.

 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 and press the Tab key once, nothing happens. This indicates that you haven’t yet entered enough characters for tab-completion to identify which command you want. Press the Tab again to display a list of possible commands:

$./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 s and press the Tab key once, nothing happens. This indicates that more than one command begins with 's', and you need to enter more character for tab-completion to identify which command you want. Press the Tab again to display a list of commands that begin with the 's' character:

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

When you type ./dfw sta and press the Tab key once, this time only one command (start) command matches the partially-completed command and the command is completed:

$./dfw start When you type ./dfw start and press the Tab key once, nothing happens. This indicates that you haven’t yet entered enough characters for tab-completion to identify which blade you wish to start. Press the Tab key again to display a list of runnable blades. The list includes the virtual-blade 'servers', which 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 Li and press the Tab key once, the blade name is partially completed to 'Liberator'. This indicates that more blades than 'LiberatorDemoDataSource' begin with 'Liberator'. Press the Tab key again to display a list of blades that begin with 'Liberator':$ ./dfw start Liberator
Liberator                 LiberatorDemoDataSource
$./dfw start Liberator When you type ./dfw start LiberatorDemo and press the Tab key once, 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:

 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:

• clean-unused

• cmc

• copy-ssl-demo-files

• deploy [-f] [<kitname1> <kitname2> …​]

• hosts

• hosts all <primary host> [<secondary host>]

• info

• java <JVM-location>

• java32 <JVM32-location>

• killAll

• mon

• redeploy [-f] [<kitname1> <kitname2> …​]

• rollback [<kitname1> <kitname2> …​]

• status

• support [directory]

• validate

• versions

### activate

 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 (see Setting up dfw command completion).

### clean

 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

 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

### clean-unused

.dfw clean-unused

Since: 7.0.2, 7.1.0

Removes log files from unused kits under the kits directory in the Deployment Framework. An 'unused kit' is any component kit that is not referenced by a kits/<component>/Latest symbolic link.

When a kit is upgraded the user may choose not to delete the old unpacked kit(s). This command provides a way of removing any log files in the directories of those old unpacked kit(s).

This command assumes that components store log files in the default locations (kits/Liberator/<kit>/var, kits/Transformer/<kit>/var, and kits/<adapter>/<kit>/DataSource/var). Log files created in any other location are not removed.

This command does not stop any running components.

### 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 running the CMC on a remote server, either over a Microsoft Remote Desktop connection or using a forwarded X11 display over SSH, there are additional requirements. For more information, see Running the CMC remotely.

### copy-ssl-demo-files

./dfw copy-ssl-demo-files

Since: Deployment Framework 7.0.2

Copies the following demonstration SSL credential files to the Deployment Framework’s global_config/ssl directory, overwriting existing files with the same names:

• Self-signed certificate: rttpd_https.pem

• Encrypted private key: rttpd_https.key

The demonstration credentials are intended for use in development and testing only. Do not use them in production.

 Do not use the demonstration SSL credentials in production.

In versions of the Deployment Framework prior to version 7.0.2, the Deployment Framework automatically copies the demonstration SSL credentials on deployment of Liberator if no SSL credentials are found in the global_config/ssl directory. From version 7.0.2, you must run the ./dfw copy-ssl-demo-files command to copy the demonstration credentials.

### deactivate

 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

 This command stops all running components

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 are moved to global_config/inactive_overrides. This is in contrast to the erase command which deletes the blade’s configuration overrides.

### deploy

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

 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

 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.

### erase

 This command stops all running components

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 are deleted. This is in contrast to the delete command which moves configuration overrides to the global_config/inactive_overrides directory.

### hosts

./dfw hosts

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

where:

• <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 ./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 ./dfw hosts command to make all other host configuration changes.

 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-library-path>

Sets the absolute path to a JVM library used to run the embedded JVMs of Liberator, Transformer, and other C DataSources.

The <JVM-library-path> 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.

Windows example
./dfw java "C:/Program Files (x86)/Java/jre7/bin/client/jvm.dll"
Linux example
./dfw java "/usr/lib/jvm/java-8-oracle/jre/lib/amd64/server/libjvm.so"

If the path name in <JVM-library-path> contains spaces, enclose the path name 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.

### 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

Since: Deployment Framework release 6.2

Takes a copy of component log files for use in log file analysis.

By default, the copied log files are written to the directory <Framework-root>/global_config/logs/. The content of this directory is erased before log files are copied. To change the default directory, set the environment variable DFW_LOGS_DIR to your preferred directory.

• 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.

### 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.

 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

 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

 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

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

• 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

 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

Since: Deployment Framework release 6.2

 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.