Reference - Agent configuration

Use the following environment variables to control your Discovery and Traceability agents

11 minute read

As the Discovery and Traceability agents share many parameters, it is more efficient to use environment variables and reference these parameters, instead of declaring parameters twice.

To maintain a shareable collection of environment files, you can create a da_env_vars.env (Discovery Agent) and ta_env_vars.env (Traceability Agent) file per environment, which contains simple key value pairs. By default, agent configuration files are looking for corresponding environment variables before looking on the configuration file property. This file can be used for both modes of the agent (binary VS Docker container).

Note that the agent (binary mode) will accept an argument pointing to the environment variables file, which you can point to the da_env_vars.env or ta_env_vars.env file. Use the –envFile da_env_vars.env argument with either agent, pointing to the file for that agent.

Note that the Docker image of the agent is expecting this da_env_vars.env or ta_env_vars.env as an argument of the Docker runner docker run --env-file <PATH>/da_env_vars.env...

Some variables/properties have a default known value so that there is no need to parameter them.

In order to be able to switch easily from one environment to another, the following environment variables list is a good starting point:

#
#API Manager connectivity
#
APIMANAGER_HOST=ApiManagerHostName (localhost by default)
APIMANAGER_PORT=ApiManagerPortNunber (8075 by default)
APIMANAGER_AUTH_USERNAME=AnApiManagerUserName
APIMANAGER_AUTH_PASSWORD=AnApiManagerUserPassword
#
#API Gateway connectivity
#
APIGATEWAY_HOST=ApiGatewayHostName (localhost by default)
APIGATEWAY_PORT=ApiGatewayPortNumber (8090 by default)
APIGATEWAY_AUTH_USERNAME=AnApiGatewayOperatorUser
APIGATEWAY_AUTH_PASSWORD=AnApiGatewayOperatorUserPassword
#
#API Central connectivity
#
CENTRAL_AUTH_CLIENTID=AnApiCentralServiceAccountClientId
CENTRAL_ORGANIZATIONID=TheOrganizationIDfromAmplifyCentral
CENTRAL_ENVIRONMENT=AmplifyCentralEnvironmentName
CENTRAL_TEAM=AmplifyCentralTeamName

If you are either struggling with a variable value or you want to benefit from the advanced agents features (API filtering / SSL security / proxy access / logging), the following section describes all the variables the agents (discovery / traceability) rely on.

Complete variable list for advance features

You can extend the previous minimum variable list with the following variables. Some are common to all agents and some are specific to an agent.

Common variables to both agents

Variable name Description
API Manager variables
APIMANAGER_HOST The host API Manager is running on (default value: localhost).
APIMANAGER_PORT The port API Manager is listening on (default value: 8075).
APIMANAGER_APIVERSION The API version of the API Manager (default value: 1.3).
APIMANAGER_POLLINTERVAL The frequency in which API Manager is polled for new endpoints (default=ns, us, ms, s, m, h). Set to 30s.
APIMANAGER_PROXYURL The URL for the proxy for API Manager <http://username:password@hostname:port>. If empty, no proxy is defined.
APIMANAGER_SUBSCRIPTIONAPPLICATIONFIELD The custom field name used to save subscription IDs to the API Manager application (default value: subscriptions). To display this in the UI, add a custom property under applications in your API Manager configuration. See Customize API Manager.
APIMANAGER_SUBSCRIPTIONSISSUENEWCREDENTIALS When creating a subscription on Amplify Central, setting this value to true will cause the agent to create new authorization credentials for the API Manager application. If false, new subscriptions will use a previously defined authentication credential from the application. The value defaults to true.
APIMANAGER_ALLOWAPPLICATIONAUTOCREATION When creating a subscription on Amplify Central, setting this value to true will enable a selection in the App name dropdown for ‘Create an application.’ This allows the user to either select from an existing API Manager application, or to create a new application in API Manager. The new application in API Manager will be given the name of the subscription ID from Amplify Central. A value of false will cause ‘Create an application’ to not be shown in the dropdown. (default value: true).
APIMANAGER_AUTH_USERNAME The API Manager username for this agent. Created in API Manager (must be API Manager Admin).
APIMANAGER_SUBSCRIPTIONSISSUENEWCREDENTIALS When creating a subscription on Amplify Central, setting this value to true will cause the agent to create new authorization credentials for the API Manager application. If false, new subscriptions will use a previously defined authentication credential from the application. The value defaults to true.
APIMANAGER_AUTH_PASSWORD The password created for the API Manager username created for this agent (created in API Manager).
APIMANAGER_SSL_MINVERSION String value for the minimum SSL/TLS version that is acceptable. If zero, empty TLS 1.0 is taken as the minimum. Allowed values are: TLS1.0, TLS1.1, TLS1.2, TLS1.3.
APIMANAGER_SSL_MAXVERSION String value for the maximum SSL/TLS version that is acceptable. If empty, then the maximum version supported by this package is used, which is currently TLS 1.3. Allowed values are: TLS1.0, TLS1.1, TLS1.2, TLS1.3.
APIMANAGER_SSL_CIPHERSUITES An array of strings. It is a list of supported cipher suites for TLS versions up to TLS 1.2. If CipherSuites is nil, a default list of secure cipher suites is used, with a preference order based on hardware performance. See Supported Cipher Suites.
APIMANAGER_SSL_NEXTPROTOS An array of strings. It is a list of supported application level protocols, in order of preference, based on the ALPN protocol list. Allowed values are: h2, http/1.0, http/1.1, h2c.
APIMANAGER_SSL_INSECURESKIPVERIFY Controls whether a client verifies the server’s certificate chain and host name. If true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks.
API Gateway variables
APIGATEWAY_HOST The host that Axway API Gateway is running on (default value: localhost).
APIGATEWAY_PORT The port that Axway API Gateway is listening on (default value: 8090).
APIGATEWAY_POLLINTERVAL The frequency in which the agent polls the logs in us, ms, s, m, h. Default=ns. Set to 1m.
APIGATEWAY_PROXYURL The URL for the proxy for Axway API Gateway <http://username:password@hostname:port>. If empty, no proxy is defined.
APIGATEWAY_AUTH_USERNAME Your Axway API Gateway username: should have an API Operator role.
APIGATEWAY_AUTH_PASSWORD Your Axway API Gateway user password.
APIGATEWAY_SSL_MINVERSION String value for the minimum SSL / TLS version that is acceptable. If zero, empty TLS 1.0 is taken as the minimum. Allowed values are: TLS1.0, TLS1.1, TLS1.2, TLS1.3.
APIGATEWAY_SSL_MAXVERSION String value for the maximum SSL / TLS version that is acceptable. If empty, then the maximum version supported by this package is used, which is currently TLS 1.3. Allowed values are: TLS1.0, TLS1.1, TLS1.2, TLS1.3.
APIGATEWAY_SSL_CIPHERSUITES An array of strings. It is a list of supported cipher suites for TLS versions up to TLS 1.2. If CipherSuites is nil, a default list of secure cipher suites is used, with a preference order based on hardware performance. See [Supported Cipher Suites] (/docs/central/connect-api-manager/agent-security-api-manager/).
APIGATEWAY_SSL_NEXTPROTOS An array of strings. It is a list of supported application level protocols, in order of preference, based on the ALPN protocol list. Allowed values are: h2, http/1.0, http/1.1, h2c.
APIGATEWAY_SSL_INSECURESKIPVERIFY InsecureSkipVerify controls whether a client verifies the server’s certificate chain and host name. If true, then TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks.
Amplify Central variables
CENTRAL_DEPLOYMENT Specifies region (default: US = prod / EU = prod-eu).
CENTRAL_URL The URL to the Amplify Central instance being used for Agents (default value: US = <https://apicentral.axway.com> / EU = https://central.eu-fr.axway.com).
CENTRAL_ORGANIZATIONID The Organization ID from Amplify Central. Locate this at Platform > User > Organization.
CENTRAL_TEAM The name of the team in Amplify Central that all APIs will be linked to. Locate this at Amplify Central > Access > Team Assets.
CENTRAL_MODE Method to send endpoints back to Central. (publishToEnvironment = API Service, publishToEnvironmentAndCatalog = API Service and Catalog asset).
CENTRAL_APPENDDATAPLANETOTITLE Set to false to skip adding the data plane name to the title and description of the API.
CENTRAL_PROXYURL The URL for the proxy for Amplify Central <http://username:password@hostname:port>. If empty, no proxy is defined.
CENTRAL_AUTH_URL The Amplify login URL: <https://login.axway.com/auth>
CENTRAL_AUTH_REALM The Realm used to authenticate for Amplify Central: Broker.
CENTRAL_AUTH_CLIENTID The client identifier associated to the Service Account created in Amplify Central. Locate this at Amplify Central > Access > Service Accounts > client Id.
CENTRAL_AUTH_PRIVATEKEY The private key associated with the Service Account.
CENTRAL_AUTH_PUBLICKEY The public key associated with the Service Account.
CENTRAL_AUTH_KEYPASSWORD The password for the private key, if applicable.
CENTRAL_AUTH_TIMEOUT The timeout to wait for the authentication server to respond (ns - default, us, ms, s, m, h). Set to 10s.
CENTRAL_ENVIRONMENT Name of the Amplify Central environment where API will be hosted.
CENTRAL_APISERVERVERSION Version of the API Server that the agent will communicate with
CENTRAL_SSL_MINVERSION String value for the minimum SSL/TLS version that is acceptable. If zero, empty TLS 1.0 is taken as the minimum. Allowed values are: TLS1.0, TLS1.1, TLS1.2, TLS1.3.
CENTRAL_SSL_MAXVERSION String value for the maximum SSL/TLS version that is acceptable. If empty, then the maximum version supported by this package is used, which is currently TLS 1.3. Allowed values are: TLS1.0, TLS1.1, TLS1.2, TLS1.3.
CENTRAL_SSL_CIPHERSUITES An array of strings. It is a list of supported cipher suites for TLS versions up to TLS 1.2. If CipherSuites is nil, a default list of secure cipher suites is used, with a preference order based on hardware performance. See Supported Cipher Suites.
CENTRAL_SSL_INSECURESKIPVERIFY Controls whether a client verifies the server’s certificate chain and host name. If true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks.
CENTRAL_SUBSCRIPTIONS_APPROVAL_MODE The mode for approving subscriptions on Amplify Central (manual, auto, webhook; default = manual).
CENTRAL_SUBSCRIPTIONS_APPROVAL_WEBHOOK_URL The url for a subscription approval webhook (if any). CENTRAL_SUBSCRIPTIONS_APPROVAL_MODE must be set to “webhook” for webhooks to be invoked.
CENTRAL_SUBSCRIPTIONS_APPROVAL_WEBHOOK_HEADERS The headers to pass to the subscription approval webhook (if any). For example, “Header=contentType,Value=application/json”.
CENTRAL_SUBSCRIPTIONS_APPROVAL_WEBHOOK_AUTHSECRET The authentication secret to pass to the subscription approval webhook (if any).
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_WEBHOOK_URL The webhook URL that subscription data will be posted to, see Subscription webhook notifications.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_WEBHOOK_HEADERS The headers that will be used when posting data to the webhook url, see Subscription webhook notifications.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_HOST The SMTP server that will send email notifications.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PORT The SMTP port to communicate to the SMTP server over.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_AUTHTYPE The authentication type based on the email server. You may have to refer to the email server properties and specifications. This value defaults to NONE.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_USERNAME The username used to authenticate to the SMTP server, if necessary.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_PASSWORD The password used to authenticate to the SMTP server, if necessary.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_FROMADDRESS The email address that will be listed in the from field.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_SUBJECT The subject of email sent for Subscribe events.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_BODY The body of the email for Subscribe events.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_OAUTH The body of the email for Subscribe events when the API is secured using an OAUTH token.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBE_APIKEYS The body of the email for Subscribe events when the API is secured using an APIKEY.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBE_SUBJECT The subject of email sent for Unsubscribe events.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBE_BODY The body of the email for Unsubscribe events.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBEFAILED_SUBJECT The subject of email sent for Failed to Subscribe events.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_SUBSCRIBEFAILED_BODY The body of the email for Failed to Subscribe events.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBEFAILED_SUBJECT The subject of email sent for Failed to Unsubscribe events.
CENTRAL_SUBSCRIPTIONS_NOTIFICATIONS_SMTP_UNSUBSCRIBEFAILED_BODY The body of the email for Failed to Unsubscribe events.
Status variables
STATUS_PORT Port used for checking the health status of the running agent.
STATUS_HEALTHCHECKINTERVAL Time in seconds between running periodic health checker (binary agents only). Allowed values are from 30 seconds to 5 minutes. Specify value as s or m. (default value: 30s)
STATUS_HEALTHCHECKPERIOD Time in minutes allotted for services to be ready before exiting the agent. Allowed values are from 1 to 5 minutes
Logging variables
LOG_LEVEL The log level for output messages (debug, info, warn, error).
LOG_FORMAT The format to print log messages (json, line, package).
LOG_OUTPUT The output for the log lines (stdout, file, both).
LOG_MASKEDVALUES Comma-separated list of keywords to identify within the agent config, which is used to mask its corresponding sensitive data. Keywords are matched by whole words and are case-sensitive.
LOG_FILE_NAME The name of the log files.
LOG_FILE_PATH The path (relative or absolute) to save logs files, if output type file or both.
LOG_FILE_ROTATEEVERYMEGABYTES The max size, in megabytes that a log file can grow to.
LOG_FILE_KEEPFILES The max number of log file backups to keep.
LOG_FILE_CLEANBACKUPS The max age of a backup file, in days.

Note: For logging, it is recommended to set it up in the agent configuration file to keep the log separated for each agent.

Specific variables for Discovery Agent

Variable name Description
APIMANAGER_DISCOVERYIGNORETAGS Comma-separated blacklist of tags that should not be on a Proxy before sending to Amplify Central. Take precedence over APIMANAGER_FILTER
APIMANAGER_FILTER Expression to filter the API you want the agent to discover. See Discover APIs.
CENTRAL_MODE Method to send endpoints back to Central. (publishToEnvironment = API Service, publishToEnvironmentAndCatalog = API Service and Catalog asset).
CENTRAL_ADDITIONALTAGS Additional tag names to publish while publishing the API. Could help to identified the API source. It is a comma separated list.

Specific variables for Traceability Agent

Variable name Description
EVENT_LOG_PATHS The path(s), comma separated, to the event logs that need to be watched.
TRACEABILITY_HOST The host name and port of the ingestion service to forward the transaction log entries (default value: US = <ingestion-lumberjack.datasearch.axway.com:453> / EU = ingestion-lumberjack.visibility.eu-fr.axway.com:453).
TRACEABILITY_PROTOCOL Protocol (https or tcp) to be used for communicating with ingestion service (default value: tcp).
TRACEABILITY_PROXYURL The socks5 or http URL of the proxy server for ingestion service (<socks5://hostname:port>). If empty, no proxy is defined.
TRACEABILITY_COMPRESSIONLEVEL The gzip compression level for the output event (default value: 3).
TRACEABILITY_BULKMAXSIZE The maximum number of events to bulk in a single ingestion request (default value: 100).
TRACEABILITY_TIMEOUT The time to wait for ingestion response (default value: 300s).
QUEUE_MEM_EVENTS The size of the internal queue used for storing consumed events before publishing them (default value: 2048).
QUEUE_MEM_FLUSH_MINEVENTS The minimum number of events in queue required for publishing (default value: 100).
QUEUE_MEM_FLUSH_TIMEOUT The maximum time to wait for min_events to be fulfilled (default value: 1s).
APIGATEWAY_GETHEADERS Call the API Gateway API to get additional transaction details (headers, useragent). If false, API Gateway config does not need to be set. Default is True.

Last modified February 2, 2021: APIGOV-17429 Change AMPLIFY to Amplify (#1606) (eda66915)