thttpd_man.html

嵌入式http源代码的文档资料

<P>
Throttling is implemented by checking each incoming URL
filename against all of the patterns in the throttle file.
The server accumulates statistics on how much bandwidth each
pattern has accounted for recently (via a rolling average).
If a URL matches a pattern that has been exceeding its
specified limit, then the data returned is actually slowed
down, with pauses between each block.
If that's not possible (e.g. for CGI programs), then the server
returns a special code saying 'try again later'.


<H4><A NAME="MULTIHOMING">MULTIHOMING</A></H4>

<P>
Multihoming means using one machine to serve multiple hostnames.
For instance, if you're an internet provider and you
want to let all of your customers have customized web
addresses, you might have www.joe.acme.com,
www.jane.acme.com, and your own www.acme.com, all running on
the same physical hardware.
This feature is also known as "virtual hosts".
There are three steps to setting this up.

<P>
One, make DNS entries for all of the hostnames.
The current way to do this, allowed by HTTP/1.1, is to use CNAME aliases,
like so:
<BLOCKQUOTE><CODE><PRE>
www.acme.com IN A 192.100.66.1
www.joe.acme.com IN CNAME www.acme.com
www.jane.acme.com IN CNAME www.acme.com
</PRE></CODE></BLOCKQUOTE>
However, this is incompatible with older HTTP/1.0 browsers.
If you want to stay compatible, there's a different way - use A records
instead, each with a different IP address, like so:
<BLOCKQUOTE><CODE><PRE>
www.acme.com IN A 192.100.66.10
www.joe.acme.com IN A 192.100.66.200
www.jane.acme.com IN A 192.100.66.201
</PRE></CODE></BLOCKQUOTE>
This is bad because it uses extra IP addresses, a somewhat scarce resource.
But if you want people with older browsers to be able to visit your
sites, you still have to do it this way.

<P>
Step two.
If you're using the modern CNAME method of multihoming, then you can
skip this step.
Otherwise, using the older multiple-IP-address method you
must set up IP aliases or multiple interfaces for the extra addresses.
You can use ifconfig(8)'s alias command to tell the machine to answer to
all of the different IP addresses.
Example:
<BLOCKQUOTE><CODE><PRE>
ifconfig le0 www.acme.com
ifconfig le0 www.joe.acme.com alias
ifconfig le0 www.jane.acme.com alias
</PRE></CODE></BLOCKQUOTE>
If your OS's version of ifconfig doesn't have an alias command, you're
probably out of luck (but see the
<A HREF="notes.html#aliasing" tppabs="http://www.acme.com/software/thttpd/notes.html#aliasing">notes</A>).

<P>
Third and last, you must set up thttpd to handle the multiple hosts.
The easiest way is with the -v flag, or the ALWAYS_VHOST config.h option.
This works with either CNAME multihosting or multiple-IP multihosting.
What it does is send each incoming request to a subdirectory based on the
hostname it's intended for.
All you have to do in order to set things up is to create those subdirectories
in the directory where thttpd will run.
With the example above, you'd do like so:
<BLOCKQUOTE><CODE><PRE>
mkdir www.acme.com www.joe.acme.com www.jane.acme.com
</PRE></CODE></BLOCKQUOTE>
If you're using old-style multiple-IP multihosting, you should also create
symbolic links from the numeric addresses to the names, like so:
<BLOCKQUOTE><CODE><PRE>
ln -s www.acme.com 192.100.66.1
ln -s www.joe.acme.com 192.100.66.200
ln -s www.jane.acme.com 192.100.66.201
</PRE></CODE></BLOCKQUOTE>
This lets the older HTTP/1.0 browsers find the right subdirectory.

<P>
There's an optional alternate step three if you're using multiple-IP
multihosting: run a separate thttpd process for each hostname, using
the -h flag to specify which one is which.
This gives you more flexibility, since you can run each of these processes
in separate directories, with different throttle files, etc.
Example:
<BLOCKQUOTE><CODE><PRE>
thttpd -r -d /usr/www -h www.acme.com
thttpd -r -d /usr/www/joe -u joe -h www.joe.acme.com
thttpd -r -d /usr/www/jane -u jane -h www.jane.acme.com
</PRE></CODE></BLOCKQUOTE>
But remember, this multiple-process method does not work with CNAME
multihosting - for that, you must use a single thttpd process with
the -v flag.


<H4><A NAME="CUSTOM_ERRORS">CUSTOM ERRORS</A></H4>

<P>
thttpd lets you define your own custom error pages for the various
HTTP errors.
There's a separate file for each error number, all stored in one
special directory.
The directory name is "errors", at the top of the web directory tree.
The error files should be named "errNNN.html", where NNN is the error
number.
So for example, to make a custom error page for the authentication
failure error, which is number 401, you would put your HTML into the
file "errors/err401.html".
If no custom error file is found for a given error number, then the
usual built-in error page is generated.

<P>
If you're using the virtual hosts option, you can also have different
custom error pages for each different virtual host.
In this case you put another "errors" directory in the top of that
virtual host's web tree.
thttpd will look first in the virtual host errors directory, and then
in the server-wide errors directory, and if neither of those has an
appropriate error file then it will generate the built-in error.


<H4><A NAME="NON-LOCAL_REFERERS">NON-LOCAL REFERERS</A></H4>

<P>
Sometimes another site on the net will embed your image files in their
HTML files, which basically means they're stealing your bandwidth.
You can prevent them from doing this by using non-local referer filtering.
With this option, certain files can only be fetched via a local referer.
The files have to be referenced by a local web page.
If a web page on some other site references the files, that fetch will
be blocked.
There are three config-file variables for this feature:

<DL>

<DT> urlpat
<DD>
A wildcard pattern for the URLs that should require a local referer.
This is typically just image files, sound files, and so on.
For example:
<BLOCKQUOTE><CODE>
urlpat=**.jpg|**.gif|**.au|**.wav
</CODE></BLOCKQUOTE>
For most sites, that one setting is all you need to enable referer filtering.

<DT> noemptyreferers
<DD>
By default, requests with no referer at all, or a null referer, or a
referer with no apparent hostname, are allowed.
With this variable set, such requests are disallowed.

<DT> localpat
<DD>
A wildcard pattern that specifies the local host or hosts.
This is used to determine if the host in the referer is local or not.
If not specified it defaults to the actual local hostname.

</DL>


<H4><A NAME="SYMLINKS">SYMLINKS</A></H4>

<P>
thttpd is very picky about symbolic links.
Before delivering any file, it first checks each element in the path to
see if it's a symbolic link, and expands them all out to get
the final actual filename.
Along the way it checks for
things like links with ".." that go above the server's
directory, and absolute symlinks (ones that start with a /).
These are prohibited as security holes, so the server
returns an error page for them.
This means you can't set up
your web directory with a bunch of symlinks pointing to
individual users' home web directories.
Instead you do it
the other way around - the user web directories are real
subdirs of the main web directory, and in each user's home
dir there's a symlink pointing to their actual web dir.

<P>
The CGI pattern is also affected - it gets matched against
the fully-expanded filename.
So, if you have a single CGI
directory but then put a symbolic link in it pointing somewhere else,
that won't work.
The CGI program will be
treated as a regular file and returned to the client,
instead of getting run.
This could be confusing.


<H4><A NAME="PERMISSIONS">PERMISSIONS</A></H4>

<P>
thttpd is also picky about file permissions.
It wants data files (HTML, images) to be world readable.
Readable by the group that the thttpd process runs as is not enough - thttpd
checks explicitly for the world-readable bit.
This is so that no one ever gets surprised by a file that's not set
world-readable and yet somehow is readable by the HTTP server and
therefore the *whole* world.

<P>
The same logic applies to directories.
As with the standard Unix "ls" program, thttpd will only let you
look at the contents of a directory if its read bit is on; but
as with data files, this must be the world-read bit, not just the
group-read bit.

<P>
thttpd also wants the execute bit to be *off* for data files.
A file that is marked executable but doesn't match the CGI pattern
might be a script or program that got accidentally left in the
wrong directory.
Allowing people to fetch the contents of the file might be a security breach,
so this is prohibited.
Of course if an executable file *does* match the CGI pattern, then it
just gets run as a CGI.

<P>
In summary, data files should be mode 644 (<CODE>rw-r--r--</CODE>),
directories should be 755 (<CODE>rwxr-xr-x</CODE>) if you want to allow indexing and
711 (<CODE>rwx--x--x</CODE>) to disallow it, and CGI programs should be mode
755 (<CODE>rwxr-xr-x</CODE>) or 711 (<CODE>rwx--x--x</CODE>).


<H4><A NAME="LOGS">LOGS</A></H4>

<P>
thttpd does all of its logging via syslog(3).
The facility it uses is configurable.
Aside from error messages, there are only a few log entry types of interest,
all fairly similar to CERN Common Log Format:
<BLOCKQUOTE><CODE><PRE>
Aug  6 15:40:34 acme thttpd[583]: 165.113.207.103 - - "GET /file" 200 357
Aug  6 15:40:43 acme thttpd[583]: 165.113.207.103 - - "HEAD /file" 200 0
Aug  6 15:41:16 acme thttpd[583]: referer http://www.acme.com/ -> /dir
Aug  6 15:41:16 acme thttpd[583]: user-agent Mozilla/1.1N
</PRE></CODE></BLOCKQUOTE>
The package includes a script for translating these log entries info
CERN-compatible files.
Note that thttpd does
not translate numeric IP addresses into domain names.
This is both to save time and as a minor security measure (the
numeric address is harder to spoof).

<P>
Relevant config.h option:
<A HREF="options.html#LOG_FACILITY" tppabs="http://www.acme.com/software/thttpd/options.html#LOG_FACILITY">LOG_FACILITY</A>.

<P>
If you'd rather log directly to a file, you can use the -l command-line
flag.  But note that error messages still go to syslog.


<H4><A NAME="SIGNALS">SIGNALS</A></H4>

<P>
thttpd handles a couple of signals, which you can send via the
standard Unix kill(1) command:

<DL>

<DT> INT,TERM
<DD>
These signals tell thttpd to shut down immediately.
Any requests in progress get aborted.

<DT> USR1
<DD>
This signal tells thttpd to shut down as soon as it's done servicing
all current requests.
In addition, the network socket it uses to accept new connections gets
closed immediately, which means a fresh thttpd can be started up
immediately.

<DT> HUP
<DD>
This signal tells thttpd to close and re-open its (non-syslog) log file,
for instance if you rotated the logs and want thttpd to start using the
new one.
However, this feature isn't actually that useful at the moment.
The problem is that thttpd will generally be started as root, so that
it can bind to port 80; then it gives up the root uid as soon as it can,
for security reasons.
But if you later send it a HUP, it will try to re-open the log file
without root access and will generally fail.
Also, if you're running inside a chroot tree, as you should be,
the log file won't even be accessible.
Currently the best alternative for log rotation is to send a USR1 signal,
shutting down thttpd altogether, and then restart it.

</DL>


<H4><A NAME="SEE_ALSO">SEE ALSO</A></H4>

<P>
<A HREF="redirect_man.html" tppabs="http://www.acme.com/software/thttpd/redirect_man.html">redirect(8)</A>,
<A HREF="ssi_man.html" tppabs="http://www.acme.com/software/thttpd/ssi_man.html">ssi(8)</A>,
<A HREF="makeweb_man.html" tppabs="http://www.acme.com/software/thttpd/makeweb_man.html">makeweb(1)</A>,
<A HREF="htpasswd_man.html" tppabs="http://www.acme.com/software/thttpd/htpasswd_man.html">htpasswd(1)</A>,
<A HREF="syslogtocern_man.html" tppabs="http://www.acme.com/software/thttpd/syslogtocern_man.html">syslogtocern(8)</A>,
<A HREF="tppmsgs/msgs0.htm#70" tppabs="http://www.acme.com/software/weblog_parse/">weblog_parse(1)</A>,
<A HREF="tppmsgs/msgs0.htm#23" tppabs="http://www.acme.com/software/http_get/">http_get(1)</A>


<H4><A NAME="THANKS">THANKS</A></H4>

<P>
Many thanks to reviewers and testers:
John LoVerso, Jordan Hayes, Chris Torek, Jim Thompson, Barton Schaffer,
Geoff Adams, Dan Kegel, John Hascall, Bennett Todd, KIKUCHI Takahiro,
Catalin Ionescu.
Special thanks to Craig Leres for substantial debugging and development,
and for not complaining about my coding style very much.


<H4><A NAME="AUTHOR">AUTHOR</A></H4>

<P>
Copyright &copy; 1995,1998,1999,2000 by Jef Poskanzer &lt;jef&#64;acme.com&gt;.
All rights reserved.

<HR>
Back to the <A HREF="thttpd.html" tppabs="http://www.acme.com/software/thttpd/thttpd.html">thttpd page</A>.
<P>
<ADDRESS><A HREF="mailto:webmaster&#64;acme.com">ACME Labs Webmaster &lt;webmaster&#64;acme.com&gt;</A></ADDRESS>
</BODY>
</HTML>