Annotated AOLserver Configuration Reference

[ Please make comments on the Talk:Annotated_AOLserver_Configuration_Reference page. ]

    #
    # config-reference.tcl.txt --
    #
    #      Annotated AOLserver Configuration Reference
    #
    #      Nearly every AOLserver configuration variable is represented
    #      here.  This file is provided as a reference -- please do not load
    #      this into your server.
    #
    
    #
    # Global parameters
    #
    ns_section "ns/parameters"
    ns_param   home            $home     ;# Server's home directory
       
    # Limits
    ns_param   listenbacklog   32        ;# Max length of pending conn queue
    ns_param   schedmaxelapsed 2         ;# Warn when waiting on really long procs
    ns_param   shutdowntimeout 20        ;# Secs to wait on shutdown if open conns
    
    # Server logging
    ns_param   dev             true      ;# Display logging with "Dev" severity
    ns_param   debug           false     ;# Display logging with "Debug" severity
    ns_param   logexpanded     false     ;# true = double-spaced server.log
    ns_param   logroll         false     ;# Roll server.log every 24 hours.
    ns_param   maxbackup       10        ;# Max number of old server.log files
    ns_param   pidfile         "nspid"   ;# PID of server (named "nspid.PORT")
    ns_param   serverlog       "server.log" ;# Filename of server.log
    
    # DNS tuning
    ns_param   dnscache        true      ;# In-memory cache of DNS lookups
    ns_param   dnscachetimeout 60        ;# How long to keep hostnames in cache
    
    # Miscellaneous
    ns_param   mailhost        smtp.yourcompany.com ;# SMTP host for ns_sendmail
    
    
    #
    # Thread library (nsthread) parameters
    #
    ns_section "ns/threads"
    ns_param   mutexmeter      true      ;# measure lock contention
    ns_param   stacksize       [expr 128*1024]  ;# stack size per thread (in bytes)
    
    
    #
    # MIME types.
    #
    # Note: AOLserver 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   ".xls"          "application/vnd.ms-excel"
    ns_param   default         "*/*"     ;# MIME type for unknown extension
    ns_param   noextension     "*/*"     ;# MIME type for missing extension
    
    
    ############################################################
    #
    # Server-level configuration
    #
    #  There is only one server in AOLserver, 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.
    #
    
    ns_section "ns/servers"
    ns_param   $server         $servername ;# Name of virtual server.
    
    #
    # Server parameters
    #
    ns_section "ns/server/${servername}"
    ns_param   directoryfile   $directoryfile ;# List of files to use (index.html)
    ns_param   pageroot        $pageroot ;# Directory under which all pages live
    
    # Tuning options
    ns_param   connsperthread  0         ;# Normally there's one conn per thread
    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 timeout for connection threads
    ns_param   maxconnections  100       ;# Max connections per connection thread before it is shut down
    ns_param   spread          20        ;# Variance factor for threadtimeout and maxconnections
                                         ;# to prevent mass mortality of theads (e.g. +-20%) 
    
    # Limits
    ns_param   maxline         8192      ;# Max line length from client
    
    # Directory listings can be generated with an ADP or a Tcl proc.
    ns_param   directoryadp    $home/dirlist.adp  ;# Choose one or the other
    ns_param   directoryproc   _ns_dirlist        ;#  ...but not both!
    ns_param   directorylisting simple   ;# Can be simple or fancy (for ns_dirlist)
    
    # Miscellaneous
    ns_param   checkmodifiedsince true   ;# Check url if no If-Modified-Since?
    ns_param   enableaolpress  false     ;# Enable extra features used by AOLpress
    ns_param   headercase      preserve  ;# tolower, toupper, preserve
    
    #
    # Internal redirects
    #
    ns_section "ns/server/${servername}/redirects"
    ns_param   404 "/notfound.html"      ;# Not Found error page
    ns_param   500 "/servererror.html"   ;# Server Error page
    
    #
    # Fastpath serves HTML
    #
    ns_section "ns/server/${servername}/fastpath"
    ns_param   cache           true      ;# Enable cache for normal URLs; default: false
    ns_param   cachemaxentry   8192      ;# Largest file size allowable in cache; default: cachemaxsize/10
    ns_param   cachemaxsize    [expr 5000*1024] ;# Size of fastpath cache; default: 5120000
    ns_param   mmap            false     ;# Use mmap() for cache; default: false
    ns_param   directoryfile   index.adp,index.tcl,index.html,index.htm 
                                         ;# String. Directory index/default page to look for. 
                                         ;# Optional, default is directoryfile parameter set in 
                                         ;# ns/server/${servername} section.
    ns_param   directorylisting fancy    ;# Directory listing style. 
                                         ;# Optional, can be "fancy" or "simple". 
    ns_param   directoryproc _ns_dirlist ;# 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.
    ;#ns_param directoryadp dir.adp      ;# String. Name of ADP page to use to display directory 
                                         ;# listings. Optional. You can either specify directoryadp 
                                         ;# or directoryproc - not both.
    
    #
    # Tcl interpreter
    #
    ns_section "ns/server/${servername}/tcl"
    ns_param   debug           false     ;# Names of files sourced is logged
    ns_param   nsvbuckets      8         ;# No. of buckets to hold nsv's
    ns_param   library  "$home/servers/${servername}/modules/tcl" ;# Private tcl library for the server
    
    #
    # ADP (AOLserver Dynamic Page) configuration
    #
    ns_section "ns/server/${servername}/adp"
    
    # ADP features
    ns_param   map             "/*.adp"  ;# Extensions to parse as ADP's
    ns_param   map             "/*.html" ;# Any extension can be mapped
    ns_param   enableexpire    true      ;# Set "Expires: now" on all ADP's
    ns_param   enabledebug     true      ;# Turn on Tclpro debugging with "?debug"
    ns_param   debuginit "ns_adp_debuginit" ;# Debug procedure
    
    # ADP tuning
    ns_param   cache           true      ;# In-memory cache of ADP's
    ns_param   cachesize       [expr 5000*1024]
    
    # ADP special pages
    ns_param   errorpage  ${pageroot}/errorpage.adp        ;# Pretty-print ADP errors with an ADP
    ns_param   startpage  ${pageroot}/startpage.inc        ;# Page to include for all ADP's
    
    
    #
    # ADP custom parsers -- see adp.c
    #
    ns_section "ns/server/${servername}/adp/parsers"
    ns_param   adp             ".adp"   ;# The simple parser looks for <\% ... \%>
    ns_param   fancy           ".adp"   ;# The fancy parser does a lot more.
    
    
    #
    # Socket driver module (HTTP)  -- nssock
    #
    ns_section "ns/server/${servername}/module/nssock"
    ns_param   port            $httpport ;# Port for HTTP (typically 80)
    ns_param   hostname        $host     ;# This is not the same as your hostname
    ns_param   address         $address  ;# This is not the same as your host addr
    ns_param   location        "url"     ;# URL for auto-redirects (trailing slash)
    ns_param   maxinput        [expr 5 * 1024 * 1024]  ;# Maximum file size for uploads in bytes, default is 1MB, new in AOLserver 4.01
    ns_param   keepwait        30        ;# Max time conn is kept alive (keepalive)
                                         ;#   (set to 0 to disable keepalive)
    
    #
    # Socket driver module (HTTPS) -- nsssl
    #
    ns_section "ns/server/${servername}/module/nsssl"
    ns_param   port            $httpsport ;# Port for HTTPS (typically 443)
    ns_param   hostname        $host     ;# This is not the same as your hostname
    ns_param   address         $address  ;# This is not the same as your host addr
    ns_param   keyfile         ${home}/servers/${servername}/modules/nsssl/keyfile.pem
    ns_param   certfile        ${home}/servers/${servername}/modules/nsssl/certfile.pem
    
    
    #
    # Control port -- nscp
    #
    ns_section "ns/server/${servername}/module/nscp"
    ns_param   port            9999      ;# Control port listens on port 9999
    ns_param   address         "127.0.0.1" ;# For security, use 127.0.0.1 only
    
    # Control port users
    ns_section "ns/server/${servername}/module/nscp/users"
    # The default password for nsadmin is "x". You should change it.
    # type "ns_crypt newpassword salt" and put the encrypted string below.
    ns_param user "nsadmin:t2GqvvaiIUbF2:" ;# sample user="nsadmin", pw="x".
    
    #
    # Access log -- nslog
    #
    ns_section "ns/server/${servername}/module/nslog"
    ns_param   file            "access.log"
    ns_param   formattedtime   true      ;# true=common log format
    ns_param   logcombined     false     ;# true==NCSA combined format
    ns_param   maxbackup       5         ;# Max number to keep around when rolling
    ns_param   rollhour        0         ;# Time to roll log
    ns_param   rolllog         true      ;# Should we roll log?
    ns_param   rollonsignal    true      ;# Roll log on SIGHUP
    
    #
    # CGI interface -- nscgi
    #
    # Note: CGI is *vastly* inferior to ADP's or even built-in Tcl libraries.
    #
    ns_section "ns/server/${servername}/module/nscgi"
    ns_param   debug           false     ;# Be chatty in log
    ns_param   gethostbyaddr   false     ;# Whether to do reverse DNS lookups
    ns_param   limit           0         ;# Max number of concurrent CGI processes
    ns_param   maxoutput       10240     ;# Max bytes allowed from external process
    ns_param   buffersize      8192      ;# Buffer output from external process
    ns_param   map  "GET /cgi /usr/local/cgi"        ;# Where your CGI executables live (GET)
    ns_param   map  "POST /cgi /usr/local/cgi"       ;# Where your CGI executables live (POST)
    
    # CGI environment variable handling -- See admin guide
    ns_param   systemenvironment false   ;# Copies environment from nsd start shell
    
    
    #
    # Access control (permissions) -- nsperm
    #
    ns_section "ns/server/${servername}/module/nsperm"
    
    #
    # Unix domain socket driver -- nsunix
    #
    ns_section "ns/server/${servername}/module/nsunix"
    ns_param   hostname        "host"    ;# Hostname used in response to client
    ns_param   port            "port"    ;# Port to listen on
    ns_param   socketfile      "path.name" ;# UNIX domain socket driver
    
    #
    # Virtual Hosting redirector -- nsvhr
    #
    ns_section "ns/server/${servername}/module/nsvhr"
    ns_param   busyurl         "url"     ;# Redirect here if back-end times out
    ns_param   errorurl        "url"     ;# Redirect here on proxy errors
    ns_param   method          "GET"     ;# Methods allowed to proxy
    ns_param   method          "POST"    ;# Methods allowed to proxy (can have >1)
    ns_param   timeout         30        ;# Timeout waiting for back-end
    
    # Register hosts to proxy
    ns_section "ns/server/${servername}/module/nsvhr/maps"
    ns_param   "www.tcpsocket.com"    "http://127.0.0.0:2000" ;# HTTP proxy
    ns_param   "www.domainsocket.com" "unix://somehost"       ;# Domain socket
    
    #
    # Database drivers
    #
    # Two pools are given here.  Sybase uses the Sybase client libraries,
    # obtained from Sybase.  Postgres is freely available at
    # www.postgresql.org.  Sybase uses an external proxy daemon while
    # Postgres uses an internal driver.  The Sybase driver requires some
    # configuration in ns/db/driver/sybase_driver to tell th "nsext.so"
    # driver where to find the nssybpd executable and some other things.
    # The Postgres driver doesn't need any of that because it's internal
    # and does not use nsext.so.
    #
    ns_section "ns/db/drivers"
    ns_param   sybase_driver   nsext.so       ;# Use nsext.so for a proxy daemon
    ns_param   postgres_driver nspostgres.so  ;# An internal driver
    
    ns_section "ns/db/driver/sybase_driver"
    ns_param   localdaemon     nssybpd        ;# Name of the proxy daemon executable
    ns_param   param           path_to_sybase ;# Usually the $SYBASE env var
    
    ns_section "ns/db/pools"
    ns_param   sybase_pool    "Sybase Pool"
    ns_param   postgres_pool  "Postgres Pool"
    
    ns_section "ns/db/pool/sybase_pool"
    ns_param   driver          sybase_driver
    ns_param   datasource      SERVER_NAME:database_name
    ns_param   user            user_name
    ns_param   password        password
    ns_param   connections     1
    ns_param   logsqlerrors    true      ;# Verbose SQL query error logging
    ns_param   verbose         false     ;# Verbose error logging
    ns_param   maxidle         600       ;# Max time to keep idle db conn open
    ns_param   maxopen         3600      ;# Max time to keep active db conn open
    
    ns_section "ns/db/pool/postgres_pool"
    ns_param   driver          postgres_driver
    ns_param   datasource      HOSTNAME:PORT:database_name
    ns_param   user            user_name
    ns_param   password        password
    ns_param   connections     1
    ns_param   logsqlerrors    true      ;# Verbose SQL query error logging
    ns_param   verbose         false     ;# Verbose error logging
    ns_param   maxidle         600       ;# Max time to keep idle db conn open
    ns_param   maxopen         3600      ;# Max time to keep active db conn open
    
    
    #
    # Accessing DB pools
    #
    # In the case of virtual servers you can give different virtual
    # servers access to different databases, or you can let them access
    # them all.  AOLserver 3.x does not use virtual servers so the only
    # useful value is "*", but if you use one config file for multiple nsd
    # processes, or you are using a version of AOLserver that supports
    # virtual servers, then you should list the pools you want to access.
    #
    ns_section "ns/server/${servername}/db"
    ns_param pools          *            ;# Wildcard gives access to all
    ns_param defaultpool    sybase_pool
    
    
    #
    # Modules to load
    #
    # Note: Only load the modules you are actually going to use.
    #
    ns_section "ns/server/${servername}/modules"
    ns_param   nssock             nssock.so
    ns_param   nsssl              nsssle.so
    ns_param   nscp               nscp.so
    ns_param   nslog              nslog.so
    ns_param   nscgi              nscgi.so
    ns_param   nsperm             nsperm.so
    
    #
    # Loading a Tcl module
    #
    # This example shows a Tcl module, called "tcl_module", has its code
    # in the AOLserver Tcl library in either the modules/tcl/tcl_module
    # directory or servers/servername/modules/tcl/tcl_module directory.
    #
    ns_param   tcl_module          tcl