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:
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 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:
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 6.3.1. memory limits.
- ●Enabling 7.5. 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 |
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.