Chapter 8 Installing and Using the Oracle VM Guest Additions
The Oracle VM Guest Additions allow bi-directional communication between Oracle VM Manager and the guest operating system of a virtual machine running in the Oracle VM environment. The Oracle VM Guest Additions provide fine-grained control over the configuration and behavior of components running within the virtual machine directly from Oracle VM Manager!
8.1 Features of the Oracle VM Guest Additions
The Oracle VM Guest Additions allow direct integration between guest software and the virtualization layer, to assist in orchestration and automation of complex, multi-virtual machine deployments. This integration can be used between Oracle Solaris, Microsoft Windows, and Oracle Linux running the Oracle Unbreakable Enterprise Kernel (UEK).
The Oracle VM Guest Additions allow you to:
-
Send key-value pairs to a virtual machine, or guest, and to retrieve messages from the guest.
-
More easily get information about virtual machines within Oracle VM Manager, such as reporting on IP addressing.
-
Use the template configuration facility to automatically configure virtual machines as they are first started.
-
Trigger programmed events by sending messages directly to a virtual machine from Oracle VM Manager.
-
Query virtual machines to obtain information pertaining to previous messages.
-
Interact with the Oracle VM Utilities ovm_vmmessage command.
Virtual Machine IP Address
When you install the Oracle VM Guest Additions, the IP address of the virtual machine displays in the Networks subtab of the Virtual Machines perspective in the Oracle VM Manager Web Interface.
8.2 Oracle VM Guest Additions Packages
To install the Oracle VM Guest Additions, you first download a set of packages from a yum repository to the virtual machine. You can download the packages from the Unbreakable Linux Network (ULN) or the Oracle Linux Yum Server. After you download the required packages, you use the yum install to install them.
The following table lists the packages for the Oracle VM Guest Additions:
|
Package |
Description |
Required or Optional |
|---|---|---|
|
|
Library that adds support for the Oracle VM API. |
Required |
|
|
Library that adds developer support for the Oracle VM API. |
Optional |
|
|
Daemon that handles configuration events and enables sending and receiving of messages between the virtual machine and Oracle VM Manager. |
Required |
|
|
Library that communicates with the Oracle VM API kernel infrastructure. |
Required |
|
|
Basic operating system configuration scripts. |
Required |
|
|
Script for configuring virtual machine authentication. |
Optional |
|
|
Script for configuring virtual machine datetime settings. |
Optional |
|
|
Script for configuring virtual machine firewall. |
Optional |
|
|
Script for configuring virtual machine network settings. |
Optional |
|
|
Script for configuring virtual machine selinux settings. |
Optional |
|
|
Script for configuring virtual machine ssh settings. |
Optional |
|
|
Script for configuring virtual machine system settings. |
Optional |
|
|
Script for configuring virtual machine user settings. |
Optional |
Microsoft Windows Guests
For Microsoft Windows guests, the Oracle VM Guest Additions are included in the Oracle VM Paravirtual Drivers. The implementation of the guest additions consists of these components:
-
vmapi.dll: a dynamic link library that exposes callable interfaces -
ovmsvc: the service that receives and sends events and messages -
xenpci: the driver that interacts with the hypervisor -
ovmcmd: the command used to invoke the guest additions
vmapi.dll
The vmapi.dll exposes interfaces to functions
for communication between Windows applications and the
xenpci driver in the Windows guest operating
system. Applications load this library and call the exported
functions to access xenpci. Normally device I/O
controls (IOCTLs) are used to communicate with the
xenpci driver. The following table shows
function names and their descriptions:
|
Function |
Description |
|---|---|
|
OVMAPI_Register |
initializes OVMAPI and optionally registers a callback |
|
OVMAPI_ParamGetValue |
retrieves name-value pairs stored within the OVMAPI engine |
|
OVMAPI_ParamSetValue |
creates or modifies a name-value pair |
|
OVMAPI_Subscribe |
receives particular events in the application registered event handler |
|
OVMAPI_UnSubscribe |
blocks particular events in the application registered event handler |
|
OVMAPI_EventComplete |
completes the event with a finalizing status code at a later time |
|
OVMAPI_ParamGetValueSize |
retrieves the size, in bytes, of a parameter value |
|
OVMAPI_GetSessionFileDescriptors |
retrieves the internal file descriptor for use in making special calls to the driver |
|
OVMAPI_UserEventPublish |
sends application-specific events to the management server and to other OVMAPI-enabled applications running on the same VM |
|
OVMAPI_ParamGetAllNames |
browses for existing parameters that may be of interest to the application |
|
OVMAPI_ParamGetCount |
retrieves the number of existing parameters |
|
OVMAPI_UnRegister |
terminates OVMAPI usage |
ovmsvc
The ovmsvc service starts automatically by
default when the Windows VM is booted. The command to install or
uninstall this service is ovmsvc install or
ovmsvc uninstall respectively. The
ovmsvc service monitors messages sent from
Oracle VM Manager, and sends Windows VM specific information, such as the
operating system version and the VM's IP address. It uses the
vmapi.dll to implement communication between
the Windows guest and Oracle VM Manager. The following figure shows
ovmsvc running inside a Windows VM.
When ovmsvc is started, it opens the
xenpci device and registers a callback function
where messages are processed. A thread is created to monitor
events corresponding with vmapi messages. The
current callback function of ovmsvc processes
VM shutdown messages; other messages, for example "snapshot",
could be implemented as additional features.
xenpci
Applications exchanging messages with Oracle VM Manager use the xenpci
driver, which implements several IOCTLs to process messages. The
xenpci driver directly accesses xenstore, a memory area shared by
Xen domains. The ovmsvc calls API functions to
send or read VM messages to or from xenstore.
The xenpci driver uses the
xenbus_watch function to monitor incoming
messages. The xenpci driver initialization registers a watch
function on the xenstore key
"control/oracle-vmapi/to-guest/last-write".
Messages sent by Oracle VM Manager are set in this xenstore key. The watch
function of xenpci is triggered when this
xenstore key changes. The watch function checks and sends out
events, a monitor thread acknowledges events, and a callback
function processes API messages.
The ovmsvc sends Windows VM messages during its
startup process, and uses an IOCTL in xenpci to
write the xenstore key
"control/oracle-vmapi/from-guest/%d/%s". The
ovmsvc updates the message periodically to
synchronize the information, such as guest IP address, from the
guest to Oracle VM Manager.
Oracle Solaris
The Oracle VM Guest Additions are also available for Oracle Solaris, both on
SPARC and x86. They can be optionally installed from a Solaris IPS
repository:
pkg://solaris/system/management/ovm-guest-additions.
8.3 Downloading the Oracle VM Guest Additions Packages
The Oracle VM Guest Additions packages are available for download from the addons channel for the guest operating system on the Unbreakable Linux Network (ULN) or the Oracle Linux Yum Server. The appropriate channels for the Oracle Linux guest operating systems on the Oracle Linux yum server are:
-
Oracle Linux 8 Add ons (x86_64) – Oracle Linux 8 (x86_64) Addons
-
Oracle Linux 7 Add ons (x86_64) – Oracle Linux 7 (x86_64) Addons
-
Oracle Linux 6 Add ons (x86_64) – Oracle Linux 6 (x86_64) Addons
Downloading from ULN
To download the Oracle VM Guest Additions packages from ULN, subscribe your system to the addons channel.
Alternatively, you can create a yum server that acts as a local mirror of the ULN addons channel.
For Oracle Linux Release 8, see the Oracle Linux documentation for more information at Registering With the Unbreakable Linux Network
For Oracle Linux Release 7: or Oracle Linux Release 6, see the following Oracle Linux documentation for more information:
-
Oracle Linux Release 7:
-
Oracle Linux Release 6:
Downloading from the Oracle Linux Yum Server
By default, the yum repository configuration file on Oracle Linux contains a section that defines the addons channel on the Oracle Linux Yum Server.
To download the Oracle VM Guest Additions packages from the public yum repository, you need to enable the addons channel in the yum configuration file.
For Oracle Linux Release 8, see the Oracle Linux documentation for more information at Obtaining Errata and Updates From the Oracle Linux Yum Server
For Oracle Linux Release 7: or Oracle Linux Release 6, see the following Oracle Linux documentation for more information:
-
Oracle Linux Release 7:
-
Oracle Linux Release 6:
Microsoft Windows Guests
For Microsoft Windows guests, the Oracle VM Guest Additions are included in the Oracle VM Paravirtual Drivers. Refer to the Oracle VM Paravirtual Drivers for Microsoft Windows documentation library. Follow the download instructions for the selected release of the paravirtual drivers.
Oracle Solaris
For Oracle Solaris, both on SPARC and x86, the Oracle VM Guest Additions can be downloaded from a Solaris IPS repository at https://pkg.oracle.com/solaris/release/en/index.shtml or through https://support.oracle.com/portal/ with your support contract access.
8.4 Installing the Oracle VM Guest Additions
To install the Oracle VM Guest Additions, do the following:
-
Download the required packages for the Oracle VM Guest Additions.
-
Run the yum install command to install the packages; for example,
# yum install libovmapi xenstoreprovider ovmd xenstoreprovider
Microsoft Windows Guests
For Microsoft Windows guests, the Oracle VM Guest Additions are included in the Oracle VM Paravirtual Drivers. Refer to the Oracle VM Paravirtual Drivers for Microsoft Windows documentation library. Follow the installation instructions for the selected release of the paravirtual drivers.
Oracle Solaris
To install the Oracle VM Guest Additions on Oracle Solaris, do the following:
-
Ensure that an appropriate 'solaris' repository publisher is configured.
-
Run the IPS command to install the package; for example,
# pkg install ovm-guest-additions
8.5 Upgrading the Oracle VM Guest Additions
You should update the Oracle VM Guest Additions packages regularly to ensure they function correctly. You should update the packages after you create a new virtual machine from an Oracle VM template on which the Oracle VM Guest Additions are installed.
To update the Oracle VM Guest Additions, do the following:
-
Ensure your virtual machine is connected to a yum repository that contains the packages for the Oracle VM Guest Additions.
-
Run the yum update command to install the packages; for example,
# yum update libovmapi xenstoreprovider ovmd xenstoreprovider
Microsoft Windows Guests
For Microsoft Windows guests, the Oracle VM Guest Additions are included in the Oracle VM Paravirtual Drivers. Refer to the Oracle VM Paravirtual Drivers for Microsoft Windows documentation library. Follow the upgrade instructions for the selected release of the paravirtual drivers. Silent upgrade is available in case you need to upgrade a large number of Windows guests.
Oracle Solaris
To upgrade the Oracle VM Guest Additions on Oracle Solaris, do the following:
-
Ensure that an appropriate 'solaris' repository publisher is configured.
-
Run the IPS command to update the package; for example,
# pkg update ovm-guest-additions
8.6 Using the Oracle VM Guest Additions (ovmd)
The Oracle VM Guest Additions daemon, ovmd, facilitates a bi-directional messaging channel between Oracle VM Manager and the guest. It allows first-boot installation configuration, and is capable of sending and receiving messages consisting of key-value pairs.
In previous releases you could use the ovmd utility to send key/value messages to a virtual machine. This feature is now included directly in Oracle VM Manager. Although this section mentions the options available to send messages to a virtual machine using ovmd, you should instead use the Oracle VM Manager Web Interface or Oracle VM Manager Command Line Interface to send key/value messages. The virtual machine must have the Oracle VM Guest Additions daemon installed and running. See sendVmMessage in the Oracle VM Manager Command Line Interface User's Guide , or the Send VM Messages section in the Oracle VM Manager User's Guide for more information.
Used in conjunction with the ovm-template-config script, the ovmd utility can be used to remotely configure system and application configuration parameters within a virtual machine as it boots. See Section 8.8, “The Oracle VM Template Configuration Script and Modules” for more information on this facility.
Oracle VM Manager makes use of ovmd in order to obtain IP addressing information from the guest to include in the Oracle VM Manager Web Interface when displaying detailed virtual machine information. See Virtual Machine IP Address.
You can run ovmd directly from the command line
to perform actions outside of ovmd's function as
a daemon or system service. Running ovmd using
the --help parameter provides you with a breakdown
of the options supported when run directly from the command line.
On Oracle Solaris, the command options and script names may differ from those presented
for Oracle Linux. For details, please refer to the ovmd(1M) man page, which is installed along
with the ovm-guest-additions package on Oracle Solaris.
Syntax
ovmd [
{
-p
|
--set-param=
}
param-g
|
--get-param=
}
key-r
|
--delete-param=
}
key-x
|
--delete-params
}
] [
{
-l
|
--list-params
}
] [
{
-e
|
--event=
}
event-s
|
--script=
}
script-d
|
--debug=
}
{
0
|
1
|
2
}
] [
{
-f
|
--pid-file=
}
filename-t
|
--time-period=
}
seconds-v
|
--version
}
] [
{
-h
|
--help
}
]
Options
The following table shows the available options for this command:
|
Option |
Description |
|---|---|
|
{
|
Set a parameter in the format of
|
|
{
|
Get the value of the parameter by key name. |
|
{
|
Delete the parameter by key name. |
|
{
|
Delete all parameters. |
|
{
|
List all parameters. |
|
{
|
Inject an event. |
|
{
|
Run a script on the virtual machine. |
|
{
|
Set the debug level. |
|
{
|
Set the path name of the process ID (PID) file. |
|
{
|
Set the period for daemon mode. The default is
|
|
{
|
Show the ovmd script version number and exit. |
|
{
|
Show help on the ovmd command options. |
Examples
# ovmd -v
# ovmd --script=/scripts/cleanup
# ovmd -p key1=value1
See Section 8.6.2, “Sending Messages to Virtual Machines” for more information on sending and receiving messages using the ovmd script.
# ovmd -\-list
{"key1":"value1"}
{"key2":"value2"}
# ovmd -r key1
8.6.1 Using the Oracle VM Guest Additions Daemon to Enable First-Boot Configuration
If you are configuring a virtual machine to act as a template, or if you intend to clone it, you can enable a first-boot configuration. This configuration causes the virtual machine to behave as if it is booting for the first time each time it boots. As a result, the virtual machine prompts for configuration input either by the VM API or on the virtual machine console. This can be achieved by running the following commands as root within the virtual machine:
# ovmd -s cleanup # service ovmd enable-initial-config # shutdown -h now
On next boot, the virtual machine acts as if it is performing a first-time boot.
If you have configured ovmd to run as a service, you can configure it remotely using the messaging facility and the ovm-template-config script.
See the example Section 8.6.2, “Sending Messages to Virtual Machines” for more information on using the messaging channel. Also see Section 8.8, “The Oracle VM Template Configuration Script and Modules” for information about the ovm-template-config script.
8.6.2 Sending Messages to Virtual Machines
This section gives an example of a message exchange between Oracle VM Manager and a running Oracle Linux virtual machine with Oracle VM Guest Additions installed.
Using ovmd, you send information from within the virtual machine to your Oracle VM Manager using the following syntax:
# ovmd -p key1=value1
The message appears in the Oracle VM Manager user interface, as a Virtual Machine API Incoming Message event for the virtual machine in question. When you expand the event, the description shows the key-value pair and the date and time when the information exchange took place.
Using ovmd from within the guest, you can retrieve the message sent from Oracle VM Manager using the following syntax:
# ovmd -\-list
{"key1":"value1"}
{"key2":"value2"}
The ovmd -\-list command retrieves all messages, both sent and received. You can identify the specific message you are looking for by its key. To remove obsolete messages, use the following syntax:
# ovmd -r key1
# ovmd -\-list
{"key2":"value2"}
8.6.3 Configuring the Oracle VM Guest Additions Daemon to Run as a Service
To enable ovmd to run as a service on Oracle Linux, run the chkconfig command as root:
# chkconfig ovmd on
To start the ovmd service, run the following as root:
# service ovmd start
When configured as a service, ovmd listens for message requests sent from Oracle VM Manager.
8.7 Using the Oracle VM Guest Additions with Microsoft Windows (ovmcmd)
The Oracle VM Guest Additions provide a command line tool named ovmcmd for
interacting with their functions, similar to the ovmd command in Linux. The
command line tool is distributed during installation of the Oracle VM Paravirtual Drivers,
and is located in the folder: C:\Program Files (x86)\Oracle Corporation\Oracle VM
Windows PV Drivers.
The Shell
The executable binary file ovmcmd is used with 32-bit Windows, while ovmcmd_64 is used with 64-bit Windows. You can run ovmcmd directly by using the Windows command line. The ovmcmd command provides its own shell mode, which is convenient for setting multiple variables. Enter ovmcmd without any parameter to display the list of supported interfaces.
Enter one of these commands to run ovmcmd in shell mode:
-
32-bit Windows: ovmcmd ovmapishell
-
64-bit Windows: ovmcmd_x64 ovmapishell
This example shows the ovmcmd shell on a 64-bit Windows:
The Commands
In shell mode, ovmcmd sets up a session and connects an event handler.
The user can enter commands at the OVMAPIShell shell prompt without having to
re-issue ovmcmd. This is optional, as individual commands can be specified on
the Windows command line executing ovmcmd. Shell mode can be used to send and
receive messages containing parameter values, or to display the contents of the xenstore.
Commands for sending and receiving messages are illustrated under Conversation
Between Guest and Oracle VM Manager. Command names in ovmcmd are not
case sensitive.
The Xenstore commands should only be used by people with substantial
knowledge of the internals of Xen. Those commands are:
-
XenstoreRead: reads the value of a xenstore key. The parameter following the subcommand is the xenstore key to read.
OVMAPIShell>XenstoreRead /local/domain/708/device/vif/0/state 4 OVMAPIShell>
-
XenstoreWrite: writes a value to a xenstore key or creates a new xenstore key. The parameters are the xenstore key and the value to be written. If the xenstore key is read-only, an error message appears.
OVMAPIShell>XenstoreWrite /local/domain/708/control/test 1 Operation Succeeded OVMAPIShell>XenstoreWrite /local/domain/708/test 2 Operation Failed OVMAPIShell>
-
XenstoreDir: lists a xenstore directory. The parameter is the xenstore directory to display.
OVMAPIShell>XenstoreDir /local/domain/0 vm device control error memory guest hvmpv data cpu 1 availability 2 availability [...] OVMAPIShell>
The SendMessage command is used to send messages. However, messages sent this way are not saved.
OVMAPIShell>SendMessage value 1 Operation Succeeded OVMAPIShell>
To send a message and at the same time save the parameter key/value pair, use the ParamSetValue command.
OVMAPIShell>ParamSetValue guestparam1 guestval 1 ParamSetValue returned 0 OVMAPIShell>OVMCmdEventHandler: Received Event type 64, size 12, ID 6 ParamSetValue returned 0
To retrieve the value of a specified parameter, use the ParamGetValue command.
OVMAPIShell>ParamGetValue guestparam1 guestval ParamGetValue returned 0, guestparam1 = guestval (len = 9)
Conversation Between Guest and Oracle VM Manager
Conversations between the guest VM and Oracle VM Manager are based on sending and receiving messages.
From the Windows VM side of the conversation: use the ovmcmd command
ParamSetValue to set a parameter and send a message from the guest VM to
Oracle VM Manager. For example ParamSetValue mykey myval sets the value of key "mykey"
to "myval", and sends a message to Oracle VM Manager.
C:\Program Files (x86)\Oracle Corporation\Oracle VM Windows PV Drivers>OVMCmd_64 ParamSetValue mykey myval ParamSetValue returned 0
The SendMessage command can also be used.
C:\Program Files (x86)\Oracle Corporation\Oracle VM Windows PV Drivers>OVMCmd_64 SendMessage foo bar Operation Succeeded
Use the ReadParameter command as shown below to read messages from Oracle VM Manager. Output can optionally be piped to a file for later processing.
C:\Program Files (x86)\Oracle Corporation\Oracle VM Windows PV Drivers>OVMCmd_64 ReadParameter sesame Success: sesame = street (7)
For the Oracle VM Manager side of the conversation: to display the message from the Oracle VM Manager user interface, select the VM in the Servers and VMs tab, right click, and select Display Events.
Alternatively, send a message to the guest with the Oracle VM CLI sendVmMessage command.
OVM> sendvmmessage vm name=VMNAMEkey=managerparammessage=managervallog=no
See sendVmMessage in the Oracle VM Manager Command Line Interface User's Guide for more information.
8.8 The Oracle VM Template Configuration Script and Modules
The Oracle VM Guest Additions include a set of packages that can help with the automatic configuration of virtual machine as they are created from a template and booted for the first time. The master package for this facility is known as ovm-template-config. The Oracle VM template configuration script can be used to configure a virtual machine remotely using the Oracle VM messaging facility via ovmd.
8.8.1 Template Configuration Script (ovm-template-config)
The Oracle VM Template Configuration Script,
ovm-template-config works in conjunction with a
set of modular configuration scripts that function in a manner very
similar to the standard Linux System V, init.d
and chkconfig, script model. Control over how
configuration modules are run is handled within the
/etc/template.d directory on the
guest virtual
machine. The configuration module scripts are stored in
/etc/template.d/scripts.
The ovm-template-config script is the master
script that is used to control all enabled modules. Running
ovm-template-config with the
--help parameter provides a usage breakdown.
For remote configuration, ovm-template-config is
used in conjunction with ovmd to capture
configuration parameters that have been sent to the guest using the
Oracle VM messaging facility. When this is the case,
ovm-template-config targets are presented to
ovmd as --script parameters:
# ovmd -s cleanup # ovmd -s configure
When performing remote configuration, using ovmd to process messages containing configuration keys, the authentication module must be enabled. Processing of messages can only be completed if the final message contains the root user password. See Section 8.8.2, “Enabling and Disabling Configuration Modules (ovm-chkconfig)” for more information on this module.
See Section 8.8.4, “Triggering Configuration Changes” for more information on calling this script directly.
Syntax
ovm-template-config [
-e
|
--enumerate
] [
--human-readable
] [
{
-i
|
--input=
}
input-o
|
--output=
}
output--stdin
] [
--console-input
] [
--ovf-transport-iso
] [
{
-s
|
--script=
}
script--logfile= logfile--loglevel= loglevel--version
] [
{
-h
|
--help
}
]
target
Where target
{
configure
|
unconfigure
|
reconfigure
|
cleanup
|
suspend
|
resume
|
migrate
|
shutdown
}
Options
The following table shows the available options for this command.
|
Option |
Description |
|---|---|
|
[
|
Enumerate the parameters for
|
|
|
Print in human readable format when enumerate parameters. |
|
{
|
Input parameters from this file descriptor. |
|
{
|
Output parameters to this file descriptor. |
|
|
Build parameters from |
|
|
Build parameters from the console input. |
|
|
Build parameters from the OVF transport ISO. |
|
{
|
Specify a script. |
|
|
Set the name of the log file. |
|
|
Set the logging level. |
|
|
Show the ovm-template-config script version number and exit. |
|
{
|
Show help on the ovm-template-config command options. |
Examples
# ovm-template-config --enumerate configure
# ovm-template-config --enumerate --script network configure
# ovm-template-config --stdin configure
# ovm-template-config --console-input configure
# ovm-template-config --ovf-transport-iso configure
8.8.2 Enabling and Disabling Configuration Modules (ovm-chkconfig)
When a module is enabled, symlinks to the module script are made to
other subdirectories within /etc/template.d
based on the type of target the module provides, in much the same
way that the System V init process works. When
a module gets added, the header of the module script is read to
verify the name, priority and targets and then a symlink is made to
the corresponding subdirectories under
/etc/template.d.
Enabling and disabling targets for any module is handled using the
ovm-chkconfig script. Usage of this command is
outlined using the --help parameter.
Syntax
ovm-chkconfig [
--list
[
name--add
name--del
name--target=
targetnameon
|
off
}
] [
--version
] [
{
-h
|
--help
}
]
Where target
{
configure
|
unconfigure
|
reconfigure
|
cleanup
|
suspend
|
resume
|
migrate
|
shutdown
}
Options
The following table shows the available options for this command.
|
Option |
Description |
|---|---|
|
[
|
Lists the status of the script
|
|
[
|
Add a new script |
|
[
|
Delete a script |
|
[
|
Specify the
|
|
|
Show the ovm-chkconfig script version number and exit. |
|
{
|
Show help on the ovm-chkconfig command options. |
Examples
# ovm-chkconfig --list name configure unconfigure reconfigure cleanup suspend resume migrate shutdown authentication on:90 off off off off off off off datetime on:50 off off off off off off off firewall on:41 off off off off off off off network off off off off off off off off selinux off off off off off off off off ssh off off off off off off off off system off off off off off off off off user off off off off off off off off
# ovm-chkconfig --add authentication
# ovm-chkconfig --del datetime
# ovm-chkconfig --target=cleanup user off
8.8.3 Key-Value Pairs Used By Available Configuration Modules
To obtain a full listing of all of the key pairs that are used to trigger configuration changes through the ovm-template-config configuration modules, run the following command on the guest system where ovm-template-config is installed:
# ovm-template-config --human-readable --enumerate configure
The output from this command is printed as a Python data structure,
that is easy to parse and understand. Content can be limited to the
information specific to a configuration module by using the
--script parameter as presented below:
# ovm-template-config --human-readable --enumerate configure --script datetime
[('50',
'datetime',
[{u'description': u'System date and time in format year-month-day-hour-minute-second,
e.g., "2011-4-7-9-2-42".',
u'hidden': True,
u'key': u'com.oracle.linux.datetime.datetime'},
{u'description': u'System time zone, e.g., "America/New_York".',
u'hidden': True,
u'key': u'com.oracle.linux.datetime.timezone'},
{u'description': u'Whether to keep hardware clock in UTC: True or False.',
u'hidden': True,
u'key': u'com.oracle.linux.datetime.utc'},
{u'description': u'Whether to enable NTP service: True or False.',
u'hidden': True,
u'key': u'com.oracle.linux.datetime.ntp'},
{u'description': u'NTP servers separated by comma, e.g.,
"time.example.com,0.example.pool.ntp.org".',
u'hidden': True,
u'key': u'com.oracle.linux.datetime.ntp-servers'},
{u'description': u'Whether to enable NTP local time source: True or False.',
u'hidden': True,
u'key': u'com.oracle.linux.datetime.ntp-local-time-source'}])]
From the output, it becomes clear as to which configuration modules are triggered at which runlevel and what keys and values they accept. Note that all key names are structured so that they are prefixed with com.oracle, to avoid conflicts with any custom modules that you may intend to develop for your own purposes.
Key value pairs are actually passed to ovm-template-config in JSON format:
{"com.oracle.linux.datetime.ntp":"True"}
{"com.oracle.linux.datetime.ntp-servers":"0.pool.ntp.org,1.pool.ntp.org,2.pool.ntp.org"}
{"com.oracle.linux.root-password":"mysecret"}
8.8.4 Triggering Configuration Changes
There are a variety of approaches that can be used to trigger a configuration change using ovm-template-config. Most commonly, this is done by setting the ovmd service to run using in enable-initial-config mode. This causes the virtual machine to wait to be provided with configuration parameters either on via the console, or via the ovmd messaging facility, after the next boot. This is the usual approach when configuring a virtual machine to act as a template.
To manually force ovmd to pass messages to the
ovm-template-config script, simply run
ovmd with the --script parameter
set to point to one of the ovm-template-config
targets:
# ovmd --list
{"com.oracle.linux.datetime.ntp":"True"}
{"com.oracle.linux.datetime.ntp-servers":"0.pool.ntp.org,1.pool.ntp.org,2.pool.ntp.org"}
{"com.oracle.linux.root-password":"password"}
# ovmd -s configure
To perform an action using messaging parameters and ovm-template-config, the authentication module must be enabled and your final message should include an authentication request in the form of a key-value message:
{"com.oracle.linux.root-password":"password"}
When running ovmd like this, ovmd prepares two pipes (infd and outfd) and calls the ovm-template-config script transparently in the background in the following way:
# ovm-template-config --input <infd> --output <outfd> configure
During testing, it may be useful to simply pass configuration
information directly to the script from STDIN on the command line.
This can be achieved by calling the script directly with the
--stdin parameter:
# ovm-template-config --stdin configure <<EOF
> {"com.oracle.linux.selinux.mode": "disabled"}
> {"com.oracle.linux.root-password": "ovsroot"}
> EOF
Configuration can also be achieved directly from the console by
running the script using the --console-input
option. Doing this will prompt you for values for each of the keys
that need to be defined for any enabled modules:
# ovm-template-config --console-input configure
8.8.5 Developing Oracle VM Template Configuration Modules
The provided module scripts are developed in Python. Theoretically, it is possible to develop module scripts in a different language, as long as the input, output and argument handling remains the same. The example provided in this section makes use of the Python programming language.
Each module script consists of two main parts:
-
The script header, which contains information like script name, targets, priorities and description.
-
The actual script, which handles a small set of parameters.
For examples of functional module scripts, refer to the existing
modules in the /etc/template.d/scripts
directory.
Module Script Header
Module script headers require a very specific comment block in order for ovm-chkconfig to handle enabling and disabling your script functionality. The format for the script header is as follows:
### BEGIN PLUGIN INFO # name: [script name] # [target]: [priority] # [target]: [priority] # description: a description that can # cross multiple lines. ### END PLUGIN INFO
When developing your own module script, you must include a header following the exact same format. Provide your own script name, which will be used when calling ovm-chkconfig, the targets that your script will support, and the priority for your script. The priority will specify in what order the script gets executed. You do not have to implement all targets. If you have a configure target but no cleanup target, this is still acceptable. The configure target gets called when a first boot/initial start of the virtual machine happens. The cleanup target happens when you manually initiate a cleanup in your virtual machine or when you want to restore the virtual machine to its original state. An example of the network module script header is provided below:
### BEGIN PLUGIN INFO # name: network # configure: 50 # cleanup: 50 # description: Script to configure template network. ### END PLUGIN INFO
Module Script Body
The main requirement for the module script body is that it accepts at least one target parameter. Target parameters that might get presented by the ovm-template-configure script include:
-
configure -
unconfigure -
reconfigure -
cleanup -
suspend -
resume -
migrate -
shutdown
Your script can handle any other arguments that you require. There
is one optional parameter which is useful to implement and this is
-e or --enumerate.
ovm-template-config uses this to be able to
enumerate or list the parameters for a target supported by your
script.
A very basic template to use for your script body follows:
try:
import json
except ImportError:
import simplejson as json
from templateconfig.cli import main
def do_enumerate(target):
param = []
if target == 'configure':
param += []
elif target == 'cleanup':
param += []
return json.dumps(param)
def do_configure(param):
param = json.loads(param)
return json.dumps(param)
def do_cleanup(param):
param = json.loads(param)
return json.dumps(param)
if __name__ == '__main__':
main(do_enumerate, {'configure': do_configure, 'cleanup': do_cleanup})
This script supports the configure and cleanup targets.
You can fill out the script with your own code. For instance, for
the do_enumerate function, you would populate the
parameters that are supported for each target in the script. An
example from the firewall module is presented below:
def do_enumerate(target):
param = []
if target == 'configure':
param += [{'key': 'com.oracle.linux.network.firewall',
'description': 'Whether to enable network firewall: True or False.',
'hidden': True}]
return json.dumps(param)
Each target function begins by reading the JSON parameters passed to
the script, using the param = json.loads(param)
statement. From this point, code can be written to perform actions
based on the values of the keys that the script expects to receive.
Once again, the example provided below is from the firewall module:
def do_configure(param):
param = json.loads(param)
firewall = param.get('com.oracle.linux.network.firewall')
if firewall == 'True':
shell_cmd('service iptables start')
shell_cmd('service ip6tables start')
shell_cmd('chkconfig --level 2345 iptables on')
shell_cmd('chkconfig --level 2345 ip6tables on')
elif firewall == 'False':
shell_cmd('service iptables stop')
shell_cmd('service ip6tables stop')
shell_cmd('chkconfig --level 2345 iptables off')
shell_cmd('chkconfig --level 2345 ip6tables off')
return json.dumps(param)
Module Script Packaging
Once you have written one or more configuration module scripts, you
may want to package them as RPMs that can be deployed on other
systems. In order to install and configure template configure
scripts, they have to be packaged in an RPM, with a specific naming
convention. Package the script as
ovm-template-config-[scriptname]. Ideally in
the post install of the RPM you should add the script automatically
by executing # /usr/sbin/ovm-chkconfig --add
. When uninstalling a
script/RPM, remove it at uninstall time using scriptname#
/usr/sbin/ovm-chkconfig --del
. This is illustrated
in the following example of an RPM spec file that can be used:
scriptname
Name: ovm-template-config-example
Version: 3.0
Release: 1%{?dist}
Summary: Oracle VM template example configuration script.
Group: Applications/System
License: GPL
URL: https://www.oracle.com/virtualization
Source0: %{name}-%{version}.tar.gz
BuildRoot: %(mktemp -ud %{_tmppath}/%{name}-%{version}-%{release}-XXXXXX)
BuildArch: noarch
Requires: ovm-template-config
%description
Oracle VM template example configuration script.
%prep
%setup -q
%install
rm -rf $RPM_BUILD_ROOT
make install DESTDIR=$RPM_BUILD_ROOT
%clean
rm -rf $RPM_BUILD_ROOT
%post
if [ $1 = 1 ]; then
/usr/sbin/ovm-chkconfig --add example
fi
%preun
if [ $1 = 0 ]; then
/usr/sbin/ovm-chkconfig --del example
fi
%files
%defattr(-,root,root,-)
%{_sysconfdir}/template.d/scripts/example
%changelog
* Tue Mar 22 2011 John Smith - 3.0-1
- Initial build.
Edit the example spec file to reference your own script name.
In order to create RPMs, you must install
rpmbuild:
# yum install rpm-build
The following is an example Makefile that you might assist in automating the build process:
You must edit this Makefile to reference your own script.
DESTDIR=
PACKAGE=ovm-template-config-example
VERSION=3.0
help:
@echo 'Commonly used make targets:'
@echo ' install - install program'
@echo ' dist - create a source tarball'
@echo ' rpm - build RPM packages'
@echo ' clean - remove files created by other targets'
dist: clean
mkdir $(PACKAGE)-$(VERSION)
tar -cSp --to-stdout --exclude .svn --exclude .hg --exclude .hgignore \
--exclude $(PACKAGE)-$(VERSION) * | tar -x -C $(PACKAGE)-$(VERSION)
tar -czSpf $(PACKAGE)-$(VERSION).tar.gz $(PACKAGE)-$(VERSION)
rm -rf $(PACKAGE)-$(VERSION)
install:
install -D example $(DESTDIR)/etc/template.d/scripts/example
rpm: dist
rpmbuild -ta $(PACKAGE)-$(VERSION).tar.gz
clean:
rm -fr $(PACKAGE)-$(VERSION)
find . -name '*.py[cdo]' -exec rm -f '{}' ';'
rm -f *.tar.gz
.PHONY: dist install rpm clean
Create a working directory, copy over your script, the spec file and the Makefile. Run the following command to create a src tarball of your code:
# make dist
Run the following command to generate an RPM file:
# make rpm
The preceding command generates an RPM in the
RPMS/noarch directory within your working
directory, for example:
RPMS/noarch/ovm-template-config-test-3.0-1.el6.noarch.rpm.