commands/httpd/README

   1 httpd documentation 7/16/96 by Michael Temari <Michael@TemWare.Com>
   2 updated 2003-07-05 by Al Woodhull <awoodhull@hampshire.edu>
   3
   4 DISCLAIMER:
   5
   6 Use at own risk etc...
   7
   8
   9 COMMENTS:
  10
  11 Please send me any bug reports, comments, questions, etc...  My email
  12 address is Michael@TemWare.Com
  13
  14
  15 BACKGROUND:
  16
  17 httpd is a World Wide Web (WWW) server.  I wrote it from scratch so
  18 the setup and configuration will not be like other web servers though
  19 hopefully by reading this document there will be no problems in getting
  20 my web server up and running on your Minix system.
  21
  22
  23 COMPILING:
  24
  25 To compile httpd all you need to do is type "make" in the httpd source
  26 directory.  There should be no errors or warnings.  If you should run
  27 out of memory when compiling try adding the -m option to the CFLAGS
  28 list in the Makefile.
  29
  30
  31 INSTALLING:
  32
  33 To install httpd all you need to do is type "make install" in the httpd
  34 source directory.  By default the place to install httpd is into
  35 /usr/local/bin.  If you would like to change this then change BINDIR in
  36 the Makefile.  Httpd will be linked to in.httpd, which is the preferred
  37 name for a program started by the tcpd internet access control program.
  38 The program dir2html is also installed -- this provides a directory
  39 listing when a web client accesses a directory which does not contain a
  40 file named index.html (or an alternative designated in /etc/httpd.conf).
  41 The man pages are installed by typing "make installman".
  42
  43 CONFIGURING:
  44
  45 Before running httpd it must be configured.  The name of the default
  46 configuration file is /etc/httpd.conf or you may pass the configuration
  47 file name to httpd.  Upon starting up, httpd will parse the configuration
  48 file and then process requests.  This README file and the sample httpd.conf
  49 may also help in configuring. The httpd.conf.5 man page presents the same
  50 information for reference use.
  51
  52
  53 The configuration file is an ascii file which consists of lines of the
  54 following form:
  55
  56 directive LWS [parameters separated by LWS]
  57
  58 NOTE: LWS denotes Linear White Space which is spaces and/or tabs
  59
  60 The following are valid configuration file directives:
  61   serverroot user chroot logfile dbgfile dirsend direxec vhost auth
  62   proxyauth vpath include mtype
  63
  64 To make the file more readable, on directives which occupy multiple
  65 lines you may omit the directive on lines after the first and begin
  66 these lines with LWS.
  67
  68
  69 serverroot path
  70
  71 The serverroot directive sets the translation for // to the given path.
  72
  73
  74 user username
  75
  76 The user directive causes the server to run as the given username, otherwise
  77 the server will run as whoever started it (normally root).
  78
  79
  80 chroot directory
  81
  82 The chroot directive causes the server to chroot to the given directory after
  83 the configuration and log files have been opened.  Normally this will be the
  84 home directory of the given username in the user directive.
  85 NOTE: /~user will be translated to the home directory of the given user
  86       // will be translated to the serverroot directory
  87 NOTE: if this directive is used then beware of the consequences.
  88
  89
  90 logfile filename
  91
  92 The logfile directive tells the server where to log http transactions.
  93 NOTE: the file must exist to enable logging
  94
  95
  96 dbgfile filename
  97
  98 The dbgfile directive tells the server where to log debug http transactions.
  99 NOTE: the file must exist to enable logging
 100
 101 dirsend filelist
 102
 103 The dirsend directive tells the server that when a directory is requested
 104 that it should send the first file that it finds in the directory from the
 105 filelist for the request.
 106
 107
 108 direxec program
 109
 110 The direxec directive tells the server that when a directory is requested
 111 and no file is found from the dirsend directive that it should run the
 112 given program.
 113 NOTE: the program normally generates a directory listing on the fly
 114 NOTE: the program access is considered X with no access restrictions.
 115
 116
 117 vhost hostname VhostRoot
 118
 119 vhost is for defining access for virtual hosts.  If none are configured then
 120 any host is accepted.  If specified then access is only granted for requests
 121 for hosts which are configured here.  In the Vpath section below the /// gets
 122 translated to the corresponding VhostRoot.
 123
 124
 125 auth authname authdescription access [passwdfile [users]]
 126
 127 The auth directive sets up different authorizations with the server.  The
 128 authname is the name given to the authorization and is case insensitive.
 129 The authdescription is the description of the authorization and is what
 130 the user will see when asked to enter a username and password.  The
 131 access is one or more of (rwx).  R tells the server the url can be
 132 read.  W tells the server the url can be overwritten.  X tells the server
 133 that the url can and should be executed.  Access is in addition to normal
 134 unix security considerations.  For instance a file that can be written to
 135 that does not have the W access will have an error returned.  The
 136 passwdfile is the name of the passwdfile to validate users against.  If
 137 the passwdfile is given as '.' then the system password file will be used
 138 which is /etc/passwd.  If no passwdfile is given then no authorization is
 139 allowed for anyone.  If no users are given then any validated users is
 140 authorized, otherwise only the given users are allowed.
 141
 142
 143 proxyauth authname authdescription access [passwdfile [users]]
 144
 145 proxyauth defines any access authorization to be used for Proxy access
 146 authname = Same as auth above
 147 authdescription = Same as auth above
 148 access = Must be R to allow proxy
 149 passwdfile = Same as auth above
 150 users = Same as auth above
 151
 152
 153 vpath from to [auth [access]]
 154
 155 The vpath directive sets up url path translations and authorizations.  A
 156 requested url that matches from will be translated to to with the given
 157 auth and access.  If auth does not exist then the url will have no access.
 158 If access is not given then the access is taken from the auth record (see
 159 above).  A '.' in place of the to means that the server should use a
 160 translation from another vpath record, but associate the given auth and
 161 access with the requested url.  A '*' maybe at the end only of the from
 162 which is a wildcard match.  For example if the from has /AB* then any of
 163 /ABCDEF or /AB or /ABmichael will match, but /AD or /a will not.  The
 164 requested url is first checked against each vpath record until an exact
 165 match (meaning url match from and from had no '*') is found or the end of
 166 the list.  Therefore a wildcard match will match the last from is the list
 167 in which it matched.
 168 NOTE: if at the beginning of the to field
 169       /~user will get translated to the home directory of the given user
 170       // wile get translated to the serverroot directory
 171
 172
 173 include filename
 174
 175 The include directive tells the server to read configuration information
 176 from the given filename.
 177 NOTE: normally mtype directives are included from another file
 178
 179
 180 mtype mimetype extensions
 181
 182 The mtype directive tells the server what mimetype to associate with files
 183 which have any of the given extensions.  If no match is found then the file
 184 will be treated as application/octet-stream.
 185 NOTE: normally you get mtype directives in included file
 186
 187
 188
 189 USAGE:
 190
 191                 httpd [-v|-t] [configuration-file]
 192
 193 The -t tells the server to just parse the configuration file so that you
 194 can test it to see if it is the way you want it.  You may also pass the
 195 name of your configuration file if it is not the default /etc/httpd.conf.
 196
 197 The -v option prints the server version and then exits.
 198
 199
 200 STARTING:
 201
 202 First of all httpd is a server and therefore you will need to start it
 203 with tcpd.  Tcpd is a program which listens for incoming TCP connections
 204 on the passed port and when a connection comes in it forks and starts the
 205 given daemon program.  Therefore to start httpd you use:
 206
 207                 tcpd http /usr/local/bin/in.httpd &
 208
 209 You will more than likely have this line in your /etc/rc or /etc/rc.net
 210 file so that whenever your system is restarted the web server will also
 211 be started.  The first parameter http is the port that tcpd is going
 212 to be listening for connections on.  Here http (which should be defined
 213 in /etc/services as 80) is the standard port for a web server.  The second
 214 parameter is the program that tcpd will fork and exec when a connection
 215 comes in.  The program will then have its stdin and stderr connected to
 216 the client  Then the web server program will start running with the tcpd
 217 program waiting for the next connection.  Currently there is no ability to
 218 limit the number of simultaneous web servers running.  NOTE: At some point
 219 I will be adding the ability for httpd to start itself without the need of
 220 tcpd.  That way httpd will already be in memory and have parsed its
 221 configuration file.
 222
 223 In Minix 2.0.3 and later versions you may use:
 224
 225                 daemonize tcpd http /usr/local/bin/in.httpd
 226
 227 (daemonize is a shell function defined in /usr/etc/rc which starts programs
 228 as daemons).
 229
 230
 231 FINAL WORDS
 232
 233 I wanted to get the server out as soon as possible so I hurried up and
 234 created this document to help out.  Hopefully it will HELP more than
 235 it HURTS.  If anyone is interested in writing man pages for httpd or any
 236 of the other network programs please let me know.
 237
 238
 239 Michael Temari
 240 Michael@TemWare.Com
 241
 242 Please note also the SECURITY document in this directory. (asw 2003-07-05)