virsh-pool-build

Build the storage pool specified by name or UUID (determine using virsh pool-list)

$ virsh pool-build --pool [name|uuid]

virsh pool-build <pool-name> [--all]

<pool-name>
    The name of the storage pool to be built or formatted. This pool must already be defined in libvirt.

--all
    Builds all storage pools that are currently defined but not yet built. Use with caution as this can be a destructive operation for multiple pools.

The virsh pool-build command is used to format or 'build' a defined libvirt storage pool, making it ready for use. This operation is typically performed after a storage pool has been defined using virsh pool-define (or virsh pool-create with a definition) but before it is started (virsh pool-start).

The 'build' operation varies depending on the type of storage pool. For 'dir' or 'fs' type pools, it might involve creating the necessary directory structure or formatting the underlying block device (if specified to be formatted during definition). For other pool types like 'iscsi' or 'logical', it prepares the pool for volume creation. It's crucial to understand that pool-build can be a destructive operation, potentially erasing data on the target storage if it involves formatting.

This command is a critical step in the lifecycle of a libvirt storage pool, ensuring the storage is properly initialized and accessible for creating and managing virtual disk images (volumes).

Data Loss: The pool-build command, especially for 'dir' or 'fs' type pools that involve formatting, can be a destructive operation. Ensure you have backed up any necessary data before proceeding, as it may erase existing content on the target storage.
Pre-requisite: The pool must first be defined using virsh pool-define or created with a definition, before it can be built.
Purpose: This command initializes the pool for libvirt's use, but it does not necessarily create the underlying physical storage (e.g., a partition or LVM volume). That typically needs to be done beforehand.

The exact action performed by pool-build depends on the type of storage pool being built. For example:

• 'dir' type: If the target directory does not exist, it will be created. If specified in the definition XML, it might also format an underlying block device.
• 'fs' type: If configured to format a device, it will perform the filesystem creation (e.g., mkfs.ext4) on the specified underlying device.
• 'logical' (LVM) type: It prepares the LVM volume group for creating logical volumes within it, typically without formatting the VG itself.
• 'iscsi' or 'rbd' (Ceph) type: These typically don't involve a 'build' step in the same way, as the underlying storage is already managed externally. The 'build' operation for these types primarily ensures libvirt can connect and manage them.

The virsh command-line utility is the primary interface for managing libvirt virtualization. libvirt itself was initially released in 2005 and has evolved significantly to become a standard management layer for various hypervisors. The storage pool management capabilities, including pool-build, have been a core part of libvirt's functionality, providing robust ways to manage persistent storage for virtual machines since their early implementations.

virsh(1), virsh pool-define(1), virsh pool-create(1), virsh pool-start(1), virsh pool-list(1), virsh pool-destroy(1), libvirt(7)