admin-running - Running NaviServer
This manual page provides comprehensive guidance on running NaviServer, a high-performance web server. It covers command-line options, configuration management, service integration, security practices, and operational best practices.
Only one of the options -h, -V, -c, -f, -i, or -w may be used at a time.
-h: Displays a short help message.
-V: Displays the version number and build information.
-c: Runs NaviServer in interactive command mode (similar to tclsh).
-f: Runs NaviServer in the foreground; the server is not forked and logs are output to the console (stderr).
-i: Similar to -f but with stdout directed to the server.log file, suitable for use with systemd.
-w: Runs NaviServer in watchdog mode that automatically restarts the server if it fails.
-d: Runs NaviServer in debugger-friendly mode (ignores SIGINT).
-u: Runs NaviServer under the specified user ID (requires root privileges).
-g: Runs NaviServer under the specified group ID (requires root privileges).
-r directory: Changes the restricted root directory (chroot) to the specified path.
-b prebindinfo: Prebinds to the specified address during startup (e.g., ipaddr:port). Multiple sockets may be bound using the syntax “ipaddr:port#N” (requires SO_REUSEPORT). Multiple prebind addresses might be specified separated by a comma.
-B file: Reads prebind address:port lists from the specified file.
-s servername: Specifies which server to run if multiple servers are defined; by default, the first server is used.
-t configuration-file: Specifies the path to the configuration file.
-T: Tests the configuration file (provided via -t) without starting NaviServer.
Restarting the Server One can restart the server by sendig it a SIGINT signal, or by using the ns_shutdown -restart command. The command has the advantage that one can restart the server from the application. During shutdown, NaviServer tries to terminate all requests and background activity gracefully within a configurable time limit.
Run NaviServer in the background (using fork()) using the configuration file nsd.tcl.
nsd -t nsd.tcl
Run in the foreground, using the configuration file nsd.tcl. This variant is often used for testing, since the system log is shown in the console such one sees quickly debugging output. The server can be quickly stopped by Ctr-C.
nsd -f -t nsd.tcl
Run NaviServer in the foreground, using the configuration file nsd.tcl and sets the chroot directory to /newroot.
nsd -f -t nsd.tcl -r /newroot
NaviServer is packaged with a few sample configuration files, which are in part for documentation purposes, but can be used as well for common setups. The sample configuration file sample-config.tcl is a file containing all of the configuration variables, which are described in this file with their default values
The configuration file nsd-config.tcl can be used for small applications and quick testing. It can be used as well a a blueprint for custom configuration files. This configuration file offers to alter default parameters also from the command line. One can set in the command line before the name of the NaviServer binary variables, which are passed as environment variables to the nsd process. In the following example, we are passing the listening port and IP address by using the nsd_ prefix followed by the name of the configuration variable and the value. The output from server startup shows the configuration variables and which values are taken from the command line or from the default configuration.
% nsd_httpport=8888 nsd_ipaddress=::1 /usr/local/ns/bin/nsd -f -t /usr/local/ns/conf/nsd-config.tcl 2>&1 [-main:conf-] Notice: OpenSSL 3.5.0-dev initialized (pid 39427) [-main:conf-] Notice: random: generating 1 seed [-main:conf-] Notice: using configuration file '/usr/local/ns/conf/nsd-config.tcl' [-main:conf-] Notice: Running nsd with user 'neumann' and group 'staff' [-main:conf-] Notice: setting ipaddress to '::1' from environment variable [-main:conf-] Notice: setting httpport to '8888' from environment variable [-main:conf-] Notice: setting httpsport to '' from default configuration [-main:conf-] Notice: setting nscpport to '' from default configuration [-main:conf-] Notice: setting home to '/usr/local/ns' from default configuration [-main:conf-] Notice: setting hostname to 'localhost' from default configuration [-main:conf-] Notice: setting pagedir to '/usr/local/ns/pages' from default configuration [-main:conf-] Notice: setting logdir to '/usr/local/ns/logs' from default configuration [-main:conf-] Notice: setting certificate to '/usr/local/ns/etc/server.pem' from default configuration [-main:conf-] Notice: setting vhostcertificates to '/usr/local/ns/etc/certificates' from default configuration [-main:conf-] Notice: setting serverprettyname to 'My NaviServer Instance' from default configuration [-main:conf-] Notice: setting reverseproxymode to 'false' from default configuration [-main:conf-] Notice: setting trustedservers to '' from default configuration [-main:conf-] Notice: setting enablehttpproxy to 'false' from default configuration [-main:conf-] Notice: initialized locale en_US.UTF-8 from environment variable LANG ... [...] Notice: listening on [::1]:8888 (sock 18)
It is also possible to add the further configuration variables by extended the Tcl dictionary, which is provided at the begin of the confiration file.
dict set defaultConfig ipaddress 0.0.0.0
dict set defaultConfig httpport 8080
dict set defaultConfig httpsport ""
dict set defaultConfig nscpport ""
dict set defaultConfig home [file dirname [file dirname [info nameofexecutable]]]
dict set defaultConfig hostname localhost
dict set defaultConfig pagedir {$home/pages}
...
When larger modification are required, one can adapt the configuration file to load e.g. further modules, fine tune the settings for configuration values which are not offered via command line configuration values.
NaviServer supports an interactive command mode (invoked with the option -c that launches a Tcl shell for comprehensive testing and debugging.
This mode is intended for development use only; for live administration with shell commands, use the secure control port provided by the nscp module.
Example:
./nsd -c ...
In interactive mode, you can execute commands such as ns_info threads or ns_server requestprocs to inspect server status.
buckel@tulpe:/usr/local/ns/bin> ./nsd -c -u nsadmin -g www -t ../sample-config.tcl
[-main-] Notice: nsmain: NaviServer/4.99.28 (naviserver-4.99.28) starting
[-main:conf-] Notice: nsmain: security info: uid=500, euid=500, gid=100, egid=100
[-main:conf-] Notice: nsmain: max files: soft limit 10240, hard limit 10240
[-main:default-] Notice: nsd/init.tcl [default]: booting virtual server: Tcl system encoding: "utf-8"
[-main:default-] Notice: modload: loading '/usr/local/ns/bin/nssock.so'
[-main:default-] Notice: modload: loading '/usr/local/ns/bin/nslog.so'
[-main:default-] Notice: nslog: opened '/usr/local/ns/servers/server1/modules/nslog/access.log'
[-main:default-] Notice: conf: [ns/server/server1]enabletclpages = 0
[-main:default-] Notice: nsmain: NaviServer/4.99.28 (naviserver-4.99.28) running
[-main:default-] Notice: nsmain: security info: uid=500, euid=500, gid=100, egid=100
[-sched-] Notice: sched: starting
[-driver:nssock:0-] Notice: starting
[-driver:nssock:0-] Notice: nssock:0: listening on [0.0.0.0]:8080
[-driver:nssock:0-] Notice: driver: accepting connections
% ns_info threads
{-driver- -main- 1084140464 0 1119862183 p:0x40037cfb a:0x0}
{-sched- -main- 1082039216 0 1119862183 p:0x4004a09a a:0x0}
{-main- {} 1076887680 1 1119862183 p:0x0 a:0x0}
% ns_server requestprocs
{GET / * inherit ns:fastget a:0x0} {HEAD / * inherit ns:fastget a:0x0} {POST / * inherit ns:fastget a:0x0}
%
This mode is intended for development use. In order to communicate at runtime of the server via a shell, use the nscp module, or the optional nsshell NaviServer module (available separately from GitHub).
NaviServer can be managed as a service using various service management tools. The following approaches are supported:
Most modern Unix-like systems use systemd. A sample systemd unit file for NaviServer might be placed at /etc/systemd/system/nsd.service or /usr/lib/systemd/system/nsd.service:
[Unit] Description=NaviServer After=network.target # After=network.target postgresql.service # Wants=postgresql.service [Service] Type=forking PIDFile=/usr/local/ns/logs/nsd.pid Environment="LANG=en_US.UTF-8" # In case, a site is using Google Perfortools malloc with the system-malloc patch for Tcl: # Environment="LD_PRELOAD=/usr/lib/libtcmalloc.so" ExecStartPre=/bin/rm -f /usr/local/ns/logs/nsd.pid # Standard startup with a non-privileged port (like 8000) ExecStart=/usr/local/ns/bin/nsd -u nsadmin -g nsadmin -t /usr/local/ns/conf/nsd-config.tcl # Startup for privileged port, like 80; the IPv6 address is bound to 2 sockets. # ExecStart=/usr/local/ns/bin/nsd -u nsadmin -g nsadmin -t /usr/local/ns/conf/nsd-config.tcl -b YOUR-IPv4-ADDRESS:80,YOUR-IPv6-ADDRESS:80#2 Restart=on-abnormal KillMode=process [Install] #WantedBy=multi-user.target
For systems using traditional Unix init, add an entry to /etc/inittab to respawn NaviServer:
ns1:345:respawn:/usr/local/ns/bin/nsd -i -u nsadmin -g www -t /usr/local/ns/config.tcl
Daemontools provides an alternative for process supervision, allowing multiple users to manage the server. Note that this requires additional installation and root privileges.
Docker offers a convenient method to deploy or test NaviServer. It provides start modes to provide stable NaviServer servers. Several Docker images for NaviServer are available for common architectures. For more details, visit Docker Hub: NaviServer.
When NaviServer is started with -w, it is running in watchdog mode where it automatically restarts the server if it fails.
Technically speaking the nsd process is forked twice and the first forked instance (the watchdog) controls the second (the worker). The first instance reacts on exit codes and signals caught during the watch and correspondingly restarts the second instance.
WARNING: Running NaviServer as root is not recommended for web server usage.
Running NaviServer as root should be avoided except in exceptional cases where NaviServer is used as an application rather than a traditional web server. If necessary, run NaviServer as root using the -u switch:
./nsd -f -u root -g www -t ../sample-config.tcl
Startup logs will indicate that NaviServer is running with uid=0.
Running NaviServer inside a chroot environment confines the server to a specified directory, limiting its access to the underlying filesystem. Although chroot does not secure file content, it effectively restricts access to sensitive files (e.g., passwords, configuration files).
NaviServer supports built-in chroot functionality via the -r option. Before running in a chroot, ensure that all necessary files and directories are copied into the new root. Example:
mkdir $root/dev $root/tmp $root/etc chmod 1777 $root/tmp cd $root/dev; /dev/MAKEDEV generic usema cp /etc/passwd /etc/resolve.conf $root/etc
Then start NaviServer with:
nsd -t nsd.tcl -r $root