sys/man/8/httpd

   1 .TH HTTPD 8
   2 .SH NAME
   3 httpd, save, imagemap, man2html, webls \- HTTP server
   4 .SH SYNOPSIS
   5 .B ip/httpd/httpd
   6 .RB [ -a
   7 .IR srvaddr ]
   8 .RB [ -c
   9 .I cert
  10 .RB [ -C
  11 .IR certchain ]]
  12 .RB [ -d
  13 .IR domain ]
  14 .RB [ -n
  15 .IR namespace ]
  16 .RB [ -w
  17 .IR webroot ]
  18 .PP
  19 .B ip/httpd/save
  20 .RB [ -b
  21 .IR inbuf ]
  22 .RB [ -d
  23 .IR domain ]
  24 .RB [ -r
  25 .IR remoteip ]
  26 .RB [ -w
  27 .IR webroot ]
  28 .RB [ -N
  29 .IR netdir ]
  30 .I method version uri
  31 .RI [ search ]
  32 .br
  33 .B ip/httpd/imagemap
  34 .I ...
  35 .br
  36 .B ip/httpd/man2html
  37 .I ...
  38 .br
  39 .B ip/httpd/webls
  40 .I ...
  41 .SH DESCRIPTION
  42 .I Httpd
  43 serves the
  44 .I webroot
  45 directory of the file system described by
  46 .I namespace
  47 (default
  48 .BR /lib/namespace.httpd ),
  49 using version 1.1 of the HTTP protocol.
  50 It announces the service
  51 .I srvaddr
  52 (default
  53 .BR tcp!*!http ),
  54 and listens for incoming calls.
  55 If an X.509 certificate is supplied with the
  56 .B -c
  57 option, then the service is instead
  58 .BR tcp!*!https .
  59 There should already be a factotum
  60 holding the corresponding private key.
  61 If the specified certificate has been signed
  62 by a certificate authority, the
  63 .B -C
  64 option may be used to specify a file
  65 containing a chain of signed certificates.
  66 .PP
  67 .I Httpd
  68 supports only the GET and HEAD methods of the HTTP protocol;
  69 some magic programs support POST as well.
  70 Persistent connections are supported for HTTP/1.1 or later clients;
  71 all connections close after a magic command is executed.
  72 The Content-type
  73 (default
  74 .BR application/octet-stream )
  75 and Content-encoding
  76 (default
  77 .BR binary )
  78 of a file are determined by looking for suffixes of the file name in
  79 .BR /sys/lib/mimetype .
  80 .SS Redirection
  81 .PP
  82 Each requested URI is looked up in a redirection table, read from
  83 .BR /sys/lib/httpd.rewrite .
  84 Fields are separated by spaces and tabs.
  85 Anything following a
  86 .L #
  87 is ignored.
  88 The first field of each line is a URI;
  89 the second a replacement path.
  90 If a prefix of the URI matches a redirection path,
  91 the URI is rewritten using the corresponding replacement path
  92 instead of the prefix,
  93 and a temporary redirect is sent to the HTTP client.
  94 If the replacement path does not specify a server name,
  95 and the request has no explicit host,
  96 then
  97 .I domain
  98 is the host name used in the redirection.
  99 The prefix can either be a domain root like
 100 .B http://system/
 101 (which matches that URL only)
 102 or a path like
 103 .B /who/rob
 104 (which matches that path no matter what
 105 the requested server),
 106 but not both:
 107 .B http://system/who/rob
 108 will never match a request.
 109 If the first field ends in a slash, this is an exact match;
 110 otherwise it is a prefix match.
 111 The first field is a literal string, matched against
 112 each file prefix of each URL.
 113 The most specific, i.e., longest,
 114 pattern wins, and is applied once (there is no rescanning),
 115 except for the following exceptions.
 116 .I Httpd
 117 matches only the prefix and not subordinate pages
 118 if a replacement is prefixed with
 119 .LR > .
 120 .I Httpd
 121 omits the unmatched part of the original URI
 122 from the rewritten URI if the replacement is prefixed with
 123 .LR * .
 124 This permits many-to-one mappings; for example,
 125 to send all references to an old subtree to a single error page.
 126 .PP
 127 .I Httpd
 128 handles replacements prefixed with
 129 .L @
 130 internally,
 131 treating the request as if it were for the replacement
 132 (without the
 133 .BR @ )
 134 but not informing the client of the rewritten name.
 135 Replacement URLs prefixed with
 136 .L =
 137 generate a permanent redirection instead of a temporary one.
 138 .I Httpd
 139 checks to see if this file has changed once every 50 new TCP connections.
 140 HTTP 1.1 persistent connection implies many pages
 141 may come in one browser connection, so to kick-start
 142 .IR httpd ,
 143 try
 144 .IP
 145 .EX
 146 for(i in `{seq 50}) hget http://www.your-domain.com/ >/dev/null
 147 .EE
 148 .SS "Access Control"
 149 .PP
 150 Before opening any file,
 151 .I httpd
 152 looks for a file in the same directory called
 153 .BR .httplogin .
 154 If the file exists, the directory is considered
 155 locked and the client must specify a user name
 156 and password matching a pair in the file.
 157 .B .httplogin
 158 contains a list of space or newline separated tokens, each
 159 possibly delimited by single quotes.  The first
 160 is a domain name presented to the HTTP client.
 161 The rest are pairs of user name and password.
 162 Thus, there can be many user name/password pairs
 163 valid for a directory.
 164 .br
 165 .ne 3
 166 .SS "Auxiliaries (magic)"
 167 .PP
 168 If the requested URI begins with
 169 .BI  /magic/ server /\f1,
 170 .I httpd
 171 executes the file
 172 .BI /bin/ip/httpd/ server
 173 to finish servicing the request.
 174 All the auxiliaries take the same arguments.
 175 .IR Method
 176 and
 177 .IR version
 178 are those received on the first line of the request.
 179 .I Uri
 180 is the remaining portion of the requested URI.
 181 .I Inbuf
 182 contains the rest of the bytes read by the server,
 183 and
 184 .I netdir
 185 is the network directory for the connection.
 186 There are routines for processing command arguments,
 187 parsing headers, etc. in the httpd library,
 188 .BR /sys/src/cmd/ip/httpd/libhttpd.a.$O .
 189 See
 190 .B httpd.h
 191 in that directory and existing magic commands for more details.
 192 .PP
 193 .I Save
 194 writes a line to
 195 .BI /usr/web/save/ uri .data
 196 and returns the contents of
 197 .BI /usr/web/save/ uri .html.
 198 Both files must be accessible for the request to succeed.
 199 The saved line includes the current time
 200 and either the search string from a HEAD or GET
 201 or the first line of the body from a POST.
 202 It is used to record form submissions.
 203 .PP
 204 .I Imagemap
 205 processes an HTML imagemap query.
 206 It looks up the point
 207 .I search
 208 in the image map file given by
 209 .IR uri ,
 210 and returns a redirection to the appropriate page.
 211 The map file defaults to NCSA format.
 212 Any entries after a line starting with the word
 213 .B #cern
 214 are interpreted in CERN format.
 215 .PP
 216 .I Man2html
 217 converts
 218 .IR man (6)
 219 format manual pages into html.
 220 It includes some abilities to search the manuals.
 221 .PP
 222 .I Webls
 223 produces directory listings on the fly, with
 224 output in the style of
 225 .IR ls (1).
 226 .B /sys/lib/webls.allowed
 227 and
 228 .B /sys/lib/webls.denied
 229 contain regular expressions describing
 230 what parts of
 231 .I httpd's
 232 namespace may and may not be listed, respectively.
 233 .B Webls.denied
 234 is first searched to see if access is by default
 235 denied.  If so
 236 .B webls.allowed
 237 is then searched to see if access is explicitly allowed.
 238 Thus one can have very general expressions in the
 239 denied list (like
 240 .BR .* ),
 241 yet still allow exceptions.  If
 242 .B webls.denied
 243 does not exist or is unreadable,
 244 all accesses are assumed to be denied unless
 245 explicitly allowed in
 246 .B webls.allowed.
 247 .PP
 248 Other sites will note that if neither
 249 .B webls.denied
 250 nor
 251 .B webls.allowed
 252 exist, any portion of
 253 .I httpd's
 254 namespace can be listed (however,
 255 .I webls
 256 will always endeavor to prevent listing of `.' and `..').
 257 If
 258 .B webls.allowed
 259 exists but
 260 .B webls.denied
 261 does not, any directory to be listed must be described
 262 by a regular expression in
 263 .BR webls.allowed .
 264 Similarly, if
 265 .B webls.denied
 266 exists but
 267 .B webls.allowed
 268 does not, any directory to be listed must
 269 .I not
 270 be described by a regular expression in
 271 .BR webls.denied .
 272 If both exist, a directory is listable if either
 273 it doesn't appear in
 274 .BR webls.denied ,
 275 or it appears in both
 276 .B webls.denied
 277 and
 278 .BR webls.allowed .
 279 In other words,
 280 .B webls.allowed
 281 overrides
 282 .BR webls.denied .
 283 If a listing for a directory is requested and access
 284 is denied, or another error occurs, a simple error
 285 page is returned.
 286 .SH EXAMPLES
 287 These are all examples of how to use
 288 .BR httpd.rewrite .
 289 .PP
 290 A local redirection:
 291 .RS
 292 .EX
 293 /netlib/c++/idioms/index.html.Z /netlib/c++/idioms/index.html
 294 .EE
 295 .RE
 296 .PP
 297 Redirection to another site:
 298 .RS
 299 .EX
 300 /netlib/lapack/lawns            =http://netlib.org/lapack/lawns
 301 http://inferno.bell-labs.com    =http://www.vitanuova.com
 302 .EE
 303 .RE
 304 .PP
 305 Root directory for virtual host:
 306 .RS
 307 .EX
 308 http://www.ampl.com             /cm/cs/what/ampl
 309 .EE
 310 .RE
 311 .SH FILES
 312 .TF /sys/lib/httpd.rewrite
 313 .TP
 314 .B /sys/lib/mimetype
 315 content type description file
 316 .TP
 317 .B /lib/namespace.httpd
 318 default namespace file for httpd
 319 .TP
 320 .B /sys/lib/httpd.rewrite
 321 redirection file
 322 .TP
 323 .B /sys/lib/webls.allowed
 324 regular expressions describing explicitly listable pathnames; overrides
 325 .B webls.denied
 326 .TP
 327 .B /sys/lib/webls.denied
 328 regular expressions describing explicitly unlistable pathnames
 329 .SH SOURCE
 330 .B /sys/src/cmd/ip/httpd
 331 .SH "SEE ALSO"
 332 .I newns
 333 in
 334 .IR auth (2),
 335 .IR listen (8),
 336 .IR rsa (8)