This document covers the following topics:
Linux (64-bit).
A working Natural environment. Natsubsrv is not a standalone program, it runs Natural subprograms inside a Natural session and therefore needs a complete Natural installation — nucleus, parameter module, and the libraries holding your subprograms. The Software AG Installer installs Natural together with the server, so you do not install it separately; the two belong together and are versioned together. Before starting the server, make sure the Natural environment itself is usable, for example by running one of your subprograms in a normal Natural session.
A valid Natural API Server license (license file npi11.xml). The license is validated at startup; without a valid license, the server logs an error and terminates. If the license expires within the next 90 days, a warning with the remaining days is written to the log.
Like every other Natural component, Natsubsrv is installed with the Software AG Installer. There is no separate archive to unpack.
Start the Software AG Installer.
Select the Natural API Server product.
Complete the installation. The Natural environment required by the server is installed along with it.
The installation provides:
| File | Location | Used For |
|---|---|---|
npisrv (symbolic link) |
<installdir>/Natural/bin |
Starting the server; resolves to the matching binary. |
natsubsrv, natsubsrvsec |
<installdir>/Natural/bin |
Server binaries without and with Natural Security support. |
natenv
|
<installdir>/Natural/INSTALL |
Natural environment, sourced in service operation. |
npienv
|
<installdir>/Natural/INSTALL |
Server settings for service operation. |
sys/npisrv_sys |
<installdir>/Natural/INSTALL |
Start script run by the service. |
NaturalSubprogramServer, NaturalSubprogramServerNSC |
<installdir>/Natural/docker |
Container use cases, each with a readme.txt. |
Files ending in .tpl next to natenv and npienv
are the installer's templates, not the files in use.
Both binaries are always installed. npisrv is a symbolic link to the one
that matches your installation: natsubsrvsec if Natural Security is
installed, otherwise natsubsrv. Start npisrv rather than a
binary — the link always resolves to the right one. For more information, see
Natural Security.
The server can be started manually, run as a service, or run as a container. All three use the same executable and the same configuration; they differ only in who starts and supervises the process.
By default, Natsubsrv listens on TCP port 2600. See also Server Port (port).
Create a JSON configuration file and reference it at startup. Run this in a shell that already has the Natural environment set up.
<installdir>/Natural/bin/npisrv config=/path/to/natsubsrv.json
Use this for a first check after the installation and for tests. For more information on the contents of the file, see Configuration
The link can also be bypassed and the binary addressed directly, for example when you want to be certain which variant runs:
<installdir>/Natural/bin/natsubsrv config=/path/to/natsubsrv.json
Both binaries are always installed, so either variant can be started deliberately. They take the same arguments and configuration, differ only in Natural Security support. For more information, see the Natural Security.
Always pass config= with an absolute path. If the argument is omitted,
the server looks for a file named natsubsrv.json in the current
working directory. If none is found there, the server does not fail — it starts with
defaults and environment variables only and writes a corresponding message to the log.
A configuration that is silently ignored is hard to detect, so use this fallback only
when you intentionally want the server to start without the configuration.. A path
given with config= that does not exist terminates the server with an
error.
The installer registers a system service and enables it so that the server starts at
boot and is supervised by the operating system. This is the recommended form of
operation for production. Use systemctl disable if you do not want the
automatic start.
The service name is sag<id>npisrv, where <id>
is the Software AG Installer ID of your installation directory. The installer numbers
installation directories consecutively, starting at 1. All daemons of one installation
directory share the same ID — on a machine with several Natural installations, this
indicates the directory to which the daemon belongs. The other Natural services use
the same scheme. Determine the name once:
systemctl list-unit-files 'sag*npisrv*'
The examples below use sag1npisrv:
systemctl status sag1npisrv # check state sudo systemctl start sag1npisrv # start sudo systemctl restart sag1npisrv # apply configuration changes sudo systemctl stop sag1npisrv # stop journalctl -u sag1npisrv -f # follow the log
The service runs the start script
<installdir>/Natural/INSTALL/sys/npisrv_sys. The script sources
natenv for the Natural environment and npienv for the server settings, both from
<installdir>/Natural/INSTALL, and then starts <installdir>/Natural/bin/npisrv. Server settings in service operation therefore come from npienv: change them there and restart the service.
The server writes its log to standard output, so under a service the log is available
through journalctl. Enabling syslog in addition is only necessary if you collect logs centrally.
Container use cases are delivered under <installdir>/Natural/docker, one directory per variant:
NaturalSubprogramServer — without Natural Security
NaturalSubprogramServerNSC — with Natural Security
Each directory contains a readme.txt describing how the container is built and used. Follow that description. In addition:
The image must contain a complete Natural environment, including the parameter module and the libraries holding your subprograms.
Passing the configuration through NATSUBSRV_* environment variables is usually more practical in
containers than mounting a JSON file. See How Configuration is
Applied.
Publish the server port so the middleware can reach the container.
Mount the application data directory as a volume if you want runtime data and crash reports to survive the container.
The delivered images already start Natural with ETID=$$, so every worker gets its own Adabas
ETID. Setting NATSUBSRV_NATARG yourself replaces that value as a whole.
See Adabas
User ID (ETID).
Stopping the container sends SIGTERM, which the server handles as an orderly shutdown. See
Stopping and Restarting.
At startup, Natsubsrv writes the following to the log:
The product version and build information. Keep these values at hand as they are required when reporting a problem.
A one-line summary of the effective configuration. At DEBUG level, each parameter is instead listed on its own line together with its origin — configuration file, environment variable,
or default. That is the quickest way to check whether your settings were actually picked up.
A message once the server listens on its port.
If a configuration value is invalid or a required directory cannot be created, the server terminates during startup with a configuration error naming the affected parameter.
Natsubsrv answers a ping request without requiring authentication and without executing a Natural subprogram. This is the quickest way to check whether the server is reachable — and when a problem occurs, to determine whether Natsubsrv or the middleware is at fault.
The request is a fixed 50-character text, so no client program is needed. Replace
<host> and the port as required.
Without TLS, using Bash only:
exec 3<>/dev/tcp/<host>/2600 && printf 'CALLN110PI0000000000000000000000000000000000000001' >&3 && cat <&3; echo
Without TLS, if nc is available:
printf 'CALLN110PI0000000000000000000000000000000000000001' | nc -w 5 <host> 2600; echo
With TLS:
printf 'CALLN110PI0000000000000000000000000000000000000001' | openssl s_client -quiet -connect <host>:2600 2>/dev/null; echo
The server replies with a 50-character header followed by a JSON object:
{"schemaVersion":"1.0.0","status":"healthy","ctime":1755600000,"machineName":"myhost","port":2600,
"versionNumber":"1.2.3","buildNumber":"123","commitId":"abcdef123456",
"buildDate":"2025-11-25 14:30:00","buildChannel":"..."}
versionNumber and buildNumber are the values to quote
when reporting a
problem.
Notes:
2>/dev/null to see the reason.
Configure the middleware (for example, the Natural OpenAPI Server) with the host and port of Natsubsrv and issue a request from your application.