---
name: "nvmetcli"
section: "8"
platform: "linux"
package: "nvmetcli"
version: "0.9-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/nvmetcli"
---

# nvmetcli(8)

Configure NVMe-over-Fabrics Target.

## NAME

nvmetcli - Configure NVMe-over-Fabrics Target.

## USAGE

```
nvmetcli
nvmetcli clear
nvmetcli restore [filename.json]
```

## DESCRIPTION

**nvmetcli** is a program used for viewing, editing, saving, and starting a Linux kernel NVMe Target, used for an NVMe-over-Fabrics network configuration. It allows an administrator to export a storage resource (such as NVMe devices, files, and volumes) to a local block device and expose them to remote systems based on the NVMe-over-Fabrics specification from **http://www.nvmexpress.org**.

**nvmetcli** is run as root and has two modes:

 1\. An interactive configuration shell

 2\. Command-line mode which uses an argument

## BACKGROUND

The term **NQN** used throughout this man page is the **NVMe Qualified Name** format which an NVMe endpoint (device, subsystem, etc) must follow to guarantee a unique name under the NVMe standard. Any name in a network system setup can be used, but if it does not follow the NQN format, it may not be unique on an NVMe-over-Fabrics network.

Note that some of the fields set for an NVMe Target port under interactive mode are defined in the "Discovery Log Page" section of NVMe-over-Fabrics specification. Each NVMe Target has a discovery controller mechanism that an NVMe Host can use to determine the NVM subsystems it can access. **nvmetcli** can be used to add a new record to the discovery controller upon each new subsystem entry and port entry that the newly created subsystem entry binds to (see **OPTIONS** and **EXAMPLES** sections). Each NVMe Host only gets to see the discovery entries defined in **/subsystems/\[NQN NAME\]/allowed\_hosts** and the IP port it is connected to the NVMe Target. An NVMe Host can retrieve these discovery logs via the nvme-cli tool (**https://github.com/linux-nvme/nvme-cli**).

## OPTIONS

**Interactive Configuration Shell**

To start the interactive configuration shell, type **nvmetcli** on the command-line. nvmetcli interacts with the Linux kernel NVMe Target configfs subsystem starting at base nvmetcli directories **/port**, **/subsystem**, and **/host**. Configuration changes entered by the administrator are made immediately to the kernel target configuration. The following commands can be used while in the interactive configuration shell mode:

| | |
| --- | --- |
| cd | Allows to move around the tree. |
| ls | Lists contents of current tree node. |
| create \[NQN name\]/\[#\] | Create a new object using the specified name or number. If a \[NQN name\]/\[#\] is not specified, a random entry will be used. |
| delete \[NQN name\]/\[#\] | Delete an object with the specified name or number. |
| set attr allow\_any\_host=\[0/1\] | Used under **/subsystems/\[NQN name\]** to specify if any NVMe Host can connect to the subsystem. |
| set device path=\[device path\] | Used under **/subsystems/\[NQN name\]/namespaces** to set the (storage) device to be used. |
| set device nguid=\[string\] | Used under **/subsystems/\[NQN name\]/namespaces** to set the unique id of the device to the defined namespace. |
| enable/disable | Used under **/subsystems/\[NQN name\]/namespaces** to enable and disable the namespace. |
| set addr \[discovery log page field\]=\[string\] | Used under **/ports/\[#\]** to create a port which access is allowed. See **EXAMPLES** for more information. |
| saveconfig \[filename.json\] | Save the NVMe Target configuration in .json format. Without specifying the filename this will save as **/etc/nvmet/config.json**. This file is in JSON format and can be edited directly using a preferred file editor. |
| exit | Quits interactive configuration shell mode. |

**Command Line Mode**

Typing **nvmetcli \[cmd\]** on the command-line will execute a command and not enter the interactive configuration shell.

| | |
| --- | --- |
| restore \[filename.json\] | Loads a saved NVMe Target configuration. Without specifying the filename this will use **/etc/nvmet/config.json**. |
| clear | Clears a current NVMe Target configuration. |
| ls | Dumps the current NVMe Target configuration. |

## EXAMPLES

Make sure to run nvmetcli as root, the nvmet module is loaded, your devices and all dependent modules are loaded, and configfs is mounted on /sys/kernel/config using:

```
mount -t configfs none /sys/kernel/config
```

The following section walks through a configuration example.

• To get started with the interactive mode and the nvmetcli command prompt, type (in root):

```
# ./nvmetcli
...>
```

• Create a subsystem. If you do not specify a name a NQN will be generated, which is probably the best choice. We don’t do it here as the name would be random:

```
> cd /subsystems
...> create testnqn
```

• Add access for a specific NVMe Host by it’s NQN:

```
...> cd /hosts
...> create hostnqn
...> cd /subsystems/testnqn
...> set attr allow_any_host=0
...> cd /subsystems/testnqn/allowed_hosts/
...> create hostnqn
```

• Remove access of a subsystem by deleting the Host NQN:

```
...> cd /subsystems/testnqn/allowed_hosts/
...> delete hostnqn
```

• Alternatively this allows any Host to connect to the subsystsem. Only use this in tightly controlled environments:

```
...> cd /subsystems/testnqn/
...> set attr allow_any_host=1
```

• Create a new namespace. If you do not specify a namespace ID the fist unused one will be used:

```
...> cd /subsystems/testnqn/namespaces
...> create 1
...> cd 1
...> set device path=/dev/nvme0n1
...> enable
```

Note that in the above setup the *device\_nguid* attribute does not have to be set for correct NVMe Target functionality (but to correctly match a namespace to the exact device upon clear and restore operations, it is advised to set the *device\_nguid* parameter).

• Create a loopback port that can be used with nvme-loop module on the same physical machine...

```
...> cd /ports/
...> create 1
...> cd 1/
...> set addr trtype=loop
...> cd subsystems/
...> create testnqn
```

• or create an RDMA (IB, RoCE, iWarp) port using IPv4 addressing. 4420 is the IANA assigned default port for NVMe over Fabrics using RDMA:

```
...> cd /ports/
...> create 2
...> cd 2/
...> set addr trtype=rdma
...> set addr adrfam=ipv4
...> set addr traddr=192.168.6.68
...> set addr trsvcid=4420
...> cd subsystems/
...> create testnqn
```

• or create an FC port. traddr is the WWNN/WWPN of the FC port.

```
...> cd /ports/
...> create 3
...> cd 3/
...> set addr trtype=fc
...> set addr adrfam=fc
...> set addr traddr=nn-0x1000000044001123:pn-0x2000000055001123
...> set addr trsvcid=none
...> cd subsystems/
...> create testnqn
```

• Saving the NVMe Target configuration:

```
./nvmetcli
...> saveconfig test.json
```

• Loading an NVMe Target configuration:

```
  ./nvmetcli restore test.json
```

• Clearing a current NVMe Target configuration:

```
  ./nvmetcli clear
```

## ADDITIONAL INFORMATION

nvmetcli has the ability to start and stop the NVMe Target configuration on boot and shutdown through the **systemctl** Linux utility via a .service file. nvmetcli package comes with **nvmet.service** which when installed, it can automatically restore the default, saved NVMe Target configuration from **/etc/nvmet/config.json**. **nvmet.service** can be installed in directories such as **/lib/systemd/system**.

To explicitly enable the service, type:

```
  systemctl enable nvmet
```

To explicitly disable the service, type:

```
  systemctl disable nvmet
```

See also [systemctl(1)](/systemctl/1.md).

## AUTHORS

This man page was written by **Jay Freyensee**\[1\]. nvmetcli was originally written by **Christoph Hellwig**\[2\].

## REPORTING BUGS & DEVELOPMENT

Please send patches and bug reports to **linux-nvme@lists.infradead.org**\[3\] for review and acceptance.

## LICENSE

nvmetcli is licensed under the **Apache License, Version 2.0**. Software distributed under this license is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or implied.

## NOTES

- 1\.

  Jay Freyensee

  mailto:james.p.freyensee@intel.com

- 2\.

  Christoph Hellwig

  mailto:hch@infradead.org

- 3\.

  linux-nvme@lists.infradead.org

  mailto:linux-nvme@lists.infradead.org