1 |
.TH HYDRA 8 "Oct 21 2002" "Version 0.0.7" |
2 |
.SH NAME |
3 |
.B Hydra \- a single\-tasking high performance http server |
4 |
.SH SYNOPSIS |
5 |
.B Hydra |
6 |
.RB [ -c |
7 |
.IR server_root ] |
8 |
.RB [ -r |
9 |
.IR chroot ] |
10 |
.RB [ -d ] |
11 |
.SH DESCRIPTION |
12 |
Hydra is a multi-threaded HTTP server. Unlike traditional web |
13 |
servers, it does not fork for each incoming connection, nor does it fork many |
14 |
copies of itself to handle multiple connections. It internally multiplexes all |
15 |
of the ongoing HTTP connections, using parallel multiplexers, and forks only for CGI programs, |
16 |
which must be separate processes. |
17 |
.PP |
18 |
The primary design goals of Hydra are speed and security. Security, in the sense |
19 |
of "can't be subverted by a malicious user", not "fine grained access control |
20 |
and encrypted communications". Hydra is not intended as a feature-packed server; |
21 |
if you want one of those, check out WN from John Franks. Modifications to Hydra |
22 |
that improve its speed, security, robustness, and portability, are eagerly |
23 |
sought. Other features may be added if they can be achieved without hurting the |
24 |
primary goals. |
25 |
.SH OPTIONS |
26 |
.IP \fB-d\fR |
27 |
instruct Hydra not to fork itself (non-daemonize). |
28 |
|
29 |
.IP "\fB-c \fIserver_root\fR" |
30 |
choose a server root overriding the default SERVER_ROOT #define in |
31 |
.I defines.h |
32 |
|
33 |
The server root must hold your local copy of the configuration file |
34 |
|
35 |
.IP "\fB-r \fIchroot\fR" |
36 |
instruct Hydra where to chdir and chroot to. The chdir/chroot |
37 |
is done before the configuration file is read, or any log |
38 |
files are opened. |
39 |
|
40 |
.SH FILES |
41 |
.TP |
42 |
\fBhydra.conf\fR \- the sole configuration file for Hydra. |
43 |
The directives in this file are defined in the |
44 |
.B DIRECTIVES |
45 |
section. |
46 |
|
47 |
.TP |
48 |
\fBmime.types\fR \- the |
49 |
MimeTypes <filename> |
50 |
defines what Content-Type Hydra will send in an HTTP/1.0 |
51 |
or better transaction. |
52 |
.SH DIRECTIVES |
53 |
|
54 |
The Hydra configuration file is parsed with a lex/yacc or flex/bison generated |
55 |
parser. If it reports an error, the line number will be provided; it should |
56 |
be easy to spot. The syntax of each of these rules is very simple, and they |
57 |
can occur in any order. Where possible, these directives mimic those of NCSA |
58 |
httpd 1.3; We saw no reason to introduce gratuitous differences. |
59 |
.PP |
60 |
Note: the "ServerRoot" is not in this configuration file. It can be compiled |
61 |
into the server (see |
62 |
.I defines.h |
63 |
) or specified on the command line with the |
64 |
.B -c |
65 |
option. |
66 |
|
67 |
The following directives are contained in the |
68 |
.I hydra.conf |
69 |
file, and most, but not all, are required. |
70 |
.TP |
71 |
Port <integer> |
72 |
This is the port that Hydra runs on. The default port for http servers is 80. |
73 |
If it is less than 1024, the server must be started as root. |
74 |
.TP |
75 |
User <user name or UID> |
76 |
The name or UID the server should run as. For Hydra to attempt this, the |
77 |
server must be started as root. |
78 |
.TP |
79 |
Group <group name or GID> |
80 |
The group name or GID the server should run as. For Hydra to attempt this, |
81 |
the server must be started as root. |
82 |
.TP |
83 |
ServerAdmin <email address> |
84 |
The email address where server problems should be sent. |
85 |
Note: this is not currently used. |
86 |
.TP |
87 |
PidFile <filename> |
88 |
Where to put the pid of the process. |
89 |
Comment out to write no pid file. |
90 |
Note: Because Hydra drops priviledges at startup, and the |
91 |
pid file is written by the UID/GID before doing so, Hydra |
92 |
does not attempt removal of the pid file. |
93 |
.TP |
94 |
ErrorLog <filename> |
95 |
The location of the error log file. If this does not start with |
96 |
/, it is considered relative to the server root. |
97 |
Set to /dev/null if you don't want errors logged. |
98 |
.TP |
99 |
AccessLog <filename> |
100 |
The location of the access log file. If this does not start with /, it is |
101 |
considered relative to the server root. |
102 |
Comment out or set to /dev/null (less effective) to disable access logging. |
103 |
.TP |
104 |
VerboseCGILogs |
105 |
This is a logical switch and does not take any parameters. |
106 |
Comment out to disable. |
107 |
.TP |
108 |
CGILog <filename> |
109 |
The location of the CGI error log file. If this does not start with /, it |
110 |
is considered relative to the server root. If specified, this is the file |
111 |
that the stderr of CGIs is tied to, *instead* of to the ErrorLog. |
112 |
.TP |
113 |
CGIumask <umask> |
114 |
The CGIumask is set immediately before execution of the CGI. |
115 |
The default value is 027. The number must be interpretable |
116 |
unambiguously by the C function strtol. No base is specified, |
117 |
so one may use a hexadecimal, decimal, or octal number if |
118 |
it is prefixed accordingly. |
119 |
.TP |
120 |
ServerName <server_name> |
121 |
The name of this server that should be sent back to |
122 |
clients if different than that returned by gethostname. |
123 |
.TP |
124 |
VirtualHost |
125 |
This is a logical switch and does not take any parameters. |
126 |
Comment out to disable. |
127 |
Given DocumentRoot /var/www, requests on interface 'A' or IP 'IP-A' |
128 |
become /var/www/IP-A. |
129 |
Example: http://localhost/ becomes /var/www/127.0.0.1 |
130 |
.TP |
131 |
VHostRoot <directory> |
132 |
The root location for all virtually hosted data |
133 |
Comment out to disable. |
134 |
Incompatible with 'Virtualhost' and 'DocumentRoot'!! |
135 |
Given VHostRoot /var/www, requests to host foo.bar.com, |
136 |
where foo.bar.com is ip a.b.c.d, |
137 |
become /var/www/a.b.c.d/foo.bar.com |
138 |
Hostnames are "cleaned", and must conform to the rules |
139 |
specified in rfc1034, which are be summarized here: |
140 |
|
141 |
Hostnames must start with a letter, end with a letter or digit, |
142 |
and have as interior characters only letters, digits, and hyphen. |
143 |
Hostnames must not exceed 63 characters in length. |
144 |
.TP |
145 |
DefaultVHost <hostname> |
146 |
Define this in order to have a default hostname when the client does not |
147 |
specify one, if using VirtualHostName. If not specified, the word |
148 |
"default" will be used for compatability with older clients. |
149 |
.TP |
150 |
DocumentRoot <directory> |
151 |
The root directory of the HTML documents. If this does not start with |
152 |
/, it is considered relative to the server root. |
153 |
.TP |
154 |
UserDir <directory> |
155 |
The name of the directory which is appended onto a user's home directory if a |
156 |
~user request is received. |
157 |
.TP |
158 |
DirectoryIndex <filename> |
159 |
Name of the file to use as a pre-written HTML directory index. Please make |
160 |
and use these files. On the fly creation of directory indexes can be slow. |
161 |
.TP |
162 |
DirectoryMaker <directory> |
163 |
Name of the program used to generate on-the-fly directory listings. |
164 |
The program must take one or two command-line arguments, the first |
165 |
being the directory to index (absolute), and the second, which is optional, |
166 |
contains what Hydra would have the "title" of the document be. |
167 |
Comment out if you don't want on the fly directory listings. |
168 |
If this does not start with |
169 |
/, it is considered relative to the server root. |
170 |
.TP |
171 |
KeepAliveMax <integer> |
172 |
Number of KeepAlive requests to allow per connection. Comment out, or set |
173 |
to 0 to disable keepalive processing. |
174 |
.TP |
175 |
KeepAliveTimeout <integer> |
176 |
Number of seconds to wait before keepalive connections time out. |
177 |
.TP |
178 |
MimeTypes <file> |
179 |
The location of the |
180 |
.I mime.types |
181 |
file. If this does not start with /, it is considered relative to |
182 |
the server root. Set to /dev/null if you do not want to load a mime types |
183 |
file. Do *not* comment out (better use AddType!) |
184 |
.TP |
185 |
DefaultType <mime type> |
186 |
MIME type used if the file extension is unknown, or there is no file extension. |
187 |
.TP |
188 |
AddType <mime type> <extension> [extension...] |
189 |
Associates a MIME type with an extension or extensions. |
190 |
.TP |
191 |
Redirect, Alias, and ScriptAlias <path1> <path2> |
192 |
Redirect, Alias, and ScriptAlias all have the same semantics \-\- they |
193 |
match the beginning of a request and take appropriate action. Use |
194 |
Redirect for other servers, Alias for the same server, and ScriptAlias to |
195 |
enable directories for script execution. |
196 |
|
197 |
Redirect allows you to tell clients about documents which used to exist |
198 |
in your server's namespace, but do not anymore. This allows you tell |
199 |
the clients where to look for the relocated document. |
200 |
|
201 |
Alias aliases one path to another. Of course, symbolic links in the |
202 |
file system work fine too. |
203 |
|
204 |
ScriptAlias maps a virtual path to a directory for serving scripts. |
205 |
.PP |
206 |
Please see the included |
207 |
.I hydra.conf |
208 |
for defaults and examples. |
209 |
.SH HISTORY |
210 |
Like the Linux kernel, even numbered versions are "stable", and odd numbered |
211 |
versions are "unstable", or rather, "development". |
212 |
Versions 0.91 and 0.91beta of Hydra were released by Paul Phillips <paulp@go2net.com> |
213 |
.PP |
214 |
Version 0.92 was released by Larry Doolittle on |
215 |
December 12, 1996. |
216 |
.PP |
217 |
Version 0.93 was the development version of 0.94. |
218 |
.PP |
219 |
Version 0.94 was released 22 Jan 2000. |
220 |
.SH BUGS |
221 |
There are probably bugs, but we are not aware of any at this time. |
222 |
.SH AUTHOR |
223 |
Hydra was created by Nikos Mavroyanopoulos <nmav@gnutls.org>. |
224 |
It was based on Boa that was created by Paul Phillips <paulp@go2net.com>. |
225 |
Boa is now being maintained and enhanced by Larry Doolittle |
226 |
<ldoolitt@boa.org> and Jon Nelson <jnelson@boa.org>. |
227 |
This manual page is based on the boa manual. |
228 |
.PP |
229 |
.SH LICENSE |
230 |
This program is distributed under the GNU General Public License, as noted in |
231 |
each source file. |