Docker image for Verify Access Web Reverse Proxy

The Security Verify Access Web Reverse Proxy (WRP) Docker image provides the Web Reverse Proxy capabilities of Security Verify Access.

It is a light-weight and secure alternative to running the same capabilities using the main Security Verify Access Image.

The main differences between running the Security Verify Access WRP image and the main Security Verify Access image as the WebSEAL persona include:

  • The WRP image is more light weight, which means that it consumes less disk space and memory, runs fewer processes and is quicker to start.
  • The WRP service listens on port 9443, by default, when using the Security Verify Access WRP image, whereas it listens on port 443 when using the Security Verify Access image.
  • The WRP image does not require any elevated container security capabilities/privileges (for example: the SETUID capability is not required).
  • Logging records are sent to the console in JSON format so that the container logging infrastructure can manage the logging records. No support is provided for natively forwarding logging messages to a remote syslog server.
  • The 'reload' capability is not supported which means that the container must be restarted in order to pick up configuration changes. In a Kubernetes environment the 'rolling update' capability of Kubernetes should be used to ensure that there is zero downtime when applying a configuration update.
Note: The definition for the Security Verify Access image and the Security Verify Access WRP image are interchangeable. In order to migrate to the Security Verify Access WRP image the image name will need to be changed, along with the port information. The HTTP_PORT and/or HTTPS_PORT environment variables can be set to indicate the ports on which the container will listen but note that if the supplied port number is less than 1024 the NET_BIND_SERVICE capability is required for the container. The rest of the definitions can remain the same. It is however recommended that the Security Verify Access WRP image is used as it is a more secure and light-weight alternative, and the ability to execute the WRP capabilities from the Security Verify Access image will be deprecated in a future release. Please take note that the logging in the new container will by default be in JSON format, and the SETUID privilege is no longer required.
Consider the following points when you deploy a WRP container:
  • The WRP container relies on a configuration snapshot which has been generated by the Security Verify Access configuration container.
  • The WRP container should be started as the 'isam' user (UID: 6000). In a standard container environment this will happen automatically but in a Kubernetes environment the security context should be set to allow the container to start as this particular user.
  • The following environment variables are used by the container:
    CONFIG_SERVICE_URL

    The URL that will be used to access the published configuration data. If using the configuration service of the Security Verify Access configuration container, the URL would be of the format: https://<container-ip>:<mapped-port>/shared_volume. A BA header will be supplied to handle authentication to the configuration service. If this environment variable is not specified the container will expect the configuration snapshot to be available in the shared configuration volume, at /var/shared/snapshots.

    CONFIG_SERVICE_USER_NAME
    The name of the user that will be used when accessing the configuration service.
    CONFIG_SERVICE_USER_PWD
    The password for the user that will be used when accessing the configuration service.
    HTTP_PORT
    The port on which the container will listen for HTTP request (default: 9080).
    Note: If the port number is less than 1024 the NET_BIND_SERVICE capability is required for the container.
    HTTPS_PORT
    The port on which the container will listen for HTTPS request (default: 9443).
    Note: If the port number is less than 1024 the NET_BIND_SERVICE capability is required for the container.
    SNAPSHOT
    The name of the configuration data snapshot file that is to be used when starting the container. No path information should be included in the filename. The standard snapshot locations will be searched for the specified snapshot file. This variable, if not specified, will default to the latest published configuration.
    SNAPSHOT_ID
    The identifier of the snapshot which will be used by the container. The full snapshot name is constructed as:
    ‘isva_<product_version>_<snapshot_id>.snapshot’
    If no identifier is specified, an identifier of 'published' will be used. This variable will be ignored if a full snapshot name is specified, using the SNAPSHOT environment variable.
    Note: This environment variable is not available prior to version 10.0.3.0.
    INSTANCE
    The name of the WRP instance to be started. If no INSTANCE is specified, the instance with the name of 'default' will be used.
    LOGGING_CONSOLE_FORMAT
    The required format for the log messages. Valid values are 'basic' or 'json' (default: json).
    LANG
    The language in which messages which are sent to the console will be displayed. If no language is specified the messages will appear in English. The following table lists the supported languages:
    Language Environment Variable Value
    Czech cs_CZ.utf8
    German de_DE.utf8
    Spanish es_ES.utf8
    French fr_FR.utf8
    Hungarian hu_HU.utf8
    Italian it_IT.utf8
    Japanese ja_JP.utf8
    Korean ko_KR.utf8
    Polish pl_PL.utf8
    Portuguese (Brazil) pt_BR.utf8
    Russian ru_RU.utf8
    Chinese (Simplified) zh_CN.utf8
    Chinese (Traditional) zh_TW.utf8
    FIXPACKS
    A space-separated ordered list of fix packs to be applied when starting the container. If this environment variable is not present, and the CONFIG_SERVICE_URL environment has not been set, any fix packs present in the fixpacks directory of the configuration volume will be applied in alphanumeric order.

Configuration

All configuration activities must be completed using the main Security Verify Access image, running as a configuration container. The configuration container supports a scaled-down version of the Security Verify Access appliance LMI. You can use this LMI to manage the configuration data.
Note: To make a configuration available to the WRP container, you must click Publish configuration in the LMI.

Service

The container, by default, will listen for incoming requests on port 9443, and optionally port 9080 (if HTTP access has been enabled in the configuration snapshot). Use the HTTPS_PORT and HTTP_PORT environment variables to change the ports on which the container will listen.

Shared configuration data

The shared configuration volume is a section of the file system that is reserved for the storage of persistent data.

The shared configuration volume is available in a Security Verify Access WRP container at '/var/shared'.

The shared configuration volume is used to store the following data:
Snapshots
Configuration snapshots are retrieved from the ‘snapshots’ sub-directory of the shared configuration volume if the CONFIG_SERVICE_URL environment variable is not specified.

The configuration data which is used by the Security Verify Access WRP image is fully compatible with the configuration data used by the legacy Security Verify Accessimage.

Fixpacks
Fix packs are retrieved from the 'fixpacks' sub-directory of the shared configuration volume if the CONFIG_SERVICE_URL environment variable is not specified.

When a WRP container is started, fix packs that are specified in the FIXPACKS environment variable will be applied in the order that they are specified. If the FIXPACKS environment variable is not present, and the CONFIG_SERVICE_URL environment variable has not been specified, any fix packs present in the 'fixpacks' directory of the configuration volume will be applied in alphanumeric order. If the CONFIG_SERVICE_URL environment variable has been specified the required 'fixpacks' must be specified using the FIXPACKS environment variable.

Logging

The logging of the WRP process will, by default, be sent to the console of the container, in JSON format. This allows the logging infrastructure of the container environment itself to manage the message logs.

The WRP configuration controls which auditing records are enabled, and where the auditing records are sent. It is recommended that all auditing records (including the WRP request log) are also written to the console of the container in JSON format. This can be achieved by:
  1. Changing the logging agent which is used for the auditing, controlled by the 'logcfg' configuration entry, to 'stdout'.
  2. Enabling JSON auditing, controlled by the 'audit-json' configuration entry.
  3. Modifying the request log destination so that it is set to 'stdout'.
  4. Modifying the request log format string so that the data is formatted as JSON.
For example:
[aznapi-configuration]
audit-json = yes
logcfg     = audit.azn:stdout

[logging]
requests-file      = stdout
request-log-format = {"host":"%h", "user":"%u", "time":"%t"}
Some additional log files will however still be generated on the disk of the container. By default, Docker uses a layered file system to help reduce the disk space utilization of the containers. However, this file system has slower write speeds than standard file systems. As such, a standard Docker practice is to place any files that are updated frequently (for example, log files) on a shared volume. All of the log files that are written by the container are located in the '/var/application.logs' directory. Therefore, the recommended approach is to create this directory as a shared volume when you create your container.
Note: Multiple containers should not reference the same persistent volume for log storage, otherwise multiple containers will attempt to write to the same log file at the same time, causing data write and integrity issues. In a Kubernetes environment this problem can be overcome by deploying the containers in a StatefulSet (refer to the official Kubernetes documentation for information on StatefulSets).
The log file directory structure is shown in the following table.
Table 1. Logs Directory Structure
Log file Sub-directory (relative to the root log directory)
WRP trace files wrp/<instance>/trace
WRP statistic files wrp/<instance>/stats
WRP crash files wrp/<instance>/crash