sys/man/4/u9fs

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