

Choreo Connect Router Configuration Catalog

This document describes all the configuration parameters that are used in ESB Choreo Connect Router.

Instructions for use

1. Open the Choreo Connect configuration file according to the deployment type you are using.

   Click here to see the configuration file location for your Choreo Connect deployment.

   Navigate to the correct folder path and open the config.toml or config-toml-configmap.yaml file based on your Choreo Connect deployment.

   Deployment	Mode	File name	Directory
   Docker Compose	Choreo Connect as a Standalone Gateway	config.toml	<CHOREO-CONNECT_HOME>/docker-compose/choreo-connect/conf/
   Docker Compose	Choreo Connect with MWARE ESB as a Control Plane	config.toml	<CHOREO-CONNECT_HOME>/docker-compose/choreo-connect-with-apim/conf/
   Kubernetes	Choreo Connect as a Standalone Gateway	config-toml-configmap.yaml	<CHOREO-CONNECT_HOME>/k8s-artifacts/choreo-connect/
   Kubernetes	Choreo Connect with MWARE ESB as a Control Plane	config-toml-configmap.yaml	<CHOREO-CONNECT_HOME>/k8s-artifacts/choreo-connect-with-apim/

2. Select the configuration sections, parameters, and values that are required for your use and add them as required. You can click view sample in each of the sections in this page to get the toml format. See the example .toml file given below.

# This is an example .toml file.
[router]
  listenerHost = "0.0.0.0"
  listenerPort = 9090
  securedListenerHost = "0.0.0.0"
  securedListenerPort = 9095
  clusterTimeoutInSeconds = 20
  enforcerResponseTimeoutInSeconds = 20
  # system hostname for system API resources (eg: /testkey and /health)
  systemHost = "localhost"

[router.keystore]
  certPath = "/home/wso2/security/keystore/mg.pem"
  keyPath = "/home/wso2/security/keystore/mg.key"

Router

[router]
  listenerHost = "0.0.0.0"
  listenerPort = 9090
  securedListenerHost = "0.0.0.0"
  securedListenerPort = 9095
  clusterTimeoutInSeconds = 20
  enforcerResponseTimeoutInSeconds = 20
  systemHost = "localhost"
  useRemoteAddress = false

[router] Required

The configurations required for router to route the traffic from different clients to services.

listenerHost

string Required

Default: 0.0.0.0

Host for the listener of Router.

securedListenerHost

string Required

Default: 0.0.0.0

Host for the secured listener of Router.

listenerPort

string Required

Default: 9090

Port for the listener of Router.

securedListenerPort

string Required

Default: 9095

Port for secured listener of Router.

systemHost

string Required

Default: localhost

The system hostname for system API resources (eg: /testkey and /health).

clusterTimeoutInSeconds

integer

Default: 20

The time duration that the Router will wait for an upstream TCP connection to be established.

enforcerResponseTimeoutInSeconds

integer

Default: 20

The timeout for response coming from enforcer to route per API request.

useRemoteAddress

boolean

Default: false

If configured as true, the Router appends the immediate downstream IP address to the x-forward-for header.

Connection Timeout

[router.connectionTimeout]
  requestTimeoutInSeconds = 0
  requestHeadersTimeoutInSeconds = 0 
  streamIdleTimeoutInSeconds = 300
  idleTimeoutInSeconds = 3600

[router.connectionTimeout]

Timeouts managed by the Envoy (Router) connection manager in Choreo Connect.

requestTimeoutInSeconds

integer

Default: 0

The time duration that the Router waits for the request to be received by the upstream, starting from the time it was initiated at the client.

requestHeadersTimeoutInSeconds

integer

Default: 0

The time duration that the Router waits for the request headers to be received by the upstream, starting from the time it was initiated at the client.

streamIdleTimeoutInSeconds

integer

Default: 300

The time duration that the Router will allow a stream to exist with no upstream or downstream activity. This timeout is applied to regular requests/responses as well as streaming requests/responses, and can be overridden by router.upstream.timeouts.routeIdleTimeoutInSeconds

idleTimeoutInSeconds

integer

Default: 3600

The time at which a downstream connection will be terminated if there are no active streams.

Upstream Timeout

[router.upstream.timeouts]
  routeTimeoutInSeconds = 60
  maxRouteTimeoutInSeconds = 60
  routeIdleTimeoutInSeconds = 300

[router.upstream.timeouts]

Timeout settings related to routes. This will be applicable globally for all the APIs in Choreo Connect.

routeTimeoutInSeconds

integer

Default: 60

This is the value that gets overridden by the timeout set at the endpoint level.

maxRouteTimeoutInSeconds

integer

Default: 60

Maximum value accepted as the endpoint level timeout. If a larger timeout is set as the Endpoint Level Upstream Timeout, this value will replace the provided Endpoint Level Upstream Timeout.

routeIdleTimeoutInSeconds

integer

Default: 300

The backend (upstream) connection idle timeout. The time duration that the request’s stream may be idle.

Upstream Health

[router.upstream.health]
  timeout = 1
  interval = 10
  unhealthyThreshold = 2
  healthyThreshold = 2

[router.upstream.health]

Health configuration for upstream clusters.

timeout

integer

Default: 1

Time in seconds to wait for a health check response.

interval

integer

Default: 10

Interval between health checks in seconds.

unhealthyThreshold

integer

Default: 2

Number of unhealthy health checks required before a host is marked as unhealthy.

healthyThreshold

integer

Default: 2

Number of healthy health checks required before a host is marked as healthy.

Router Keystore

[adapter.keystore]
  certPath = "/home/wso2/security/keystore/mg.pem"
  keyPath = "/home/wso2/security/keystore/mg.key"

[router.keystore] Required

The configurations of key store used in Choreo Connect Router

certPath

string Required

Default: /home/wso2/security/keystore/mg.pem

Path of the certificate of the Adaptor

keyPath

string Required

Default: /home/wso2/security/keystore/mg.key

Path of the private key of the Adaptor

CORS

[router.cors]
enabled = true
allowOrigins = ["*"]
allowMethods = ["GET","PUT","POST","DELETE","PATCH","OPTIONS"]
allowHeaders = ["authorization","Access-Control-Allow-Origin","Content-Type","SOAPAction","apikey", "testKey", "Internal-Key"]
exposeHeaders = []
allowCredentials = false

[router.cors]

CORS configurations

enabled

boolean Required

Default:

Possible Values: true, false

Enable CORS configurations globally for all endpoints and APIs deployed in Choreo Connect Router

allowOrigins

list of strings Required

Default:

Allowed origins. set this to [*] allow all origins.

allowMethods

list of strings Required

Default:

The content for the access-control-allow-methods header.

allowHeaders

list of strings Required

Default:

The content for the access-control-allow-headers header.

exposeHeaders

list of strings Required

Default:

The content for the access-control-expose-headers header.

allowCredentials

boolean Required

Default: false

Specifies whether the resource allows credentials.

Upstream Retry

[router.upstream.retry]
  maxRetryCount = 5
  baseIntervalInMillis = 25
  statusCodes = [ 504 ]

[router.upstream.retry]

The configurations for the Choreo Connect router when retrying upstream clusters.

maxRetryCount

integer

Default: 5

Maximum value that can be set as the count within the Endpoint Level Retry configuration.

baseIntervalInMillis

integer

Default: 25

Base interval for the Envoy's (Router's) exponential retry back off algorithm

statusCodes

list of integers

Default: 504

HTTP status codes that would switch on the retry mechanism when an Endpoint Level Retry configuration is set. The list here is used when the retry configuration is set via the MWARE ESB UI or when all given status codes are out of range.

Upstream TLS

[router.upstream.tls]
  minimumProtocolVersion = "TLS1_1"
  maximumProtocolVersion = "TLS1_2"
  ciphers = "ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-SHA, ECDHE-RSA-AES128-SHA, AES128-GCM-SHA256, AES128-SHA, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES256-SHA, AES256-GCM-SHA384, AES256-SHA"
  # the default endpoint certificates
  trustedCertPath = "/etc/ssl/certs/ca-certificates.crt"
  verifyHostName = true
  disableSslVerification = false

[router.upstream.tls]

The configurations for SSL configuration related to the backend connection in Choreo Connect.

minimumProtocolVersion

string

Default: TLS1_1

Possible Values: TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3

Minimum TLS protocol version.

maximumProtocolVersion

string

Default: TLS1_2

Possible Values: TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3

Maximum TLS protocol version.

ciphers

string

Default: ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-SHA, ECDHE-RSA-AES128-SHA, AES128-GCM-SHA256, AES128-SHA, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES256-SHA, AES256-GCM-SHA384, AES256-SHA

If specified, the TLS listener will only support the specified [cipher list]() when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3)

trustedCertPath

string Required

Default: /etc/ssl/certs/ca-certificates.crt

Path to trusted certificates

verifyHostName

boolean Required

Default: true

Possible Values: true, false

Enable/Disable Verifying host name

disableSslVerification

boolean

Default: false

Possible Values: true, false

Disable SSL verification

Downstream TLS

[router.downstream.tls]
  # the default client ca-certificates
  trustedCertPath = "/etc/ssl/certs/ca-certificates.crt"
  mTLSAPIsEnabled = false

[router.downstream.tls]

The configurations for SSL configuration related to the downstream in Choreo Connect.

trustedCertPath

string Required

Default: /etc/ssl/certs/ca-certificates.crt

Path to trusted ca-certificates

mTLSAPIsEnabled

boolean Required

Default: false

Possible Values: true, false

Enable mTLS APIs in Choreo Connect.

Request Payload Passing To Enforcer

[router.payloadPassingToEnforcer]
  passRequestPayload = true
  maxRequestBytes = 10240
  allowPartialMessage = false
  packAsBytes = true

[router.payloadPassingToEnforcer]

The configurations for the Choreo Connect router when passing the request payload to the Enforcer.

passRequestPayload

boolean Required

Default: false

Possible Values: true, false

Enable/Disable request payload passing to the Enforcer.

maxRequestBytes

integer

Default: 10240

The maximum allowed size of a message body in bytes.

allowPartialMessage

boolean

Default: false

If enabled, the request payload will be buffered until the maxRequestBytes is reached.

packAsBytes

boolean

Default: false

If enabled, the request payload will be passed as raw bytes to the Enforcer. Disabling this will provide a UTF-8 string request payload to the Enforcer.

Filters used in the Router

[router.filters]
  [router.filters.compression]
    enabled = true
    library = "gzip"
  [router.filters.compression.requestDirection]
    enabled = false
    minimumContentLength = 30
    contentType = ["application/javascript", "application/json", "application/xhtml+xml", "image/svg+xml", "text/css", "text/html", "text/plain", "text/xml"]
  [router.filters.compression.responseDirection]
    enabled = true
    minimumContentLength = 30
    contentType = ["application/javascript", "application/json", "application/xhtml+xml", "image/svg+xml", "text/css", "text/html", "text/plain", "text/xml"]
    enableForEtagHeader = true
  [router.filters.compression.libraryProperties]
    memoryLevel = 3
    windowBits = 12
    compressionLevel = 9
    compressionStrategy = "defaultStrategy"
    chunkSize = 4096

[router.filters]

Configurations for the filters used in the Choreo Connect Router

Default:

[router.filters.compression] Required

The configurations related to the Choreo Connect Router's compression filter

enabled

boolean Required

Default: false

Possible Values: true, false

Enable/Disable compression filter in Choreo Connect Router.

library

string Required

Default: gzip

Defines compression library used with the compression filter.

[router.filters.compression.requestDirection] Required

The configurations for the Choreo Connect router's request flow HTTP payload data compression

enabled

boolean Required

Default: false

Possible Values: true, false

Enable/Disable data compression for the Choreo Connect request flow.

minimumContentLength

integer

Default: 30

Possible Values: Unsigned integer value less than or equal to 4294967295

Minimum request payload size to consider before applying the data compression

contentType

list of strings

Default: ["application/javascript", "application/json", "application/xhtml+xml", "image/svg+xml", "text/css", "text/html", "text/plain", "text/xml"]

Possible Values: [application/javascript, application/json, application/xhtml+xml, image/svg+xml, text/css, text/html, text/plain, text/xml]

Content type to consider for data compression

[router.filters.compression.responseDirection] Required

The configurations for the Choreo Connect router's response flow HTTP payload data compression

enabled

boolean Required

Default: true

Possible Values: true, false

Enable/Disable data compression for the Choreo Connect response flow.

minimumContentLength

integer

Default: 30

Possible Values: Unsigned integer value less than or equal to 4294967295

Minimum response payload size to consider before applying the data compression

contentType

list of strings

Default: ["application/javascript", "application/json", "application/xhtml+xml", "image/svg+xml", "text/css", "text/html", "text/plain", "text/xml"]

Possible Values: [application/javascript, application/json, application/xhtml+xml, image/svg+xml, text/css, text/html, text/plain, text/xml]

Content type to consider for the data compression

[router.filters.compression.libraryProperties]

The configurations for the Choreo Connect router's compression library

memoryLevel

integer

Default: 3

Possible Values: Value between 1 to 9

Amount of internal memory used by the gzip zlib library

windowBits

integer

Default: 12

Possible Values: Value between 9 to 15

Represents the base two logarithmic of the compressor’s window size

compressionLevel

integer

Default: 9

Possible Values: Value between 9 to 15

Denotes zlib library's compression level. Level 9 provides the highest compression.

compressionStrategy

string

Default: defaultStrategy

Possible Values: gzipFiltered, gzipHuffmanOnly, gzipRLE, gzipFixed

Denotes zlib library's compression strategy. Value can change based on the content type shared with the request. For most of the cases default strategy is the best choice.

chunkSize

integer

Default: 4096

Possible Values: Unsigned integer value less than or equal to 4294967295

Denotes zlib library's next output buffer size in bytes

Top