Preface

This document describes the functionality provided by the Command Plugin.

Refer to the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

As a system administrator, the need occasionally arises to execute adhoc scripts or OS commands on remote systems. The process usually entails having to manually login to each system, copy any required resources to said system and finally executing scripts/commands to process the resources or configure the remote system. The process is acceptable for a single system, but tends not to scale when performing the tasks on entire server farms. The manual intensive process becomes tedious and error prone. The Command Plugin helps with these tedious processes and significantly reduces the chances of errors.

A system administrator could also use the Command Plugin to reuse existing deployment scripts with Deployit, before choosing to move the deployment logic to a more reusable, easily maintainable plugin form.

Features

Plugin Concepts

Command

A Command encapsulates an OS specific command, as one would enter at the command prompt of a native OS command shell. The OS command is captured in the Command's commandLine property; e.g. 'echo hello >> /tmp/hello.txt'. The Command also has the capability of uploading any dependent files to the target system and make those available to the commandLine with the use of a placeholder; e.g. 'cat ${uploadedHello.txt} >> /tmp/hello.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 usually runs when the associated Command is undeployed or upgraded.

Command Order

The order in which the Command is run in relation to other commands. The order allows for the chaining of commands to create a logical sequence of events. For example, an install tomcat command would execute before an install web application command, while a start tomcat command would be the last in the sequence.

Requirements

This plugin requires:

Usage in Deployment Packages

Please refer to Packaging Manual for more details about the DAR packaging format.

Sample DAR MANIFEST.MF entries defining a package that can (un)provision a tomcat server using an install and uninstall script

Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: CommandPluginSample
CI-Version: 1.0

Name: install-tc-command
CI-type: cmd.Command
CI-order: 50
CI-commandLine: /bin/sh ${install-tc.sh} ${tomcat.zip}
CI-undoCommand: uninstall-tc-command
CI-dependencies-EntryValue-1: install-tc.sh
CI-dependencies-EntryValue-2: tomcat.zip
CI-name: install-tc-command

Name: uninstall-tc-command
CI-type: cmd.Command
CI-order: 45
CI-commandLine: /bin/sh ${uninstall-tc.sh}
CI-dependencies-EntryValue-1: uninstall-tc.sh
CI-name: uninstall-tc-command

Name: tomcat-6.0.32.zip
CI-name: tomcat.zip
CI-type: file.File

Name: install-tc.sh
CI-type: file.File
CI-name: install-tc.sh

Name: uninstall-tc.sh
CI-type: file.File
CI-name: uninstall-tc.sh

Using the deployables and deployeds

Deployable vs. Container Table

The following table describes which deployable / container combinations are possible. Note that the CIs can only be targeted to containers derived from Host.

Deployables Containers Generated Deployed
cmd.Command overthere.Host cmd.DeployedCommand

Deployed Actions Table

The following table describes the effect a deployed has on its container.

DeployedCreate Destroy Modify
cmd.DeployedCommand
  • Upload command resources to host
  • Resolve command line placeholder references with absolute paths to the uploaded resource files on host
  • Execute command line on host
  • Run the undo command associated with the deployed command, if exists. Actions are same as described for Create
  • Run the undo command associated with the deployed command, if exists. Actions are same as described for Create
  • Run the modified command. Actions are same as described for Create

Sample Usage Senario - Provision a Tomcat server

For illustration purposes, we take a simplistic view of installing Tomcat. In reality however, your installation of Tomcat would take on a far more comprehensive form.

Tomcat is distributed as a zip. For this example, we create an installation script to unzip the distribution on the host. The uninstall script simply shuts down a running Tomcat and deletes the installation directory.

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

Create the uninstall script (uninstall-tc.sh)

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

MANIFEST snippet defining the command to trigger the execution of the install script for the initial deployment

The following command will be executed at order 50 in the generated step list. '/bin/sh' is used on the host to execute the install script which takes a single parameter, the absolute path to the tomcat.zip on the host. When the command is undeployed, uninstall-tc-command will be executed.

Name: install-tc-command
CI-type: cmd.Command
CI-order: 50
CI-commandLine: /bin/sh ${install-tc.sh} ${tomcat.zip}
CI-undoCommand: uninstall-tc-command
CI-dependencies-EntryValue-1: install-tc.sh
CI-dependencies-EntryValue-2: tomcat.zip
CI-name: install-tc-command

MANIFEST snippet defining the undo command to trigger the execution of the uninstall script for the undeploy

The undo command will be executed at order 45 in the generated step list. Note that it has a lower order than the install-tc-command. This ensures that the undo command will always run before the install-tc-command during an upgrade.

Name: uninstall-tc-command
CI-type: cmd.Command
CI-order: 45
CI-commandLine: /bin/sh ${uninstall-tc.sh}
CI-dependencies-EntryValue-1: uninstall-tc.sh
CI-name: uninstall-tc-command

See the Usage in Deployment Packages section for the complete MANIFEST.MF

CI Reference

Configuration Item Overview

Deployable Configuration Items

CIDescription
cmd.CommandCommand specification that is executed on a host

Deployed Configuration Items

CIDescription
cmd.DeployedCommandCommand deployed to a Host

Topology Configuration Items

CIDescription
overthere.CifsHostA machine that can be connected to using either WinRM or Telnet and can perform file manipulation via the CIFS protocol
overthere.LocalHostThe machine on which the Deployit Server is running on
overthere.SshHostA machine that can be connected to using ssh
overthere.SshJumpstationA machine that can be used to create a tunneled connection to the destination host

Virtual Topology Configuration Items

CIDescription
overthere.HostA machine that runs middleware, on which scripts can be executed, etc
overthere.HostContainer
overthere.JumpstationBase class for jumpstations

Configuration Item Details

cmd.Command

Hierarchyudm.BaseDeployable >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.Deployable, udm.ConfigurationItem

Command specification that is executed on a host

Public Properties
order  : INTEGER = 50

Order of the command
commandLine : STRING

Command line to execute on host. Dependent artifacts can be referred to using ${artifact name}.
dependencies : SET_OF_CI<file.File>

Artifacts that the command depends on
runUndoCommandOnUpgrade : BOOLEAN = true

Indicates whether the undoCommand should be run on an upgrade
tags : SET_OF_STRING

The tags to map deployables to containers.
undoCommand : CI<cmd.Command>

Command to execute when undeploying command

cmd.DeployedCommand

Hierarchyudm.BaseDeployed >> udm.BaseConfigurationItem
Interfacesudm.Deployed, udm.ConfigurationItem

Command deployed to a Host

Public Properties
container  : CI<udm.Container>

The container on which this deployed runs.
order  : INTEGER = 50

Order of the command
commandLine : STRING

Command line to execute on host. Dependent artifacts can be referred to using ${artifact name}.
dependencies : SET_OF_CI<file.File>

Artifacts that the command depends on
deployable : CI<udm.Deployable>

The deployable that this deployed is derived from.
rerunCommand : BOOLEAN

Forces the command to be rerun.
runUndoCommandOnUpgrade : BOOLEAN

Indicates whether the undoCommand should be run on an upgrade
undoCommand : CI<cmd.Command>

Command to execute when undeploying command

overthere.CifsHost

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

A machine that can be connected to using either WinRM or Telnet and can perform file manipulation via the CIFS protocol.

Public Properties
address  : STRING

Address of the host
connectionType  : ENUM [TELNET, WINRM_HTTP, WINRM_HTTPS] = TELNET

Connection Type
os  : ENUM [WINDOWS, UNIX]

Operating system
password  : STRING

Password to use for authentication
username  : STRING

Username to connect with
cifsPort : INTEGER = 445

Port on which the CIFS server runs
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
port : INTEGER

Port on which the Telnet or WinRM server runs
tags : SET_OF_STRING

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
protocol  : STRING = cifs

Protocol
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
winrmContext  : STRING = /wsman

Winrm Context
winrmEnvelopSize  : INTEGER = 153600

Winrm Envelop Size
winrmLocale  : STRING = en-US

Winrm Locale
winrmTimeout  : STRING = PT60.000S

Winrm Timeout
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.Host

Hierarchyudm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

A machine that runs middleware, on which scripts can be executed, etc.

Public Properties
os  : ENUM [WINDOWS, UNIX]

Operating system
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
tags : SET_OF_STRING

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
protocol  : STRING

Protocol to use when connecting to this host
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.HostContainer

null

overthere.Jumpstation

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Base class for jumpstations

Public Properties
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
tags : SET_OF_STRING

The tags to map deployables to containers.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
os  : ENUM [WINDOWS, UNIX] = UNIX

Os
protocol  : STRING

Protocol to use when connecting to this host
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
temporaryDirectoryPath : STRING

Temporary Directory Path
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.LocalHost

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

The machine on which the Deployit Server is running on.

Public Properties
os  : ENUM [WINDOWS, UNIX]

Operating system
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
tags : SET_OF_STRING

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
protocol  : STRING = local

Protocol
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.SshHost

Hierarchyoverthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

A machine that can be connected to using ssh.

Public Properties
address  : STRING

Address of the host
connectionType  : ENUM [SFTP, SFTP_CYGWIN, SFTP_WINSSHD, SCP, SUDO, INTERACTIVE_SUDO, TUNNEL] = SFTP

Type of SSH connection to create
os  : ENUM [WINDOWS, UNIX]

Operating system
port  : INTEGER = 22

Port on which the SSH server runs
username  : STRING

Username to connect with
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
passphrase : STRING

Optional passphrase for the private key in the private key file
password : STRING

Password to use for authentication
privateKeyFile : STRING

Private key file to use for authentication
sudoUsername : STRING

Username to sudo to when accessing files or executing commands
tags : SET_OF_STRING

The tags to map deployables to containers.
temporaryDirectoryPath : STRING

Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
interactiveKeyboardAuthRegex  : STRING = .*Password:[ ]?

Regular expression to look for in keyboard-interactive authentication before sending the password
protocol  : STRING = ssh

Protocol
sudoCommandPrefix  : STRING = sudo -u {0}

Sudo command to prefix to the original command. The placeholder {0} is replaced with the sudoUsername
sudoPasswordPromptRegex  : STRING = .*[Pp]assword.*:

Regular expression to look for in interactive sudo before sending the password
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
allocateDefaultPty : BOOLEAN = false

If true, a default pty is allocated when executing a command. All sudo implementations require it for interactive sudo, some even require it for normal sudo. Some SSH server implementations (notably the one on AIX 5.3) crash when it is allocated.
sudoOverrideUmask : BOOLEAN = false

If true, permissions are explicitly changed with chmod -R go+rX after uploading a file or directory with scp.
sudoQuoteCommand : BOOLEAN = false

If true, the original command is quoted when it is prefixed with sudoCommandPrefix
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection

overthere.SshJumpstation

Hierarchyoverthere.Jumpstation >> overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfacesudm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

A machine that can be used to create a tunneled connection to the destination host.

Public Properties
address  : STRING

Address of the host
port  : INTEGER = 22

Port on which the SSH server runs
username  : STRING

Username to connect with
jumpstation : CI<overthere.Jumpstation>

If this host is not directly reachable, specify a jumpstation here which can be used to reach this host.
passphrase : STRING

Optional passphrase for the private key in the private key file
password : STRING

Password to use for authentication
privateKeyFile : STRING

Private key file to use for authentication
tags : SET_OF_STRING

The tags to map deployables to containers.
Hidden Properties
connectionTimeoutMillis  : INTEGER = 1200000

Connection Timeout Millis
connectionType  : ENUM [SFTP, SFTP_CYGWIN, SFTP_WINSSHD, SCP, SUDO, INTERACTIVE_SUDO, TUNNEL] = TUNNEL

Connection Type
interactiveKeyboardAuthRegex  : STRING = .*Password:[ ]?

Regular expression to look for in keyboard-interactive authentication before sending the password
os  : ENUM [WINDOWS, UNIX] = UNIX

Os
protocol  : STRING = ssh

Protocol to use when connecting to this host
tmpFileCreationRetries  : INTEGER = 1000

Tmp File Creation Retries
temporaryDirectoryPath : STRING

Temporary Directory Path
tmpDeleteOnDisconnect : BOOLEAN = true

Whether to delete the temporary connection directory when the connection is closed
Control Tasks
checkConnection

Check connection