Command plugin

This topic describes how to use the Deploy Command plugin to execute scripts on remote systems without manually logging in to each system, copying required resources, and executing scripts or commands.

The Command plugin automates this process and makes it less error-prone. You can also use the Command plugin to reuse existing deployment scripts with Deploy before you move the deployment logic to a more reusable, easily maintainable plugin form.

Features

• Execute an operating system command on a host.
• Execute a script on a host.
• Associate undo commands.
• Copy associated command resources to a host.

Plugin concepts

Command

A command is an operating system-specific command, that you use in the command prompt of a native Operating System (OS) command shell. The OS command is captured in the command's commandLine property. Example: echo hello.

The command can also upload dependent artifacts to the target system and make them available to the commandLine with the use of a placeholder in the ${filename} format. Example: cat ${uploadedHello.txt}.

Undo command

An undo command has the same characteristics as a command, except that it reverses the effect of the original command it is associated with. An undo command runs when the associated command is undeployed or upgraded.

To define an undo command, use the following undo attributes:

• undoCommandLine: Use to define a command to be executed on the host machine. Example: ls -la.
• undoOrder: Specifies the order of execution of undo command.
• undoDependencies: Specifies the dependent artifacts that undo command requires.

note

If undoCommandLine and a reference undo command are both defined, undoCommandLine will take precedence.

note

It is also possible to define an undo command by referring to an existing command.

Command order

The command order is the order in which the command is run in relation to other commands. You can use the order to chain commands and create a logical sequence of events. Example: An "install Tomcat" command will execute before an "install web application" command, while a "start Tomcat" command will be the last in the sequence.

Limitations

• Only single-line commands are supported.

• Command lines are always split on spaces (' '), even if the target shell supports a syntax for treating strings containing a space as a single argument. Example: echo "Hello World" is interpreted as a command echo with two arguments, "Hello and World".

• Excess spaces in commands are converted to empty string arguments. Example: ifconfig    -a is executed as ifconfig "" -a.

• Characters in commands that are special characters of the target shell are escaped when executed. Example: The command ifconfig && echo Hello is executed as three commands ifconfig \&\& echo Hello on a Unix system.

• Placeholders in dependent artifacts will not be replaced. For more information, see Using placeholders in Deploy.

Blacklisting / whitelisting commands

You can specify the rules in the XL_DEPLOY_SERVER_HOME/centralConfiguration/command-whitelist.yaml file, to restrict the execution of commands through the command plugin. As the rules configuration is applied to every saved file you do not need to reboot the server instance. You can also turn the functionality on/off by setting the enabled property to true/false respectively.

If a feature is turned on, the validation rules are applied on creating a new configuration or updating an existing configuration. Once enabled and configured, the deployment will fail if it contains any restricted/non-whitelisted command.

Limitations

• Only allowed OR restricted commands (i.e. not both) can be specified throughout the whole file.
• Rules are set via regex strings and apply to the whole command line.
• Validation of the command happens at the time of execution and not while creating the step, i.e. user can create command but not be able to execute it.
• If more than one config is found for a given role, the first one is taken.
• If allowed-commands = [] and restricted-commands = [] are true, then everything is allowed.

Example:

• command lines starting with sudo restricted to all users
• command lines having pwd or echo commands restricted to users with role example-role-1
• command lines having ifconfig command restricted to users with role example-role-2

xl.command-whitelist:
  enabled: true
  all-users:
    allowed-commands: [ ]
    restricted-commands: ["^sudo.*$"]
  roles:
    - role-name:"example-role-1"
      allowed-commands: [ ]
      restricted-commands: ["^.*pwd.*$", "^.*echo.*$"]
    - role-name:"example-role-2"
      allowed-commands: [ ]
      restricted-commands: ["^.*ifconfig.*$"]

Usage in deployment packages

This is an example of a deployment package (DAR) manifest that defines a package that can provision and un-provision a Tomcat server using an install and uninstall script.

<cmd.Command name="install-tc-command">
    <order>50</order>
    <commandLine>/bin/sh ${install-tc.sh} ${tomcat.zip}</commandLine>
    <dependencies>
        <ci ref="install-tc.sh" />
        <ci ref="tomcat.zip" />
    </dependencies>
    <undoCommandLine>/bin/sh ${uninstall-tc.sh}</undoCommandLine>
    <undoOrder>45</undoOrder>
    <undoDependencies>
        <ci ref="uninstall-tc.sh" />
    </undoDependencies>
</cmd.Command>
<file.File name="tomcat.zip" location="tomcat.zip" targetPath="/tmp"/>
<file.File name="install-tc.sh" location="install-tc.sh" targetPath="/tmp" />
<file.File name="uninstall-tc.sh" location="uninstall-tc.sh" targetPath="/tmp" />

Sample scenario: Provision a Tomcat server

This is an example Apache Tomcat installation, which is distributed as a ZIP file. This example creates an installation script to unzip the distribution file on the host. The uninstall script shuts down a running Tomcat server and deletes the installation directory.

Step 1 - Create the installation script

Create a script that will install Tomcat. This is a sample installation script (install-tc.sh):

#!/bin/sh
set -e
if [ -e "/apache-tomcat-6.0.32" ]
then
  echo "/apache-tomcat-6.0.32 already exists. remove to continue."
  exit 1
fi
unzip $1 -d /
chmod +x /apache-tomcat-6.0.32/bin/*.sh

Step 2 - Create the uninstall script

Create a script that will uninstall Tomcat. This is a sample uninstall script (uninstall-tc.sh):

#!/bin/sh
set -e
/apache-tomcat-6.0.32/bin/shutdown.sh
rm -rf /apache-tomcat-6.0.32

Step 3 - Define the command to install

Define a command that will trigger the execution of the installation script for the initial deployment. In the following example from a deployit-manifest.xml file, the command will be executed at order 50 in the generated step list. On the host, /bin/sh is used to execute the installation script. It takes a single parameter: the path to the tomcat.zip file on the host. When the command is undeployed, uninstall-tc-command will be executed.

<cmd.Command name="install-tc-command">
    <order>50</order>
    <commandLine>/bin/sh ${install-tc.sh} ${tomcat.zip}</commandLine>
    <commandLine>uninstall-tc-command</commandLine>
    <undoOrder>45</undoOrder>
    <dependencies>
        <ci ref="install-tc.sh" />
        <ci ref="tomcat.zip" />
    </dependencies>
</cmd.Command>

Step 4 - Define the command to uninstall

Define a command that will trigger the execution of the uninstall script for the undeployment. In the following example from a deployit-manifest.xml file, the undo command will be executed at order 45 in the generated step list. This is at a lower order than the install-tc-command command. This ensures that the undo command will always run before install-tc-command during an upgrade.

<cmd.Command name="uninstall-tc-command">
    <order>45</order>
    <commandLine>/bin/sh ${uninstall-tc.sh}</commandLine>
    <dependencies>
        <ci ref="uninstall-tc.sh" />
    </dependencies>
</cmd.Command>
```