virsh-pool-define-as

Create the configuration file for a storage pool called pool_name using /var/vms as the underlying storage system

$ virsh pool-define-as --name [pool_name] --type [dir] --target [/var/vms]

virsh pool-define-as --name <string> --type <string> [--target <string>] [--source-host <string>] [--source-path <string>] [--source-dev <string>] [--source-name <string>] [--source-format <string>] [--source-auth <string>] [--source-protocol <string>] [--source-device-path <string>] [--source-adapter <string>] [--source-pool <string>] [--source-vol <string>] [--build] [--overwrite] [--print-xml] [--sparse]

--name <string>
    Specifies the unique name for the new storage pool. This name will be used to refer to the pool in other virsh commands.

--type <string>
    Defines the type of storage pool. Common types include:
dir: A simple directory on the host filesystem.
fs: A mounted filesystem.
netfs: A network-mounted filesystem (e.g., NFS, CIFS).
logical: A Logical Volume Management (LVM) volume group.
disk: A physical disk or partition.
iscsi: An iSCSI target.
scsi: A SCSI host bus adapter.
mpath: A multipath device.
rbd: A Ceph RBD volume.
gluster: A GlusterFS volume.
zfs: A ZFS filesystem or volume.

--target <string>
    The target path for the pool. Required for 'dir', 'fs', and 'netfs' types, indicating where the pool's volumes will reside.

--source-host <string>
    The hostname or IP address of the remote server for network-based pools (e.g., 'netfs', 'iscsi', 'rbd', 'gluster').

--source-path <string>
    The path on the source host for 'netfs', 'rbd', 'gluster' types, or the device path/name for 'logical', 'disk', 'iscsi', 'scsi', 'mpath', 'zfs'.

--source-dev <string>
    An alternative or additional way to specify the source device, typically for block-based types like 'logical', 'disk', 'iscsi', 'scsi', 'mpath', 'rbd', 'gluster', 'zfs'.

--source-name <string>
    The name of the iSCSI target, RBD volume name, or Gluster volume name.

--source-format <string>
    The filesystem format for 'fs' type pools (e.g., 'ext4', 'xfs').

--source-auth <string>
    Path to an XML file containing authentication credentials for 'iscsi', 'rbd', or 'gluster' pools.

--source-protocol <string>
    The protocol for 'netfs' type pools (e.g., 'nfs', 'cifs').

--source-device-path <string>
    Specifically the full path to a physical device (e.g., /dev/sdb) for 'disk' type pools.

--source-adapter <string>
    The SCSI adapter device path (e.g., /dev/sga) for 'scsi' type pools.

--source-pool <string>
    The name of the ZFS pool for 'zfs' type pools.

--source-vol <string>
    The name of the ZFS volume or dataset within the specified ZFS pool.

--build
    Immediately builds the storage pool after defining it. This is equivalent to running virsh pool-build separately.

--overwrite
    When used with --build for 'fs' type, it will format and overwrite any existing data on the specified filesystem. Use with extreme caution.

--print-xml
    Instead of defining the pool, prints the generated XML definition to standard output. This is useful for inspection or for creating XML files manually.

--sparse
    For 'logical' (LVM) type pools, creates sparse logical volumes (thinly provisioned) by default.

The virsh pool-define-as command is a powerful utility within the virsh command-line interface for libvirt. Its primary purpose is to create a definition for a new storage pool without immediately activating or building it. This allows administrators to prepare storage configurations beforehand, which can then be started or autostarted at a later time using virsh pool-start or virsh pool-autostart.

The command takes various parameters to describe the storage pool's type (e.g., directory, filesystem, network filesystem, iSCSI, LVM, ZFS, etc.) and its source location or device. By specifying these parameters directly on the command line, users avoid the need to manually craft complex XML configuration files, making the process of defining storage pools quicker and less error-prone. The generated definition is persistent across reboots until explicitly undefined, ensuring the storage resources are consistently available for virtual machines. This command is a foundational step in libvirt's storage management, enabling flexible and robust allocation of storage for virtual environments.

• The command only defines the pool, creating its persistent XML configuration. It does not automatically start the pool or make it active. Use virsh pool-start <name> to activate it.
• Admin privileges (root or sudo) are typically required to define storage pools, as it involves system-level resource management.
• Careful use of --overwrite is crucial as it can lead to data loss on the target device if used incorrectly with 'fs' type pools.
• The specific source-* parameters required vary significantly based on the --type of the storage pool. Refer to libvirt documentation for detailed type-specific requirements.

When you use virsh pool-define-as, libvirt internally generates an XML definition file for the storage pool. This XML file is then stored persistently, usually in /etc/libvirt/storage/ on Linux systems. You can view this generated XML using virsh pool-dumpxml <pool_name> or by using the --print-xml option with pool-define-as. Understanding the structure of this XML can be beneficial for advanced configurations or troubleshooting.

The variety of storage pool types supported by virsh pool-define-as allows libvirt to manage virtually any storage backend for virtual machines. For instance, 'dir' and 'fs' types are suitable for simple file-based storage, while 'logical' (LVM), 'iscsi', 'rbd' (Ceph), and 'gluster' are used for enterprise-grade, shared, or high-performance storage solutions. Choosing the correct type depends on the specific storage infrastructure and performance requirements of your virtual machines.

libvirt itself, which virsh interacts with, has been under active development since 2005, providing a stable and robust virtualization management layer. The storage pool management features, including the ability to define pools from the command line, have evolved as libvirt's capabilities expanded to support diverse storage backends beyond basic file-based storage. Commands like pool-define-as were introduced to simplify the creation of these complex storage definitions, abstracting away the need for users to manually write intricate XML files, thus improving usability and reducing potential configuration errors. Its development reflects libvirt's continuous effort to provide comprehensive and user-friendly management of virtualized environments.

virsh(1), virsh pool-start(1), virsh pool-autostart(1), virsh pool-destroy(1), virsh pool-undefine(1), virsh pool-list(1), virsh pool-edit(1), virsh pool-build(1)