Skip to end of metadata
Go to start of metadata

automaIT provides a command line interface (CLI) to perform unattended non-interactive provisioning using shell or Python scripts. This enables automaIT to be integrated into 3rd party systems (e.g. monitoring) and allows further processing of information.

The standard CLI

The server provides a HTTP interface which may be called from any HTTP client. As a convenience, automaIT provides a CLI which takes care of the interaction with the user by parsing the arguments and invoking the HTTP interface of the server.

Installation

The CLI is shipped as a single Python Script. This requires a Python Environment as described in the CLI Installation guide.

Needed user privileges

Icon

For user authentication the role ROLE_AUTHORIZED_CLI_USER is required. If only read access is needed and to increase security, a dedicated user with that role may be created and used.

Call a command

The general syntax of the CLI is:

The cli.py script supports a set of commands which are divided into subcommands. General and command specific arguments must be provided depending on the command.

The following general arguments are supported:

ArgumentDescriptionRequired/Optional
--config-fileConfiguration file to be used for server URL and/or credentials, Default: ~/.automait/clircOptional
--config-sectionConfiguration section within file, Default: DEFAULTOptional
--server-urlThe URL of the automaIT serverRequired if not specified in the configuration file/section
--user <username>Authentication with user name and interactive passwordRequired if not specified in the configuration file/section and no session ID is given
--session-id <ID>Authentication using session IDRequired if no user is specified in the configuration file/section or given in the command line
--format-xmlFormat the output as XML instead of a human readable format.Optional
--helpShows the command and arguments depending on the context.Optional

The following example shows the import of a plan from the local file system using user credentials, i.e. user name and password.

In the example above, the main command is "plan"; the sub command is "import". Independently of the command the server and authentication must be given. After the subcommand one or more arguments may follow. In the example above, these are the path to a file representing a plan and the subcommand specific argument --major-version.

In this case the import of the plan created an asynchronous job. Its job ID was printed to stdout.

Show help

The CLI contains a context aware help. The Parameter --help may always be supplied to get a documentation of the supported commands and arguments.

To show all top level commands and arguments:

Help formatting

Icon

Optional arguments are enclosed in square brackets.

Alternative arguments are enclosed in round brackets whereas each alternative is separated by a vertical bar ("|").

To show the help of the top level command "plan":

To show the help of the command "plan import":

Authentication

User name and password

As shown in the example below, the CLI allows authentication at a given server URL using user name and interactive password:

Stored user name and password

To simplify the use of the CLI the server URL and/or credentials may be saved in a configuration file which defaults to ~/.automait/clirc (use global parameter --config-file to overwrite this). The file is build up of sections whereas the section named DEFAULT is used by default (use global parameter --config-section to overwrite this).

This is an example of a configuration file:

~/.automait/clirc

Security risk

Icon

Don't put sensitive passwords in the CLI configuration file because passwords are stored in plain text.

Session-ID based authentication

However, repeated authentication using user name and password is not optimal for performance because authorization is rather expensive. This can be optimized by requesting a session ID once and in subsequent calls using this session ID for authentication:

The session ID is valid for a configurable time (using server property cli.session.id.expiration.period which defaults to 5 minutes). Whenever a session is accessed either in the CLI or the web interface, the countdown for deactivation is reset and starts again.

Output format

The output of the CLI is by default in a human readable format which can be parsed easily in most cases. However, depending on the output it may be easier to have an unambiguous format like XML. All commands provided by the CLI therefore provide the argument --format-xml.

The following shows the XML result of a "job steps" call:

CLI versions

CLI versions can be printed using the version command.

There are three different versions printed:

  • SCRIPT_VERSION determines the version of the CLI script code. Every change in the code of cli.py leads to a new SCRIPT_VERSION.
  • COMPATIBLE_VERSION reflects the oldest automaIT server version which is compatible with the CLI. Every change in the REST interface of the server leads to a new COMPATIBLE_VERSION.
  • COMPLETION_VERSION is the oldest CLI version whose shell completion interface is backward compatible with the current version. Every change in the completion interface leads to a new COMPLETION_VERSION. This version can be ignored on Windows environments or when the shell completion is not used.

Once per session the CLI script verifies that it is compatible with the HTTP interface of the server (see COMPATIBLE_VERSION). This check can be suppressed using the argument --suppress-version-check. However, this may lead to unexpected behaviour and should be used with caution.

Incompatible SSL Cipher preferences

Using HTTPS as communication method in the server URL the following error message may appear in some environments.

The problem are differences in the preferred SSL cipher from OpenJDK JRE (256bit encoded) in contrast to Oracle JRE (128bit encoded) for example. This is a known bug tracked in NP-920.
The following workarounds are known to work:

  • Use HTTP instead of HTTPS as communication method.
  • Use similar JREs (at least same vendor) on server and client side.
  • Define specific ciphers in the server's Tomcat server.xml configuration within the HTTPS connector section:

Exit Codes

The CLI script provides different exit codes depending on the result:

Exit CodeDescription
0The CLI script terminated normally.
1The CLI script terminated abnormally due to a user error.
2Invalid arguments were passed to the CLI.
3The server responded with an unexpected error.
4The command could not be invoked due to a communication error.
5User could not be authenticated for the server
6User is not authorized to access the target resource

Shell Completion

The shell completion supports listing and completion of the available commands, sub commands, and special arguments, according to the known built-in completion functionality of the bash shell.

Additionally, the completion of host, host types, plans, component, and variable sets is supported. Since this requires server communication the authentication must be configured on the client.

Supported shells

Icon

Shell completion is currently supported by the bash shell on Unix systems and Cygwin on Windows.

Control characters like ^[[?1034h may appear in the list of available completions, e.g.

In this case it is necessary to change the environment variable TERM, e.g.


To use completion it is necessary to register the CLI script:

This creates the folder ~/.automait/ with the required bash completion script and appends lines in ~/.bashrc needed to load the previously created completion script the next time you start the bash shell. In case of updates to the cli.py it is not necessary to register the shell completion again.

Symbolic links

Icon

If cli.py is renamed manually or referenced by a symbolic link then this script must also be registered to enable shell completion. Multiple scripts (of different versions) may be registered simultaneously and will each return the correct shell completion.

Icon

When trying to use shell completion within the input-line, please make sure the cursor is followed by a space. Otherwise the shell completion will not respond.

(tick) Shell completion responds with --format-xml.

(error) Shell completion does not respond:

To use completion of host, host type, plan, component, and variable sets it is necessary to at least save the user and the password in the CLI configuration file ~/.automait/clirc. The Server url may be provided by the DEFAULT section in ~/.automait/clirc, another section with --config-section or by the general argument --server-url.

If it happens that there are no available completions for hosts, plans, or components, please check

  • if the correct login information is stored in ~/.automait/clirc
  • if the correct server is running and stored in ~/.automait/clirc
  • if lines like the following have been appended in ~/.bashrc

The interactive Python shell

The CLI may be started as an interactive shell. In this case authentication is only done once and all constructs provided by the programming language Python are available:

First, the interactive shell must be started:

Subsequently, Python commands may be invoked:

When using the standard CLI the output must be parsed. In some cases it is more elegant to use the internal Python interface provided by the CLI module. This allows using methods and classes provided by the module.

The commands return Python objects which can be used:

Icon

The integrated auto-completion may be called by pressing the tabulator key. The following example will list all available methods:

The scripted Python shell

Instead of passing the Python commands one by one the commands can also be read from a file:

In this case the file commands.py may contain a sequence of Python commands:

The scripted Python CLI module

The Python CLI script can also be used as imported module in user defined Python scripts:

  • No labels