httpd 8.0 KB

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