admin-maintenance - NaviServer Maintenance Guide
This guide provides essential information for maintaining and securing NaviServer.
Regular maintenance is essential for ensuring continuous and reliable service. Key tasks include:
Backing up pages and associated files for each virtual server.
Archiving the access log to preserve historical data.
Backing up the server log, especially when verbose logging is enabled.
Backing up Tcl script directories.
Backing up the bin directory, particularly if custom loadable modules are used.
Detailed instructions for each maintenance task are provided in the following sections.
Regular backups of key NaviServer directories are vital to protect against data loss due to filesystem failures.
The pages directory is defined by the PageDir parameter which defaults to the /pages subdirectory under NaviServer home. When multiple servers are running with the same server configuration, the home directory can be determined dynamically based on the Host: header field mass virtual hosting. Keep this in mind, when performing backups.
Schedule regular backups using your preferred method (e.g., nightly cron jobs).
Notice, that NaviServer provides cron-like service by using ns_schedule to run jobs periodically or at certain times in the background. This can ease maintenance since everything can be done in the same environment.
The access log, per default located in logs/access.log, should be backed up frequently. Since NaviServer automatically deletes older logs beyond the configured MaxBackup limit, manual backups are required to retain a complete log history. It is recommended to use timestamp based filenames for logfile rolling (using. e.g.. the day in the filename; see ns_accesslog). This has the advantage, that the filenames are stable, such that on a system-wide backup, the old logfilenames are stable and do not required backups, whenever the log files is rolled.
Regular backups are recommended to preserve this critical information, since the file often reveals intrusion attempts, or provides information, when a certain behavior started, etc. Although the server log generally grows slowly on small sites, verbose logging (e.g., during debugging) can cause rapid expansion, especially when the tracffic is high. For keeping storage requirement low, use a timestamp based filenames for logfile rolling (see ns_log).
Back up the Tcl scripts directories, which include both virtual server-specific scripts (typically in the /tcl subdirectory) and global scripts (in /modules/tcl). Also, ensure that any external files referenced by these scripts are included in your backup strategy.
The /bin directory contains the NaviServer binary and any dynamically loadable modules. If you maintain custom modules, back up both the binaries and their source code to avoid lengthy recompilations after a failure.
The following table outlines the primary directories created during NaviServer installation, the types of files they contain, and the configuration parameters that affect them.
Default directory for storing certificates in PEM format.
Directory containing NaviServer configuration files. Although this is the conventional location, configuration files can reside anywhere if the nsd process is provided with an absolute path.
Typical Files:
.tcl files (e.g., nsd-config.tcl sample-config.tcl openacs-config.tcl}
Directory containing the NaviServer binary, supplementary binaries, and dynamically loadable C modules.
Typical files:
nsd, tclsh, critcl, nsproxy-helper, .so files, etc.
Directory containing header files needed for compiling additional C modules.
Typical files:
.h files
Default directory for storing certificates that fail validation, populated by ns_http. For details, see HTTPS Client Certificate Management.
Directory containing libraries used to build custom components and support extra installed modules.
Typical files:
libnsd.so, libnsdb.so, libnsthread.so, libnsproxy.so, ...
Default directory containing log files and the server PID file.
Typical files:
access.log, server.log, nsd.pid
Contains directories for modules that operate across servers (e.g., "tcl", "nsperm").
Directory containing user, group, and permission files used by the nsperm module for authentication and access control.
Typical files:
passwd, group, hosts.allow, hosts.deny, perms
Default directory for the server’s private Tcl script library.
Typical files:
.tcl files
Default directory where pages and images are stored. Users typically organize content into subdirectories.
Typical files:
.htm, .html, .shtml, .adp, .png, .css, ...
Default directory for the shared Tcl script library, including examples and module-specific scripts. Top-level files in this directory are loaded during startup.
Typical files:
.tcl files
This section provides guidelines to secure your NaviServer installation and protect sensitive data from unauthorized access. Follow these recommendations to minimize vulnerabilities and safeguard your system.
The default management user is nsadmin with a predefined password. NaviServer does not include a built-in, advanced password management system. In production, it is common to integrate NaviServer with external systems (e.g., PAM, Azure, OpenACS) for robust password management.
Alternatively, the nsperm module provides a basic password management solution suitable for small to medium deployments. If nsperm is enabled without customization, it uses a default password and warns you at startup to change the nsadmin password.
You can change the default password using the Tcl command ns_permpasswd or by editing the /modules/nsperm/passwd file directly. For example, the default entry is:
nsadmin:CUdnvgBYocLSI:::::
Replace the password hash (e.g., CUdnvgBYocLSI) with a new hash generated using ns_crypt:
nsd -c % ns_crypt MyNewPassword xx xxhR1Y2vt4OOY
Alternatively, generate the hash using a command-line tool such as Perl:
$ perl -le 'print crypt("MyNewPassword","xx");'
xxhR1Y2vt4OOY
For more details, see Defining Users.
Traditional Unix systems use the "crypt" algorithm to encrypt passwords using a salt. However, with the increasing power of GPUs, these hashes are vulnerable to cracking. Therefore, NaviServer supports stronger password hash algorithms such as Argon2, PBKDF2 (SCRAM), and Scrypt. For more information, refer to ns_crypto. These advanced hashes are, for example, employed in OpenACS for local accounts that require enhanced security.
Effective permission management is critical for securing your server. Authentication is only the first step; comprehensive permission settings ensure that users have appropriate access rights. Systems like OpenACS employ dynamic, role-based permission management for files and directories. If you use the nsperm module, you can implement file-level security in ADP pages and set appropriate permission records as follows:
Maintain identical permission records for both GET and POST requests.
Remove permission records for network publishing operations (PUT, DELETE, MKDIR, BROWSE) for all users except nsadmin.
Note that a permission record for a directory typically applies recursively to all its subdirectories.
Define permission entries in the /modules/nsperm/perms file; the default file includes comments explaining the format.
For more details on setting permissions via the nsperm module, see the Permissions section.
To further enhance security, consider the following recommendations:
Keep NaviServer up to date—use the latest released version.
Consider running NaviServer containerized or within a chroot environment.
For HTTP client requests (ns_http, ns_connchan), do not disable peer certificate validation; ensure that the trusted root certificates (e.g., CAfile ca-bundle.crt) are current.
Regularly review your system log for entries especially with severity Security and any unusual activity.
Enable logging for HTTP client and SMTP requests (via the nssmtpd module) when these services are in use.
When using the nsperm module, ensure that a secure password is set.
When using the nscp module, restrict access to the control port to localhost only (see NaviServer Control Port Guide).
When using the nsstats module, particularly with OpenACS, restrict access to secured administration paths or configure nsperm accordingly.
Limit the installed modules and packages to those essential for your NaviServer deployment.
Monitor resource usage (requests, threads, memory, locks, etc.) using the nsstats module or external tools (e.g., Munin) to detect bottlenecks and ensure availability.
For high security web sites, do no reveal the server implementation and the version information. You might deactivate this information per server in the configuration file:
ns_section ns/server/$server {
...
#
# Configuration of HTTP responses
#
ns_param noticedetail false ;# include server signature in ns_returnnotice commands (errors, redirects, ...)
ns_param noticeadp returnnotice.adp ;# ADP file for ns_returnnotice commands (errors, redirects, ...)
ns_param stealthmode true ;# omit "Server:" header field in responses
}
Scan you site regularly with Vulnerability Scanning Tools.
In case you are deciding to stetup a chroot jail, this section provides basic instructions for setting up NaviServer in a chroot environment (sometimes called a chroot jail).
Running NaviServer in a chroot environment confines the server to a specified directory, making all absolute file paths relative to the new root. Although chroot does not secure file content, it effectively limits access to sensitive files (e.g., passwords, configuration files).
Because a chroot jail must be self-contained, you need to copy all necessary programs, device files, and libraries into the new root directory. Example:
mkdir $root/dev $root/tmp $root/etc chmod 1777 $root/tmp $root/dev; /dev/MAKEDEV generic usema cp /etc/passwd /etc/resolve.conf $root/etc
For Debian/Ubuntu platforms, you can use debootstrap package for setting up the chroot environment.
Once the chroot environment is created, you can run NaviServer with the -r option:
nsd -t nsd.tcl -r $root
Restrict access to Tcl commands and libraries to minimize potential abuse. Although NaviServer runs as a non-privileged user, a compromised account might still execute dangerous Tcl commands. Consider disabling the following if they are not required by your application:
File system related functions, such as open, read, and puts
The NaviServer ns_sock* Tcl functions
The Tcl socket routines
The exec command
The file command, or at least the delete and rename features
The exit command
Database access (e.g. via nsdb).
In Tcl, you can completely disable (delete) unsafe commands to prevent unauthorized execution. But deleting is certainly only an option, when these commands are not used by your application.
admin-install, commandlist, ns_server