.\" -*- nroff -*- .\" .\" httpd -- Simple httpd-server man page .\" Copyright (c) 1995, 1996, 1997, 1998 Tero Kivinen .\" All Rights Reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation is hereby granted, provided that both the copyright .\" notice and this permission notice appear in all copies of the .\" software, derivative works or modified versions, and any portions .\" thereof, and that both notices appear in supporting documentation. .\" .\" TERO KIVINEN ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" .\" CONDITION. TERO KIVINEN DISCLAIMS ANY LIABILITY OF ANY KIND FOR .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. .\" .\" .\" .\" Program: simple httpd-server .\" $Source: /iki/src/simple-httpd/RCS/httpd.8,v $ .\" $Author: kivinen $ .\" .\" (C) Tero Kivinen 1995,1996,1997,1998 .\" .\" Creation : 09:24 Jan 30 1998 kivinen .\" Last Modification : 14:06 Dec 6 1997 kivinen .\" Last check in : $Date: 2011/04/06 11:05:08 $ .\" Revision number : $Revision: 1.3 $ .\" State : $State: Exp $ .\" Version : 1.0 .\" Edit time : 0 min .\" .\" Description : Simple http-server man page .\" .\" .\" $Log: httpd.8,v $ .\" Revision 1.3 2011/04/06 11:05:08 kivinen .\" Added -6 option documentation. .\" .\" Revision 1.2 2010/02/17 13:41:58 kivinen .\" Updated address. .\" .\" Revision 1.1 2002/11/07 23:19:33 kivinen .\" Created. .\" .\" .\" .\" .\" If you have any useful modifications or extensions please send them to .\" Tero.Kivinen@iki.fi .\" .TH HTTPD 8 "January 30, 1998" "HTTPD" "HTTPD" .SH NAME httpd \- simple and extremely fast httpd server .SH SYNOPSIS .na .B httpd [\c .B \-d \c ] [\c .B \-i \c ] [\c .B \-6 \c ] [\c .BI \-g \ gid\fR\c ] [\c .BI \-u \ uid\fR\c ] [\c .BI \-p \ port\fR\c ] .I redirection-filename .I htdocs-directory .ad .SH DESCRIPTION .LP .B Httpd is a very simple and extremely fast httpd server that provides two basic httpd functions: redirections and normal page serving. It does not support any kind of cgi-bins, loadable modules etc. .LP When the .B httpd starts it first reads the redirection configuration file and all files from the htdocs directory given by command line. All the files from that directory downwards are read in the memory and they are never released from the memory, so the .B httpd process takes as much memory as there is pages to be served in the htdocs directory. .LP The redirection configuration file that will contain entries that tell what local url is redirected to what remote url. The file format is very simple. There are two whitespace separeted fields in a row and the first entry is the local url and the second one is the remote url. .LP When the http request cames in the permanent page cache is first checked. This cache contains all the permanent pages from the htdocs directory preformatted and if the match is found it just starts writing the reply back from the preformatted memory buffer. This means that for small pages replying to a page requests only needs one read, some small processing to get the url out, one bsearch from the cache and two writes to write the data back (one for headers and one for data). The data is never copied in the process, it is written directly from the cache buffers. All the data is kept preformatted in the memory so no formatting or reading data from disk is needed in the process. .LP The server also starts serving the request as soon as it has enough data to work on so it answers as soon as the first line of the request is received. Because some clients didn't like that the httpd server replied to their request complately (including eof) before they have finished their request, the .B httpd now waits after sending the reply the client to send the rest of the requests and sends eof only after that. .LP If no match is found from the permanent page cache then the temporary memory cache is examined in the same way. .LP If no match is found from the caches it then checks if the the first part of the url (up to first slash in the url) can be found in the redirection list and if so it will create a subpage redirection entry and put that in the cache. The subpage redirection entry is formed in such way that the remote url is first taken as it is and the data after the first slash in the http request url is added to that. This means that the remote redirection url must end up to slash to get subpage requests to work. .LP If the request is not subpage request then the final check is to see if it is user homepage request in a form /~kivinen/. If that username is valid and its homedirectory has public_html directory having that filename, that file is read in the temporary cache and served in the normal way. .LP If the real page is found (not a redirection page) and its modification time hasn't been checked for a while (by default more than 5 minutes) the filename is stated to check if it is modified. If so the new contents of the file is read to memory. The temporary cache is periodically checked (by default every minute) if it contains entries that haven't been touched for a while (by default 10 minutes) and if so they are removed from the cache. .LP All those timeouts can be configured by changing the defines in the beginning of the httpd.c file. .LP The httpd also understands to nonstandard commands in the httpd protocol. The first one "quit" will quit the httpd server. This can be used to reread the htdocs directory files to memory, because new files in that directory are not otherwise read to memory. Because it is very easy to quit the server you either need to have loop around .B httpd to restart it again when it is quit or you need to start it from the inetd that will automatically do the restarting. .LP The other command is "status" that can be used to request status information about the server. .LP .B httpd will log all connections to syslog using level .B INFO and it will also log statistics of last hour every hour to syslog using level .B NOTICE\c \. If the .B httpd is running as standalone server it will use facility .B DAEMON otherwise it will use the facility .B LOCAL0\c \. .LP By default .B httpd only binds to IPv4 address, if IPv6 support is needed then -6 option must be given, in which case it only binds to IPv6 address. If both IPv4 and IPv6 support is needed then two httpd servers needs to be started. .SH OPTIONS .TP .BI \-g \ gid Specifies the group id of the server. After the server has opened the master socket it will setgid itself to this gid if given. .TP .BI \-u \ uid Specifies the user id of the server. After the server has opened the master socket it will setuid itself to this uid if given. .TP .B \-d Specifies that the process istarted is started as stand alone server and it should fork and open the socket itself. .TP .BI \-p \ port If the .B httpd is running as stand alone server this option can be used to specify the port used by server. Default value is "http". .TP .B \-i Specifies that httpd is being run from inetd. .B httpd is normally run from inetd because it automatically binds the socket needed by httpd and if httpd dies the inetd will automatically start a new server. The .B httpd started from the inetd should be configured as wait service, because it only takes the socket bound by inetd and serves that socket until it is requested to quit. .TP .B \-6 Specifies that the .B httpd should bind on the IPv6 socket instead of IPv4 socket. .SH INSTALLATION You need to modify the defines in the beginning of the httpd.c file before using it. You need to modify the LOCAL_ROOT_URL so that it will point to the full url to the local server without the final slash. This is needed to do local directory redirection entries. Also if you might need to add new entries to match_type function that will take file name and return mime type for it. .SH AUTHOR .LP Tero Kivinen .LP Information about new versions can be found from the iki home page at http://www.iki.fi/iki/src/ .SH SEE ALSO .LP .BR inetd (8)\c \.