The ndctl utility is used to manage the libnvdimm (non-volatile memory device) sub-system in the Linux Kernel. It is required for several Persistent Memory Developer Kit (PMDK) features if compiling from source. If ndctl is not available, the PMDK may not build all components and features. This page describes how to install ndctl using the Linux package repository or compiled from source code downloaded from the ndctl GitHub repository.

Microsoft Windows users can read the NVM documentation.

Installing NDCTL Packages on Linux

The ndctl utility is available in several Linux distro repositories.

Fedora
RHEL & CentOS
SLES & OpenSUSE
Ubuntu

1) Query the repository to identify if ndctl is delivered:

Fedora 21 or earlier

yum search ndctl

Fedora 22 or later

dnf repoquery ndctl

2) Install the ndctl utility

Fedora 21 or earlier

yum install ndctl

Fedora 22 or later

dnf install ndctl

The ndctl package is available on CentOS and RHEL 7.0 or later.

1) Query the repository to identify if ndctl is delivered:

yum search ndctl

2) Install the ndctl package

$ yum install ndctl

1) Query the repository to identify if ndctl is delivered:

$ zypper search ndctl

2) Install the ndctl package

$ zypper install ndctl

The ndctl package is available on Ubuntu 18.10 (Cosmic Cuttlefish) or later.

1) Query the repository to identify if ndctl is delivered using either the aptitude, apt-cache, or apt utilities

$ aptitude search ndctl
$ apt-cache search ndctl
$ apt search ndctl

2) Install the ndctl package

$ apt-get install ndctl

Installing NDCTL from Source on Linux

Utility library for managing the libnvdimm (non-volatile memory device) sub-system in the Linux kernel and is not available for Windows.

If your system is behind a firewall and requires a proxy to access the Internet, configure dnf to use a proxy. Edit /etc/dnf/dnf.conf and add the following line

proxy=http://url:port/

You must set a complete URL, including the TCP port number. If your proxy server requires a username and password, specify these by adding following two settings in dnf.conf file.

proxy_username=YOUR-PROXY-USERNAME-HERE
proxy_password=YOUR-SUPER-secrete-PASSWORD-HERE

1. Install Pre-Requisites

There are a number of packages required for the build steps that may not be installed by default. For information about the required packages, see the "BuildRequires:" lines in ndctl.spec.in.

https://github.com/pmem/ndctl/blob/master/ndctl.spec.in

To successfully compile ndctl from source with documentation, the following packages are required

  • autoconf

  • automake

  • asciidoc

  • bash-completion

  • doxygen

  • gcc

  • gcc-c++

  • git

  • glib2

  • glib2-devel

  • graphviz

  • json-c-devel

  • kmod

  • kmod-devel

  • libfabric

  • libfabric-devel

  • libtool

  • libudev-devel

  • libuuid-devel

  • ncurses

  • pandoc

  • pkg-config

  • rubygem-asciidoctor (asciidoctor)

  • xmlto

To install these prerequisites, use:

Fedora
RHEL & CentOS
SLES & OpenSUSE
Ubuntu

Fedora 21 or earlier

sudo yum install -y git gcc gcc-c++ autoconf automake asciidoc asciidoctor xmlto libtool pkg-config glib2 glib2-devel libfabric libfabric-devel doxygen graphviz pandoc ncurses kmod kmod-devel libudev-devel libuuid-devel json-c-devel

Fedora 22 or later

sudo dnf install -y git gcc gcc-c++ autoconf automake asciidoc asciidoctor xmlto libtool pkg-config glib2 glib2-devel libfabric libfabric-devel doxygen graphviz pandoc ncurses kmod kmod-devel libudev-devel libuuid-devel json-c-devel

Some of the required packages can be found in the EPEL repository. Verify the EPEL repository is active:

$ yum repolist

If the EPEL repository is not listed, install and activate it using:

$ sudo yum -y install epel-release

Install the required packages

$ sudo yum install -y git gcc gcc-c++ autoconf automake asciidoc asciidoctor bash-completion xmlto libtool pkg-config glib2 glib2-devel libfabric libfabric-devel doxygen graphviz pandoc ncurses kmod kmod-devel libudev-devel libuuid-devel json-c-devel rubygem-asciidoctor
$ sudo zypper install -y git gcc gcc-c++ autoconf automake asciidoc xmlto libtool pkg-config glib2 glib2-devel libfabric libfabric-devel doxygen graphviz pandoc ncurses kmod kmod-devel libudev-devel libuuid-devel json-c-devel rubygem-asciidoctor
$ sudo apt-get install -y git gcc gcc-c++ autoconf automake asciidoc asciidoctor xmlto libtool pkg-config glib2 glib2-devel libfabric libfabric-devel doxygen graphviz pandoc ncurses kmod kmod-devel libudev-devel libuuid-devel json-c-devel

2. Clone the GitHub Repository

  1. If you're behind a company proxy, configure git to work with your proxy server first. The following configures a HTTP and HTTPS proxy for all users. Refer to the git-config documentation for more options and information.

$ git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port
$ git config --global https.proxy https://proxyUsername:proxyPassword@proxy.server.com:port

2. Create a working directory to clone the ndctl GitHub repository to, eg: 'downloads'

$ sudo mkdir /downloads
$ sudo chmod +w /downloads

3. Clone the repository:

$ cd /downloads
$ sudo git clone https://github.com/pmem/ndctl
$ cd ndctl

3. Build

The following configures ndctl to be installed in to the /usr/local directory.

$ ./autogen.sh
$ ./configure CFLAGS='-g -O2' --prefix=/usr/local --sysconfdir=/etc --libdir=/usr/local/lib64
$ make

Note: If you want to compile with a different compiler other than gcc, you have to provide the CC and CXX environment variables. For example:

$ sudo make CC=clang CXX=clang++

These variables are independent and setting CC=clang does not set CXX=clang++.

To compile ndctl with debugging, use the --enable-debug option:

$ ./autogen.sh
$ ./configure CFLAGS='-g -O2' --enable-debug --prefix=/usr/local --sysconfdir=/etc --libdir=/usr/local/lib64
$ make

For a full list of configure options use:

$ ./configure --help

4. Install

Once ndctl has successfully been compiled, it can be installed using the following:

$ sudo make install

5. Build and Run Unit Tests (Optional)

The unit tests run by make check require the nfit_test.ko module to be loaded. To build and install nfit_test.ko:

  1. Obtain the kernel source. For example, git clone -b libnvdimm-for-next git://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git

  2. Skip to step 3 if the kernel version is >= v4.8. Otherwise, for kernel versions < v4.8, configure the kernel to make some memory available to CMA (contiguous memory allocator). This will be used to emulate DAX. CONFIG_DMA_CMA=y CONFIG_CMA_SIZE_MBYTES=200 or cma=200M on the kernel command line.

  3. Compile the libnvdimm sub-system as a module, make sure "zone device" memory is enabled, and enable the btt, pfn, and dax features of the sub-system: CONFIG_X86_PMEM_LEGACY=m CONFIG_ZONE_DEVICE=y CONFIG_LIBNVDIMM=m CONFIG_BLK_DEV_PMEM=m CONFIG_ND_BLK=m CONFIG_BTT=y CONFIG_NVDIMM_PFN=y CONFIG_NVDIMM_DAX=y CONFIG_DEV_DAX_PMEM=m

  4. Build and install the unit test enabled libnvdimm modules in the following order. The unit test modules need to be in place prior to the depmod that runs during the final modules_install make M=tools/testing/nvdimm sudo make M=tools/testing/nvdimm modules_install sudo make modules_install

  5. Now run make check in the ndctl source directory, or ndctl test, if ndctl was built with --enable-test.

Troubleshooting

The unit tests will validate that the environment is set up correctly before they try to run. If the platform is misconfigured, i.e. the unit test modules are not available, or the test versions of the modules are superseded by the "in-tree/production" version of the modules make check will skip tests and report a message like the following in test/test-suite.log:

SKIP: libndctl ============== test/init: nfit_test_init: nfit.ko: appears to be production version: /lib/modules/4.8.8-200.fc24.x86_64/kernel/drivers/acpi/nfit/nfit.ko.xz __ndctl_test_skip: explicit skip test_libndctl:2684 nfit_test unavailable skipping tests

If the unit test modules are indeed available in the modules 'extra' directory the default depmod policy can be overridden by adding a file to /etc/depmod.d with the following contents: override nfit * extra override device_dax * extra override dax_pmem * extra override libnvdimm * extra override nd_blk * extra override nd_btt * extra override nd_e820 * extra override nd_pmem * extra

The nfit_test module emulates pmem with memory allocated via vmalloc(). One of the side effects is that this breaks 'physically contiguous' assumptions in the driver. Use the --align=4K option to ndctl create-namespace to avoid these corner case scenarios.

Using ndctl

To learn how to use the ndctl utility, continue to the NDCTL Users Guide within this collection.

Additional Documentation

See the latest documentation for the NVDIMM kernel sub-system here: https://git.kernel.org/cgit/linux/kernel/git/nvdimm/nvdimm.git/tree/Documentation/nvdimm/nvdimm.txt?h=libnvdimm-for-next