Environment Variables

Environment Variables Defined in Integration Server and Microservices Runtime

Integration Server and Microservices Runtime have defined environment variables (ENV variable). These environment variables can be used in the following situations:

  • To support performing tasks while Integration Server or Microservices Runtime runs in a Docker container. Environment variables are included in the docker run command immediately before the image name.
  • When starting Integration Server or Microservices Runtime from the command line.
  • When starting an Integration Server or Microservices Runtime that functions as an Edge Runtime with Integration Anywhere.
  • As the value of a substitution variable during ACDL-based deployment, including deploying to Cloud Container.

    To use the value of an environment variable as the substitution value, specify the substitution value as: ${ENV_VARIABLE} where ENV_VARIABLE is the name of a defined environment variable. If you specify an environment variable that does not exist, ${ENV_VARIABLE} will be retained and used in the configuration.

Note: Unless otherwise specified, an environment variable for use with Microservices Runtime can be used with an Integration Server equipped with a Microservices license.

The following table identifies the environment variables supported with Integration Server or Microservices Runtime.

Environment Variable Description
EXTERNALIZE_PACKAGES When set to true, instructs the Integration Server running in the Docker container to load the packages located in one of the following directories at startup:
  • <HOST_DIR>/<SERVICE_NAME>/packages
  • <HOST_DIR>/<INSTANCE_NAME>/packages

Where HOST_DIR SERVICE_NAME, and INSTANCE_NAME are the values set for the ENV variables of the same name.

If SERVICE_NAME is supplied,Integration Server looks in <HOST_DIR>/<SERVICE_NAME>/packages. Only if SERVICE_NAME is not supplied, does Integration Server look in <HOST_DIR>/<INSTANCE_NAME>/packages.

The default value of EXTERNALIZE_PACKAGES is false.

The content of the packages directory must be a folder where the folder name is the package name. The contents of the packageName folder must match the structure of Integration Server packages. That is the packages located in the packages directory cannot be an archive file, such as *.zip or *.7z. For information about the structure of an Integration Server package, see How the Server Stores Package Information.

HOST_DIR The path to the mounted directory on the HOST machine to which to write the files. Passing the HOST_DIR parameter and value or setting it as an ENV variable with the docker run command externalizes the logs and configuration artifacts of Integration Server.
LOG_FORMAT Specifies the format to which Integration Server converts the server log and audit log entries written to the console (STDOUT or computer screen). Integration Server supports only "json" type.
JAVA_MAX_MEM The maximum heap size. The default value is 1024 MB. Use the JAVA_MAX_MEM environment variable to override the value set forMicroservices Runtime in Integration Server_directory /bin/setenv.bat|sh file without having to edit the file itself.
Note: The JAVA_MAX_MEM environment variable is for use with Microservices Runtime only.
JAVA_MIN_MEM The minimum heap size. The default value is 256 MB. Use the JAVA_MIN_MEM environment variable to override the value set for Microservices Runtime in Integration Server_directory /bin/setenv.bat|sh file without having to edit the file itself.
Note: The JAVA_MIN_MEM environment variable is for use with Microservices Runtime only.
PERSIST_LOGS If set to true, the Integration Server running inside the Docker container persists the log files to HOST_DIR/SERVICE_NAME/logs where SERVICE_NAME is replaced by INSTANCE_NAME if the SERVICE_NAME environment variable is not specified. Integration Server externalizes the logs located in the Integration Server_directory /instances/<instanceName>/logs directory. If set to false, the Integration Server running inside the Docker container does not externalize the log files. The default is true.
PERSIST_CONFIGS If set to true, the Integration Server running inside the Docker container persists the configuration files to the HOST_DIR/SERVICE_NAME/config directory where SERVICE_NAMEis replaced by INSTANCE_NAME> if the SERVICE_NAME environment variable is not specified. If set to false, the Integration Server running inside the Docker container does not externalize the config files. The default is true.
SAG_IS_ADMIN_PASSWORD Specifies the password to be used for the Administrator user. This password replaces the Administrator password value specified in Integration Server or Microservices Runtime.
SAG_IS_AUDIT_STDOUT_LOGGERS Specifies the audit loggers to write to the console (STDOUT). When an audit logger writes to STDOUT it is considered an auxiliary output which means the logger will still write to the specified log destination of file or database. Set to one of the following:
  • A comma-separated list of the audit loggers that you want to write to STDOUT. For example: WMSESSION,WMERROR

    The audit logger name is the first portion of the audit log file name. For a list of audit log files names, see File Names and Locations .

  • A comma-separated list of the logger names as they appear in the Logs > Logging configuration page in Integration Server Administrator. For example: Session Logger,Error Logger
  • ALL to write all log entries for all file-based audit loggers to STDOUT.
  • NONE to indicate that none of the file-based audit loggers will write to STDOUT. This is the default value.

The variable content is case-insensitive.

When writing audit log entries to STDOUT, Integration Server includes the logger name in the entry to identity the source of the entry.

For information about using the SAG_IS_AUDIT_STDOUT_LOGGERS environment variable with Integration Server running in Docker container, see Writing Audit Logs to the Console.

You can configure the delimiters used for fields and records in the audit log entries written to STDOUT using the watt.server.audit.stdout.fieldDelimiter and watt.server.audit.stdout.recordDelimiter server configuration parameters, respectively.

SAG_IS_CLOUD_ALLOW_SYNC

Specifies whether the Integration Server or Microservices Runtime acting as an Edge Runtime synchronizes with cloud tenant on Integration. Synchronization occurs when the runtime starts and when a refresh request is received from Integration. During synchronization, the Edge Runtime requests the latest agent manifest from Integration and attempts to provision everything in the manifest. An agent manifest contains packages, assets, and configurations needed for proper functioning of the Edge Runtime.

Set to true to allow synchronization to occur at start up and when Integration requests that the Edge Runtime refresh.

Set to false to prevent synchronization at start up and to refuse any refresh requests from Integration. Edge Runtime will respond to refresh requests with an HTTP Status of 403 Forbidden and the error message “Cloud synchronization is disabled for this server.”

Specify the SAG_IS_CLOUD_ALLOW_SYNC environment variable when starting a Docker container to control whether synchronization with Integration occurs for that Edge Runtime.

You might want to disable synchronization with Integration when starting a Docker container for an Edge Runtime that is a production ready image that has already been synchronized. The Integration Server or Microservices Runtime used as the Docker image might have watt.edge.allowSync set to true, which allows and performs synchronization with Integration. The SAG_IS_CLOUD_ALLOW_SYNC value supplied when starting the container overwrites the watt.edge.allowSync value in the image. By disabling synchronization, you can effectively “lock” an image so that synchronization is not attempted.

If the SAG_IS_CLOUD_ALLOW_SYNC environment variable is not specified or is an invalid value, the Edge Runtime relies on the value of watt.edge.allowSync to determine if synchronization with Integration occurs.

SAG_IS_CLOUD_REGISTER_TOKEN The token used to register an Integration Server or Microservices Runtime with Integration. The registration token, also known as a pairing token, is provided when you use Integration to register Integration Server or Microservices Runtime as an Edge Runtime.
SAG_IS_CLOUD_REGISTER_URL The URL of Integration with which to register Integration Server or Microservices Runtime. The Cloud URL is provided when you use Integration to register Integration Server or Microservices Runtime as an Edge Runtime.
SAG_IS_CONFIG_PROPERTIES Specifies the location and name of the configuration variables template or the directory containing templates for use with Microservices Runtime or an Integration Server with licensed Microservices functionality. Use a comma-separated list to specify multiple templates and/or directories.
SAG_IS_CONFIG_VARIABLES_DEBUG When set to true, instructs Microservices Runtime to include debug level messages in the log generated during configuration variable initialization. When set to false, configuration log messages of severity Information and higher are included in the configuration variables log. The default is false.

For more information about configuration variables logging, see Configuration Variables Logging .

SAG_IS_CONFIG_VARIABLES_ENC_KEY Key that Microservices Runtime uses for encrypting and decrypting values in a configuration variables template (application.properties file). The encryption key must be 16, 24, or 32 bit string.

For more information about encrypting configuration variables, see Encrypting Values for the Variables Template .

SAG_IS_DEBUG_LEVEL Specifies the logging level for the server logger when Integration Server runs in a Docker container.

Set the logging level using the environment variable at container start up. For more information about the logging levels, see Logging Levels.

If the environment variable is invalid or absent, Integration Server or Microservices Runtime uses the default value of the watt.debug.level parameter. For more information about setting the logging levels using the parameter, see watt.debug..

SAG_IS_DIAGNOSTIC_PORT Specifies the diagnostic port for an Integration Server running in a Docker container. The supplied value overrides the value set for watt.server.diagnostic.port.

Do not specify a port number of 5555 or 5543 as these are the default values for the primary port and the secure port, respectively. If you specify 5555 or 5543 as the SAG_IS_DIAGNOSTIC_PORT value, Integration Server ignores the supplied value and uses the value of watt.server.diagnostic.port instead.
SAG_IS_EDGE_CLOUD_ALIAS Unique alias for an Integration Server or Microservices Runtime acting as an Edge Runtime. Supply the SAG_IS_EDGE_CLOUD_ALIAS when restarting an Edge Runtime that has crashed.
SAG_IS_HTTP_PORT Specifies the primary port for an Integration Server running in a Docker container. The supplied value overrides the value set for watt.server.port.

If a port with this number does not yet exist, Integration Server adds a new HTTP port to the WmRoot package. This new port is added as the primary port and contains default values. If a port with the same TCP/IP number already exists in the WmRoot package, Integration Server overrides its settings with the new default values. In effect, deleting the existing port and then adding a new port with default settings.

Do not specify a port number of 9999 or 5543 as these are the default values for the diagnostic port and the secure port, respectively. If you specify 9999 or 5543 as the SAG_IS_HTTP_PORT value, Integration Server ignores the supplied value and uses the value of watt.server.port instead.
SAG_IS_HTTPS_PORT Specifies the default secure port for an Integration Server running in a Docker container. The supplied value overrides the value set for watt.server.securePort.

If a port with this number does not yet exist, Integration Server adds a new HTTPS port to the WmRoot package. This new port is added as the DefaultSecure port and contains default values. If a port with the same TCP/IP number already exists in the WmRoot package, Integration Server overrides its settings with the new default values. In effect, deleting the existing port and then adding a new port with default settings.

Do not specify a port number of 5555 or 9999 as these are the default values for the primary port and the diagnostic port, respectively. If you specify 5555 or 9999 as the SAG_IS_HTTP_PORT value, Integration Server ignores the supplied value and uses the value of watt.server.securePort instead.
SAG_IS_HEALTH_ENDPOINT_ACL Specifies the Access Control List (ACL) whose members can invoke the health gauge endpoints /health and /health/readiness. The default ACL for /health/liveness is “Anonymous”. Therefore, authentication is not required when the endpoint is invoked.

For a Microservices Runtime or Integration Server running in a Docker container that was created using the is_container.bat/sh script, the default ACL for accessing the health gauge endpoint is Anonymous, which means authentication is not required when the endpoint is invoked. For all other Microservices Runtimes or Integration Servers, the default ACL is Administrators.

SAG_IS_LICENSE_FILE Supplies a license file to use with Integration Server in place of the licenseKey.xml located in the Integration Server_directory /instances/instanceName/config. The specified license key must be a valid license file and in a location accessible by Integration Server. For an Integration Server running in a Docker container, the provided license key must be available on a mounted directory on the host file system. At start up, if a file exists at the location specified by SAG_IS_LICENSE_FILE, Integration Server copies the file from the specified location to Integration Server_directory /instances/instanceName/config and saves the file as licenseKey.xml

Supplying the license file at start up can be useful when a Docker image for an Integration Server contains an expired license file or you want it specify an alternative license file for use with an existing Docker image. By using SAG_IS_LICENSE_FILE to supply the license file, you can change the license file without recreating a Docker image.

SAG_IS_MASTER_PASSWORD_KEY The master password to use for an Integration Server running in a Docker container. Integration Server uses master passwords to encrypt outbound passwords. You can configure Integration Server to use the master password for encrypting and decrypting configuration variable values.
SAG_IS_METRICS_ENDPOINT_ACL Specifies the Access Control List (ACL) whose members can invoke the metrics endpoint /metrics.

For a Microservices Runtime or Integration Server running in a Docker container that was created using the is_container.bat/sh script, the default ACL for accessing the metrics endpoint is Anonymous, which means authentication is not required when the endpoint is invoked. For all other Microservices Runtimes or Integration Servers, the default ACL is Administrators.

SAG_IS_SHUTDOWN_WAIT_TIME Maximum number of seconds Integration Server waits for running services to complete before shutting down. Integration Server starts waiting after a shutdown or restart request is made. The default is 600 seconds for Integration Server and 300 seconds for a Microservices Runtime. Set to 0 to shut down immediately.
SECRET_PATH Specifies the path to a Kubernetes Secret inside a container. Passing the SECRET_PATH ENV variable with the docker run command allows sensitive data stored in a Kubernetes Secret to be referenced from a configuration variables template.
SERVICE_NAME Name of a unique directory under HOST_DIR for persisting Integration Server artifacts. When supplied, the logs and config directories are created under the HOST_DIR/SERVICE_NAME directory and all artifacts of logs and config directories are persisted in the respective directories. If SERVICE_NAME is not supplied, Integration Server instance name will be used for the name of the unique directory that gets created under the HOST_DIR directory. IBM recommends specifying a unique directory for each Docker container.
WM_HTTPS_PROXY_ALIAS Specifies the name of the proxy server.
WM_HTTPS_PROXY_HOST Specifies the host name or IP address of the proxy server.
WM_HTTPS_PROXY_PORT Specifies the port on which the proxy server listens to HTTPS requests.
WM_HTTPS_PROXY_PWD Specifies the password Integration Server uses to access the proxy server.
WM_HTTPS_PROXY_USER Specifies the user name Integration Server uses to access the proxy server.
WM_HTTPS_PROXY_IS_DEFAULT

Specifies whether the proxy server alias should be the default proxy server alias for HTTPS or not. Only one default proxy server alias can be set for each protocol type. The values are Yes (Y) or No (N). If no value is provided, this defaults to N.
WM_IS_INFO_NAME Specifies a name to identify an Integration Server. This can be useful when you are running multiple servers and want to more easily differentiate between them.

You can also define the server name in the watt.server.info.name server configuration parameter. If both watt.server.info.name and WM_IS_INFO_NAME are set, the WM_IS_INFO_NAME value takes precedence. For more information about the parameter, see watt.server.info.name.

WM_IS_INFO_TYPE Specifies the type of Integration Server where the type can be one of the following: DEV, TEST, UAT, PREPROD, PROD, or a user-defined type.

You can also you can define the server type in the watt.server.info.type server configuration parameter which accepts the same values as WM_IS_INFO_TYPE. If both watt.server.info.type and WM_IS_INFO_TYPE are set, the WM_IS_INFO_TYPE value takes precedence. For more information about the parameter, see watt.server.info.type.
WM_IS_SECURITY_PROFILE Specifies the security profile for an Integration Server environment. The value is either DEV or PROD depending on the security needs of the environment. Specify DEV for a development environment and PROD for a production environment.
WM_PORTS_ADMIN_RESTRICTACCESS Specifies whether Integration Server denies access to Integration Server Administrator and APIs that are accessed through admin ports. An admin port is any predefined or custom port associated with the WmRoot or WmAdmin package. Predefined ports include DefaultPrimary, DefaultDiagnostic, DefaultSecure. Set to:
  • None: Integration Server has no restrictions and functions normally on the admin ports. This is the default.
  • UI: Integration Server denies access to Integration Server Administrator through the admin ports.
  • ALL: Integration Server denies access to Integration Server Administrator and all the APIs through the admin ports.

The supplied value to this variable overrides the value in application.properties, server.cnf, and the security profile. For more information, see "Denying access to Integration Server Administrator and APIs" section in Using Integration Server Administrator.