1.\"	$MirOS: src/usr.sbin/httpd/httpd.8,v 1.3 2008/03/19 23:07:17 tg Exp $
2.\"	$OpenBSD: httpd.8,v 1.27 2007/05/31 19:20:24 jmc Exp $
3.\" Copyright (c) 1995-1997 David Robinson. All rights reserved.
4.\" Copyright (c) 1997-1999 The Apache Group. All rights reserved.
5.\" Copyright (c) 1998-1999 Bob Beck. All rights reserved.
6.\" Copyright (c) 2002-2003 Henning Brauer. All rights reserved.
7.\" Copyright (c) 2004-2005 Thorsten Glaser. All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\"
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\"
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in
18.\"    the documentation and/or other materials provided with the
19.\"    distribution.
20.\"
21.\" 3. All advertising materials mentioning features or use of this
22.\"    software must display the following acknowledgment:
23.\"    "This product includes software developed by the Apache Group
24.\"    for use in the Apache HTTP server project (http://www.apache.org/)."
25.\"
26.\" 4. The names "Apache Server" and "Apache Group" must not be used to
27.\"    endorse or promote products derived from this software without
28.\"    prior written permission.
29.\"
30.\" 5. Redistributions of any form whatsoever must retain the following
31.\"    acknowledgment:
32.\"    "This product includes software developed by the Apache Group
33.\"    for use in the Apache HTTP server project (http://www.apache.org/)."
34.\"
35.\" THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
36.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
37.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
38.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE APACHE GROUP OR
39.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
41.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
42.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
43.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
44.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
45.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
46.\" OF THE POSSIBILITY OF SUCH DAMAGE.
47.\" ====================================================================
48.\"
49.\" This software consists of voluntary contributions made by many
50.\" individuals on behalf of the Apache Group and was originally based
51.\" on public domain software written at the National Center for
52.\" Supercomputing Applications, University of Illinois, Urbana-Champaign.
53.\" For more information on the Apache Group and the Apache HTTP server
54.\" project, please see <http://www.apache.org/>.
55.Dd $Mdocdate: March 19 2008 $
56.Dt HTTPD 8
57.Os
58.Sh NAME
59.Nm httpd
60.Nd Hypertext Transfer Protocol Daemon
61.Sh SYNOPSIS
62.Nm httpd
63.Bk -words
64.Op Fl 46FhLlSTtuVvX
65.Op Fl C Ar directive
66.Op Fl c Ar directive
67.Op Fl D Ar parameter
68.Op Fl d Ar serverroot
69.Op Fl f Ar config
70.Op Fl R Ar libexecdir
71.Ek
72.Sh DESCRIPTION
73.Nm
74is the
75.Mx
76HyperText Transfer Protocol (HTTP) server program.
77It is designed to be run as a stand-alone daemon process.
78When used like this it will create a pool of child processes to
79handle requests.
80To stop it, send a
81.Dv TERM
82signal to the initial (parent) process.
83The PID of this process is written to a file as given in the
84configuration file.
85Normally this service can be enabled for startup on
86.Mx
87by editing
88.Pa /etc/rc.conf.local .
89.Pp
90Alternatively,
91.Nm
92may be invoked by the Internet daemon
93.Xr inetd 8
94each
95time a connection to the HTTP service is made.
96.Pp
97.Nm
98can be made to support HTTPS transactions
99if RSA certificates are generated
100and the utility is started with the
101.Va -DSSL
102flag.
103See
104.Xr ssl 8
105for further information.
106.Pp
107By default,
108.Nm
109will
110.Xr chroot 2
111to the
112.Dq ServerRoot
113path,
114serving documents from the
115.Dq DocumentRoot
116path.
117As a result of the default secure behaviour,
118.Nm
119cannot access any objects outside
120.Dq ServerRoot
121\- this security measure is taken in case
122.Nm
123is compromised.
124This is not without drawbacks, though:
125.Pp
126CGI programs may fail due to the limited environment available inside
127this chroot space.
128.Dq UserDir ,
129of course, cannot access files outside the directory space.
130Other modules will also have issues.
131.Dq DocumentRoot
132directories or any other files needed must be inside
133.Dq ServerRoot .
134For this to work,
135pathnames inside the configuration file do not need adjustment relative to
136.Dq ServerRoot .
137For this option to remain secure, it is important that no files or directories
138writable by user
139.Ar www
140or group
141.Ar www
142are created inside the
143.Dq ServerRoot .
144.Pp
145The
146.Fl u
147option
148(see below)
149can be specified to disable
150.Xr chroot 2
151functionality.
152.Pp
153This manual page only lists the command line arguments.
154For details of the directives necessary to configure
155.Nm ,
156see a local copy of the Apache(TM) manual in
157.Pa /var/www/htdocs/manual/ .
158This manual is not 100% accurate for
159.Mx
160.Nm
161though.
162Paths in this manual page reflect those
163compiled into
164.Nm
165by default with
166.Mx .
167.Pp
168The options are as follows:
169.Bl -tag -width Ds
170.It Fl C Ar directive
171Process the configuration
172.Ar directive
173before reading config files.
174.It Fl c Ar directive
175Process the configuration
176.Ar directive
177after reading config files.
178.It Fl D Ar parameter
179Sets a configuration
180.Ar parameter
181which can be used with
182<IfDefine>...</IfDefine> sections in the configuration files
183to conditionally skip or process commands.
184.It Fl d Ar serverroot
185Set the initial value for the
186.Dq ServerRoot
187directive to
188.Ar serverroot .
189This can be overridden by the
190.Dq ServerRoot
191command in the configuration file.
192The default is
193.Pa /var/www .
194.It Fl F
195Run the main process in foreground.
196For process supervisors.
197.It Fl f Ar config
198Execute the commands in the file
199.Ar config
200on startup.
201If
202.Ar config
203does not begin with a /, then it is taken to be a path relative to
204the ServerRoot.
205The default is
206.Pa conf/httpd.conf .
207.It Fl h
208Output a short summary of available command line options.
209.It Fl L
210Output a list of directives together with expected arguments and
211places where the directive is valid.
212.It Fl l
213Output a list of modules compiled into the server.
214.It Fl R Ar libexecdir
215This option is only available if
216.Nm
217was built with the
218.Dv SHARED_CORE
219rule enabled which forces the
220.Nm
221core code to be placed into a dynamic shared object (DSO) file.
222This file is searched in a hardcoded path under ServerRoot per default.
223Use this option to override.
224.It Fl S
225Show the settings as parsed from the config file (currently only shows the
226virtualhost settings).
227.It Fl T
228Run syntax tests for configuration files only, without DocumentRoot checks.
229The program immediately exits after this syntax parsing with either a return
230code of 0 (Syntax OK) or return code not equal to 0 (Syntax Error).
231.It Fl t
232Run syntax tests for configuration files only, including DocumentRoot checks.
233The program immediately exits after this syntax parsing with either a return
234code of 0 (Syntax OK) or return code not equal to 0 (Syntax Error).
235.It Fl u
236By default
237.Nm
238will
239.Xr chroot 2
240to the
241.Dq ServerRoot
242path.
243The
244.Fl u
245option disables this behaviour, and returns
246.Nm
247to the expanded "unsecure" behaviour.
248.It Fl V
249Print the version and build parameters of
250.Nm httpd ,
251and then exit.
252.It Fl v
253Print the version of
254.Nm httpd ,
255and then exit.
256.It Fl X
257Run in single-process mode, for internal debugging purposes only; the daemon
258does not detach from the terminal or fork any children.
259Do NOT use this mode to provide ordinary web service.
260.El
261.Pp
262The documents served by
263.Nm
264should not be owned by the user which
265.Nm
266is running as (usually user
267.Ar www
268and group
269.Ar www ) .
270They must, however, be readable by this user.
271.Sh FILES
272.Bl -tag -width /etc/passwd -compact
273.It Pa /var/www/cgi-bin/
274.It Pa /var/www/conf/httpd.conf
275.It Pa /var/www/conf/httpd.conf-dist
276.It Pa /var/www/conf/magic
277.It Pa /var/www/conf/mime.types
278.It Pa /var/www/icons/
279.It Pa /var/www/logs/access_log
280.It Pa /var/www/logs/error_log
281.It Pa /var/www/logs/etag-state
282.It Pa /var/www/logs/httpd.pid
283.It Pa /var/www/logs/ssl_engine_log
284.It Pa /var/www/logs/ssl_request_log
285.It Pa /var/www/logs/ssl_scache.db
286.It Pa /var/www/users/
287.It Pa /etc/rc.conf.local
288.El
289.Sh SEE ALSO
290.Xr dbmmanage 1 ,
291.Xr htdigest 1 ,
292.Xr htpasswd 1 ,
293.Xr chroot 2 ,
294.Xr apxs 8 ,
295.Xr inetd 8 ,
296.Xr logresolve 8 ,
297.Xr rc.conf.local 8 ,
298.Xr rotatelogs 8 ,
299.Xr ssl 8 ,
300.Xr suexec 8
301.Pp
302The
303.Mx
304httpd manual:
305.Pa /var/www/htdocs/manual/ .
306