config.json

Top level elements

A current config.json has the following top level values (details below):

  • PORT : 8880 The port for the API
  • ADMINPORT : 8889 commands regarding the runtime, e.g. config and shutdown, should not be exposed
  • METRICSPORT: 8890 Port for Prometeus metrics
  • shutdownkey: key to be passed to trigger a server shutdown. This is hashed out in the “/config” endpoint and only accessible by looking at the relevant config files. Note, this may have been overloaded in a config file in the config.d directory.
  • versions: List of the OpenAPI definition files to load
  • verticles: What verticles to load
  • vertx : Parameters to hand to the start of vert.x, see the vert.x documentation for details
  • metrics: Parameter for vert.x metrics.
  • AllowJwtMail: true to allow email to be sent via a JWT token.
  • CalendarTemplateFileName: location of the mail template.
  • prometheusMetrics: Parameters to hand over to the prometheus task from vert.x.
  • LocalMode: true to use “localhost” as the server name.
  • GodMode: true to allow Local Users defined in the KeepConfig database.
  • DisableEventBusSocket: true….
  • disableDominoLogin:
  • JwtPublicKey:
  • JwtIssuer: Parameter for the issuer name for the JWT tokens generated by Keep.
  • JwtDuration: Parameter for the length of JWT tokens in minutes.
  • maxJwtDuration: IS THIS STILL USED? Not referenced in code.
  • disableJwtExpiryCheck: true for disabling checks against expired JWT tokens.
  • TLSFile: Parameter for TLS file with key for jks, pem or pfx. This is hashed out in the “/config” endpoint.
  • TLSPassword: Parameter for password for jks and pfx key file. This is hashed out in the “/config” endpoint.
  • PEMCert: Parameter for path to Certificate file, if your TLS is PEM format (e.g. LetsEncrypt). This is hashed out in the “/config” endpoint.
  • TLSType: Parameter for format for the TLSFile - “jks”, “pem” or “pfx”.
  • cipher: Parameter for TLS ciphers and whether or not they are allowed.
  • enabledProtocols: Parameter for TLS protocols and whether they are enabled. There are problems currently using TLSv1.3.
  • removeInsecureProtocols: Parameter for insecure protocols and whether they should be removed.
  • jwt: Parameter for JWT providers, algorithm format to be used (e.g. “RS256”) and key or keyfile.
  • jwtAlgorythms: Parameter for valid JWT algorithms in use.
  • CORS: Parameter for sites or subsites from which CORS requests will be accepted.
  • DEBUG: true if debug level logging is enabled.
  • LOG_DIR: Parameter for the directory in which to write logs.

Named elements vs. arrays

All configuration entries are named entries and not arrays, since named entries can be merged in the configuration while arrays only can be overwritten.

Deactivation of entries

The config.json in the Jar has the entry:

    "versions": {
    "v1": {
            "path": "/openapi.v1.json",
            "active": true
        }
    }    

When you supply your own some.json in the config.d directory:

    "versions": {
    "v1": {
            "active": false
        }
    }    

the resulting configuration available to Keep will be:

    "versions": {
    "v1": {
            "path": "/openapi.v1.json",
            "active": false
        }
    }    

In conclusion the v1 will not get loaded This is the mechanism to disable default components without packing the Jar apart

versions

versions has a named list of entries with 2 parameters:

  • path: Path used by getResourceAsStream to load an OpenAPI specification file
  • active: true / false - shall the spec get loaded

The name of the entries needs to match the name used in versions of the RestAPI verticle (See below).

verticles

verticles defines a separate unit of work for particular tags. For the RestAPI verticle, see below. The rest have a standard set of parameters:

  • worker: true / false - to make this a worker verticle. Worker verticles do not run on the event loop thread, but on worker threads from a preconfigured pool of 20 threads. This should be used for heavy-duty verticles.
  • threadPoolName: If a worker verticle should use a dedicated pool, you need to define a thread pool name. By default it will be assigned 10 threads, but this can be overridden with threadPoolSize. If the same threadPoolName is used by multiple verticles, the thread pool is shared across those verticles.
  • threadPoolSize: This will only be used for worker threads with a specific threadPoolName. The default will be 10, but this can be overridden.
  • className: Parameter for the class to use for the verticle. Typically this will be com.hcl.domino.keep.verticles.DominoDefaultVerticle, unless you need to extend that class.
  • tags: Parameter for tags from OpenAPI specs to allocate to this verticle and the package in which to find the NSFHandlers.
  • active: true / false - shall this verticle get loaded.

RestAPI verticle

This is the verticle for managing WebHandlers. “worker”, “threadPoolName”, “threadPoolSize”, “className” and “active” parameters are as for the other verticles. This verticle also has a “versions” parameter. This maps to the top-level “versions” parameter and has the following properties:

  • package: Parameter for the package in which to find the WebHandlers for this version.
  • route: Parameter for the URL path for all OpenAPI endpoints for this spec.
  • defaultClass: Parameter for the class to use for the WebHandler if no specific class is defined. com.hcl.domino.keep.handlers.v1.DefaultJsonHandler will handle any authenticated endpoint that receives either no body or a body with ContentType as “application/json” and responds with ContentType as “application/json”.
  • defaultDatabase: Parameter for the Keep Database to use if there is no query parameter for “db” passed.
  • jsonBodyLimit: Parameter for the maximum size of the request body as JSON.
  • filesBodyLimit: Parameter for the maximum size of the body if including files.

AsyncAgentScheduler verticle

This is the verticle for running async agents - calls to “/run/agent” with “async” set to true in the payload. In Notes Client you can look at KeepAgents.nsf for the asynchronous agents that are running or have run. Most properties are the same as other verticles, but there are two additions:

  • agentDefaultMaxDurationSeconds: Parameter for setting a timeout for asynchronous agents, in seconds. A value of -1 will allow all agents to run to completion without timeout.
  • logFrequencyMs: Parameter for the frequency to log messages of running async agents to the console.

metrics

Sample format is:

{
  "disabledMetricsCategories" : [ ],
  "enabled" : true,
  "jvmMetricsEnabled" : true,
  "labels" : [ "HTTP_METHOD", "HTTP_CODE", "EB_SIDE", "POOL_TYPE" ],
  "registryName" : "default"
}

Details are:
- disabledMetricsCategories, an array of the string values specified in the MetricsDomain Java class, e.g. “vertx.http.server.”.
- enabled, a boolean.
- jvmMetricsEnabled, a boolean.
- labelMatches, a JSON object specifying which labels (i.e. tags) to filter on. The JSON object contains:
- domain, using the string values specified in the MetricsDomain Java class, e.g. “vertx.net.server.”.
- label, a string, the tag to match, e.g. “method”.
- value, a string, the value of the tag to match, e.g. “GET”.
- type of match, either EQUALS or REGEX
- labels, a list of which labels to enable / disable
- registryName, a name for the registry. Leave blank for default.

prometheusMetrics

Sample format is:

{
  "embeddedServerEndpoint" : "/metrics",
  "enabled" : true,
  "publishQuantiles" : true,
  "startEmbeddedServer" : true
}

Details are:
- embeddedServerPoint, path at which to make metrics available.
- enabled, whether or not the Prometheus metrics are enabled.
- startEmbeddedServer, whether or not Prometheus should be started embedded with the vert.x instance. This should be true - we are not starting it separately.
- publishQuantiles, whether histogram quantiles should be delivered.
- embeddedServerOptions, io.vertx.core.http.HttpServerOptions to apply for the Prometheus metrics server. Instead we load these to be consistent with the rest of Keep, but using METRICSPORT.

Overwriting the values

All values can be over written by entries in the config.d directory. The structure needs to be the same as in the default file, but only needs the entries you want to change