Reference - Agent configuration
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.
Minimum recommended variables
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. |
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.