Unattended Mode

Published on Oct 13 2009

As you may know, installers generated with InstallBuilder provide different execution modes using the command line option “–mode”. The mode “unattended” is particularly useful when we need to incorporate installations into an automated process. With this mode, the installer will not prompt the user for any information and will instead take the default settings configured for each of the parameters. That way, it is possible to incorporate the installer execution into scripts since no input is required from the user during the installation.

Note that you are not forced to use only the default values when running the installer in this mode. You can also define the values through command line switches which are generated for each parameter definition inside the InstallBuilder project. If we want to use specific values, we should run the installation as follows:

“$ installer_binary –mode unattended –param1 value1 –param2 value2 ….”

As the number of parameters grows, it may be best to define the options values inside a text file. This is possible using the command line switch “–optionfile <filename>”. This will instruct the installer to take the values from the specified file. Here is an example:

“$ installer_binary –mode unattended –optionfile optionfile”

Where optionfile should contain a list of pairs <key>=<value>. For instance:

param1=value1

param2=value2

….

Configuring Unattended Mode Parameters in an Installer

Let’s take a look at how you can configure the installer so it behaves as expected in unattended mode and provides the appropriate feedback to the user through “–help”.

In order to configure the default values for each parameter, you need to edit the field “default” which appears in the “Main” tab inside parameter window or adding the property “default” to its definition inside the XML file:

<stringParameter>
 <name>port</name>
 <default>8080</default>
</stringParameter>

As mentioned earlier, each parameter will have its own command line option. When the installer is run with the –help option, the whole list of available command line switches is displayed. Each parameter is shown with a message similar to:

--option_name  option_description
   default: option_default_value

The given information can be modified using the properties inside the “Command Line” tab in the parameter window or adding the properties “cliOptionName”, “cliOptionText” and “cliOptionShow” to its definition in the XML file:

• option_name will be set to the value in “Command Line Name” (cliOptionName) or to the property name if it is not defined.

• option_description will be set to the value in “Command Line Text” (cliOptionText) or to the property description if it is not defined.

• It is also possible to hide parameters from the –help menu by setting the option “Show in Command Line” (cliOptionShow) to false.

<stringParameter>
 <name>port</name>
 <default>8080</default>
 <description>...</description>
 <cliOptionName>webport</cliOptionName>
 <cliOptionText>Web server port</cliOptionText>
 <cliOptionShow>1</cliOptionShow>
</stringParameter>

Using this settings, help will show the following entry:

--webport   Web server port
    default: 8080

Additional Switches

As previously mentioned, each parameter will have its own command line option. However, there are additional command line switches that may be useful while performing installations in unattended mode.

You can enable and disable components from the command line using the following options:

–enable-components name1,name2,name3

–disable-components name1,name2,name3

where name1, name2,… are the names inside the <name> tag of each component. Component names are case sensitive.

You can also modify the user interface shown during the installation process adding the option “–unattendedmodeui” It can take the values:

“none” : no progress bar will be shown when performing an unattended installation (default).

“minimal” : this value will show a graphical progress bar during an unattended installation.

“minimalWithDialogs” : In this mode, pop-ups will also be displayed in addition to the progress bar of the minimal mode.

Behaviour Modifications in Unattended Mode

While using unattended mode, the installation process is altered. It is important to note that all of the actions inside action lists that require user interaction are not executed, including those inside:

<componentselectionvalidationactionlist>
<finalpageactionlist>
Any parameter's <validationactionlist>
Any parameter's <preshowpageactionlist>
Any parameter's <postshowpageactionlist>

Also, be sure to take into account that during “initializationActionList”, the parameters haven’t yet been initialized with the values provided through the command line switches. They will contain the default values.

You may need to modify your installer behavior according to the mode used. In order to do this, you can use the “${installer_ui}” variable, which contains the mode that has been used to run the installer (gui, text, unattended).

You can define specific actions for unattended mode or prevent any actions from running in that mode by adding one of the following rules inside the specific ruleList.

<compareText text=“${installer_ui}” logic=“does_not_equal” value=“unattended”/>

<compareText text=“${installer_ui}” logic=“equals” value=“unattended”/>

For example, you can de-select a component at initialization if the installer detects that it is in unattended mode as follows:

<initializationActionList>
<componentSelection deselect="componentname">
 <ruleList>
 <compareText text="${installer_ui}" logic="equals" value="unattended"/>
 </ruleList>
</componentSelection>
</initialiationActionList>

Unattended Uninstallation

Unattended mode is also present in the uninstaller and it behaves in a similar way. This functionality may be useful for performing an uninstallation operation in the background without requiring any user feedback during an upgrade. Assuming that the path to the uninstaller is known, we could add the following action before starting to copy the new files:

<runProgram>
 <program>${uninstaller_path}</program>
 <programArguments>--mode unattended</programArguments>
 <ruleList>
     <fileTest>
         <path>${uninstaller_path}</path>
         <condition>exists</condition>
     </fileTest>
 </ruleList>
</runProgram>

Of course, we may also need to backup the application data before running the uninstaller and recover it once the new version is in place.

Usage Examples

Unattended mode may be used to automate any process that requires performing several installations with different settings. A few examples are provided below.

Simple Installer Tests

After building an installer, we may want to check to make sure it will work correctly while being run with different configurations. Instead of doing this by hand each time you build a new version, you can write a script that will try to install the application and ensure that no errors are thrown during the process. This script may use different option files containing the specific settings to be tested.

For example, under Unix systems we may implement a shell script as follows:

#!/bin/sh
OPTIONFILES_PATH="option_files/"
for optionfile in `ls $OPTIONFILES_PATH | cat`
do
installer.bin --mode-unattended --optionfile $optionfile
if [ $? -eq 0 ]
then
 echo "Test $optionfile: OK"
else
 echo "Test $optionfile: FAILED"
fi
done

Each of the configurations that we want to test should be defined inside optionfile in option_files folder. We may want to run the script in different machines or operating systems to detect if any parameter combination causes the installer to fail. Additional checks may be also included once each installation finishes.

Simple Automated Script

Let’s imagine you have an application which could act as client or server. Each client installation has to be configured to connect to a specific server. If you want to perform a network installation with several client machines and one server you may proceed as follows:

• Define the necessary parameters inside the installer. For instance: nodetype, servernode, servernodeport.

<stringParameter name="nodetype"   default="client"/>
<stringParameter name="servernode"   default=""/>
<stringParameter name="servernodeport"   default=""/>
<stringParameter name="port"   default="8080"/>

• Write the different optionfile configurations needed:

server_options.ini:
nodetype=server
port=8003
client_options.ini:
nodetype=client
servernode=192.168.1.200
serverport=8003

• Write a simple script which performs the installations in unattended mode with the proper option files. In Unix systems we may do something like:

#!/bin/sh
CLIENT_OPTIONS=client_options.ini
SERVER_OPTIONS=server_options.ini

SERVER=192.168.1.200
CLIENTS="192.168.1.201 192.168.1.202 192.168.1.203 192.168.1.204"
INSTALLER=node-installer.bin

scp $INSTALLER $SERVER:/tmp
scp $SERVER_OPTIONS $SERVER:/tmp
ssh $SERVER chmod +x /tmp/$INSTALLER
ssh $SERVER /tmp/$INSTALLER --mode unattended --optionfile /tmp/$SERVER_OPTIONS

for c in $CLIENTS
do
 scp $INSTALLER $c:/tmp
 scp $CLIENT_OPTIONS $c:/tmp
 ssh $c chmod +x /tmp/$INSTALLER
 ssh $c /tmp/$INSTALLER --mode unattended --optionfile /tmp/$CLIENT_OPTIONS
done

• After running the script, all the machines will be configured with the appropriate configuration and without requiring any user interaction in the process.

We are assuming that the proper ssh keys have been configured in the network and the user running the script has access to all of them and required permissions.

As you can see, the script acts as a template network configuration that may be used on different environments.

Modular Installer

Let’s imagine that we have an application which contains several modules. We want to have the ability to install/uninstall them separately with a global installer / uninstaller. How could we achieve this ?

One possible approach is to use unattended mode. We could generate one installer for each module and then construct a primary installer which will package them as binary files. When the primary installation is performed, each of the additional installers would be run in unattended mode in the background. The primary installation process should ask for the necessary parameters and send them to the background installations through the command line switches. For example, we can use a parameter “prefix” to tell each module where it should be installed.

Each installation will generate its own uninstaller so they can be run separately. Once again, to achieve global uninstallation, we will need to run each uninstaller in unattended mode.

Taking all of this into account, we can define a component inside primary installer for each module as follows:

<component>
<name>module1</name>
<canBeEdited>1</canBeEdited>
<selected>1</selected>
<show>1</show>

<folderList>
 <folder>
   <name>module1_installer</name>
   <destination>${installdir}</destination>
   <platforms>all</platforms>
   <distributionFileList>
      <distributionFile origin="module1_installer.bin"/>
   </distributionFileList>
   <actionList>
     <runProgram>
       <program>${installdir}/module1_installer.bin</program>
       <programArguments>--mode unattended --prefix=${installdir}/module1</programArguments>
     </runProgram>
   </actionList>
   <deleteFile path="${installdir}/module1_installer.bin"/>
 </folder>
</folderList>

<postUninstallationActionList>
 <runProgram>
   <program>${installdir}/module1/uninstaller</program>
   <programArguments>--mode unattended</programArguments>
   <ruleList>
     <fileTest>
       <path>${installdir}/module1/uninstaller</path>
       <condition>exists</condition>
     </fileTest>
   </ruleList>
 </runProgram>
</postUninstallationActionList>

</component>

As we can see, the component packs the module installer. During installation, it is copied to the installation directory and executed with the specific parameters. Then, the binary is removed.

During uninstallation, we run the module uninstaller, checking to make sure that the binary is still there, as it might have already been uninstalled by the user.