Martin's Server Suite
 

Snug HTTP server - Configuration


The configuration file

The configuration is stored in a single file. The default configuration file is named snug.ini. The file should be opened and edited with a standard text editor, such as notepad or vi. You must not edit text to the left of the equal sign (=) and you must not remove the equal sign. All lines beginning with a semicolon (;) in the first column is treated as a comment. A general rule is to use the default value if uncertain. Not all parameters are of interest for all users. Tha last AddVirtual is enough for most users to change. AddVirtual sets the default web root. If a parameter that was needed is missing the server will write an error message to stderr (probably the console) and if possible, assign a default value to the parameter. A tip is to use the default configuration file as a starting point.


LogMaxEntries

The log will rotate if the log exceeds LogMaxEntries entries. One completed request generates one entry in the log file. Setting LogMaxEntries=0 allows unlimited number of entries.


LogMaxAge

The log will rotate if the file age exceeds LogMaxAge hours. If you specify LogMaxAge=24 the log will rotate once every day.


LogRotation

If LogRotation is 0, no log will be written. A new file will be created or the log will rotate when the criteria for LogMaxAge or LogMaxEntries is fullfilled. The log will rotate (old log files will be overwritten) when a number of files specified by LogRotation is reached. Maximum number of allowed logfiles is 9999. If you specify a number larger than 9999, LogRotation will be set to 9999.


LogDir

LogDir is the folder where the log files will be placed. Each file will be named log0001.log, log0002.log, log0003.log and so on.Leaving the Log entry empty will most likely place the log files in the working directory of the server process, this depends on your environment settings. If the searchpath exceeds its maximum length, an error will be displayed and the log will be dissabled. If you set LogDir=CONSOLE and LogRotation=1, log will be written to stdout (usually the console if not redirected to a file). Log files can be placed in the web root directory. It is recommended to password protect the log directory in that case. Read on to see how password protection is applied.


ExtendedMessages

Extended error messages will be enabled if ExtendedMessages=1. This is usefull for diskless operation of error messages and debugging your site. The message returned to the client is generated by the server and cannot be changed. If ExtendedMessages=0, the err directory should be copied to the default web root directory given by the last AddVirtual. Even if ExtendedMessages=0 and custom error pages is used the server can return a default error message of possible 500. The htm-files in the err directory are plain html documents. The documents can be modified but any images and other files refered to in the html-files must be located under the default webroot (the last AddVirtual).


Port

The default listening port for www services is 80. You can make the server listening on port 6666 with Port=6666 If you choose a port that is not valid or already in use, the program will display an error at initialization.


Address

You can specify an address with Address=xxx.xxx.xxx.xxx, where xxx.xxx.xxx.xxx is the IPv4 address of the NIC (Network Interface Card) and xxx is a one to three digit number. If you enter a non-valid address, the program will display an error at initialization. You can also use Address=AUTO;eth0 for IP address auto detection of address bound to interface eth0. eth0 can be replaces with eth1, lo0 or any working interface. If AUTO fails, Address will be set to 127.0.0.1 and the server will continue reading the configuration.


ExternIP

A gateway is a network point that acts as an entrance to another network. If you are using a gateway you must specify ExternIP which is the public address facing the other network (for example the Internet). If you don't use a gateway you should specify the same address as in Address. You can use AUTO to set ExternIP=Address. http:// will be added to ExternIP if AUTO is used. ExternIP can optionaly be an URL (usually the case). Remember to add the public listening port number to the URL if not 80 (default for www services). ExternIP=http://xelectrox.homeip.net:1734. The maximum length of values to ExternIP is limited. Remember the preceding http:// f you specifies an IP address (for example: ExternIP=http://192.168.0.7). You will receive an error if you exceeds the limit.


Timeout

To prevent connections from becoming idle and taking up valuable system resources you must specify a timeout time. Clients who have been idle (0 bytes sent and 0 bytes received for Timeout seconds) will be disconnected. Specify the timeout time with Timeout=xx, where xx is the timeout time in seconds. The server checks for idle connections after Timeout seconds or if the number of connections is MaxConnections and after approximately every 50th connection made to the server. Use the default value if you are uncertain what timeout-time to use. Timeout with value 0 can be used which will disable the timeout feature (not recommended).


AddAllowedReferer

This feature may not be available in later versions of the server!
AddAllowedReferer basicly tells whether files can be directly linked to from external resources. If no AddAllowedReferer is given, no restrictions is applied. AddAllowedReferer=http://www.google.com tells the server that all resources linked from http://www.google.com is allowed to access. To disable referer restrictions (recommended for most users) remove or out-comment all AddAllowedReferer in the configuration file. This feature offers protection against direct linking. Exceptions are files marked as index-files with AddIndex. However, it is not possible to directly link or surf to http://127.0.0.1/index.htm. A user must access the site with http://127.0.0.1/ letting the server decide what index-file to send. If the server can't find an index-file the server will respond with a 403 Forbidden message. 127.0.0.1 is the localhost address and is only used as an example. It is recommended to add the machines local IP address or the WAN IP as allowed referer. AddAllowedReferer= can be zero length.


MaxConnections

The server can handle a limited number of connections simultaneously. The maximum value is operating system dependent. A safe maximum for most system is 63 connections. specify themaximum number of connections with MaxConnections=xx, where xx is the maximum number of connections the server will accept simultaneously. Low-end systems may need a low value.


DirectoryListing

A powerfull feature is the directory listing feature. This allows the connected client to receive a dynamicly created html document containing a directory listing of the desired directory. The directory listing includes detailed information about files and directories. Enable or disable the directory listing feature with DirectoryListing=1 respective DirectoryListing=0. Also see Addforbidden, AddHidden, ShowProtectedFiles and AddUser.

ShowProtectedFiles

You can choose whether you want to show password protected files in the directory listing or not. Files marked simply as forbidden (see Forbidden) without user authentication (see AddUser) will not be shown.


AddIndex

An index page is the first page that is loaded and sent to the client if no filename was specified in the request. If no index page exists and if the directory listing feature is enabled (see DirectoryListing), a directory listing will be sent back. Index pages is traditionaly named index.htm or index.html. Add for example picture.png as an index page with AddIndex=picture.png. The most commonly used index file should be placed first for best performance.


AddType

MIME Types represent file types as presented to a web browser. Add MIME types with AddType=.xxx;xxxxx, where .xxx is the file extension (for example .txt) and xxxxx is the MIME-type. Default MIME-type is application/octet-stream.

AddType=.htm;text/htmlAddType=.html;text/html
AddType=.gif;image/gifAddType=.jpg;image/jpeg
AddType=.txt;text/plainAddType=.css;text/css




AddForbidden

It may be necessary to specify strings or single characters that may not occur in the file names. Protect a resource with AddForbidden=xxxx, where xxxx is the string that may not occur in file names. If you specify AddForbidden=a all files with an a will be marked as forbidden and thus not accessible. However, if you specify AddForbidden=a;user, only the user called user will have access to all public files with an a in its file name (see AddUser for more information on how to add a user). The server use basic authentication for access control. Below follows a list with valid AddForbidden entries.

; All directories or files with program.com in its name will not be accesible.
AddForbidden=program.com

; All folders named forbidden will be inaccessible.
AddForbidden=/forbidden/

; All directories or files with dungeon in its name requires
; athentication (only user dragon will have access).
AddForbidden=dungeon;dragon

; All content on the server requires authentication and is
; only accessible for user x.
AddForbidden=;x

; File /www/files/pictures.zip is marked forbidden.
AddForbidden=/www/files/pictures.zip


The server searches the list of AddForbidden entries from the beginning and uses the first one that requires authentication to access the requested resource. This can be used to password protect files on different levels in the directory tree using two-step authentication. Pretend that /Windows/System is requested. Adding both System and Windows to the configuration will require authentication in two step for /Windows/System. System must be placed over Windows in the list of protected files for this to work.

AddForbidden=/System/;user2
AddForbidden=/Windows/;user1

; And the users.
AddUser=user1;password1
AddUser=user2;password2



AddUser

You can password protect resources on the server with AddUser in combination with AddForbidden. AddUser=user;pass will create a user with the name user and the password pass. Only characters A-Z, a-z, 0-9 and +, / and = can be used in user names and passwords. Below follows a short list of valid AddUser entries.

; User x without password.
AddUser=x;

; User x with password X set.
AddUser=x;X
; User Setag+Llib with password *NIX rules!

AddUser=Setag+Llib;NIX rules!



AddVirtual

Use AddVirtual to add virtual folders or alias. Virtual folders cannot contain characters that needs URL encoding (white spaces etc.). Use a-z, A-Z and 0-9 to be on the safe side. The program checks if the virtual folder is present in the first part of name of the requested resource. The default webroot directory is specified using the last AddVirtual in the configuration file as AddVirtual=/;/home/www, where /home/www is the webroot.The server can serve content spread over different partitions or drives. If you wish to make the content of drive D:\ accessible as /DDRIVE/, you should specify AddVirtual=/DDRIVE/;D:\. Note, the last AddVirtual statement must start with AddVirtual=/; and cannot be placed before any other AddVirtual statements.

; DOS, Windows and OS/2:
AddVirtual=/www2/;d:\www
AddVirtual=/www2again/;d:\www
AddVirtual=/;c:\www

; UNIX, BeOS and Linux:
AddVirtual=/;/home; AROS:
AddVirtual=/;sys:www



AddHost

AddHost is used to enable name-based virtual hosts. Use AddHost=host;root, where host is a valid host name and root is the root directory associated with the host name. In reality, Both AddHost and AddVirtual are used to determine what root directory to be accessed. The result for AddHost is based on the host name and AddVirtual uses the URL to determine root directory. AddHost=www.hostname.nu;c:\www and AddVirtual=/;c:\www will accomplish the exact same thing. AddForbidden and AddUser applies to AddHost. A typical configuration uses / or \ in the parameter to AddForbidden to specify a folder. / and \ can't be present in a host name. Typical host names are www.w3.org and lenny.nu. By using AddHost=lenny.nu;c:\lenny's host, AddForbidden=lenny.nu;lenny and AddUser=lenny;pass, lenny.nu will be password protected with username lenny and password pass. Also all files with the string lenny.nu in its filename will be password protected. The last AddHost in the main configuration is treated as the default host. AddVirtual is only applicable on the default host. This also means that if you specify only one AddHost in the main configuration file causes the server to use the last (default) AddVirtual instead. The path section of the last AddHost is not used but needs to be there.


AddInterpreter

The server need to know two things for scripting to be enabled. First it need to know what interpreters to use and what files to be associated with that interpreter. This is done by using the AddInterpreter= in the main configuration file. The interpreter must be set to work in CLI (Command Line Interface) mode. If for example cgi-php.exe should be used with php files (files with MIME-type application/x-httpd-php), AddInterpreter=c:\php\cgi-php.exe;application/x-httpd-php can be used. The MIME-type for a php file is application/x-httpd-php. So by using AddType=.php;application/x-httpd-php the server will put all files ending with .php through the interpreter. If no interpreters are added to the configuration, scripting will be disabled. To put all files through a interpreter named filter.exe, leave out the MIME part of AddInterpreter; AddInterpreter=filter.exe;.
See the section about CGI for more information.


AddCustomEnvironment

AddCustomEnvironment is used for interpreters and scripts that needs special environment variables set.AddCustomEnvironment=REDIRECT_STATUS;200 will add the environment variable REDIRECT_STATUS=200 for all successfull CGI request, regardless of MIME-type.


EnableDebug

By adding EnableDebug=1 in the main configuration file, information is written to the console window. This can be usefull when troubleshooting the server and clients. Client request header, server response header and server response body can be viewed in the console. Server response body is only written if returned status code is not in the 200 range.