Child pages
  • CLI Manual

This is the documentation of the release 2.2 of automaIT. The documentation of the latest stable release can be found at AUTOMAIT.

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

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:

$ ./cli.py [General arguments] [Command] [Subcommand] [Command specific arguments]

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.

$ ./cli.py --server-url http://localhost:8080/np-server --user admin plan import /path/Plan.xml --major-version
Password:
job: 496
$

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:

$ ./cli.py --help
usage: cli.py [-h] [--config-file FILE] [--config-section SECTION]
              [--server-url URL] [--proxy-host HOST] [--proxy-port PORT]
              [--user USER | --session-id ID] [--format-xml]
              [--suppress-version-check]
              {shell,login,plan,component,component-varset,job,host,host-type,plugin,shell-completion}
              ...

positional arguments:
  {shell,login,plan,component,component-varset,job,host,host-type,plugin,shell-completion}
    shell               starts an interpreter shell, either interactively or
                        file based
    login               logs in and retrieves a session id
    plan                plan related actions
    component           component related actions
    component-varset    component variable set related actions
    job                 job related actions
    host                host related actions
    host-type           host-type related actions
    plugin              plug-in related actions
    shell-completion    generates shell completion for commands, subcommands,
                        arguments, hosts, plans, and components

optional arguments:
  -h, --help            show this help message and exit
  --config-file FILE    configuration file to be used for server URL and/or
                        credentials (default: /root/.automait/clirc)
  --config-section SECTION
                        configuration section within file (default: DEFAULT)
  --server-url URL      base URL of the server instance to connect to
                        (default: None)
  --proxy-host HOST     host of the proxy instance to connect to (default:
                        None)
  --proxy-port PORT     port of the proxy instance to connect to (default:
                        None)
  --user USER
  --session-id ID
  --format-xml          outputs the result as xml instead of human readable
                        text (default: False)
  --suppress-version-check
                        suppresses the version check which compares the
                        expected version of the server with that of the
                        script. (default: False)

Copyright(C) 2013 NovaTec Solutions GmbH
$

Help formatting

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

$ ./cli.py plan --help
usage: cli.py plan [-h]
                   {import,details,source,delete,delete-latest,list-components,execute}
                   ...
positional arguments:
  {import,details,source,delete,delete-latest,list-components,execute}
    import              imports a new plan or plan version and returns the job
                        ID
    details             shows the details of a plan
    source              shows the source of a plan
    delete              deletes a plan with all corresponding versions and
                        returns the job ID
    delete-latest       deletes the latest plan version and returns the job ID
    list-components     lists the components which are installable by the plan
    execute             executes the (latest) plan and returns the job ID
optional arguments:
  -h, --help            show this help message and exit
$

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

$ ./cli.py plan import --help
usage: cli.py plan import [-h] [--major-version] infile
positional arguments:
  infile           XML input file containing the plan to be imported
optional arguments:
  -h, --help       show this help message and exit
  --major-version  create major version
$

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:

$ ./cli.py --server-url http://localhost:8080/np-server --user admin plan import /path/Plan.xml
Password:
job: 558
$
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
[DEFAULT]
user = test
password = test
server-url = http://localhost:8080/np

[int]
server-url = http://automait-test:8080/np-server

Security risk

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:

$ ./cli.py --server-url http://localhost:8080/np-server --user admin login
Password:
44691cd9-0ed0-4c3e-bcd8-35dd0dc08964
$ ./cli.py --server-url http://localhost:8080/np-server --session-id 44691cd9-0ed0-4c3e-bcd8-35dd0dc08964 plan import /path/Plan.xml
job: 538
$

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.py --server-url http://localhost:8080/np --user admin --format-xml job steps --id 7119 --host-name localhost
Password:
<jobSteps><step id="7124" sequence="1" nestingDepth="0" started="26.06.2012 12:35:55" finished="26.06.2012 12:35:56" duration="00:00:00" rawExpression="lock and connect (localhost)" substitutedExpression="lock and connect (localhost)" status="COMPLETED" errorMessage=""/><step id="7125" sequence="2" nestingDepth="1" started="26.06.2012 12:35:55" finished="26.06.2012 12:35:56" duration="00:00:00" rawExpression="execNative ( sleep :[duration] )" substitutedExpression="execNative ( sleep 10 )" status="COMPLETED" errorMessage=""/></jobSteps>
$

CLI versions

CLI versions can be printed using the version command.

$ ./cli.py version
SCRIPT_VERSION=2.2.0-002
COMPATIBLE_VERSION=2.2.0-001
COMPLETION_VERSION=2.0.0-001

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.

Communication error: URL: https://localhost:8443/np-server/cli/generic/version Error: <urlopen error [Errno 1] _ssl.c:517: error:14077438:SSL routines:SSL23_GET_SERVER_HELLO:tlsv1 alert internal error>

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:

    <Connector port="8443" SSLEnabled="true"
    	...
    	ciphers="SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA" />

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

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.

$ ./cli.py --config-section automait-test host initialize [TAB][TAB]
--help            --host-set        --ids             ^[[?1034h--names 

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

export TERM=dumb


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

$ ./cli.py shell-completion register 

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

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.

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.

$ ./cli.py --fo[TAB] plan list

(error) Shell completion does not respond:

$ ./cli.py --fo[TAB]plan list

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

    # enable completion for automaIT cli.py
    if [ -f ~/.automait/cli.py ]; then
         . ~/.automait/cli.py
    fi

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:

$ ./cli.py --server-url http://localhost:8080/np-server --user admin shell

Subsequently, Python commands may be invoked:

>>> cli.cmd.plan_import(open("/path/Plan.xml"))
job: 549

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:

>>> jobid = cli.cmd.plan_import(open("/path/Plan.xml"))
>>> print jobid.id
555

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

>>> cli.cmd.[TAB][TAB]

The scripted Python shell

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

$ ./cli.py --server-url http://localhost:8080/np --user admin shell < commands.py
>>> job: 7135
>>> job: 7139
>>> job: 7143
$

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

cli.cmd.plan_import(open("/path/PlanA.xml"))
cli.cmd.plan_import(open("/path/PlanB.xml"))
cli.cmd.plan_import(open("/path/PlanC.xml"))

The scripted Python CLI module

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

import sys
from cli import Session
from cli import CommunicationError
from cli import UserError


def _main(argv):
    try:
        # open session to specified server with given credentials (user:test, password: test)
        s = Session('https://localhost:8443/np', ['test', 'test'], None, True)

        # get details for a component: first argument is the component path, second one is the component name
        result = s.component_details_by_key(argv[0], argv[1])
        # print formatted result
        print result
        # print result as raw xml format
        print result.content
    except CommunicationError as comm_err:
        print 'Communication error: %s' % comm_err.message
    except UserError as user_err:
        print 'User error: %s' % user_err.message

if __name__ == '__main__':
    _main(sys.argv[1:])
  • No labels