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>

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

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

  • clean-unused

  • cmc

  • copy-ssl-demo-files

  • deactivate [<bladename1> <bladename2> …​]

  • delete [<bladename1> <bladename2> …​]

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

  • dump [Liberator] [Transformer] [<AdapterBladename1> <AdapterBladename2> …​] servers]

  • erase [<bladename1> <bladename2> …​]

  • hosts [{<bladename>|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 {bladename|Liberator|Transformer|servers} …​

  • start-fg {bladename|Liberator|Transformer|servers} …​

  • start-fg-nologs {bladename|Liberator|Transformer|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.

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

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

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

  • Password file: rttpd_https.pwd

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

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

Deactivates a blade or blades.

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

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

./dfw dump [Liberator] [Transformer] [<AdapterBladename> …​] [servers]

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

Stops the specified components (by default all components) and dumps their configuration to files under the global_config/dump/ directory. From Deployment Framework 7.1.3, dump also records the current values of shell environment variables to the file global_config/dump/env.txt.

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.

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 a different location, define an environment variable called DFW_DUMP_DIR that specifies the location’s path.

erase

./dfw erase [<bladename1> <bladename2> …​]

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

hosts

./dfw hosts

Regenerate hosts.conf and output a configuration summary to the console.

Run this command if you have edited hosts-defn.conf to remove a misspelled component.

./dfw hosts {blade_name|all} primary_host [secondary_host]

Update the primary host (and optionally secondary host) for a named blade or all deployed blades, and regenerate hosts.conf.

Where:

  • blade_name is the name of an adapter blade. The symbolic blade name all resolves to currently deployed blades only. If you deploy a new blade after setting hosts for all, you will still need to configure the primary and secondary host for the new 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.

Example: set the Liberator blade’s primary and secondary hosts
$ ./dfw hosts Liberator lib1.example.com lib2.example.com
Example: for all currently deployed blades, set the primary server to localhost
$ ./dfw hosts all localhost

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

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

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.

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

Examples:

Red Hat Enterprise Linux (OpenJDK 8)
./dfw java "/etc/alternatives/java_sdk_1.8.0/jre/lib/amd64/server/libjvm.so"
Windows
./dfw java "C:/Program Files/Java/jre1.8.0_131/bin/server/jvm.dll"
macOS
./dfw java "/Library/Java/JavaVirtualMachines/adoptopenjdk-11.0.2.jdk/Contents/Home/lib/server/libjvm.dylib"

java32

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

Platform: Linux

Since: Deployment Framework 6.2

Sets up the location and name of the 32 bit JVM (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

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

./dfw start {bladename|Liberator|Transformer|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 Transformer 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.

start-fg

./dfw start-fg {bladename|Liberator|Transformer}

Since: Deployment Framework 7.1.2

Compatibility: DataSource for C (DSDK) 7.1.12+, DataSource for Java 7.1.16+, Liberator 7.1.15+, Transformer 7.1.10+

Start one component in the foreground. Log to STDOUT, prefixing each log line with the name of the log.

start-fg-nologs

./dfw start-fg-nologs {bladename|Liberator|Transformer}

Since: Deployment Framework 7.1.2

Compatibility: DataSource for C (DSDK) 7.1.12+, DataSource for Java 7.1.16+, Liberator 7.1.15+, Transformer 7.1.10+

Start one component in the foreground. No logs are written to STDOUT or to log files.

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

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.

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

The following Deployment Framework information is collated:

  • Log files

  • Output of the versions command

  • Output of the info command

  • Output of the dump command

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.