Icon

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

Skip to end of metadata
Go to start of metadata

Contents

Operating System

Icon

Unless specified differently, all (shell) commands within this operations manual are examples for an installation on SuSE Linux. Installing automaIT on other operating systems or in a different way may require other commands.

Standalone vs. multiple instancing

In some cases the installation of multiple automaIT server instances on one machine may be required to, for example, separate test and production environments or to separately manage hosts of several principals.

The following documentation describes an automaIT server installation prepared for multiple instancing. If just a single automaIT server should be installed, the specially marked sections for the second instance can be ignored.

automaIT is not cluster-safe!

Icon

Please note that multiple instancing for load balancing using the same database with different automaIT instances is not supported.

Requirements

Please read the System Requirements first. They provide a hint about supported software versions in the following server installation also including the requirements for automaIT agent and command line interface (CLI).

 Software requirements for automaIT server

Operating system

automaIT server should run on every Unix operating system fulfilling the software prerequisites.

Recommended operating systems are:

  • SuSE Linux Enterprise Server (Version 11 SP2)
  • Solaris (Version 11)

Java

Supported are all Oracle compatible Java Runtime Environment (JRE) implementations in 64-bit starting at version 7.

Version

Status

Java 5 64-bit(error) not supported

Java 6 64-bit

(error) not supported

Java 7 64-bit

(tick) supported
Java 8 64-bit(tick) supported

Apache Tomcat

Apache Tomcat is used as application server providing the user interface. Binary distributions for Apache Tomcat Core can be obtained from tomcat.apache.org. Verified versions are:

Version

Status

Apache Tomcat 6

(tick) supported (≥ 6.0.18 recommended)

Apache Tomcat 7

(tick) supported

PostgreSQL

The underlying database for automaIT is PostgreSQL. It is available in most Linux distributions through the packet management and can alternatively be downloaded from www.postgresql.org.

Version

Status
PostgreSQL 8(tick) supported (≥ 8.3 recommended)
PostgreSQL 9(tick) supported

automaIT server

The server is the central component of automaIT. It manages agents, plug-ins and logs and provides the user interface. All models for provisioning software are executed on the server and the resulting commands send to the agent.

Server-sizing

The following table displays the absolutely minimum hardware requirements for automaIT server and a recommended size for a good startup with little resources. Keep in mind that the really needed hardware resources vary greatly in size, depending on the environment to manage.

Property

Minimum

Recommended

CPU800 MHz4.0 GHz
RAM1 GB2 GB

File systems

It is strongly recommended to separate at least operating system and automaIT data into different devices. The volume size needed for the automaIT data depends on the number of jobs running each day (which increases the database size) and component resources to provision (which increases the space needed for the file repository). It is entirely possible to provision resources with a size of a few gigabytes.

Regarding the limits for filename length, file size and volume size all typical Linux file systems are supported except FAT and ReiserFS (version 3.5 and lower).

It's recommended to create at least two separated volumes, once again the file system sizing is just a recommendation (the minimum required disk space for automaIT is 250 MB):

SizeUsed forMountpoint
10 GBOperating system, swap, .../
80 GBautomaIT data

/opt/automait/

Multiple Instancing

Installing multiple instances it's recommended to do so each on a dedicated file system. Therefore the recommendation leads to the following example:

SizeUsed forMountpoint
10 GBOperating system, swap, .../
80 GBautomaIT data instance 1

/opt/automait/serverA/

80 GBautomaIT data instance 2/opt/automait/serverB/
.........

automaIT user

It's recommended to create a dedicated user for the automaIT server which will run the web server. To do so create a system user called automait and a dedicated system group automait as well.

Installation directory

If it doesn't exist yet create the installation directory /opt/automait and make user automait its owner.

Multiple Instancing

Each automaIT instance must have its own file repository. It's recommended to also separate the automaIT databases into dedicated directories. For example create a directory structure as the following where /opt/automait/serverA and /opt/automait/serverB link to different file systems as described above:

/
└─ opt/
   └─ automait/
      ├─ serverA/ -> /mnt/2nd-fs
      │  ├─ db/
      │  └─ filerepo/
      └─ serverB/ -> /mnt/3rd-fs
         ├─ db/
         └─ filerepo/

PostgreSQL

The database for automaIT will be provided by PostgreSQL which can be installed via the packet manager of the operating system or alternatively downloaded from www.postgresql.org/download/.

SuSEUbuntu
Multiple Instancing

There are two recommended ways to configure PostgreSQL:

  1. One instance with databases separated by tablespaces into different directories.
    • one port
    • one directory per database
    • shared transaction log
    • collective backup (all instances need to be stopped)
  2. Several instances, one for each database.
    • several ports
    • one directory per instance (including transaction log)
    • individual backup

Several instances recommended

Icon

It's recommended to use option two to separate e.g. test from production environments.This makes handling of backups, restores and other downtimes more easier. Option one can be used to separate automaIT instances within a test environment with minimal overhead.

 

Instance configuration

The database server will be configured to store all its data inside a separate folder under /opt/automait called db. Again, it would be advisable to outsource /opt/automait/db  to a separate file system.

For some succeeding operations a locale is needed. Following command will provide all valid locale strings.

One can pick any ID from the output. Following commands regarding the database will be attributed with en_GB.utf8 in this example.

The command initdb creates a new database instance and asks for a superuser password. All subsequent database commands will ask for that password.

Multiple Instancing

For multiple instancing use the following commands instead:

The database instance(s) will be created with default settings. The port and the listen address need to be updated. Locate the file postgresql.conf inside the database directory and adjust these two settings:

/opt/automait/db/postgresql.conf

Naturally, each instance needs its own port. The value * for listen_addresses means that requests on any network interface will be served.

Multiple Instancing

The second PostgreSQL instance has to use another listening port. Set it to another than 5432 in the postgresql.conf of the second instance.

/opt/automait/serverB/db/postgresql.conf

Recommended listening port for second PostgreSQL instance

Icon

Using port 5436 for the second instance is recommended cause ports 5433 to 5435 are used by other applications by default.

Now that a new database was created it should be added to the startup scripts. In this case the standard startup script will be modified to point to the new location.

Therefore in file /etc/sysconfig/postgresql the following line

/etc/sysconfig/postgresql

needs to be replaced by

/etc/sysconfig/postgresql
Multiple Instancing

Using multiple instances of PostgreSQL copy the startup script and the configuration file.

Replace the reference for the configuration file in the copied startup script and rename the provided service (see second line in init info block) from postgresql to postgresql2.

/etc/init.d/postgresql2

Change the parameter POSTGRES_DATADIR in /etc/sysconfig/postgresql to /opt/automait/serverA/db resp. in /etc/sysconfig/postgresql2 to /opt/automait/serverB/db.

/etc/sysconfig/postgresql2

Now the new configuration of the startup scripts needs to be reloaded in order to start the new instance(s) of PostgreSQL.

Make sure that PostgreSQL will be started automatically at every system reboot:

SuSEUbuntu

This will install the init script for service postgresql (named through info field Provides in the script) in its default runlevels (here 3 and 5).

Multiple Instancing

The second PostgreSQL instance has to be started as well.

User and database

automaIT needs a user that has access to the database. For security reasons this user should only be used to access the automaIT database with least possible permissions. The password for the user needs to match the user password pair from JDBC configuration.

It is important to create the database with UTF-8 as encoding.

Multiple Instancing

For the second PostgreSQL instance change the --port parameter to the listening port defined in /opt/automait/serverB/postgresql.conf before.

 To test the setup simply log in to the command line interface of PostgreSQL. Exiting the command-line is done with \q.

Missing configuration in PostgreSQL 8.x

Icon

automaIT database migration algorithms make use of the PL/pgSQL language module which is not configured by default in PostgreSQL 8.x but 9.x and above. To configure this module do:


 

Apache Tomcat

Apache Tomcat is used as application server providing the user interface. Binary distributions for Apache Tomcat Core 7 can be obtained from http://tomcat.apache.org/download-70.cgi. Please read the System Requirements for verified Tomcat versions. After successfully downloading the package it needs to be extracted to the automaIT folder and set up for the user automait as the owner of the directory.

It is recommended to create a link /usr/local/tomcat to the extracted directory (/opt/automait/apache-tomcat-7.0.35  in this case). This makes it easier to change Tomcat version in the future. The following steps will refer to this link as $CATALINA_HOME.

$CATALINA_HOME vs. $CATALINA_BASE

Icon

In a single instance Tomcat installation, normally the environment variables $CATALINA_HOME and $CATALINA_BASE both point to the Tomcat installation directory where the bin directory is located in. Setting up multiple instances of Tomcat is the case, where $CATALINA_HOME still points to the installation directory containing the binaries and $CATALINA_BASE points to the directory containing all instance specific directories like conflogswebappswork etc.

Multiple Instancing

Using multiple instances the Tomcat directories conf, logs, temp, webapps and work have to be moved or copied into /opt/automait/serverA/ and /opt/automait/serverB/. Don't copy but create empty directories called lib in both instances and copy all files from np-release-<version>.zip/server-lib into both lib directories. Both instance directories /opt/automait/serverA/ and /opt/automait/serverB/ are referenced as $CATALINA_BASE in the following.

Using a single instance copy all files from np-release-<VERSION>.zip/server-lib into the directory $CATALINA_HOME/lib.

Violating library in Tomcat 6.x

Icon

Tomcat 6.x contains an older version of the el-api in it's classpath which usually is loaded first. Thus it's necessary to manually delete the file el-api.jar from $CATALINA_HOME/lib. Tomcat 7.x and later already fixed this issue.

Correct user permissions

Icon

Check your $CATALINA_HOME directory and if used instance directories ($CATALINA_BASE) if the following permissions referring to the user automait are set correctly for the directories and the files, they contain:

DirectoriesPermission
bin
executable
conf webapps libreadable
logs work tempwriteable

JVM Parameter

To work properly automaIT server needs at least 512 MB of RAM. Depending on the number of concurrent users the value may be set much higher. For production usage it's recommended to reserve 1.5 GB of RAM for automaIT server. The following file needs to be placed at $CATALINA_HOME/bin/setenv.sh.

$CATALINA_HOME/bin/setenv.sh

The file needs to be executable as well.

 Windows

Using a Windows installer which registers Tomcat as a Windows Service set the JVM properties with the GUI tool tomcat7w.exe which is placed in the Tomcat's bin directory. Parameters set through this tool will be stored in the Windows Registry key HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Apache Software Foundation\Procrun 2.0\Tomcat7\Parameters\Java.

SSL connection configuration

Icon

The following line in $CATALINA_BASE/conf/server.xml should be removed or commented out as it could prevent the server from initialising under certain circumstances (especially with Tomcat 6.0.33):

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />

To secure the connection between the user and the web interface, SSL needs to be enabled. The configuration file $CATALINA_BASE/conf/server.xml already contains a section for SSL secured connections ("Define a SSL HTTP/1.1 Connector on port 8443"). Usually this section is not activated (commented out). The following snippet activates SSL with a custom keystore for the SSL certificate on port 8443. The keystore will be named https.server.keystore and stored in the directory $CATALINA_BASE/certs in the next step.

$CATALINA_BASE/conf/server.xml

The code snippet above is an example for a keystore containing only one private key which is not password encrypted. To use a key store containing several private keys add the parameter keyAlias to the Connector configuration defining the alias of the key to use. To secure the private key itself (which should be not mixed up with the key store password) the parameter keyPass is needed. Unfortunately this configuration parameter only works correctly in Tomcat 7.0.12 and above.

It is heavily advised to change the password for the keystore. To do so the value of the attribute keystorePass needs to be adjusted. The standard keystore resides under $HOME/.keystore which is the default save path for keytool. The attribute keystoreFile is used to point the server to an alternate keystore as defined in the following code snippet.

Generating the keystore, keytool will prompt for two passwords. First one is to secure the key store (=keystorePass) and should be always set. The second password secures the private key itself (=keyPass) and should be left empty, especially when using a Tomcat version less than 7.0.12.

Self signed certificate

Icon

Using the code above will create a 5 years valid self signed certificate. Most web browsers will display a warning message when accessing websites via HTTPS with such a certificate. This message can be confirmed by saving the certificate as a trusted one. Alternatively have a look at SSL certificates on how to create a CA signed certificate.

If no Apache Webserver with mod_jk is used in front of the Tomcat server the AJP-Connector on port 8009 can be removed resp. commented out. For further details regarding configuration please refer to the documentation of Apache Tomcat.

Multiple Instancing

Using multiple instances set the variable CATALINA_BASE to the instance directories, create one keystore in each instance and set the correct references for keystoreFile in each $CATALINA_BASE/conf/server.xml.

Also make sure to use different Ports for the second Tomcat instance in the /opt/automait/serverB/conf/server.xml:

/opt/automait/serverB/conf/server.xml

Enabling gzip compression

When working with huge data sets it is advisable to use gzip compression to minimize the transferred data (between web client and server).

Connector attributes for compression

The attribute compressionMinSize specifies the amount of data before compression is used and can can be adjusted. The following is an example of an SSL and gzip enabled connector.

$CATALINA_BASE/conf/server.xml

JNDI configuration

To grant automaIT access to the database the corresponding settings need to be published via JNDI entries in Apache Tomcat. Following lines need to be inserted into $CATALINA_BASE/conf/context.xml between the context tags:

$CATALINA_BASE/conf/context.xml

The attributes username and password have to match the values defined in section database configuration before. The attribute maxWait defines how long (in milliseconds) the pool waits to obtain a connection if all are taken before reporting an error. -1 will wait an infinite time.

BasicDataSourceFactory

Icon

On some systems the pre-packaged Apache Tomcat uses different DataSourceFactory implementations. If you experience problems during startup, please specify the correct version with

factory="org.apache.commons.dbcp.BasicDataSourceFactory"

in the DataSource definition from above.

Windows

Set the parameter file.repository.root as a default windows path reference like D:\automait\filerepo. Trying to mask the backslashes may lead to unexpected errors during file imports.

Multiple Instancing

Using multiple instances set the parameters file.repository.root to ${CATALINA_BASE}/filerepo.

Also make sure to set the correct database port and the modified HTTP/HTTPS ports for the second instance!

Last but not least the attributes sessionCookieName="JSESSIONID-A" resp. sessionCookieName="JSESSIONID-B" should be added to the leading <Context> tag of the context.xml files:

/opt/automait/serverB/conf/context.xml

As last step the folder file.repository.root needs to be created. It is advisable to outsource this folder to a separate file system.

Multiple Instancing

Using multiple instances the commands for creating the file repository differ from the snippet above.

Deploy automaIT

To deploy automaIT to the application server the file np-server.war has to be copied from np-release-<VERSION>.zip to $CATALINA_BASE/webapps/automait.warApache Tomcat will extract the war file upon first startup and install the contained application.

Tomcat as system service

To easily start or stop the Tomcat instance create an init script like the following:

/etc/init.d/automait  Expand source
Multiple Instancing

Using multiple instances use these scripts instead. They include different definitions for $CATALINA_BASE and also for the provided and required services.

/etc/init.d/automait  Expand source
/etc/init.d/automait2  Expand source

Install it resp. them in the runlevels to automatically startup on system reboot.

SuSEUbuntu

Testing installation

Congratulations, the installation procedure has been completed!

Start the database if not done yet and the the Tomcat instance.

Prove running of the instances using netstat and ps. There should be results similar to the following for PostgreSQL:

And results like this for Tomcat:

Open a web browser and surf to https://your.server.name:8443/automait to check if your automaIT instance is online.

The default login for automaIT is user admin with password admin. After logging in successfully the password has to be changed to something different.

Having problems installing automaIT?

Icon

If your automaIT instance does not come up correctly you will find the log messages in $CATALINA_BASE/logs/catalina.out. If the problem can not be solved, please contact our Support.

  • No labels