plan9-gpl/sys/man/4/webfs

.TH WEBFS 4
.SH NAME
webfs \- world wide web file system
.SH SYNOPSIS
.B webfs
[
.B -c
.I cookiefile
]
[
.B -m
.I mtpt
]
[
.B -s
.I service
]
\&...
.SH DESCRIPTION
.I Webfs
presents a file system interface to the parsing and retrieving
of URLs.
.I Webfs
mounts itself at
.I mtpt
(default
.BR /mnt/web ),
and, if 
.I service
is specified, will post a service file descriptor
in 
.BR /srv/\fIservice .
.PP
.I Webfs
presents a three-level file system suggestive
of the network protocol hierarchies
.IR ip (3)
and
.IR ether (3).
.PP
The top level contains three files:
.BR ctl ,
.BR cookies ,
and
.BR clone .
.PP
The
.B ctl
file is used to maintain parameters global to the instance of
.IR webfs .
Reading the 
.B ctl
file yields the current values of the parameters.
Writing strings of the form
.RB `` attr " " value ''
sets a particular attribute.
Attributes are:
.TP
.B chatty9p
The
.B chatty9p
flag used by the 9P library, discussed in
.IR 9p (2).
.B 0
is no debugging,
.B 1
prints 9P message traces on standard error,
and values above
.B 1
present more debugging, at the whim of the library.
The default for this and the following debug flags is 
.BR 0 .
.TP
.B fsdebug
This variable is the level of debugging output about the file system module.
.TP
.B cookiedebug
This variable is the level of debugging output about the cookie module.
.TP
.B urldebug
This variable is the level of debugging output about URL parsing.
.TP
.B acceptcookies
This flag controls whether to accept cookies presented by remote web servers.
(Cookies are described below, in the discussion of the
.B cookies
file.)
The values
.B on
and
.B off
are synonymous with
.B 1
and
.BR 0 .
The default is
.BR on .
.TP
.B sendcookies
This flag controls whether to present stored cookies to remote web servers.
The default is
.BR on .
.TP
.B redirectlimit
Web servers can respond to a request with a message
redirecting to another page.
.I Webfs
makes no effort to determine whether it is in an infinite
redirect loop.
Instead, it gives up after this many redirects.
The default is
.BR 10 .
.TP
.B useragent
.I Webfs
sends the value of this attribute in its
.B User-Agent:
header in its HTTP requests.
The default is
.RB `` "webfs/2.0 (plan 9)" .''
.PD
.PP
The top-level directory also contains
numbered directories corresponding to connections, which
may be used to fetch a single URL.
To allocate a connection, open the
.B clone
file and read a number 
.I n
from it.
After opening, the
.B clone
file is equivalent to the file
.IB n /ctl \fR.
A connection is assumed closed once all files in its directory
have been closed, and is then will be reallocated.
.PP
Each connection has its own private set of
.BR acceptcookies ,
.BR sendcookies ,
.BR redirectlimit ,
and
.B useragent
variables, initialized to the defaults set in the
root's
.B ctl
file.  The per-connection
.B ctl
file allows editing the variables for this particular connection.
.PP
Each connection also has a URL string variable
.B url
associated with it.
This URL may be an absolute URL such as
.I http://www.lucent.com/index.html
or a relative URL such as
.IR ../index.html .
The
.B baseurl
string variable sets the URL against which relative URLs
are interpreted.
Once the URL has been set,
its pieces can be retrieved via individual files in the
.B parsed
directory.
.I Webfs
parses the following URL syntaxes; names in italics are
the names of files in the
.B parsed
directory.
.IP
\fIscheme\f5:\fIschemedata
.br
\f5http://\fIhost\f5/\fIpath\fR[\f5?\fIquery\fR][\f5#\fIfragment\fR]
.br
\f5ftp://\fR[\fIuser\fR[\f5:\fIpassword\fR]\f5@\fR]\fP\f5\fIhost\f5/\fIpath\fR[\f5;type=\fIftptype\fR]
.br
\f5file:\fIpath
.LP
If there is associated data to be
posted with the request, it can be written to
.BR postbody .
Finally, opening
.B body
initiates the request.
The resulting data may be read from
.B body
as it arrives.
After the request has been executed, the MIME content type
may be read from the
.B contenttype
file.
.PP
The top-level
.B cookies
file contains the internal set of HTTP cookies, which
are used by HTTP servers to associate requests with persistent
state such as user profiles.
It may be edited as an ordinary text file.
Multiple instances of
.I webfs
and
.IR webcookies (4)
share cookies by keeping their internal set
consistent with the
.I cookiefile
(default
.BR $home/lib/webcookies ),
which has the same format.
.PP
These files contain one line per cookie;
each cookie comprises some number of
.IB attr = value
pairs.
Cookie attributes are:
.TP
.BI name= name
The name of the cookie on the remote server.
.TP
.BI value= value
The value associated with that name on the remote server.
The actual data included when a cookie is sent back
to the server is
.IB \fR``\fIname = value\fR''
(where, confusingly,
.I name
and
.I value
are the values associated with the
.B name
and
.B value
attributes.
.TP
.BI domain= domain
If
.I domain
is an IP address, the cookie can only be used for URLs
with
.I host
equal to that IP address.
Otherwise,
.I domain
must be a pattern beginning with a dot, and
the cookie can only be used for URLs with a
.I host
having
.I domain
as a suffix.
For example, a cookie with
.B domain=.bell-labs.com
may be used on hosts
.I www.bell-labs.com
and
.IR www.research.bell-labs.com
(but not
.IR www.not-bell-labs.com ).
.TP
.BI path= path
The cookie can only be used for URLs with a path
beginning with
.IR path .
.TP
.BI version= version
The version of the HTTP cookie specification, specified by the server.
.TP
.BI comment= comment
A comment, specified by the server.
.TP
.BI expire= expire
The cookie expires at time
.IR expire ,
which is a decimal number of seconds since the epoch.
.TP
.B secure=1
The cookie may only be used over secure
.RB ( https )
connections.
Secure connections are currently unimplemented.
.TP
.B explicitdomain=1
The domain associated with this cookie was set by
the server (rather than inferred from a URL).
.TP
.B explicitpath=1
The path associated with this cookie was set by the
server (rather than inferred from a URL).
.TP
.B netscapestyle=1
The server presented the cookie in ``Netscape style,'' which
does not conform to the cookie standard, RFC2109.
It is assumed that when presenting the cookie to the server,
it must be sent back in Netscape style as well.
.PD
.SH EXAMPLE
.B /sys/src/cmd/webfs/webget.c
is a simple client.
.SH SOURCE
.B /sys/src/cmd/webfs
.SH SEE ALSO
.IR hget (1),
.IR webcookies (4)
.SH BUGS
It's not clear what the relationship between
.IR hget ,
.I webcookies
and
.I webfs
should be.