Install Autoform DM (Silent Installation)

Introduction

Both the standalone and clustered versions of the installer can be automated using a properties file.

A properties file named installation-record.properties is created automatically after a successful installation of a standalone Autoform DM Server or any Autoform DM Cluster node and is populated with relevant values chosen during the installation process. You can then use the installation-record.properties file as a seed file for automatically installing identical servers / nodes.

It is also possible to generate a blank installation-record.properties (template) file which you can then populate yourself without having to perform a manual installation first.

Note

installation-record.properties files vary between installation types – Standalone and Cluster: PDC (Primary Domain Controller), SDC (Secondary Domain Controller), LB (Load Balancer), and Nodes – and may also vary between versions where new installation options are introduced / deprecated. Whilst many options are the same across all versions, we recommend using or generating the correct install installation-record.properties template file for the version of Autoform DM you are using.

For security reasons, an installation-record.properties file does not contain any credentials. Therefore, you will need to add the cluster shared secret as a minimum. Depending on your installation type, it may be necessary to add the management console password, database password and service account password before using it to run an automated install.

You can use the installerProperties.bat script (described below) to encode your secret key and correctly insert it into your installation properties file.

Prerequisites

Silent install support is built into both the standalone and clustered installers; therefore, the prerequisites are as follows:

• A JRE with a minimum version of 1.8 must be available on the target system in order to run the installer.

• An empty database along with an account which has permission to CREATE, DROP, and ALTER tables.

• Check your system and software is listed as compatible, as per the Autoform DM Compatibility Matrix.

• A valid Autoform DM license (if not available, Evaluation mode can be used for up to 30 days, before a valid license is required).

Note

If you use the 32-bit JRE, the installation folder will be Program Files (x86). If you use the 64-bit JRE, the installation folder will be Program Files. The examples on this page are for 64-bit JRE.

installation-record.properties

After a successful install of a server or node, the installation-record.properties file is in the root of the installation folder:

• Standalone: C:\Program Files\Formpipe Software\Autoform DM\Server_x.x\

• Cluster: C:\Program Files\Formpipe Software\Autoform DM\Server_x.x-[**your-cluster-role-server**]\

The installation-record.properties file can be viewed using any text / XML editor (for example, Notepad ++). An example extract from a PDC properties file is shown at the end of this document.

installerProperties.bat

The installerProperties.bat batch script can be used to generate blank installation properties files (templates) for any installation type. It can also update or validate existing properties files, or populate them with a correctly encoded (base64) cluster shared secret key.

To run installerProperties.bat, open an elevated command prompt and navigate to the <tools> folder in the root of your Autoform DM installation directory:

• Standalone: C:\Program Files\Formpipe Software\Autoform DM\Server_9\tools

• Cluster Installation: C:\Program Files\Formpipe Software\Autoform DM\Server_9 - Cluster_<cluster name>-<role>-<node name>\tools

Running the batch script with no modifiers will give you a list of options:

C:\Program Files\Formpipe Software\Autoform DM\Server_9\tools\installerProperties.bat

Usage: [-d, --debug]

 generate-empty [standalone | pdc | sdc | lb | dm]  : Generate an empty installation properties file

 update                                             : Update a previously generated properties file

 validate [path/to/file]                            : Validate a properties file highlighting any errors

 populate-cluster-secret [path/to/file]             : Generate and insert encoded cluster secret into properties file

Validating .properties Files Is Recommended

It is always recommended to run a validate on a properties file before use, as this will confirm that all required properties have been set.

For example:

[ERROR]> Property [DB_PASSWORD] has no value but is required, ensure a value is set before using for an installation

For upgrades: Using the updated tools version will also verify that the properties file is compatible with the target Autoform DM version. A separate distribution of the properties-tool.jar file can be obtained for this purpose, which can be run with java -jar properties-tool.jar

Generate Template

To generate a blank template file (installation-template.properties), for any of the Autoform DM install types run:

installerProperties.bat generate-empty <installation type>

<installation type> can be standalone, pdc, sdc, lb or dm.

For example, to generate a Load Balancer properties template file which you can then populate yourself, run:

installerProperties.bat generate-empty lb

Update an installation-record.properties File

Over time you may make updates to your standalone or clustered server installations and adjust your node.properties file in order to achieve this. Examples of this may be updating an expired / temporary certificate, changing a database or management console password or port number. To ensure that your silent installation-record.properties file accurately reflects all of the changes made to your installation (by you or others), you can automatically update your installation-record.properties file so that it contains all of the latest changes.

Warning

If you are updating the properties file and the file already exists, it will be overwritten.

To do this, simply run the installerProperties.bat script with the update command:

installerProperties.bat update

This will generate a new properties file named installation-record-updated.properties in the root installation folder, which can then be used to install and deploy Autoform DM using the most recent installation settings.

Credentials / Cluster Shared Secret

For security reasons, no credentials are stored in the automatically generated properties file following a successful install. Therefore you must manually re-add the appropriate credentials where required.

Whilst almost all credentials can be entered in plain text, an additional version of the cluster shared secret must also be added, prefixed with the name of the cluster and then base64 encoded. e.g. base64[<password>_<clustername>].

To make this process easier, the installerProperties.bat file will automatically format and add the encoded shared secret key for you.

Add the cluster name and plain-text shared secret in their respective fields. Save your properties file, then run:

installerProperties.bat populate-cluster-secret <path/to/file>

For example:

installerProperties.bat populate-cluster-secret c:/Temp/my-pdc-template.properties

This will then generate the base64 version for the installer to use. Opening the properties file after completing the above step will show your populated base64 encoded secret, e.g.:

USR_CLUSTER_NAME=LIVE

USR_SHARED_SECRET=thisisatest

CLUSTER_SHARED_SECRET_BASE64=dGhpc2lzYXRlc3RfTElWRQ==

Validate an installation-record.properties File

If you have populated a blank properties file, or tweaked an existing properties file, you may wish to check to see if it is valid before attempting a silent install with it. Please note that this will not check if the values entered are correct for your particular installation (i.e. credentials, paths, ports), only that the required fields are filled and the syntax is valid.

To check your properties file run:

installerProperties.bat validate pathto\file

For example:

installerProperties.bat validate c:\tmp\installation-record.properties

If no errors are found, the command will execute cleanly with no feedback. If any errors are found, they will be listed on-screen as shown in the example below:

[ERROR]> Property [CLUSTER_SHARED_SECRET_BASE64] has no value but is required, ensure a value is set before using for an installation

[ERROR]> Property [USR_SHARED_SECRET] has no value but is required, ensure a value is set before using for an installation

[ERROR]> Property [USR_HTTP_MGMT_PASSWORD] has no value but is required, ensure a value is set before using for an installation

[ERROR]> Property [DB_PASSWORD] has no value but is required, ensure a value is set before using for an installation

Run a Silent Install

We recommend using the JAR version of the installer to automate the install, as it provides some console output, but it is also possible to run the normal (.exe) installer silently as well.

Using an elevated command prompt, navigate to the directory holding the Autoform DM installer(s) and run:

<installer_exe> -auto -defaults-file <your_properties_file>

For example:

Autoform-DM_Installer-vX.x.exe -auto -defaults-file install_my_pdc.properties

Alternatively, to run the java installer with a defaults file, use the following command:

java -jar <installer_jar_file> -auto -defaults-file <defaults_file>

For example:

java -jar AUTOFORM-DM_Installer-vx.x.x.jar -auto -defaults-file install_pdc.properties

This will need to be done once per node, using the appropriate installation type properties file for each (PDC, SDC, LB, DM).

Example - PDC Properties File

The extract below shows some of the entries in an example properties file. For more information and insight into properties files we recommend that you manually run through a test install, which will show you all of your installation options, as well as providing you with a populated properties file at the end, which you can review and tweak as necessary. Please note that the information below may change with different software versions and is used for purely illustrative purposes.

Warning

Backslashes “\” must be escaped with an additional backslash, hence the use of double backslashes “\\” where you would normally expect only one.

Installs a PDC node for a cluster of name 'LIVE', which uses the http management port '9990', 
native management port '9999' and the shared secret 'MySecret'

Cluster Common

The name of the cluster; e.g. 'TEST' or 'LIVE', each node in the cluster must specify the same value here
USR_CLUSTER_NAME=LIVE

The shared secret used to authenticate remote nodes in the cluster. Each node in the cluster must specify the same value here
USR_SHARED_SECRET=MySecret

The base64 encoded shared secret combined with the cluster name: <shared-secret>_<cluster-name>, in this case 'MySecret_LIVE'
CLUSTER_SHARED_SECRET_BASE64=TXlTZWNyZXRfTElWRQ==

Windows Service

#The windows domain prefixed username to be applied to the windows service, if not specified the service will just use 'Local System'
SERVICE_USERNAME=DOMAIN\\user

#The windows user password to be applied to the windows service
SERVICE_PASSWORD=password

#The startup logic for the windows service; either 'auto' or 'manual'
SERVICE_STARTUP=auto