u9fs 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280
  1. .TH U9FS 4
  2. .SH NAME
  3. u9fs \- serve 9P from Unix
  4. .SH SYNOPSIS
  5. .B u9fs
  6. [
  7. .B -Dnz
  8. ]
  9. [
  10. .B -a
  11. .I authtype
  12. ]
  13. [
  14. .B -A
  15. .I autharg
  16. ]
  17. [
  18. .B -l
  19. .I logfile
  20. ]
  21. [
  22. .B -m
  23. .I msize
  24. ]
  25. [
  26. .B -u
  27. .I onlyuser
  28. ]
  29. .SH DESCRIPTION
  30. .I U9fs
  31. is
  32. .I not
  33. a Plan 9 program. Instead it is a program that
  34. serves Unix files to Plan 9 machines using the 9P protocol
  35. (see
  36. .IR intro (5)).
  37. It is typically invoked on a
  38. Unix machine by
  39. .B inetd
  40. with its standard input and output connected to a
  41. network connection, typically TCP on an Ethernet.
  42. It typically runs as user
  43. .B root
  44. and multiplexes access to multiple Plan 9 clients over the single wire.
  45. It assumes Plan 9 uids match Unix login names,
  46. and changes to the corresponding Unix effective uid when processing requests.
  47. Characters in file and directory names unacceptable to Plan 9 are translated
  48. into a three-character sequence:
  49. .L \e
  50. followed by two hexadecimal digits.
  51. .I U9fs
  52. serves both 9P1 (the 9P protocol as used by
  53. the second and third editions of Plan 9) and 9P2000.
  54. .PP
  55. The options are:
  56. .TF "\fL-A \fIautharg"
  57. .PD
  58. .TP
  59. .B -D
  60. Write very chatty debugging output to the log file (see
  61. .B -l
  62. option below).
  63. .TP
  64. .B -n
  65. Signals that
  66. .I u9fs
  67. is
  68. .I not
  69. being invoked with a network connection
  70. on standard input and output, and thus should
  71. not try to determine the remote address of the connection.
  72. This is useful when
  73. .I u9fs
  74. is not invoked from
  75. .I inetd
  76. (see examples below).
  77. .TP
  78. .B -z
  79. Truncate the log file on startup. This is useful mainly when debugging
  80. with
  81. .BR -D .
  82. .TP
  83. .BI -a " authtype
  84. Sets the authentication method to be used.
  85. .I Authtype
  86. should be
  87. .BR rhosts ,
  88. .BR none ,
  89. or
  90. .BR p9any .
  91. The default is
  92. .BR rhosts ,
  93. which uses the
  94. .I ruserok
  95. library call to authenticate users by entries in
  96. .B /etc/hosts.equiv
  97. or
  98. .BR $HOME/.rhosts .
  99. This default is discouraged for all but the most controlled networks.
  100. Specifying
  101. .B none
  102. turns off authentication altogether.
  103. This is useful when
  104. .I u9fs
  105. is not invoked from
  106. .I inetd
  107. (see examples below, or
  108. .I srvssh
  109. in
  110. .IR srv (4)).
  111. Specifying
  112. .B p9any
  113. uses the fourth edition Plan 9 authentication mechanisms.
  114. The file
  115. .BR /etc/u9fs.key ,
  116. or
  117. .I autharg
  118. if specified
  119. (see the
  120. .B -A
  121. option),
  122. is consulted for the authentication data
  123. and should be suitably protected.
  124. This file must contain exactly three lines:
  125. .I secret
  126. (plaintext password),
  127. .I u9fs-user
  128. (user id),
  129. and
  130. .I plan9-auth.dom
  131. (authentication domain).
  132. .RS
  133. .LP
  134. Finally,
  135. .I factotum
  136. must be taught a key of the form:
  137. .LP
  138. .EX
  139. .B
  140. key proto=p9sk1 dom=\fIplan9-auth.dom\fP user=\fIu9fs-user\fP !password=\fIsecret\fP
  141. .EE
  142. .RE
  143. .TP
  144. .BI -A " autharg
  145. Used to specify an argument to the authentication method.
  146. See the authentication descriptions above.
  147. .TP
  148. .BI -l " logfile
  149. Specifies the file which should contain debugging output
  150. and other messages.
  151. The out-of-the-box compile-time default is
  152. .BR /tmp/u9fs.log .
  153. .TP
  154. .BI -m " msize
  155. Set
  156. .I msize
  157. for 9P2000
  158. (see
  159. .IR open (5)).
  160. .TP
  161. .BI -u " user
  162. Treat all attaches as coming from
  163. .IR user .
  164. This is useful in some cases when running without
  165. .IR inetd ;
  166. see the examples.
  167. .SH EXAMPLES
  168. .PP
  169. Plan 9 calls 9P file service
  170. .B 9fs
  171. with TCP port number 564.
  172. Set up this way on a machine called, say,
  173. .BR kremvax ,
  174. .I u9fs
  175. may be connected to the name space of a Plan 9 process by
  176. .IP
  177. .EX
  178. 9fs kremvax
  179. .EE
  180. .PP
  181. For more information on this procedure, see
  182. .IR srv (4)
  183. and
  184. .IR bind (1).
  185. .PP
  186. .I U9fs
  187. serves the entire file system of the Unix machine.
  188. It forbids access to devices
  189. because the program is single-threaded and may block unpredictably.
  190. Using the
  191. .B attach
  192. specifier
  193. .B device
  194. connects to a file system identical to the usual system except
  195. it only permits device access (and may block unpredictably):
  196. .IP
  197. .EX
  198. srv tcp!kremvax!9fs
  199. mount -c /srv/tcp!kremvax!9fs /n/kremvax device
  200. .EE
  201. .PP
  202. (The
  203. .B 9fs
  204. command
  205. does not accept an attach specifier.)
  206. Even so,
  207. device access may produce unpredictable
  208. results if the block size of the device is greater than 8192,
  209. the maximum data size of a 9P message.
  210. .PP
  211. The source to
  212. .I u9fs
  213. is in the Plan 9 directory
  214. .BR /sys/src/cmd/unix/u9fs .
  215. To install
  216. .I u9fs
  217. on a Unix system with an ANSI C compiler, copy the source to a directory on that system
  218. and run
  219. .BR make .
  220. Then install the binary in
  221. .BR /usr/etc/u9fs .
  222. Add this line to
  223. .BR inetd.conf :
  224. .IP
  225. .EX
  226. 9fs stream tcp nowait root /usr/etc/u9fs u9fs
  227. .EE
  228. .PP
  229. and this to
  230. .BR services :
  231. .IP
  232. .EX
  233. 9fs 564/tcp 9fs # Plan 9 fs
  234. .EE
  235. .LP
  236. Due to a bug in their
  237. IP software, some systems will not accept the service name
  238. .BR 9fs ,
  239. thinking it
  240. a service number because of the initial digit.
  241. If so, run the service as
  242. .B u9fs
  243. or
  244. .BR 564 .
  245. .PP
  246. On systems where listeners cannot be started,
  247. .IR execnet (4)
  248. is useful for running
  249. .I u9fs
  250. via other network mechanisms; the script
  251. .I srvssh
  252. in
  253. .IR srv (4)
  254. provides this for the
  255. .I ssh
  256. protocol.
  257. .SH SOURCE
  258. .B /sys/src/cmd/unix/u9fs
  259. .SH DIAGNOSTICS
  260. Problems are reported to the
  261. log file specified with the
  262. .B -l
  263. option (default
  264. .BR /tmp/u9fs.log ).
  265. The
  266. .B -D
  267. flag enables chatty debugging.
  268. .SH SEE ALSO
  269. .IR bind (1),
  270. .IR execnet (4),
  271. .IR srv (4),
  272. .IR ip (3),
  273. .IR nfsserver (8)
  274. .SH BUGS
  275. The implementation of devices is unsatisfactory.
  276. .LP
  277. Semantics like remove-on-close or the
  278. atomicity of
  279. .B wstat
  280. are hard to provide exactly.