Configuration

Use this reference to configure module deployment and the settings shared by modules that expose HTTP endpoints. Module-specific settings remain in each module's own reference.

Basic configuration

These configuration properties are common to all modules:

Properties

Name	Description	Default	Mandatory
name	Canonical module name or alias.	""
enabled	Controls whether the module is deployed.	true
instances	Number of instances to deploy with the same configuration.	1
worker	Deploys the instances with worker execution when enabled.	false
group	Deployment group. A configured or built-in module affiliation takes precedence over the fallback.	Module affiliation or "default"
config	Module-specific configuration object.	{}

Example

{
  "name": "Resource",
  "enabled": true,
  "instances": 1,
  "worker": false,
  "group": "resource-group",
  "config": {
    "context_path": "/files",
    "webroot_dir": "/path/to/dir"
  }
}

HTTP configuration

HTTP modules register their routes below an http_context and use either a named server-level listener or local compatibility settings. Prefer a named listener so host, port, TLS, and proxy-header handling are configured once.

Key concepts

Context

Every HTTP module registers a context path through http_context. The selected listener supplies the network host, port, and TLS settings, while the module defines the routes below its context.

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. It must start with /.
2. It must not end with /.
3. It can contain multiple levels separated by /.
4. It can overlap another module's context when their registered routes do not conflict.

Keystores

TLS listeners can use a keystore for their private key and certificate and a truststore for certificates they 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)

The configuration can contain the object inline or reference an externalized object with an expansion expression. Externalization allows the same keystore object to be reused.

Keystore object

Properties

Name	Description	Default	Mandatory
data	Base64-encoded keystore data. Required unless path is used.	""
path	Path from which the keystore is loaded. Required unless data is used.	""
password	Keystore password.	""
type	Keystore type.	"PKCS12"

Example (externalized)

Example of an externalized keystore object:

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

Example (inline)

Example of an inline keystore object:

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

Properties

Note

Configure transport properties with a server-level HTTP listener whenever possible.

This recommendation applies to the following settings:

• Host and port
• TLS, including keystore, truststore, client authentication, and ALPN settings

Properties

Name	Description	Default	Mandatory
http_listener	Name of HTTP listener to use. If not specified, local properties will be used.	""
http_host	Hostname or IP address for the local compatibility listener. *	"0.0.0.0"
http_port	Port of HTTP listener. *	8080
http_options	Additional Vert.x HTTP server options for the local compatibility listener.	{}
http_context	Module context path. All routes registered by a module are relative to this context.	Module-specific
http_allow_forward_headers	Reverse-proxy header policy: "NONE", "FORWARD", "X_FORWARD", or "ALL".	"X_FORWARD"
http_redirect_url	Optional target for redirecting requests to the listener root.	""
http_use_ssl	Enables TLS for the local compatibility listener. 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	Keystore object. The compatibility alias is http_keystore_ref. *	""
http_keystore_path	Path to the keystore. *	""
http_keystore_password	Keystore password. **	""
http_keystore_type	Keystore type. **	"PKCS12"
http_key_alias	Keystore key alias. *	""
http_key_password	Private-key password. *	""
http_truststore	Truststore object. The compatibility alias is http_truststore_ref. *	""
http_truststore_path	Path to the truststore. **	""
http_truststore_password	Truststore password. **	""
http_client_auth	Enables TLS client-certificate authentication. *	false
http_form_attr_limit	Compatibility setting for the maximum size of HTTP form attributes in bytes.	524288
http_request_body_limit	Compatibility setting for the maximum HTTP request-body size in bytes.	2097152
http_webroot_dir	Compatibility setting for the directory from which static files are served.	""
http_overlay_dir	Compatibility setting for a static web-root overlay directory.	""
http_index	Compatibility setting for the index page served when a URL does not name a file.	"index.html"
http_session_cookie_path	Cookie path. When omitted, the module context path is used.	Module context path
http_session_cookie_name	Session cookie name.	"__session"
http_session_timeout_ms	Session timeout in milliseconds.	1800000
http_session_enabled	Enables the HTTP session handler for the context. The compatibility name is use_session.	true
http_session_cookie_http_only	Prevents browser scripts from reading the session cookie. The legacy compatibility name is http_session_cookie_httponly.	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 policy: "STRICT", "LAX", or "NONE".	"NONE"
http_headers	Response headers added to routes in the HTTP context.	{}
public	Allows requests without an authenticated session.	true
http_auth_redirect_url	Redirect location used when authentication is required.	""
use_body_handler	Enables request-body handling for the context.	true
http_enable_file_upload	Compatibility setting that enables file uploads.	false
http_file_upload_dir	Compatibility setting for the upload directory.	"uploads"
http_file_upload_delete_files_on_end	Deletes uploaded temporary files when the request ends.	true
http_cors	CORS configuration object.	{"enabled": true}
http_cors.enabled	Enables CORS handling.	true
http_cors.origins	Array of allowed origins in the form <scheme>://<host>[:<port>].	[]
http_cors.allowed_methods	Array of allowed HTTP methods.	[]
http_cors.allowed_headers	Array of allowed request headers.	[]
http_cors.exposed_headers	Array of response headers exposed to browsers.	[]
http_cors.allow_credentials	Allows credentials in cross-origin requests. Explicit origins are required when this is enabled.	false
http_cors.allow_private_network	Allows cross-origin access from public networks to private networks.	false
http_cors.max_age_secs	Browser cache lifetime for CORS preflight responses.	Handler default
http_csrf	CSRF handler configuration.	{"enabled": true}
http_csp	Content Security Policy configuration.	{"enabled": false}
http_fingerprint	Session fingerprint configuration object.	{"enabled": false}
http_fingerprint.enabled	Enables session fingerprint validation.	false
http_fingerprint.allow_client	Allows a client-supplied fingerprint.	false
http_fingerprint.pattern	Regular expression that validates the fingerprint value.	".{16,}"
http_fingerprint.failure_location	Redirect location used when fingerprint validation fails.	""

Example

{
  "http_listener": "default",
  "http_context": "/example",
  "http_session_enabled": true,
  "http_cors": {
    "enabled": true,
    "origins": ["https://app.example.com"]
  }
}

*) Use a server-level HTTP listener instead of local transport properties when possible.

**) Used only with key- or truststore path configuration in compatibility modules.