webfs 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309
  1. .TH WEBFS 4
  2. .SH NAME
  3. webfs \- world wide web file system
  4. .SH SYNOPSIS
  5. .B webfs
  6. [
  7. .B -c
  8. .I cookiefile
  9. ]
  10. [
  11. .B -m
  12. .I mtpt
  13. ]
  14. [
  15. .B -s
  16. .I service
  17. ]
  18. \&...
  19. .SH DESCRIPTION
  20. .I Webfs
  21. presents a file system interface to the parsing and retrieving
  22. of URLs.
  23. .I Webfs
  24. mounts itself at
  25. .I mtpt
  26. (default
  27. .BR /mnt/web ),
  28. and, if
  29. .I service
  30. is specified, will post a service file descriptor
  31. in
  32. .BR /srv/\fIservice .
  33. .PP
  34. .I Webfs
  35. presents a three-level file system suggestive
  36. of the network protocol hierarchies
  37. .IR ip (3)
  38. and
  39. .IR ether (3).
  40. .PP
  41. The top level contains three files:
  42. .BR ctl ,
  43. .BR cookies ,
  44. and
  45. .BR clone .
  46. .PP
  47. The
  48. .B ctl
  49. file is used to maintain parameters global to the instance of
  50. .IR webfs .
  51. Reading the
  52. .B ctl
  53. file yields the current values of the parameters.
  54. Writing strings of the form
  55. .RB `` attr " " value ''
  56. sets a particular attribute.
  57. Attributes are:
  58. .TP
  59. .B chatty9p
  60. The
  61. .B chatty9p
  62. flag used by the 9P library, discussed in
  63. .IR 9p (2).
  64. .B 0
  65. is no debugging,
  66. .B 1
  67. prints 9P message traces on standard error,
  68. and values above
  69. .B 1
  70. present more debugging, at the whim of the library.
  71. The default for this and the following debug flags is
  72. .BR 0 .
  73. .TP
  74. .B fsdebug
  75. This variable is the level of debugging output about the file system module.
  76. .TP
  77. .B cookiedebug
  78. This variable is the level of debugging output about the cookie module.
  79. .TP
  80. .B urldebug
  81. This variable is the level of debugging output about URL parsing.
  82. .TP
  83. .B acceptcookies
  84. This flag controls whether to accept cookies presented by remote web servers.
  85. (Cookies are described below, in the discussion of the
  86. .B cookies
  87. file.)
  88. The values
  89. .B on
  90. and
  91. .B off
  92. are synonymous with
  93. .B 1
  94. and
  95. .BR 0 .
  96. The default is
  97. .BR on .
  98. .TP
  99. .B sendcookies
  100. This flag controls whether to present stored cookies to remote web servers.
  101. The default is
  102. .BR on .
  103. .TP
  104. .B redirectlimit
  105. Web servers can respond to a request with a message
  106. redirecting to another page.
  107. .I Webfs
  108. makes no effort to determine whether it is in an infinite
  109. redirect loop.
  110. Instead, it gives up after this many redirects.
  111. The default is
  112. .BR 10 .
  113. .TP
  114. .B useragent
  115. .I Webfs
  116. sends the value of this attribute in its
  117. .B User-Agent:
  118. header in its HTTP requests.
  119. The default is
  120. .RB `` "webfs/2.0 (plan 9)" .''
  121. .PD
  122. .PP
  123. The top-level directory also contains
  124. numbered directories corresponding to connections, which
  125. may be used to fetch a single URL.
  126. To allocate a connection, open the
  127. .B clone
  128. file and read a number
  129. .I n
  130. from it.
  131. After opening, the
  132. .B clone
  133. file is equivalent to the file
  134. .IB n /ctl \fR.
  135. A connection is assumed closed once all files in its directory
  136. have been closed, and is then will be reallocated.
  137. .PP
  138. Each connection has its own private set of
  139. .BR acceptcookies ,
  140. .BR sendcookies ,
  141. .BR redirectlimit ,
  142. and
  143. .B useragent
  144. variables, initialized to the defaults set in the
  145. root's
  146. .B ctl
  147. file. The per-connection
  148. .B ctl
  149. file allows editing the variables for this particular connection.
  150. .PP
  151. Each connection also has a URL string variable
  152. .B url
  153. associated with it.
  154. This URL may be an absolute URL such as
  155. .I http://www.lucent.com/index.html
  156. or a relative URL such as
  157. .IR ../index.html .
  158. The
  159. .B baseurl
  160. string variable sets the URL against which relative URLs
  161. are interpreted.
  162. Once the URL has been set,
  163. its pieces can be retrieved via individual files in the
  164. .B parsed
  165. directory.
  166. .I Webfs
  167. parses the following URL syntaxes; names in italics are
  168. the names of files in the
  169. .B parsed
  170. directory.
  171. .IP
  172. \fIscheme\f5:\fIschemedata
  173. .br
  174. \f5http://\fIhost\f5/\fIpath\fR[\f5?\fIquery\fR][\f5#\fIfragment\fR]
  175. .br
  176. \f5ftp://\fR[\fIuser\fR[\f5:\fIpassword\fR]\f5@\fR]\fP\f5\fIhost\f5/\fIpath\fR[\f5;type=\fIftptype\fR]
  177. .br
  178. \f5file:\fIpath
  179. .LP
  180. If there is associated data to be
  181. posted with the request, it can be written to
  182. .BR postbody .
  183. Finally, opening
  184. .B body
  185. initiates the request.
  186. The resulting data may be read from
  187. .B body
  188. as it arrives.
  189. After the request has been executed, the MIME content type
  190. may be read from the
  191. .B contenttype
  192. file.
  193. .PP
  194. The top-level
  195. .B cookies
  196. file contains the internal set of HTTP cookies, which
  197. are used by HTTP servers to associate requests with persistent
  198. state such as user profiles.
  199. It may be edited as an ordinary text file.
  200. Multiple instances of
  201. .I webfs
  202. and
  203. .IR webcookies (4)
  204. share cookies by keeping their internal set
  205. consistent with the
  206. .I cookiefile
  207. (default
  208. .BR $home/lib/webcookies ),
  209. which has the same format.
  210. .PP
  211. These files contain one line per cookie;
  212. each cookie comprises some number of
  213. .IB attr = value
  214. pairs.
  215. Cookie attributes are:
  216. .TP
  217. .BI name= name
  218. The name of the cookie on the remote server.
  219. .TP
  220. .BI value= value
  221. The value associated with that name on the remote server.
  222. The actual data included when a cookie is sent back
  223. to the server is
  224. .IB \fR``\fIname = value\fR''
  225. (where, confusingly,
  226. .I name
  227. and
  228. .I value
  229. are the values associated with the
  230. .B name
  231. and
  232. .B value
  233. attributes.
  234. .TP
  235. .BI domain= domain
  236. If
  237. .I domain
  238. is an IP address, the cookie can only be used for URLs
  239. with
  240. .I host
  241. equal to that IP address.
  242. Otherwise,
  243. .I domain
  244. must be a pattern beginning with a dot, and
  245. the cookie can only be used for URLs with a
  246. .I host
  247. having
  248. .I domain
  249. as a suffix.
  250. For example, a cookie with
  251. .B domain=.bell-labs.com
  252. may be used on hosts
  253. .I www.bell-labs.com
  254. and
  255. .IR www.research.bell-labs.com
  256. (but not
  257. .IR www.not-bell-labs.com ).
  258. .TP
  259. .BI path= path
  260. The cookie can only be used for URLs with a path
  261. beginning with
  262. .IR path .
  263. .TP
  264. .BI version= version
  265. The version of the HTTP cookie specification, specified by the server.
  266. .TP
  267. .BI comment= comment
  268. A comment, specified by the server.
  269. .TP
  270. .BI expire= expire
  271. The cookie expires at time
  272. .IR expire ,
  273. which is a decimal number of seconds since the epoch.
  274. .TP
  275. .B secure=1
  276. The cookie may only be used over secure
  277. .RB ( https )
  278. connections.
  279. Secure connections are currently unimplemented.
  280. .TP
  281. .B explicitdomain=1
  282. The domain associated with this cookie was set by
  283. the server (rather than inferred from a URL).
  284. .TP
  285. .B explicitpath=1
  286. The path associated with this cookie was set by the
  287. server (rather than inferred from a URL).
  288. .TP
  289. .B netscapestyle=1
  290. The server presented the cookie in ``Netscape style,'' which
  291. does not conform to the cookie standard, RFC2109.
  292. It is assumed that when presenting the cookie to the server,
  293. it must be sent back in Netscape style as well.
  294. .PD
  295. .SH EXAMPLE
  296. .B /sys/src/cmd/webfs/webget.c
  297. is a simple client.
  298. .SH SOURCE
  299. .B /sys/src/cmd/webfs
  300. .SH SEE ALSO
  301. .IR hget (1),
  302. .IR webcookies (4)
  303. .SH BUGS
  304. It's not clear what the relationship between
  305. .IR hget ,
  306. .I webcookies
  307. and
  308. .I webfs
  309. should be.