Expose a Local Block Device over NVMe-TCP with systemd-storagetm

You will prepare a systemd 255 host to expose a chosen block device or regular file as an NVMe-TCP mass-storage device, with a network boundary that limits who can reach it. Allow about 10 minutes for a prepared test machine. This is an infrastructure operation, not a harmless local file-sharing command: the target is exported read/write and the local tool provides no authentication or encryption.

Before you start

• Use a disposable or deliberately selected device. Do not experiment with the device backing the running root filesystem.
• Have a second machine on the same private link if you intend to connect as an NVMe host. The manpage's recommended boot mode uses link-local addressing.
• Check the installed implementation. The examples below were verified against Ubuntu's systemd 255.4-1ubuntu8.17.

1. Check the installed interface

Run the version and help queries as an ordinary user. They do not start a service or alter storage.

$ /usr/lib/systemd/systemd-storagetm --version
systemd 255 (255.4-1ubuntu8.17)
$ /usr/lib/systemd/systemd-storagetm --help
systemd-storagetm [OPTIONS...] [DEVICE...]

Expose a block device or regular file as NVMe-TCP volume.

The executable accepts one or more device or regular-file arguments. The --all option changes that contract to a live inventory: it exposes current and future local block devices as they appear. The short form is -a.

2. Identify the exact device

Use your normal inventory tools and record the path before doing anything privileged. This read-only check helps catch the common mistake of selecting the running root disk by label or by an unstable kernel name.

$ lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,MOUNTPOINTS
$ readlink -f /dev/disk/by-id/<YOUR-DISK-ID>
/dev/sdX

Replace <YOUR-DISK-ID> only after confirming it identifies the intended device. Prefer a stable /dev/disk/by-id/ path for a planned invocation, but still inspect the resolved target. A typo here can export the wrong disk, and a remote NVMe host can write to it.

3. Choose one device for a controlled test

For a narrowly scoped test, pass one block-device path or a regular file to the executable. Starting this operation requires elevated privileges because it configures the local NVMe target.

$ sudo /usr/lib/systemd/systemd-storagetm /dev/disk/by-id/<YOUR-TEST-DISK-ID>

There is no useful success banner promised by the manpage. Keep the process running while the target is needed, and watch its exit status from the terminal that started it. If it exits immediately, inspect the error printed by that invocation and confirm that the path exists, is the intended type, and is not already claimed by another setup.

Recovery checkpoint: pressing Ctrl-C terminates this foreground invocation and removes the target configuration created by that process. If you launched it through another supervisor, stop that supervisor using its normal service-management procedure. Do not disconnect a client while it still has mounted or actively written filesystems; unmount and flush the client side first.

4. Set an explicit NQN when clients need a stable name

Use --nqn= when your test plan needs a known NVMe Qualified Name. The tool appends a dot and the block-device name before exposing the target, so the value is a base rather than necessarily the final name seen by a client.

$ sudo /usr/lib/systemd/systemd-storagetm \
    --nqn=nqn.2026-09.example.test:lab \
    /dev/disk/by-id/<YOUR-TEST-DISK-ID>

Choose an NQN that follows the NVMe specification and is appropriate for your environment. If you omit this option, systemd 255 derives a default from a machine-specific 128-bit ID: nqn.2023-10.io.systemd:storagetm.<ID>. That default is convenient for a single host, but an explicit value makes a controlled test easier to recognise.

5. Use all-device mode only after reviewing its exception

--all watches for devices arriving and disappearing, so it is the option intended for storage-target mode rather than a one-off export.

$ sudo /usr/lib/systemd/systemd-storagetm --all

By default, devices originating on the same underlying block device as the current root filesystem are excluded. This is a safety mechanism, not a general guarantee that every exported device is safe to write. Repeating the switch disables that exclusion:

$ sudo /usr/lib/systemd/systemd-storagetm --all --all

Destructive-action warning: do not use the repeated form on a normal running host. It can expose the storage on which the host itself depends, and a remote writer can corrupt the operating system or mounted data. If you need storage-target mode at boot, the documented kernel command line is rd.systemd.unit=storage-target-mode.target ip=link-local. Add it only through your bootloader's normal, recoverable configuration process and retain a way to remove it.

6. Verify the network and stop cleanly

The storage target needs networking configured too. With ip=link-local, the host receives IPv4LL and IPv6LL addresses, which are non-routable and restrict discovery to the local link. Confirm the addresses without changing anything:

$ ip -br address
$ ip route

When a test is finished, stop the client-side use first, then stop the foreground target process with Ctrl-C or stop the unit that owns it. Re-run lsblk on both machines and confirm that no filesystem remains mounted through the exported device. Starting the target again is the undo for a temporary foreground test; it does not undo writes already made by a client.

Done means

• The installed executable reports systemd 255 and its help lists --nqn and --all.
• You identified the intended device with lsblk and did not select the running root disk.
• The target is reachable only on a trusted local link, unless you have deliberately accepted the risk of routable addressing.
• You know whether the process is exposing one device or watching all devices.
• You stopped the target only after clients had unmounted or otherwise finished using the exported storage.