8.1. 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:

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.

Example (instance.properties)
name of the instance (e.g. when used in instances/auth/instance.properties, auth)
iam.config = instances/${instance.name}/medusa-configuration.xml
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 7.2. Sandboxing with profiles.

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

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:

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:

docker run -e "IAM_WEB_SERVER_HTTPS_PORT=8443"

Example: Changing the log level to DEBUG


# 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 # ...


version: '3'

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:

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

Parameter Name
File: instances/<instance-name>/instance.properties
File: instances/<instance-name>/profiles/<profile-name>.properties
Environment can be set through a shell, systemd service, or Docker. See "IAM_LOG_LEVEL" examples above.
This environment variable applies to any and all commands, including CLI commands.
information.svg 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 7.5. Monitoring/health checks.