Parameters

Type

Details

LogbackOptions

The options for configuring logback.

String

The temporary directory to use.Defaults to the value of System.getProperty("java.io.tmpdir").

int

The seconds to wait after being notified or a file change to allow all file writes to complete.

int

The delay between initiating scans for query config changes.

VertxOptions

The VertxOptions that will be used when creating the Vertx instance.

These values do not usually need to be altered.

HttpServerOptions

The HttpServerOptions that will be used when creating the HTTP server.

The HttpServerOptions#setMaxHeaderSize(int) method should be particularly useful when running behind a proxy that passes large JSON headers.

TracingConfig

The configuration to use for distributed tracing.

boolean

Whether the process will end rather than waiting for requests.This is useful for things such as JIT compilers or CDS preparation.

String

The path to the root of the configuration files.

Persistence

Set the persistence configuration.Persistence is used for both audit and state management of logins. Persistence is optional, without it there will be no audit and login state will be scoped to the current process.

CacheConfig

The configuration of the pipeline cache.

List<String>

The Allowed-Origin-Regex to use for CORS.

Map<String, ProtectedCredentials>

The externalized credentials map.

Credentials that can be used in Source definitions. Externalising credentials is much more secure - the credentials do not need to be committed to the query definition repository and developers do not need access to live credentials.

Kubernetes secrets can be mounted as volumes directly into the externalized credentials map, keeping them out of all configuration.

String

The name of the header that will contain the payload from a token as Json (that may be base64 encoded or not).

If this is used the query engine will not attempt to validate tokens itself, the header will be trusted implicitly. This clearly has security implications and should only be used in a secure environment.

List<DataSourceConfig>

The data sources to use attempt to initialize with the sample data.

The query engine is provided with some example queries that will be deployed to the baseConfigPath on startup if the directory is empty. These sample queries depend upon the target databases being accessible at known locations with known credentials, it is recommended that the provided query-engine-compose.yml file be used set up the database servers within Docker. An attempt will be made to load each data source configured here with the sample data. If loadSampleData is true, and the targets databases can be accessed, then will be loaded with the sample data on startup.

The sample data is loaded using three SQL scripts (one per database engine) and it is perfectly acceptable to run those queries manually instead of using loadSampleData.

Note that the URLs here must be vertx sql URLs, not JDBC URLs, for example: * mysql://localhost:2001/test * sqlserver://localhost:2002/test * postgresql://localhost:2003/test

The leading component of the URL (the scheme) will be used to determine which script to run.

This is unlikely to be useful unless the example compose file is used to start the Query Engine and the different database engines.

JwtValidationConfig

The configuration of the JWT validator.

List<String>

Set the management endpoints (all under /manage) that should be enabled.

Some of the management endpoints provide internal information and should absolutely not be accessible to end-users. This can either be achieved by configuring the ingress appropriately, or by disabling the endpoints.

If no endpoints are specified then all endpoints will be enabled. Whilst this does mean that it is not possible to disable all management endpoints, the "up" endpoint should always be enabled so this should not be a problem. Also, if you really want to you can set a single invalid value for the list of management endpoints, which will result in none of them being enabled (invalid values are silently ignored).

The complete list of management endpoints can be seen by making a request to /manage on a running query engine. The list below is a subset of some of them: * up A simple health endpoint that reports when the service is up (suitable for use by a Kubernetes readiness/startup probe). * health A more complete health endpoint. * prometheus System metrics in Prometheus format. * parameters Dumps the full set of configuration parameters. * envvars Dumps all environment variables. * sysprops Dumps all system properties. * accesslog Reports the past few requests to the system. * inflight Reports all requests made to the system that have not yet completed. * threads Dump stack traces from all threads. * heapdump Download a heap dump.

Unless you are sure that you have secured your /manage endpoint adequately it is strongly recommended that production systems only enable the up; health and prometheus endpoints.

See:

Integer

Set the port that the /manage endpoints should listen on.

In order to help secure the management endpoints they can be run on a secondary port.

If the managementEndpointPort is set to null (the default) the management endpoints will listen on the same port as the API. This is the least secure option (but most convenient for the UI).

It the managementEndpointPort is negative the entire management endpoint setup will be disabled.

See:

String

Set the URL that clients should be using to access the management endpoints.

If set (and managementEndpointPort is positive), requests to /manage will return a JSON object containing a single "location" value with this URL. An HTTP redirect would be more appropriate, but causes issues with client UI behaviour.

Aimed at use cases where a different ingress is required for accessing the management endpoints. The replacement ingress should not usually be accessible to end users.

If managementEndpointPort does not have a positive value any setting of managementEndpointUrl will be ignored.

The value provided must be the full URL to the /manage path.

If not set, and managementEndpointPort is positive, users will have no way to discover the management endpoint URL (which may be the intention).

SessionConfig

Set the authentication configuration of the UI and REST API.

ProcessorConfig

Set the configuration for individual processors.

Some processors have specific configuration options that are not appropriate for configuration in pipeline definitions, they are controlled here.

String

Set the directory to contain cached output.

This is the on-disc caching of stream output, controlled by the cacheDuration value in individual pipelines.

The cache key is based on: * The full request URL. * Headers: * Accept * Accept-Encoding

Note that the fileHash must also match, but isn’t built into the key (should usually match because of the use of the inclusion of full URL).

Note that the default value for the outputCacheDir is probably a bad choice for anything other than the simplest setups.

int

Set the WriteStream buffer size.The amount of data to cache before writing to the output stream.

Pipeline are run in parallel in Verticles, but the actual write to the network has to occur from the HttpServer Context.

If the context hop from the Verticle to the HttpServer context happens too often it will be a drain on CPU cycles , but making it too large will cause the response to stutter.

Recommended Buffer Sizes

BasicAuthConfig

Set the configuration of the handling of requests using basic authentication for data requests.

Note that when the IdP to use for validating the credentials is determined by the OpenID Discovery the path from jwt.issuerHostPath will be appended to the host used to make the request.

boolean

If set to false any basic auth header will be ignored.

String

Get the URL to the minified OpenAPI Explorer JS that is to be used for displaying The API documentation.The default value is (something like) "https://unpkg.com/openapi-explorer@2.2.733/dist/browser/openapi-explorer.min.js".

It is not usually necessary to set this.

String

Set the path to alternative documentation to make available.

Documentation for Query Engine is built in, but documents how to deploy Query Engine and configure its security. In deployments aimed at clients it may be inappropriate to display this information.

This configuration allows for the built in documentation to be replaced with an alternative set aimed at your clients.

The alternativeDocumentation should be a directory containing a hierarchy of HTML files (and supporting resources). The entire hierarchy will be read on startup and then served by the DocHandler - any changes to the contents of the directory will be ignored.

Soft links will not be followed.

The path must be valid (Query Engine will not start if it is not), but may be set to "/dev/null" in which case no documentation will be served at all.

Map<String, String>

The additional data that is made available via the request object.

The uk.co.spudsoft.query.exec.context.RequestContext is made available in both uk.co.spudsoft.query.exec.conditions.ConditionInstance s and various templates (such as and ). By default this context contains information specific to the request, and very little information about the service it is running in.

The entire requestContextEnvironment is also available (with no change) using uk.co.spudsoft.query.exec.context.RequestContext#getEnv , providing a way to add additional environmental information to the context.

String

Set the URL to redirect requests to / to.

By default requests to / redirect to /ui/ and display the Query Engine UI. This is not much use in a path hijack situation, so this allows for the provision of an alternative.

The redirection is literally to the string provided here, so this may either be a full URL or a path (which may be relative or absolute).

uk.co.spudsoft.query.main.SecurityHeadersConfig

Set the security headers configuration.

The following response headers can be configured: * X-Frame-Options - Controls whether the page can be displayed in a frame</li> * Referrer-Policy - Controls how much referrer information should be included with requests</li> * Permissions-Policy - Controls which features and APIs can be used in the browser</li>

All of these values are optional, the default values are secure, but may be too restrictive in some environments.

boolean

Set the enableForceJwt parameter.If true, the path /login/forcejwt can be PUT to create a session based on the the JWT in the message body. This should be secure even in a production environment (because the caller must be still be able to create an acceptable JWT) , but for the sake of safety it defaults to being disabled.