Skip to main content
Version: 9.2605.x RR

Component configuration

nevisMeta is implemented as a web service in Java.

In case of a standalone deployment, nevisMeta is deployed as a web service including an embedded container.

The following sections describe the deployment types and their configuration.

Standalone​

The standalone deployment type makes use of an embedded container. There is no need anymore to install a separate container application. The standalone deployment mode is the default.

The following configuration files control the behavior of nevisMeta in the standalone deployment type:

Configuration file: env.conf​

  • Remarks:

Administration command and process environment:

  • JAVA_HOME (optional): Use specified JRE/JD. KNo other parameter should be changed.

    • Heap size
    • Garbage collector
    • JSSE configuration properties
    • JNDI configuration properties
    • Temporary Directory
  • JAVA_OPTS: JVM command-line options

The JAVA_OPTS environment variable can be an expression that will be replaced.

Example 1: (using single quotes)

JAVA_OPTS=(
'-server'
'-Djavax.net.ssl.keyStorePassword=${exec:cat /var/opt/pwd.txt}'
)

Example 2: (using double quotes)

JAVA_OPTS=(
"-server"
"-Djavax.net.ssl.keyStorePassword=\${exec:cat /var/opt/pwd.txt}"
)

Old string syntax: (cannot handle spaces in jvm arguments and inline comments)

JAVA_OPTS="-server \
-Djavax.net.ssl.keyStorePassword=\${exec:cat /var/opt/pwd.txt}"

In case if you use double quotes the $ must be escaped. For details, see Standalone nevismeta.properties expression.

Configuration file: nevismeta.properties​

Application, login, server configuration:

  • Back-end configuration options
  • Ninja authentication module configuration options
  • Scaling (concurrency with worker threads)
  • Network settings (host, port, protocol, tls, ...)

Configuration file: log4j.xml​

Logging configuration:

  • Configuration of log levels for for individual components
  • Audit channel (if the file rotation policy or output file needs to be customized)

The configuration files are located here:

  • /var/opt/nevismeta/<instance>/conf

The location of the temporary files of the standalone embedded container can be changed by -Djava.io.tmpdir=/path/to/tmpdir. This property can be provided via JAVA_OPTS in the env.conf.

Environment configuration​

As the first priority, nevisMeta uses the Java installation defined in the file env.conf using the configuration property JAVA_HOME. If the JAVA_HOME property is not defined in the file env.conf, the Java version as defined in the PATH environment variable is used.

To define the usage of a specific Java installation, we recommend setting the configuration property JAVA_HOME in the file env.conf:

Example​

JAVA_HOME=/etc/alternatives/jre_1.8.0

Configuration properties​

You can configure the server of the standalone deployment type through the properties in the file nevismeta.properties.

Server configuration​

  • server.name

    Example: <instance>

  • server.protocol

    Example: https

    Default: https

  • server.port

    Example: 8991

    Default: 8991

  • server.host

    Example: localhost

  • server.max-threads

    Example: 200

    Default: 200

  • server.max-http-header-size

    The maximum size in bytes of HTTP request and response headers.

    Example: 8192

    Default: 8192

  • server.session-timeout

    Example: 6000

    Default: 6000

TLS configuration​

  • server.tls.keystore

    Example: /var/opt/keybox/default/node_keystore.jks

  • server.tls.keystore-passphrase

    Example: keystorepassword

  • server.tls.truststore

    Example: /var/opt/keybox/default/truststore.jks

  • server.tls.truststore-passphrase

    Example: truststorepassword

  • server.tls.require-client-auth

    Example: true

    Default: false

  • server.tls.client-auth

    Example: required

    Default: requested

  • server.tls.verify-hostname (optional)

    Default: false

    If set to true and two-way TLS is enabled (server.tls.client-auth is required or requested), the server verifies that the IP address in the certificate presented by the client matches the IP address of the client. The IP address must be specified in the Subject Alternative Names (SAN) field of the client certificate.

    In the TLS connection setups of Nevis, nevisProxy acts as the client and nevisMeta acts as the server. Hostname verification is a client-side feature by design, which allows for a stricter verification of the server identity. On the server side, there is not enough information: only the IP address of the client can be verified, because its hostname is not available. Using this feature therefore requires nevisProxy to have a fixed IP address, or the client certificates to be regenerated each time the IP address changes.

    It is recommended to leave this property unset or set to false. Instead, enable the client-side hostname verification in the HttpsConnectorServlet of nevisProxy. For more information, see the chapter HttpsConnectorServlet in the nevisProxy reference guide.

  • server.tls.supported-protocols

    Default: TLSv1.3

    If you require TLSv1.2, set server.tls.supported-protocols: TLSv1.2 explicitly. When both protocols are configured, nevisMeta accepts connections using either version.

  • server.tls.cipher-suites

    The default cipher suites depend on the configured protocol:

    For TLSv1.3 (default):

    TLS_AES_128_GCM_SHA256,
    TLS_AES_256_GCM_SHA384,
    TLS_CHACHA20_POLY1305_SHA256

    For TLSv1.2:

    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
    TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,
    TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

    When both TLSv1.3 and TLSv1.2 are configured, the TLSv1.3 cipher suites are included first, followed by the TLSv1.2 cipher suites.

Management server configuration​

  • management.server.host

    Example: 0.0.0.0

    Default: localhost

  • management.server.port

    Example: 9000

    Default: 9005

  • management.healthchecks.enabled

    Example: false

    Default: false

  • management.healthchecks.default-api-version

    Example: 2.0

    Default: 2.0

    API version used if the api-version request header is missing, empty, or unsupported. Allowed values: 1.0, 2.0. An invalid value is ignored with a warning.

  • management.healthchecks.database.active.timeout

    Example: 2s

    Default: 2s

    Time limit of the active database check. Allowed range: 1ms to 60s.

  • management.healthchecks.database.passive.evidence-max-age

    Example: 10s

    Default: 10s

    How long the outcome of a connection pool borrow counts as evidence.

  • management.healthchecks.database.passive.failure-threshold

    Example: 3

    Default: 3

    Number of consecutive failed borrows that make the readiness DOWN. Allowed range: 1 to 256.

  • management.healthchecks.database.passive.pool-wait-threshold

    Example: 5s

    Default: 5s

    Wait time for a pool connection from which the pool counts as exhausted.

Database configuration​

You configure the persistence backend in the file nevismeta.properties. nevisMeta supports MariaDB and PostgreSQL. For setting up the database, see Persistence backend.

  • database.connection.url

    The connection string is handed over to the MariaDB or PostgreSQL JDBC driver without any changes. Define it with the full syntax supported by the database driver. For more information, see MariaDB JDBC and PostgreSQL JDBC. For TLS options, see the MariaDB Connector/J TLS documentation and the PostgreSQL JDBC SSL documentation.

    For TLS connections, MariaDB uses the sslMode parameter (camelCase) and PostgreSQL uses lowercase sslmode with ssl=true.

    Examples:

    • jdbc:mariadb:sequential//host-db1:3306,host-db2:3306/nevismeta
    • jdbc:mariadb://host-db1:3306/nevismeta
    • jdbc:postgresql://host-db1:5432/nevismeta

    One-way TLS examples:

    • jdbc:mariadb://server.sieven.ch:3306/nevismeta?sslMode=verify-ca
    • jdbc:mariadb:sequential//server_1.sieven.ch:3306,server_2.sieven.ch:3306/nevismeta?sslMode=verify-ca
    • jdbc:postgresql://server.sieven.ch:5432/nevismeta?ssl=true&sslmode=verify-ca
  • database.connection.username

    The name of the application user who has access to the schema set in the property database.connection.url. For details, see Overview of database users.

    Example: umet02

  • database.connection.password

    The password of the user set in the property database.connection.username.

    Example: umet02

  • database.connection.schema.owner.username

    The name of the user who is the owner of the schema specified in database.connection.url. For details, see Overview of database users.

    Example: umet01

  • database.connection.schema.owner.password

    The password of the user set in the property database.connection.schema.owner.username.

    Example: umet01

  • database.migration.automatic (deprecated)

    Deprecated since nevisMeta 9.2611.0 and planned for removal in the May 2027 Rolling Release. Use the nevismeta-dbschema image to migrate the database schema. See General upgrade and patching instructions.

    If set to "true", nevisMeta migrates the database schema at startup.

    Example: true

    Default: false

  • database.connection.pool.auto-commit

    Example: true

    Default: true

  • database.connection.pool.connection-timeout

    Expressed in milliseconds.

    Example: 30000

    Default: 30000

  • database.connection.pool.idle-timeout

    Expressed in milliseconds.

    Example: 600000

    Default: 600000

  • database.connection.pool.max-lifetime

    Expressed in milliseconds.

    Example: 1800000

    Default: 1800000

  • database.connection.pool.minimum-idle

    Example: 10

    Default: 10

  • database.connection.pool.maximum-pool-size

    Example: 1000

    Default: 10

  • database.connection.pool.socket-timeout

    Maximum time, in milliseconds, that nevisMeta waits for a single read on a database connection (JDBC socket timeout) before the connection fails and is evicted from the pool. It prevents requests from hanging forever when the connection is silently broken, for example by a firewall or a database failover. 0 disables the timeout. Maximum: 2147483647.

    The limit applies to each network read, not to a whole request. A single database statement that takes longer than this value to return a response fails, which can happen when importing or exporting very large setups. Increase the value if you have large datasets.

    If the JDBC URL (database.connection.url) already contains socketTimeout, the value from the URL is used and this property is ignored. The unit of socketTimeout in the URL depends on the driver: MariaDB uses milliseconds, PostgreSQL uses seconds.

    Example: 300000

    Default: 120000

  • database.connection.pool.tcp-keep-alive

    Enables TCP keep-alive on database connections. Accepted values: true, false. The detection time depends on the operating system settings (about 2 hours by default on Linux), so this does not replace database.connection.pool.socket-timeout. Ignored if the JDBC URL already contains tcpKeepAlive.

    Example: false

    Default: true

  • database.query.timeout

    Maximum execution time of a database query, in whole seconds (1 to 2147483). Any other value makes nevisMeta fail at startup. This does not detect broken connections. Use database.connection.pool.socket-timeout for that.

    Example: 60

    Default: not set (disabled)

  • database.query.plan.cache.size

    The maximum number of cached query plans. For more details, see: https://docs.jboss.org/hibernate/orm/6.4/userguide/html_single/Hibernate_User_Guide.html#hql-query-plan-cache

    Example: 512

    Default: 2048

  • database.query.clause.parameter.padding

    By default, the IN clause expands to include all bind parameter values. However, for database systems supporting execution plan caching, there's a better chance of hitting the cache if the number of possible IN clause parameters lowers. For this reason, we can expand the bind parameters to power-of-two: 4, 8, 16, 32, 64. This way, an IN clause with 5, 6, or 7 bind parameters will use the 8 IN clause, therefore reusing its execution plan. If you want to activate this feature, you need to set this property to true. For more details, see: https://docs.jboss.org/hibernate/orm/6.4/userguide/html_single/Hibernate_User_Guide.html#settings-query

    Example: true

    Default: false

Default data​

During the database initialization, a new Setup with the id 00000000000000000000000000000000 named Default is created if the schema does not contain any tables.

Rest query configuration​

  • includeSoftDeletedStatesPerDefault

    Example: false

    Default: false

Certificate match configuration​

  • client.rest.match-certificate-with-jwks

    Example: false

    Default: true

Standalone - nevismeta.properties configuration file​

The property values related to the server configuration in the file nevismeta.properties can be expressions that will be replaced. The next table shows the available syntax:

SyntaxExampleRemarks
${exec:command}server.tls.keystore-passphrase: ${exec:/var/opt/keys/own/instance/keypass.sh}server.host: ${exec:hostname -f}Executes the given command and uses its output as the value
${env:variablename}server.host: ${env:HOSTNAME}Uses the value of the specified environment variable.

Standalone server command-line interface​

For standalone deployments, the standalone command-line interface (CLI) provides a low level interface to run the server process. It can be used by higher level tools like the administrative CLI (see The administrative command-line interface) or by the user directly.

You can use the standalone CLI to start nevisMeta without involvement of other system components like for example systemd.

You find the standalone script at /opt/nevismeta/bin/nevismeta-server. It provides the following command-line options:

Command-line argumentRemarksDefault
-c, --config PATHRequired. Path to the configuration file nevismeta.properties.No default.
-n, --name NAMEUnique name for that Nevis component node.Overrides the value of the property server.name (in the nevismeta.properties file).See the server.name property in the nevismeta.properties file.
-p, --port PORTThe HTTP/S port to listen on. TLS must be configured in the config file and not as an argument.Overrides the value of the property server.port (in the nevismeta.properties file).See the server.port property in the nevismeta.properties file.
-H, --host HOSTThe HTTP/S host to bind on. By default binds on all IPv4 and IPv6 interfaces.Overrides the value of the property server.host (in the nevismeta.properties file).See the server.host property in the nevismeta.properties file.
--log-config PATHLog configuration file to be used.If a log configuration is provided, nevisMeta will use the given configuration file to determine how logging should behave. If no configuration file is provided, nevisMeta will log to the console by default.Not set.
-V, --versionDisplay version and exit with status code 0.
-h, --helpShow complete and detailed usage and exit with status code 0.

Command-line arguments always prevail over the configuration in the nevismeta.properties file!

Example usage of the standalone CLI​

To start an existing nevisMeta instance named "default" without using systemd to manage the service, set the following commands:

# set working directory
cd /var/opt/nevismeta/default

/opt/nevismeta/bin/nevismeta-server --config /var/opt/nevismeta/default/conf/nevismeta.properties --log-config /var/opt/nevismeta/default/conf/log4j.xml

Creating Self-Signed Certificates with SAN (Subject Alternative Names)​

The following commands generate certificates that can be used in a test environment using a nevisAuth instance with 2-way client authentication and hostname verification enabled.

The keytool command creates a PKCS12 keystore with two SANs (one of type DNS, the other of type IP) and then, using openssl, we generate a PEM file from it, to be used by nevisProxy, for example.

# keytool -genkeypair -keyalg RSA -alias nevisProxyClientCert -keystore /var/opt/certs/keystore.p12 -storetype pkcs12 -storepass password -validity 360 -keysize 2048 -dname "cn=siven.ch,ou=auth,o=o=nevis-security,dc=com" -noprompt -ext SAN=dns:siven.ch,ip:10.0.206.87
# openssl pkcs12 -in /var/opt/certs/keystore.p12 -nodes -out /var/opt/certs/keystore.pem

The following command creates a keystore with two SANs using openssl. Note that both server.key and server.crt are PEM formatted.

openssl genrsa -out /var/opt/certs/ca.key 2048
openssl req -new -x509 -days 365 -key /var/opt/certs/ca.key -subj "/DC=COM/O=nevis-security/OU=auth/CN=siven.ch" -out /var/opt/certs/ca.crt

openssl req -newkey rsa:2048 -nodes -keyout /var/opt/certs/server.key -subj "/DC=COM/O=nevis-security/OU=auth/CN=siven.ch" -out /var/opt/certs/server.csr
openssl x509 -req -extfile <(printf "subjectAltName=DNS:example.com,DNS:siven.ch,IP:10.0.206.87") -days 365 -in /var/opt/certs/server.csr -CA /var/opt/certs/ca.crt -CAkey /var/opt/certs/ca.key -CAcreateserial -out /var/opt/certs/server.crt