# Serving a read-only filesystem This tutorial walks through the smallest useful NFS server you can build with Tahr: a static, in-memory tree of files served read-only. By the end you'll be able to mount it with your operating system's own NFS client. The complete, tested code lives in the repository at [`test/support/readonly_fs.ex`](https://harton.dev/james/tahr/src/branch/main/test/support/readonly_fs.ex) — what follows is that file, piece by piece. ## The moving parts An NFS server built with this library is just three things: 1. **A `Tahr.Mount.Backend`** — decides which paths clients may mount and hands out the root file handle for each. 2. **A `Tahr.NFSv3.Backend`** — answers the filesystem procedures: GETATTR, LOOKUP, READ, READDIR, and friends. 3. **A `Tahr.RPC.Server`** — the TCP listener. You hand it a *program registry* mapping ONC RPC program numbers to handlers, and the library takes care of the wire protocol: XDR, record marking, the portmapper, AUTH_SYS. ``` programs = %{ 100_005 => %{3 => Tahr.Mount.Handler.with_backend(MyMountBackend)}, 100_003 => %{3 => Tahr.NFSv3.Handler.with_backend(MyNFSBackend)} } children = [ {Tahr.RPC.Server, port: 2049, programs: programs} ] ``` 100005 is the MOUNT program, 100003 is NFS itself, both version 3. `with_backend/1` binds your backend module into the stateless handler. The portmapper (program 100000) is always registered for you so clients can discover the server. Our filesystem is a compile-time map of `fileid => node`, so every callback is a pure lookup — no processes, no state to manage. ## Step 1: model the tree ```elixir defmodule ReadonlyFS do @moduledoc """ A tiny read-only filesystem served over NFSv3. """ alias Tahr.NFSv3.Filehandle alias Tahr.NFSv3.Types.{Fattr3, Nfstime3} @vol_id "readonly-fs-v001" @fsid 0xFE5_0001 @root_fileid 1 @modification_time %Nfstime3{seconds: 1_767_225_600, nseconds: 0} @tree %{ 1 => %{ type: :dir, mode: 0o755, children: %{"hello.txt" => 2, "docs" => 3} }, 2 => %{ type: :reg, mode: 0o644, content: "Hello from Tahr!\n" }, 3 => %{ type: :dir, mode: 0o755, children: %{"notes.txt" => 4} }, 4 => %{ type: :reg, mode: 0o644, content: "Static content, served over NFSv3.\n" } } end ``` A flat map of `fileid => node` is enough: directories carry a `children` map from name to fileid. The root is fileid 1, and it contains one file and one subdirectory. ### File handles NFS file handles are opaque blobs of up to 64 bytes that the client hands back to you on every call — you choose what goes in them. `Tahr.NFSv3.Filehandle` packs a 16-byte volume id, a 64-bit fileid, and a 32-bit generation counter into 29 bytes, which is all we need: ```elixir def vol_id, do: @vol_id def root_handle, do: handle_for(@root_fileid) def handle_for(fileid), do: Filehandle.encode(@vol_id, fileid) def fetch(fhandle) do with {:ok, decoded} <- Filehandle.decode(fhandle), true <- Filehandle.same_volume?(decoded, @vol_id), {:ok, node} <- Map.fetch(@tree, decoded.fileid) do {:ok, decoded.fileid, node} else _ -> {:error, :stale} end end ``` Every callback starts with `fetch/1`. Handles that fail to decode, belong to a different volume, or name a forgotten fileid are refused with `NFS3ERR_STALE` — the client drops its cache and re-resolves. ### Attributes GETATTR and most other replies carry an `fattr3` — POSIX-style metadata. Note that `ctime` means *metadata-change time*, not creation time, and for a static tree one fixed timestamp everywhere is honest: ```elixir def attr(fileid, node) do size = size_of(node) %Fattr3{ type: node.type, mode: node.mode, nlink: nlink(node), uid: 0, gid: 0, size: size, used: size, fsid: @fsid, fileid: fileid, atime: @modification_time, mtime: @modification_time, ctime: @modification_time } end ``` (`nlink/1` and `size_of/1` are two-line helpers — directories claim two links, files one; only regular files have a size.) ## Step 2: the Mount backend The MOUNT protocol is how a client turns a path like `/export` into a root file handle. The behaviour has two required callbacks; the mount-bookkeeping callbacks are optional and we skip them: ```elixir defmodule ReadonlyFS.MountBackend do @behaviour Tahr.Mount.Backend alias Tahr.Mount.Types.ExportNode @export_path "/export" @auth_sys 1 @impl true def resolve(@export_path, _ctx), do: {:ok, ReadonlyFS.root_handle(), [@auth_sys]} def resolve(_path, _ctx), do: {:error, :noent} @impl true def list_exports(_ctx), do: [%ExportNode{dir: @export_path, groups: []}] end ``` `resolve/2` returns the root handle plus the list of acceptable RPC auth flavours (`1` is AUTH_SYS). Anything else gets `MOUNT3ERR_NOENT`. `list_exports/1` backs the EXPORT procedure — `showmount -e`. ## Step 3: the NFSv3 backend — read procedures The `Tahr.NFSv3.Backend` behaviour has 21 callbacks, one per NFSv3 procedure. Take them in three groups. ### Object lookup and attributes ```elixir @impl true def getattr(fhandle, _auth, _ctx) do case ReadonlyFS.fetch(fhandle) do {:ok, fileid, node} -> {:ok, ReadonlyFS.attr(fileid, node)} {:error, status} -> {:error, status} end end ``` Every callback receives the file handle, the decoded credential (`%Tahr.RPC.Auth.Sys{}` or `%Auth.None{}`), and an opaque `ctx` map carrying the RPC envelope (including `ctx.peer`, the client's IP address, if you want per-export host filtering). ACCESS answers "which of these permission bits will you grant?" — RFC 1813's flags are READ `0x01`, LOOKUP `0x02`, MODIFY `0x04`, EXTEND `0x08`, DELETE `0x10`, EXECUTE `0x20`. A read-only server grants only the read-ish subset: ```elixir @access_read 0x0001 @access_lookup 0x0002 @access_execute 0x0020 @grantable bor(bor(@access_read, @access_lookup), @access_execute) @impl true def access(fhandle, requested_mask, _auth, _ctx) do case ReadonlyFS.fetch(fhandle) do {:ok, fileid, node} -> {:ok, band(requested_mask, @grantable), ReadonlyFS.attr(fileid, node)} {:error, status} -> {:error, status, nil} end end ``` Mind the error shapes — they differ per callback because the RFC attaches attributes to different replies. GETATTR errors are bare `{:error, status}`; ACCESS errors carry a `post_op_attr` (or `nil`) as a third element. Each callback's `@doc` spells out its shape. LOOKUP is the workhorse — name to handle within a directory: ```elixir @impl true def lookup(dir_fhandle, name, _auth, _ctx) do case ReadonlyFS.fetch(dir_fhandle) do {:ok, dir_id, %{type: :dir} = dir} -> lookup_child(dir_id, dir, name) {:ok, _fileid, _node} -> {:error, :notdir, nil} {:error, status} -> {:error, status, nil} end end defp lookup_child(dir_id, dir, name) do case ReadonlyFS.fetch_child(dir, name) do {:ok, fileid, node} -> {:ok, ReadonlyFS.handle_for(fileid), ReadonlyFS.attr(fileid, node), ReadonlyFS.attr(dir_id, dir)} {:error, status} -> {:error, status, ReadonlyFS.attr(dir_id, dir)} end end ``` Note the three-element success tuple: the child's handle, the child's attributes, and the *directory's* attributes — and that even a `NOENT` reply carries the directory's attributes so the client can refresh its cache. ### Reading file content READ returns a map with a lazy chunk enumerator, an EOF flag, and a post-op attribute. The handler streams the chunks straight to the socket, so a real backend should never materialise a whole file — our static files are already in memory, so a one-element list is honest here: ```elixir @impl true def read(fhandle, offset, count, _auth, _ctx) do case ReadonlyFS.fetch(fhandle) do {:ok, fileid, %{type: :reg, content: content} = node} -> size = byte_size(content) data = binary_part(content, min(offset, size), min(count, size - min(offset, size))) {:ok, %{ data: [data], eof: offset + byte_size(data) >= size, post_op: ReadonlyFS.attr(fileid, node) }} {:ok, _fileid, _node} -> {:error, :isdir, nil} {:error, status} -> {:error, status, nil} end end ``` ### Listing directories READDIR and READDIRPLUS paginate with an opaque *cookie* per entry — you pick the encoding, the client just hands it back. A *cookie verifier* lets the server spot a directory that changed mid-pagination: return `{:error, :bad_cookie, attr}` and the client restarts from cookie 0. Our tree never changes, so a constant verifier and position-index cookies are enough: ```elixir @cookieverf <<0::64>> @impl true def readdir(fhandle, cookie, verf, _count, _auth, _ctx) do with_dir(fhandle, fn dir_id, dir -> with :ok <- check_verf(cookie, verf, dir_id, dir) do {:ok, entries_after(dir, cookie), @cookieverf, true, ReadonlyFS.attr(dir_id, dir)} end end) end defp entries_after(dir, cookie) do dir |> ReadonlyFS.entries() |> Enum.drop_while(fn {_id, _name, c} -> c <= cookie end) end ``` Entries are `{fileid, name, cookie}` tuples; the handler splices in `.` and `..` for you. We ignore the client's `count` budget and return everything with `eof: true` — fine for tiny directories; a real backend must stop when the next entry would blow the budget. READDIRPLUS is identical except each entry also carries the child's attributes and handle. ### Server introspection FSSTAT, FSINFO, and PATHCONF describe the filesystem to the client — capacity, transfer sizes, feature flags. Static answers are fine: ```elixir @impl true def fsinfo(fhandle, _auth, _ctx) do case ReadonlyFS.fetch(fhandle) do {:ok, fileid, node} -> reply = %{ rtmax: 65_536, rtpref: 32_768, rtmult: 4_096, wtmax: 65_536, wtpref: 32_768, wtmult: 4_096, dtpref: 8_192, maxfilesize: 1_048_576, time_delta: %Nfstime3{seconds: 0, nseconds: 1_000_000}, properties: @fsf3_homogeneous } {:ok, reply, ReadonlyFS.attr(fileid, node)} {:error, status} -> {:error, status, nil} end end ``` `properties` is an OR of RFC 1813's `FSF3_*` flags — `0x01` LINK, `0x02` SYMLINK, `0x08` HOMOGENEOUS, `0x10` CANSETTIME. A read-only tree advertises only HOMOGENEOUS. READLINK we refuse with `NFS3ERR_INVAL` — there are no symlinks in this tree. ## Step 4: refuse mutations The remaining eleven callbacks all exist, because the behaviour requires them — they just say no. `NFS3ERR_ROFS` is exactly what a real read-only filesystem returns: ```elixir @impl true def setattr(_fhandle, _sattr, _guard_ctime, _auth, _ctx), do: {:error, :rofs} @impl true def create(_dir, _name, _mode, _auth, _ctx), do: {:error, :rofs} @impl true def write(_fhandle, _offset, _data, _stable, _auth, _ctx), do: {:error, :rofs} # …and the same for mkdir, remove, rmdir, symlink, mknod, link, # rename, and commit. ``` ## Step 5: wire the supervision tree ```elixir defmodule MyApp.Application do use Application @impl true def start(_type, _args) do programs = %{ 100_005 => %{3 => Tahr.Mount.Handler.with_backend(ReadonlyFS.MountBackend)}, 100_003 => %{3 => Tahr.NFSv3.Handler.with_backend(ReadonlyFS.NFSBackend)} } children = [ {Tahr.RPC.Server, port: 2049, programs: programs} ] Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor) end end ``` ## Step 6: mount it The library's portmapper answers on the same port as everything else, so tell the client where to look (rather than the rpcbind it would normally consult on port 111): ```bash sudo mount -t nfs -o vers=3,tcp,port=2049,mountport=2049 \ 127.0.0.1:/export /mnt/readonly cat /mnt/readonly/hello.txt # Hello from Tahr! ls -la /mnt/readonly/docs # notes.txt ``` ## Where next This tree can't change — every write bounces off `NFS3ERR_ROFS`. The [read-write tutorial](read-write-server.html) builds a mutable filesystem with an `Agent`, real WRITE/CREATE/RENAME support, and the weak-cache-consistency data the kernel expects — which is also the `Tahr.InMemory` reference backend that `mix tahr.serve` runs.