Proxy Options

Options in the 'proxy' section mostly apply to clients of the proxy and the proxy itself. It does not contain any EMS-specific options.

proxy.certificate

The path to a file containing the proxy's client-facing public TLS certificate. Certificate files may be in PEM (.pem), DER (.der), or PKCS#12 (.p12 or .pfx) format.

If a PKCS#12 file containing both the public certificate and its private key is used, then either specify the same file for both the proxy.certificate and proxy.private_key options, or leave the proxy.certificate option unset and only set the proxy.private_key option.

If not specified and TLS has not been disabled by the proxy.disable_tls option, a temporary random self-signed public certificate and private key will be generated at startup.

Default value: none

Example usage:

Command Line

--proxy.certificate /path/to/public_cert.pem

Config File

proxy:
  certificate: /path/to/public_cert.pem

Environment Variable

EMSRESTD_PROXY_CERTIFICATE='/path/to/public_cert.pem'

proxy.default_cache_timeout

Time in seconds that the proxy will cache the results of certain GET requests before making a new request to the EMS server if no Cache-Control header was sent in the request.

This must be equal to or greater than proxy.minimum_cache_timeout.

A value of 0 means results are not cached.

Note: Shorter cache timeouts will cause higher load on EMS servers.

Default value: 5

Example usage:

Command Line

--proxy.default_cache_timeout 5

Config File

proxy:
  default_cache_timeout: 5

Environment Variable

EMSRESTD_PROXY_DEFAULT_CACHE_TIMEOUT=5

proxy.disable_tls

Disable TLS (https) and use unencrypted plaintext (http) connections for proxy clients.

Caution: Disabling TLS means user credentials and tokens will be transmitted in plaintext and potentially expose the proxy to a wide range of attacks and security problems. This is an enormous security risk. Please only disable TLS at the proxy if you are certain you have considered and otherwise addressed the security problems doing so may create.

Default value: false

Example usage:

Command Line

--proxy.disable_tls

Config File

proxy:
  disable_tls: true

Environment Variable

EMSRESTD_PROXY_DISABLE_TLS=true

proxy.listeners

List of interface:port pairs the proxy should listen on. The proxy will listen on each interface:port pair specified in the list. If no interface component is specified before the colon, the proxy will listen on the specified port on all available interfaces.

Default value: :8080

Example usage:

Command Line

--proxy.listeners 127.0.0.1:8080,127.0.0.1:9090

Config File

proxy:
  listeners:
    - 127.0.0.1:8080
    - 127.0.0.1:9090

Environment Variable

EMSRESTD_PROXY_LISTENERS=127.0.0.1:8080,127.0.0.1:9090

proxy.minimum_cache_timeout

Minimum amount of time, in seconds, the proxy will cache the results of certain GET requests before making a new request to the EMS server. If the Cache-Control header of a request specifies a max-age value smaller than this value, the requested max-age will be ignored and the value of minimum_cache_timeout will be used instead.

This must be equal to or greater than 0.

Note: Shorter cache timeouts will cause higher load on EMS servers.

Default value: 0

Example usage:

Command Line

--proxy.minimum_cache_timeout 0

Config File

proxy:
  minimum_cache_timeout: 0

Environment Variable

EMSRESTD_PROXY_MINIMUM_CACHE_TIMEOUT=0

proxy.name

Name of this instance of the EMS REST Proxy. Used for logging and tracing purposes.

Default value: EMS REST Proxy

Example usage:

Command Line

--proxy.name 'My EMS REST Proxy'

Config File

proxy:
  name: "My EMS Rest Proxy"

Environment Variable

EMSRESTD_PROXY_NAME='My EMS REST Proxy'

proxy.page_limit

For REST API calls which support pagination, the maximum number of items that can be returned in each page of results.

This option may be set to 0 to disable the maximum page size limit.

Note: Large or unlimited page sizes may have an adverse effect on performance.

Default value: 100

Example usage:

Command Line

--proxy.page_limit 1000

Config File

proxy:
  page_limit: 1000

Environment Variable

EMSRESTD_PROXY_PAGE_LIMIT=1000

proxy.private_key

The path to a file containing the private key corresponding to the proxy's client-facing TLS public proxy.certificate. Key files may be in PEM (.pem), DER (.der), or PKCS#12 (.p12 or .pfx) format.

If a PKCS#12 file containing both the public certificate and its private key is used, then either specify the same file for both the proxy.certificate and proxy.private_key options, or leave the certificate option unset and only set the proxy.private_key option.

Default value: none

Example usage:

Command Line

--proxy.private_key /path/to/private_key.pem

Config File

proxy:
  private_key: /path/to/private_key.pem

Environment Variable

EMSRESTD_PROXY_PRIVATE_KEY='/path/to/private_key.pem'

proxy.private_key_password

The password used to decrypt the proxy.private_key if it is encrypted.

Caution: For security purposes, this option is not allowed on the command-line and may only be specified via configuration file or environment variable.

Default value: none

Example usage:

Config File

proxy:
  private_key_password: p4ssw0rd123dontUSEme!

Environment Variable

EMSRESTD_PROXY_PRIVATE_KEY_PASSWORD='p4ssw0rd123dontUSEme!'

proxy.private_key_password_file

Path to a file containing the password used to decrypt the proxy.private_key if it is encrypted.

Caution: Make sure to appropriately protect and limit access to a private key password file if used.

Default value: none

Example usage:

Command Line

--proxy.private_key_password_file /path/to/secret_password.txt

Config File

proxy:
  private_key_password_file: /path/to/secret_password.txt

Environment Variable

EMSRESTD_PROXY_PRIVATE_KEY_PASSWORD_FILE='/path/to/secret_password.txt'

proxy.require_client_certificate

Require clients to use a valid, trusted client certificate when connecting to the proxy.

When enabled, you must also specify a list of client certificates or certificate authorities to trust via the proxy.trusted_client_certificates option.

Default value: false

Example usage:

Command Line

--proxy.require_client_certificate

Config File

proxy:
  require_client_certificate: true

Environment Variable

EMSRESTD_PROXY_REQUIRE_CLIENT_CERTIFICATE=true

proxy.server_check_interval

The proxy periodically checks for connectivity and state changes in the EMS servers it is connected to. This check will be performed every server_check_interval seconds. If the proxy has lost its connection with any EMS servers, it will attempt to reconnect to them during this check.

This must be equal to or greater than 1.

Note: Shorter intervals will cause higher load on EMS servers.

Default value: 5

Example usage:

Command Line

--proxy.server_check_interval 5

Config File

proxy:
  server_check_interval: 5

Environment Variable

EMSRESTD_PROXY_SERVER_CHECK_INTERVAL=5

proxy.session_inactivity_timeout

Amount of time, in seconds, a client session will be allowed to remain inactive before it is automatically closed and cleaned up.

Setting this option to 0 means clients will not time out due to inactivity. Clients will still be subject to timeout from the proxy.session_timeout option if set.

Default value: 3600 (1 hour)

Example usage:

Command Line

--proxy.session_inactivity_timeout 0

Config File

proxy:
  session_inactivity_timeout: 0

Environment Variable

EMSRESTD_PROXY_SESSION_INACTIVITY_TIMEOUT=0

proxy.session_secret

The secret, formatted as a hexadecimal string, used to encrypt session cookies.

Setting this option allows client session cookies to remain valid across proxy restarts. If neither this option or the proxy.session_secret_file option is set, a new random 32-byte session secret will be generated each time the proxy starts.

Note: Secrets should be at least 32 bytes in length, formatted as a hexadecimal string, and should be generated using a secure random number source. One convenient way to generate such a secret is with the openssl tool:

openssl rand -hex 32


Caution: For security purposes, this option is not allowed on the command-line and may only be specified via configuration file or environment variable.

Do NOT use the example secret shown below!

Default value: none

Example usage:

Config File

proxy:
  session_secret: 13750116ff45d53bf68306668134cebe82916d34205d83da23a8d235e56efc88

Environment Variable

EMSRESTD_PROXY_SESSION_SECRET='13750116ff45d53bf68306668134cebe82916d34205d83da23a8d235e56efc88'

proxy.session_secret_file

Path to a file containing the secret, formatted as a hexadecimal string, to use to encrypt session cookies.

Setting this option allows client session cookies to remain valid across proxy restarts. If neither this option or the proxy.session_secret option is set, a new random 32-byte session secret will be generated each time the proxy starts.

If the proxy.session_secret option is set, this option is ignored.

Note: Secrets should be at least 32 bytes in length, formatted as a hexadecimal string, and should be generated using a secure random number source. One convenient way to generate such a secret is with the openssl tool:

openssl rand -hex 32

Caution: Make sure to appropriately protect and limit access to a session secret file if used.

Default value: none

Example usage:

Command Line

--proxy.session_secret_file /path/to/secret.txt

Config File

proxy:
  session_secret_file: /path/to/secret.txt

Environment Variable

EMSRESTD_PROXY_SESSION_SECRET_FILE='/path/to/secret.txt'

proxy.session_timeout

Maximum amount of time, in seconds, a client session will remain open and valid before it is automatically closed and cleaned up.

Setting this option to 0 means there is no maximum session time length. Client sessions may still time out due to inactivity if the proxy.session_inactivity_timeout option is set.

Default value: 86400 (24 hours)

Example usage:

Command Line

--proxy.session_timeout 0

Config File

proxy:
  session_timeout: 0

Environment Variable

EMSRESTD_PROXY_SESSION_TIMEOUT=0

proxy.trusted_client_certificates

List of paths to files containing the public certificates of certificate authorities or individual clients the proxy should trust.

This option is required if proxy.require_client_certificate is true.

Note: Currently only PEM-formatted certificate files are supported for this option.

Default value: none

Example usage:

Command Line

--proxy.trusted_client_certificates /path/to/ca_cert.pem,/path/to/another_public_cert.pem

Config File

proxy:
  trusted_client_certificates:
    - /path/to/ca_cert.pem
    - /path/to/another_public_cert.pem

Environment Variable

EMSRESTD_PROXY_TRUSTED_CLIENT_CERTIFICATES='/path/to/ca_cert.pem,/path/to/another_public_cert.pem'