virsh-pool-undefine

Delete the configuration for the storage pool specified name or UUID (determine using virsh pool-list)

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

virsh pool-undefine <pool-name>

The virsh pool-undefine command removes the definition of a storage pool from the libvirt daemon's configuration. This action makes libvirt "forget" about the pool, meaning it will no longer manage or display it in its list of pools. It is crucial to understand that pool-undefine does not delete or modify the actual data residing on the storage device or path associated with the pool; the underlying storage remains untouched. Before a pool can be undefined, it must be in an inactive (destroyed) state. This command is typically used when you no longer want libvirt to manage a particular storage location, perhaps because you are decommissioning it, migrating it, or managing it manually outside of libvirt. It requires one mandatory argument: the name of the storage pool to be undefined.

The storage pool must be inactive (stopped) before it can be undefined. Use virsh pool-destroy <pool-name> first if it's currently active.
This command does not delete any data on the underlying storage. The data remains intact. To delete the data, you would typically use virsh pool-delete (if supported for the pool type and contents) or manually delete the storage after undefining.
Any virtual machines that were configured to use storage volumes from this pool will no longer be able to access those volumes via libvirt once the pool is undefined. You might need to update or redefine those VMs' storage configurations.

It is crucial to differentiate virsh pool-undefine from virsh pool-delete. Undefine merely removes the pool's definition from libvirt's configuration, leaving the underlying data untouched. Delete, on the other hand, attempts to remove the pool's definition and any data or devices associated with it (e.g., deleting LVM volumes, unmounting filesystems). The delete operation is often more destructive and not supported for all pool types or configurations. Generally, the workflow is to destroy (deactivate) a pool, then undefine it. If you also wish to remove the underlying storage, you would then manually remove it or, in specific cases, use pool-delete.

The virsh command-line tool is the primary interface for managing libvirt virtualization. Storage pool management, including the pool-undefine command, has been a core feature of libvirt since its early versions. Its development has focused on providing a standardized and abstracted way to manage various storage backends for virtual machines, allowing users to configure and manipulate different storage types (e.g., directories, LVM, NFS, iSCSI) through a consistent interface. This command reflects libvirt's design principle of separating configuration from data lifecycle management.

virsh(1), virsh pool-define(1), virsh pool-list(1), virsh pool-start(1), virsh pool-destroy(1), virsh pool-delete(1), virsh pool-info(1)