This is just an HTMLized version of config.h.
CGI programs must match this pattern to get executed. It's a simple shell-style filename pattern, with ? and *, or multiple such patterns separated by |. The patterns get checked against the filename part of the incoming URL.
Restricting CGI programs to a single directory lets the site administrator review them for security holes, and is strongly recommended. If there are individual users that you trust, you can enable their directories too.
You can also specify a CGI pattern on the command line, with the -c flag. Such a pattern overrides this compiled-in default.
If no CGI pattern is specified, neither here nor on the command line, then CGI programs cannot be run at all. If you want to disable CGI as a security measure that's how you do it, just don't define any pattern here and don't run with the -c flag.
Some sample patterns.
How many seconds to allow CGI programs to run before killing them. This is in case someone writes a CGI program that goes into an infinite loop, or does a massive database lookup that would take hours, or whatever. If you don't want any limit, comment this out, but that's probably a really bad idea.
A typical value is 300.
How many seconds to allow for reading the initial request on a new connection. A typical value is 300.
How many seconds before an idle connection gets closed. A typical value is 300.
The syslog facility to use. Using this you can set up your syslog.conf so that all thttpd messages go into a separate file. Note that even if you use the -l command line flag to send logging to a file, errors still get sent via syslog. A typical value is LOG_DAEMON.
Tilde mapping. Many URLs use ~username to indicate a user's home directory. thttpd provides two options for mapping this construct to an actual filename.
1) Map ~username to <prefix>/username. This is the recommended choice. Each user gets a subdirectory in the main chrootable web tree, and the tilde construct points there. The prefix could be something like "users", or it could be empty. See also the makeweb program for letting users create their own web subdirectories.
2) Map ~username to <user's homedir>/<postfix>. The postfix would be the name of a subdirectory off of the user's actual home dir, something like "public_html". This is what NCSA and other servers do. The problem is, you can't do this and chroot() at the same time, so it's inherently a security hole. This is strongly dis-recommended, but it's here because some people really want it. Use at your own risk.
You can also leave both options undefined, and thttpd will not do anything special about tildes. Enabling both options is an error.
Typical values, if they're defined, are "users" for TILDE_MAP_1 and "public_html" for TILDE_MAP_2.
The file to use for authentication. If this is defined then thttpd checks for this file in the local directory before every fetch. If the file exists then authentication is done, otherwise the fetch proceeds as usual.
If you leave this undefined then thttpd will not implement authentication at all and will not check for auth files, which saves a bit of CPU time.
A typical value is ".htpasswd".
The default character set name to use with text MIME types. This gets substituted into the MIME types where they have a "%s".
You can override this in the config file with the "charset" setting, or on the command like with the -T flag.
A typical value is "UTF-8".
This controls the SERVER_NAME environment variable that gets passed to CGI programs. By default thttpd does a gethostname(), which gives the host's canonical name. If you want to always use some other name you can define it here.
Alternately, if you want to run the same thttpd binary on multiple machines, and want to build in alternate names for some or all of them, you can define a list of canonical name to altername name mappings. thttpd seatches the list and when it finds a match on the canonical name, that alternate name gets used. If no match is found, the canonical name gets used.
If both SERVER_NAME and SERVER_NAME_LIST are defined here, thttpd searches the list as above, and if no match is found then SERVER_NAME gets used.
In any case, if thttpd is started with the -h flag, that name always gets used.
Undefine this if you want thttpd to hide its specific version when returning into to browsers. Instead it'll just say "thttpd" with no version.
Define this if you want to always chroot(), without having to give the -r command line flag. Some people like this as a security measure, to prevent inadvertant exposure by accidentally running without -r. You can still disable it at runtime with the -nor flag.
Define this if you want to always do virtual hosting, without having to give the -v command line flag. You can still disable it at runtime with the -nov flag.
If you're using the vhost feature and you have a LOT of virtual hostnames (like, hundreds or thousands), you will want to enable this feature. It avoids a problem with most Unix filesystems, where if there are a whole lot of items in a directory then name lookup becomes very slow. This feature makes thttpd use subdirectories based on the first characters of each hostname. You can set it to use from one to three characters. If the hostname starts with "www.", that part is skipped over. Dots are also skipped over, and if the name isn't long enough then "_"s are used. Here are some examples of how hostnames would get turned into directory paths, for each different setting:
1: www.acme.com -> a/www.acme.com 1: foobar.acme.com -> f/foobar.acme.com 2: www.acme.com -> a/c/www.acme.com 2: foobar.acme.com -> f/o/foobar.acme.com 3: www.acme.com -> a/c/m/www.acme.com 3: foobar.acme.com -> f/o/o/foobar.acme.com 3: m.tv -> m/t/v/m.tv 4: m.tv -> m/t/v/_/m.tv
Note that if you compile this setting in but then forget to set up the corresponding subdirectories, the only error indication you'll get is a "404 Not Found" when you try to visit a site. So be careful.
Define this if you want to always use a global passwd file, without having to give the -P command line flag. You can still disable it at runtime with the -noP flag.
When started as root, the default username to switch to after initializing. If this user (or the one specified by the -u flag) does not exist, the program will refuse to run. A typical values is "nobody".
When started as root, the program can automatically chdir() to the home directory of the user specified by -u or DEFAULT_USER. An explicit -d still overrides this.
If this is defined, some of the built-in error pages will have more explicit information about exactly what the problem is. Some sysadmins don't like this, for security reasons.
Subdirectory for custom error pages. The error filenames are $WEBDIR/$ERR_DIR/err%d.html - if virtual hosting is enabled then $WEBDIR/hostname/$ERR_DIR/err%d.html is searched first. This allows different custom error pages for each virtual hosting web server. If no custom page for a given error can be found, the built-in error page is generated. If ERR_DIR is not defined at all, only the built-in error pages will be generated.
Define this if you want a standard HTML tail containing $SERVER_SOFTWARE and $SERVER_ADDRESS to be appended to the custom error pages. (It is always appended to the built-in error pages.)
nice(2) value to use for CGI programs. If this is left undefined, CGI programs run at normal priority. A typical value, if defined, is 10.
$PATH to use for CGI programs. A typical value is "/usr/local/bin:/usr/ucb:/bin:/usr/bin".
If defined, $LD_LIBRARY_PATH to use for CGI programs. A typical value, if defined, is "/usr/local/lib:/usr/lib".
How often to run the occasional cleanup job. A typical value is 120 (two minutes).
Seconds between stats syslogs. If this is undefined then no stats are accumulated and no stats syslogs are done. A typical value is 3600 (an hour).
The mmap cache tries to keep the total number of mapped files below this number, so you don't run out of kernel file descriptors. If you have reconfigured your kernel to have more descriptors, you can raise this and thttpd will keep more maps cached. However it's not a hard limit, thttpd will go over it if you really are accessing a whole lot of files. A typical value is 2000.
The mmap cache also tries to keep the total mapped bytes below this number, so you don't run out of address space. Again it's not a hard limit, thttpd will go over it if you really are accessing a bunch of large files. A typical value is 1000000000.
When throttling CGI programs, we don't know how many bytes they send back to the client because it would be inefficient to interpose a counter. CGI programs are much more expensive than regular files to serve, so we set an arbitrary and high byte count that gets applied to all CGI programs for throttling purposes.
A typical value is 200000.
The default port to listen on. 80 is the standard HTTP port.
A list of index filenames to check. The files are searched for in this order. A typical value is "index.html", "index.htm", "index.cgi".
If this is defined then thttpd will automatically generate index pages for directories that don't have an explicit index file. If you want to disable this behavior site-wide, perhaps for security reasons, just undefine this. Note that you can disable indexing of individual directories by merely doing a "chmod 711" on them - the standard Unix file permission to allow file access but disable "ls".
Whether to log unknown request headers. Most sites will not want to log them, which will save them a bit of CPU time.
Whether to fflush() the log file after each request. If this is turned off there's a slight savings in CPU cycles.
Time between updates of the throttle table's rolling averages. A typical value is 60.
The listen() backlog queue length. The 1024 doesn't actually get used, the kernel uses its maximum allowed value. This is a config parameter only in case there's some OS where asking for too high a queue length causes an error. Note that on many systems the maximum length is way too small - see http://www.acme.com/software/thttpd/notes.html
Maximum number of throttle patterns that any single URL can be included in. This has nothing to do with the number of throttle patterns that you can define, which is unlimited. A typical value is 50.
Number of file descriptors to reserve for uses other than connections. Currently this is 5, representing one for the listen fd, one for dup()ing at connection startup time, one for reading the file, one for syslog, and one possibly for the log file.
How many milliseconds to leave a connection open while doing a lingering close. A typical value is 500.
Maximum number of symbolic links to follow before assuming there's a loop. A typical value is 32.
You don't even want to know.
