Config - Gateway Settings

JSON Configuration for Gateway Settings

The following is an example of the JSON format for the gateway settings.

Gateway Settings

{
  "gateway": {
    "clusterid": 0,
    "segmentid": 0,
    "environmentid": 0,
    "group": "default",
    "iothreads": 4,
    "workerthreads": 20,
    "http2": true,
    "default.host": "",
    "max.entity.size": 67107840,
    "max.header.size": -1,
	"idle.timeout": -1,
	"norequest.timeout": -1,
	"request.parse.timeout": -1,
	"max.parameters": -1,
	"max.headers": -1,
	"max.cookies": -1,
	"max.buffered.request.size": -1,
	"always.add.date.header": true,
    "sslaccelerator": {
      "address": "10.1.2.3",
      "header.client.ip": "X-Forwarded-For",
      "header.client.port": "X-Forwarded-Port",
      "header.secure": "X-SSL-Cipher",
      "header.client.certificate": "X-Client-Cert"
    },
    "accesslog.pattern": "%{REMOTE_ADDR}(:%{REMOTE_PORT}) - "%{REMOTE_USER}" %{TIME_LOGFORMAT} "%{ORIGINAL_REQUEST}" %{HTTP_RESPONSECODE} %{HTTP_BYTESSENT} %{HTTP_RESPONSETIME} "%{HTTP_REFERER}",
    "accesslog.type": "log",
    "accesslog.category": "accesslog",
    "accesslog.directory": "/var/log",
    "accesslog.basename": "accesslog",
    "accesslog.suffix": "log",
    "opentelemetry.enabled": false,
    "opentelemetry.requestmapper": "%{REQUEST_PATH}",
    "opentelemetry.headers": "^authorization",
    "errorpage": "%{script}getBody();\n\nfunction getBody() {\n    var Headers = Java.type('io.undertow.util.Headers');\n    var HtmlEncoder = Java.type('dk.itp.security.utils.HtmlEncoder');\n    \n    var errorInfo = JSON.parse(input);\n    \n    var reqHeaders = context.httpExchange.getRequestHeaders();\n    if (reqHeaders.getFirst('Content-Type') == 'application/json' ||\n        reqHeaders.getFirst('Accept').contains('application/json')) {\n        context.httpExchange.getResponseHeaders().add(Headers.CONTENT_TYPE, 'application/json')\n        \n        var resp = {\n            'status': errorInfo.status,\n            'error': errorInfo.message\n //           ,'diagnostics': errorInfo.exception\n        }\n        \n        return JSON.stringify(resp);\n    }\n    \n    context.httpExchange.getResponseHeaders().add(Headers.CONTENT_TYPE, 'text/html')\n    \n    return \"<html><head><title>Error \" + errorInfo.status + \"<\/title><\/head><body>Error \" +\n        errorInfo.status + \" \" + errorInfo.message +\n//        \"<pre>\" + HtmlEncoder.encode(errorInfo.exception) + \"<\/pre>\" +\n        \"<\/body><\/html>\"\n}"
  }
}

Gateway Settings - Configuration via Ceptor Console

Here, you can specify the following settings:

General

Contains general settings for the entire gateway
JSON object key is gateway

Cluster ID

ID between 0 and 255 of the environment this gateway is in.
Cluster ID is part of created session IDs, and refer to which cluster of session controllers the session resides in.

Default value is 0.
JSON key is clusterid

Segment ID

ID between 0 and 255 of the segment this gateway is within.
Segment IDs are part of created session IDs and sessions are only valid within the same segment.

Default value is 0.
JSON key is segmentid

Environment ID

ID between 0 and 255 of the environment this gateway is in.
Environment IDs are part of transaction IDs, some authentication plugins might be restricted to specific environments.

Default value is 0.
JSON key isenvironmentid

Group

Gateway group - gateways in the same group share destination host availability state between them.
A group can usually be thought of as a cluster of gateway servers all being in the same group, often they are located logically in the same place and they will share the same configuration and destination servers. A common setup, is to have one group/cluster of gateways for external users, and another for internal users. If you via the console change the availability status of an individual target server, that change will be broadcast to all other gateways member of the same group.

Default value is the string "default"
JSON key is group

IO Threads

Number greater than 2.
Number of IO threads to share connections between - usually set to twice the number of CPU cores. This is the number of threads which are available to process IO events, such as receiving data. One IO thread handles a large number of socket connections both from clients and towards target servers. IO threads must not be blocked e.g. waiting for session controller replies or similar, so any blocking work is handed off to individual Worker threads. However dispatching work to worker threads have a scheduling cost so performance is better if an IO thread can handle it.
But, blocking is strictly not allowed for IO threads.
If you have performance issues, but lots of available CPU, you can try to increase the number of IO threads.

Default value is 2 times the number of CPU cores
JSON key is iothreads

Worker Threads

Number greater than 2.
Number of worker threads PER IO THREAD to handle blocking tasks - each IO thread has this number of worker threads available to do blocking work - this could be e.g. to create a new session in the session controller, or to execute an authorization script to check if the a request is permitted access or not.

Default value is 20.
JSON key is workerthreads

POST max size

Maximum size of a request body, e.g. in a POST or PUT request. often called "POST max size" although it also applies to other HTTP request methods.
You should change this to a sensible value, e.g. 64Mb

Default value is 0 which means unlimited message size, meaning in practice it is limited to amount of available memory for the Gateway process.
JSON key is max.entity.size

Max Header Size

The maximum size of a HTTP header block, in bytes. If a client sends more data that this as part of the request header then the connection will be closed. Undertow currently defaults to 1048576 bytes.

Default: -1
JSON Key: max.header.size

Max Buffered Request Size

The maximum size of a request that can be saved in bytes. Requests are buffered in a few situations, the main ones being SSL renegotiation and saving post data when using FORM based auth. If set to 0 or -1, this setting is not used and Undertow defaults are used instead. Undertow currently defaults to 16384.

Default: -1
JSON Key: max.buffered.request.size

Idle Timeout

The amount of time a connection can be idle for before it is timed out. An idle connection is a connection that has had no data transfer in the idle timeout period. Note that this is a fairly coarse grained approach, and small values will cause problems for requests with a long processing time. If set to 0 or -1, this setting is not used and Undertow defaults are used instead.

Default: -1
JSON Key: idle.timeout

Request Parse Timeout

How long a request can spend in the parsing phase before it is timed out. This timer is started when the first bytes of a request are read, and finishes once all the headers have been parsed. If set to 0 or -1, this setting is not used and Undertow defaults are used instead.

Default: -1
JSON Key: idle.timeout

Max Parameters

The maximum number of query parameters that are permitted in a request. If a client sends more than this number the connection will be closed. This limit is necessary to protect against hash based denial of service attacks. If set to 0 or -1, this setting is not used and Undertow defaults are used instead. Undertow currently defaults to 1000.

Default: -1
JSON Key: max.parameters

Max Headers

The maximum number of headers that are permitted in a request. If a client sends more than this number the connection will be closed. This limit is necessary to protect against hash based denial of service attacks. If set to 0 or -1, this setting is not used and Undertow defaults are used instead. Undertow currently defaults to 200.

Default: -1
JSON Key: max.headers

Max Cookies

The maximum number of cookiesthat are permitted in a request. If a client sends more than this number the connection will be closed. This limit is necessary to protect against hash based denial of service attacks. If set to 0 or -1, this setting is not used and Undertow defaults are used instead. Undertow currently defaults to 200.

Default: -1
JSON Key: max.cookies

Enable HTTP/2

Check to enable support for the HTTP/2 protocol on all http/https listeners - this support includes the TLS ALPN protocol for negotiating SSL connections, and upgrading a connection using HTTP/2 Upgrade.
Note that this setting affects all defined listeners.

Default: true
JSON key: http2

Default hostname

Default hostname to use if no HOST header in request.
If not set or empty, defaults to IP of running server.
Note that you might want another default to avoid revealing internal IP - e.g. if client sends request without HOST header and you redirect to https://${HTTP_HOST} since that will reveal internal IP

Default: empty - which means using IP address of server
JSON key: default.host

Always Add Date Header

If the server should add a HTTP Date header to all response entities which do not already have one. The server sets the header right before writing the response, if none was set by other means.
Note that this setting affects all defined listeners.

Default: true
JSON key: always.add.date.header

Error Page Script

Allows you to specify a script which generates content for an error page body. If e.g. no destination servers can be reached, or if a request times out, an error response is generated and sent by the gateway. By default, no response body is included but by using this script you can control which response body is sent, and what it looks like.

See Plugins for more information and an example of a script generating both JSON and HTML response bodies.

Default: none
JSON key: errorpage

SSL Accelerator

Contains settings specific for SSL accelerators deployed in front of the gateway.
Note that it is extremely important when using HTTP headers to forward this information that the SSL accelerator is configured to remove headers from its clients and replace them with its owns to avoid the risk of someone spoofing headers by e.g. sending a fake SSL client certificate in an HTTP header.

JSON object key is sslaccelerator located within the gateway object.

IP addresses

Semicolon-separated list of IP addresses or hostnames of SSL accelerators. When requests originate from these IPs, the headers below are used.

Default: none
JSON key is address

IP addresses (pattern)

Wildcard pattern (prefix with {regex} if you want to use a regular expression) of IP addresses to match - e.g. 172.16.* or 10.* - use this - e.g. in AWS if your SSL accelerator uses a wide number of client IP addresses where pattern matching is easier that listing each IP.

Default: none
JSON key is address.pattern

Client IP HTTP Header

Name of HTTP Header containing forwarded client IP from SSL accelerator - if present, the value of this header will be used as client IP address instead of the client IP on the socket connection which is then assumed to be from a proxy/SSL accelerator. A semi-standard is to use the header name X-Forwarded-For. If the value contains a list of IP addresses, the last entry will be used.

Default: none
JSON key is header.client.ip

Client Port HTTP Header

HTTP Header containing forwarded client source TCP Port from SSL accelerator. A semi-standard name to use is X-Forwarded-Port. If this header is specified, the value will be used as the source port instead of the one taken from the socket. This is useful in cases where clients are hiding behind NAT gateways, and multiple different clients share the same IP address - in this case you will need the client port number to identify the remote. Note that this port number is forwarded in the Request specific part of the session ID (see Sessions for an explanation) but it does require the new session ID format to be used since the old one has not spaced enough for this information.

Default: none
JSON key is header.client.port

Client Certificate Header

HTTP Header containing forwarded SSL client certificate in base64 encoded PEM format from SSL accelerator.

Default: none
JSON key is header.client.certificate

Secure HTTP Header

Name of HTTP request header.
If this header is present in the request from the SSL accelerator, the request is considered secured, no matter if https is used or not between the SSL accelerator and the Ceptor gateway. This is used e.g. to determine if request was using http or https - and is used to determine if session cookies can have the "secure" flag added to them or not.

Default: none
JSON key is header.secure

Access Log

The following settings control access logging.

JSON object key: The properties are located in the gateway object.

Definition

Access log definition / pattern - defines what is logged within the access log, here you should use the macros documented in Scripts and Macros - if you wish to include additional information in the access logs, you can specify it here.

Default is: %{REMOTE_ADDR}(:%{REMOTE_PORT}) - "%{REMOTE_USER}" %{TIME_LOGFORMAT} "%{ORIGINAL_REQUEST}" %{HTTP_RESPONSECODE} %{HTTP_BYTESSENT} %{HTTP_RESPONSETIME} "%{HTTP_REFERER}"
JSON key is: accesslog.pattern

Type

Access log type - file or log - if log, category decides which log category / logger name is used when logging. When set to file, the file will roll every day at midnight. Setting it to a file will perform better than log, since the file is then written directly to disk using memory mapped IO where with a log the log request has to go via the logging framework.

Default is: log
JSON key is: accesslog.type

Output directory

When type is set to file, this specifies which directory the access log files are stored within.

Default: none
JSON key is accesslog.directory

Base name

When type is set to file, this is the base name of the logfile.

Default is accesslog
JSON key is accesslog.basename

Suffix

When type is set to file, this is the suffix (will be prefixed with .)

Default is log
JSON key is accesslog.suffix

OpenTelemetry

These settings affect the OpenTelemetry integration.

This requires minimum Ceptor 6.5.10

Enable OpenTelemetry

Enable OpenTelemetry support - if set, OpenTelemetry API is called for incoming and outgoing requests.

Note that if you use OpenTelemetry Agent, you should disable automatic Undertow instrumentation, since the default instrumentation is inferior and does not provide full information we cannot rely on it so disabling default is needed to avoid double entries.

Also note that if you use Dynatrace, then you need to go into settings, and choose Server-side service monitoring → Span context propagation and here add an item with the matcher "Span equals client" otherwise context propagation will not work.

Details in the screenshot below

Default is false
JSON key is opentelemetry.enabled

Request Path

When creating traces, this mapper controls what text to use - it can be use to replace e.g. individual path entries with "Images", "Javascript" or other types or you can choose to otherwise override or shorten the path.

By default the full path will be provided

Default is %{REQUEST_PATH}
JSON key is opentelemetry.requestpathmapper

HTTP Headers

Chooses which HTTP (request or response) headers to included in the trace taken

Default is ^authorization - meaning everything except for the authorization header.
JSON key is opentelemetry.headers