1 .TH thttpd 8 "29 February 2000"
3 thttpd - tiny/turbo/throttling HTTP server
41 is a simple, small, fast, and secure HTTP server.
42 It doesn't have a lot of special features, but it suffices for most uses of
43 the web, it's about as fast as the best full-featured servers (Apache, NCSA,
45 and it has one extremely useful feature (URL-traffic-based throttling)
46 that no other server currently has.
50 Specifies a config-file to read.
51 All options can be set either by command-line flags or in the config file.
52 See below for details.
55 Specifies an alternate port number to listen on.
57 The config-file option name for this flag is "port",
58 and the config.h option is DEFAULT_PORT.
61 Specifies a directory to chdir() to at startup.
62 This is merely a convenience - you could just as easily
63 do a cd in the shell script that invokes the program.
64 The config-file option name for this flag is "dir",
65 and the config.h options are WEBDIR, USE_USER_DIR.
68 Do a chroot() at initialization time, restricting file access
69 to the program's current directory.
70 If -r is the compiled-in default, then -nor disables it.
71 See below for details.
72 The config-file option names for this flag are "chroot" and "nochroot",
73 and the config.h option is ALWAYS_CHROOT.
76 Specifies a directory to chdir() to after chrooting.
77 If you're not chrooting, you might as well do a single chdir() with
79 If you are chrooting, this lets you put the web files in a subdirectory
80 of the chroot tree, instead of in the top level mixed in with the
82 The config-file option name for this flag is "data_dir".
85 Don't do explicit symbolic link checking.
86 Normally, thttpd explicitly expands any symbolic links in filenames,
87 to check that the resulting path stays within the original document tree.
88 If you want to turn off this check and save some CPU time, you can use
89 the -nos flag, however this is not recommended.
90 Note, though, that if you are using the chroot option, the symlink
91 checking is unnecessary and is turned off, so the safe way to save
92 those CPU cycles is to use chroot.
93 The config-file option names for this flag are "symlinkcheck" and "nosymlinkcheck".
96 Do el-cheapo virtual hosting.
97 If -v is the compiled-in default, then -nov disables it.
98 See below for details.
99 The config-file option names for this flag are "vhost" and "novhost",
100 and the config.h option is ALWAYS_VHOST.
103 Use a global passwd file.
104 This means that every file in the entire document tree is protected by
105 the single .htpasswd file at the top of the tree.
106 Otherwise the semantics of the .htpasswd file are the same.
107 If this option is set but there is no .htpasswd file in
108 the top-level directory, then thttpd proceeds as if the option was
109 not set - first looking for a local .htpasswd file, and if that doesn't
110 exist either then serving the file without any password.
111 If -g is the compiled-in default, then -nog disables it.
112 The config-file option names for this flag are "globalpasswd" and
114 and the config.h option is ALWAYS_GLOBAL_PASSWD.
117 Specifies what user to switch to after initialization when started as root.
118 The default is "nobody".
119 The config-file option name for this flag is "user",
120 and the config.h option is DEFAULT_USER.
123 Specifies a wildcard pattern for CGI programs, for instance "**.cgi"
125 See below for details.
126 The config-file option name for this flag is "cgipat",
127 and the config.h option is CGI_PATTERN.
130 Specifies a file of throttle settings.
131 See below for details.
132 The config-file option name for this flag is "throttles".
135 Specifies a hostname to bind to, for multihoming.
136 The default is to bind to all hostnames supported on the local machine.
137 See below for details.
138 The config-file option name for this flag is "host",
139 and the config.h option is SERVER_NAME.
142 Specifies a file for logging.
143 If no -l argument is specified, thttpd logs via syslog().
144 If "-l /dev/null" is specified, thttpd doesn't log at all.
145 The config-file option name for this flag is "logfile".
148 Specifies a file to write the process-id to.
149 If no file is specified, no process-id is written.
150 You can use this file to send signals to thttpd.
151 See below for details.
152 The config-file option name for this flag is "pidfile".
155 Specifies the character set to use with text MIME types.
156 The default is UTF-8.
157 The config-file option name for this flag is "charset",
158 and the config.h option is DEFAULT_CHARSET.
161 Specifies a P3P server privacy header to be returned with all responses.
162 See http://www.w3.org/P3P/ for details.
163 Thttpd doesn't do anything at all with the string except put it in the
164 P3P: response header.
165 The config-file option name for this flag is "p3p".
168 Specifies the number of seconds to be used in a "Cache-Control: max-age"
169 header to be returned with all responses.
170 An equivalent "Expires" header is also generated.
171 The default is no Cache-Control or Expires headers,
172 which is just fine for most sites.
173 The config-file option name for this flag is "max_age".
176 Shows the current version info.
179 This was originally just a debugging flag, however it's worth mentioning
180 because one of the things it does is prevent thttpd from making itself
182 Instead it runs in the foreground like a regular program.
183 This is necessary when you want to run thttpd wrapped in a little shell
184 script that restarts it if it exits.
187 All the command-line options can also be set in a config file.
188 One advantage of using a config file is that the file can be changed,
189 and thttpd will pick up the changes with a restart.
191 The syntax of the config file is simple, a series of "option" or
192 "option=value" separated by whitespace.
193 The option names are listed above with their corresponding command-line flags.
196 chroot() is a system call that restricts the program's view
197 of the filesystem to the current directory and directories
199 It becomes impossible for remote users to access any file
200 outside of the initial directory.
201 The restriction is inherited by child processes, so CGI programs get it too.
202 This is a very strong security measure, and is recommended.
203 The only downside is that only root can call chroot(), so this means
204 the program must be started as root.
205 However, the last thing it does during initialization is to
206 give up root access by becoming another user, so this is safe.
208 The program can also be compile-time configured to always
209 do a chroot(), without needing the -r flag.
211 Note that with some other web servers, such as NCSA httpd, setting
212 up a directory tree for use with chroot() is complicated, involving
213 creating a bunch of special directories and copying in various files.
214 With thttpd it's a lot easier, all you have to do is make sure
215 any shells, utilities, and config files used by your CGI programs and
216 scripts are available.
217 If you have CGI disabled, or if you make a policy that all CGI programs
218 must be written in a compiled language such as C and statically linked,
219 then you probably don't have to do any setup at all.
221 However, one thing you should do is tell syslogd about the chroot tree,
222 so that thttpd can still generate syslog messages.
223 Check your system's syslodg man page for how to do this.
224 In FreeBSD you would put something like this in /etc/rc.conf:
226 syslogd_flags="-l /usr/local/www/data/dev/log"
228 Substitute in your own chroot tree's pathname, of course.
229 Don't worry about creating the log socket, syslogd wants to do that itself.
230 (You may need to create the dev directory.)
231 In Linux the flag is -a instead of -l, and there may be other differences.
233 Relevant config.h option: ALWAYS_CHROOT.
236 thttpd supports the CGI 1.1 spec.
238 In order for a CGI program to be run, its name must match the pattern
239 specified either at compile time or on the command line with the -c flag.
240 This is a simple shell-style filename pattern.
241 You can use * to match any string not including a slash,
242 or ** to match any string including slashes,
243 or ? to match any single character.
244 You can also use multiple such patterns separated by |.
245 The patterns get checked against the filename
246 part of the incoming URL.
247 Don't forget to quote any wildcard characters so that the shell doesn't
250 Restricting CGI programs to a single directory lets the site administrator
251 review them for security holes, and is strongly recommended.
252 If there are individual users that you trust, you can enable their
255 If no CGI pattern is specified, neither here nor at compile time,
256 then CGI programs cannot be run at all.
257 If you want to disable CGI as a security measure, that's how you do it, just
258 comment out the patterns in the config file and don't run with the -c flag.
260 Note: the current working directory when a CGI program gets run is
261 the directory that the CGI program lives in.
262 This isn't in the CGI 1.1 spec, but it's what most other HTTP servers do.
264 Relevant config.h options: CGI_PATTERN, CGI_TIMELIMIT, CGI_NICE, CGI_PATH, CGI_LD_LIBRARY_PATH, CGIBINDIR.
265 .SH "BASIC AUTHENTICATION"
267 Basic Authentication is available as an option at compile time.
268 If enabled, it uses a password file in the directory to be protected,
269 called .htpasswd by default.
270 This file is formatted as the familiar colon-separated
271 username/encrypted-password pair, records delimited by newlines.
272 The protection does not carry over to subdirectories.
273 The utility program htpasswd(1) is included to help create and
274 modify .htpasswd files.
276 Relevant config.h option: AUTH_FILE
279 The throttle file lets you set maximum byte rates on URLs or URL groups.
280 You can optionally set a minimum rate too.
281 The format of the throttle file is very simple.
282 A # starts a comment, and the rest of the line is ignored.
283 Blank lines are ignored.
284 The rest of the lines should consist of a pattern, whitespace, and a number.
285 The pattern is a simple shell-style filename pattern, using ?/**/*, or
286 multiple such patterns separated by |.
288 The numbers in the file are byte rates, specified in units of bytes per second.
289 For comparison, a v.90 modem gives about 5000 B/s depending on compression,
290 a double-B-channel ISDN line about 12800 B/s, and a T1 line is about
292 If you want to set a minimum rate as well, use number-number.
296 # throttle file for www.acme.com
298 ** 2000-100000 # limit total web usage to 2/3 of our T1,
299 # but never go below 2000 B/s
300 **.jpg|**.gif 50000 # limit images to 1/3 of our T1
301 **.mpg 20000 # and movies to even less
302 jef/** 20000 # jef's pages are too popular
305 Throttling is implemented by checking each incoming URL filename against all
306 of the patterns in the throttle file.
307 The server accumulates statistics on how much bandwidth each pattern
308 has accounted for recently (via a rolling average).
309 If a URL matches a pattern that has been exceeding its specified limit,
310 then the data returned is actually slowed down, with
311 pauses between each block.
312 If that's not possible (e.g. for CGI programs) or if the bandwidth has gotten
313 way larger than the limit, then the server returns a special code
314 saying 'try again later'.
316 The minimum rates are implemented similarly.
317 If too many people are trying to fetch something at the same time,
318 throttling may slow down each connection so much that it's not really
320 Furthermore, all those slow connections clog up the server, using
321 up file handles and connection slots.
322 Setting a minimum rate says that past a certain point you should not
323 even bother - the server returns the 'try again later" code and the
324 connection isn't even started.
326 There is no provision for setting a maximum connections/second throttle,
327 because throttling a request uses as much cpu as handling it, so
328 there would be no point.
329 There is also no provision for throttling the number of simultaneous
330 connections on a per-URL basis.
331 However you can control the overall number of connections for the whole
332 server very simply, by setting the operating system's per-process file
333 descriptor limit before starting thttpd.
334 Be sure to set the hard limit, not the soft limit.
337 Multihoming means using one machine to serve multiple hostnames.
338 For instance, if you're an internet provider and you want to let
339 all of your customers have customized web addresses, you might
340 have www.joe.acme.com, www.jane.acme.com, and your own www.acme.com,
341 all running on the same physical hardware.
342 This feature is also known as "virtual hosts".
343 There are three steps to setting this up.
345 One, make DNS entries for all of the hostnames.
346 The current way to do this, allowed by HTTP/1.1, is to use CNAME aliases,
349 www.acme.com IN A 192.100.66.1
350 www.joe.acme.com IN CNAME www.acme.com
351 www.jane.acme.com IN CNAME www.acme.com
353 However, this is incompatible with older HTTP/1.0 browsers.
354 If you want to stay compatible, there's a different way - use A records
355 instead, each with a different IP address, like so:
357 www.acme.com IN A 192.100.66.1
358 www.joe.acme.com IN A 192.100.66.200
359 www.jane.acme.com IN A 192.100.66.201
361 This is bad because it uses extra IP addresses, a somewhat scarce resource.
362 But if you want people with older browsers to be able to visit your
363 sites, you still have to do it this way.
366 If you're using the modern CNAME method of multihoming, then you can
368 Otherwise, using the older multiple-IP-address method you
369 must set up IP aliases or multiple interfaces for the extra addresses.
370 You can use ifconfig(8)'s alias command to tell the machine to answer to
371 all of the different IP addresses.
374 ifconfig le0 www.acme.com
375 ifconfig le0 www.joe.acme.com alias
376 ifconfig le0 www.jane.acme.com alias
378 If your OS's version of ifconfig doesn't have an alias command, you're
379 probably out of luck (but see http://www.acme.com/software/thttpd/notes.html).
381 Third and last, you must set up thttpd to handle the multiple hosts.
382 The easiest way is with the -v flag, or the ALWAYS_VHOST config.h option.
383 This works with either CNAME multihosting or multiple-IP multihosting.
384 What it does is send each incoming request to a subdirectory based on the
385 hostname it's intended for.
386 All you have to do in order to set things up is to create those subdirectories
387 in the directory where thttpd will run.
388 With the example above, you'd do like so:
390 mkdir www.acme.com www.joe.acme.com www.jane.acme.com
392 If you're using old-style multiple-IP multihosting, you should also create
393 symbolic links from the numeric addresses to the names, like so:
395 ln -s www.acme.com 192.100.66.1
396 ln -s www.joe.acme.com 192.100.66.200
397 ln -s www.jane.acme.com 192.100.66.201
399 This lets the older HTTP/1.0 browsers find the right subdirectory.
401 There's an optional alternate step three if you're using multiple-IP
402 multihosting: run a separate thttpd process for each hostname, using
403 the -h flag to specify which one is which.
404 This gives you more flexibility, since you can run each of these processes
405 in separate directories, with different throttle files, etc.
408 thttpd -r -d /usr/www -h www.acme.com
409 thttpd -r -d /usr/www/joe -u joe -h www.joe.acme.com
410 thttpd -r -d /usr/www/jane -u jane -h www.jane.acme.com
412 But remember, this multiple-process method does not work with CNAME
413 multihosting - for that, you must use a single thttpd process with
417 thttpd lets you define your own custom error pages for the various
419 There's a separate file for each error number, all stored in one
421 The directory name is "errors", at the top of the web directory tree.
422 The error files should be named "errNNN.html", where NNN is the error number.
423 So for example, to make a custom error page for the authentication failure
424 error, which is number 401, you would put your HTML into the file
425 "errors/err401.html".
426 If no custom error file is found for a given error number, then the
427 usual built-in error page is generated.
429 If you're using the virtual hosts option, you can also have different
430 custom error pages for each different virtual host.
431 In this case you put another "errors" directory in the top of that
432 virtual host's web tree.
433 thttpd will look first in the virtual host errors directory, and
434 then in the server-wide errors directory, and if neither of those
435 has an appropriate error file then it will generate the built-in error.
436 .SH "NON-LOCAL REFERRERS"
438 Sometimes another site on the net will embed your image files in their
439 HTML files, which basically means they're stealing your bandwidth.
440 You can prevent them from doing this by using non-local referrer filtering.
441 With this option, certain files can only be fetched via a local referrer.
442 The files have to be referenced by a local web page.
443 If a web page on some other site references the files, that fetch will
445 There are three config-file variables for this feature:
448 A wildcard pattern for the URLs that should require a local referrer.
449 This is typically just image files, sound files, and so on.
452 urlpat=**.jpg|**.gif|**.au|**.wav
454 For most sites, that one setting is all you need to enable referrer filtering.
457 By default, requests with no referrer at all, or a null referrer, or a
458 referrer with no apparent hostname, are allowed.
459 With this variable set, such requests are disallowed.
462 A wildcard pattern that specifies the local host or hosts.
463 This is used to determine if the host in the referrer is local or not.
464 If not specified it defaults to the actual local hostname.
467 thttpd is very picky about symbolic links.
468 Before delivering any file, it first checks each element in the path
469 to see if it's a symbolic link, and expands them all out to get the final
471 Along the way it checks for things like links with ".." that go above
472 the server's directory, and absolute symlinks (ones that start with a /).
473 These are prohibited as security holes, so the server returns an
475 This means you can't set up your web directory with a bunch of symlinks
476 pointing to individual users' home web directories.
477 Instead you do it the other way around - the user web directories are
478 real subdirs of the main web directory, and in each user's home
479 dir there's a symlink pointing to their actual web dir.
481 The CGI pattern is also affected - it gets matched against the fully-expanded
482 filename. So, if you have a single CGI directory but then put a symbolic
483 link in it pointing somewhere else, that won't work. The CGI program will be
484 treated as a regular file and returned to the client, instead of getting run.
485 This could be confusing.
488 thttpd is also picky about file permissions.
489 It wants data files (HTML, images) to be world readable.
490 Readable by the group that the thttpd process runs as is not enough - thttpd
491 checks explicitly for the world-readable bit.
492 This is so that no one ever gets surprised by a file that's not set
493 world-readable and yet somehow is readable by the HTTP server and
494 therefore the *whole* world.
496 The same logic applies to directories.
497 As with the standard Unix "ls" program, thttpd will only let you
498 look at the contents of a directory if its read bit is on; but
499 as with data files, this must be the world-read bit, not just the
502 thttpd also wants the execute bit to be *off* for data files.
503 A file that is marked executable but doesn't match the CGI pattern
504 might be a script or program that got accidentally left in the
506 Allowing people to fetch the contents of the file might be a security breach,
507 so this is prohibited.
508 Of course if an executable file *does* match the CGI pattern, then it
509 just gets run as a CGI.
511 In summary, data files should be mode 644 (rw-r--r--),
512 directories should be 755 (rwxr-xr-x) if you want to allow indexing and
513 711 (rwx--x--x) to disallow it, and CGI programs should be mode
514 755 (rwxr-xr-x) or 711 (rwx--x--x).
517 thttpd does all of its logging via syslog(3).
518 The facility it uses is configurable.
519 Aside from error messages, there are only a few log entry types of interest,
520 all fairly similar to CERN Common Log Format:
522 Aug 6 15:40:34 acme thttpd[583]: 165.113.207.103 - - "GET /file" 200 357
523 Aug 6 15:40:43 acme thttpd[583]: 165.113.207.103 - - "HEAD /file" 200 0
524 Aug 6 15:41:16 acme thttpd[583]: referrer http://www.acme.com/ -> /dir
525 Aug 6 15:41:16 acme thttpd[583]: user-agent Mozilla/1.1N
527 The package includes a script for translating these log entries info
528 CERN-compatible files.
529 Note that thttpd does not translate numeric IP addresses into domain names.
530 This is both to save time and as a minor security measure (the numeric
531 address is harder to spoof).
533 Relevant config.h option: LOG_FACILITY.
535 If you'd rather log directly to a file, you can use the -l command-line
536 flag. But note that error messages still go to syslog.
539 thttpd handles a couple of signals, which you can send via the
540 standard Unix kill(1) command:
543 These signals tell thttpd to shut down immediately.
544 Any requests in progress get aborted.
547 This signal tells thttpd to shut down as soon as it's done servicing
548 all current requests.
549 In addition, the network socket it uses to accept new connections gets
550 closed immediately, which means a fresh thttpd can be started up
554 This signal tells thttpd to generate the statistics syslog messages
555 immediately, instead of waiting for the regular hourly update.
558 This signal tells thttpd to close and re-open its (non-syslog) log file,
559 for instance if you rotated the logs and want it to start using the
561 This is a little tricky to set up correctly, for instance if you are using
562 chroot() then the log file must be within the chroot tree, but it's
565 redirect(8), ssi(8), makeweb(1), htpasswd(1), syslogtocern(8), weblog_parse(1), http_get(1)
568 Many thanks to contributors, reviewers, testers:
569 John LoVerso, Jordan Hayes, Chris Torek, Jim Thompson, Barton Schaffer,
570 Geoff Adams, Dan Kegel, John Hascall, Bennett Todd, KIKUCHI Takahiro,
572 Special thanks to Craig Leres for substantial debugging and development,
573 and for not complaining about my coding style very much.
575 Copyright © 1995,1998,1999,2000 by Jef Poskanzer <jef@mail.acme.com>.
577 .\" Redistribution and use in source and binary forms, with or without
578 .\" modification, are permitted provided that the following conditions
580 .\" 1. Redistributions of source code must retain the above copyright
581 .\" notice, this list of conditions and the following disclaimer.
582 .\" 2. Redistributions in binary form must reproduce the above copyright
583 .\" notice, this list of conditions and the following disclaimer in the
584 .\" documentation and/or other materials provided with the distribution.
586 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
587 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
588 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
589 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
590 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
591 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
592 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
593 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
594 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
595 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
git://git.gir.st / ttxd.git / blob