Configuration

Module configuration 101

Basic configuration

These configuration properties are common to all modules:

Properties

Name	Description
name	Module name (Mandatory)
enabled	Flag to enable/disable deployment of a module (Default: true)
instances	Number of instances to start. All instances share the same configuration. (Default: 1)
group	Name of module deployment group (Default: "default")
config	Module specific configuration object. (Optional)

Example

{
  "name": "Resources",
  "enabled": true,
  "group": "resource-group",
  "config": {
    "context_path": "/files",  
    "webroot_dir": "/path/to/dir"
  }
}

Http configuration

These configuration properties applies to all HTTP modules.

Key concepts

Context

All HTTP modules are bound to a specific context (http_context), in the form of a path, on a specific address specified as a host (http_host) and a port (http_port). All endpoints provided by a module is located below this path and their names are defined by the module.

Example

 http://192.168.1.23:8080/path/to/api/operation
 ^      ^            ^   ^           ^ 
 |      |            |   |           |
 |      + host       |   |           |
 + scheme            |   + context   |
                     + port          + endpoint   

The following rules apply to the context property:

1. MUST always start with /

2. MUST NOT end with /

3. MAY contain any number of levels, each separated by a /

4. MAY overlap with other modules context

Keystores

If module should use SSL/TLS keystores must be configured containing keys and certificates to use and/or trust.

Two types of key-/truststores are supported:

• Java Keystore format ("JKS")

• PKCS#12 ("PKCS12")

Key-/truststores can be configured in two ways:

• As a keystore object (recommended)

• Using local properties (deprecated, used only for compatibility)

When using an object, the value can be the actual object (inline) or an expansion expression resulting in the actual object (externalized). Path expressions enables externalisation and reuse of keystore objects in multiple locations in the configuration.

Keystore object

Properties

Name	Description
data	Base64 encoded keystore data (Mandatory unless path is used)
path	Keystore path if keystore data is to be read from file. (Mandatory unless data is used)
password	Keystore password
type	(Default: "PKCS12")

Example (externalized)

Example of externalized keystore object configurations.

{
  "keystores": {
    "keystore01": {
      "path": "/path/to/keystore.jks",
      "password": "secret",
      "type": "JKS"
    }
  },
  "modules": [
    {
      "name": "ModuleUsingExternalKeystore",
      "config" : {
        "http_keystore": "${keystores.keystore01}"  
      }
    }
  ]
}

Example (inline)

Example of inline keystore object configuration

{
  "name": "ModuleWithInlineKeystore",
  "config": {
    "keystore": {
      "data": "YmFu...YW4K",
      "password": "secret",
      "type": "PCKS12"
    }
  }
}

Properties

The recommended way to configure HTTP listener properties is by using server level HTTP listeners (see: HTTP Listener).

This recommendation applies to the following settings:

• Host and port

• SSL, including keystore/trustore, client auth and ALPN (HTTP/2) settings

Properties

Name	Description	Default
http_listener	Name of HTTP listener to use. If not specified, local properties will be used.
http_host	Hostname or ip adress of HTTP listener. *	"0.0.0.0"
http_port	Port of HTTP listener. *	8080
http_context	Module context path. All routes registered by a module are relative to this context.	"/"
http_allow_forward_headers	Enable support for reverse proxy forward headers. Supported values: "NONE", "FORWARD", "X_FORWARD", "ALL". Note: This property can also be set for all modules using a global.	"NONE"
http_use_ssl	Flag to enable SSL/TLS for this configuration. Requires a configured keystore.*	false
http_use_alpn	Flag to enable support for ALPN (Application Layer Protocol Negotiation), required for using HTTP/2 over SSL/TLS. *	true
http_keystore	Key store object (alias: http_keystore_ref) *
http_keystore_path	Path to key store. *
http_keystore_password	Key store password **
http_keystore_type	Key store type **	"PKCS12"
http_key_alias	Key store key alias*
http_key_password	Key password*
http_truststore	Trust store object to use (alias: http_truststore_ref)*
http_truststore_path	Path to trust store **
http_truststore_password	Trust store password **
http_client_auth	Flag to enable SSL client authentication*	false
http_form_attr_limit	Max size of HTTP form attributes in bytes.	524288
http_request_body_limit	Max body size of HTTP requests in bytes.	2097152
http_webroot_dir	Directory from where static files are served. (Optional; if not configured static file serving is disabled)
http_overlay_dir	Web root overlay directory. (Optional; if not configured overlay is disabled)
http_index	Name of index page served if no file is specified in url.	"index.html"
http_session_cookie_name	Session cookie name	"__session"
http_session_timeout_ms	Session timeout.	1800000
http_session_cookie_httponly	Session cookie http only flag. Http-only cookies can not be read be scripts in the browser.	true
http_session_cookie_secure	Session cookie secure flag. Secure cookies are only sent over secure (HTTPS) connections.	true
http_session_cookie_same_site	Session cookie SameSite property. Controls how cookies are sent over domain boundaries ("STRICT", "LAX", NONE")	"NONE"
http_enable_file_upload	Enable support for file upload.	false
http_file_upload_dir	Path to dir where uploaded files will be stored.	"file-uploads"
http_auth_redirect_url	Login redirect location. User-Agent will be redirected to this location when authentication is required.	"login"
http_cors	CORS configuration object (optional)
http_cors.enabled	Flag to turn on/off CORS (default: false)	false
http_cors.origins	Array of allowed origins in format: <scheme>://<host>[:<port>].	"*"
http_cors.allowed_methods	Array of allowed methods (optional)
http_cors.allowed_headers	Array of allowed headers (optional)
http_cors.exposed_headers	Array of exposed headers (optional)
http_cors.allow_credentials	Set whether credentials are allowed. Note that user agents will block requests that use a wildcard as origin and include credentials. (optional)
http_cors.allow_private_network	Set whether access from public to private networks are allowed.	false
http_cors.max_age_secs	Set how long the browser should cache the information. (optional)

Example

{
    "http_host": "0.0.0.0",
    "http_port": 8080
}

*) Use of HTTP listener is recommended instead of local properties

**) Only used in combination key-/truststore path configuration