Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HTTPD(1)		FreeBSD	General	Commands Manual		      HTTPD(1)

     httpd -- WWW server conforming to HTTP/1.1

     httpd [-v]
     httpd [-c configfile] [-P preprocessor] [-m message] [-N] [-p port]
	   [-u user] [-g group]	[-n number] [-d	directory] [-a address]

     This manual describes the behaviour of xs-httpd/3.7 beta/0.35.

     Note that the server must run as root in order to use a port number below
     or	equal to 1024 (the default is 80).  Also, to have users' CGI binaries
     executed under their own user ID, the webserver should be started with
     root privileges.

     The server	has a number of	command	line options. These are	listed below,
     starting with the options that do not have	an equivalent configuration
     file setting:
     -c	configfile
	     Uses the specified	configuration file instead of the default.
	     The default location can be displayed using the -v	option.
     -P	preprocessor
	     Run the preprocessor command to parse the global configuration
	     file, for example `m4' or `cpp'.  A fixed preprocessor program
	     can also be set at	compile	time.
     -m	service-message
	     If	you give this option to	the server, it will not	function as it
	     normally would. Instead of	supplying documents, all it will do is
	     display the service-message.  This	is very	useful to at least
	     give users	an idea	of what	you are	doing when the server is tem-
	     porarily out of order. Remember that if you are supplying an en-
	     tire sentence, then you have to enclose that sentence in quotes
     -N	     This option disables reading of the configuration file and	writ-
	     ing of logfiles and pidfile. This can be useful for testing, non-
	     superuser execution or in combination with	the -m option.
     -v	     Shows the server version number and certain compile options.
	     This does not launch a daemon but exits immediately.

     Additional	options	may be specified on the	command	line or	in the
     httpd.conf	configuration file. Please use the more	flexible configuration
     file for all standard settings, see httpd.conf(5) for details.
     -p	portnumber
	     Listen for	incoming HTTP requests on port portnumber instead of
	     the default (the factory default is 80).
     -u	username
	     Runs the server under username' s user id instead of the default
	     (the factory default is nobody).  This option is only available
	     when running as root and the selected user	should be unprivileged
	     (it can not be root).
     -g	groupname
	     Runs the server under groupname 's	group id instead of the	de-
	     fault nogroup.
     -n	number
	     Uses number as the	number of servers to start (the	factory	de-
	     fault is 20).
     -d	rootdir
	     Uses rootdir as the base directory	for other directories like the
	     logs directory, the htdocs	directory and the cgi-bin directory.
	     The factory default rootdir is @rootdir@/.
     -a	address
	     Uses address as the internet address to listen on.	This name may
	     be	used in	redirects, so the fully	qualified domain name for this
	     address should be used.

   Server design
     XS-httpd has some important features that distinguishes it	from other
     well-known	webservers. The	following list highlights the main concepts:

     - Small and fast
	 The webserver was designed to be small	and fast. Although it should
	 be fully standards-compliant, it does lack some of the	more elaborate
	 features that other servers offer.

	 An important design choice is to run with pre-forked processes: which
	 means it doesn't start	up a new client	process	for every connection
	 to the	webserver. This	has advantages and disadvantages, but in gen-
	 eral leads to a faster	response and less overhead.

     - Multi-user environment
	 The server can	be used	on a multi-user	system where every user	has
	 their own website(s). The webpages will be retrieved under the	user's
	 uid, so there is no need to make documents with sensitive data	(such
	 as database passwords)	readable to other users	on the same server.

	 CGI scripts, server-side include controls (SSI) and server-side in-
	 terpreters (PHP, Python) will run with	full user privileges as	well.
	 This gives the	users a	lot of flexibility to organise their own web-
	 space and also	limits the effect of problems with a user's scripts to
	 their own environment.	See httpd_cgi(7) and httpd_ssi(7) for detailed

     - Full user control
	 It should be possible for skilled users to exercise a great deal of
	 control over their own	webspace. The ability to run CGI binaries in
	 any language or choose	local interpreters and mime-types for any doc-
	 ument is an important aspect of this.

	 But users can also limit access to (part of) their webspace to	cer-
	 tain visitors using (built-in)	HTTP authentication with freely	chosen
	 usernames and passwords. Users	can choose for Basic or	Digest authen-
	 tication, or even configure access using SSL client-certificates, or
	 blocking/allowing certain IP ranges.

	 Of course the amount of control a user	actually has can be limited by
	 the webserver administrator. It is for	instance possible to set re-
	 source	limits on user scripts,	or even	disable	the feature completely
	 in the	global configuration file.

   Automatic decompression
     One of the	nice features of the WWW server	is automatic decompression.
     This feature is dealt with	in the file called compress.methods.

     This file lists the possible compression types that are understood	by the
     WWW server. It works very simply: if somebody asks	for (for example)
     index.html, and this file does not	exist, but index.html.gz does exist,
     then index.html will be `generated' out of	index.html.gz using the	method
     specified with .gz.  Note that this process does not actually create
     index.html	in that	same directory.	It creates a file in the temporary di-
     rectory, which is removed immediately after usage.

     In	the case that the browsers accepts certain document encodings (gzip is
     quite common) and the document is stored on disk in an acceptable format,
     then the server won't even	bother to decompress the document himself, but
     will send it to the client	compressed as it is, so	that the browser will
     extract it	itself before presenting the document to the user.

     If	somebody asks directly for index.html.gz, he will get it in the	com-
     pressed format. This way, nice things like	the following can be done:
	   Get <A HREF="xshttpd.tar">the uncompressed tar</A>,
	   or get the <A HREF="xshttpd.tar.gz">the compressed tar</A>.

     The user only has to have the compressed version, because if somebody
     asks for the uncompressed version,	the server will	uncompress it on the
     fly for that user.

     Note that only one	compression type per file is possible. Of course, you
     can make frontends	for types that require multiple	filters. In that case,
     it	can be helpful to know that the	list is	traversed from top to bottom.

     This server supports the basic and	digest HTTP authentication protocols.
     This means	that users can protect their pages with	a username/password
     combination. Other	servers	can do this as well, but they lack one thing:
     the "protected" files often have to be world-readable. Because our	server
     retrieves pages under users' own uid, this	problem	is avoided.

     Basic authentication does not provide (password) encryption. If you are
     worried about other parties intercepting your communications, you should
     configure SSL (as explained below).  More information about setting up
     authentication passwords can be found in the manual pages of xspasswd(1)
     and xsauth(5).

     Authentication can	also be	handled	using SSL client certificates.	How-
     ever this requires	the user to deal with SSL_* environment	variables in
     an	CGI environment. See the description of	the available CGI variables in

   Secure Sockets Layer
     The webserver supports secure https connections as	well as	normal http.
     However if	you want to do both, you will need to run separate instances,
     one with UseSSL (or the command line option -s) set and one without.

     To	use SSL	you will need an X.509 certificate (cert.pem) and the corre-
     sponding private key (key.pem).  If you don't have	certificates -or a
     certificate authority to give these to you- then you can create the re-
     quired files yourself using openssl(1).

     The two *.pem files are usually stored in the httpd configuration direc-
     tory. You can use other filenames for the certificate and private key by
     setting the parameters SSLCertificate and SSLPrivateKey in	the configura-
     tion file.

     An	example	SSL-Makefile that can help you generate	the certificate, can
     be	found in the httpd source distribution.

   Additional HTTP/1.1 features
     Several new features were derived from the	RFC 2616 standard:
     +o	 Persistent connections	(multiple get/post requests per	connection)
     +o	 Additional http methods (OPTIONS, PUT,	DELETE and TRACE)
     +o	 Chunked transfers (both for input and output)
     +o	 Content trailers (additional headers following	end of data)
     +o	 Conditional requests (If-*, Accept-*)
     +o	 Content entity	tags (ETag) and	digests	(MD5 checksum)

   Built-in support for	common tasks
     XS-httpd configuration files, server-side includes	and several additional
     programs make certain tedious tasks a lot simpler for the common user.
     Examples are:
     +o	 Page counters served using server-side	includes: daily	or total page
	 views can be included in text or in graphical fonts.
     +o	 Easy configuration of headers that describe the content: the mime-
	 type, character set and language of documents can be set per file,
	 file extension	or directory tree by the user.
     +o	 Allow user-settable redirects (HTTP 301, 302 code), server-side file-
	 name rewriting	rules or proxying to have the server retrieve contents
	 from another backend server.

     All environment variables which were set when the program was started
     will be ignored. These are	not available to CGI scripts or	other child
     processes.	See httpd_cgi(7) for the variables that	will be	available
     within the	httpd environment.

     The global	configuration file is httpd.conf: this should be configured by
     the site administrator before starting the	webserver. All available set-
     tings are explained in httpd.conf(5).

     There are several files that this WWW server considers special when they
     appear in the HTML	documents directories. These files start with a	dot
     (hidden) and contain special instructions for the webserver that apply to
     a sigle file or all files in a directory (and underlying subdirectories).

	     This file provides	a generic interface to set a lot of the	op-
	     tions mentioned below, specifically for a certain file or group
	     of	files.	It allows you to set file-specific mime	type, charac-
	     ter set, passwords	and other access restrictions. See xsconf(5)
	     for full details.

     .noxs   If	this file exists in a certain directory, that entire directory
	     is	considered closed. If somebody attempts	to retrieve a file
	     from that directory, he will get a	`Permission denied' notice.
	     This is useful for	users and system administrators: users can use
	     it	when they are updating the directory and system	administrators
	     can use it	to easily shut down a group of pages. This applies to
	     subdirectories as well.

	     It	is possible to allow access to this directory for a limited
	     number of hosts. You can list the IP-addresses to which access
	     should be granted in this file (one address per line). This works
	     for IPv4 as well as IPv6 addresses. Or you	can use	CIDR notation
	     to	allow an entire	subnet.	So including ""	will
	     unblock -

     .redir  If	this file is present in	a certain directory, and a file	is re-
	     quested from that directory, then a redirection message will be
	     sent to the remote	user's browser.	See xsredir(5) for the format
	     of	this file.

	     If	this file exists, all files in that directory and subdirecto-
	     ries are protected	by usercode/password combinations. See
	     xsauth(5) for more	details	about this.

     Use of the	following files	is deprecated. They can	still be used, but
     support may be dropped in the future.  The	same (or better) functionality
     is	offered	by the xsconf(5) local configuration feature.

	     If	a (regular) file is requested and a file exists	with the same
	     name but with that	is mentioned in	this *.redir file.

	     The same as `*.redir', however instead of a temporary redirection
	     (302) a permanent redirection (301) will be sent.

	     If	this file is present in	a certain directory, then all files
	     requested from that directory will	get an extra HTTP header which
	     indicates the character set used, as specified by the contents of
	     the .charset file.	Useful settings	are e.g. UTF-8,	ISO-8859-1,

	     Sets the character	set for	a specific file	(see *.redir).

	     This file lets a user override the	contents of the	global
	     mime.types	file. The syntax of this file is exactly the same as
	     that for the global configuration file, but it applies (recur-
	     sively) to	the local subdirectories.

	     This file lets a user override the	contents of the	global
	     script.methods fP file. The syntax	of this	file is	exactly	the
	     same as that for the global configuration file and	it applies
	     (recursively) to the local	subdirectories.	See xsscripts(5) for
	     more information.

     .xsuid  If	this file exists in a certain directory, all files in that di-
	     rectory will be retrieved as (by default) nobody/nogroup instead
	     of	under your own UID. This can be	useful if you want a file per-
	     mission of	say 600	to mean: do not	allow retrieval	(by default,
	     the file is retrieved under your own UID, so the daemon could
	     have still	read those files).

     The httpd returns status 0	when it	starts successfully and	the daemon
     will continue to run in the background. If	any fatal error	occurs,	addi-
     tional information	should be available in the logfile error_log.

     httpdc(1),	xspasswd(1), xsindex(1), readxs(1), clearxs(1),	imagemap(1),
     gfxcount(1), xschpass(1), httpd.conf(5), xsauth(5), xsconf(5),
     xsredir(5), xsscripts(5), httpd_cgi(7), httpd_ssi(7)

     The project homepage:

     Hypertext Transfer	Protocol -- HTTP/1.0, RFC 1945,	May 1996.
     Hypertext Transfer	Protocol -- HTTP/1.1, RFC 2616,	June 1999.
     HTTP Authentication: Basic	and Digest Access Authentication, RFC 2617,
     June 1999.
     HTTP State	Management Mechanism, RFC 2965,	October	2000.
     The Common	Gateway	Interface (CGI)	Version	1.1, RFC 3875, October 2004.
     The Transport Layer Security (TLS)	Protocol Version 1.1, RFC 4346,	April
     FastCGI Specification Version 1.0,, April 1996.

     The original author of this WWW server and	its accompanying programs is
     Sven Berkvens, except the imagemapper which was taken from	the NCSA dis-
     tribution and cleaned up. The current maintainer is Johan van Selst.

     Please use	the general contact address <>	for queries.

     Support for the alternative document processing methods using internal
     Perl, Python, Ruby	or FastCGI hooks is still highly experimental and not
     very useful.  These features should not be	used in	a production environ-

xs-httpd/3.5			March 26, 1996			  xs-httpd/3.5


Want to link to this manual page? Use this URL:

home | help