vdsmd (8) - Linux Manuals

vdsmd: Virtual Desktops and Servers Manager

NAME

vdsmd - Virtual Desktops and Servers Manager
@ENGINENAME@ host agent

SYNOPSIS

service vdsmd start

DESCRIPTION

The VDSM service is required by a @ENGINENAME@ to manage oVirt Nodes and Linux hosts. Currently, only Fedora and Red Hat Enterprise Linux are supported. VDSM manages and monitors the host's storage, memory and networks as well as virtual machine creation, other host administration tasks, statistics gathering, and log collection.

VDSM should be run as a daemon on each node managed by @ENGINENAME@. It answers XML-RPC calls from clients (mostly @ENGINENAME@).

HOOKS

VDSM is extendible: it has hooks in strategic locations, where it executes external scripts. Hooks API is new and is subject to future changes. Currently-supported hooks have self-explanatory names:
 before_vm_start, after_vm_start,
 before_vm_cont, after_vm_cont,
 before_vm_pause, after_vm_pause,
 before_vm_hibernate, after_vm_hibernate,
 before_vm_dehibernate, after_vm_dehibernate,
 before_vm_migrate_source, after_vm_migrate_source,
 before_vm_migrate_destination, after_vm_migrate_destination,
 before_device_migrate_source, after_device_migrate_source,
 before_device_migrate_destination, after_device_migrate_destination,
 before_vm_destroy, after_vm_destroy,
 before_vm_set_ticket, after_vm_set_ticket,
 before_device_create, after_device_create,
 before_device_destroy, after_device_destroy,
 before_nic_hotplug, after_nic_hotplug, after_nic_hotplug_fail,
 before_nic_hotunplug, after_nic_hotunplug, after_nic_hotunplug_fail,
 before_update_device, after_update_device, after_update_device_fail,
 before_disk_hotplug, after_disk_hotplug,
 before_disk_hotunplug, after_disk_hotunplug,
 before_vdsm_start, after_vdsm_stop,
 before_network_setup, after_network_setup, after_network_setup_fail,
 before_set_num_of_cpus, after_set_num_of_cpus,
 before_get_vm_stats, after_get_vm_stats,
 before_get_all_vm_stats, after_get_all_vm_stats,
 before_get_caps, after_get_caps,
 before_get_stats, after_get_stats,
 after_hostdev_list_by_caps,
 before_memory_hotplug, after_memory_hotplug,
 before_ifcfg_write, after_ifcfg_write.

Each hook executes the scripts under /usr/libexec/vdsm/hooks/<hook-name>/ in lexicographic order.

Hook environment

Each hook script (except before_vdsm_start, after_vdsm_stop, before_network_setup, after_network_setup and after_network_setup_fail, before_get_vm_stats, after_get_vm_stats, before_get_all_vm_stats, after_get_all_vm_stats, before_get_caps, after_get_caps, before_get_stats, after_get_stats, after_hostdev_list_by_caps, before_ifcfg_write and after_ifcfg_write) inherit the environment of the VDSM process, with an additional variable _hook_domxml which holds the path of libvirt's domain xml representation of the relevant virtual machine. The uuid of the virtual machine may be deduced from that xml, but it is also available as the environment variable vmId.

The before_network_setup, after_network_setup, after_network_setup_fail, before_ifcfg_write and after_ifcfg_write hooks do also include an extra environment variable _hook_json which holds a pointer to a file with the network parameters that vdsm is setting up ( request ) , the request may be modified by the before_network_setup hook as thus affect the operation ultimately taken place by Vdsm.

The JSON format of this file for before_network_setup, after_network_setup and after_network_setup_fail has one section: request, this section contains networks, bondings and options, those parameters are specified in the setupNetworks VDSM API call.

{"request":
    {
    "networks": {"virtnet": {"bonding" : "bond0", "bridged": true, "vlan":27}},
    "bondings": {"bond0": {"nics":["eth1","eth2"]}},
    "options":  {"conectivityCheck":false}
    }
 }

The JSON format of this file for before_ifcfg_write and after_ifcfg_write has the following parameters: ifcfg_file and config.

{
 "ifcfg_file": "/etc/sysconfig/network-scripts/ifcfg-eth0",
 "config": "IPADDR=192.168.1.2ETMASK=255.255.255.0"
 }

Hooks that handle NIC hotplug, hotunplug and update device have the _hook_domxml variable but it contains the representation of the NIC rather than the VM. Hotplug/hotunplug disk hooks also have the _hook_dom_xml variable, which contains the drive definition (not the VM). All hook points that are device specific get the xml of the device instead of the entire VM. Such hooks are listed below.

On top of these, @ENGINENAME@ allows to set a collection of "custom parameters" for each virtual machine. Each of these parameters is provided to hooks as an environment variable.

before_migration_destination (and before_dehibernation) hooks currently receive the xml of the domain from the source host. The xml of the domain at the destination will differ in various details.

The environment of before_vm_set_ticket and after_vm_set_ticket hooks is augmented with a set of params passed by the caller of setVmTicket.

The environment of before_vm_dehibernate and after_vm_dehibernate hooks have FROM_SNAPSHOT variable set to True if the VM is being restored from a live snapshot.

The environment of hooks specific to devices:
 before_nic_hotplug, after_nic_hotplug, after_nic_hotplug_fail,
 before_nic_hotunplug, after_nic_hotunplug, after_nic_hotunplug_fail,
 before_update_device, after_update_device, after_update_device_fail,
 before_disk_hotplug, after_disk_hotplug,
 before_disk_hotunplug, after_disk_hotunplug,
 before_device_create, after_device_create,
 before_device_destroy, after_device_destroy,
 before_device_migrate_source, after_device_migrate_source,
 before_device_migrate_destination, after_device_migrate_destination,
 before_memory_hotplug, after_memory_hotplug.

Are all augmented by custom properties specific to those devices, sent by the caller of the hook. For example if before_nic_hotplug is called with custom: {qos: '0.5', color: 'red'} then qos and color will be directly available as environment variables when before_nic_hotplug is called.

before_get_vm_stats and before_get_all_vm_stats are called upon API request to get VM statistics, before getVmStats and getAllVmStats respectively. Those hooks do not receive any parameters.

after_get_vm_stats and after_get_all_vm_stats are called upon getVmStats and getAllVmStats respectively. Both receive a parameter in _hook_json containing a list of dictionaries of VM stats (in case of after_get_vm_stats the list will have a single element):

[
        {"vm_id": "...", ... },
        {"vm_id": "...", ... },
        ...
]

before_get_caps and after_get_caps are called before (and after) a getVdsCapabilities API request. after_get_caps receives the complete capabilities dictionary within _hook_json.

before_get_stats and after_get_stats are called before (and after) a getVdsStats API request. after_get_stats receives the complete host statistics dictionary within _hook_json.

Hook execution

before_vdsm_start and after_vdsm_stop scripts are executed as user root. All the other hooks are executed as user vdsm.

before_vm_start scripts may edit the domain xml file (pointed by _hook_domxml ) in order to change VDSM's definition of a virtual machine before it reaches libvirt. As with all hooks, the China Store Rule applies - if you break something, you own it. Any script can mess up VDSM's operation badly. In particular, you may never change the uuid of the domain, and should better know what you are doing if you remove a device from the domain.

before_vm_start and before_device_create may alter the vm start behavior by modifying the vm libvirt vm startup flags. The flag must be written to the /var/run/vdsm/hook/<vm id>/launchflags file, the required value being a decimal based on the libvirt virDomainCreateFlags enum values.

Standard error of hook scripts is collected into VDSM's log, which may be used by scripts for debugging.

As a somewhat silly example, let us think of a script that warns when a domain with too much memory is started on a host:

    #!/bin/bash

    mem=`/usr/bin/xpath $_hook_domxml '/domain/memory/text()' 2> /dev/null`

    if [ "$mem" -gt 1073741824 ]; then
        echo "Domain with more than Gb!" >&2
    fi

    exit 0

Hook return code

Hook script must return one of the following return codes:

0

the hook script ended successfully.

1

the hook script failed, other hooks should be processed.

2

the hook script failed, no further hooks should be processed.

>2

reserved.

If a before_<action> hook fails, the <action> would be aborted.

However, before_vm_destroy's failure does not abort destroy().

FILES

/etc/vdsm/vdsm.conf

VDSM main configuration file. Use with great caution; some information about available variables and their meaning appear in /usr/share/doc/vdsm-<version>/vdsm.conf.sample

/var/log/vdsm/vdsm.log

Default log location for vdsm.

/usr/share/doc/vdsm-<version>/vdsm-api.html

vdsm QAPI documentation.

/etc/pki/vdsm

VDSM's trust store: server key, certificate, and @ENGINENAME@ CA's certificate.

/rhev/data-center

VDSM's image repository, or more exactly, links to NFS exports and iSCSI or FiberChannel devices which VDSM uses.

AUTHOR

VDSM was written by Ayal Baron, Barak Azulay, Cyril Plisko, Dan Kenigsberg, Doron Fediuck, Igor Lvovsky, Saggi Mizrahi, Shahar Frank, Simon Grinberg, and probably others.

BUGS

Report bugs to <http://bugzilla.redhat.com>

COPYRIGHT

Copyright 2010-2013 Red Hat, Inc. License GPLv2: GNU GPL Version 2 <http://gnu.org/licenses/gpl.html>.