Configuration

This document covers the following topics:

How Configuration is Applied

Configuration is provided in a JSON file and can be overridden by environment variables:

  1. Defaults built into the server.

  2. Values from the JSON configuration file.

  3. Values from environment variables — these have the highest precedence.

The mechanism that applies depends on how the server is started:

  • As a service - The settings come from <installdir>/Natural/INSTALL/npienv, which sets the NATSUBSRV_* variables. Change them there and restart the service. Commented-out entries in that file show the optional settings.

  • Started manually - Use a JSON file and reference it with config=.

  • As a container - As described in the readme.txt of the container use case.

Keep the two apart. Because environment variables take precedence, a NATSUBSRV_* variable that is set in your shell overrides the corresponding value in your JSON file.

All parameters are optional; each one falls back to its default. Invalid values are not silently corrected: the server reports a configuration error and does not start. Changing the configuration requires a restart of the server.

Example of Configuration File

{
  "port": 2600,
  "appDataDir": "/srv/natsubsrv/appdata",
  "numberOfWorkers": 4,
  "workerQueueSize": 10,
  "socketTimeout": 3000,
  "closeDrainTimeout": 250,
  "maxMessageSize": 1024,
  "naturalCommandLine": "parm=NATPARM",
  "loggingMode": "INFO",
  "enableSyslog": true,
  "metrics": false,
  "metricsInterval": 15,
  "tracesStoredPerWorker": 1000,
  "natRpc39IntervalInSeconds": 0,
  "tlsKey": "/path/to/tls.key",
  "tlsCertificate": "/path/to/tls.crt",
  "pamService": "natsubsrv",
  "keepSecuritySession": false,
  "backoutTransactionPerRequest": true,
  "closeWorkFilesPerRequest": true,
  "nscStartupLogonRetryCount": 0,
  "nscStartupLogonRetryWaitSeconds": 5
}

Configuration Reference

The following parameters are available:

JSON Parameter Environment Variable Values / Default Description
port NATSUBSRV_PORT TCP port / 2600 Port the server listens on.
appDataDir NATSUBSRV_APP_DATA_DIR absolute path / $HOME/.natsubsrv/<port> Base directory for runtime data.
unixDomainSocketPath NATSUBSRV_UDSPATH absolute path / <appDataDir>/run/natsubsrv.sock Socket used for internal communication.
numberOfWorkers NATSUBSRV_WORKERS ≥ 1 / 1 Number of parallel worker processes.
workerQueueSize NATSUBSRV_QUEUESIZE ≥ 1 / 10 Number of connections queued per worker.
socketTimeout NATSUBSRV_TIMEOUT ms / 3000 Timeout for reading and writing request data.
closeDrainTimeout NATSUBSRV_CLOSE_DRAIN_TIMEOUT ms, min. 10 / 250 Wait time for the client to close the connection.
maxMessageSize NATSUBSRV_MAX_MESSAGE_SIZE 1–10240 MB / 1024 Maximum accepted size of a single request.
naturalCommandLine NATSUBSRV_NATARG text / empty Startup parameters passed to Natural.
natRpc39IntervalInSeconds NATSUBSRV_NATRPC39INTERVAL seconds, 0 = off / 0 Interval for the periodic SYSTEM/NATRPC39 call.
loggingMode NATSUBSRV_LOG See Logging / INFO Log level.
enableSyslog NATSUBSRV_SYSLOG true/false / false Also writes log messages to syslog.
metrics NATSUBSRV_METRICS true/false / false Enable metrics and trace collection. See Metrics for how the data can be read out.
metricsInterval NATSUBSRV_METRICS_INTERVAL seconds / 15 Interval at which workers report metrics.
tracesStoredPerWorker NATSUBSRV_TRACES_PER_WORKER ≥ 1 / 1000 Number of traces buffered per worker.
tlsKey NATSUBSRV_TLSKEY path / off TLS private key. See Transport Security (TLS/SSL).
tlsCertificate NATSUBSRV_TLSCERT path / off TLS certificate. See Transport Security (TLS/SSL).
pamService NATSUBSRV_PAM service name / off PAM service used for authentication.
keepSecuritySession NATSUBSRV_KEEP_SECURITY_SESSION true/false / false Keep the Natural Security session between requests.
backoutTransactionPerRequest NATSUBSRV_BACKOUT_TRANSACTION_PER_REQUEST true/false / true Back out the open transaction of every database at the start of a request.
closeWorkFilesPerRequest NATSUBSRV_CLOSE_WORK_FILES_PER_REQUEST true/false / true Close the work files the previous request left open.
nscStartupLogonRetryCount NATSUBSRV_NSC_STARTUP_LOGON_RETRY_COUNT 0 = off, or 2–10 / 0 Natural Security logon attempts at startup.
nscStartupLogonRetryWaitSeconds NATSUBSRV_NSC_STARTUP_LOGON_RETRY_WAIT 1–60 seconds / 5 Wait time between two logon attempts.

Parameters where default is off are inactive until you configure them. To switch such a parameter off explicitly, set it to an empty string, false, 0, or OFF.

Server and Connections

Server Port (port)

TCP port on which Natsubsrv accepts requests from the middleware.

  • Values: a free TCP port — Default: 2600

  • Environment variable: NATSUBSRV_PORT

  • Choosing a value: Leave the default unchanged unless the port is already in use. To run several instances on the same host, give each instance its own port and configure the middleware accordingly. The port is also part of the default appDataDir, so instances on different ports keep their runtime data separate.

Request Timeout (socketTimeout)

Limits how long the server waits for request data from the client and for the response to be accepted.

  • Values: milliseconds — Default: 3000

  • Environment variable: NATSUBSRV_TIMEOUT

  • Choosing a value: The default is sufficient for clients in the same network. Increase it if the middleware connects over a high-latency network and requests are aborted although the subprogram itself completes. Note that this timeout covers the network transfer, not the runtime of the subprogram.

Connection Close Timeout (closeDrainTimeout)

Limits how long the server waits for the client to close the connection after the response has been sent.

  • Values: milliseconds, minimum 10 — Default: 250

  • Environment variable: NATSUBSRV_CLOSE_DRAIN_TIMEOUT

  • Choosing a value: 250 ms suits most installations. Use 50–100 ms when the middleware runs in the same data center and the connection rate is high, so workers become available again faster. Increase the value only for WAN connections when the log repeatedly reports a timeout while closing the connection.

Allowing the client to close first ensures that it has received the complete response. Values below 50 ms are accepted but produce a startup warning because remote or TLS clients may not complete the close in time. If the timeout expires, the server logs a warning and closes the connection itself — the response has already been sent, so no data is lost.

Maximum Message Size (maxMessageSize)

Limits the size of a single request that the server accepts.

  • Values: 1–10240 — Default: 1024

  • Environment variable: NATSUBSRV_MAX_MESSAGE_SIZE

  • Choosing a value: Increase the limit if the subprograms exchange large data volumes and requests are rejected as too large. Lower it if your workloads only use small payloads.

The limit protects the server. Each request declares the size of its data buffers and the server allocates memory accordingly. Without an upper bound, a faulty or malicious client could exhaust the server's memory. An oversized request results in an error; the server keeps running.

Workers and Throughput

Number of Workers (numberOfWorkers)

Number of worker processes that handle requests in parallel. Each worker runs its own Natural session.

  • Values: ≥ 1 — Default: 1

  • Environment variable: NATSUBSRV_WORKERS

  • Choosing a value: Base the value on the number of (virtual) CPUs and the workload type — roughly 0.5–1× the number of CPUs for CPU-bound workloads, and up to 3× for I/O-bound workloads such as database access. On an 8-CPU machine, this means about 4 workers for CPU-bound and up to 24 for I/O-bound workloads. Every worker consumes memory for its own Natural session, so increase the value in steps and observe the memory usage.

Worker Queue Size (workerQueueSize)

Number of incoming connections that may wait per worker until a worker accepts them.

  • Values: ≥ 1 — Default: 10

  • Environment variable: NATSUBSRV_QUEUESIZE

  • Choosing a value: Leave the default unchanged. Increase it only for short load peaks when clients are rejected although the workers are not fully utilized. A larger queue does not increase throughput — it only buffers longer, which increases the response times instead of rejecting requests.

Application Data Directory (appDataDir)

Base directory for the runtime data managed by Natsubsrv.

  • Values: absolute path — Default: $HOME/.natsubsrv/<port>

  • Environment variable: NATSUBSRV_APP_DATA_DIR

  • Choosing a value: Leave the default unchanged for test installations. For production installations, configure a dedicated directory that is writable only by the runtime user.

Natsubsrv manages these subdirectories:

<appDataDir>/
  run/     runtime files, for example the socket
  crash/   crash reports

The directories are created at startup with restrictive permissions. If you configure appDataDir explicitly, its parent directory must already exist — Natsubsrv creates only the directory itself and its subdirectories, not an arbitrary chain of parent directories. See File System Security.

Unix Domain Socket Path (unixDomainSocketPath)

Path to the socket used internally between the server and its workers.

  • Values: absolute path — Default: <appDataDir>/run/natsubsrv.sock

  • Environment variable: NATSUBSRV_UDSPATH

  • Choosing a value: Leave the default unchanged. Configure a path of your own only if appDataDir is located on a file system that does not support sockets. Keep the path short as it is subject to the length limit for Unix domain sockets (107 characters on Linux).

Natural Environment

Natural Startup Parameters (naturalCommandLine)

Parameters passed to the Natural session of each worker, for example the parameter module to use.

  • Values: Natural command line, for example parm=NATPARM — Default: empty

  • Environment variable: NATSUBSRV_NATARG

  • Choosing a value: Use the parameter module of the application that provides the subprograms. All workers start with the same parameters.

Adabas User ID (ETID)

Every worker runs its own Natural session, and every session identifies itself to Adabas with an ETID. If neither the parameter module nor the startup parameters set an ETID, Natural derives it from *INIT-USER, which is identical in all workers. They then all open Adabas with the same ETID: the first worker succeeds, the others fail with NAT3048.

With more than one worker, set ETID=$$. Natural replaces $$ with the process ID, so every worker receives an ETID of its own. Set it in the parameter module you use, or in naturalCommandLine, which takes precedence over the parameter module: 

"naturalCommandLine": "parm=NATPARM ETID=$$"

Check the parameter module before changing anything — if it already contains ETID=$$, several workers run without further configuration, and a parameter module that works in one environment can hide a missing ETID in another.

Natural substitutes $$ only when it reads exactly those two characters. Anything else is taken as a literal ETID — an escape sequence that survived into the value as much as a $$ a shell already replaced with its own process ID. Both put all workers back on one shared ETID without an error message. How to write it depends on where it is set:

Set in Write
JSON configuration file "naturalCommandLine": "parm=NATPARM ETID=$$"
Shell or npienv NATSUBSRV_NATARG='parm=NATPARM ETID=$$' — in single quotes, otherwise the shell substitutes its own process ID
Dockerfile ENV NATSUBSRV_NATARG="parm=NATPARM ETID=$$" — $ is the Dockerfile escape for a literal $
Docker Compose NATSUBSRV_NATARG=parm=NATPARM ETID=$$$$ — Compose reads $$ as an escaped $

The startup log shows the command line Natural actually received — check there that it arrived as $$.

User Area Size (USIZE)

For data-intensive subprograms, increase Natural's USIZE (user area size) in your Natural parameters. If USIZE is too small, requests fail with NAT6010: Operation could not be completed. Memory allocation failed.

Periodic SYSTEM/NATRPC39 (natRpc39IntervalInSeconds)

Each worker can run SYSTEM/NATRPC39 periodically to keep its database context alive and avoid NAT3009.

  • Values: seconds, 0 disables the call — Default: 0

  • Environment variable: NATSUBSRV_NATRPC39INTERVAL

  • Choosing a value: Enable this only if you see NAT3009 during idle periods. Choose an interval clearly below the timeout configured in your database — for example, half of it.

The call runs independently in each worker and always under the worker's startup user. SYSTEM/NATRPC39 must be available in your Natural environment (for example, copied from SYSRPC to SYSTEM on FUSER). If it is missing, the worker logs a warning and continues.

On this page