U9FS(4)

Okay so bestie, welcome to the U9FS(4) page from the Kernel Interfaces Manual — section 4, kernel interfaces, you know the vibe. This is literally all about u9fs, the program that serves 9P from Unix, and I'm about to spill all the tea. 💅✨

🌸 NAME 🌸

u9fs — serve 9P from Unix. That's it. That's the name. Iconic. 💖

✨ SYNOPSIS ✨

u9fs [ -Dnz ] [ -a authtype ] [ -A autharg ] [ -l logfile ] [ -m msize ]
[ -u onlyuser ] fsroot

💫 DESCRIPTION 💫

Okay so first things first: U9fs is not a Plan 9 program. Like, it's not running on Plan 9 itself. Instead, it's this program that serves Unix files to Plan 9 machines using the 9P protocol (see intro(5)). It's literally the bridge between your Unix filesystem and your Plan 9 besties. 🌉

It's typically invoked on a Unix machine by inetd with its standard input and output connected to a network connection — usually TCP on an Ethernet. Think of it like a little server gremlin that wakes up when someone connects. 💻✨

It typically runs as user root (yes, root, we stan a powerful queen) and multiplexes access to multiple Plan 9 clients over the single wire. So like, many clients, one connection, no drama. 👑

It assumes Plan 9 uids match Unix login names, and changes to the corresponding Unix effective uid when processing requests. So if your Plan 9 username is glenda, it's gonna look for glenda on the Unix side and become that user. It's giving "identity matching" realness. 🆔

Characters in file and directory names unacceptable to Plan 9 are translated into a three-character sequence: followed by two hexadecimal digits. So like, weird characters get turned into a cute little escape code. It's literally character customization but for filenames. 🔤

And bestie, it serves both 9P1 (the 9P protocol as used by the second and third editions of Plan 9) and 9P2000. So it's bilingual in protocol years. No cap. 🗣️

The options are:

🎀 OPTIONS 🎀

• -D — Write very chatty debugging output to the log file (see the -l option below). It's giving "spill the tea" but for debugging. 🗣️💬
• -n — Signals that u9fs is not being invoked with a network connection on standard input and output, and thus should not try to determine the remote address of the connection. This is useful when u9fs is not invoked from inetd (see examples below). Like, "don't look for a network address, bestie, there isn't one." 🙈
• -z — Truncate the log file on startup. This is useful mainly when debugging with -D. Fresh log, fresh me. 🧼
• -a authtype — Sets the authentication method to be used. authtype should be rhosts, none, or p9any. The default is rhosts, which uses the ruserok library call to authenticate users by entries in /etc/hosts.equiv or $HOME/.rhosts. This default is discouraged for all but the most controlled networks. Specifying none turns off authentication altogether. This is useful when u9fs is not invoked from inetd (see examples below, or srvssh in srv(4)). Specifying p9any uses the fourth edition Plan 9 authentication mechanisms. The file /etc/u9fs.key, or autharg if specified (see the -A option), is consulted for the authentication data and should be suitably protected. This file must contain exactly three lines: secret (plaintext password), u9fs-user (user id), and plan9-auth.dom (authentication domain). Finally, factotum must be taught a key of the form: key proto=p9sk1 dom=plan9-auth.dom user=u9fs-user !password=secret 🔐
• -A autharg — Used to specify an argument to the authentication method. See the authentication descriptions above. It's like passing a lil note to your auth bestie. 📝
• -l logfile — Specifies the file which should contain debugging output and other messages. The out-of-the-box compile-time default is /tmp/u9fs.log. That's where the drama gets written down. 📓
• -m msize — Set msize for 9P2000 (see open(5)). Bigger messages, bigger vibes. 📦
• -u user — Treat all attaches as coming from user. This is useful in some cases when running without inetd; see the examples. Like, "everyone is user now, deal with it." 👤

If fsroot is specified, u9fs will serve only that tree; otherwise, it will serve the entire Unix file system. So you can scope it down or give it the whole thing. Your call, bestie. 🌳

🌈 EXAMPLES 🌈

Plan 9 calls 9P file service 9fs with TCP port number 564. Set up this way on a machine called, say, kremvax, u9fs may be connected to the name space of a Plan 9 process by:

9fs kremvax

For more information on this procedure, see srv(4) and bind(1). 📚

By default, u9fs serves the entire file system of the Unix machine. It forbids access to devices because the program is single-threaded and may block unpredictably. Using the attach specifier device connects to a file system identical to the usual system except it only permits device access (and may block unpredictably):

srv tcp!kremvax!9fs
mount -c /srv/tcp!kremvax!9fs /n/kremvax device

(The 9fs command does not accept an attach specifier.) Even so, device access may produce unpredictable results if the block size of the device is greater than 8192, the maximum data size of a 9P message. So like, proceed with caution, bestie. ⚠️

The source to u9fs is in the Plan 9 directory /sys/src/cmd/unix/u9fs. To install u9fs on a Unix system with an ANSI C compiler, copy the source to a directory on that system and run make. Then install the binary in /usr/etc/u9fs. Add this line to inetd.conf:

9fs     stream  tcp     nowait  root   /usr/etc/u9fs   u9fs

and this to services:

9fs     564/tcp       9fs  # Plan 9 fs

Due to a bug in their IP software, some systems will not accept the service name 9fs, thinking it a service number because of the initial digit. If so, run the service as u9fs or 564. Weird, but okay. 🤷‍♀️

On systems where listeners cannot be started, execnet(4) is useful for running u9fs via other network mechanisms; the script srvssh in srv(4) provides this for the ssh protocol. So many ways to connect, so little time. 🚀

⭐ SOURCE ⭐

/sys/src/cmd/unix/u9fs — that's where the magic lives. 💫

🔥 DIAGNOSTICS 🔥

Problems are reported to the log file specified with the -l option (default /tmp/u9fs.log). The -D flag enables chatty debugging. So if something goes wrong, check the log — it's probably in there spilling everything. 📋

🦋 SEE ALSO 🦋

bind(1), execnet(4), srv(4), ip(3), nfsserver(8) — go read those if you want the full lore. 📖

💀 BUGS 💀

The implementation of devices is unsatisfactory. Like, it's not it. 😬

Semantics like remove-on-close or the atomicity of wstat are hard to provide exactly. So don't expect perfection on those, bestie. It's complicated. 💔

---

💖 That's the whole page, bestie! This has been U9FS(4) from the Kernel Interfaces Manual, source at /sys/src/cmd/unix/u9fs. Periodt. 💖