thttpd.8

非常优秀的linux嵌入式http服务器

.TH thttpd 8 "29 February 2000"
.SH NAME
thttpd - tiny/turbo/throttling HTTP server
.SH SYNOPSIS
.B thttpd
.RB [ -C
.IR configfile ]
.RB [ -p
.IR port ]
.RB [ -d
.IR dir ]
.RB [ -dd
.IR data_dir ]
.RB [ -r | -nor ]
.RB [ -s | -nos ]
.RB [ -v | -nov ]
.RB [ -g | -nog ]
.RB [ -u
.IR user ]
.RB [ -c
.IR cgipat ]
.RB [ -t
.IR throttles ]
.RB [ -h
.IR host ]
.RB [ -l
.IR logfile ]
.RB [ -i
.IR pidfile ]
.RB [ -T
.IR charset ]
.RB [ -P
.IR P3P ]
.RB [ -M
.IR maxage ]
.RB [ -V ]
.RB [ -D ]
.SH DESCRIPTION
.PP
.I thttpd
is a simple, small, fast, and secure HTTP server.
It doesn't have a lot of special features, but it suffices for most uses of
the web, it's about as fast as the best full-featured servers (Apache, NCSA,
Netscape),
and it has one extremely useful feature (URL-traffic-based throttling)
that no other server currently has.
.SH OPTIONS
.TP
.B -C
Specifies a config-file to read.
All options can be set either by command-line flags or in the config file.
See below for details.
.TP
.B -p
Specifies an alternate port number to listen on.
The default is 80.
The config-file option name for this flag is "port",
and the config.h option is DEFAULT_PORT.
.TP
.B -d
Specifies a directory to chdir() to at startup.
This is merely a convenience - you could just as easily
do a cd in the shell script that invokes the program.
The config-file option name for this flag is "dir",
and the config.h options are WEBDIR, USE_USER_DIR.
.TP
.B -r
Do a chroot() at initialization time, restricting file access
to the program's current directory.
If -r is the compiled-in default, then -nor disables it.
See below for details.
The config-file option names for this flag are "chroot" and "nochroot",
and the config.h option is ALWAYS_CHROOT.
.TP
.B -dd
Specifies a directory to chdir() to after chrooting.
If you're not chrooting, you might as well do a single chdir() with
the -d flag.
If you are chrooting, this lets you put the web files in a subdirectory
of the chroot tree, instead of in the top level mixed in with the
chroot files.
The config-file option name for this flag is "data_dir".
.TP
.B -nos
Don't do explicit symbolic link checking.
Normally, thttpd explicitly expands any symbolic links in filenames,
to check that the resulting path stays within the original document tree.
If you want to turn off this check and save some CPU time, you can use
the -nos flag, however this is not recommended.
Note, though, that if you are using the chroot option, the symlink
checking is unnecessary and is turned off, so the safe way to save
those CPU cycles is to use chroot.
The config-file option names for this flag are "symlinkcheck" and "nosymlinkcheck".
.TP
.B -v
Do el-cheapo virtual hosting.
If -v is the compiled-in default, then -nov disables it.
See below for details.
The config-file option names for this flag are "vhost" and "novhost",
and the config.h option is ALWAYS_VHOST.
.TP
.B -g
Use a global passwd file.
This means that every file in the entire document tree is protected by
the single .htpasswd file at the top of the tree.
Otherwise the semantics of the .htpasswd file are the same.
If this option is set but there is no .htpasswd file in
the top-level directory, then thttpd proceeds as if the option was
not set - first looking for a local .htpasswd file, and if that doesn't
exist either then serving the file without any password.
If -g is the compiled-in default, then -nog disables it.
The config-file option names for this flag are "globalpasswd" and
"noglobalpasswd",
and the config.h option is ALWAYS_GLOBAL_PASSWD.
.TP
.B -u
Specifies what user to switch to after initialization when started as root.
The default is "nobody".
The config-file option name for this flag is "user",
and the config.h option is DEFAULT_USER.
.TP
.B -c
Specifies a wildcard pattern for CGI programs, for instance "**.cgi"
or "/cgi-bin/*".
See below for details.
The config-file option name for this flag is "cgipat",
and the config.h option is CGI_PATTERN.
.TP
.B -t
Specifies a file of throttle settings.
See below for details.
The config-file option name for this flag is "throttles".
.TP
.B -h
Specifies a hostname to bind to, for multihoming.
The default is to bind to all hostnames supported on the local machine.
See below for details.
The config-file option name for this flag is "host",
and the config.h option is SERVER_NAME.
.TP
.B -l
Specifies a file for logging.
If no -l argument is specified, thttpd logs via syslog().
If "-l /dev/null" is specified, thttpd doesn't log at all.
The config-file option name for this flag is "logfile".
.TP
.B -i
Specifies a file to write the process-id to.
If no file is specified, no process-id is written.
You can use this file to send signals to thttpd.
See below for details.
The config-file option name for this flag is "pidfile".
.TP
.B -T
Specifies the character set to use with text MIME types.
The default is iso-8859-1.
The config-file option name for this flag is "charset",
and the config.h option is DEFAULT_CHARSET.
.TP
.B -P
Specifies a P3P server privacy header to be returned with all responses.
See http://www.w3.org/P3P/ for details.
Thttpd doesn't do anything at all with the string except put it in the
P3P: response header.
The config-file option name for this flag is "p3p".
.TP
.B -M
Specifies the number of seconds to be used in a "Cache-Control: max-age"
header to be returned with all responses.
An equivalent "Expires" header is also generated.
The default is no Cache-Control or Expires headers,
which is just fine for most sites.
The config-file option name for this flag is "max_age".
.TP
.B -V
Shows the current version info.
.TP
.B -D
This was originally just a debugging flag, however it's worth mentioning
because one of the things it does is prevent thttpd from making itself
a background daemon.
Instead it runs in the foreground like a regular program.
This is necessary when you want to run thttpd wrapped in a little shell
script that restarts it if it exits.
.SH "CONFIG-FILE"
.PP
All the command-line options can also be set in a config file.
One advantage of using a config file is that the file can be changed,
and thttpd will pick up the changes with a restart.
.PP
The syntax of the config file is simple, a series of "option" or
"option=value" separated by whitespace.
The option names are listed above with their corresponding command-line flags.
.SH "CHROOT"
.PP
chroot() is a system call that restricts the program's view
of the filesystem to the current directory and directories
below it.
It becomes impossible for remote users to access any file
outside of the initial directory.
The restriction is inherited by child processes, so CGI programs get it too.
This is a very strong security measure, and is recommended.
The only downside is that only root can call chroot(), so this means
the program must be started as root.
However, the last thing it does during initialization is to
give up root access by becoming another user, so this is safe.
.PP
The program can also be compile-time configured to always
do a chroot(), without needing the -r flag.
.PP
Note that with some other web servers, such as NCSA httpd, setting
up a directory tree for use with chroot() is complicated, involving
creating a bunch of special directories and copying in various files.
With thttpd it's a lot easier, all you have to do is make sure
any shells, utilities, and config files used by your CGI programs and
scripts are available.
If you have CGI disabled, or if you make a policy that all CGI programs
must be written in a compiled language such as C and statically linked,
then you probably don't have to do any setup at all.
.PP
However, one thing you should do is tell syslogd about the chroot tree,
so that thttpd can still generate syslog messages.
Check your system's syslodg man page for how to do this.
In FreeBSD you would put something like this in /etc/rc.conf:
.nf
    syslogd_flags="-l /usr/local/www/data/dev/log"
.fi
Substitute in your own chroot tree's pathname, of course.
Don't worry about creating the log socket, syslogd wants to do that itself.
(You may need to create the dev directory.)
In Linux the flag is -a instead of -l, and there may be other differences.
.PP
Relevant config.h option: ALWAYS_CHROOT.
.SH "CGI"
.PP
thttpd supports the CGI 1.1 spec.
.PP
In order for a CGI program to be run, its name must match the pattern
specified either at compile time or on the command line with the -c flag.
This is a simple shell-style filename pattern.
You can use * to match any string not including a slash,
or ** to match any string including slashes,
or ? to match any single character.
You can also use multiple such patterns separated by |.
The patterns get checked against the filename
part of the incoming URL.
Don't forget to quote any wildcard characters so that the shell doesn't
mess with them.
.PP
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.
.PP
If no CGI pattern is specified, neither here nor at compile time,
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
comment out the patterns in the config file and don't run with the -c flag.
.PP
Note: the current working directory when a CGI program gets run is
the directory that the CGI program lives in.
This isn't in the CGI 1.1 spec, but it's what most other HTTP servers do.
.PP
Relevant config.h options: CGI_PATTERN, CGI_TIMELIMIT, CGI_NICE, CGI_PATH, CGI_LD_LIBRARY_PATH, CGIBINDIR.
.SH "BASIC AUTHENTICATION"
.PP
Basic Authentication is available as an option at compile time.
If enabled, it uses a password file in the directory to be protected,
called .htpasswd by default.
This file is formatted as the familiar colon-separated
username/encrypted-password pair, records delimited by newlines.
The protection does not carry over to subdirectories.
The utility program htpasswd(1) is included to help create and
modify .htpasswd files.
.PP
Relevant config.h option: AUTH_FILE
.SH "THROTTLING"
.PP
The throttle file lets you set maximum byte rates on URLs or URL groups.
You can optionally set a minimum rate too.
The format of the throttle file is very simple.
A # starts a comment, and the rest of the line is ignored.
Blank lines are ignored.
The rest of the lines should consist of a pattern, whitespace, and a number.
The pattern is a simple shell-style filename pattern, using ?/**/*, or
multiple such patterns separated by |.
.PP
The numbers in the file are byte rates, specified in units of bytes per second.