16.1.2. Custom Properties
Red Hat Enterprise Virtualization Manager also allows specification of custom properties for each virtual machine. Each of these properties is provided to hooks as an environment variable. This allows users to pass virtual machine dependent parameters to the hook scripts. Additionally hook scripts are able to use the presence, or absence, of a given custom property to determine whether they should execute to completion.
The custom properties that are accepted by the Red Hat Enterprise Virtualization Manager — and in turn passed to custom hooks — are defined using the configuration tool, rhevm-config
. Run this command as the root
user on the host where Red Hat Enterprise Virtualization Manager is installed.
The configuration key UserDefinedVMProperties
is used to store the names of the custom properties supported. Regular expressions defining the valid values for each named custom property are also contained in this configuration key.
Where multiple custom properties are defined they are separated by a semi-colon. Note that when setting the configuration key any existing value it contained is overwritten. When combining new and existing custom properties it is necessary to include all of the custom properties in the command used to set the key's value.
Once the configuration key has been updated the jbossas
service must be restarted for it to take effect.
Example 16.1. Defining smartcard
Custom Property
Check the existing custom properties defined by the UserDefinedVMProperties
configuration key using rhevm-config -g UserDefinedVMProperties
.
In this case the custom property memory
is already defined. The regular expression ^[0-9]+$
ensures that the custom property will only ever contain numeric characters.
# rhevm-config -g UserDefinedVMProperties
UserDefinedVMProperties : version: general
UserDefinedVMProperties : version: 2.2
UserDefinedVMProperties : memory=^[0-9]+$ version: 3.0
As the memory
custom property is already defined in the UserDefinedVMProperties
configuration key the new custom property must be appended to it. The additional custom property, smartcard
, is added to the configuration key's value. The new custom property is able to hold a value of true
or false
.
# rhevm-config -s UserDefinedVMProperties='memory=^[0-9]+$;smartcard=^(true|false)$' --cver=3.0
Verify that the custom properties defined by the UserDefinedVMProperties
configuration key now match your expectations.
# rhevm-config -g UserDefinedVMProperties
UserDefinedVMProperties : version: general
UserDefinedVMProperties : version: 2.2
UserDefinedVMProperties : memory=^[0-9]+$;smartcard=^(true|false)$ version: 3.0
Finally, the jbossas
service must be restarted for the configuration change to take effect.
# service restart jbossas
Once custom properties are defined to Red Hat Enterprise Virtualization Manager you are able to begin setting them on virtual machines. Custom properties are set on the Custom Properties tab of the New Server Virtual Machine, New Desktop Virtual Machine, Edit Server Virtual Machine, and Edit Desktop Virtual Machine dialog boxes in the Administration Portal.
You are also able to set custom properties from the Run Once dialog box. Custom properties set from the Run Once dialog box will only apply to the virtual machine until it is next shutdown.
The Custom Properties must be provided as key to value pairs of the form key
=value
, where key
is the name of the custom property and value
is the value which it should be set to for this virtual machine. Where multiple custom properties are being provided they must be separated by a semi-colon, as illustrated in the example below.
Each key set in the Custom Properties field for a virtual machine is appended as an environment variable when calling hook scripts. Although the regular expressions used to validate the Custom Properties field provide some protection you should ensure that your scripts also validate that the inputs provided match their expectations.
Example 16.2. Evaluating Custom Properties
This short Python example checks for the existence of the custom property key1
. If the custom property is set then the value is printed to standard error. If the custom property is not set then no action is taken.
#!/usr/bin/python
import os
import sys
if os.environ.has_key('key1'):
sys.stderr.write('key1 value was : %s\n' % os.environ['key1'])
else:
sys.exit(0)
VDSM ships with a Python hooking module, providing helper functions for VDSM hook scripts. This module is provided as an example, and is only relevant to VDSM hooks written in Python.
The modified object can then be saved back to libvirt XML using the hooking module. The hooking module provides the following functions to support hook development:
Table 16.2. Hooking module functions
Name
|
Argument
|
Description
|
---|
tobool
|
string
|
Converts a string "true" or "false" to a Boolean value
|
read_domxml
|
-
|
Reads the virtual machine's libvirt XML into a DOM object
|
write_domxml
|
DOM object
|
Writes the virtual machine's libvirt XML from a DOM object
|