httpd 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308
  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 application/octet-stream)
  114. and Content-encoding
  115. (default binary)
  116. of a file are determined by looking for suffixes of the file name in
  117. .BR /sys/lib/mimetype .
  118. .PP
  119. Each requested URI is looked up in a redirection table, read from
  120. .BR /sys/lib/httpd.rewrite .
  121. If a prefix of the URI matches a redirection path,
  122. the URI is rewritten using a replacement path,
  123. and a redirect is sent to the HTTP client.
  124. If the replacement path does not specify a server name,
  125. and the request has no explicit host,
  126. then
  127. .I domain
  128. is the host name used in the redirection.
  129. The prefix can either be a domain root like
  130. .B http://system/
  131. (which matches that URL only)
  132. or a path like
  133. .B /who/rob
  134. (which matches that path no matter what
  135. the requested server),
  136. but not both:
  137. .B http://system/who/rob
  138. will never match a request.
  139. .I Httpd
  140. handles replacements prefixed with
  141. .B @
  142. internally,
  143. treating the request as if it were for the replacement
  144. (without the
  145. .BR @ )
  146. but not informing the client of the rewritten name.
  147. .PP
  148. Before opening any file,
  149. .I httpd
  150. looks for a file in the same directory called
  151. .BR .httplogin .
  152. If the file exists, the directory is considered
  153. locked and the client must specify a user name
  154. and password matching a pair in the file.
  155. .B .httplogin
  156. contains a list of space or newline separated tokens, each
  157. possibly delimited by single quotes. The first
  158. is a domain name presented to the HTTP client.
  159. The rest are pairs of user name and password.
  160. Thus, there can be many user name/password pairs
  161. valid for a directory.
  162. .PP
  163. If the requested URI begins with
  164. .BI /magic/ server /\f1,
  165. .I httpd
  166. executes the file
  167. .BI /bin/ip/httpd/ server
  168. to finish servicing the request.
  169. .IR Method
  170. and
  171. .IR version
  172. are those received on the first line of the request.
  173. .I Uri
  174. is the remaining portion of the requested URI.
  175. .I Inbuf
  176. contains the rest of the bytes read by the server,
  177. and
  178. .I netdir
  179. is the network directory for the connection.
  180. There are routines for processing command arguments,
  181. parsing headers, etc. in the httpd library,
  182. .BR /sys/src/cmd/ip/httpd/libhttpd.a.$O .
  183. See
  184. .B httpd.h
  185. in that directory and existing magic commands for more details.
  186. .PP
  187. .I Mirror
  188. is a trivial server that just returns the method, URI, any search,
  189. the headers, and the message body sent by the client.
  190. .PP
  191. .I Save
  192. writes a line to
  193. .BI /usr/web/save/ uri .data
  194. and returns the contents of
  195. .BI /usr/web/save/ uri .html.
  196. Both files must be accessible for the request to succeed.
  197. The saved line includes the current time
  198. and either the search string from a HEAD or GET
  199. or the first line of the body from a POST.
  200. It is used to record form submissions.
  201. .PP
  202. .I Imagemap
  203. processes an HTML imagemap query.
  204. It looks up a the point
  205. .I search
  206. in the image map file given by
  207. .IR uri ,
  208. and returns a redirection to the appropriate page.
  209. The map file defaults to NCSA format.
  210. Any entries after a line starting with the word
  211. .B #cern
  212. are interpreted in CERN format.
  213. .PP
  214. .I Man2html
  215. converts
  216. .IR man (6)
  217. format manual pages into html.
  218. It includes some abilities to search the manuals.
  219. .PP
  220. .I Webls
  221. produces directory listings on the fly, with
  222. output in the style of
  223. .IR ls (1).
  224. .B /sys/lib/webls.allowed
  225. and
  226. .B /sys/lib/webls.denied
  227. contain regular expressions describing
  228. what parts of
  229. .I httpd's
  230. namespace may and may not be listed, respectively.
  231. .B Webls.denied
  232. is first searched to see if access is by default
  233. denied. If so
  234. .B webls.allowed
  235. is then searched to see if access is explicitly allowed.
  236. Thus one can have very general expressions in the
  237. denied list (like
  238. .BR .* ),
  239. yet still allow exceptions. If
  240. .B webls.denied
  241. does not exist or is unreadable,
  242. all accesses are assumed to be denied unless
  243. explicitly allowed in
  244. .B webls.allowed.
  245. .PP
  246. Other sites will note that if neither
  247. .B webls.denied
  248. nor
  249. .B webls.allowed
  250. exist, any portion of
  251. .I httpd's
  252. namespace can be listed (however,
  253. .I webls
  254. will always endeavor to prevent listing of `.' and `..').
  255. If
  256. .B webls.allowed
  257. exists but
  258. .B webls.denied
  259. does not, any directory to be listed must be described
  260. by a regular expression in
  261. .BR webls.allowed .
  262. Similarly, if
  263. .B webls.denied
  264. exists but
  265. .B webls.allowed
  266. does not, any directory to be listed must
  267. .I not
  268. be described by a regular expression in
  269. .BR webls.denied .
  270. If both exist, a directory is listable if either
  271. it doesn't appear in
  272. .BR webls.denied ,
  273. or it appears in both
  274. .B webls.denied
  275. and
  276. .BR webls.allowed .
  277. In other words,
  278. .B webls.allowed
  279. overrides
  280. .BR webls.denied .
  281. If a listing for a directory is requested and access
  282. is denied, or another error occurs, a simple error
  283. page is returned.
  284. .SH FILES
  285. .TF /lib/namespace.httpd
  286. .TP
  287. .B /sys/lib/mimetype
  288. content type description file
  289. .TP
  290. .B /lib/namespace.httpd
  291. default namespace file for httpd
  292. .TP
  293. .B /sys/lib/httpd.rewrite
  294. redirection file
  295. .TP
  296. .B /sys/lib/webls.allowed
  297. regular expressions describing explicitly listable pathnames; overrides webls.denied
  298. .TP
  299. .B /sys/lib/webls.denied
  300. regular expressions describing explicitly unlistable pathnames
  301. .SH SOURCE
  302. .B /sys/src/cmd/ip/httpd
  303. .SH "SEE ALSO"
  304. .I newns
  305. in
  306. .IR auth (2),
  307. .IR listen (8),
  308. .IR rsa (8)