NaviServer Manual – 5.2.0a
admin-config-params - NaviServer Configuration Parameter Reference
This manual page provides a reference for NaviServer configuration sections and parameters. It is generated from the machine-readable configuration documentation used by NaviServer tooling, such as the nsstats module, and therefore focuses on the meaning, type, default value, and status of individual configuration parameters.
The reference is organized by configuration scope. Global sections describe process-wide settings, per-server sections describe settings below ns/server/$server, and module sections describe parameters accepted by module implementations such as network drivers or server modules.
This page complements admin-config.html, which explains the structure of NaviServer configuration files, common configuration patterns, and deployment examples. Use admin-config.html for conceptual guidance and examples, and this page as a parameter reference.
The ns/parameters section contains global NaviServer settings that are read during startup or used by process-wide subsystems. It includes the installation directory layout, global logging behavior, DNS caching, scheduler and job defaults, startup behavior, and compatibility settings.
Write error.log and access.log asynchronously using writer threads.
Type: boolean
Default: true
Enable SNI
Type: boolean
Default: true
Name of the directory used for loading binary libraries or executables such as nsproxy workers; relative paths are resolved against the home directory
Type: path
Default: bin
Controls ns_cache behavior; full enables normal caching, while none makes ns_cache operations no-ops for conservative cluster deployments
Type: enum
Allowed values: full, none
Default: full
Allow Tcl interpreters to be created concurrently; when disabled, interpreter creation is serialized
Type: boolean
Default: true
Enable DNS result caching
Type: boolean
Default: true
Max in-memory size of DNS cache
Type: size
Default: 500KB
Time to keep entries in cache
Type: time
Default: 60m
Timeout for DNS replies
Type: time
Default: 5s
Global default for the per-server formfallbackcharset setting; used when ns/server/$server formfallbackcharset is not configured
Type: charset
Root directory of the NaviServer installation; used as the base directory for relative paths in ns/parameters
Type: path
Log only jobs longer than this
Type: time
Default: 1s
Number of ns_jobs processed by a worker thread before it exits
Type: integer
Default: 0
Default timeout for ns_job.
Type: time
Default: 5m
Backlog for ns_socket
Type: integer
Default: 32
ANSI-colored log output
Type: boolean
Default: false
Debug messages
Type: boolean
Default: false
Collapse repeated identical log messages
Type: boolean
Default: false
Development messages
Type: boolean
Default: false
Name of the directory used for log files and early startup files such as the pid file; relative paths are resolved against the home directory
Type: path
Default: logs
Use expanded log formatting by placing the message on an indented separate line and adding a blank line after each entry; useful for manual debugging
Type: boolean
Default: false
Number of rotated logs to keep
Type: integer
Default: 10
Informational messages
Type: boolean
Default: true
Color used for log prefixes
Type: enum
Allowed values: black, red, green, yellow, blue, magenta, cyan, gray, default
Default: green
Intensity used for log prefixes
Type: enum
Allowed values: bright, normal
Default: normal
Start timestamps from zero
Type: boolean
Default: false
Suffix appended to logfile name when rolled
Type: string
Rotate log on SIGHUP
Type: boolean
Default: true
Timestamps in seconds
Type: boolean
Default: true
Include thread id in log lines
Type: boolean
Default: true
Timestamps in microseconds
Type: boolean
Default: false
Deltas between log entries in microseconds
Type: boolean
Default: false
Maximum number of Tcl interpreters that may concurrently run update scripts after the server Tcl epoch changes
Type: integer
Default: 1000
Enable tracing of mutex lock operations for debugging locking behavior
Type: boolean
Default: false
Number of task threads
Type: integer
Default: 1
Global default for the per-server outputcharset setting; used when ns/server/$server outputcharset is not configured
Type: charset
Default: utf-8
Path of the file storing the nsd process id; relative paths are resolved against the log directory
Type: path
Default: nsd.pid
Minimum upload size for enabling upload progress tracking; useful for clients that display progress bars for large uploads, while avoiding progress bookkeeping overhead for small requests
Type: size
Default: 0
Reject and log attempts by application code to send output on an already closed or detached connection, such as a second ns_return for the same request; prevents undefined behavior and confusing partial output, while false preserves legacy behavior
Type: boolean
Default: true
Legacy switch for enabling reverse-proxy mode; deprecated in favor of the ns/reverseproxymode section, which provides explicit control over trusted proxies and filtering of forwarded client addresses
Type: boolean
Default: false
Deprecated: Use the ns/reverseproxymode section instead
Sanitize log file names; 0 = none, 1 = full, 2 = human-friendly
Type: integer
Default: 2
Log scheduled jobs that run longer than this
Type: time
Default: 2s
Number of scheduled jobs processed by a scheduler thread before it exits
Type: integer
Default: 0
Maximum time to wait during shutdown for threads and subsystems to terminate cleanly
Type: time
Default: 20s
Log repeated accepts after this threshold
Type: integer
Default: 4
Legacy location for the default thread stack size; when unset or 0, the operating system default is used
Type: size
Deprecated: Use ns/threads stacksize instead
Path of the main server log file; relative paths are resolved against the log directory
Type: path
Default: nsd.log
Serialize Tcl interpreter initialization; usually disabled, but useful when debugging rare initialization crashes or when running under tools such as valgrind
Type: boolean
Default: false
Directory containing NaviServer Tcl library files; relative paths are resolved against the home directory
Type: path
Default: tcl
Directory for temporary files; when unset, NaviServer uses the TMPDIR environment variable or the system default temporary directory, with a trailing slash removed
Type: path
Global default for the per-server urlcharset setting; used when ns/server/$server urlcharset is not configured
Type: charset
Default: utf-8
The ns/fastpath section configures global behavior for static-file delivery. These settings control optional in-memory caching, memory-mapped file I/O, and support for pre-compressed gzip or Brotli variants of static files.
Per-server file locations and directory handling are configured separately in the ns/server/$server/fastpath section.
ns_section ns/fastpath {
# Global fastpath delivery settings.
ns_param cache false
ns_param mmap false
# Serve existing .gz files when the client accepts gzip content.
ns_param gzip_static true
# Refresh stale .gz files by invoking ns_gzipfile.
ns_param gzip_refresh true
ns_param gzip_cmd "/usr/bin/gzip -9"
# Serve existing .br files when the client accepts Brotli content.
ns_param brotli_static true
# Refresh stale .br files by invoking ns_brotlifile.
ns_param brotli_refresh true
ns_param brotli_cmd "/usr/bin/brotli -f -q 11"
# Optional minification before gzip refresh for CSS and JavaScript.
# The commands must read from stdin and write to stdout.
# ns_param minify_css_cmd "/usr/bin/yui-compressor --type css"
# ns_param minify_js_cmd "/usr/bin/yui-compressor --type js"
}
Use for re-compressing
Type: command
Refresh stale .br files
Type: boolean
Default: false
Check for static brotli files
Type: boolean
Default: false
Enable the global fastpath file-content cache for small static files; cached entries are validated against file mtime, size, device, and inode, while recently changed files and files larger than cachemaxentry are served directly
Type: boolean
Default: false
Maximum size of an individual static file stored in the fastpath cache; files above this limit are not cached and are served directly from the filesystem or via mmap when enabled
Type: size
Default: 8KB
Maximum total memory used by the fastpath file-content cache; applies only when the fastpath cache parameter is enabled
Type: size
Default: 10MB
Use for re-compressing
Type: command
Refresh stale .gz files
Type: boolean
Default: false
Check for static gzip file
Type: boolean
Default: false
Command used to minify CSS files when refreshing stale gzip-compressed static files; the command must read CSS from stdin and write minified CSS to stdout
Type: command
Default:
Command used to minify JavaScript files when refreshing stale gzip-compressed static files; the command must read JavaScript from stdin and write minified JavaScript to stdout
Type: command
Default:
Use memory-mapped I/O for serving static files that are not cached; falls back to normal file reading when mmap is unavailable or disabled
Type: boolean
Default: false
The ns/mimetypes section defines MIME type mappings used when NaviServer determines the content type of a file from its filename. These mappings are used when serving static files and by APIs such as ns_guesstype.
NaviServer includes a large built-in MIME type table based on IANA media type registrations. Since lookup is based on filename extensions, real-world usage can still require local overrides when the same extension is used for different content types or when local conventions differ from the built-in defaults.
ns_section ns/mimetypes {
ns_param default text/plain
ns_param noextension text/plain
# Override or add extension-specific mappings.
ns_param .md text/markdown
ns_param .log text/plain
ns_param .wasm application/wasm
}
MIME type used when no more specific mapping is found for a requested file
Type: mime-type
Default: */*
MIME type used for requested files whose names do not have a filename extension; when unset, the value of default is used
Type: mime-type
Default: */*
Maps a filename extension to a MIME content type, overriding or extending the built-in MIME type table
Value type: mime-type
Role of parameter name: mapping key
Cardinality: multiple entries with different parameter names are expected
The ns/reverseproxymode section configures how NaviServer interprets request information when it runs behind trusted reverse proxies or load balancers. These settings affect the effective client peer address used by access logs and APIs that report peer-address information.
This section is about NaviServer being behind a reverse proxy. It is unrelated to the revproxy module, where NaviServer itself forwards requests to backend servers.
Enable reverse-proxy mode for installations behind trusted frontend proxies or load balancers; affects the effective peer address used by access logs and APIs that determine the client peer address
Type: boolean
Default: false
Ignore forwarded client addresses that are not public addresses; useful to avoid recording private or internal proxy-chain addresses as the effective client peer
Type: boolean
Default: false
Trusted proxy addresses or networks whose forwarded client information may be accepted; only proxies listed here should be allowed to influence the effective peer address used by access logs and peer-address APIs
Type: list
The ns/threads section defines process-wide defaults for NaviServer threads. Currently, it is used to configure the default stack size for newly created threads.
Default stack size for newly created threads; when unset or 0, the operating system default is used
Type: size
Default: 0kB
The ns/modules section defines global module instances. Each parameter name is a configuration-defined module instance name, and each value is the module implementation to load. For network drivers, the instance name is used as the final path component of the corresponding configuration section, such as ns/module/http.
ns_section ns/modules {
ns_param http nssock
}
ns_section ns/module/http {
ns_param port 8080
}
Maps a global module instance name to a module implementation name
Value type: module
Role of parameter name: configuration-defined identifier
The ns/servers section defines the virtual servers known to this NaviServer process. Each parameter name is a configuration-defined server name, and each value is a human-readable server description. The server name is used in per-server configuration sections such as ns/server/$server.
ns_section ns/servers {
ns_param default "Default server"
ns_param intranet "Intranet server"
}
ns_section ns/server/default {
ns_param serverdir servers/default
}
Maps a virtual server name to a human-readable server description
Value type: string
Role of parameter name: configuration-defined identifier
Network drivers are NaviServer modules that accept incoming client connections and dispatch requests to configured virtual servers. They are usually loaded globally through the ns/modules section. The parameter name used in ns/modules becomes the module instance name and determines the corresponding driver configuration section.
ns_section ns/modules {
ns_param http nssock
ns_param https nsssl
}
ns_section ns/module/http {
ns_param port 8080
}
ns_section ns/module/https {
ns_param port 8443
ns_param certificate /usr/local/ns/certificates/server.pem
}
In this example, http and https are configuration-defined module instance names. The accepted parameters are determined by the module implementation, such as nssock or nsssl, not by the instance name. Therefore ns/module/http accepts nssock parameters, while ns/module/https accepts nsssl parameters.
The accepted parameters are determined by the module implementation, such as nssock or nsssl, not by the instance name. For example, ns/module/http accepts nssock parameters when the instance http is mapped to nssock.
The nssock module provides the HTTP network driver. It accepts incoming TCP connections, parses HTTP requests, and dispatches them to configured virtual servers.
The parameters documented here are the base network-driver parameters. They control listen addresses and ports, request size limits, socket behavior, keep-alive handling, upload spooling, writer threads, and outgoing bandwidth limits. These base parameters are also accepted by nsssl, which extends nssock with TLS support.
This module can be loaded globally through ns/modules or per-server through ns/server/$server/modules.
ns_section ns/modules {
ns_param http nssock
}
ns_section ns/module/http {
ns_param port 8080
}
For detailed documentation, see nssock.
Maximum number of sockets accepted, default to value of backlog
Type: integer
Local IP address or addresses on which the driver listens; when multiple addresses and ports are specified, NaviServer listens on every address/port combination
Type: list
Listen backlog for this driver, defaults to value of listenbacklog
Type: integer
Size of I/O buffer for reading requests
Type: size
Default: 16kB
Timeout when closing the socket
Type: time
Default: 2s
Default virtual server used for requests accepted by this driver when no more specific host or SNI based mapping selects another server
Type: string
Defer accepting a socket until data arrives where supported by the operating system; can improve performance, but may cause recvwait not to apply while the socket remains in the kernel accept queue
Type: boolean
Default: false
Number of driver threads; values greater than 1 activate reuseport Every driver thread has its own socket queue and its own maxqueuesize limit. Increasing driverthreads therefore also increases the aggregate driver queue capacity.
Type: integer
Default: 1
Additional HTTP response headers sent for responses handled by this network driver; useful for setting driver-wide security headers such as X-Frame-Options, X-Content-Type-Options, and Referrer-Policy
Type: ns_set
Hostname associated with this network driver; when address is not specified, NaviServer resolves this hostname, or the system hostname when unset, to determine the listen address; when hostname remains unset, the first configured or derived address is used
Type: string
Maximum response size for keep-alive; 0 means no limit
Type: size
Default: 0MB
Maximum upload size for keep-alive; 0 means no limit
Type: size
Default: 0MB
Keep-alive timeout
Type: time
Default: 5s
Fallback absolute location URL used when the driver cannot determine a location from a configured host-to-server mapping; normally left unset, since NaviServer computes the location from the request host or local socket address when needed
Type: url
Maximum number of header lines per request
Type: integer
Default: 128
Maximum size for request bodies
Type: size
Default: 1MB
Maximum size of a single header line
Type: size
Default: 8kB
Maximum number of accepted sockets retained concurrently by each driver thread instance. When this limit is reached, the driver instance stops accepting additional sockets until previously accepted sockets are released. The limit applies independently to every instance created by driverthreads; for example, driverthreads 4 and maxqueuesize 1024 provide a nominal aggregate limit of 4096 accepted sockets.
Type: integer
Default: 1024
Spool request bodies larger than this size
Type: size
Default: 0MB
Enable TCP_NODELAY on accepted sockets, disabling Nagle's algorithm; useful for reducing latency, while false leaves Nagle's algorithm enabled
Type: boolean
Default: true
TCP port or ports on which the driver listens; when multiple addresses and ports are specified, the driver listens on every address/port combination
Type: list
Externally visible port advertised by the driver when it differs from the listening port, for example because of container port mapping or network address translation; defaults to the first configured listening port.
Type: integer
Amount of extra data to read ahead, defaults to value of bufsize
Type: size
Timeout for receiving the full request
Type: time
Default: 30s
Enable SO_REUSEPORT explicitly
Type: boolean
Default: false
Timeout for sending responses
Type: time
Default: 30s
Log repeated socket accept operations after this threshold; overrides the global ns/parameters sockacceptlog setting for this network driver
Type: integer
Default: 4
Number of upload spooler threads
Type: integer
Default: 0
Directory for temporary upload files; default to value of tmpdir
Type: path
Buffer size for writer threads
Type: size
Default: 32kB
Maximum outgoing bandwidth per connection in kilobytes per second for responses sent through writer threads; 0 disables driver-level rate limiting, while limits set per connection or per connection pool override this value
Type: integer
Default: 0
Use writer threads for responses larger than this size
Type: size
Default: 1MB
Use writer threads for streaming output such as ns_write
Type: boolean
Default: false
Number of writer threads for this network driver; 0 disables writer threads
Type: integer
Default: 0
The nsssl module provides the HTTPS network driver. It extends the HTTP driver with TLS support, certificate configuration, client certificate verification, OCSP stapling, and optional HTTP/3 Alt-Svc advertisement.
This module also accepts the parameters documented for nssock. The parameters listed below are specific to nsssl.
This module can be loaded globally through ns/modules or per-server through ns/server/$server/modules.
ns_section ns/modules {
ns_param https nsssl
}
ns_section ns/module/https {
ns_param port 8443
ns_param certificate /usr/local/ns/certificates/server.pem
}
For detailed documentation, see nsssl.
Certificate chain file in PEM format; relative paths are resolved against the certificates directory below the home directory
Type: path
OpenSSL cipher list used for TLS connections; controls the allowed cipher suites for protocols where OpenSSL uses the traditional cipher-list syntax
Type: string
OpenSSL TLS 1.3 cipher suite list for this TLS-enabled driver; use ciphers for TLS 1.2 and older protocol versions
Type: string
Trusted CA certificates file for client certificate validation; relative paths are resolved against the home directory
Type: path
Trusted CA certificates directory for client certificate validation; relative paths are resolved against the home directory
Type: path
Client certificate request mode
Type: enum
Allowed values: none, request, require
Default: none
Advertise HTTP/3 availability via the Alt-Svc response header when an HTTP/3 driver is active and linked to this TLS driver; no header is added when Alt-Svc is already set
Type: boolean
Default: false
Add the persist flag to the HTTP/3 Alt-Svc advertisement, indicating that clients may keep using the advertised HTTP/3 alternative across network changes
Type: boolean
Default: false
Private key file in PEM format; optional when the private key is included in the certificate file; relative paths are resolved against the certificates directory below the home directory
Type: path
OCSP recheck interval
Type: time
Default: 5m
Enable OCSP stapling
Type: boolean
Default: false
Enable verbose OCSP stapling logging
Type: boolean
Default: false
Colon-separated string of TLS/SSL protocol versions to disable for this driver. The traditional nsssl syntax uses exclusions prefixed with "!", for example "!SSLv2:!SSLv3:!TLSv1.0:!TLSv1.1". When omitted, the default disables SSLv2, SSLv3, TLSv1.0, and TLSv1.1. When explicitly set to the empty string, NaviServer applies no protocol restriction and leaves the effective protocol set to OpenSSL and the system crypto policy.
Type: string
Default: !SSLv2:!SSLv3:!TLSv1.0:!TLSv1.1
TLS key log file used for writing TLS session secrets for debugging or protocol analysis; when set to a non-empty value, the file is opened in append mode, and when set to an empty value, NaviServer uses the SSLKEYLOGFILE environment variable. The file contains sensitive material that can decrypt captured TLS traffic
Type: path
Helper script used to obtain the password for the server private key when the key is encrypted in the PEM file
Type: script
Directory for virtual-host certificates of the default server
Type: path
The quic module provides the experimental HTTP/3 network driver based on QUIC. It is part of NaviServer 5.1, but requires OpenSSL 4.0 or newer. The driver uses an existing HTTPS driver configuration as a fallback for shared network-driver and TLS settings. Values specified in the HTTP/3 section override the corresponding HTTPS values, allowing TCP and UDP drivers to use different transport and thread settings.
HTTP/3 support is disabled by default. The current implementation is functional but still experimental and not yet recommended for production use. More testing, leak checking, load testing, and hardening are still needed.
This module also accepts the parameters documented for nsssl. The parameters listed below are specific to quic.
This module should be loaded globally through ns/modules.
ns_section ns/modules {
ns_param https nsssl
ns_param h3 quic
}
ns_section ns/module/https {
ns_param port 8443
ns_param certificate /usr/local/ns/certificates/server.pem
# Extra parameters specific for HTTP/3
# ns_param h3advertise true
# ns_param h3persist false
}
ns_section ns/module/h3 {
ns_param https ns/module/https
# ns_param driverthreads 2
# ns_param writerthreads 1
# ns_param recvbufsize 8MB
# ns_param sendbufsize 8MB
ns_param sendqueuesize 256kB
ns_param idletimeout 3s
ns_param draintimeout 10ms
ns_param validateclientaddress true
}
For detailed documentation, see quic.
Enable detailed HTTP/3 and QUIC diagnostic logging
Type: boolean
Default: false
Drain timeout used when closing QUIC connections, allowing pending packets or connection-close handling to complete
Type: time
Default: 10ms
Configuration section of the HTTPS driver to which this HTTP/3 driver is linked. Shared driver and TLS parameters fall back to values from this section; parameters specified in ns/module/h3 override them
Type: section
Default: ns/module/https
Maximum idle time for QUIC connections before they are closed
Type: time
Default: 3s
Maximum UDP payload size advertised to the peer as the QUIC max_udp_payload_size transport parameter. Valid values range from 1200 to 65527 bytes. This parameter requires OpenSSL 4.1 or newer.
Currently, the setting only changes the advertised transport parameter. OpenSSL neither uses it to increase outgoing QUIC packet sizes nor enforces it as a receive limit, so it currently has no direct operational effect.
Type: size
Default: 1200
UDP port or ports on which the HTTP/3 driver listens
Type: integer
Default: 443
Size of the UDP receive buffer used by the HTTP/3 driver
Type: size
Default: 8MB
A value of 0 leaves the operating-system default unchanged. The effective size is subject to operating-system limits.
Type: size
Default: 8MB
Maximum response-body data retained in the HTTP/3 stream send queue. When this limit is reached, writer delivery pauses until the queue drains to half the configured size.
Type: size
Default: 256kB
Validate the QUIC client address before accepting a new connection. Clients without a valid address-validation token receive a Retry packet, adding one network round trip. Disabling validation improves first-connection latency but weakens protection against spoofed-source connection floods.
Type: boolean
Default: true
Per-server sections configure virtual-server behavior. The placeholder $server denotes a server name defined in ns/servers. These sections control request handling, ADP behavior, static-file delivery, outgoing HTTP client defaults, Tcl initialization, and legacy host-based virtual hosting.
Connection pools are configured below the server. The placeholder $pool denotes a connection pool name defined in ns/server/$server/pools. Requests that are not explicitly mapped to a named connection pool are handled by the server's default connection pool.
The ns/server/$server section defines core settings for a virtual server. It controls connection-thread behavior, compression defaults, request-overload handling, system-generated notices, default character sets, and selected compatibility options.
The placeholder $server is the server name defined in ns/servers.
Honour If-Modified-Since for cached files
Type: boolean
Default: true
Enable gzip compression for eligible dynamic responses by default; individual requests can still control compression via ns_conn compress
Type: boolean
Default: false
Compression level; higher values use more CPU and provide better compression
Type: integer 1-9
Default: 4
Compress responses larger than this size
Type: size
Default: 512
Preallocate compression buffers at startup
Type: boolean
Default: false
Rate limit per connection; -1 means unlimited
Type: size
Default: 0
Number of requests processed by a connection thread before it exits; 0 means unlimited
Type: integer
Default: 10000
Enable forward HTTP proxy handling for this server; for scalable proxying, the revproxy module should normally be loaded, otherwise a simple fallback implementation is used
Type: boolean
Default: false
Enable direct execution of .tcl pages for GET, HEAD, and POST requests by registering /*.tcl as Tcl request handlers
Type: boolean
Default: false
Pad error replies up to this size
Type: size
Default: 514
Additional HTTP response headers added for this server, typically used for server-wide security headers or policy headers
Type: ns_set
Use read/write locks for managing request filters; this improves concurrency when filters are mostly read during request processing and only changed occasionally
Type: boolean
Default: true
Fallback character set used when parsing form data if no explicit charset can be determined from the request; defaults to value of formfallbackcharset from ns/parameters
Type: charset
Allow concurrent thread creation above this queue fill percentage
Type: integer
Default: 80
Directory for per-server log files; relative paths are resolved against the server home directory
Type: path
Create more threads above this queue fill percentage
Type: integer
Default: 10
Maximum number of connection structures allocated for this connection pool. These structures cover both requests currently assigned to connection threads and requests waiting in the pool queue. When all structures are in use, the pool has reached its connection limit. If rejectoverrun is enabled, additional requests for this pool are rejected. Otherwise, the socket remains managed by the driver and may be retried according to the driver's queue handling.
Type: integer
Default: 100
Maximum number of connection threads
Type: integer
Default: 10
Minimum number of connection threads
Type: integer
Default: 1
ADP template used for system-generated HTTP notice responses such as ns_returnnotice; relative paths are resolved against SERVERHOME/conf, an empty value uses a built-in template, and errors in a custom template fall back to a basic built-in template
Type: path
Default: returnnotice.adp
Include server signature
Type: boolean
Default: true
Default character set for text output from this server; used to determine the Tcl encoding for converting Tcl UTF-8 strings to the response encoding; defaults to value of outputcharset from ns/parameters
Type: charset
Default: utf-8
Rate limit per pool; 0 means unlimited
Type: size
Default: 0
Default HTTP Basic authentication realm used in WWW-Authenticate responses when no connection-specific realm is set; defaults to $server
Type: string
Reject requests with 503 Service Unavailable when the selected connection pool has reached its maxconnections limit and no connection structure is available. When enabled, driver-level queueing and later retry for this pool-overrun condition are disabled, so overload is reported immediately to the client. When false, the socket remains managed by the network driver and may be retried later for queueing into the selected pool, subject to the driver's maxqueuesize. Enabling this option applies back-pressure during overload.
Type: boolean
Default: false
Number of seconds used for the Retry-After header on pool-overrun 503 responses (i.e., rejectoverrun is active); 0 disables the header.
Type: time
Default: 5s
Root directory for this virtual server; relative paths are resolved against the NaviServer home directory. This setting is the canonical location for the per-server directory and replaces the deprecated serverdir setting in ns/server/$server/fastpath
Type: path
Default:
Tcl procedure used to compute the server root directory dynamically, for example for mass virtual hosting based on the request host
Type: proc
Omit Server header
Type: boolean
Default: false
Idle timeout for connection threads above minthreads; excess threads exit after being idle for this duration
Type: time
Default: 2m
Default character set for decoding URL query strings and form data for this server; defaults to value of urlcharset from ns/parameters
Type: charset
Default: utf-8
The ns/server/$server/pools section defines named connection thread pools for a virtual server. Each parameter name is a configuration-defined pool name, and each value is a human-readable description of the pool.
Connection pools can be used to route selected requests to dedicated worker threads, for example for monitoring URLs, fast static requests, slow requests, or bot traffic. Requests not matching any per-pool map entry are handled by the server's default connection pool.
ns_section ns/server/$server/pools {
ns_param monitor "Monitoring and health-check requests"
ns_param fast "Fast static-file requests"
ns_param slow "Slow request pool"
ns_param bots "Crawler and bot traffic"
}
Configuration-defined connection pool name whose value is a human-readable pool description; the pool name is used in ns/server/$server/pool/$pool sections
Value type: string
Role of parameter name: configuration-defined identifier
Cardinality: multiple entries with different parameter names are expected
The ns/server/$server/pool/$pool section configures a named connection thread pool. The parameters in this section correspond to selected parameters from ns/server/$server and override the per-server values for requests assigned to this pool.
Requests are assigned to a named pool by map entries. Each map entry matches an HTTP method and URL pattern, optionally followed by context constraints such as user-agent patterns. Requests that do not match any configured pool map are handled by the server's default connection pool.
ns_section ns/server/$server/pool/monitor {
ns_param minthreads 2
ns_param maxthreads 2
ns_param map "GET /SYSTEM"
ns_param map "POST /SYSTEM"
ns_param map "GET /admin/nsstats"
ns_param map "GET /admin/nsstats.tcl"
}
ns_section ns/server/$server/pool/bots {
ns_param map "GET /* {user-agent *bot*}"
ns_param map "GET /* {user-agent *crawl*}"
ns_param minthreads 2
ns_param maxthreads 2
ns_param rejectoverrun true
ns_param poolratelimit 1000
}
Outgoing bandwidth limit in kilobytes per second for individual connections in this pool; 0 means unlimited
Type: integer
Number of requests processed by a connection thread in this pool before it exits
Type: integer
Queue fill percentage above which connection threads for this pool may be created in parallel
Type: integer
Queue fill percentage above which an additional connection thread for this pool may be created
Type: integer
Pool mapping entry; each occurrence maps an HTTP method and URL pattern to this connection pool, optionally followed by context constraints such as user-agent patterns
Type: mapping
Cardinality: multiple entries with the same parameter name are expected
Maximum number of allocated connection structures for this pool
Type: integer
Maximum number of connection threads for this pool
Type: integer
Minimum number of connection threads kept for this pool
Type: integer
Default outgoing bandwidth limit in kilobytes per second for each connection in this pool; 0 means unlimited and per-connection limits take precedence
Type: integer
Reject requests assigned to this pool with 503 Service Unavailable when the pool queue is full
Type: boolean
Value used for the Retry-After header in 503 Service Unavailable responses from this pool when rejectoverrun is enabled
Type: time
Idle timeout for connection threads in this pool above minthreads
Type: time
The ns/server/$server/adp section configures ADP processing for a virtual server, including ADP caching, buffering, error handling, debugging, streaming, and URL mappings for ADP pages.
ns_section ns/server/$server/adp {
# Register ADP pages.
ns_param map /*.adp
# Development/debugging.
ns_param enabledebug $debug
# Optional cache and buffer tuning.
# ns_param cache true
# ns_param cachesize 10MB
# ns_param bufsize 5MB
# Optional common processing and error handling hooks.
# ns_param startpage /path/to/startpage.adp
# ns_param errorpage /path/to/errorpage.adp
}
Failure to flush a buffer generates an ADP exception
Type: boolean
Default: true
Size of ADP buffer
Type: size
Default: 1MB
Enable ADP caching
Type: boolean
Default: false
Size of ADP cache
Type: size
Default: 5MB
Procedure to execute on ADP debug initialization
Type: proc
Default: ns_adp_debuginit
Optional file extension appended to unresolved ADP page filenames; useful when requests omit the ADP extension, for example resolving a request for page to page.adp
Type: string
Default:
Include connection info in error backtrace
Type: boolean
Default: true
Include error message in output
Type: boolean
Default: false
URL pattern registered for ADP processing; each map entry registers the ADP handler for GET, HEAD, and POST requests on the specified pattern
Type: boolean
Default: false
Set Expires: now on all ADPs
Type: boolean
Default: false
Page for returning errors
Type: path
Default:
URL pattern registered for ADP processing; each entry maps the pattern for GET, HEAD, and POST requests
Type: list
Disable inline scripts
Type: boolean
Default: false
Collapse Tcl blocks to a single Tcl script; in singlescript mode, an error in any part of the combined script stops execution of that ADP page
Type: boolean
Default: false
File to run for every ADP request
Type: path
Default:
Enable ADP streaming
Type: boolean
Default: false
Interrupt execution on any error
Type: boolean
Default: false
Trace execution of ADP scripts
Type: boolean
Default: false
Maximum number of entries in ADP trace
Type: integer
Default: 40
Trim whitespace from output buffer
Type: boolean
Default: false
The ns/fastpath section configures global behavior for fast static-file delivery. It controls optional in-memory caching, memory-mapped file I/O, and support for pre-compressed gzip or Brotli variants of static files. Per-server fastpath settings, such as the page directory and directory listing behavior, are configured separately under ns/server/*/fastpath.
ADP page invoked to generate a directory listing when a request maps to a directory and no directory index file is found; when unset, NaviServer falls back to directoryproc if configured
Type: path
Default:
List of filenames to try when a request maps to a directory; the first existing file is served as the directory index
Type: list
Default: index.adp index.tcl index.html index.htm
Directory listing style when no index file is present; "none" disables generated listings to avoid potential information disclosure
Type: enum
Allowed values: simple, fancy, none
Default: none
Tcl procedure used to generate directory listings when no directory index file is found and directory listing is enabled
Type: proc
Default: _ns_dirlist
Hide files and directories whose names start with a dot from generated directory listings
Type: boolean
Default: true
Root directory for static files and fastpath content for this server; relative paths are resolved against the server home directory
Type: path
Default: pages
The ns/server/$server/httpclient section defines per-server defaults for outgoing HTTP and HTTPS requests made through ns_http and ns_connchan. It controls default timeouts, connection reuse, logging, and TLS certificate validation.
CA bundle file containing trusted top-level certificates for outgoing HTTPS requests; relative paths are resolved against the home directory
Type: path
Default: ca-bundle.crt
Directory containing trusted CA certificates for outgoing HTTPS requests; relative paths are resolved against the home directory
Type: path
Default: certificates
Default timeout for outgoing ns_http requests when neither -timeout nor -expire is specified
Type: time
Default: 5s
Directory where invalid peer certificates from outgoing HTTPS requests are stored for inspection; relative paths are resolved against the home directory
Type: path
Default: invalid-certificates
Default keep-alive timeout for outgoing ns_http requests; 0 disables connection reuse by default
Type: time
Default: 0s
Enable logging for outgoing HTTP client requests
Type: boolean
Default: false
Maximum number of backup log files
Type: integer
Default: 100
Rotate log files automatically
Type: boolean
Default: true
Format appended to log filename
Type: string
Default:
Hour at which to roll the log
Type: integer
Default: 0
Perform log rotation on SIGHUP
Type: boolean
Default: false
Validate TLS certificates for outgoing ns_http and ns_connchan HTTPS requests; disabling validation is insecure and increases exposure to man-in-the-middle attacks
Type: boolean
Default: true
Maximum allowed certificate chain validation depth for outgoing HTTPS requests; 0 accepts only self-signed certificates, 1 accepts self-signed or certificates issued by one CA, and higher values allow longer chains
Type: integer
Default: 9
Whitelist certificate validation exceptions for outgoing HTTPS requests, optionally restricted by client IP or network; useful for controlled exceptions while still collecting invalid certificates for review
Type: list
The ns/server/$server/tcl section configures Tcl interpreter initialization and server-specific Tcl behavior, including the init file, Tcl library location, lazy loading, memoization, and NSV locking settings.
List of request header field names to include in Tcl error log messages for connection-related errors; matching headers are appended to the logged request method, URL, and peer address
Type: list
Tcl initialization file sourced when initializing interpreters for this server; relative paths are resolved against the home directory
Type: path
Default: bin/init.tcl
Enable lazy loading of Tcl library procedures, loading definitions on demand instead of during interpreter initialization; note: not supportend for e.g. OpenACS
Type: boolean
Default: false
Directory containing server-specific Tcl library files; relative paths are resolved against the home directory
Type: path
Default: modules/tcl
Size of the Tcl memoization cache used by this server
Type: size
Number of hash buckets used for NSV storage; increasing the value can reduce lock contention for workloads with many shared variables
Type: integer
Default: 8
Use read/write locks for NSV access; improves concurrency for read-heavy shared-variable workloads
Type: boolean
Default: true
The ns/server/$server/vhost section configures legacy host-based page root mapping within a single virtual server. The request Host header is normalized and used to select a host-specific subdirectory below the server page root.
This mechanism is less flexible than mass virtual hosting based on serverrootproc, but remains useful for simple legacy virtual-host layouts.
Enable legacy host-based page-root mapping within this server; the request Host header is used to select a host-specific subdirectory below the server page root. This mode requires a relative pagedir and is less flexible than server-root based virtual hosting via serverrootproc
Type: boolean
Default: false
Number of hash-directory levels added before the normalized host name in the generated page-root path; values from 0 to 5 are allowed and can avoid too many host directories in one directory
Type: integer
Default: 0
Optional directory prefix inserted between the server directory and the normalized host name when building the host-specific page root
Type: path
Strip the port part from the Host header before deriving the host-specific page-root directory
Type: boolean
Default: true
Strip a leading www. from the Host header before deriving the host-specific page-root directory
Type: boolean
Default: true
Server modules extend a virtual server with additional functionality such as access logging, CGI execution, control-port access, reverse proxying, or other application services. They are usually loaded through ns/server/$server/modules and configured below ns/server/$server/module/$name. The final path component $name is the configured module instance name; the accepted parameters are determined by the module implementation.
ns_section ns/server/$server/modules {
ns_param nslog nslog
ns_param nscgi nscgi
}
ns_section ns/server/$server/module/nslog {
ns_param file access.log
}
The nslog module writes HTTP access logs for a virtual server. It can produce combined access logs, rotate log files, include request timing and thread information, and optionally anonymize logged client addresses.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param nslog nslog
}
ns_section ns/server/$server/module/nslog {
ns_param file access.log
ns_param rolllog true
ns_param maxbackup 10
ns_param logcombined true
}
For detailed documentation, see nslog.
Legacy option for logging the client address from X-Forwarded-For; deprecated in favor of reverse-proxy mode, which centralizes trusted proxy handling for access logs and peer-address APIs
Type: boolean
Default: false
Deprecated: Use ns/parameters/reverseproxymode instead
Tcl string-match pattern for selecting network driver instance names to be logged by this nslog instance; when unset, the access log records requests from all drivers
Type: pattern
Default:
Additional header fields to include in access log entries; entries without a prefix are treated as request headers, while request:NAME and response:NAME select request and response headers explicitly
Type: list
Access log file written by this nslog instance; relative paths are resolved against the server log directory
Type: path
Default: access.log
Use formatted timestamps instead of Unix time
Type: boolean
Default: true
Use NCSA combined log format including referer and user-agent
Type: boolean
Default: true
Log partial request timing information for selected request processing phases; useful for diagnosing where request time is spent
Type: boolean
Default: false
Include total request processing time in access log entries
Type: boolean
Default: false
Include the connection thread name in access log entries; useful for debugging thread and pool behavior
Type: boolean
Default: false
IPv4 address mask for anonymizing logged client addresses
Type: ip-mask
IPv6 address mask for anonymizing logged client addresses
Type: ip-mask
Anonymize logged client addresses using maskipv4 and maskipv6 before writing access log entries
Type: boolean
Default: false
Maximum number of rotated log files
Type: integer
Default: 100
Number of log entries buffered
Type: integer
Default: 0
Suffix format used when rotating the access log file; controls how timestamps are appended to rolled log filenames
Type: string
Hour of day to roll the log
Type: integer
Default: 0
Rotate logs automatically
Type: boolean
Default: true
Rotate log on SIGHUP
Type: boolean
Default: false
Suppress the query string in logged request URLs; useful for reducing log volume and avoiding accidental logging of sensitive URL parameters
Type: boolean
Default: false
The nscp module provides the NaviServer control port. It listens on a configured local address and port and should normally be restricted to trusted interfaces such as loopback.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param nscp nscp
}
ns_section ns/server/$server/module/nscp {
ns_param address 127.0.0.1
ns_param port 9999
}
ns_section ns/server/$server/module/nscp/users {
#ns_param user "username:password:"
}
For detailed documentation, see nscp.
Local address on which the control port listens; should normally be restricted to a trusted interface such as loopback (e.g. 127.0.0.1)
Type: address
TCP port on which the control port listens
Type: integer
The nsperm module provides file-based permission checking for a virtual server. It can protect URL spaces using access-control data and optional .htaccess-style files.
This module is mainly useful for simple deployments or compatibility with older configurations. Applications with their own authentication and authorization layer typically use application-level permission checks instead.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param nsperm nsperm
}
ns_section ns/server/$server/module/nsperm {
ns_param htaccess false
}
For detailed documentation, see nsperm.
Activate htaccess mode, which is similar to Apache but more simpler and limited in functionality. It supports only allowing and denying access to a particular directory.
Type: boolean
Default: false
Absolute path to the passwd file
Type: path
Default: HOME/modules/nsperm/passwd
The nsproxy module manages pools of external worker processes used to evaluate Tcl code outside the main NaviServer process. This can be used to isolate potentially unsafe, blocking, or resource-intensive work from the server process.
Each nsproxy module instance configures a worker pool, including the worker executable, timeout behavior, maximum number of workers, and logging threshold for long-running operations.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param nsproxy nsproxy
}
ns_section ns/server/$server/module/nsproxy {
ns_param exec /usr/local/ns/bin/nsproxy
ns_param maxworker 8
ns_param gettimeout 0ms
ns_param evaltimeout 0ms
ns_param sendtimeout 5s
ns_param recvtimeout 5s
ns_param waittimeout 1s
ns_param idletimeout 5m
ns_param logminduration 1s
}
For detailed documentation, see nsproxy.
Timeout for evaluating a request in an nsproxy worker; 0 disables this timeout
Type: time
Default: 0ms
Worker executable used for nsproxy processes; when unset, NaviServer uses the default nsproxy executable
Type: path
Timeout for obtaining an nsproxy worker from the pool; 0 disables this timeout
Type: time
Default: 0ms
Maximum idle time for an nsproxy worker before it may be closed
Type: time
Default: 5m
Log nsproxy operations whose duration is at least this threshold
Type: time
Default: 1s
Legacy name for maxworker
Type: integer
Default: 8
Deprecated: Use maxworker instead
Maximum number of nsproxy worker processes in this pool
Type: integer
Default: 8
Timeout for receiving data or results from an nsproxy worker
Type: time
Default: 5s
Timeout for sending data or commands to an nsproxy worker
Type: time
Default: 5s
Timeout while waiting for an nsproxy worker process to become ready or complete a control operation
Type: time
Default: 1s
The nscgi module runs external CGI programs for configured URL mappings. It maps request methods and URL prefixes to filesystem directories, controls the CGI execution environment, and limits request body size and execution time.
The optional interps parameter refers to an ns/interps/$name section that maps script filename extensions to interpreter commands. The optional environment parameter refers to an ns/environment/$name section whose entries are merged into the CGI process environment.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param nscgi nscgi
}
ns_section ns/interps/cgi {
ns_param .pl /usr/bin/perl
ns_param .sh /bin/sh
}
ns_section ns/environment/cgi {
ns_param PATH /usr/local/bin:/usr/bin:/bin
ns_param TMPDIR /tmp
ns_param LANG C.UTF-8
}
ns_section ns/server/$server/module/nscgi {
ns_param interps cgi
ns_param environment cgi
ns_param map "GET /cgi-bin /usr/local/ns/cgi-bin"
ns_param map "POST /cgi-bin /usr/local/ns/cgi-bin"
ns_param maxinput 1MB
ns_param maxwait 30s
}
For detailed documentation, see nscgi.
Allow CGI requests to serve static resources from the mapped CGI directories; normally disabled so mapped locations are treated as executable CGI resources only
Type: boolean
Default: false
Name of an ns/environment/$name section whose entries are merged into the environment of CGI scripts
Type: string
Resolve the remote client address to a hostname for CGI environment variables; disabled by default to avoid DNS lookup overhead and latency
Type: boolean
Default: false
Name of an ns/interps/$name section used to map CGI script filename extensions to interpreter commands
Type: string
Maximum number of concurrent CGI executions allowed by this module instance; 0 disables the concurrency limit
Type: integer
Default: 0
Maps HTTP methods and URL prefixes to filesystem directories containing CGI scripts
Type: list
Maximum accepted request body size for CGI requests
Type: size
Default: 1MB
Maximum time to wait for a CGI process to complete before treating the request as failed
Type: time
Default: 30s
Pass the server process environment to CGI scripts; disabled by default to avoid exposing unintended environment variables
Type: boolean
Default: false
The revproxy module provides reverse-proxy support for a virtual server. It forwards selected incoming requests to configured backend servers and returns the backend response to the client.
Backend servers are configured in subsections below the revproxy module configuration. The main module section contains global defaults and initialization hooks, while each backend subsection defines its target URLs, URL mappings, timeouts, optional URL rewriting, backend connection handling, and forwarding constraints.
Backend subsections are documented separately in the following revproxy backends subsection.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param revproxy tcl
}
ns_section ns/server/$server/module/revproxy {
ns_param verbose false
}
ns_section ns/server/$server/module/revproxy/backend1 {
ns_param target https://backend.example.com/
ns_param map "GET /api/*"
ns_param map "POST /api/*"
}
For detailed documentation, see revproxy.
Default backend connection type used for reverse proxy backends; can be overridden per backend
Type: enum
Allowed values: s_http+ns_connchan, ns_http, ns_connchan
Default: ns_http+ns_connchan
Tcl script evaluated during revproxy initialization; used to register additional handlers or filters for URLs handled by the proxy itself rather than forwarded to a backend
Type: script
Enable verbose logging for reverse proxy operations in the system log
Type: boolean
Default: false
Backend sections below the revproxy module define individual upstream targets. The final path component is a configuration-defined backend name.
Each backend specifies one or more target URLs and one or more map entries that select which incoming requests are forwarded to that backend. Optional settings control connection and transfer timeouts, URL rewriting, backend connection behavior, and context constraints.
ns_section ns/server/$server/module/revproxy/backend1 {
ns_param target https://backend.example.com/
ns_param connecttimeout 2s
ns_param receivetimeout 15s
ns_param sendtimeout 15s
ns_param map "GET /api/*"
ns_param map "POST /api/* {-use_target_host_header true}"
}
Backend connection type for this backend; overrides the revproxy-wide backendconnection setting and can be used to select special forwarding behavior such as preauth
Type: enum
Allowed values: s_http+ns_connchan, ns_http, ns_connchan
Default: ns_http+ns_connchan
Maximum time to wait while establishing a connection to the backend server
Type: time
Default: 1s
Context constraint entry; key/value pairs within one entry are combined with AND, while multiple constraints entries are combined with OR
Type: context-constraints
Cardinality: multiple entries with the same parameter name are expected
Backend mapping entry; each occurrence maps an HTTP method and URL pattern to this backend, optionally followed by per-map options such as -use_target_host_header or -constraints
Type: mapping
Cardinality: multiple entries with the same parameter name are expected
Maximum time to wait for receiving data from the backend server
Type: time
Default: 10s
Regular-expression substitutions applied to the forwarded URL before sending the request to the backend, for example to strip a URL prefix
Type: list
Maximum time to wait while sending request data to the backend server
Type: time
Default: 10s
Upstream backend URL or list of backend URLs to which matching requests are forwarded
Type: URI
Database support is optional. Installations that use NaviServer database integration load the nsdb module for a virtual server, select the server's available database pools in ns/server/$server/db, and define the global database pool configurations under ns/db/pools and ns/db/pool/$dbpool.
The placeholder $dbpool denotes a database pool name defined in ns/db/pools. Database pools are global and may be shared by multiple virtual servers.
Database drivers are external modules for the nsdb interface. They must be compiled and installed separately, then registered in ns/db/drivers before database pools can use them. The placeholder $dbdriver denotes a database driver name defined in ns/db/drivers.
For a broader introduction to NaviServer database access and administration, see Database Access and Configuration.
The nsdb module provides NaviServer's database integration for a virtual server. Loading this module enables the server to use database pools defined globally under ns/db/pools and ns/db/pool/$dbpool.
The server-specific ns/server/$server/db section selects which global pools are available to this server and which one is used as the default pool.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param nsdb nsdb
}
ns_section ns/server/$server/db {
ns_param pools pool1,pool2,pool3
ns_param defaultpool pool1
}
For detailed documentation, see nsdb.
The ns/server/$server/db section selects the database pools available to a virtual server. The pools themselves are defined globally under ns/db/pools and ns/db/pool/$dbpool and may be shared by multiple servers.
The default pool is used when application code requests a database handle without explicitly naming a pool.
ns_section ns/server/$server/db {
ns_param pools pool1,pool2,pool3
ns_param defaultpool pool1
}
Default database pool used by this server when no explicit pool name is requested
Type: string
List of database pool names available to this server; the names must refer to pools defined in ns/db/pools
Type: list
The ns/db/pools section defines global database pool names. Each parameter name is a configuration-defined pool name, and each value is a human-readable description of the pool.
Database pools are process-wide definitions and can be made available to one or more virtual servers through the server-specific ns/server/$server/db section.
ns_section ns/db/pools {
ns_param pool1 "Main database pool"
ns_param pool2 "Secondary database pool"
ns_param pool3 "Optional third database pool"
}
Configuration-defined database pool name whose value is a human-readable pool description; the pool name is used in ns/db/pool/$dbpool sections and in per-server database configuration
Value type: string
Role of parameter name: configuration-defined identifier
Cardinality: multiple entries with different parameter names are expected
The ns/db/pool/$dbpool section configures a global database connection pool. A pool defines how NaviServer connects to a database, how many handles are maintained, and how idle or stale handles are checked and closed.
Database pools are global and may be used by multiple virtual servers. A server selects the pools it uses in ns/server/$server/db.
ns_section ns/db/pool/pool1 {
ns_param driver postgres
ns_param datasource localhost::dbname
ns_param user dbuser
ns_param password secret
ns_param connections 15
ns_param logminduration 10ms
}
Interval at which the pool checks for stale database handles
Type: time
Default: 5m
Number of database connections maintained by this pool
Type: integer
Default: 2
Driver-specific datasource string identifying the database connection target
Type: string
Database driver used by this pool
Type: string
When SQL logging is enabled, log only statements whose execution time is at least this duration
Type: time
Default: 0ms
Log SQL errors reported by this pool
Type: boolean
Default: false
Close database handles that have been idle for at least this interval
Type: time
Default: 5m
Close database handles that have been open longer than this interval
Type: time
Default: 60m
Database password used when opening connections for this pool
Type: string
Database user name used when opening connections for this pool
Type: string
The ns/db/drivers section defines database driver instances available to NaviServer's nsdb interface. Each parameter name is a configuration-defined driver name, and each value is the database driver module implementation to load.
Database drivers are external NaviServer modules. They are maintained separately from the core server, usually in separate source repositories, and must be compiled and installed before they can be loaded. Common drivers include nsdbpg for PostgreSQL and nsoracle for Oracle; additional drivers are available for other database systems.
ns_section ns/db/drivers {
ns_param postgres nsdbpg
ns_param nsoracle nsoracle
}
Available external database drivers include nsdbpg, nsoracle, nsdbmysql, nsdbsqlite, nsdbtds, nsodbc, and nsdbbdb.
Configuration-defined database driver name whose value names the installed database driver module implementation; the driver name is used in ns/db/pool/$dbpool via the driver parameter
Value type: module
Role of parameter name: configuration-defined identifier
Cardinality: multiple entries with different parameter names are expected
The ns/db/driver/$dbdriver section contains optional settings for a database driver instance. The final path component is the configuration-defined driver name from ns/db/drivers, not necessarily the implementation name.
For example, a configuration may map the driver name postgres to the nsdbpg implementation and then configure driver-specific settings below ns/db/driver/postgres.
ns_section ns/db/drivers {
ns_param postgres nsdbpg
}
ns_section ns/db/driver/postgres {
ns_param pgbin /usr/lib/postgresql/18/bin/
}
The nsdbpg module provides the PostgreSQL database driver for the nsdb interface. It is an external NaviServer module and must be compiled and installed separately.
The configured driver name is chosen in ns/db/drivers. A common convention is to use postgres as the driver name and nsdbpg as the implementation.
ns_section ns/db/drivers {
ns_param postgres nsdbpg
}
ns_section ns/db/driver/postgres {
ns_param pgbin /usr/lib/postgresql/16/bin/
}
ns_section ns/db/pool/pool1 {
ns_param driver postgres
}
For detailed documentation, see nsdbpg.
PostgreSQL DateStyle setting applied to database sessions opened by this driver; explicit values such as ISO, DMY or ISO, MDY are recommended to define both output style and ambiguous date input ordering. The historical values ISO, SQL, POSTGRES, GERMAN, NONEURO, and EURO remain accepted for compatibility. When unset, PGDATESTYLE or the PostgreSQL server default applies
Type: enum
Allowed values: ISO, SQL, POSTGRES, GERMAN, NONEURO, EURO, ISO, MDY, ISO, DMY, ISO, YMD, SQL, MDY, SQL, DMY, POSTGRES, MDY, POSTGRES, DMY, GERMAN, DMY
Directory containing PostgreSQL client tools such as psql; used when these tools are not available on PATH
Type: path
The nsoracle module provides the Oracle database driver for the nsdb interface. It is an external NaviServer module and must be compiled and installed separately.
The configured driver name is chosen in ns/db/drivers. A common convention is to use nsoracle as both the driver name and the implementation name
ns_section ns/db/drivers {
ns_param nsoracle nsoracle
}
ns_section ns/db/driver/nsoracle {
ns_param maxStringLogLength -1
ns_param LobBufferSize 32768
}
ns_section ns/db/pool/pool1 {
ns_param driver nsoracle
}
For detailed documentation, see nsoracle.
Buffer size used for Oracle LOB operations
Type: size
Default: 32768
Maximum length of SQL strings written to the log; -1 disables this limit
Type: integer
Default: -1
This section documents selected external NaviServer modules that are commonly used together with the core server. External modules are maintained outside the core NaviServer source tree and may require separate checkout, compilation, installation, or loading.
The NaviServer project maintains additional external modules. For the full list of available repositories, see the NaviServer project repositories on GitHub.
Some external modules are documented in more specific sections when their role belongs to a larger subsystem. For example, nsdbpg and nsoracle are external modules, but are documented under Database Configuration because they implement database drivers for the nsdb interface.
The nssmtpd module provides an SMTP server for NaviServer. It can be used to receive mail locally, relay messages to another mail server, filter incoming messages, and dispatch SMTP processing to Tcl callback procedures.
The optional aliasproc command prefix provides envelope alias resolution. The supplied smtpd::resolvefilealiases resolver supports classical aliases and Postfix virtual address-forwarding maps without requiring a database. It can also reject unknown incoming recipients using the same lookup. The separate recipientpolicyproc supports SMTP policies such as greylisting. Alias handling, unknown-recipient rejection and SMTP policy are disabled by default. Message headers and envelope senders are not rewritten.
For file-based aliases, configure aliasfile and aliasdomains, then set aliasproc to smtpd::resolvefilealiases. aliasformat defaults to virtual. Enable rejectunknownrecipients for alias-only incoming domains. LOCAL submissions, direct sends and resolve operations retain passthrough for unknown addresses while still expanding known aliases.
Alias resolution does not add a persistent delivery queue or direct MX delivery. Retain an upstream MTA for these functions. In the streaming relay path, forwarding precedes the message-data callback and spam checks; these checks cannot prevent delivery already made to the relay.
The module is an external NaviServer module and must be compiled and installed separately. For new mail-related applications, nssmtpd or Tcl library based mail support is usually preferable to the legacy ns_sendmail command.
The logging parameters documented here apply to SMTP sending operations performed by the module. A graphical viewer for the log file is included in the nsstats module.
This module is loaded per server through ns/server/$server/modules.
ns_section ns/server/$server/modules {
ns_param nssmtpd nssmtpd
}
ns_section ns/server/$server/module/nssmtpd {
ns_param port 2525
ns_param address 127.0.0.1
ns_param relay localhost:25
ns_param spamd localhost
ns_param initproc smtpd::init
ns_param rcptproc smtpd::rcpt
ns_param dataproc smtpd::data
ns_param errorproc smtpd::error
ns_param relaydomains "localhost"
ns_param localdomains "localhost"
ns_param logging on
ns_param logfile smtpsend.log
ns_param logrollfmt %Y-%m-%d
# Optional file aliases and strict incoming recipient validation.
# These are disabled until explicitly configured.
# Also change relaydomains above to {localhost example.org}.
# ns_param aliasfile /var/www/openacs/etc/mail/virtual
# ns_param aliasdomains {example.org}
# ns_param aliasformat virtual ;# default; may be omitted
# ns_param aliasproc smtpd::resolvefilealiases
# ns_param rejectunknownrecipients true
# Alternative aliasproc value; configure only one aliasproc:
# ns_param aliasproc {smtpd::resolvefilealiases -file /another/virtual}
# Optional greylisting of incoming mail from non-LOCAL peers.
# ns_param recipientpolicyproc smtpd::greylist
# ns_param greylistdelay 300
# ns_param greylistretrywindow 14400
# ns_param greylistlifetime 604800
# ns_param greylistmaxentries 10000
# Public reception also requires a reachable listener address
# and port; the loopback listener above is for local submission.
}
For detailed documentation, see nssmtpd.
Local address on which the SMTP server listens
Type: address
Default recipient-domain scope for smtpd::resolvefilealiases. An explicit -domains option overrides this setting. Domains must be supplied here or by the callback option; an explicitly empty list matches no domains. These are recipient domains, not trusted peers, and this setting neither enables aliasproc nor grants relay authorization
Type: list
Default map filename for smtpd::resolvefilealiases. An explicit -file option overrides this setting. A filename must be supplied here or by the callback option; there is no implicit map path. This setting alone does not enable aliasproc
Type: path
Default file format for smtpd::resolvefilealiases: virtual or aliases. An explicit -format option overrides this setting. This setting alone does not enable aliasproc
Type: string
Default: virtual
Tcl command prefix returning a list of final envelope destinations. The module appends -recipient and the original address. For LOCAL SMTP submissions, ns_smtpd send and ns_smtpd resolve it also appends -rejectunknown false, overriding fixed callback options. Custom callbacks must accept these named arguments. A dash-prefixed address is passed as the value of -recipient, so no -- separator belongs in the configured prefix. Unset or empty disables alias handling and retains existing behavior.
Return the original address for passthrough or final addresses for expansion. An empty list or error code NSSMTPD ALIAS UNKNOWN rejects an unknown recipient (550 for incoming SMTP). Lookup errors produce 451, and recipient-limit overflow produces 452. Direct operations report Tcl errors. The module resolves once per original recipient after relay authorization, before rcptproc and greylisting. It applies the saved expansion only after rcptproc accepts, inheriting flags/data from the original recipient and looking up destination transport routes. Duplicate targets within an expansion are removed; maxrcpt bounds it.
The supplied smtpd::resolvefilealiases resolver uses aliasformat, aliasfile, aliasdomains and rejectunknownrecipients. Explicit -format, -file, -domains and -rejectunknown options override these settings. Arguments are parsed by ns_parseargs. aliasformat defaults to virtual and rejectunknownrecipients to false. File and domains must each be supplied by an option or module setting. The file resolver supports aliases/virtual maps, bounded chains, identity mappings and virtual catch-alls. It performs membership checking and expansion from one snapshot. Callbacks must not send mail or mutate SMTP sessions.
When migrating earlier experimental configurations, rename filealiases to resolvefilealiases, remove trailing -- separators and replace recipientcheckproc with rejectunknownrecipients true where strict incoming validation is required. Custom alias callbacks must accept -recipient and the optional -rejectunknown override.
Type: list
Default:
Size of the SMTP receive buffer in bytes
Type: integer
Default: 4096
CA certificate file used for TLS certificate validation
Type: path
Directory containing CA certificates used for TLS certificate validation
Type: path
Certificate chain file used for STARTTLS support
Type: path
OpenSSL cipher list for TLS 1.2 and older STARTTLS connections
Type: string
Tcl callback procedure invoked for processing SMTP message data
Type: proc
Default: smtpd::data
Tcl callback procedure invoked for SMTP error handling
Type: proc
Default: smtpd::error
Positive minimum number of seconds from first attempt to an accepted greylist retry. Early retries do not reset the first-attempt time. Used by smtpd::greylist when explicitly enabled via recipientpolicyproc
Type: integer
Default: 300
Positive lifetime in seconds of a passed greylist tuple, refreshed on each accepted attempt. Different peers, senders or recipients use separate tuples
Type: integer
Default: 604800
Positive maximum number of pending and passed greylist tuples per server. Expired entries are swept on traffic at most once per minute; an accessed expired entry is also removed immediately. At capacity, new tuples pass without being remembered, preserving mail availability while weakening filtering; monitor capacity log entries
Type: integer
Default: 10000
Seconds from first attempt before a pending greylist tuple expires. Must exceed greylistdelay; a later attempt starts a new waiting period
Type: integer
Default: 14400
Optional Tcl callback procedure for HELO/EHLO handling; receives the SMTP session ID
Type: proc
Default:
Tcl initialization procedure invoked at server startup. The supplied procedure populates relay and trusted-peer rules from relaydomains and localdomains, and initializes the greylist when recipientpolicyproc is configured
Type: proc
Default: smtpd::init
Trusted sending-peer addresses, networks or hostnames loaded by smtpd::init. Matching connections receive the LOCAL flag and may relay to arbitrary recipient domains; they also bypass unknown-recipient rejection and recipientpolicyproc. This is not a list of local recipient domains. Restrict it to trusted submitting peers
Type: list
Default: localhost
Log file for SMTP sending operations; relative paths are resolved according to the module's logging rules
Type: path
Enable logging for SMTP sending operations performed by the module
Type: boolean
Default: false
Maximum number of rotated SMTP sending log files to keep
Type: integer
Default: 100
Enable automatic rotation of the SMTP sending log
Type: boolean
Default: true
Suffix format used when rotating the SMTP sending log file
Type: string
Hour of day at which to rotate the SMTP sending log
Type: integer
Default: 0
Rotate the SMTP sending log when the server receives a SIGHUP signal
Type: boolean
Default: false
Optional Tcl callback procedure for MAIL FROM handling; receives the SMTP session ID
Type: proc
Default:
Maximum SMTP message data size in bytes
Type: integer
Default: 10485760
SMTP input-line length limit in bytes
Type: integer
Default: 4096
Maximum number of recipients; alias expansion also enforces this limit, accounting for recipients already accepted in an incoming transaction
Type: integer
Default: 100
TCP port on which the SMTP server listens
Type: integer
Default: 25
Tcl callback receiving the SMTP session ID after relay authorization and alias resolution, before applying the saved expansion. It sees the original recipient. The supplied smtpd::rcpt invokes the optional recipientpolicyproc; custom callbacks adopt that policy by calling smtpd::checkpolicy and stopping when it returns false. Alias resolution errors skip rcptproc and return the appropriate SMTP failure.
Type: proc
Default: smtpd::rcpt
Receive timeout in seconds. The local receive implementation shares a deadline across readiness retries for one buffer refill, not across an entire SMTP line or transaction
Type: integer
Default: 60
Optional Tcl command prefix called by smtpd::checkpolicy from the supplied smtpd::rcpt, after relay authorization and alias resolution with optional recipient validation, before applying the saved expansion and before DATA. Unset or empty disables this policy. Trusted LOCAL peers bypass it, as do direct ns_smtpd send and ns_smtpd resolve operations.
Receives a dictionary with id (SMTP session ID), peeraddr (socket peer IP), sender (envelope sender, empty for a null sender), and recipient (original envelope recipient). Returns a dictionary with action accept, defer (451 4.7.1), or reject (550 5.7.1). An optional message for defer/reject must contain 1 to 400 printable ASCII characters without newlines. Errors or invalid results cause 451 4.3.0 Recipient policy unavailable. Only the current recipient is removed on failure. Callbacks must not modify SMTP sessions or send mail. Accept continues normal processing, including later checks.
The supplied smtpd::greylist callback uses a mutex-protected shared table of exact peer-IP, sender and original-recipient tuples. A mature retry grants a sliding allowance for that tuple. State is bounded and in memory only: restarting the server clears it and may delay subsequent deliveries again. No database is required. At capacity, new tuples pass without being stored; existing entries remain. Notice logs record deferrals, rejections and new/retry/ expired/capacity greylist decisions. Legitimate delivery is delayed, senders changing IPs may be delayed repeatedly, and spammers that retry can pass. This is not content filtering.
smtpd::init initializes greylisting when a recipient policy is configured. Custom initproc callbacks using greylisting must call smtpd::greylistinit once at startup; this clears its state.
Type: list
Default:
Default for smtpd::resolvefilealiases -rejectunknown. When true, an unknown original recipient within the effective domain scope (aliasdomains or an explicit -domains option) raises NSSMTPD ALIAS UNKNOWN, producing 550 Unknown recipient for incoming SMTP. Exact entries, identity mappings and virtual catch-alls count as known. Out-of-scope addresses pass through the resolver; relay authorization still applies. Missing or malformed maps cause lookup failure, not an unknown-user rejection. LOCAL submissions, direct sends and resolve operations explicitly pass -rejectunknown false, so unknown addresses pass through. Known aliases expand in all contexts. This setting is read by the file resolver; it does not enable aliasproc and is not a separate C policy. A direct Tcl call to smtpd::resolvefilealiases uses this configured default unless -rejectunknown is explicitly supplied; this differs from ns_smtpd resolve, which always supplies -rejectunknown false.
Type: boolean
Default: false
Upstream SMTP server or mail relay used for forwarding messages
Type: address
Recipient-domain relay rules loaded by smtpd::init. Permit untrusted peers to address these domains; this does not establish that an individual recipient exists. Configure aliasproc with rejectunknownrecipients for alias-only domains
Type: list
Default: localhost
Spamd or SpamAssassin daemon used for filtering messages
Type: address
Timeout in seconds used for outbound SMTP and spamd connection establishment. The current local send implementation uses separate retry waits; this setting is not an overall write or SMTP transaction deadline
Type: integer
Default: 60
The nsstats module provides status and diagnostic pages for a running NaviServer instance. It is configured as a global Tcl module and can display runtime information such as server statistics, locks, threads, loaded modules, and the current configuration database.
This module provides access to potentially sensitive information. Do not deploy it on public-facing websites unless you implement appropriate access controls. For OpenACS installations, it is recommended to place the module main script nsstats.tcl in a secure directory such as acs-subsite/www/admin/, ensuring that only authorized users can access it.
This module should be loaded globally through ns/modules.
ns_section ns/module/nsstats {
ns_param enabled true
ns_param user nsadmin
ns_param password ""
ns_param bglocks {oacs:sched_procs}
}
For detailed documentation, see nsstats.
List of lock names treated as non-per-request background locks in nsstats lock reporting
Type: list
Default:
Enable or disable the nsstats module
Type: boolean
Default: true
Password required for accessing nsstats pages; when empty, access control depends on the surrounding configuration
Type: password
Default:
User name required for accessing nsstats pages
Type: string
Default: nsadmin
This section documents compatibility configuration for older command-level interfaces. These settings are retained for existing installations but are not the preferred interface for new applications.
The ns/sendmail section documents configuration parameters used by the legacy ns_sendmail command. The command sends mail through a configured SMTP server and provides only basic SMTP support. STARTTLS is available only when the external Tcl package "tls" is installed and loadable.
For new applications, prefer the external nssmtpd module where appropriate, or Tcl library based mail support with modern TLS-capable SMTP handling.
In earlier NaviServer versions, these parameters were configured directly in ns/parameters. This legacy location is still accepted for compatibility, but new configurations should use ns/sendmail.
For detailed documentation, see nssmtpd.
SMTP authentication mode used by ns_sendmail; empty value disables SMTP authentication
Type: enum
Allowed values: PLAIN, LOGIN
Default: PLAIN
SMTP authentication password used by ns_sendmail
Type: password
Default:
SMTP authentication user name used by ns_sendmail
Type: string
Default:
Character encoding used by ns_sendmail when SMTP encoding mode is enabled
Type: charset
Default: utf-8
Enable message encoding support for ns_sendmail
Type: boolean
Default: false
SMTP server host used by ns_sendmail
Type: hostname
Default: localhost
Enable logging of SMTP dialogue or delivery activity for ns_sendmail
Type: boolean
Default: false
Generate a Message-ID header for messages sent by ns_sendmail
Type: boolean
Default: false
Host name used when generating Message-ID headers for ns_sendmail; when empty, the default host name is used
Type: hostname
Default:
SMTP server port used by ns_sendmail
Type: integer
Default: 25
Timeout for SMTP operations performed by ns_sendmail
Type: time
Default: 60