HTTPD(8)                                                 HTTPD(8)

     NAME
          httpd, mirror, save, imagemap, man2html, webls - HTTP server

     SYNOPSIS
          ip/httpd/httpd [-a srvaddr] [-c cert] [-d domain] [-n
          namespace] [-w webroot]

          ip/httpd/mirror [-b inbuf] [-d domain] [-r remoteip] [-w
          webroot] [-N netdir] method version uri [search]

          ip/httpd/save [-b inbuf] [-d domain] [-r remoteip] [-w
          webroot] [-N netdir] method version uri [search]

          ip/httpd/imagemap [-b inbuf] [-d domain] [-r remoteip] [-w
          webroot] [-N netdir] method version uri

          ip/httpd/man2html [-b inbuf] [-d domain] [-r remoteip] [-w
          webroot] [-N netdir] method version uri [search]

          ip/httpd/notas [-b inbuf] [-d domain] [-r remoteip] [-w
          webroot] [-N netdir] method version uri [search]

          ip/httpd/group [-b inbuf] [-d domain] [-r remoteip] [-w
          webroot] [-N netdir] method version uri [search]

          ip/httpd/webls [-b inbuf] [-d domain] [-r remoteip] [-w
          webroot] [-N netdir] method version uri [search]

     DESCRIPTION
          Httpd serves the webroot directory of the file system
          described by namespace (default /lib/namespace.httpd), using
          version 1.1 of the HTTP protocol.  It announces the service
          srvaddr (default tcp!*!http), and listens for incoming
          calls.  If an X.509 certificate is supplied with the -c
          option, then the service is instead tcp!*!https.  There
          should already be a factotum holding the corresponding pri-
          vate key.

          Httpd supports only the GET and HEAD methods of the HTTP
          protocol; some magic programs support POST as well.  Persis-
          tent connections are supported for HTTP/1.1 or later
          clients; all connections close after a magic command is exe-
          cuted.  The Content-type (default application/octet-stream)
          and Content-encoding (default binary) of a file are deter-
          mined by looking for suffixes of the file name in
          /sys/lib/mimetype.

          Each requested URI is looked up in a redirection table, read
          from /sys/lib/httpd.rewrite.  If a prefix of the URI matches
          a redirection path, the URI is rewritten using a replacement

     Page 1                       Plan 9             (printed 3/29/24)

     HTTPD(8)                                                 HTTPD(8)

          path, and a redirect is sent to the HTTP client.  If the
          replacement path does not specify a server name, and the
          request has no explicit host, then domain is the host name
          used in the redirection.  The prefix can either be a domain
          root like http://system/ (which matches that URL only) or a
          path like /who/rob (which matches that path no matter what
          the requested server), but not both: http://system/who/rob
          will never match a request.  Httpd handles replacements pre-
          fixed with @ internally, treating the request as if it were
          for the replacement (without the @) but not informing the
          client of the rewritten name.

          Before opening any file, httpd looks for a file in the same
          directory called .httplogin.  If the file exists, the direc-
          tory is considered locked and the client must specify a user
          name and password machine a pair in the file.  .httplogin
          contains a list of space or newline separated tokens, each
          possibly delimited by single quotes.  The first is a domain
          name presented to the HTTP client.  The rest are pairs of
          user name and password.  Thus, there can be many user
          name/password pairs valid for a directory.

          If the requested URI begins with /magic/server/, httpd exe-
          cutes the file /bin/ip/httpd/server to finish servicing the
          request.  Method and version are those received on the first
          line of the request.  Uri is the remaining portion of the
          requested URI.  Inbuf contains the rest of the bytes read by
          the server, and netdir is the network directory for the con-
          nection.  There are routines for processing command argu-
          ments, parsing headers, etc. in the httpd library,
          /sys/src/cmd/ip/httpd/libhttpd.a.$O.  See httpd.h in that
          directory and existing magic commands for more details.

          Mirror is a trivial server that just returns the method,
          URI, any search, the headers, and the message body sent by
          the client.

          Save writes a line to /usr/web/save/uri.data and returns the
          contents of /usr/web/save/uri.html.  Both files must be
          accessible for the request to succeed.  The saved line
          includes the current time and either the search string from
          a HEAD or GET or the first line of the body from a POST.  It
          is used to record form submissions.

          Imagemap processes an HTML imagemap query.  It looks up a
          the point search in the image map file given by uri, and
          returns a redirection to the appropriate page.  The map file
          defaults to NCSA format.  Any entries after a line starting
          with the word #cern are interpreted in CERN format.

          Man2html converts man(6) format manual pages into html.  It
          includes some abilities to search the manuals.

     Page 2                       Plan 9             (printed 3/29/24)

     HTTPD(8)                                                 HTTPD(8)

          Notas gives access to student grades after searching for the
          student NIF in a grade listing. Listings are kept under
          /usr/prof/notas Each listing is made of two files, one with
          the grades, and one with the student information (see an
          existing one as an example).

          Group implements web discussion groups. Each group is kept
          at a directory under /usr/web/groups and has one file per
          article. Replies are stored within the article file. The
          program uses templates to generate the index, the view-
          article, and the post-article pages.  See an existing group
          for an example. The directory must contain an append-only,
          writeable by all, INDEX file, used to record existing arti-
          cles.

          Webls produces directory listings on the fly, with output in
          the style of ls(1). /sys/lib/webls.allowed and
          /sys/lib/webls.denied contain regular expressions describing
          what parts of httpd's namespace may and may not be listed,
          respectively.  Webls.denied is first searched to see if
          access is by default denied.  If so webls.allowed is then
          searched to see if access is explicitly allowed.  Thus one
          can have very general expressions in the denied list (like
          .*), yet still allow exceptions.  If webls.denied does not
          exist or is unreadable, all accesses are assumed to be
          denied unless explicitly allowed in webls.allowed.

          Other sites will note that if neither webls.denied nor
          webls.allowed exist, any portion of httpd's namespace can be
          listed (however, webls will always endeavor to prevent list-
          ing of `.' and `..').  If webls.allowed exists but
          webls.denied does not, any directory to be listed must be
          described by a regular expression in webls.allowed.  Simi-
          larly, if webls.denied exists but webls.allowed does not,
          any directory to be listed must not be described by a regu-
          lar expression in webls.denied.  If both exist, a directory
          is listable if either it doesn't appear in webls.denied, or
          it appears in both webls.denied and webls.allowed.  In other
          words, webls.allowed overrides webls.denied.  If a listing
          for a directory is requested and access is denied, or
          another error occurs, a simple error page is returned.

     FILES
          /sys/lib/mimetype     content type description file
          /lib/namespace.httpd  default namespace file for httpd
          /sys/lib/httpd.rewrite
                                redirection file
          /sys/lib/webls.allowed
                                regular expressions describing explic-
                                itly listable pathnames; overrides
                                webls.denied
          /sys/lib/webls.denied regular expressions describing

     Page 3                       Plan 9             (printed 3/29/24)

     HTTPD(8)                                                 HTTPD(8)

                                explicitly unlistable pathnames

     SOURCE
          /sys/src/cmd/ip/httpd

     SEE ALSO
          newns in auth(2), listen(8), x509(8)

     Page 4                       Plan 9             (printed 3/29/24)