virsh
From Gentoo Wiki
Resources
virsh is a CLI-based virtualization management toolkit.
The program is used to create, pause, and shutdown domains. It also list current domains.
Libvirt is a C toolkit to interact with the virtualization capabilities of recent versions of Linux (and other OSes).
Libvirt (and virsh) currently supports QEMU, LXC, Xen, KVM, OpenVZ, VirtualBox and VMware ESX.
Installation
See libvirt for installation of virsh.
System user/group
For non-root usage of virsh, user must have group name libvirt as part of its supplemental group. Defined by acct-group/libvirt; evoked by app-emulation/libvirt package.
Configuration
Environment variables
A list of all environment variables that are read and checked by the virsh command:
- DISPLAY - for virtualbox-only
- DNSMASQ_CLIENT_ID - Used with dnsmasqd
- DNSMASQ_IAID - Used with dnsmasqd
- DNSMASQ_INTERFACE - Used with dnsmasqd
- DNSMASQ_LEASE_EXPIRES - Used with dnsmasqd
- DNSMASQ_OLD_HOSTNAME - Used with dnsmasqd
- DNSMASQ_SERVER_DUID - Used with dnsmasqd
- DNSMASQ_SUPPLIED_HOSTNAME - Used with dnsmasqd
- LIBVIRT_ADMIN_DEFAULT_URI - administration
- LIBVIRT_AUTH_FILE - authentication
- LIBVIRT_AUTOSTART
- LIBVIRT_DEBUG
- LIBVIRT_DEFAULT_URI
- LIBVIRT_DIR_OVERRIDE
- LIBVIRT_GNUTLS_DEBUG
- LIBVIRT_LIBSSH_DEBUG
- LIBVIRT_LOG_FILTERS
- LIBVIRT_LOG_OUTPUTS
- LISTEN_PID - For systemd only.
- LISTEN_FDS - For systemd only.
- NOTIFY_SOCKET - for systemd-only.
- QEMU_AUDIO_DRV
- SDL_AUDIODRIVER
- VBOX_APP_HOME - for virtualbox-only
- VIR_BRIDGE_NAME - Bridging
- VIRSH_DEFAULT_CONNECT_URI
- VIRTD_PATH
Files
Files that are read by the host-side OS virsh command:
- /etc/libvirt/hooks/
- /etc/libvirt/libvirt-admin.conf
- /etc/libvirt/libvirt.conf
- /etc/libvirt/libvirtd.conf
- /etc/libvirt/libxl.conf
- /etc/libvirt/libxl-lockd.conf
- /etc/libvirt/libxl-sanlock.conf
- /etc/libvirt/lxc.conf
- /etc/libvirt/nwfilter/
- /etc/libvirt/secrets/
- /etc/libvirt/storage/
- /etc/libvirt/virtlockd.conf
- /etc/libvirt/virtlogd.conf
- /proc/cgroups
- /proc/cpuinfo
- /proc/modules
- /proc/mounts
- /proc/net/dev
- /proc/stat
- /proc/sys/ipv4/ip_forward
- /proc/sys/ipv6/conf/all/forwarding
- /proc/sys/ipv6/conf/%s/%s
- /proc/vz/vestat - Only with openvz
- /sys/class/fc_host/host0
- /sys/class/fc_remote_ports
- /sys/class/scsi_host
- /sys/devices/system
- /sys/devices/system/%s/cpu/online
- /sys/devices/system/cpu/online
- /sys/devices/system/node/node0/access1
- /sys/devices/system/node/node0/meminfo
- /sys/devices/system/node/node0/memory_side_cache
- /sys/devices/system/node/online
- /sys/fs/resctrl
- /sys/fs/resctrl/info/%s/num_closids
- /sys/fs/resctrl/%s/schemata
- /sys/fs/resctrl/info/%s/min_cbm_bits
- /sys/fs/resctrl/info/L3_MON
- /sys/fs/resctrl/info/L3_MON/num_rmids
- /sys/fs/resctrl/info/MB/bandwidth_gran
- /sys/fs/resctrl/info/MB/min_bandwidth
- /sys/fs/resctrl/info/MB/num_closids
- /sys/kernel/mm/ksm
- /sys/kernel/mm/transparent_hugepage/hpage_pmd_size
- /var/lib/libvirt/boot
- /var/lib/libvirt/dnsmasq
- /var/lib/libvirt/images
- /var/lib/libvirt/sanlock
User permissions
To use virsh as a non-root user, ensure each user has been added to the libvirt group:
root #gpasswd -a <user> libvirtSee libvirt configuration for more setup on enabling user to use the virsh command.
Service
virsh requires libvirtd daemon to be started. It's also a good idea to enabled in order to be around once we restart the system, see libvirt service for more commands.
A quick test to see if the daemon is up and running from the command line in one of three ways:
libvirtd service - status by CLI
root #virsh list --allvirsh list --all Id Name State --------------------------- 16 gentoo running - gentoo2 shut off
libvirtd service - status by explicit channel
root #virsh -c qemu:///system list --allvirsh -c qemu:///system list --all Id Name State --------------------------- 16 gentoo running - gentoo2 shut off
libvirtd service - status by environment variable
Define VIRSH_DEFAULT_CONNECT_URI to "qemu:///system", then
root #virsh list --allVIRSH_DEFAULT_CONNECT_URI="qemu:///system" virsh list --all Id Name State --------------------------- 16 gentoo running - gentoo2 shut off
Networking
As a default, virsh uses UNIX socket to communicate with libvirtd.
Usage
The virsh can be checked by running:
root #virsh nodeinfoCPU model: x86_64 CPU(s): 4 CPU frequency: 1600 MHz CPU socket(s): 1 Core(s) per socket: 4 Thread(s) per core: 1 NUMA cell(s): 1 Memory size: 16360964 KiB
The virsh can check communication with libvirtd daemon via Unix socket by running:
root #virsh sysinfo<sysinfo type='smbios'>
<bios>
<entry name='vendor'>Dell Inc.</entry>
<entry name='version'>A22</entry>
<entry name='date'>11/29/2018</entry>
<entry name='release'>4.6</entry>
</bios>
<system>
<entry name='manufacturer'>Dell Inc.</entry>
<entry name='product'>OptiPlex 3010</entry>
<entry name='version'>01</entry>
<entry name='serial'>JRJ0SW1</entry>
<entry name='uuid'>4c4c4544-0052-4a10-8030-cac04f535731</entry>
<entry name='sku'>OptiPlex 3010</entry>
<entry name='family'>Not Specified</entry>
</system>
<baseBoard>
<entry name='manufacturer'>Dell Inc.</entry>
<entry name='product'>042P49</entry>
<entry name='version'>A00</entry>
<entry name='serial'>/JRJ0SW1/CN701632BD05R5/</entry>
<entry name='asset'>Not Specified</entry>
<entry name='location'>Not Specified</entry>
</baseBoard>
<chassis>
<entry name='manufacturer'>Dell Inc.</entry>
<entry name='version'>Not Specified</entry>
<entry name='serial'>JRJ0SW1</entry>
<entry name='asset'>Not Specified</entry>
<entry name='sku'>To be filled by O.E.M.</entry>
</chassis>
<processor>
<entry name='socket_destination'>CPU 1</entry>
<entry name='type'>Central Processor</entry>
<entry name='family'>Core i5</entry>
<entry name='manufacturer'>Intel(R) Corporation</entry>
<entry name='signature'>Type 0, Family 6, Model 58, Stepping 9</entry>
<entry name='version'>Intel(R) Core(TM) i5-3470 CPU @ 3.20GHz</entry>
<entry name='external_clock'>100 MHz</entry>
<entry name='max_speed'>3200 MHz</entry>
<entry name='status'>Populated, Enabled</entry>
<entry name='serial_number'>Not Specified</entry>
<entry name='part_number'>Fill By OEM</entry>
</processor>
<memory_device>
<entry name='size'>8 GB</entry>
<entry name='form_factor'>DIMM</entry>
<entry name='locator'>DIMM1</entry>
<entry name='bank_locator'>Not Specified</entry>
<entry name='type'>DDR3</entry>
<entry name='type_detail'>Synchronous</entry>
<entry name='speed'>1600 MT/s</entry>
<entry name='manufacturer'>8C26</entry>
<entry name='serial_number'>00000000</entry>
<entry name='part_number'>TIMETEC-UD3-1600</entry>
</memory_device>
<memory_device>
<entry name='size'>8 GB</entry>
<entry name='form_factor'>DIMM</entry>
<entry name='locator'>DIMM2</entry>
<entry name='bank_locator'>Not Specified</entry>
<entry name='type'>DDR3</entry>
<entry name='type_detail'>Synchronous</entry>
<entry name='speed'>1600 MT/s</entry>
<entry name='manufacturer'>8C26</entry>
<entry name='serial_number'>00000000</entry>
<entry name='part_number'>TIMETEC-UD3-1600</entry>
</memory_device>
<oemStrings>
<entry>Dell System</entry>
<entry>1[0585]</entry>
<entry>3[1.0]
</entry>
<entry>12[www.dell.com]
</entry>
<entry>14[1]</entry>
<entry>15[11]</entry>
</oemStrings>
</sysinfo>
Checking domain
Guest domains maintained by virt-manager can be checked by doing:
root #virsh list --allId Name State -------------------------------------- 1 gentoo running
Checking networking
Network interfaces maintained by virt-manager can be checked by running:
root #virsh net-list --allName State Autostart Persistent ---------------------------------------------- default active yes yes
Checking storage pools
Storage pools maintained by virt-manager can be checked by executing:
root #virsh pool-list --allName State Autostart --------------------------------- default active yes Downloads active yes
List available commands
In case the mind slips, the group of list-related options can be obtained by doing:
root #virsh help | grep list get-user-sshkeys list authorized SSH keys for given user (via agent)
domblklist list all domain blocks
domiflist list all domain virtual interfaces
list list domains
checkpoint-list List checkpoints for a domain
iface-list list physical host interfaces
nwfilter-list list network filters
nwfilter-binding-list list network filter bindings
net-list list networks
net-port-list list network ports
nodedev-list enumerate devices on this host
secret-list list secrets
snapshot-list List snapshots for a domain
pool-list list pools
vol-list list vols
Then you can add the --help option for more detailed options specific to, for example, the iface-list command:
user $virsh iface-list --help NAME
iface-list - list physical host interfaces
SYNOPSIS
iface-list [--inactive] [--all]
DESCRIPTION
Returns list of physical host interfaces.
OPTIONS
--inactive list inactive interfaces
--all list inactive & active interfaces
Invocation
user $virsh --help# virsh --help
virsh [options]... [<command_string>]
virsh [options]... <command> [args...]
options:
-c | --connect=URI hypervisor connection URI
-d | --debug=NUM debug level [0-4]
-e | --escape <char> set escape sequence for console
-h | --help this help
-k | --keepalive-interval=NUM
keepalive interval in seconds, 0 for disable
-K | --keepalive-count=NUM
number of possible missed keepalive messages
-l | --log=FILE output logging to file
-q | --quiet quiet mode
-r | --readonly connect readonly
-t | --timing print timing information
-v short version
-V long version
--version[=TYPE] version, TYPE is short or long (default short)
commands (non interactive mode):
Domain Management (help keyword 'domain')
attach-device attach device from an XML file
attach-disk attach disk device
attach-interface attach network interface
autostart autostart a domain
blkdeviotune Set or query a block device I/O tuning parameters.
blkiotune Get or set blkio parameters
blockcommit Start a block commit operation.
blockcopy Start a block copy operation.
blockjob Manage active block operations
blockpull Populate a disk from its backing image.
blockresize Resize block device of domain.
change-media Change media of CD or floppy drive
console connect to the guest console
cpu-stats show domain cpu statistics
create create a domain from an XML file
define define (but don't start) a domain from an XML file
desc show or set domain's description or title
destroy destroy (stop) a domain
detach-device detach device from an XML file
detach-device-alias detach device from an alias
detach-disk detach disk device
detach-interface detach network interface
domdisplay domain display connection URI
domfsfreeze Freeze domain's mounted filesystems.
domfsthaw Thaw domain's mounted filesystems.
domfsinfo Get information of domain's mounted filesystems.
domfstrim Invoke fstrim on domain's mounted filesystems.
domhostname print the domain's hostname
domid convert a domain name or UUID to domain id
domif-setlink set link state of a virtual interface
domiftune get/set parameters of a virtual interface
domjobabort abort active domain job
domjobinfo domain job information
domname convert a domain id or UUID to domain name
domrename rename a domain
dompmsuspend suspend a domain gracefully using power management functions
dompmwakeup wakeup a domain from pmsuspended state
domuuid convert a domain name or id to domain UUID
domxml-from-native Convert native config to domain XML
domxml-to-native Convert domain XML to native config
dump dump the core of a domain to a file for analysis
dumpxml domain information in XML
edit edit XML configuration for a domain
event Domain Events
get-user-sshkeys list authorized SSH keys for given user (via agent)
inject-nmi Inject NMI to the guest
iothreadinfo view domain IOThreads
iothreadpin control domain IOThread affinity
iothreadadd add an IOThread to the guest domain
iothreadset modifies an existing IOThread of the guest domain
iothreaddel delete an IOThread from the guest domain
send-key Send keycodes to the guest
send-process-signal Send signals to processes
lxc-enter-namespace LXC Guest Enter Namespace
managedsave managed save of a domain state
managedsave-remove Remove managed save of a domain
managedsave-edit edit XML for a domain's managed save state file
managedsave-dumpxml Domain information of managed save state file in XML
managedsave-define redefine the XML for a domain's managed save state file
memtune Get or set memory parameters
perf Get or set perf event
metadata show or set domain's custom XML metadata
migrate migrate domain to another host
migrate-setmaxdowntime set maximum tolerable downtime
migrate-getmaxdowntime get maximum tolerable downtime
migrate-compcache get/set compression cache size
migrate-setspeed Set the maximum migration bandwidth
migrate-getspeed Get the maximum migration bandwidth
migrate-postcopy Switch running migration from pre-copy to post-copy
numatune Get or set numa parameters
qemu-attach QEMU Attach
qemu-monitor-command QEMU Monitor Command
qemu-monitor-event QEMU Monitor Events
qemu-agent-command QEMU Guest Agent Command
guest-agent-timeout Set the guest agent timeout
reboot reboot a domain
reset reset a domain
restore restore a domain from a saved state in a file
resume resume a domain
save save a domain state to a file
save-image-define redefine the XML for a domain's saved state file
save-image-dumpxml saved state domain information in XML
save-image-edit edit XML for a domain's saved state file
schedinfo show/set scheduler parameters
screenshot take a screenshot of a current domain console and store it into a file
set-lifecycle-action change lifecycle actions
set-user-sshkeys manipulate authorized SSH keys file for given user (via agent)
set-user-password set the user password inside the domain
setmaxmem change maximum memory limit
setmem change memory allocation
setvcpus change number of virtual CPUs
shutdown gracefully shutdown a domain
start start a (previously defined) inactive domain
suspend suspend a domain
ttyconsole tty console
undefine undefine a domain
update-device update device from an XML file
vcpucount domain vcpu counts
vcpuinfo detailed domain vcpu information
vcpupin control or query domain vcpu affinity
emulatorpin control or query domain emulator affinity
vncdisplay vnc display
guestvcpus query or modify state of vcpu in the guest (via agent)
setvcpu attach/detach vcpu or groups of threads
domblkthreshold set the threshold for block-threshold event for a given block device or it's backing chain element
guestinfo query information about the guest (via agent)
Domain Monitoring (help keyword 'monitor')
domblkerror Show errors on block devices
domblkinfo domain block device size information
domblklist list all domain blocks
domblkstat get device block stats for a domain
domcontrol domain control interface state
domif-getlink get link state of a virtual interface
domifaddr Get network interfaces' addresses for a running domain
domiflist list all domain virtual interfaces
domifstat get network interface stats for a domain
dominfo domain information
dommemstat get memory statistics for a domain
domstate domain state
domstats get statistics about one or multiple domains
domtime domain time
list list domains
Host and Hypervisor (help keyword 'host')
allocpages Manipulate pages pool size
capabilities capabilities
cpu-baseline compute baseline CPU
cpu-compare compare host CPU with a CPU described by an XML file
cpu-models CPU models
domcapabilities domain capabilities
freecell NUMA free memory
freepages NUMA free pages
hostname print the hypervisor hostname
hypervisor-cpu-baseline compute baseline CPU usable by a specific hypervisor
hypervisor-cpu-compare compare a CPU with the CPU created by a hypervisor on the host
maxvcpus connection vcpu maximum
node-memory-tune Get or set node memory parameters
nodecpumap node cpu map
nodecpustats Prints cpu stats of the node.
nodeinfo node information
nodememstats Prints memory stats of the node.
nodesuspend suspend the host node for a given time duration
sysinfo print the hypervisor sysinfo
uri print the hypervisor canonical URI
version show version
Checkpoint (help keyword 'checkpoint')
checkpoint-create Create a checkpoint from XML
checkpoint-create-as Create a checkpoint from a set of args
checkpoint-delete Delete a domain checkpoint
checkpoint-dumpxml Dump XML for a domain checkpoint
checkpoint-edit edit XML for a checkpoint
checkpoint-info checkpoint information
checkpoint-list List checkpoints for a domain
checkpoint-parent Get the name of the parent of a checkpoint
Interface (help keyword 'interface')
iface-begin create a snapshot of current interfaces settings, which can be later committed (iface-commit) or restored (iface-rollback)
iface-bridge create a bridge device and attach an existing network device to it
iface-commit commit changes made since iface-begin and free restore point
iface-define define an inactive persistent physical host interface or modify an existing persistent one from an XML file
iface-destroy destroy a physical host interface (disable it / "if-down")
iface-dumpxml interface information in XML
iface-edit edit XML configuration for a physical host interface
iface-list list physical host interfaces
iface-mac convert an interface name to interface MAC address
iface-name convert an interface MAC address to interface name
iface-rollback rollback to previous saved configuration created via iface-begin
iface-start start a physical host interface (enable it / "if-up")
iface-unbridge undefine a bridge device after detaching its device(s)
iface-undefine undefine a physical host interface (remove it from configuration)
Network Filter (help keyword 'filter')
nwfilter-define define or update a network filter from an XML file
nwfilter-dumpxml network filter information in XML
nwfilter-edit edit XML configuration for a network filter
nwfilter-list list network filters
nwfilter-undefine undefine a network filter
nwfilter-binding-create create a network filter binding from an XML file
nwfilter-binding-delete delete a network filter binding
nwfilter-binding-dumpxml network filter information in XML
nwfilter-binding-list list network filter bindings
Networking (help keyword 'network')
net-autostart autostart a network
net-create create a network from an XML file
net-define define an inactive persistent virtual network or modify an existing persistent one from an XML file
net-destroy destroy (stop) a network
net-dhcp-leases print lease info for a given network
net-dumpxml network information in XML
net-edit edit XML configuration for a network
net-event Network Events
net-info network information
net-list list networks
net-name convert a network UUID to network name
net-start start a (previously defined) inactive network
net-undefine undefine a persistent network
net-update update parts of an existing network's configuration
net-uuid convert a network name to network UUID
net-port-list list network ports
net-port-create create a network port from an XML file
net-port-dumpxml network port information in XML
net-port-delete delete the specified network port
Node Device (help keyword 'nodedev')
nodedev-create create a device defined by an XML file on the node
nodedev-destroy destroy (stop) a device on the node
nodedev-detach detach node device from its device driver
nodedev-dumpxml node device details in XML
nodedev-list enumerate devices on this host
nodedev-reattach reattach node device to its device driver
nodedev-reset reset node device
nodedev-event Node Device Events
Secret (help keyword 'secret')
secret-define define or modify a secret from an XML file
secret-dumpxml secret attributes in XML
secret-event Secret Events
secret-get-value Output a secret value
secret-list list secrets
secret-set-value set a secret value
secret-undefine undefine a secret
Snapshot (help keyword 'snapshot')
snapshot-create Create a snapshot from XML
snapshot-create-as Create a snapshot from a set of args
snapshot-current Get or set the current snapshot
snapshot-delete Delete a domain snapshot
snapshot-dumpxml Dump XML for a domain snapshot
snapshot-edit edit XML for a snapshot
snapshot-info snapshot information
snapshot-list List snapshots for a domain
snapshot-parent Get the name of the parent of a snapshot
snapshot-revert Revert a domain to a snapshot
Backup (help keyword 'backup')
backup-begin Start a disk backup of a live domain
backup-dumpxml Dump XML for an ongoing domain block backup job
Storage Pool (help keyword 'pool')
find-storage-pool-sources-as find potential storage pool sources
find-storage-pool-sources discover potential storage pool sources
pool-autostart autostart a pool
pool-build build a pool
pool-create-as create a pool from a set of args
pool-create create a pool from an XML file
pool-define-as define a pool from a set of args
pool-define define an inactive persistent storage pool or modify an existing persistent one from an XML file
pool-delete delete a pool
pool-destroy destroy (stop) a pool
pool-dumpxml pool information in XML
pool-edit edit XML configuration for a storage pool
pool-info storage pool information
pool-list list pools
pool-name convert a pool UUID to pool name
pool-refresh refresh a pool
pool-start start a (previously defined) inactive pool
pool-undefine undefine an inactive pool
pool-uuid convert a pool name to pool UUID
pool-event Storage Pool Events
pool-capabilities storage pool capabilities
Storage Volume (help keyword 'volume')
vol-clone clone a volume.
vol-create-as create a volume from a set of args
vol-create create a vol from an XML file
vol-create-from create a vol, using another volume as input
vol-delete delete a vol
vol-download download volume contents to a file
vol-dumpxml vol information in XML
vol-info storage vol information
vol-key returns the volume key for a given volume name or path
vol-list list vols
vol-name returns the volume name for a given volume key or path
vol-path returns the volume path for a given volume name or key
vol-pool returns the storage pool for a given volume key or path
vol-resize resize a vol
vol-upload upload file contents to a volume
vol-wipe wipe a vol
Virsh itself (help keyword 'virsh')
cd change the current directory
echo echo arguments
exit quit this interactive terminal
help print help
pwd print the current directory
quit quit this interactive terminal
connect (re)connect to hypervisor
(specify help <group> for details about the commands in the group)
(specify help <command> for details about the command)
Removal
Removal of libvirt package (toolkit, library, and utilities) can be done by executing:
root #emerge --ask --depclean --verbose app-emulation/libvirtSee also
- Virtualization — the concept and technique that permits running software in an environment separate from a computer operating system.
- QEMU — a generic, open source hardware emulator and virtualization suite.
- QEMU/Front-ends — facilitate VM management and use
- Libvirt — a virtualization management toolkit.
- Libvirt/QEMU_networking — details the setup of Gentoo networking by Libvirt for use by guest containers and QEMU-based virtual machines.
- Libvirt/QEMU_guest — covers libvirt and its creation of a virtual machine (VM) for use under the soft-emulation mode QEMU hypervisor Type-2, notably using virsh command.
- Virt-manager — desktop user interface for management of virtual machines and containers through the libvirt library
- Virt-manager/QEMU_guest — QEMU creation of a guest (VM or container)
- QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.