.TH HTTPD 8.SH NAMEhttpd, mirror, save, imagemap, man2html, webls \- HTTP server.SH SYNOPSIS.PP.B ip/httpd/httpd.RB [ -a.IR srvaddr ].RB [ -c.IR cert ].RB [ -d.IR domain ].RB [ -n.IR namespace ].RB [ -w.IR webroot ].PP.B ip/httpd/mirror.RB [ -b.IR inbuf ].RB [ -d.IR domain ].RB [ -r.IR remoteip ].RB [ -w.IR webroot ].RB [ -N.IR netdir ].I method version uri.RI [ search ].PP.B ip/httpd/save.RB [ -b.IR inbuf ].RB [ -d.IR domain ].RB [ -r.IR remoteip ].RB [ -w.IR webroot ].RB [ -N.IR netdir ].I method version uri.RI [ search ].PP.B ip/httpd/imagemap.RB [ -b.IR inbuf ].RB [ -d.IR domain ].RB [ -r.IR remoteip ].RB [ -w.IR webroot ].RB [ -N.IR netdir ].I method version uri.PP.B ip/httpd/man2html.RB [ -b.IR inbuf ].RB [ -d.IR domain ].RB [ -r.IR remoteip ].RB [ -w.IR webroot ].RB [ -N.IR netdir ].I method version uri.RI [ search ].PP.B ip/httpd/notas.RB [ -b.IR inbuf ].RB [ -d.IR domain ].RB [ -r.IR remoteip ].RB [ -w.IR webroot ].RB [ -N.IR netdir ].I method version uri.RI [ search ].PP.B ip/httpd/group.RB [ -b.IR inbuf ].RB [ -d.IR domain ].RB [ -r.IR remoteip ].RB [ -w.IR webroot ].RB [ -N.IR netdir ].I method version uri.RI [ search ].PP.B ip/httpd/webls.RB [ -b.IR inbuf ].RB [ -d.IR domain ].RB [ -r.IR remoteip ].RB [ -w.IR webroot ].RB [ -N.IR netdir ].I method version uri.RI [ search ].SH DESCRIPTION.I Httpdserves the.I webrootdirectory of the file system described by.I namespace(default.BR /lib/namespace.httpd ),using version 1.1 of the HTTP protocol.It announces the service.I srvaddr(default.BR tcp!*!http ),and listens for incoming calls.If an X.509 certificate is supplied with the.B -coption, then the service is instead.BR tcp!*!https .There should already be a factotumholding the corresponding private key..PP.I Httpdsupports only the GET and HEAD methods of the HTTP protocol;some magic programs support POST as well.Persistent connections are supported for HTTP/1.1 or later clients;all connections close after a magic command is executed.The Content-type(default application/octet-stream)and Content-encoding(default binary)of a file are determined by looking for suffixes of the file name in.BR /sys/lib/mimetype ..PPEach requested URI is looked up in a redirection table, read from.BR /sys/lib/httpd.rewrite .If a prefix of the URI matches a redirection path,the URI is rewritten using a replacement 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.I domainis the host name used in the redirection.The prefix can either be a domain root like.B http://system/(which matches that URL only)or a path like.B /who/rob(which matches that path no matter whatthe requested server),but not both:.B http://system/who/robwill never match a request..I Httpdhandles replacements prefixed with .B @ internally,treating the request as if it were for the replacement(without the.BR @ )but not informing the client of the rewritten name..PPBefore opening any file,.I httpdlooks for a file in the same directory called.BR .httplogin .If the file exists, the directory is consideredlocked and the client must specify a user nameand password machine a pair in the file..B .httplogincontains a list of space or newline separated tokens, eachpossibly delimited by single quotes. The firstis 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 pairsvalid for a directory..PPIf the requested URI begins with.BI /magic/ server /\f1,.I httpdexecutes the file.BI /bin/ip/httpd/ serverto finish servicing the request..IR Methodand.IR versionare those received on the first line of the request..I Uriis the remaining portion of the requested URI..I Inbufcontains the rest of the bytes read by the server,and.I netdiris the network directory for the connection.There are routines for processing command arguments,parsing headers, etc. in the httpd library,.BR /sys/src/cmd/ip/httpd/libhttpd.a.$O .See.B httpd.hin that directory and existing magic commands for more details..PP.I Mirroris a trivial server that just returns the method, URI, any search,the headers, and the message body sent by the client..PP.I Savewrites a line to.BI /usr/web/save/ uri .dataand returns the contents of.BI /usr/web/save/ uri .html.Both files must be accessible for the request to succeed.The saved line includes the current timeand either the search string from a HEAD or GETor the first line of the body from a POST.It is used to record form submissions..PP.I Imagemapprocesses an HTML imagemap query.It looks up a the point.I searchin the image map file given by .IR 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.B #cernare interpreted in CERN format..PP.I Man2htmlconverts.IR man (6)format manual pages into html.It includes some abilities to search the manuals..PP.I Notasgives access to student grades after searching for the student NIFin a grade listing. Listings are kept under.B /usr/prof/notasEach listing is made of two files,one with the grades, and one with the student information (see an existing one as an example)..PP.I Groupimplements web discussion groups. Each group is kept at a directory under.B /usr/web/groupsand has one file per article. Replies are stored within the article file. The programuses 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,.B INDEXfile, used to record existing articles..PP.I Weblsproduces directory listings on the fly, withoutput in the style of.IR ls (1)..B /sys/lib/webls.allowedand.B /sys/lib/webls.deniedcontain regular expressions describingwhat parts of.I httpd'snamespace may and may not be listed, respectively..B Webls.deniedis first searched to see if access is by defaultdenied. If so.B webls.allowedis then searched to see if access is explicitly allowed.Thus one can have very general expressions in thedenied list (like.BR .* ),yet still allow exceptions. If.B webls.denieddoes not exist or is unreadable, all accesses are assumed to be denied unlessexplicitly allowed in.B webls.allowed..PPOther sites will note that if neither.B webls.deniednor.B webls.allowedexist, any portion of.I httpd'snamespace can be listed (however,.I weblswill always endeavor to prevent listing of `.' and `..').If.B webls.allowedexists but.B webls.denieddoes not, any directory to be listed must be describedby a regular expression in.BR webls.allowed .Similarly, if.B webls.deniedexists but.B webls.alloweddoes not, any directory to be listed must.I notbe described by a regular expression in.BR webls.denied .If both exist, a directory is listable if eitherit doesn't appear in.BR webls.denied ,or it appears in both.B webls.deniedand.BR webls.allowed .In other words,.B webls.allowedoverrides.BR webls.denied .If a listing for a directory is requested and accessis denied, or another error occurs, a simple errorpage is returned..SH FILES.TF /lib/namespace.httpd.TP.B /sys/lib/mimetypecontent type description file.TP.B /lib/namespace.httpddefault namespace file for httpd.TP.B /sys/lib/httpd.rewriteredirection file.TP.B /sys/lib/webls.allowedregular expressions describing explicitly listable pathnames; overrides webls.denied.TP.B /sys/lib/webls.deniedregular expressions describing explicitly unlistable pathnames.SH SOURCE.B /sys/src/cmd/ip/httpd.SH "SEE ALSO".I newnsin.IR auth (2),.IR listen (8),.IR x509 (8)
.TH HTTPD 8
.SH NAME
httpd, mirror, save, imagemap, man2html, webls \- HTTP server
.SH SYNOPSIS
.PP
.B ip/httpd/httpd
.RB [ -a
.IR srvaddr ]
.RB [ -c
.IR cert ]
.RB [ -d
.IR domain ]
.RB [ -n
.IR namespace ]
.RB [ -w
.IR webroot ]
.PP
.B ip/httpd/mirror
.RB [ -b
.IR inbuf ]
.RB [ -d
.IR domain ]
.RB [ -r
.IR remoteip ]
.RB [ -w
.IR webroot ]
.RB [ -N
.IR netdir ]
.I method version uri
.RI [ search ]
.PP
.B ip/httpd/save
.RB [ -b
.IR inbuf ]
.RB [ -d
.IR domain ]
.RB [ -r
.IR remoteip ]
.RB [ -w
.IR webroot ]
.RB [ -N
.IR netdir ]
.I method version uri
.RI [ search ]
.PP
.B ip/httpd/imagemap
.RB [ -b
.IR inbuf ]
.RB [ -d
.IR domain ]
.RB [ -r
.IR remoteip ]
.RB [ -w
.IR webroot ]
.RB [ -N
.IR netdir ]
.I method version uri
.PP
.B ip/httpd/man2html
.RB [ -b
.IR inbuf ]
.RB [ -d
.IR domain ]
.RB [ -r
.IR remoteip ]
.RB [ -w
.IR webroot ]
.RB [ -N
.IR netdir ]
.I method version uri
.RI [ search ]
.PP
.B ip/httpd/notas
.RB [ -b
.IR inbuf ]
.RB [ -d
.IR domain ]
.RB [ -r
.IR remoteip ]
.RB [ -w
.IR webroot ]
.RB [ -N
.IR netdir ]
.I method version uri
.RI [ search ]
.PP
.B ip/httpd/group
.RB [ -b
.IR inbuf ]
.RB [ -d
.IR domain ]
.RB [ -r
.IR remoteip ]
.RB [ -w
.IR webroot ]
.RB [ -N
.IR netdir ]
.I method version uri
.RI [ search ]
.PP
.B ip/httpd/webls
.RB [ -b
.IR inbuf ]
.RB [ -d
.IR domain ]
.RB [ -r
.IR remoteip ]
.RB [ -w
.IR webroot ]
.RB [ -N
.IR netdir ]
.I method version uri
.RI [ search ]
.SH DESCRIPTION
.I Httpd
serves the
.I webroot
directory of the file system described by
.I namespace
(default
.BR /lib/namespace.httpd ),
using version 1.1 of the HTTP protocol.
It announces the service
.I srvaddr
(default
.BR tcp!*!http ),
and listens for incoming calls.
If an X.509 certificate is supplied with the
.B -c
option, then the service is instead
.BR tcp!*!https .
There should already be a factotum
holding the corresponding private key.
.PP
.I Httpd
supports only the GET and HEAD methods of the HTTP protocol;
some magic programs support POST as well.
Persistent connections are supported for HTTP/1.1 or later clients;
all connections close after a magic command is executed.
The Content-type
(default application/octet-stream)
and Content-encoding
(default binary)
of a file are determined by looking for suffixes of the file name in
.BR /sys/lib/mimetype .
.PP
Each requested URI is looked up in a redirection table, read from
.BR /sys/lib/httpd.rewrite .
If a prefix of the URI matches a redirection path,
the URI is rewritten using a replacement 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
.I domain
is the host name used in the redirection.
The prefix can either be a domain root like
.B http://system/
(which matches that URL only)
or a path like
.B /who/rob
(which matches that path no matter what
the requested server),
but not both:
.B http://system/who/rob
will never match a request.
.I Httpd
handles replacements prefixed with
.B @
internally,
treating the request as if it were for the replacement
(without the
.BR @ )
but not informing the client of the rewritten name.
.PP
Before opening any file,
.I httpd
looks for a file in the same directory called
.BR .httplogin .
If the file exists, the directory is considered
locked and the client must specify a user name
and password machine a pair in the file.
.B .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.
.PP
If the requested URI begins with
.BI /magic/ server /\f1,
.I httpd
executes the file
.BI /bin/ip/httpd/ server
to finish servicing the request.
.IR Method
and
.IR version
are those received on the first line of the request.
.I Uri
is the remaining portion of the requested URI.
.I Inbuf
contains the rest of the bytes read by the server,
and
.I netdir
is the network directory for the connection.
There are routines for processing command arguments,
parsing headers, etc. in the httpd library,
.BR /sys/src/cmd/ip/httpd/libhttpd.a.$O .
See
.B httpd.h
in that directory and existing magic commands for more details.
.PP
.I Mirror
is a trivial server that just returns the method, URI, any search,
the headers, and the message body sent by the client.
.PP
.I Save
writes a line to
.BI /usr/web/save/ uri .data
and returns the contents of
.BI /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.
.PP
.I Imagemap
processes an HTML imagemap query.
It looks up a the point
.I search
in the image map file given by
.IR 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
.B #cern
are interpreted in CERN format.
.PP
.I Man2html
converts
.IR man (6)
format manual pages into html.
It includes some abilities to search the manuals.
.PP
.I Notas
gives access to student grades after searching for the student NIF
in a grade listing. Listings are kept under
.B /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).
.PP
.I Group
implements web discussion groups. Each group is kept at a directory under
.B /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,
.B INDEX
file, used to record existing articles.
.PP
.I Webls
produces directory listings on the fly, with
output in the style of
.IR ls (1).
.B /sys/lib/webls.allowed
and
.B /sys/lib/webls.denied
contain regular expressions describing
what parts of
.I httpd's
namespace may and may not be listed, respectively.
.B Webls.denied
is first searched to see if access is by default
denied. If so
.B webls.allowed
is then searched to see if access is explicitly allowed.
Thus one can have very general expressions in the
denied list (like
.BR .* ),
yet still allow exceptions. If
.B webls.denied
does not exist or is unreadable,
all accesses are assumed to be denied unless
explicitly allowed in
.B webls.allowed.
.PP
Other sites will note that if neither
.B webls.denied
nor
.B webls.allowed
exist, any portion of
.I httpd's
namespace can be listed (however,
.I webls
will always endeavor to prevent listing of `.' and `..').
If
.B webls.allowed
exists but
.B webls.denied
does not, any directory to be listed must be described
by a regular expression in
.BR webls.allowed .
Similarly, if
.B webls.denied
exists but
.B webls.allowed
does not, any directory to be listed must
.I not
be described by a regular expression in
.BR webls.denied .
If both exist, a directory is listable if either
it doesn't appear in
.BR webls.denied ,
or it appears in both
.B webls.denied
and
.BR webls.allowed .
In other words,
.B webls.allowed
overrides
.BR webls.denied .
If a listing for a directory is requested and access
is denied, or another error occurs, a simple error
page is returned.
.SH FILES
.TF /lib/namespace.httpd
.TP
.B /sys/lib/mimetype
content type description file
.TP
.B /lib/namespace.httpd
default namespace file for httpd
.TP
.B /sys/lib/httpd.rewrite
redirection file
.TP
.B /sys/lib/webls.allowed
regular expressions describing explicitly listable pathnames; overrides webls.denied
.TP
.B /sys/lib/webls.denied
regular expressions describing explicitly unlistable pathnames
.SH SOURCE
.B /sys/src/cmd/ip/httpd
.SH "SEE ALSO"
.I newns
in
.IR auth (2),
.IR listen (8),
.IR x509 (8)