9P2000.L

9P is a stateful, root-only transport. Use it to serve a virtual machine (VM) guest.

mountx/9p implements 9P2000.L, the Linux kernel v9fs dialect. It uses a stream: a unix socket for a local mount, TCP for anything else. mountx encodes and decodes every message. A JavaScript client built from the same codecs can test the complete protocol.

import { mount9p } from "mountx/9p";
import { createMemoryDriver } from "mountx/drivers/memory";

await using mounted = await mount9p(createMemoryDriver(), "/mnt/point");

mountx/auto selects 9P on Linux when FUSE cannot mount and root is available, and its options move under "9p": {…}.

#Where it mounts

9P mounting supports Linux only. v9fs is a Linux filesystem, and no other kernel implements a 9P client. Therefore, 9P has no second platform like NFS. It also has no rootless path like FUSE. mount(2) needs CAP_SYS_ADMIN, and 9P has no helper such as fusermount3.

#p9ClientProbe(platform?)

function p9ClientProbe(platform?: NodeJS.Platform): P9ClientProbe;

interface P9ClientProbe {
  usable: boolean;
  platform: "linux" | undefined;
  kernel: boolean; // is `9p` in /proc/filesystems?
  transport: boolean; // is `9pnet_fd` in /sys/module?
  modules: boolean; // is there a module tree for this kernel at all?
  root: boolean;
  reason: string | undefined;
}

This function is synchronous and small. It reads only node:fs, as nfsClientProbe() does. Therefore, mountx/auto can call it before selecting code to load. Its result lets a mount name the missing requirement instead of returning wrong fs type, bad option, bad superblock.

#What it costs, and what it buys

9P is stateful. NFSv3 is stateless. The client names a path once and receives a fid. It reuses that fid until it clunks it. The server keeps the fid table for the lifetime of the connection. This design has the following effects:

• A file deleted while open stays readable and writable. It does not return ESTALE. After unlink, the same handle still supports read, write, fstat, and fsync.
• close() and fsync() reach the driver, through Tclunk and Tfsync. A handles: true driver that buffers writes needs these calls. This is why mountx prefers 9P over NFS when both need root. A 9P driver that holds bytes across a session receives a real close. NFSv3 has no equivalent request.
• A tighter bound on server-side state. Both servers keep a table, and neither has a FORGET. NFS drops a handle entry after its last path disappears. Handle IDs come from a counter that does not repeat. Therefore, a client that still holds the handle receives NFS3ERR_STALE or NFS4ERR_STALE. The table keeps one entry for each path that a client can still name, regardless of lookup age. 9P's fid table is bounded by what the client currently has open, and a clunked fid is released on the spot.

This design has these costs:

• Root, unconditionally: see above.
• Two clients are two fid tables and two sessions, not one. createP9Server accepts multiple connections and shares byte-range locks across them. However, it serializes rename only within each connection. See Serving more than one client.

#mount9p(driver, mountpoint, options?)

function mount9p(driver: FsDriver, mountpoint: string, options?: MountP9Options): Promise<P9Mount>;

This function serves driver over 9P2000.L. It uses mount(8) to attach the kernel v9fs client. Linux, and root. Options are at the top level here. mountx/auto nests them under "9p": {…}.

It resolves after mount(8) succeeds. At that point, the kernel has completed Tversion and Tattach. Therefore, a resolved mount9p() means that the path is usable, not only that a child returned zero.

interface P9Mount extends AsyncDisposable {
  readonly mountpoint: string;
  readonly server: P9Server;
  readonly source: string; // the socket path, or the TCP address
  readonly trans: "unix" | "tcp";
  readonly connection: P9Connection; // the kernel's, and the only one this mount cares about
  readonly active: boolean;
  readonly closed: Promise<void>; // resolves once the connection and the server are both gone
  unmount(): Promise<void>;
}

unmount() is idempotent, concurrency-safe and retryable after a failure.

The promise always settles. A normal unmount settles within unmountTimeout. A forced unmount settles within twice that time because the timeout applies separately to each phase.

Each step receives only the time that remains in its phase. This includes umount(8) calls and server shutdown. Shutdown closes every fid that the session still holds. These closes can call the same driver that stopped responding.

#trans=unix, the local mount

This is the default. It does not need a native addon. mount9p() starts a unix-socket server in a mkdtemp 0700 directory holding a 0600 socket, and mounts with that socket's path as the mount's source argument:

mount -i -t 9p -o trans=unix,version=9p2000.L,msize=131096,access=client,cache=none,uname=nobody,aname=/ \
  -- /tmp/mountx-9p-XXXXXX/9p.sock /mnt/point

The kernel function p9_fd_create_unix() in net/9p/trans_fd.c connects to that path. The kernel documentation in Documentation/filesystems/9p.rst uses the same form for Plan 9 From User Space.

The handoff needs only a listener that Node can create and a path in the argument list. It does not need a socket pair or descriptor passing.

The directory's mode is what keeps the socket private: 9P authenticates nothing, so who can reach the socket is the entire security boundary.

#trans=tcp, for a VM guest

Pass port and host, or pass a server that already listens on a port. The mount then receives trans=tcp,port=N and uses the address as its source. A VM guest uses this form to mount its host over virtio-net or a host-only network.

On loopback, a Unix socket is safer than trans=tcp because every user on the host can reach a port. Therefore, TCP is not the default. Use it when a socket path cannot reach the client.

#MountP9Options

Extends P9ServerOptions (and through it P9SessionOptions), so everything on this page is settable in one object.

#cache=none

Cost of the default. cache=none is the largest cost for this transport on a metadata-heavy workload. No page cache is the smaller part of that.

The absence of a directory-entry cache has the larger cost. Each system call must walk every named path component again. Walking and clunking already cause most v9fs traffic.

The durable measurement is a message count rather than a clock.

The same bun install was run over the same driver in each mode. The default sent about 1.5 times as many 9P messages: 237,580 instead of 155,314 with cache=loose. Each of three runs produced the same message count. Therefore, this difference is protocol behavior rather than timing variation.

It lands exactly where a missing dentry cache predicts: Tclunk 56,849 → 15,292, Twalk 75,268 → 49,906, Tgetattr 41,560 → 27,490.

#cache=loose

Use cache=loose only if all these conditions are true:

• Every change to the driver arrives through this mount while the mount is active. This includes bytes, attributes, and names.
• The process serving the mount does not write to its own driver once it is mounted. This is the one people miss: a driver the server keeps updating has a second writer, and that second writer is you.
• There is only one mount of that server. Two mounts are two caches, and neither can invalidate the other.

A violation causes stale data without a warning.

One write outside the client can cause a silent stale read. The client receives old bytes without an error. There is no timeout to wait for and no invalidation function to call.

FUSE caching has a time limit because attrTimeout expires. You can also revoke it with notifyInvalInode(). 9P caching has neither control. Therefore, none is the default. Select loose only after you understand this risk.

Good uses include a build or install target, a scratch tree, and a tree served read-only to a VM guest. Do not use it when the server process continues to update the driver. JavaScript filesystems often have this shape, so this mode is not the default.

// Only with the three conditions above satisfied.
await mount9p(driver, "/mnt/point", { cache: "loose" });

#p9MountOptions(target, options?)

function p9MountOptions(target: P9MountTarget, options?: MountP9Options): string;

interface P9MountTarget {
  trans: "unix" | "tcp";
  port?: number; // for `trans=tcp`; ignored, and omitted, otherwise
}

The exact -o string mount9p() would pass. Pure, so you can see it, log it, or hand it to mount(8) yourself.

#live9pMounts() / unmountAll9p()

live9pMounts() returns active 9P mounts in creation order. unmountAll9p() unmounts all of them and never rejects.

#Serving more than one client

createP9Server accepts multiple concurrent connections, and each gets a separate session with its own fid table, negotiated msize, and PathLock. Before serving multiple clients, note these two rules:

• Byte-range locks are shared across clients. One createP9Server keeps one lock table. A Tlock from one connection is refused when another connection holds a conflicting range. Tgetlock reports the owner. Closing a connection releases all its locks. The client puts a (client_id, proc_id) owner pair on the wire. The pair identifies a process on a host. Therefore, two mounts from one kernel can have one owner. As in POSIX, a process does not conflict with itself. The server returns BLOCKED for a conflict and does not wait. fs/9p converts this result to EAGAIN for F_SETLK. It polls for F_SETLKW, so the client performs the wait. Files are keyed by path, so a rename moves the ranges with the file and a removal drops them.
• A rename is serialized per connection, not across them. Each session has a PathLock that keeps its connection consistent. Two clients can race when they rename the same subtree concurrently. This is equivalent to two local processes racing a rename on a real filesystem.

One more behaviour worth knowing regardless of client count: a Tlcreate race is refused, not rolled back. Two Tlcreate requests on the same fid race in the same way as two Tlopen requests. The same rule applies when Tlcreate races Tlopen. The losing request receives EBUSY, not the normal double-open EINVAL. Another request in flight claimed the fid; the client did not reuse an already-open fid.

The loser's own driver.open() call already ran by the time the race is caught, and that create is not undone.

If both requests name the same child, they use the same path. The winner's fid names the object that the losing request also created. No object is orphaned.

If the requests name different children, the losing request creates a real file without a fid. The server does not remove it because another request might have opened it. Removal could delete an object that another request now uses.

#Serving without mounting

Serving does not need privileges or mount(8):

import { createP9Server } from "mountx/9p";
import { createMemoryDriver } from "mountx/drivers/memory";

await using server = await createP9Server(createMemoryDriver()).listen();
// sudo mount -t 9p -o trans=tcp,port=<p>,version=9p2000.L 127.0.0.1 /mnt

interface P9Server extends AsyncDisposable {
  readonly host: string;
  readonly port: number; // 0 before listen(); ephemeral unless you set one
  readonly path: string | undefined; // set for a unix-socket server
  readonly options: P9ServerOptions; // what it was constructed with, as given
  readonly clients: readonly P9Connection[];
  readonly connections: number;
  address(): net.AddressInfo | string | null; // `net.Server.address()`, verbatim
  listen(): Promise<P9Server>; // idempotent
  attach(stream: Duplex, options?: { peer?: string; own?: boolean }): P9Connection;
  close(): Promise<void>; // idempotent; does not wait for clients to leave politely
}

Use attach() with an already-connected stream that you control. Examples include one end of a socket pair, a pipe, and a test double. The mount9p() listener also uses attach() internally.

#P9ServerOptions

#P9Session

new P9Session(driver: FsDriver, options?: P9SessionOptions)

P9Session converts bytes to bytes without a socket: handleCall(bytes) → Promise<Uint8Array | null>.

handleCall() never rejects. Every message that needs a reply gets exactly one. A thrown driver error becomes Rlerror with a positive Linux errno from src/errors.ts. This transport has no status-mapping layer.

session.driver; // the Loopback wrapping your driver
session.fids; // the FidTable
session.stats; // { requests, replies, errors, dropped, flushed, assertions, messages }

#P9SessionOptions

#Teardown

Teardown follows the same rules as FUSE and NFS. It first runs plain umount(8). After the deadline, it tries umount -f and then umount -l.

The mount table is authoritative; command exit status is not. One deadline bounds every spawned child, and mountx abandons a child that exceeds it. The operation remains idempotent and retryable. umount -f has a real effect here. v9fs implements .umount_begin through v9fs_umount_begin(), which cancels requests in flight. It has the same role as FUSE fuse_abort_conn.

Each mount has one connection, and the connection ends at unmount. 9P has no Tdestroy or equivalent of FUSE_DESTROY. Therefore, a mount waits for P9Connection.closed, which means the session and stream are closed. This applies to its own unmount() and another process's umount(8).

A terminated 9P server does not block the mount like a terminated FUSE daemon. The first later access returns ECONNRESET. Each following access immediately returns EIO. A plain umount removes the mount, so no force is necessary.

The remaining deadlock requires a client in the server process: see Troubleshooting.

#The layers below

Every file except server.ts and mount.ts runs on any operating system without privileges. Therefore, a JavaScript client built from the same codecs can test the protocol:

mountx/9p re-exports the whole protocol layer by name:

• wire.ts: P9Reader/P9Writer: little-endian, unaligned, bounds-checked, and copy the bytes they retain.
• constants.ts: every P9_T*/P9_R* message type, the GETATTR/SETATTR masks, lock and qid-type constants.
• protocol.ts: every message encoded and decoded, P9FrameAssembler, P9DirentPacker, messageName().
• fids.ts: FidTable and the readdir cursor scheme: the state a stateful protocol needs.

#Not available

• Legacy 9P2000 opcodes. Topen/Tcreate/Tstat/Twstat return Rlerror ENOTSUP. This server supports only .L, and no v9fs client sent these opcodes during a complete local workload.
• Tauth. The session decodes this field so it can return a specific refusal. It does not authenticate the field. The socket is the complete security boundary. For trans=tcp, the network path to the socket is the boundary.
• xattr, beyond the probe. Txattrwalk/Txattrcreate return ENOTSUP. The server handles this probe with little work because a real client sends one Txattrwalk for each created file (v9fs probes security.* on every Tlcreate).

#Next

• FUSE: the transport that beats this one whenever it can mount.
• NFSv3: the other root-needing transport, and the stateless trade this one avoids.
• mountx/auto reference: the chooser that calls this.