This document covers the following topics:
Natural Security is in use when it is part of the installation; npisrv
then points to the natsubsrvsec binary. The Natural runtime starts with
auto=on, and the initial session runs under the system user, which must
exist in Natural Security.
Natural Security is enforced only by the natsubsrvsec binary. Since both
binaries are always installed, make sure that service operation and any manual start go
through npisrv or natsubsrvsec — starting
natsubsrv in a Natural Security installation results in a server that
does not apply Natural Security.
Incoming requests must be authenticated with Natural Security credentials, or through PAM when it is configured. Successful PAM authentication can provide single sign-on into Natural Security.
Controls whether the Natural Security session is kept between requests instead of being ended and rebuilt after every request.
Values: true/false —
Default: false
Environment variable:
NATSUBSRV_KEEP_SECURITY_SESSION
Choosing a value: Enable it when many requests arrive for the same user — for example, when the middleware calls Natsubsrv with a single technical user, or with high request rates and short-running subprograms. The fewer distinct users, the larger the benefit; with constantly changing users there is little to gain.
Credentials are still verified by Natural Security on every request; requests with wrong credentials are rejected as before. Only the teardown and reload of the security context is skipped, which makes consecutive requests of the same user considerably faster. Each worker keeps its own session, so with several workers the same user may still need a full logon per worker.
Consider these before enabling:
Audit: Natural Security records one continuous logon per worker instead of a logon/logoff pair per request. If your organization requires per-request records, keep the option switched off.
Idle sessions: While a worker is idle, the session of its last user remains logged on.
Periodic SYSTEM/NATRPC39: If that call is configured,
the kept session is ended beforehand so the call runs under the worker's startup
user. The next request performs a full logon once.
Number of Natural Security logon attempts a worker makes while starting up. The value counts attempts including the first one, so 3 means one logon plus two retries.
Values: 0 (no retry) or
2–10 — Default:
0
Environment variable:
NATSUBSRV_NSC_STARTUP_LOGON_RETRY_COUNT
Choosing a value: Enable it when Natsubsrv and its database are started together and the startup order is not guaranteed, for example in a container environment. Size the retry budget to the time your database realistically needs to become ready — for instance, 4 attempts every 5 seconds for a database that starts within about 15 seconds. Leave it off if the database is always up beforehand.
The wait between two attempts is set with
nscStartupLogonRetryWaitSeconds (environment variable
NATSUBSRV_NSC_STARTUP_LOGON_RETRY_WAIT, 1–60
seconds, default 5). The maximum time a worker spends retrying is
(nscStartupLogonRetryCount − 1) ×
nscStartupLogonRetryWaitSeconds, because there is no wait after the
last attempt.
This option applies only to the startup logon. Logons performed later, when a client request is dispatched, are never retried: a failing request logon is reported to the client with its Natural error.
Only NAT3148 — the database is not active — is retried. All other
errors, in particular wrong credentials, terminate the server immediately because
waiting cannot change the result and Natural Security counts unsuccessful logons and
can lock a user ID.
Consider these before enabling:
Delayed error reporting: If the database is permanently unreachable, the startup error appears only after the full retry budget has elapsed. Keep the budget small so genuine configuration errors are still noticed quickly.
Clients during the retry phase: The server already accepts connections on its TCP port while workers are still retrying, so a middleware connecting in this phase waits and runs into its own timeout instead of being refused right away.
Shutdown: A stop request during a waiting phase is honored within about a second.
Natsubsrv can authenticate users through PAM (Pluggable Authentication Modules). Set
pamService (environment variable NATSUBSRV_PAM) to the
name of a PAM service defined in /etc/pam.d/.
For example, to authenticate with an OIDC-based PAM module, create
/etc/pam.d/natsubsrv:
auth required pam_oidc.so jwks=/path/to/jwks.json issuer=https://your-issuer userClaim=given_name aud=your_audience
Adjust jwks, issuer, userClaim, and
aud for your environment.
PAM authentication uses the user name exactly as supplied, preserving case. For the Natural runtime, the name is converted to uppercase and truncated to eight characters to match Natural's user field constraints.
The connection between the middleware and Natsubsrv can be encrypted with TLS.
Values: tlsKey — path to the private key;
tlsCertificate — path to the certificate —
Default: off
Environment variable: NATSUBSRV_TLSKEY,
NATSUBSRV_TLSCERT
Choosing a value: Enable TLS whenever the middleware and Natsubsrv do not run on the same machine, or whenever the connection crosses a network you do not fully control.
Restrict access to the server port to the hosts running the middleware. The port speaks an internal protocol and answers ping requests without authentication, so it does not belong in an untrusted network.
Both values must be configured together — configuring only one causes a configuration error. Both files must exist and be readable by the runtime user; restrict access to the private key to that user. Supported protocol versions are TLS 1.2 and TLS 1.3. The middleware must be configured for TLS as well.
Natsubsrv protects the directories and files it creates:
appDataDir and its run/ and crash/
subdirectories are created with restrictive permissions and must be writable by
the runtime user only.
Paths are resolved without following symbolic links. A symbolic link within
appDataDir or within the parent directory of the socket path causes
startup to fail.
Paths containing . or .. components are rejected.
The parent directory of the socket must not be world-readable or world-writable.
Crash files are created so that only the runtime user can read them.
Run the server under a dedicated, unprivileged operating system user, and grant that user only the access required for your Natural environment.
