virsh

From Gentoo Wiki
Jump to:navigation Jump to:search

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.

Tip
For GUI-based, use virt-manager — lightweight GUI application designed for managing virtual machines and containers via the libvirt API..

Installation

See libvirt for installation of virsh.

System user/group

For non-root usage of virsh, user must have the libvirt group name as part of its supplemental group. Defined by acct-group/libvirt; evoked by app-emulation/libvirt package.

Tip
See User/group permissions in Libvirt for adding an user to the libvirt group list.

Configuration

Environment variables

A list of optional environment variables that are read and checked by the virsh command:

  • DISPLAY - the display X server and screen to which graphical applications should be sent. For virtualbox-only
  • DNSMASQ_CLIENT_ID - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • DNSMASQ_IAID - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • DNSMASQ_INTERFACE - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • DNSMASQ_LEASE_EXPIRES - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • DNSMASQ_OLD_HOSTNAME - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • DNSMASQ_SERVER_DUID - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • DNSMASQ_SUPPLIED_HOSTNAME - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • VIR_BRIDGE_NAME - Used by libvirt_leaseshelper with dnsmasqd during bridge driver.
  • LIBVIRT_ADMIN_DEFAULT_URI - administration, see virt-admin(1) manpage. (Deprecated; use LIBVIRT_DEFAULT_URI)
  • LIBVIRT_AUTH_FILE - authentication, when connecting to libvirtd
  • LIBVIRT_DEBUG - debug level
  • LIBVIRT_DEFAULT_URI - administration, see virt-admin(1) manpage.
  • LIBVIRT_GNUTLS_DEBUG - Enable GNUTLS debug, if defined
  • LIBVIRT_LIBSSH_DEBUG - Enable LIBSSH debug, if defined; use TRACE_LIBSSH=<level> to define debug level.
  • LIBVIRT_LOG_FILTERS - A component:level colon-pair, each separated by commas: levels are , error, warning, info, debug, trace.; Some components are qemu, network, storage, cpu, driver, interface, xml, domain, migration, security, host, api, config, event, util.
  • LIBVIRT_LOG_OUTPUTS - A valid filepath to a debug log file.
  • LISTEN_PID - For systemd only.
  • LISTEN_FDS - For systemd only.
  • NOTIFY_SOCKET - for systemd-only.
  • QEMU_AUDIO_DRV - Valid values are pa, none, alsa, coreaudio, jack, oss, pipewire, sdl, spice or wav.
  • SDL_AUDIODRIVER - Valid values are pulseaudio, esd, alsa or arts.
  • VBOX_APP_HOME - for virtualbox-only
  • VIRSH_DEFAULT_CONNECT_URI - administration, see virsh(1) manpage. (Deprecated; used LIBVIRT_DEFAULT_URI).
  • VIRTD_PATH - find the libvirtd executable; colon-separated directory spec(s).

Environment variables - Test

A list of all testing environment variables that are read and checked by the virsh command:

  • LIBVIRT_AUTOSTART - If set to 0, disables auto-launching the libvirtd, but only if there is any unprivileged hypervisor drivers required.
  • LIBVIRT_DIR_OVERRIDE - Ensure that any 3rd party apps using libvirt.so from the build tree get files resolved to the build/source tree too. Typically useful for language bindings running tests against non-installed libvirt.

Files

Whenever a domain starts, virsh checks for that domain XML file in each of the following paths:

  • System mode: /etc/libvirt/qemu/
  • User mode: $HOME/.config/libvirt/qemu/


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:

host-root#gpasswd -a <user> libvirt

See libvirt configuration for more setup on enabling user to use the virsh command.

Service

virsh requires libvirtd daemon to be started. 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

host-root#virsh list --all

libvirtd service - status by explicit channel

host-root#virsh -c qemu:///system list --all

libvirtd service - status by environment variable

By environment variable, run:

CODE Use environment variable to define connect type
export VIRSH_DEFAULT_CONNECT_URI=qemu:///system

then run:

host-root#virsh list --all


libvirtd service - status by config file

The libvirt configuration file is in the following directory order:

1. /etc/libvirt/libvirt.conf

Note
There is no $HOME nor user-specific Libvirt configuration file.
CODE Libvirt configuration settings
#
# This can be used to setup URI aliases for frequently
# used connection URIs. Aliases may contain only the
# characters  a-Z, 0-9, _, -.
#
# Following the '=' may be any valid libvirt connection
# URI, including arbitrary parameters

#uri_aliases = [
#  "hail=qemu+ssh://root@hail.cloud.example.com/system",
#  "sleet=qemu+ssh://root@sleet.cloud.example.com/system",
#]

#
# These can be used in cases when no URI is supplied by the application
# (@uri_default also prevents probing of the hypervisor driver).
#
#uri_default = "qemu:///system"

Use @uri_default if using this configuration file is copied as-is across multiple hosts; no probe for hypervisor driver done here, but if it does exist, use them.

Networking

The virsh command uses UNIX sockets to communicate with its libvirtd domain controller:

when using --connect=qemu:///system (default):

  • /run/libvirt/libvirt-sock
  • /run/libvirt/libvirt-admin-sock
  • /run/libvirt/libvirt-sock-ro

when using --connect=qemu:///session:

  • /run/user/1000/libvirt/libvirt-sock
  • /run/user/1000/libvirt/libvirt-admin-sock

Usage

Most distro (including Gentoo) includes auto-complete of virsh options at bash shell prompt by pressing Tab as needed.

General info

The virsh can be checked by running:

host-root#virsh nodeinfo

The virsh can check communication with libvirtd daemon via Unix socket by running:

host-root#virsh sysinfo

Checking domain

Guest domains maintained by virt-manager can be checked by doing:

host-root#virsh list --all

Checking networking

Network interfaces maintained by virt-manager can be checked by running:

host-root#virsh net-list --all

Checking storage pools

Storage pools maintained by virt-manager can be checked by executing:

host-root#virsh pool-list --all

List available commands

In case the mind slips, the group of list-related options can be obtained by doing:

host$virsh help | grep list

Then you can add the --help option for more detailed options specific to, for example, the iface-list command:

host$virsh iface-list --help


Invocation

host$virsh --help

Removal

Removal of libvirt package (toolkit, library, and utilities) can be done by executing:

root #emerge --ask --depclean --verbose app-emulation/libvirt

See 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 — creation of a guest domain (virtual machine, VM), running inside a QEMU hypervisor, using tools found in libvirt package.
  • Virt-manager — lightweight GUI application designed for managing virtual machines and containers via the libvirt API.
  • Virt-manager/QEMU_guest — creation of a guest virtual machine (VM) running inside a QEMU hypervisor using just the virt-manager GUI tool.
  • QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.

External resources

Retrieved from "https://wiki.gentoo.org/index.php?title=Virsh&oldid=1370392"