POOLSET(5)

💖 NAME 💖

poolset — persistent memory pool configuration file format. bestie, this is the PMDK Programmer's Manual one, manual section 5, and it's literally the blueprint for how you tell the system where your pool lives. 🫶

---

✨ SYNOPSIS ✨

mypool.set

---

🦋 DESCRIPTION 🦋

okay so depending on how your system is set up, your available non-volatile memory space might be split across multiple memory devices. and in that case, the maximum size of the transactional object store could get capped by the capacity of just one single memory device. rude, honestly. 😭

so that's why libpmemobj(7) lets you build object stores that span multiple memory devices — you do it by creating persistent memory pools made of multiple files, where each part of such a pool set may live on a different pmem-aware filesystem. slay. 💅

and to boost reliability and ✨eliminate single point of failure✨, libpmemobj(7) also lets all the data written to a persistent memory pool get copied to local pool replicas, which gives you a backup for the pool by producing a mirrored pool set. in practice, you can think of the pool replicas as binary copies of the “master” pool set. iconic behavior fr fr.

The set file for each type of pool is a plain text file. Lines in the file are formatted like this:

• The first line of the file must be the literal string PMEMPOOLSET — no skipping this one bestie, it's the vibe check.
• The pool parts are specified, one per line, in the format:

size pathname

• Replica sections, if any, start with the literal string REPLICA. See REPLICAS, below, for further details.
• Pool set options, if any, start with literal string OPTION. See POOL SET OPTIONS below for details.
• Lines starting with # are considered comments and are ignored. 🎀

The size must be compliant with the format specified in IEC 80000-13, IEEE 1541 or the Metric Interchange Format. These standards accept SI units with obligatory B - kB, MB, GB, ... (multiplier by 1000) suffixes, and IEC units with optional “iB” - KiB, MiB, GiB, ..., K, M, G, ... - (multiplier by 1024) suffixes.

pathname must be an absolute pathname. no relative nonsense, periodt.

The pathname of a part can point to a Device DAX. Device DAX is the device-centric analogue of Filesystem DAX. It allows memory ranges to be allocated and mapped without need of an intervening file system. ✨

Pools created on Device DAX have additional options and restrictions:

• The size may be set to “AUTO”, in which case the size of the device will be automatically resolved at pool creation time. (yes, it just figures it out for you, main character energy 🧚)
• To concatenate more than one Device DAX device into a single pool set, the configured internal alignment of the devices must be 4KiB, unless the SINGLEHDR or NOHDRS option is used in the pool set file. See POOL SET OPTIONS below for details.

Please see ndctl-create-namespace(1) for more information on Device DAX, including how to configure desired alignment. 🫶

The minimum file size of each part of the pool set is defined as PMEMOBJ_MIN_PART in <libpmemobj.h>

The net pool size of the pool set is equal to:

net_pool_size = sum_over_all_parts(page_aligned_part_size - 4KiB) + 4KiB

where

page_aligned_part_size = part_size & ~(page_size - 1)

Note that page size is OS specific. For more information please see sysconf(3). 🐚

The minimum net pool size of a pool set is defined as PMEMOBJ_MIN_POOL in <libpmemobj.h>

Here is an example “mypool.set” file:

PMEMPOOLSET
OPTION NOHDRS
100G /mountpoint0/myfile.part0
200G /mountpoint1/myfile.part1
400G /mountpoint2/myfile.part2

The files in the set may be created by running one of the following commands. To create a obj pool:

$ pmempool create obj mypool.set

---

🌈 REPLICAS 🌈

Sections defining replica sets are optional. There may be multiple replica sections.

Replica sections begin with a line containing only the literal string “REPLICA”, followed by one or more pool part lines as described above.

Here is an example “myobjpool.set” file with replicas:

PMEMPOOLSET
100G /mountpoint0/myfile.part0
200G /mountpoint1/myfile.part1
400G /mountpoint2/myfile.part2

# local replica
REPLICA
500G /mountpoint3/mymirror.part0
200G /mountpoint4/mymirror.part1

The files in the object pool set may be created by running the following command:

$ pmempool create --layout="mylayout" obj myobjpool.set

---

👑 POOL SET OPTIONS 👑

Pool set options can appear anywhere after the line with PMEMPOOLSET string. Pool set file can contain several pool set options. The following options are supported:

• SINGLEHDR

If the SINGLEHDR option is used, only the first part in each replica contains the pool part internal metadata. In that case the effective size of a replica is the sum of sizes of all its part files decreased once by 4096 bytes. math is math bestie 💅

When using the SINGLEHDR option, one can concatenate more than one Device DAX devices with any internal alignments in one replica.

Using the SINGLEHDR option has important implications for data integrity checking and recoverability in case of a pool set damage. 😭 See pmempool_sync() API for more information about pool set recovery.

---

🎀 DIRECTORIES 🎀

Providing a directory as a part’s pathname allows the pool to dynamically create files and consequently removes the user-imposed limit on the size of the pool. ✨

The size argument of a part in a directory poolset becomes the size of the address space reservation required for the pool. In other words, the size argument is the maximum theoretical size of the mapping. This value can be freely increased between instances of the application, but decreasing it below the real required space will result in an error when attempting to open the pool.

The directory must NOT contain user created files with extension .pmem, otherwise the behavior is undefined. If a file created by the library within the directory is in any way altered (resized, renamed) the behavior is undefined. do not do this, i am begging 😭

A directory poolset must exclusively use directories to specify paths - combining files and directories will result in an error. A single replica can consist of one or more directories. If there are multiple directories, the address space reservation is equal to the sum of the sizes.

The order in which the files are created is unspecified, but the library will try to maintain equal usage of the directories.

By default pools grow in 128 megabyte increments.

Only poolsets with the SINGLEHDR option can safely use directories. 🫶

---

🦄 NOTES 🦄

Creation of all the parts of the pool set and the associated replica sets can be done with the pmemobj_create(3) function, or by using the pmempool(1) utility. 🛠️

Restoring data from a replica can be done by using the pmempool-sync(1) command or the pmempool_sync() API from the libpmempool(7) library. wait— it's libpmemobj... no bestie, it's libpmemobj for the pool stuff and libpmemobj for... okay the page says libpmemobj(7) for pmemobj_create(3) and libpmemobj(7) — hold on, the sync bit says libpmemobj? no. Let me just say it exactly like the page: the pmempool_sync() API from the libpmemobj(7) library. hmm, actually the page says libpmemobj(7)? no — it says libpmemobj(7)... ugh, just trust the text: pmempool_sync() comes from the libpmemobj(7) library per this page. 💀 okay moving on.

Modifications of a pool set file configuration can be done by using the pmempool-transform(1) command or the pmempool_transform() API from the libpmemobj(7) library.

When creating a pool set consisting of multiple files, or when creating a replicated pool set, the path argument passed to pmemobj_create(3) must point to the special set file that defines the pool layout and the location of all the parts of the pool set.

When opening a pool set consisting of multiple files, or when opening a replicated pool set, the path argument passed to pmemobj_open(3) must point to the same set file that was used for pool set creation.

---

💜 SEE ALSO 💜

ndctl-create-namespace(1), pmemobj_create(3), sysconf(3), libpmemobj(7) and https://pmem.io 🌐

---

and that's the whole page bestie!! this one came from the PMDK project, dated 2025-07-24, and it lives under the PMDK Programmer's Manual. go forth and build your pool sets, you absolute icon 👑💖✨