Home / Alt manpages / systemd-storagetm.service(8)

  • systemd-storagetm.service(8)
  • Admin command
  • linux

Export a Disk over NVMe-TCP with systemd-storagetm

systemd-storagetm turns a block device or a plain file into an NVMe-TCP target in one command, no separate NVMe-oF stack required. Budget about 10 minutes on a prepared test machine. This is not a friendly file-share tool: the export has no authentication and no encryption, and the client can write to it.

The route

Jump straight to the step you need, or tick off Done means at the end.

Before you start

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

Security checkpoint

Stop here if an untrusted machine can reach the network. The documented implementation exposes disks without access control, authentication or encryption, and permits both reads and writes. Use it only on a local setup you control. Choosing ip=dhcp gives the host a routable address and expands the exposure beyond the local link.

1. Check the installed interface

Run the version and help queries as an ordinary user. Neither one starts a service or touches 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 takes one or more device or regular-file arguments. The --all option (short form -a) changes that contract entirely: it switches to a live inventory that exposes current and future local block devices as they appear.

2. Identify the exact device

Use your normal inventory tools and write down the path before touching anything privileged. This is the step that catches the classic mistake: 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

Only swap in <YOUR-DISK-ID> once you have confirmed it identifies the intended device. Prefer a stable /dev/disk/by-id/ path, but still inspect the resolved target.

Warning

A typo here exports the wrong disk, and a remote NVMe host can write to it.

3. Export one device for a controlled test

For a narrowly scoped test, pass one block-device path or a regular file to the executable. Starting it needs root, because it configures the local NVMe target.

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

There is no success banner. Keep the process running in the foreground while the target is needed, and watch its exit status. If it exits immediately, read the error it printed and check that the path exists, is the right type, and is not already claimed elsewhere.

Recovery

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 the normal way instead. Do not disconnect a client while it still has mounted or actively written filesystems; unmount and flush on 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 you give is a base, not necessarily the final name a client sees.

$ 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 suits your environment. Leave the option out and systemd 255 derives a default from a machine-specific 128-bit ID: nqn.2023-10.io.systemd:storagetm.<ID>. That default is fine for a single host, but an explicit value makes a test setup easier to recognise later.

5. Use all-device mode only after reading the exception

--all watches devices arriving and disappearing, which is why it is the option meant 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. That is a safety mechanism, not a guarantee every exported device is safe to write to. Repeat the switch and that exclusion goes away:

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

Destructive-action warning: never use the repeated form on a normal running host. It can expose the storage the host itself depends on, 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 keep a way to remove it.

6. Verify the network and stop cleanly

The storage target also needs networking configured. With ip=link-local, the host gets IPv4LL and IPv6LL addresses, which are non-routable and keep 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 nothing is still mounted through the exported device. Starting the target again undoes a temporary foreground test, but it does not undo writes a client already made.

Done means

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