Docker image for Security Access Manager

The Security Access Manager Docker image can run as a configuration container, a Web Reverse Proxy container, a runtime profile (aka Advanced Access Control/Federation) container, or a Distributed Session Cache (DSC) container. It contains the essential components to get Security Access Manager running on Docker.

Consider the following points when you start a container.
  • The docker container should be started as the 'isam' user (UID: 6000). In standard docker 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 Linux capabilities are required by the container (these capabilities are allowed by default in a standard Docker environment):
    • CHOWN
    • DAC_OVERRIDE
    • FOWNER
    • KILL
    • NET_BIND_SERVICE
    • SETFCAP
    • SETGID
    • SETUID
  • The following environment variables are used by the container:
    CONTAINER_TIMEZONE
    The timezone that will be used by the container (this is a standard Docker environment variable). For example: "Australia/Brisbane"
    INSTANCE
    The service instance that the container will provide.

    In a Web Reverse Proxy container, this environment variable is used to specify the name of the Web Reverse Proxy instance to start. This parameter is required when running in "webseal" mode.

    In a Distributed Session Cache container, this environment variable specifies the role of the container (i.e. primary/secondary/tertiary/quaternary) in the format of INSTANCE = '1|2|3|4'. For example, to specify that the container acts as the primary, use INSTANCE = '1'. To specify that the container acts as the secondary, use INSTANCE = '2'.

    SERVICE
    The service that the container will provide. If no service is specified, the container will default to "config". Valid values are: config, webseal, dsc, and runtime.
    SNAPSHOT
    The name of the configuration data snapshot that is to be used when starting the container. This will default to the latest published configuration.
    FIXPACKS
    A space-separated ordered list of fix packs to be applied when starting the container. If this environment variable is not present, any fix packs present in the fixpacks directory of the configuration volume will be applied in alphanumeric order.
    CONFIG_SERVICE_URL
    The URL that will be used to access the published configuration/fix-pack data. If using the configuration service of the Security Access Manager 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.
    Note: This environment variable is ignored by the configuration container.
    CONFIG_SERVICE_USER_NAME
    The user that will be used when accessing the configuration service.
    Note: This environment variable is ignored by the configuration container.
    CONFIG_SERVICE_USER_PWD
    The password for the user that will be used when accessing the configuration service.
    Note: This environment variable is ignored by the configuration container.
    ADMIN_PWD
    The password for the built in 'admin' user that will be used when accessing the configuration service. If this parameter is not specified, the default password 'admin' will be used.
    Note: This password cannot be changed at runtime and can only be set by this environment variable.
    AUTO_RELOAD_FREQUENCY
    The frequency, in seconds, that the container will check to see if the configuration has been updated. If an updated configuration is detected, the container will automatically reload the configuration data. Note that there will be a service interruption while the reload takes place. If this environment variable is missing, the container will not attempt any automatic reload of configuration data. This environment variable is ignored in the configuration container.

Consider the following points regarding user registry support when you use Security Access Manager in a Docker environment.

  • The embedded user registry can only be used to house the secAuthority=Default suffix in conjunction with basic users. If full Security Access Manager users are required, the secAuthority=Default suffix must be stored in an external user registry.
  • An external user registry is always required for the user suffix. Configure the external user registry as a federated user registry if the embedded user registry is being used for the secAuthority=Default suffix.

Configuration service

All configuration must be completed using the configuration container. The configuration service supports a scaled-down version of the LMI. You can use this LMI to manage the configuration data.

Note: To make a configuration available to a runtime container, you must click the Publish configuration button in the LMI.

The management service (i.e. the LMI) always listens on port 9443 of the container.

Runtime Management Web Services

The Runtime management Web services are light-weight web services hosted on the runtime container. These Web Services are used to manage the runtime of the container. They cannot be used to manage the configuration data, which should be done with the configuration Web services that is provided by the configuration container. The runtime management Web services listen on port 9443 of the runtime container.

Currently the runtime Web Services provides the ability to access the CLI and the application log files. For those APIs, the {appliance_hostname} parameter can be the configuration container address or the runtime container address. See the following Web Services documentation for the usage:

"Run CLI Command" Web Services
This Web Service acts as a front-end to the command line interface.
"Application Log Files" Web Services
The "Application Log Files" Web Services allows you to access the application log files.

Migrating an appliance to Docker

To migrate your appliance to the Docker environment, you can create a snapshot of the appliance in its original environment and import the snapshot into a running Security Access Manager configuration container.

You can only import a snapshot from an appliance if the following conditions are met:

  • For a Security Access Manager Base only activation, the snapshot was taken on version 9.0.0.0 or later. For an Advanced Access Control or Federation activation, the snapshot was taken on version 9.0.2.0 or later.
  • The appliance was configured with an embedded configuration database and an external runtime database.
  • The appliance runtime environment was using an external LDAP server. Alternatively, if the appliance was running Security Access Manager 9.0.4.0, an embedded LDAP server can be used if the "wga_rte.embedded.ldap.include.in.snapshot" advanced tuning parameter was set to true before generating the snapshot.

When a snapshot from an appliance is imported to a Docker container:

  • The LMI HTTPS listening port will be rewritten to 9443.
  • Any reverse proxy instances will have their HTTPS and HTTP ports rewritten to 443 and 80 respectively.

Restrictions

Security Access Manager, when run in a Docker environment, has the following restrictions:

  • Any configuration changes require the service containers to be reloaded. You can use the CLI to trigger a manual reload. Changes to the Federation configuration and the policy database will not result in any service down time. Changes to junction definitions and Web Reverse Proxy configuration will result in minimal service down time while the Web Reverse Proxy is restarted. See CLI in a Docker environment.
  • The authorization server (i.e. pdacld) is not supported.
  • The front-end load balancer capability of the Security Access Manager appliance is not supported.
  • The IP reputation policy information point (PIP) capability of Advanced Access Control is not supported.
  • Network HSM devices are not supported. All keys are stored locally.
  • A sample geo-location database is not provided. If a sample geo-location database is required, it should be obtained from the downloads area of a running virtual or hardware appliance. See Updating location attributes.
  • Pre-installed federation partner templates are not provided. See Managing federation partner templates. The connector package is available from the following public IBM download site: http://public.dhe.ibm.com/software/security/products/isam/downloads/
  • Web Reverse proxy flow data or PAM statistics are not supported.
  • The default administrator password must be set on each container using the ADMIN_PWD environment variable. If this parameter is not specified, the default password 'admin' will be used. This password cannot be changed at runtime through the configuration service and is not captured in configuration snapshots.
  • The embedded user registry can only be used to hold static data and should not be used to hold any user data. As a result the embedded user registry should only be used in conjunction with a federated registry, to store the user data, and basic users. The Security Access Manager integration component of the SCIM support will not be available if the embedded user registry is in use.

Shared configuration data

The shared configuration volume is a section of the file system that is reserved for the storage of data to be shared among multiple containers. The data on the shared configuration volume is persisted even if the containers are deleted.

The shared configuration volume is mounted in a Security Access Manager container at '/var/shared'. Snapshots, support files, and fix packs are stored in this volume. To manage these files, you can use the Manage System Settings > Network Settings > Shared Volume page of the configuration container LMI.

Snapshots

Snapshots are located in the snapshots directory of the configuration volume.

When a snapshot is published from the configuration container, it is stored on the shared volume. When a runtime container is started, it uses the snapshot to perform configuration and bootstrap successfully. Snapshots can only be created using the configuration container, though an administrator can also manually add or remove snapshots by directly accessing the Docker volume.

Support files

Support files are located in the support directory of the configuration volume.

Technically, you can create support files in containers of any type. However, support files are most commonly generated in one of the runtime containers. To generate and retrieve a support file in a runtime container, follow these steps:

  1. Using the CLI or CLI web service, create a support file in the runtime container. This support file will be visible in the configuration container.
  2. If the volume has not been directly mounted in the runtime container and a configuration service has been defined, use the support -> publish CLI command to send the snapshot to the configuration service.
  3. Using the LMI or web service of the configuration container, retrieve the support file. Alternatively, you can also access the support folder on the Docker volume directly to retrieve the support file.
Fix packs

Fix packs are located in the fixpacks directory of the configuration volume.

When a 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, any fix packs present in the fixpacks directory of the configuration volume will be applied in alphanumeric order.

To manage fix packs, you can either access the Docker volume manually, or use the Manage System Settings > Network Settings > Shared Volume page of the configuration container LMI. On the Shared Volume page, you can view the contents of the fixpacks directory of the configuration volume, upload, delete, or rename fix packs.

The Manage System Settings > Updates and Licensing > Fixpack LMI page is read-only in a Docker environment. You can use that page to see which fix packs have been applied, but cannot use it to apply or roll back fix packs.

Log files

By default, Docker uses a layered file system to help reduce the disk space utilization of the Docker 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 (e.g. log files) on a shared volume. All of the log files that are used by Security Access Manager are located in the '/var/application.logs/<identifier>' directory. Therefore the recommended approach is to create this directory as a shared volume when you create your container.

You can view the log files through the Monitor Analysis and Diagnostics > Application Log Files panel of the LMI.

Within the log files directory, a subdirectory is created for each container. The name of the subdirectory is set based on the containers unique identifier.
Note: Prior to IBM Security Access Manager version 9.0.7.0, log files were written to the root directory of the shared log volume. When a container is started and any legacy log directories are encountered on the log volume they are automatically moved to the current containers log subdirectory.

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)
Local management interface log files lmi
Runtime profile log files rtprofile
Runtime audit logs rtaudit
DSC log files dsc
Security Access Manager policy server log and trace files isam_runtime/policy
Embedded User Registry log files isam_runtime/user_registry
Web Reverse Proxy log files wrp/<instance>/log
Web Reverse Proxy statistic files wrp/<instance>/stats
Web Reverse Proxy trace files wrp/<instance>/trace
Web Reverse Proxy transaction files wrp/<instance>/translog
System log files system
Remote system log forwarder files rsyslog_forwarder

The other option is to access the logs with the Web services on the configuration and the runtime containers. By invoking the corresponding "Application Logs" API on each container, the user can list and retrieve the log files on that container. See the Docker Web Services documentation for more information.

Note: The recommended approach is to configure Security Access Manager to send the log files to a remote syslog server wherever possible.