Configuration CLIs

Airlock IAM provides a number of command-line tools (CLIs) for configuration management. They expose crucial config management functions to the command line and can be used, for example, in configuration automation pipelines or scripts.

General information

The config CLIs are part of the IAM CLI (the one used for creating instances, upgrading, etc.). To get an up-to-date list of config manipulating CLIs, call iam config -h.

In IAM 8.4 this results in the commands in the table further below in this article. More commands may have been added in later versions.

Functional limitation

Note that all subcommands of iam config only work on YAML configuration files and not on XML configuration files.

All commands related to config manipulation can be either used on:

an IAM instance: the command then automatically manipulates the file iam-config.yaml within the specified instance.
a single file: the command then manipulates the file given as an argument or writes a new file.

Config CLI command overview

The following table summarizes the config commands as of IAM 8.4. Use the -h option with each command for further usage information.

Command	Description
`iam config validate`	This CLI command is used to validate a configuration (or snippet) file, i.e., check if it contains a correct configuration that can be activated. The validation checks are the same as in the Config Editor. When validating snippets, unconnected plugins are validated as well. The CLI command allows you to specify a custom code directory to include custom code plugins in the validation process. Usage examples: Validate the resulting configuration after automated modification using a script. Make a deployment pipeline fail if a configuration is invalid. Use CLI command while developing snippets.
`iam config import-snippet`	This CLI command is used to import a configuration snippet into a configuration or another snippet. The plugins from the snippet are not connected to the plugins from the target configuration. Use the separate connect CLI commands. Usage example: Put together a configuration from a base configuration and one or more snippets in a script or deployment pipeline. Note that a snippet can also be imported into a configuration by uploading the snippet in the Config Editor.
`iam config connect plugin`	This CLI command is used to connect a plugin to a plugin property of another plugin. Usage examples: Modification or completion of a configuration in a script. Connecting plugins after importing a snippet in a script or deployment pipeline.
`iam config connect to-list`	This CLI command is used to insert a plugin to a plugin list property of another plugin. Usage examples: Modification or completion of a configuration in a script. Connecting plugins after importing a snippet in a script or deployment pipeline. Note the different command modes: plugins can be appended to the list, inserted at a given index position, after or before a specified other plugin.
`iam config connect to-map`	This CLI command is used to insert a plugin to a plugin map property of another plugin. Usage examples: Modification or completion of a configuration in a script. Connecting plugins after importing a snippet in a script or deployment pipeline.
`iam config convert`	This CLI command is used to convert XML configuration files to YAML. There is no possibility to convert YAML back to XML.

Example usage

Consider the following example Bash script excerpt. It does the following:

Import a simple snippet into the main configuration.
Connect a config tree of the snippet to the base configuration.
Validate the resulting configuration.
For simplicity, error handling after calling each CLI command has been omitted.

Example

#!/bin/bash


# import snippet "2fa-letter-task.yaml" into "iam-config.yaml" 
./iam config import-snippet -f iam-config.yaml 2fa-letter-task.yaml
 
# all plugins (and trees thereof) of the snippet are now in the
# main configuration but not connected. 
 
# use the "connect" command to insert a plugin tree from the
#  snippet into a plugin list property from the main configuration.
./iam config connect to-list -f iam-config.yaml -s "airlock2FA-letter-task-schedule" -d "taskScheduler" -p "tasks"

# validate result configuration
./iam config validate -f iam-config.yaml
 
# Abort if the configuration is not valid
if [ $? -ne 0 ]
then
  echo "Aborting because configuration not valid"
  exit 1
fi

More examples can be found in the article about snippets.