diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 204 |
1 files changed, 89 insertions, 115 deletions
@@ -5,157 +5,82 @@ NVM-Express user space tooling for Linux. -nvme-cli uses meson as build system. In order to build nvme-cli -run following commands +## Build from source - $ meson .build - $ ninja -C .build +nvme-cli uses meson as build system. -nvme-cli depends on json-c +### nvme-cli dependencies: -To install, run: + | Library | Dependency | Notes | + |---------|------------|-------| + | libnvme, libnvme-mi| yes | be either installed or included into the build via meson fallback feature | + | json-c | optional | recommended, without all plugins are disabled and json-c output format is disabled | + | libhugetblfs | optional | adds support for hugetblfs | - # meson install -C .build - -There is a Makefile wrapper for meson for backwards compatiblily - - $ make - # make install - -RPM build support via Makefile that uses meson - - $ make rpm - -If not sure how to use, find the top-level documentation with: - - $ man nvme -Or find a short summary with: - - $ nvme help - -## Distro Support - -### Alpine Linux +### Configuring -nvme-cli is tested on Alpine Linux 3.3. Install it using: - - # apk update && apk add nvme-cli nvme-cli-doc - -if you just use the device you're after, it will work flawless. -``` -# nvme smart-log /dev/nvme0 -Smart Log for NVME device:/dev/nvme0 namespace-id:ffffffff -critical_warning : 0 -temperature : 49 C -available_spare : 100% -``` +In case libnvme is not installed on the system, it possible to use meson's +fallback feature to resolve the dependency. -### Arch Linux + $ meson setup --force-fallback-for=libnvme .build -nvme-cli is available in the `[community]` repository. It can be installed with: +If the libnvme is already installed on the system meson is using pkg-config to +find the dependency. In this case a plain setup call is enough: - # pacman -S nvme-cli + $ meson setup .build -The development version can be installed from AUR, e.g.: +With meson's --wrap-mode argument it's possible to control if the additional +dependencies should also resolved or not. The options are - $ yay -S nvme-cli-git + --wrap-mode {default,nofallback,nodownload,forcefallback,nopromote} -### Debian +Note for nvme-cli the 'default' is set to nofallback. -nvme-cli is available in Debian 9 and up. Install it with your favorite -package manager. For example: +### Building - $ sudo apt install nvme-cli + $ meson compile -C .build -### Fedora +### Installing -nvme-cli is available in Fedora 23 and up. Install it with your favorite -package manager. For example: + # meson install -C .build - $ sudo dnf install nvme-cli +### Makefile wrapper -### FreeBSD +There is a Makefile wrapper for meson for backwards compatibility -`nvme-cli` is available in the FreeBSD Ports Collection. A prebuilt binary -package can be installed with: + $ make + # make install -```console -# pkg install nvme-cli -``` +Note in this case libnvme needs to be installed by hand first. -### Gentoo +RPM build support via Makefile that uses meson -nvme-cli is available and tested in portage: -``` -$ emerge -av nvme-cli -``` + $ make rpm -### Nix(OS) +If not sure how to use, find the top-level documentation with: -The attribute is named `nvme-cli` and can e.g. be installed with: -``` -$ nix-env -f '<nixpkgs>' -iA nvme-cli -``` + $ man nvme -### openSUSE +Or find a short summary with: -nvme-cli is available in openSUSE Leap 42.2 or later and Tumbleweed. You can -install it using zypper. For example: + $ nvme help - $ sudo zypper install nvme-cli +## Distro Support -### Ubuntu +Many popular distributions (Alpine, Arch, Debian, Fedora, FreeBSD, Gentoo, +Ubuntu, Nix(OS), openSUSE, ...) and the usual package name is nvme-cli. -nvme-cli is supported in the Universe package sources for -many architectures. For a complete list try running: - ``` - rmadison nvme-cli - nvme-cli | 0.5-1 | xenial/universe | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x - nvme-cli | 0.5-1ubuntu0.2 | xenial-updates/universe | source, amd64, arm64, armhf, i386, powerpc, ppc64el, s390x - nvme-cli | 1.5-1 | bionic/universe | source, amd64, arm64, armhf, i386, ppc64el, s390x - nvme-cli | 1.5-1ubuntu1.2 | bionic-updates | source, amd64, arm64, armhf, i386, ppc64el, s390x - nvme-cli | 1.9-1 | focal/universe | source, amd64, arm64, armhf, ppc64el, riscv64, s390x - nvme-cli | 1.9-1ubuntu0.1 | focal-updates | source, amd64, arm64, armhf, ppc64el, riscv64, s390x - nvme-cli | 1.14-1 | impish | source, amd64, arm64, armhf, ppc64el, riscv64, s390x - nvme-cli | 1.16-3 | jammy | source, amd64, arm64, armhf, ppc64el, riscv64, s390x - ``` -A Debian based package for nvme-cli is currently maintained as a -Ubuntu PPA. To install nvme-cli using this approach please perform the following -steps: - 1. Perform an update of your repository list: - ``` - sudo apt-get update - ``` - 2. Get nvme-cli! - ``` - sudo apt-get install nvme-cli - ``` - 3. Test the code. - ``` - sudo nvme list - ``` - In the case of no NVMe devices you will see - ``` - No NVMe devices detected. - ``` - otherwise you will see information about each NVMe device installed - in the system. - -### OpenEmbedded/Yocto +#### OpenEmbedded/Yocto An [nvme-cli recipe](https://layers.openembedded.org/layerindex/recipe/88631/) is available as part of the `meta-openembeded` layer collection. -### Buildroot +#### Buildroot `nvme-cli` is available as [buildroot](https://buildroot.org) package. The package is named `nvme`. -### Other Distros - -TBD - ## Developers You may wish to add a new command or possibly an entirely new plug-in @@ -254,7 +179,7 @@ means if the current branch is updated via git, the subprojects/libnvme branch will not updated accordingly. To update it, either use the normal git operations or the command: - $ meson subprojects update + $ meson subprojects update ## Dependency @@ -309,3 +234,52 @@ $ git rebase master # Push your changes to github and trigger a PR $ git push -u origin fix-something ``` + +## Persistent, volatile configuration + +Persistent configurations can be stored in two different locations: either in +the file `/etc/nvme/discovery.conf` using the old style, or in the file +`/etc/nvme/config.json` using the new style. + +On the other hand, volatile configurations, such as those obtained from +third-party tools like `nvme-stats` or `blktests'` can be stored in the +`/run/nvme` directory. When using the `nvme-cli` tool, all these configurations +are combined into a single configuration that is used as input. + +The volatile configuration is particularly useful for coordinating access to the +global resources among various components. For example, when executing +`blktests` for the FC transport, the `nvme-cli` udev rules can be triggered. To +prevent interference with a test, `blktests` can create a JSON configuration +file in `/run/nvme` to inform `nvme-cli` that it should not perform any actions +trigged from the udev context. This behavior can be controlled using the +`--context` argument. + +For example a `blktests` volatile configuration could look like: + +```json +[ + { + "hostnqn": "nqn.2014-08.org.nvmexpress:uuid:242d4a24-2484-4a80-8234-d0169409c5e8", + "hostid": "242d4a24-2484-4a80-8234-d0169409c5e8", + "subsystems": [ + { + "application": "blktests", + "nqn": "blktests-subsystem-1", + "ports": [ + { + "transport": "fc", + "traddr": "nn-0x10001100aa000001:pn-0x20001100aa000001", + "host_traddr": "nn-0x10001100aa000002:pn-0x20001100aa000002" + } + ] + } + ] + } +] +``` + +Note when updating the volatile configuration during runtime, it should done in +a an atomic way. For example create a temporary file without the `.json` file +extension in `/run/nvme` and write the contents to this file. When finished use +`rename` to add the `'.json'` file name extension. This ensures nvme-cli only +sees the complete file. |