Configuration CLIs

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

General information

The configuration CLIs are part of the IAM CLI - the same CLI used for creating and upgrading instances, etc. To get an up-to-date list of config manipulating CLIs, call iam config -h. For an overview of the available commands, see the table further below in this article.

 
Functional limitation

All subcommands of iam config work only with YAML configuration files and not with XML configuration files.

All commands related to config manipulation can be 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 checks whether the configuration in a configuration file or snippet is valid and can be activated. It performs the same validation as the Config Editor. When validating snippets, unconnected plugins are also included in the check.

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 check-license

This CLI command checks whether all the plugins in a configuration are covered by the license.

Usage examples:

  • Verification of the license coverage after assembling or manipulating a configuration.

iam config import-snippet

This CLI command imports 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 connects 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 inserts 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 inserts 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 converts 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:

  • Imports a simple snippet into the main configuration.
  • Connects a config tree of the snippet to the base configuration.
  • Validates 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.