1
0

httpd 7.9 KB

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