Complete Config File

Main ✸ Source Code ✸ Downloads ✸ API Documentation ✸ Mailing Lists ✸ Bugs ✸ Developers

Complete Config File

Intention

NaviServer ships with sample-config.tcl, a Tcl Configuration File with many examples to get you started. It defines one server and should let you config a basic server very fast. This page may end as a collection of well and complete documented configuration options that are missing in the sample-config.tcl.

(It would be nice to document also the default values...)

The NaviServer module nsstats shows for a running NaviServer instance the actual config settings including the values derived from defaults. The listing provides for many parameters additionally tooltips with default information.

Set TCL variables for later use

The NaviServer configuration file is not just a collection of rows of key and value pairs. It's sourced and evaluated by TCL. You are able to do very flexible setups. The following example just sets up some variables at the beginning.

 # ============================================================================
 # Set some Tcl variables that are commonly used throughout this file.
 # ============================================================================
 #
 set httpport               8000
 #
 # The hostname and address should be set to actual values.
 set hostname               [ns_info hostname]
 set address                [ns_info address]
 #
 set servername             "server1"
 set serverdesc             "Server Name"
 #
 set homedir                [file dirname [ns_info config]]
 set bindir                 [file dirname [ns_info nsd]]
 #
 set serverdir              ${homedir}/servers/${servername}
 set pageroot               pages
 set directoryfile          index.adp,index.html,index.htm,index.xhtml,index.xht

Global server parameters

 # ============================================================================
 # Global server parameters
 # ============================================================================
 ns_section "ns/parameters"
 ns_param   home            $homedir
 ns_param   debug           false

 Server Logfile

 Command: ns_log

 ns_param   logusec             false
 ns_param   logroll             false
 ns_param   logexpanded         false
 ns_param   debug               false
 ns_param   logdev              false
 ns_param   lognotice           true
 ns_param   logmaxbackup        
 ns_param   logmaxlevel
 ns_param   logmaxbuffer
 ns_param   logflushinterval
 ns_param   serverlog           server.log

Option	Type	Default
logroll	bool	false
logexpanded	bool	false
debug	bool	false
lognotice	bool	false
logusec	bool	false
logmaxlevel	int	INT_MAX
logmaxbuffer	int	10
logflushinterval	int	10
logmaxbackup	int	10
serverlog	string	server.log

for HTTP Keepalive (keepalive.c)

 ns_param   keepalivetimeout   30
 ns_param   maxkeepalive       100

for DNS Tuning (dns.c)

 ns_param   dnscache           true
 ns_param   dnscachemaxentries
 ns_param   dnscachetimeout    60

for I/O settings

 ns_param   shutdowntimeout    20  ;# Seconds to wait on shutdown if open connections
 ns_param   schedmaxelapsed    2   ;# Warn when waiting on rely long procedures
 ns_param   listenbacklog      32  ;# Number of pending connections

for Sendmail

 ns_param   smtphost       "localhost" ;# "mailhost"-param is also asked, means the same;
 ns_param   smtptimeout    60
 ns_param   smtpport       25

for Miscellaneous

 ns_param   verbose        false       ;# more detailed logging
 ns_param   errorminsize   514         ;# Minimum size of error page; below size is padded
                                       ;# with whitespace to suppress IE friendly pages
                                       ;# For http status codes > 400

I18N Parameters

 # ============================================================================
 # I18N Parameters
 # ============================================================================
 #ns_param HackContentType false      ;# automatic adjustment of response
                                       # content-type header to include charset
                                       # This defaults to True.
 ns_param  OutputCharset  iso8859-1   ;# Default output charset.  When none specified,
                                       # no character encoding of output is performed.
 ns_param  URLCharset     iso8859-1   ;# Default Charset for Url Encode/Decode.
                                       # When none specified, no character set encoding
                                       # is performed.
 #ns_param  PreferredCharsets { utf-8 iso8859-1 } ;# This parameter supports output
                                       # encoding arbitration.

MIME types

 # ============================================================================
 # MIME types.
 # ============================================================================
 #  Note: naviserver already has an exhaustive list of MIME types, but in
 #  case something is missing you can add it here.
 #
 ns_section "ns/mimetypes"
 ns_param   default         "*/*"     ;# MIME type for unknown extension.
 ns_param   noextension     "*/*"     ;# MIME type for missing extension.
 #ns_param   ".xls"          "application/vnd.ms-excel"

For Developers: Mimetypes are defined in nsd/mimetypes.c (List of MIME types).

I18N Mime-types

 # ============================================================================
 # I18N Mime-types
 # ============================================================================
 # Define content-type header values to be mapped from these file-types.
 # 
 # Note that you can map file-types of adp files to control
 # the output encoding through mime-type specificaion.
 # Remember to add an adp mapping for that extension.
 #
 ns_param   .adp            "text/html; charset=iso-8859-1"
 ns_param   .u_adp          "text/html; charset=UTF-8"
 ns_param   .gb_adp         "text/html; charset=GB2312"
 ns_param   .sjis_html      "text/html; charset=shift_jis"
 ns_param   .sjis_adp       "text/html; charset=shift_jis"
 ns_param   .gb_html        "text/html; charset=GB2312"

I18N File-type to Encoding mappings

 # ============================================================================
 #   I18N File-type to Encoding mappings
 # ============================================================================
 ns_section "ns/encodings"
 ns_param   .utf_html       "utf-8"
 ns_param   .sjis_html      "shiftjis"
 ns_param   .gb_html        "gb2312"
 ns_param   .big5_html      "big5"
 ns_param   .euc-cn_html    "euc-cn"
 #
 # Note: you will need to include file-type to encoding mappings
 #       for ANY source files that are to be used, to allow the
 #       server to handle them properly.  E.g., the following
 #       asserts that the GB-producing .adp files are themselves
 #       encoded in GB2312 (this is not simply assumed).
 #
 ns_param   .gb_adp         "gb2312"

Thread library (nsthread) parameters

 # ============================================================================
 # Thread library (nsthread) parameters
 # ============================================================================
 ns_section "ns/threads"
 #ns_param   stacksize [expr {128*1024}] ;# Per-thread stack size.

Option	Type	Default
stacksize	int	64*1024

Notes: The default value is not sufficient if you

are using a lot of recursive functions/procedures or nested calls
want to run the OpenACS toolkit
integrate other scripting languages like PHP with NaviServer

In those cases even the example value of 128*1024 of sample-config.tcl may not be sufficient. Start at least with 512*1024.

Server-level configuration

 ############################################################
 #
 # Server-level configuration
 #
 #  There is only one server in naviserver, but this is helpful when multiple
 #  servers share the same configuration file.  This file assumes that only
 #  one server is in use so it is set at the top in the "server" Tcl variable.
 #  Other host-specific values are set up above as Tcl variables, too.
 #
 ns_section "ns/servers"
 ns_param   $servername     $serverdesc

Server parameters

 # ============================================================================
 # Server parameters
 # ============================================================================
 ns_section "ns/server/${servername}"
 ns_param   directoryfile      $directoryfile
 ns_param   pageroot           $serverdir/$pageroot  ;# absolute path to public pages
 ns_param   enabletclpages     false     ;# Parse *.tcl files in pageroot.
 ns_param   SourceCacheSize    5000000   ;# Size of Cache if Caching is enabled
 ns_param   noticedetail       true      ;# display Name+Version info on error pages
 ns_param   checkmodifiedsince true      ;# Obey 'If-Modified-Since' from Client
 ns_param   realm              "server"
 # Compress response character data: ns_return, ADP etc.
 ns_param   compressenable     off     ;# Boolean. Default; use ns_conn compress to override
 ns_param   compresslevel      4       ;# 1-9 where 9 is high compression, high overhead
 ns_param   compressminsize    512     ;# Compress responses larger than this

 #
 #         Server-level I18N Parameters can be specified here, to override
 #         the global ones for this server.  These are:
 #              HackContentType
 #              OutputCharset
 #              URLCharset
 #         See the global parameter I18N section for a description of these.
 #

Option	Type	Default
directoryfile	string	?
pageroot	string	?
enabletclpages	bool	used in tcl/file.tcl only if set: true/false/on/off
SourceCacheSize	int	Cache Size: used in tcl/file.tcl if ns_cache command is available
noticedetail	bool	true
checkmodifiedsince	bool	true
realm	string	server
headercase	string	tolower, toupper, preserve

Scaling and Tuning Options

 # ============================================================================
 # Scaling and Tuning Options
 # ============================================================================ 
 #  Note: These values aren't necessarily the defaults.
 #
 #ns_param   connsperthread  0         ;# Normally there's one conn per thread
 #ns_param   flushcontent    false     ;# Flush all data before returning
 #ns_param   maxconnections  100       ;# Max connections to put on queue
 #ns_param   maxdropped      0         ;# Shut down if dropping too many conns
 #ns_param   maxthreads      20        ;# Tune this to scale your server
 #ns_param   minthreads      0         ;# Tune this to scale your server
 #ns_param   threadtimeout   120       ;# Idle threads die at this rate

Option	Type	Default
connsperthread	int	0, means: thread runs unlimited number of connections
flushcontent	bool	false
maxconnections	int	100
maxthreads	int	10
minthreads	int	0
threadtimeout	int	120

ADP (AOLserver Dynamic Page) configuration

 # ============================================================================
 # ADP (AOLserver Dynamic Page) configuration
 # ============================================================================
 ns_section "ns/server/${servername}/adp"
 ns_param   map             "/*.adp"  ;# Extensions to parse as ADP's.
 # I18N Note: will need to define I18N specifying mappings of ADP's here as well.
 ns_param   map             "/*.u_adp"
 ns_param   map             "/*.gb_adp"
 ns_param   map             "/*.sjis_adp"
 #ns_param   map             "/*.html" ;# Any extension can be mapped.
 ns_param   enableexpire    false     ;# Set "Expires: now" on all ADP's.
 ns_param   enabledebug     false     ;# Allow Tclpro debugging with "?debug".
 # ADP special pages
 #ns_param   errorpage      ${serverdir}/${pageroot}/errorpage.adp ;# ADP error page.

 ns_section "ns/server/${servername}/adp/compress"
 ns_param   enable          yes
 ns_param   level           4
 ns_param   minsize         0

Socket driver module (HTTP)

 # ============================================================================
 # Socket driver module (HTTP)  -- nssock
 # ============================================================================
 ns_section "ns/server/${servername}/module/nssock"
 ns_param   port            $httpport
 ns_param   hostname        $hostname
 ns_param   address         $address
 #ns_param   maxinput           1024000  ;# Max upload size
 #ns_param   maxline           4096     ;# Max line size
 #ns_param   bufsize        16000    ;# Read-ahead buffer size

Socket driver logging controls

 # ============================================================================
 # Socket driver logging controls. Default is no logging.
 # ============================================================================
 #ns_param   readtimeoutlogging    true  ;# Timed-out waiting for complete
                                          # request.
 #ns_param   serverrejectlogging   true  ;# Unable to match request to a virtual
                                          # server.
 #ns_param   sockerrorlogging      true  ;# Malformed request, or would exceed
                                          # request limits.
 #ns_param   sockshuterrorlogging  true  ;# Error while attempting to shutdown
                                         # a socket during connection close.

Global Fast Path

 # ============================================================================
 # Global Fast Path Configuration
 # ============================================================================
 #
 #     Fast path configuration is used to configure options used for serving
 #     static content.
 #
 # Parameters:
 #
 #     cache               Boolean. Enable cache for normal URLs.
 #                         Optional, default is false.
 #
 #     cachemaxsize        Integer. Size of fast path cache.
 #                         Optional, default is 5120000.
 #
 #     cachemaxentry       Integer. Largest file size allowed in cache.
 #                         Optional, default is cachemaxsize / 10.
 #
 #     mmap                Boolean. Use mmap() for cache. (when cache is false)
 #                         Optional, default is false.
 #
 #     gzip_static         Boolean. Return gzip-ed variant, if available and 
 #                         allowed by client, default is false.
 #
 #                         When a file path/foo.ext is requested, and there 
 #                         exists a file path/foo.ext.gz, and the timestamp of 
 #                         the gzip-ed file is equal or newer than the source file,
 #                         use the gzip-ed file for delivery.
 #
 #     gzip_refresh        Boolean. Refresh stale .gz files on the fly using 
 #                         ::ns_gzipfile, default is false.
 #
 #     gzip_cmd            Command for gzip-ing files, used by ::ns_gzipfile.
 #
 #
 # Example:
 #
 #     ns_section "ns/fastpath"
 #     ns_param    cache                 true
 #     ns_param    gzip_static           true
 #     ns_param    gzip_refresh          true
 #     ns_param    gzip_cmd              "/usr/bin/gzip -9"
 #
 # See also:
 #
 #     /naviserver/nsd/fastpath.c
 #     /naviserver/tcl/fastpath.tcl

Per-server Fast Path

 # ============================================================================
 # Per-server Fast Path Configuration
 # ============================================================================
 #
 #     Fast path configuration is used to configure options used for serving
 #     static content, and also provides options to automatically display
 #     directory listings.
 #
 # Parameters:
 #
 #     serverdir           Defines absolute path to server's home directory
 #
 #     pagedir             Defines absolute or relative to serverdir directory
 #                         where all html/adp pages are located
 #
 #     directoryfile       String. Directory index/default page to
 #                         look for. Optional, default is directoryfile
 #                         parameter set in ns/server/${servername} section.
 #
 #     directorylisting    String. Directory listing style. Optional,
 #                         Can be "fancy" or "simple".
 #
 #     directoryproc       String. Name of Tcl proc to use to display
 #                         directory listings. Optional, default is to use
 #                         _ns_dirlist. You can either specify directoryproc,
 #                         or directoryadp - not both.
 #
 #     directoryadp        String. Name of ADP page to use to display
 #                         directory listings. Optional. You can either 
 #                         specify directoryadp or directoryproc - not both.
 #
 # Example:
 #
 #     ns_section "ns/server/${servername}/fastpath"
 #     ns_param    directorylisting      fancy
 #     ns_param    serverdir             ${serverdir}
 #     ns_param    pagedir               ${pageroot}
 #
 # See also:
 #
 #     /naviserver/nsd/fastpath.c
 #     /naviserver/tcl/fastpath.tcl

Access Log

Command: ns_accesslog

 # ============================================================================
 # Access log -- nslog module
 # ============================================================================
 ns_section "ns/server/${servername}/module/nslog"
 ns_param   rolllog         true                       ;# Should we roll log?
 ns_param   rollonsignal    true                       ;# Roll log on SIGHUP.
 ns_param   rollhour        0                          ;# Time to roll log.
 ns_param   rollfmt         "%Y-%m-%d-%H:%M"           ;# Renames access.log
 ns_param   maxbackup       5                          ;# Max number to keep around when rolling.
 ns_param   logreqtime      true                       ;# Log the execution time of request
 ns_param   file            "access-${servername}.log" ;# path to the log file
 ns_param   formattedtime   true                       ;# true=common log format
 ns_param   logcombined     false                      ;# true==NCSA combined format
 ns_param   maxbuffer       0                          ;# Max number of lines to keep in the buffer before flushing to disk
 ns_param   suppressquery   false                      ;# true==Do not show query string in the log
 ns_param   checkforproxy   false                      ;# true==check for X-Forwarded-For header
 ns_param   extendedheaders "Host Referer X-Forwarded-For"  ;# Tcl list of additional headers

Option	Type	Default
rolllog	bool	?
rollonsignal	bool	?
rollhour	int	0
rollfmt	string	?
maxbackup	int	100
logreqtime	bool	?
file	string	"access.log", created in module specific directory
formattedtime	bool	? ; true=common log format
logcombined	bool	? ; true=NCSA combined format
maxbuffer	int	0
suppressquery	bool	?
checkforproxy	bool	?
extendedheaders	list	no default, expects a TCL list of names

CGI interface

 # ============================================================================
 # CGI interface -- nscgi
 # ============================================================================
 #  WARNING: These directories must not live under pageroot.
 #
 ns_section "ns/server/${servername}/module/nscgi"
 ns_param   interps           CGIinterps ;# name the interpreters section
 ns_param   environment       CGIenvironment ;# name the environment section
 ns_param   systemenvironment false ;# copy environment from nsd start shell?
 ns_param   map               "GET  /cgi /usr/local/cgi"     ;# CGI script file dir (GET).
 ns_param   map               "POST /cgi /usr/local/cgi"     ;# CGI script file dir (POST).
 ns_param   maxinput          [expr {10*1024}] ;# bytes allowed from external process
 ns_param   limit             0       ;# number of concurrent CGI processes
 ns_param   maxwait           30      ;# maximum number of time to wait for CGI execution
 ns_param   gethostbyaddr     0       ;# do reverse DNS lookups?

 # Windows Examples
 ns_section ns/interps/CGIinterps
 ns_param    .pl                     "c:\\PROGRA~1\\perl\\bin\\perl.exe"
 ns_param    .bat                    "c:\\winnt\\system32\\start.exe"
 ns_param    .sh                     "c:\\cygwin\\bin\\bash.exe"

 # ..or Linux
 ns_param    .pl                     "/usr/bin/perl"
 ns_param    .py                     "/usr/bin/python"

 # Examples
 ns_section ns/environment/CGIenvironment
 ns_param    variable_a       value-of-variable_a
 ns_param    variable_b       value-of-variable_b

Option	Type	Default
stacksize	int	64*1024
maxinput	int	1024000
limit	int	0
maxwait	int	30
gethostbyaddr	int	0

TCL library

 ns_section "ns/server/${servername}/tcl"
 ns_param   library  "/www/${servername}/tcl"
 #ns_param   initfile ""
 #ns_param   nsvbuckets 8

Option	Type	Default
library	string	(...?)tcl
initfile	string	(...?)bin/init.tcl
nsvbuckets	int	8

Database configuration

TODO

Modules to load

 # ============================================================================
 # Modules to load
 # ============================================================================
 ns_section "ns/server/${servername}/modules"
 ns_param nssock ${bindir}/nssock.so
 ns_param nslog ${bindir}/nslog.so
 #ns_param nscgi ${bindir}/nscgi.so
 #ns_param nsperm ${bindir}/nsperm.so

Control port

 # ============================================================================
 # Example: Control port configuration.
 # ============================================================================
 # To enable:
 #  
 # 1. Define an address and port to listen on. For security
 #    reasons listening on any port other then 127.0.0.1 is 
 #    not recommended.
 #
 # 2. Decided whether or not you wish to enable features such
 #    as password echoing at login time, and command logging. 
 #
 # 3. Add a list of authorized users and passwords. The entires
 #    take the following format:
 #
 #    <user>:<encryptedPassword>:
 #
 #    You can use the ns_crypt Tcl command to generate an encrypted
 #    password. The ns_crypt command uses the same algorithm as the 
 #    Unix crypt(3) command. You could also use passwords from the
 #    /etc/passwd file.
 #
 #    The first two characters of the password are the salt - they can be 
 #    anything since the salt is used to simply introduce disorder into
 #    the encoding algorithm.
 #
 #    ns_crypt <key> <salt>
 #    ns_crypt x t2
 #    
 #    The configuration example below adds the user "nsadmin" with a 
 #    password of "x".
 #
 # 4. Make sure the nscp.so module is loaded in the modules section.
 #
 #ns_section "ns/server/${servername}/module/nscp"
 #ns_param address 127.0.0.1        
 #ns_param port 9999
 #ns_param echopassword 1
 #ns_param cpcmdlogging 1
 #
 #ns_section "ns/server/${servername}/module/nscp/users"
 #ns_param user "nsadmin:t2GqvvaiIUbF2:"
 #
 #ns_section "ns/server/${servername}/modules"
 #ns_param nscp ${bindir}/nscp.so
 #

Host headers based virtual servers

 # ============================================================================
 # Example: Host headers based virtual servers.
 # ============================================================================
 # To enable:
 #
 # 1. Load comm driver(s) globally.
 # 2. Configure drivers as in a virtual server.
 # 3. Add a "servers" section to map virtual servers to Host headers.
 # 4. Ensure "defaultserver" in comm driver refers to a defined
 #    virtual server.
 #
 #ns_section "ns/modules"
 #ns_param   nssock          ${bindir}/nssock.so
 # 
 #ns_section "ns/module/nssock"
 #ns_param   port            $httpport
 #ns_param   hostname        $hostname
 #ns_param   address         $address
 #ns_param   defaultserver   server1
 #
 #ns_section "ns/module/nssock/servers"
 #ns_param   server1         $hostname:$httpport
 #
 #
 # Example: Dynamic Host headers based virtual servers.
 #
 # To enable:
 #
 # 1. Enable by setting enabled to true.
 #  2. For each hosted name create directory under ${serverdir}
 # 3. Each virtual host directory should have ${pageroot} subdirectory
 #  
 #  /usr/local/ns/
 #        servers/${servername}
 #                        host.com/
 #                               pages
 #                        domain.net/
 #                               pages
 #
 #
 # Parameters:
 # 
 #  enabled            Enable or disable virtual hosting
 #  hostprefix         Prefix between serverdir and host name
 #  stripport          Remove :port in the Host: header when 
 #                     building pageroot path so Host: www.host.com:80
 #                     will result in pageroot ${serverdir}/www.host.com
 #  stripwww           Remove www. prefix from Host: header
 #                     when building pageroot path so Host: www.host.com
 #                     will result in pageroot ${serverdir}/host.com
 #  hosthashlevel      Hash the leading characters of string into a path, skipping
 #                     periods and slashes. If string contains less characters than
 #                     levels requested, '_' characters are used as padding.
 #                     For example, given the string 'foo' and the levels 2, 3:
 #                     foo, 2 -> /f/o
 #                     foo, 3 -> /f/o/o
 #
 #ns_section      "ns/server/${servername}/vhost"
 #ns_param        enabled                 true
 #ns_param        hostprefix              ""
 #ns_param        hosthashlevel           0
 #ns_param        stripport               true
 #ns_param        stripwww                true

Multiple connection thread pools

 # ============================================================================
 # Example:  Multiple connection thread pools.
 # ============================================================================
 # To enable:
 # 
 # 1. Define one or more thread pools.
 # 2. Configure pools as with the default server pool.
 # 3. Map method/URL combinations to the pools
 # 
 # All unmapped method/URL's will go to the default server pool.
 # 
 #ns_section ns/server/server1/pools
 #ns_section slow "Slow requests here."
 #ns_section fast "Fast requests here." 
 #
 #ns_section ns/server/server1/pool/slow
 #ns_param map {POST /slowupload.adp}
 #ns_param maxconnections  100       ;# Max connections to put on queue
 #ns_param maxdropped      0         ;# Shut down if dropping too many conns
 #ns_param maxthreads      20        ;# Tune this to scale your server
 #ns_param minthreads      0         ;# Tune this to scale your server
 #ns_param threadtimeout   120       ;# Idle threads die at this rate
 #
 #ns_section ns/server/server1/pool/fast
 #ns_param map {GET /faststuff.adp}
 #ns_param maxthreads 10
 #

Internal redirects to custom error pages

 ns_section  ns/server/${servername}/redirects
 ns_param    400    "/errorpages/400.html"     ;# 400 (Bad Request) error page
 ns_param    404    "/errorpages/404.html"     ;# 404 (File not found) error page
 ns_param    505    "/errorpages/505.html"     ;# 505 (HTTP Version not supported) error page
 ...

Web based stats interface

 # ============================================================================
 # Example:  Web based stats interface.
 # ============================================================================
 # To enable:
 #
 # 1. Configure whether or not stats are enabled. (Optional: default = false)
 # 2. Configure URL for statistics. (Optional: default = /_stats)
 #
 #    http://<host>:<port>/_stats
 # 
 # 3. Configure user. (Optional: default = naviserver)
 # 4. Configure password. (Optional: default = stats)
 #
 # For added security it is recommended that configure your own
 # URL, user, and password instead of using the default values.
 #
 #ns_section ns/server/stats
 #ns_param enabled 1
 #ns_param url /naviserver/stats
 #ns_param user nsadmin
 #ns_param password 23dfs!d

Category NaviServer