Application parameters

Application parameters are the fundamental parameters used to launch a process running Airlock IAM.

For each instance, a template instance.properties is created, e.g.,  instances/auth/instance.properties.

The instance.properties template contains all available application parameters, descriptions, and default values.

An up-to-date version of the template can be generated using the CLI:

copy
iam default-parameters

Using variables

Variables are used to make the instance.properties file transferable between instances and to avoid hard-wiring paths to the Airlock IAM distribution into the configuration.

Variable

Description

Example (instance.properties)

${instance.name}

name of the instance (e.g. when used in instances/auth/instance.properties, auth)

iam.config = instances/${instance.name}/medusa-configuration.xml

${log4j.base}

path to a logging configuration file with a common built-in set of logging configurations that serve as a base for this instance's logging configuration.

iam.adminapp.log4j.configs = instances/${instance.name}/log4j/all-modules.xml,${log4j.base}

Overriding with profiles

It is possible to launch multiple processes for one instance. Separate profiles can be defined by creating a file called <profile-name>.properties in the instances profiles/ directory. For more information, see Sandboxing with profiles.

When launching, the "--profile" option, or its short version "-p" can be used:

copy
su - airlock
cd /home/airlock/iam
vi instances/auth/profiles/myprofile.properties  # Create a new profile called "myprofile"
iam -c . -i auth -p myprofile  # Launch "auth" instance using the profile "myprofile"

Overriding with environment variables

Environment variables override both the instance instance.properties and the profile properties files.

All application parameters can be overriden using the Environment. This is especially useful during testing/integration, and for Docker deployments.

Environment variables are derived from the parameter name, always written in all-caps, with punctuation such as "-" and "." replaced with "_".

To convert a parameter from instance.properties to an environment variable name, run the following command in a shell:

copy
echo 'iam.web-server.https.port' | tr '[:lower:]' '[:upper:]' | tr '[:punct:]' '_' # Prints "IAM_WEB_SERVER_HTTPS_PORT"

When using Docker, environment variables can be passed using the "-e" option, for example:

copy
docker run -e "IAM_WEB_SERVER_HTTPS_PORT=8443"

Example: Changing the log level to DEBUG

airlock@server.example.com

# Equivalent to setting iam.log.level=DEBUG in instances/auth/instance.properties
IAM_LOG_LEVEL=DEBUG iam -c /home/airlock/iam -i auth

# With Docker the "-e" option is used to set environment variables
docker run -e IAM_LOG_LEVEL=DEBUG airlock-iam # ...

docker-compose.yml

version: '3'
services:
  iam:
    environment:
      - IAM_LOG_LEVEL=DEBUG

Java options

Java options are typically using the "iam.java.opts" parameter. "iam.java.opts" only applies to running IAM itself, but not the CLI processes. E.g. when running "iam -h", "iam.java.opts" does not apply.

Common use-cases for setting Java options include:

  • Setting memory limits.
  • Enabling monitoring through JMX.
  • Using IAM plugins that use native libraries.

The following list describes all possible ways of setting Java options in increasing priority:

Parameter Name

Source

Info

iam.java.opts

File: instances/<instance-name>/instance.properties

iam.java.opts

File: instances/<instance-name>/profiles/<profile-name>.properties

IAM_JAVA_OPTS

Environment

Environment can be set through a shell, systemd service, or Docker. See "IAM_LOG_LEVEL" examples above.

JAVA_OPTS

Environment

This environment variable applies to any and all commands, including CLI commands.

This variable is technically not an application parameter and will not be logged as part of application parameter logging.

Inspecting application parameters

The final resolved values used to launch Airlock IAM can be inspected as follows:

  • During start-up relevant parameters are logged to the standard output (stdout) of the process.
  • Running the CLI command iam info displays all resolved parameters for a given instance/profile combination. (Use iam info -h to get usage information)
  • All parameters are written as Java System Properties. System Properties can be inspected through standard Java tools, such as JMX. See Monitoring, health checks, and metrics.