You are here

Airlock 4.2 Upgrade Guide

Affects product: 
Airlock WAF
Affects version(s): 

If you are planning to upgrade to Airlock 4.2, please follow this upgrade guide.

What's new in 4.2?

Here is an overview of all the Airlock 4.2 highlights.


During the installation process the disks are reformatted. All historical log data will be lost.

  • If possible, upgrade your test environment before you touch your productive systems.
  • Make sure your current Airlock 4.0 or 4.1 system is up to date and fully working. Older versions of Airlock (3.x) are not supported for a direct upgrade to 4.2.
  • Check if your existing hardware is sufficient for running Airlock 4.2. See below.
  • Prepare a list of all manual changes (changed files like Static.rsc, or other *.in files, etc.). Some of these settings might have to be re-applied after upgrading.
  • Backup your configuration file by downloading it from the Configuration Center ( including the SSL private keys).
  • Backup all add-on modules installed on Airlock (Authentication Service, SSL VPN Module, Application Portal etc.) using SSH/SCP.
  • Check the size of the reporting data in any case! See here for more instructions.
  • Order a new license for Airlock 4.2. See below.
  • Insert the Airlock 4.2 installation CD and reboot.
  • Follow the on-screen instructions.
  • Choose to keep your existing configuration by selecting the disk partition proposed.
  • After installing check in the Configuration Center if all settings are correctly converted.
  • Let your users or QA people test! The more detailed tests on the test environment were done the less is the risk to upgrade the productive environment.
  • If all tests were successful, you may now upgrade your productive system(s).
  • For upgrading a failover cluster, follow the steps described below.

Hardware Requirements

The Hardware requirements for Airlock version 4.2 are the same as for the earlier version Airlock 4.1. For more information see the articles Hardware Sizing and Hardware Compatibility.

Converting your old configuration

Your old configuration can be converted automatically in two ways:

  • by upgrading an existing installation and choosing to keep your old configuration
  • by importing your configuration backup on a fresh installation of Airlock 4.2

Since "keep config" saves also other files like the reporting data, the SSL private keys, Static.rsc etc. we recommend to choose keep the old configuration during the installation!

There are a few configuration items that require your attention after upgrading. Please check the following issues.

  • License
    You need to convert your old license files to use them Airlock 4.2. The system can't be activated with a 4.1 or 4.0 license. Remove the license to run Airlock 4.2 in restricted mode. Please use the license conversion form to request a updated license from ergon.
  • Encryption pass phrase
    If in previous Airlock versions 4.0 or 4.1 the passphrase for encryption never was set, then, right after the installation of Airlock 4.2, the administrator is forced to set the encryption passphrase. Otherwise it is not possible to activate the configuration. Make sure the encryption passphrase of two failover cluster nodes ist set identically.
  • Server Certificates
    In Airlock 4.2 the server certificates and private keys are globally stored. So a stored server certificate including the private key can reused for any virtual host by simply choose it from the dropdownlist at server certificate settings. All new added server certificates then will appear in this dropdownlist.
    During conversion, identical server certificates of different virtual host will be merged to one. If the imported configuration does not contain the SSL private keys, they must be manually pasted under certificate settings afterward.
    If on a virtual host the old test certificate ( was used, delete this entry under the certificate settings. Then choose the new test certificate of Airlock (test.certificate) in the corresponding virtual host(s).
  • Multiple Virtual Hosts per Mapping
    In the past, a mapping was tied to exactly one virtual host. Since 4.2 a mapping can be published on multiple virtual hosts. Automatic conversion does not make use of this features: You have to check manually if you have identical mappings for different virtual hosts that can now be combined to one mapping. This will simplify the future administration work and will also save some memory.
  • Filter rules
    Allow rules:
    In Airlock 4.2 the allow rule filters can be configured directly in the mappings. No global configuration necessary. But all filters and patterns can still be reused in other mappings. For the special case "parameter and path length checks" and "length check exception" see here.
    Deny rules:
    Deny rules are still defined globally. Parameter exception patterns can be defined/edited directly in the mapping for the corresponding rule. The patterns can also be reused in different mappings for different rules.
  • Parameter length checks
    Parameter and path length checks can no longer be configured for each allow rule, these restrictions are now valid per mapping.
    If more than one allow rule per mapping is activated, then, during the configuration conversion, the largest value of each field (e.g. Max parameters) over all allow rules of the corresponding mapping is set in the new 4.2 mapping/allow rule configuration. The parameter length check exception pattern is taken from the first allow rule on which an exception pattern is configured. Otherwise it is set to the default value.
  • Cookie prefixes
    Whether an application cookie is passed to the browser (either unchanged or encrypted) was formerly configured via the settings Passthrough cookie prefixes and Encrypted cookie prefixes. These parameters are now configured (1) as a regular expression and (2) per mapping. Your settings are automatically converted: Regular expressions equivalent to your prefixes are used for all existing mappings. Thus, your configuration will be backward-compatible, but you might want to check your settings to take advantage of this security improvement.

    Let's assume you had set the Passthrough cookie prefix to JSESSION,PHP because two of your applications need these cookies to be sent to the browser. After upgrading to 4.2, every mapping will have its Passthrough Cookie RegEx set to ^(JSESSION|PHP). This regular expression matches all cookies names starting with either JSESSION or PHP, so everything should work as before. However, we would recommend you to improve the security by restricting the cookie settings: In this case, you should set the Passthrough Cookie RegEx of the two affected mappings to ^JSESSION and ^PHP  and disable the Cookie Passthrough setting for all other mappings
  • Cookie names (AL_ENV_ und AL_CONTROL)
    The cookie names (cookie prefixes) for the environment cookies, AL_ENV_, and the control cookie name, AL_CONTROL, can no longer be configured under "Cookie settings". In Airlock 4.2 it is possible to change the names under "Expert Settings -> Security Gate -> 30-customer-settings.rsc file" by adding the following properties:
    SecurityGateway * EnvVarCookiePrefix "<prefix env. cookies>"
    SecurityGateway * ControlCookieName "<control cookie name>"
    During the configuration import the names from the previous 4.1 configuration will be added to the "Expert Settings -> Security Gate -> default settings file" automatically. Please check the names after import.
  • Back-end servers
    In Airlock 4.2 the back-end servers can be defined globally and can be reused for different mappings. During the import all identical back-end servers are merged. So just one back-end server with the same name will exist.
  • Back-end HTTP timeout
    The IdleChlidTimeout as known from the previous Airlock version 4.1 does no longer exists in this manner. In Airlock version 4.2, now there exists a new timeout,  the "Back-end HTTP timeout", which is used for back-end request. The "Back-end HTTP timeout" can be configured per mapping. The IdleChlidTimeout is still used on process level, but is no longer related to back-end requests.
    During the import, the value of the old IdleChlidTimeout from the Static.rsc is set in all mappings as value of the "Back-end HTTP timeout". As default the "Back-end HTTP timeout" is set to 120 seconds. After the import check the timeout values in all mappings and change it if necessary. 
  • Static.rsc
    If you had specific configurations in your Static.rsc and the configuration is imported after the installation, that changes have to be imported into the configuration center manually. Go to "Expert Settings -> Security Gate" - there you can edit the new file 30-customer-settings.rsc which replaces Static.rsc.
    If you made a "keep config" during the installation, as recommended by ergon, then the changes from Static.rsc will be imported automatically to 30-customer-settings.rsc.
    To migrate settings referring mappings, like for example Session Hijacking Prevention settings, please contact Airlock support.
  • RawSessionSlots
    The RawSlots parameter is no longer part of the Airlock license key. The maximum raw session limit respectively the session store size value (see below) is now calculated automatically based on the hardware. The calculated value can be found in the Configuration Center under "Expert Settings -> Security Gate -> link: default settings file". #
    # Session store size
    SecurityGateway * SessionStoreSize "<value in MB>"
    The value of maximum session slots can be found in the Log viewer by the following message:m:SY-SG-SESS-008 c:C Creating shared session cache for maximum <value> sessionsPlease check if this computed maximum session value is close to the RawSlots parameter of your old license. If you need to change the maximum session slot value it ist possible with the following setting. Just paste the following part in to the "Expert Settings -> Security Gate" 30-customer-settings.rsc textarea. # The number of created raw session slots will be logged at SG start time
    # see logs m:SY-SG-SESS
    # this value is calcuated according to the system memory - to override this
    # generated value with specific value add a line like this
    SecurityGateway * RawSessionSlotsOverride <new value>
  • Cluster Configuration
    On Airlock 4.1 it was possible to use the same hostname for both cluster nodes. With Airlock 4.2 this is no longer possible. Make sure that both cluster Nodes have configured different hostnames. 

Cluster Upgrade

The following procedure describes how to upgrade an Airlock HA cluster setup from 4.1 to 4.2

A full installation from cdrom is required to upgrade each system. This will take appx. 2 hours to complete.


Before upgrading the Airlock HA cluster system, following prerequisites are required (also see Checklist above):

  • Backup all Airlock cluster configuration files (airlock-conf_<cluster>.zip
  • Backup all add-on modules manually installed on tomcat (authentication service, SOAP/XML filter and their settings)
  • Save any manual modifications, e.g. in the file Static.rsc, or other *.in files, etc.

Upgrade steps

Note: The "Offline" state is not persistent. After a system reboot the state will switch to "Online".

Upgrading system A (passive System):

  • Take system A offline to upgrade by clicking the offline button, "Set this Airlock offline", in the Configuration Center under "Server settings".
  • System B should remain in active mode and all applications should still be accessible as normal.
  • Install Airlock 4.2 from CDROM on system A.
  • Do not change the host name, i.e. set the same host name the system had before the upgrade (Attention: see above "Cluster configuration").
  • Choose to keep (convert) the previous configuration.
  • After installing, check (see above "Converting your old configuration") and activate the configuration.
  • If needed, deploy the authentication service and apply all manual settings e.g. the settings from the file Static.rsc (see also above "Static.rsc").
  • After the activation the system A should remain in passive mode. 

Switch from System B (4.1) to System A (4.2):

  • Take system B still using 4.1 offline by using the button "Set this Airlock offline" in the Configuration Center under "Server settings".
  • System A with 4.2 should switch to active mode.
  • Requests should now be handled by system A.

Upgrading system B:

  • Install Airlock 4.2 from CDROM on system B, keeping the configuration during the installation.
  • After installing, check and activate the configuration.
  • If needed, deploy the authentication service and apply all manual settings e.g. the settings from the file Static.rsc.
  • After the activation the system B should remain in passive mode.
Knowledge Base Categories: