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

`./dfw start <Blade name>`

`./dfw -x start <Blade name>`
 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> …​`

 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]`

 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]`

 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`
 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> …​]`

 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> …​]`

 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’re deactivated but aren’t removed.

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

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

 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.

 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.

 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

`./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]`

• 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

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

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.