The Deployment Framework command: dfw

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:

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:

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:

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.

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

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 activate <bladename1> <bladename2> …​

Activates a blade or 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).

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

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

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.

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

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

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

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

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

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

The demonstration credentials are intended for use in development and testing only. Do not use them 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.

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

Deactivates a blade or 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

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

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.

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

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.

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

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 and 8.0.0, 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.

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

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.

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.

./dfw info

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

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

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

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

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

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

Since: Deployment Framework 6.2.1

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.

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

Since: Deployment Framework 6.2.1

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:

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:

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.

./dfw start {bladename|Liberator|Transformer|servers} …​

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

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.

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

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

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

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

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

Since: Deployment Framework 7.0

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:

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

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

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

Since: Deployment Framework release 6.2

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 want the licence database files to be removed, or Transformer’s memory file to be cleaned up, use the command ./dfw clean instead.