[http://naviserver.sourceforge.net/ns_logobig.gif] [NaviServer%|%Main%|%] ✸ http://bitbucket.org/naviserver/naviserver/%|%Source Code %|% ✸ http://sourceforge.net/project/showfiles.php?group_id=130646%|%Downloads %|% ✸ http://naviserver.sourceforge.net/n/toc.html%|%API Documentation %|% ✸ http://sourceforge.net/mail/?group_id=130646%|%Mailing Lists%|% ✸ http://sourceforge.net/tracker/?group_id=130646&atid=719006%|%Bugs %|% ✸ https://www.ohloh.net/p/naviserver/contributors%|%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: # # :: # # 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 # 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://:/_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 <> NaviServer