Red Hat Enterprise Virtualization 3.5
Technical Concepts and Developer Tools for Red Hat Enterprise Virtualization
Legal Notice
Copyright © 2015 Red Hat.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Abstract
A comprehensive guide to the underlying technical concepts behind and developer tools available in Red Hat Enterprise Virtualization.
- I. Technical Reference
- 1. Introduction
- 2. Storage
- 2.1. Storage Domains Overview
- 2.2. Types of Storage Backing Storage Domains
- 2.3. Storage Domain Types
- 2.4. Storage Formats for Virtual Machine Disk Images
- 2.5. Virtual Machine Disk Image Storage Allocation Policies
- 2.6. Settings to Wipe Virtual Disks After Deletion
- 2.7. Storage Domain Autorecovery in Red Hat Enterprise Virtualization
- 2.8. The Storage Pool Manager
- 2.9. Storage Pool Manager Selection Process
- 2.10. Exclusive Resources and Sanlock in Red Hat Enterprise Virtualization
- 2.11. Thin Provisioning and Storage Over-Commitment
- 2.12. Logical Volume Extension
- 3. Network
- 3.1. Network Architecture
- 3.2. Introduction: Basic Networking Terms
- 3.3. Network Interface Controller
- 3.4. Bridge
- 3.5. Bonds
- 3.6. Switch Configuration for Bonding
- 3.7. Virtual Network Interface Cards
- 3.8. Virtual LAN (VLAN)
- 3.9. Cluster Networking
- 3.10. Logical Networks
- 3.11. Required Networks, Optional Networks, and Virtual Machine Networks
- 3.12. Virtual Machine Connectivity
- 3.13. Port Mirroring
- 3.14. Host Networking Configurations
- 3.15. Bridge Configuration
- 3.16. VLAN Configuration
- 3.17. Bridge and Bond Configuration
- 3.18. Multiple Bridge, Multiple VLAN, and NIC Configuration
- 3.19. Multiple Bridge, Multiple VLAN, and Bond Configuration
- 4. Power Management
- 5. Load Balancing, Scheduling, and Migration
- 5.1. Load Balancing, Scheduling, and Migration
- 5.2. Load Balancing Policy
- 5.3. Load Balancing Policy: VM_Evenly_Distributed
- 5.4. Load Balancing Policy: Evenly_Distributed
- 5.5. Load Balancing Policy: Power_Saving
- 5.6. Load Balancing Policy: None
- 5.7. Highly Available Virtual Machine Reservation
- 5.8. Scheduling
- 5.9. Migration
- 6. Directory Services
- 7. Templates and Pools
- 8. Virtual Machine Snapshots
- 9. Hardware Drivers and Devices
- 10. Minimum Requirements and Technical Limitations
- 10.1. Minimum Requirements and Supported Limits
- 10.2. Data Center Limitations
- 10.3. Cluster Limitations
- 10.4. Storage Domain Limitations
- 10.5. Red Hat Enterprise Virtualization Manager Limitations
- 10.6. Hypervisor Requirements
- 10.7. Guest Requirements and Support Limits
- 10.8. SPICE Limitations
- 10.9. Additional References
- II. The Command Line Interface
- 11. Using the CLI
- 12. Quick Start Example
- 13. Commands
- 14. Resource Types
- 14.1. brick
- 14.2. cdrom
- 14.3. cluster
- 14.4. datacenter
- 14.5. disk
- 14.6. glustervolume
- 14.7. group
- 14.8. host
- 14.9. network
- 14.10. nic
- 14.11. permission
- 14.12. permit
- 14.13. quotas
- 14.14. role
- 14.15. snapshot
- 14.16. statistic
- 14.17. storageconnection
- 14.18. storagedomain
- 14.19. tag
- 14.20. template
- 14.21. user
- 14.22. vm
- 14.23. vmpool
- 14.24. vnicprofile
- 15. CLI Queries
- III. The REST Application Programming Interface
- 16. Introduction
- 17. Authentication and Security
- 18. REST API Quick Start Example
- 18.1. Example: Access API Entry Point
- 18.2. Example: List Data Center Collection
- 18.3. Example: List Host Cluster Collection
- 18.4. Example: List Logical Networks Collection
- 18.5. Example: List Host Collection
- 18.6. Example: List CPU Profiles
- 18.7. Example: Approve Host
- 18.8. Example: Create NFS Data Storage
- 18.9. Example: Create NFS ISO Storage
- 18.10. Example: Attach Storage Domains to Data Center
- 18.11. Example: Activate Storage Domains
- 18.12. Example: Create Virtual Machine
- 18.13. Example: Create Virtual Machine NIC
- 18.14. Example: Create Virtual Machine Storage Disk
- 18.15. Example: Attach ISO Image to Virtual Machine
- 18.16. Example: Start Virtual Machine
- 18.17. Example: Check System Events
- 19. Entry Point
- 20. Compatibility Level Versions
- 21. Capabilities
- 22. Common Features
- 23. The Backup and Restore API
- 24. Data Centers
- 25. Clusters
- 26. Networks
- 27. Storage Domains
- 28. Storage Connections
- 29. Hosts
- 30. Virtual Machines
- 31. Floating Disks
- 32. Templates
- 33. Virtual Machine Pools
- 34. Domains
- 35. Groups
- 36. Roles
- 37. Users
- 38. Tags
- 39. Events
- IV. The Python Sofware Development Kit
- 40. Software Development Kit Overview
- 41. Python Quick Start Example
- 41.1. Python Quick Start Introduction
- 41.2. Example: Accessing the API Entry Point using Python
- 41.3. Example: Listing the Data Center Collection using Python
- 41.4. Example: Listing the Cluster Collection using Python
- 41.5. Example: Listing the Logical Networks Collection using Python
- 41.6. Example: Listing the Host Collection using Python
- 41.7. Example: Listing the ISO Files in an ISO Storage Domain
- 41.8. Example: Listing the Size of a Virtual Machine
- 41.9. Example: Approving a Host using Python
- 41.10. Example: Creating NFS Data Storage using Python
- 41.11. Example: Creating NFS ISO Storage using Python
- 41.12. Example: Attaching Storage Domains to a Data Center using Python
- 41.13. Example: Activating Storage Domains using Python
- 41.14. Example: Creating a Virtual Machine using Python
- 41.15. Example: Creating a Virtual Machine NIC using Python
- 41.16. Example: Creating a Virtual Machine Storage Disk using Python
- 41.17. Example: Attaching an ISO Image to a Virtual Machine using Python
- 41.18. Example: Detaching a Disk using Python
- 41.19. Example: Starting a Virtual Machine using Python
- 41.20. Example: Starting a Virtual Machine with Overridden Parameters using Python
- 41.21. Example: Starting a Virtual Machine with Cloud-Init using Python
- 41.22. Example: Checking System Events using Python
- 42. Using the Software Development Kit
- 42.1. Connecting to the API using Python
- 42.2. Resources and Collections
- 42.3. Retrieving Resources from a Collection
- 42.4. Retrieving a Specific Resource from a Collection
- 42.5. Retrieving a List of Resources from a Collection
- 42.6. Adding a Resource to a Collection
- 42.7. Updating a Resource in a Collection
- 42.8. Removing a Resource from a Collection
- 42.9. Handling Errors
- 43. Python Reference Documentation
- V. The Java Software Development Kit
- 44. Software Development Kit Overview
- 45. Using the Software Development Kit
- 45.1. Connecting to the Red Hat Enterprise Virtualization Manager
- 45.2. Listing Entities
- 45.3. Modifying the Attributes of Resources
- 45.4. Getting a Resource
- 45.5. Adding Resources
- 45.6. Performing Actions on Resources
- 45.7. Listing Sub-Resources
- 45.8. Getting Sub-Resources
- 45.9. Adding Sub-Resources to a Resource
- 45.10. Modifying Sub-Resources
- 45.11. Performing Actions on Sub-Resources
- 45.12. Recommended Practices
- 45.13. Configuring SSL
- A. API Usage with cURL
- B. UI Plugins
- C. Enumerated Value Translation
- D. Event Codes
- E. Timezones
- F. Revision History
Part I. Technical Reference
Table of Contents
- 1. Introduction
- 2. Storage
- 2.1. Storage Domains Overview
- 2.2. Types of Storage Backing Storage Domains
- 2.3. Storage Domain Types
- 2.4. Storage Formats for Virtual Machine Disk Images
- 2.5. Virtual Machine Disk Image Storage Allocation Policies
- 2.6. Settings to Wipe Virtual Disks After Deletion
- 2.7. Storage Domain Autorecovery in Red Hat Enterprise Virtualization
- 2.8. The Storage Pool Manager
- 2.9. Storage Pool Manager Selection Process
- 2.10. Exclusive Resources and Sanlock in Red Hat Enterprise Virtualization
- 2.11. Thin Provisioning and Storage Over-Commitment
- 2.12. Logical Volume Extension
- 3. Network
- 3.1. Network Architecture
- 3.2. Introduction: Basic Networking Terms
- 3.3. Network Interface Controller
- 3.4. Bridge
- 3.5. Bonds
- 3.6. Switch Configuration for Bonding
- 3.7. Virtual Network Interface Cards
- 3.8. Virtual LAN (VLAN)
- 3.9. Cluster Networking
- 3.10. Logical Networks
- 3.11. Required Networks, Optional Networks, and Virtual Machine Networks
- 3.12. Virtual Machine Connectivity
- 3.13. Port Mirroring
- 3.14. Host Networking Configurations
- 3.15. Bridge Configuration
- 3.16. VLAN Configuration
- 3.17. Bridge and Bond Configuration
- 3.18. Multiple Bridge, Multiple VLAN, and NIC Configuration
- 3.19. Multiple Bridge, Multiple VLAN, and Bond Configuration
- 4. Power Management
- 5. Load Balancing, Scheduling, and Migration
- 5.1. Load Balancing, Scheduling, and Migration
- 5.2. Load Balancing Policy
- 5.3. Load Balancing Policy: VM_Evenly_Distributed
- 5.4. Load Balancing Policy: Evenly_Distributed
- 5.5. Load Balancing Policy: Power_Saving
- 5.6. Load Balancing Policy: None
- 5.7. Highly Available Virtual Machine Reservation
- 5.8. Scheduling
- 5.9. Migration
- 6. Directory Services
- 7. Templates and Pools
- 8. Virtual Machine Snapshots
- 9. Hardware Drivers and Devices
- 10. Minimum Requirements and Technical Limitations
- 10.1. Minimum Requirements and Supported Limits
- 10.2. Data Center Limitations
- 10.3. Cluster Limitations
- 10.4. Storage Domain Limitations
- 10.5. Red Hat Enterprise Virtualization Manager Limitations
- 10.6. Hypervisor Requirements
- 10.7. Guest Requirements and Support Limits
- 10.8. SPICE Limitations
- 10.9. Additional References
Chapter 1. Introduction
1.1. Red Hat Enterprise Virtualization Manager
The Red Hat Enterprise Virtualization Manager provides centralized management for a virtualized environment. A number of different interfaces can be used to access the Red Hat Enterprise Virtualization Manager. Each interface facilitates access to the virtualized environment in a different manner.
The Red Hat Enterprise Virtualization Manager provides graphical interfaces and an Application Programming Interface (API). Each interface connects to the Manager, an application delivered by an embedded instance of the Red Hat JBoss Enterprise Application Platform. There are a number of other components which support the Red Hat Enterprise Virtualization Manager in addition to Red Hat JBoss Enterprise Application Platform.
1.2. Red Hat Virtualization Hypervisor
A Red Hat Enterprise Virtualization environment has one or more hosts attached to it. A host is a server that provides the physical hardware that virtual machines make use of.
Red Hat Enterprise Virtualization Hypervisor hosts run an optimized operating system installed using a special, customized installation media specifically for creating virtualization hosts.
Red Hat Enterprise Linux hosts are servers running a standard Red Hat Enterprise Linux operating system that has been configured after installation to permit use as a host.
Both methods of host installation result in hosts that interact with the rest of the virtualized environment in the same way, and so, will both referred to as hosts.
- Kernel-based Virtual Machine (KVM)
- The Kernel-based Virtual Machine (KVM) is a loadable kernel module that provides full virtualization through the use of the Intel VT or AMD-V hardware extensions. Though KVM itself runs in kernel space, the guests running upon it run as individual QEMU processes in user space. KVM allows a host to make its physical hardware available to virtual machines.
- QEMU
- QEMU is a multi-platform emulator used to provide full system emulation. QEMU emulates a full system, for example a PC, including one or more processors, and peripherals. QEMU can be used to launch different operating systems or to debug system code. QEMU, working in conjunction with KVM and a processor with appropriate virtualization extensions, provides full hardware assisted virtualization.
- Red Hat Enterprise Virtualization Manager Host Agent, VDSM
- In Red Hat Enterprise Virtualization,
VDSMinitiates actions on virtual machines and storage. It also facilitates inter-host communication. VDSM monitors host resources such as memory, storage, and networking. Additionally, VDSM manages tasks such as virtual machine creation, statistics accumulation, and log collection. A VDSM instance runs on each host and receives management commands from the Red Hat Enterprise Virtualization Manager using the re-configurable port54321.VDSM-REGVDSMusesVDSM-REGto register each host with the Red Hat Enterprise Virtualization Manager.VDSM-REGsupplies information about itself and its host using port80or port443. libvirt- Libvirt facilitates the management of virtual machines and their associated virtual devices. When Red Hat Enterprise Virtualization Manager initiates virtual machine life-cycle commands (start, stop, reboot), VDSM invokes libvirt on the relevant host machines to execute them.
- Storage Pool Manager, SPM
- The Storage Pool Manager (SPM) is a role assigned to one host in a data center. The SPM host has sole authority to make all storage domain structure metadata changes for the data center. This includes creation, deletion, and manipulation of virtual disk images, snapshots, and templates. It also includes allocation of storage for sparse block devices on a Storage Area Network(SAN). The role of SPM can be migrated to any host in a data center. As a result, all hosts in a data center must have access to all the storage domains defined in the data center.Red Hat Enterprise Virtualization Manager ensures that the SPM is always available. In case of storage connectivity errors, the Manager re-assigns the SPM role to another host.
- Guest Operating System
- Guest operating systems can be installed without modification on virtual machines in a Red Hat Enterprise Virtualization environment. The guest operating system, and any applications on the guest, are unaware of the virtualized environment and run normally.Red Hat provides enhanced device drivers that allow faster and more efficient access to virtualized devices. You can also install the Red Hat Enterprise Virtualization Guest Agent on guests, which provides enhanced guest information to the management console.
1.3. Features Requiring a Compatibility Upgrade to Red Hat Enterprise Virtualization 3.5
Some of the features provided by Red Hat Enterprise Virtualization 3.5 are only available if your data centers, clusters, and storage have a compatibility version of 3.5.
Table 1.1. Features Requiring a Compatibility Upgrade to Red Hat Enterprise Virtualization 3.5
| Feature | Description |
|---|---|
|
Para-virtualized random number generator (RNG) device support
|
This feature adds support for enabling a para-virtualized random number generator in virtual machines. To use this feature, the random number generator source must be set at cluster level to ensure all hosts support and report desired RNG device sources. This feature is supported in Red Hat Enterprise Linux hosts of version 6.6 and higher.
|
|
Serial number policy support
|
This feature adds support for setting a custom serial number for virtual machines. Serial number policy can be specified at cluster level, or for an individual virtual machine.
|
|
Save OVF files on any data domain
|
This feature adds support for Open Virtualization Format files, including virtual machine templates, to be stored on any domain in a supported pool.
|
|
Boot menu support
|
This feature adds support for enabling a boot device menu in a virtual machine.
|
|
Import data storage domains
|
This feature adds support for users to add existing data storage domains to their environment. The Manager then detects and adds all the virtual machines in that storage domain.
|
|
SPICE copy and paste support
|
This feature adds support for users to enable or disable SPICE clipboard copy and paste.
|
|
Storage pool metadata removal
|
This feature adds support for storage pool metadata to be stored and maintained in the engine database only.
|
|
Network custom properties support
|
This feature adds support for users to define custom properties when a network is provisioned on a host.
|
1.4. Interfaces for Accessing the Manager
- User Portal
- Desktop virtualization provides users with a desktop environment that is similar a personal computer's desktop environment. The User Portal is for delivering Virtual Desktop Infrastructure to users. Users access the User Portal through a web browser to display and access their assigned virtual desktops. The actions available to a user in the User Portal are set by a system administrator. Standard users can start, stop, and use desktops that are assigned to them by the system administrator. Power users can perform some administrative actions. Both types of user access the User Portal from the same URL, and are presented with options appropriate to their permission level on login.
- Standard User AccessStandard users are able to power their virtual desktops on and off and connect to them through the User Portal. Direct connection to virtual machines is facilitated with Simple Protocol for Independent Computing Environments (SPICE) or Virtual Network Computing (VNC) clients. Both protocols provide the user with an environment similar to a locally installed desktop environment. The administrator specifies the protocol used to connect to a virtual machine at the time of the virtual machine's creation.More information on the actions available from the User Portal as well as supported browsers and clients can be found in the User Guide.
- Power User AccessThe Red Hat Enterprise Virtualization User Portal provides power users with a graphical user interface to create, use, and monitor virtual resources. System administrators can delegate some administration tasks by granting users power user access. In addition to the tasks that can be performed by standard users, power users can:
- Create, edit, and remove virtual machines.
- Manage virtual disks and network interfaces.
- Assign user permissions to virtual machines.
- Create and use templates to rapidly deploy virtual machines.
- Monitor resource usage and high-severity events.
- Create and use snapshots to restore virtual machines to previous states.
Power users can perform virtual machine administration tasks to be delegated. Data center and cluster level administration tasks are saved for the environment administrator.
- Administration Portal
- The Administration Portal is the graphical administration interface of the Red Hat Enterprise Virtualization Manager server. Using it administrators can monitor, create, and maintain all elements of the virtualized environment using from web browsers. Tasks which can be performed from the Administration Portal include:
- Creation and management of virtual infrastructure (networks, storage domains).
- Installation and management of hosts.
- Creation and management of logical entities (data centers, clusters).
- Creation and management of virtual machines.
- Red Hat Enterprise Virtualization user and permission management.
The Administration Portal is displayed using the JavaScript.Administration Portal functions are discussed in further detail in the Red Hat Enterprise Virtualization Administration Guide. Information on the browsers and platforms that are supported by the Administration Portal can be found in the Red Hat Enterprise Virtualization Installation Guide. - Representational State Transfer (REST) API
- The Red Hat Enterprise Virtualization REST API provides a software interface for the interrogation and control of the Red Hat Enterprise Virtualization environment. The REST API can be used by any programming language that supports HTTP actions.Using the REST API developers and administrators can:
- Integrate with enterprise IT systems.
- Integrate with third party virtualization software.
- Perform automated maintenance and error checking tasks.
- Use scripts to automate repetitive tasks in a Red Hat Enterprise Virtualization environment.
See the Red Hat Enterprise Virtualization REST API Guide for the API specification and usage examples.
1.5. Components that Support the Manager
- Red Hat JBoss Enterprise Application Platform
- Red Hat JBoss Enterprise Application Platform is a Java application server. It provides a framework to support efficient development and delivery of cross-platform Java applications. The Red Hat Enterprise Virtualization Manager is delivered using Red Hat JBoss Enterprise Application Platform.
Important
The version of the Red Hat JBoss Enterprise Application Platform bundled with Red Hat Enterprise Virtualization Manager is not to be used to serve other applications. It has been customized for the specific purpose of serving the Red Hat Enterprise Virtualization Manager. Using the Red Hat JBoss Enterprise Application Platform that is included with the Manager for additional purposes adversely affects its ability to service the Red Hat Enterprise Virtualization environment. - Gathering Reports and Historical Data
- The Red Hat Enterprise Virtualization Manager includes a data warehouse that collects monitoring data about hosts, virtual machines, and storage. A number of pre-defined reports are available. Customers can analyze their environments and create reports using any query tools that support SQL.The Red Hat Enterprise Virtualization Manager installation process creates two databases. These databases are created on a Postgres instance which is selected during installation.
- The engine database is the primary data store used by the Red Hat Enterprise Virtualization Manager. Information about the virtualization environment like its state, configuration, and performance are stored in this database.
- The ovirt_engine_history database contains configuration information and statistical metrics which are collated over time from the engine operational database. The configuration data in the engine database is examined every minute, and changes are replicated to the ovirt_engine_history database. Tracking the changes to the database provides information on the objects in the database. This enables you to analyze and enhance the performance of your Red Hat Enterprise Virtualization environment and resolve difficulties.For more information on generating reports based on the ovirt_engine_history database see the Red Hat Enterprise Virtualization Administration Guide.
Important
The replication of data in the ovirt_engine_history database is performed by the RHEVM History Service, ovirt-engine-dwhd. - Directory services
- Directory services provide centralized network-based storage of user and organizational information. Types of information stored include application settings, user profiles, group data, policies, and access control. The Red Hat Enterprise Virtualization Manager supports Active Directory, Identity Management (IdM), OpenLDAP, and Red Hat Directory Server 9. There is also a local, internal domain for administration purposes only. This internal domain has only one user: the admin user.
1.6. Storage
Red Hat Enterprise Virtualization uses a centralized storage system for virtual machine disk images, templates, snapshots, and ISO files. Storage is logically grouped into storage pools, which are comprised of storage domains. A storage domain is a combination of storage capacity and metadata that describes the internal structure of the storage. There are three types of storage domain; data, export, and ISO.
The data storage domain is the only one required by each data center. A data storage domain is exclusive to a single data center. Export and ISO domains are optional. Storage domains are shared resources, and must be accessible to all hosts in a data center.
Storage networking can be implemented using Network File System (NFS), Internet Small Computer System Interface (iSCSI), GlusterFS, or Fibre Channel Protocol (FCP). Red Hat Enterprise Virtualization additionally provides the unsupported ability to use any POSIX compliant networked filesystem as a data domain.
On NFS (and other POSIX compliant filesystems) domains, all virtual disks, templates, and snapshots are simple files.
On SAN (iSCSI/FCP) domains, block devices are aggregated by Logical Volume Manager (LVM)into a Volume Group (VG). Each virtual disk, template and snapshot is a Logical Volume (LV) on the VG. See Red Hat Enterprise Linux Logical Volume Manager Administration Guide for more information on LVM.
- Data storage domain
- Data domains hold the virtual hard disk images of all the virtual machines running in the environment. Templates and snapshots of the virtual machines are also stored in the data domain. A data domain cannot be shared across data centers, and the data domain must be of the same type as the data center. For example, a data center of iSCSI type must have an iSCSI data domain.
- Export storage domain
- An export domain is a temporary storage repository that is used to copy and move images between data centers and Red Hat Enterprise Virtualization environments. The export domain can be used to back up virtual machines and templates. An export domain can be moved between data centers, but can only be active in one data center at a time.
- ISO storage domain
- ISO domains store ISO files, which are logical CD-ROMs used to install operating systems and applications for the virtual machines. As a logical entity that replaces a library of physical CD-ROMs or DVDs, an ISO domain removes the data center's need for physical media. An ISO domain can be shared across different data centers.
1.7. Network
The Red Hat Enterprise Virtualization network architecture facilitates connectivity between the different elements of the Red Hat Enterprise Virtualization environment. The network architecture not only supports network connectivity, it also allows for network segregation.
Networking is defined in Red Hat Enterprise Virtualization in several layers. The underlying physical networking infrastructure must be in place and configured to allow connectivity between the hardware and the logical components of the Red Hat Enterprise Virtualization environment.
- Networking Infrastructure Layer
- The Red Hat Enterprise Virtualization network architecture relies on some common hardware and software devices:
- Network Interface Controllers (NICs) are physical network interface devices that connect a host to the network.
- Virtual NICs (VNICs) are logical NICs that operate using the host's physical NICs. They provide network connectivity to virtual machines.
- Bonds bind multiple NICs into a single interface.
- Bridges are a packet-forwarding technique for packet-switching networks. They form the basis of virtual machine logical networks.
- Logical Networks
- Logical networks allow segregation of network traffic based on environment requirements. The types of logical network are:
- logical networks that carry virtual machine network traffic,
- logical networks that do not carry virtual machine network traffic,
- optional logical networks,
- and required networks.
All logical networks can either be required or optional.A logical network that carries virtual machine network traffic is implemented at the host level as a software bridge device. By default, one logical network is defined during the installation of the Red Hat Enterprise Virtualization Manager: therhevmmanagement network.Other logical networks that can be added by an administrator are: a dedicated storage logical network, and a dedicated display logical network. Logical networks that do not carry virtual machine traffic do not have an associated bridge device on hosts. They are associated with host network interfaces directly.Red Hat Enterprise Virtualization segregates management-related network traffic from migration-related network traffic. This makes it possible to use a dedicated network (without routing) for live migration, and ensures that the management network (rhevm) does not lose its connection to hypervisors during migrations. - Explanation of logical networks on different layers
- Logical networks have different implications for each layer of the virtualization environment.Data Center LayerLogical networks are defined at the data center level. Each data center has the
rhevmmanagement network by default. Further logical networks are optional but recommended. Designation as a VM Network and a custom MTU can be set at the data center level. A logical network that is defined for a data center must also be added to the clusters that use the logical network.Cluster LayerLogical networks are made available from a data center, and must be added to the clusters that will use them. Each cluster is connected to the management network by default. You can optionally add to a cluster logical networks that have been defined for the cluster's parent data center. When a required logical network has been added to a cluster, it must be implemented for each host in the cluster. Optional logical networks can be added to hosts as needed.Host LayerVirtual machine logical networks are implemented for each host in a cluster as a software bridge device associated with a given network interface. Non-virtual machine logical networks do not have associated bridges, and are associated with host network interfaces directly. Each host has the management network implemented as a bridge using one of its network devices as a result of being included in a Red Hat Enterprise Virtualization environment. Further required logical networks that have been added to a cluster must be associated with network interfaces on each host to become operational for the cluster.Virtual Machine LayerLogical networks can be made available to virtual machines in the same way that a network can be made available to a physical machine. A virtual machine can have its virtual NIC connected to any virtual machine logical network that has been implemented on the host that runs it. The virtual machine then gains connectivity to any other devices or destinations that are available on the logical network it is connected to.Example 1.1. Management Network
The management logical network, namedrhevm, is created automatically when the Red Hat Enterprise Virtualization Manager is installed. Therhevmnetwork is dedicated to management traffic between the Red Hat Enterprise Virtualization Manager and hosts. If no other specifically-purposed bridges are set up,rhevmis the default bridge for all traffic.
1.8. Data Centers
A data center is the highest level of abstraction in Red Hat Enterprise Virtualization. A data center is a container that is comprised of three types of sub-containers:
- The storage container holds information about storage types and storage domains, including connectivity information for storage domains. Storage is defined for a data center, and available to all clusters in the data center. All host clusters within a data center have access to the same storage domains.
- The network container holds information about the data center's logical networks. This includes details such as network addresses, VLAN tags and STP support. Logical networks are defined for a data center, and are optionally implemented at the cluster level.
- The cluster container holds clusters. Clusters are groups of hosts with compatible processor cores, either AMD or Intel processors. Clusters are migration domains; virtual machines can be live-migrated to any host within a cluster, and not to other clusters. One data center can hold multiple clusters, and each cluster can contain multiple hosts.
Chapter 2. Storage
- 2.1. Storage Domains Overview
- 2.2. Types of Storage Backing Storage Domains
- 2.3. Storage Domain Types
- 2.4. Storage Formats for Virtual Machine Disk Images
- 2.5. Virtual Machine Disk Image Storage Allocation Policies
- 2.6. Settings to Wipe Virtual Disks After Deletion
- 2.7. Storage Domain Autorecovery in Red Hat Enterprise Virtualization
- 2.8. The Storage Pool Manager
- 2.9. Storage Pool Manager Selection Process
- 2.10. Exclusive Resources and Sanlock in Red Hat Enterprise Virtualization
- 2.11. Thin Provisioning and Storage Over-Commitment
- 2.12. Logical Volume Extension
2.1. Storage Domains Overview
A storage domain is a collection of images that have a common storage interface. A storage domain contains complete images of templates and virtual machines (including snapshots), ISO files, and metadata about themselves. A storage domain can be made of either block devices (SAN - iSCSI or FCP) or a file system (NAS - NFS, GlusterFS, or other POSIX compliant file systems).
On NFS, all virtual disks, templates, and snapshots are files.
On SAN (iSCSI/FCP), each virtual disk, template or snapshot is a logical volume. Block devices are aggregated into a logical entity called a volume group, and then divided by LVM (Logical Volume Manager) into logical volumes for use as virtual hard disks. See Red Hat Enterprise Linux Logical Volume Manager Administration Guide for more information on LVM.
Virtual disks can have one of two formats, either QCOW2 or RAW. The type of storage can be either Sparse or Preallocated. Snapshots are always sparse but can be taken for disks created either as RAW or sparse.
Virtual machines that share the same storage domain can be migrated between hosts that belong to the same cluster.
2.2. Types of Storage Backing Storage Domains
Storage domains can be implemented using block based and file based storage.
- File Based Storage
- The file based storage types supported by Red Hat Enterprise Virtualization are NFS and storage local to hosts.
Note
It is possible to use any POSIX compliant networked filesystem as a storage domain, none but NFS are supported.File based storage is managed externally to the Red Hat Enterprise Virtualization environment.NFS storage is managed by a Red Hat Enterprise Linux NFS server, or other third party network attached storage server.Red Hat Enterprise Virtualization hosts can manage their own local storage file systems. - Block Based Storage
- Block storage uses unformatted block devices. Block devices are aggregated into volume groups by the Logical Volume Manager (LVM). An instance of LVM runs on all hosts, unaware of the instances running on other hosts. VDSM adds clustering logic on top of LVM by scanning volume groups for changes. When changes are detected, VDSM updates individual hosts by telling them to refresh their volume group information. The hosts divide the volume group into logical volumes, writing logical volume metadata to disk. If more storage capacity is added to an existing storage domain, the Red Hat Enterprise Virtualization Manager causes VDSM on each host to refresh volume group information.A Logical Unit Number (LUN) is an individual block device. One of the supported block storage protocols, iSCSI, FCoE, or SAS, is used to connect to a LUN. The Red Hat Enterprise Virtualization Manager manages software iSCSI connections to the LUNs. All other block storage connections are managed externally to the Red Hat Enterprise Virtualization environment. Any changes in a block based storage environment, such as the creation of logical volumes, extension or deletion of logical volumes and the addition of a new LUN are handled by LVM on a specially selected host called the Storage Pool Manager. Changes are then synced by VDSM which storage metadata refreshes across all hosts in the cluster.
2.3. Storage Domain Types
Red Hat Enterprise Virtualization supports these types of storage domains, and the storage types that each of the storage domains supports:
- The Data Storage Domain stores the hard disk images of all virtual machines in the Red Hat Enterprise Virtualization environment. Disk images may contain an installed operating system or data stored or generated by a virtual machine. Data storage domains support NFS, iSCSI, FCP, GlusterFS and POSIX compliant storage. A data domain cannot be shared between multiple data centers. Additionally, it is required that the data center and data storage domain use the same protocol (for example, both must be iSCSI based).
- The Export Storage Domain provides transitory storage for hard disk images and virtual machine templates being transferred between data centers. Additionally, export storage domains store backed up copies of virtual machines. Export storage domains support NFS storage. Multiple data centers can access a single export storage domain but only one data center can use it at a time.
- The ISO Storage Domain stores ISO files, also called images. ISO files are representations of physical CDs or DVDs. In the Red Hat Enterprise Virtualization environment the common types of ISO files are operating system installation disks, application installation disks, and guest agent installation disks. These images can be attached to virtual machines and booted in the same way that physical disks are inserted into a disk drive and booted. ISO storage domains allow all hosts within the data center to share ISOs, eliminating the need for physical optical media.
2.4. Storage Formats for Virtual Machine Disk Images
- QCOW2 Formatted Virtual Machine Storage
- QCOW2 is a storage format for virtual machine disk images. QCOW stands for QEMU copy on write. The QCOW2 format decouples the physical storage layer from the virtual layer by adding a mapping between logical and physical blocks. Each logical block is mapped to its physical offset, which enables storage over-commitment and virtual machine snapshots, where each QCOW volume only represents changes made to an underlying disk image.The initial mapping points all logical blocks to the offsets in the backing file or volume. When a virtual machine writes data to a QCOW2 volume after a snapshot, the relevant block is read from the backing volume, modified with the new information and written into a new snapshot QCOW2 volume. Then the map is updated to point to the new place.
- RAW
- The RAW storage format has a performance advantage over QCOW2 in that no formatting is applied to virtual machine disk images stored in the RAW format. Virtual machine data operations on disk images stored in RAW format require no additional work from hosts. When a virtual machine writes data to a given offset in its virtual disk, the I/O is written to the same offset on the backing file or logical volume.Raw format requires that the entire space of the defined image be preallocated unless using externally managed thin provisioned LUNs from a storage array.
2.5. Virtual Machine Disk Image Storage Allocation Policies
- Preallocated Storage
- All of the storage required for a virtual machine disk image is allocated prior to virtual machine creation. If a 20 GB disk image is created for a virtual machine, the disk image uses 20 GB of storage domain capacity. Preallocated disk images cannot be enlarged. Preallocating storage can mean faster write times because no storage allocation takes place during runtime, at the cost of flexibility. Allocating storage this way reduces the capacity of the Red Hat Enterprise Virtualization Manager to overcommit storage. Preallocated storage is recommended for virtual machines used for high intensity I/O tasks with less tolerance for latency in storage. Generally, server virtual machines fit this description.
Note
If thin provisioning functionality provided by your storage back-end is being used, preallocated storage should still be selected from the Administration Portal when provisioning storage for virtual machines. - Sparsely Allocated Storage
- The upper size limit for a virtual machine disk image is set at virtual machine creation time. Initially, the disk image does not use any storage domain capacity. Usage grows as the virtual machine writes data to disk, until the upper limit is reached. Capacity is not returned to the storage domain when data in the disk image is removed. Sparsely allocated storage is appropriate for virtual machines with low or medium intensity I/O tasks with some tolerance for latency in storage. Generally, desktop virtual machines fit this description.
Note
If thin provisioning functionality is provided by your storage back-end, it should be used as the preferred implementation of thin provisioning. Storage should be provisioned from the graphical user interface as preallocated, leaving thin provisioning to the back-end solution.
2.6. Settings to Wipe Virtual Disks After Deletion
The
wipe_after_delete flag, viewed in the Administration Portal as the Wipe After Delete check box, enables the initialization of the virtual disk upon deletion. If it is set to false, which is the default, deleting the disk will open up those blocks for re-use but will not specifically wipe the data. It is possible for this data to be recovered because the blocks have not been returned to zero.
Enabling
wipe_after_delete for virtual disks will wipe the blocks when the virtual disk is deleted, reverting the blocks to zero. This is more secure, and is recommended if the virtual disk has contained any sensitive data. This is a more intensive operation and users may experience degradation in performance and prolonged delete times.
The
wipe_after_delete flag default can be changed to true using the engine configuration tool on the Red Hat Enterprise Virtualization Manager. Restart the engine for the setting change to take effect.
Procedure 2.1. Setting SANWipeAfterDelete to Default to True Using the Engine Configuration Tool
- Run the engine configuration tool with the
--setaction:# engine-config --set SANWipeDelete=true
- Restart the engine for the change to take effect:
# service ovirt-engine restart
2.7. Storage Domain Autorecovery in Red Hat Enterprise Virtualization
Hosts in a Red Hat Enterprise Virtualization environment monitor storage domains in their data centers by reading metadata from each domain. A storage domain becomes inactive when all hosts in a data center report that they cannot access the storage domain.
Prior to Red Hat Enterprise Virtualization 3.1, storage domains that became inactive were disconnected by the Manager. Reconnecting to storage when connection issues had been resolved required manual administrator intervention.
Red Hat Enterprise Virtualization 3.1 introduced storage domain autorecovery. Rather than disconnecting an inactive storage domain, the Manager now assumes that the storage domain has become inactive temporarily, because of a temporary network outage for example. Once every 5 minutes, the Manager attempts to re-activate any inactive storage domains.
Administrator intervention may be required to remedy the cause of the storage connectivity interruption, but the Manager handles re-activating storage domains as connectivity is restored.
2.8. The Storage Pool Manager
Red Hat Enterprise Virtualization uses metadata to describe the internal structure of storage domains. Structural metadata is written to a segment of each storage domain. Hosts work with the storage domain metadata based on a single writer, and multiple readers configuration. Storage domain structural metadata tracks image and snapshot creation and deletion, and volume and domain extension.
The Red Hat Enterprise Virtualization host that can make changes to the structure of the data domain is known as the Storage Pool Manager (SPM). The SPM coordinates all metadata changes in the data center, such as creating and deleting disk images, creating and merging snapshots, copying images between storage domains, creating templates and storage allocation for block devices. There is one SPM for every data center. All other hosts can only read storage domain structural metadata.
A host can be manually selected as the SPM, or it can be assigned by the Red Hat Enterprise Virtualization Manager. The Manager assigns the SPM role by causing a potential SPM host to attempt to assume a storage-centric lease. The lease allows the SPM host to write storage metadata. It is storage-centric because it is written to the storage domain rather than being tracked by the Manager or hosts. Storage-centric leases are written to a special logical volume in the master storage domain called
leases. Metadata about the structure of the data domain is written to a special logical volume called metadata. Changes to the metadata logical volume are protected against by the leases logical volume.
The Manager uses VDSM to issue the
spmStart command to a host, causing VDSM on that host to attempt to assume the storage-centric lease. If the host is successful it becomes the SPM and retains the storage-centric lease until the Red Hat Enterprise Virtualization Manager requests that a new host assume the role of SPM.
The Manager moves the SPM role to another host if:
- the SPM host can not access all storage domains, but can access the master storage domain.
- the SPM host is unable to renew the lease because of a loss of storage connectivity or the lease volume is full and no write operation can be performed.
- the SPM host crashes.
2.9. Storage Pool Manager Selection Process
If a host has not been manually assigned the Storage Pool Manager (SPM) role, the SPM selection process is initiated and managed by the Red Hat Enterprise Virtualization Manager.
First, the Red Hat Enterprise Virtualization Manager requests that VDSM confirm which host has the storage-centric lease.
The Red Hat Enterprise Virtualization Manager tracks the history of SPM assignment from the initial creation of a storage domain onward. The availability of the SPM role is confirmed in three ways:
- The "getSPMstatus" command: the Manager uses VDSM to check with the host that had SPM status last and receives one of "SPM", "Contending", or "Free".
- The metadata volume for a storage domain contains the last host with SPM status.
- The metadata volume for a storage domain contains the version of the last host with SPM status.
If an operational, responsive host retains the storage-centric lease, the Red Hat Enterprise Virtualization Manager marks that host SPM in the administrator portal. No further action is taken.
If the SPM host does not respond, it is considered unreachable. If power management has been configured for the host, it is automatically fenced. If not, it requires manual fencing. The Storage Pool Manager role cannot be assigned to a new host until the previous Storage Pool Manager is fenced.
When the SPM role and storage-centric lease are free, the Red Hat Enterprise Virtualization Manager assigns them to a randomly selected operational host in the data center.
If the SPM role assignment fails on a new host, the Red Hat Enterprise Virtualization Manager adds the host to a list containing hosts the operation has failed on, marking these hosts as ineligible for the SPM role. This list is cleared at the beginning of the next SPM selection process so that all hosts are again eligible.
The Red Hat Enterprise Virtualization Manager continues request that the Storage Pool Manager role and storage-centric lease be assumed by a randomly selected host that is not on the list of failed hosts until the SPM selection succeeds.
Each time the current SPM is unresponsive or unable to fulfill its responsibilities, the Red Hat Enterprise Virtualization Manager initiates the Storage Pool Manager selection process.
2.10. Exclusive Resources and Sanlock in Red Hat Enterprise Virtualization
Certain resources in the Red Hat Enterprise Virtualization environment must be accessed exclusively.
The SPM role is one such resource. If more than one host were to become the SPM, there would be a risk of data corruption as the same data could be changed from two places at once.
Prior to Red Hat Enterprise Virtualization 3.1, SPM exclusivity was maintained and tracked using a VDSM feature called safelease. The lease was written to a special area on all of the storage domains in a data center. All of the hosts in an environment could track SPM status in a network-independent way. The VDSM's safe lease only maintained exclusivity of one resource: the SPM role.
Sanlock provides the same functionality, but treats the SPM role as one of the resources that can be locked. Sanlock is more flexible because it allows additional resources to be locked.
Applications that require resource locking can register with Sanlock. Registered applications can then request that Sanlock lock a resource on their behalf, so that no other application can access it. For example, instead of VDSM locking the SPM status, VDSM now requests that Sanlock do so.
Locks are tracked on disk in a lockspace. There is one lockspace for every storage domain. In the case of the lock on the SPM resource, each host's liveness is tracked in the lockspace by the host's ability to renew the hostid it received from the Manager when it connected to storage, and to write a timestamp to the lockspace at a regular interval. The ids logical volume tracks the unique identifiers of each host, and is updated every time a host renews its hostid. The SPM resource can only be held by a live host.
Resources are tracked on disk in the leases logical volume. A resource is said to be taken when its representation on disk has been updated with the unique identifier of the process that has taken it. In the case of the SPM role, the SPM resource is updated with the hostid that has taken it.
The Sanlock process on each host only needs to check the resources once to see that they are taken. After an initial check, Sanlock can monitor the lockspaces until timestamp of the host with a locked resource becomes stale.
Sanlock monitors the applications that use resources. For example, VDSM is monitored for SPM status and hostid. If the host is unable to renew it's hostid from the Manager, it loses exclusivity on all resources in the lockspace. Sanlock updates the resource to show that it is no longer taken.
If the SPM host is unable to write a timestamp to the lockspace on the storage domain for a given amount of time, the host's instance of Sanlock requests that the VDSM process release its resources. If the VDSM process responds, its resources are released, and the SPM resource in the lockspace can be taken by another host.
If VDSM on the SPM host does not respond to requests to release resources, Sanlock on the host kills the VDSM process. If the kill command is unsuccessful, Sanlock escalates by attempting to kill VDSM using sigkill. If the sigkill is unsuccessful, Sanlock depends on the watchdog daemon to reboot the host.
Every time VDSM on the host renews its hostid and writes a timestamp to the lockspace, the watchdog daemon receives a pet. When VDSM is unable to do so, the watchdog daemon is no longer being petted. After the watchdog daemon has not received a pet for a given amount of time, it reboots the host. This final level of escalation, if reached, guarantees that the SPM resource is released, and can be taken by another host.
2.11. Thin Provisioning and Storage Over-Commitment
The Red Hat Enterprise Virtualization Manager provides provisioning policies to optimize storage usage within the virtualization environment. A thin provisioning policy allows you to over-commit storage resources, provisioning storage based on the actual storage usage of your virtualization environment.
Storage over-commitment is the allocation of more storage to virtual machines than is physically available in the storage pool. Generally, virtual machines use less storage than what has been allocated to them. Thin provisioning allows a virtual machine to operate as if the storage defined for it has been completely allocated, when in fact only a fraction of the storage has been allocated.
Note
While the Red Hat Enterprise Virtualization Manager provides its own thin provisioning function, you should use the thin provisioning functionality of your storage back-end if it provides one.
To support storage over-commitment, a threshold is defined in VDSM which compares logical storage allocation with actual storage usage. This threshold is used to make sure that the data written to a disk image is smaller than the logical volume that backs it. QEMU identifies the highest offset written to in a logical volume, which indicates the point of greatest storage use. VDSM monitors the highest offset marked by QEMU to ensure that the usage does not cross the defined threshold. So long as VDSM continues to indicate that the highest offset remains below the threshold, the Red Hat Enterprise Virtualization Manager knows that the logical volume in question has sufficient storage to continue operations.
When QEMU indicates that usage has risen to exceed the threshold limit, VDSM communicates to the Manager that the disk image will soon reach the size of it's logical volume. The Red Hat Enterprise Virtualization Manager requests that the SPM host extend the logical volume. This process can be repeated as long as the data storage domain for the data center has available space. When the data storage domain runs out of available free space, you must manually add storage capacity to expand it.
2.12. Logical Volume Extension
The Red Hat Enterprise Virtualization Manager uses thin provisioning to overcommit the storage available in a storage pool, and allocates more storage than is physically available. Virtual machines write data as they operate. A virtual machine with a thinly-provisioned disk image will eventually write more data than the logical volume backing its disk image can hold. When this happens, logical volume extension is used to provide additional storage and facilitate the continued operations for the virtual machine.
Red Hat Enterprise Virtualization provides a thin provisioning mechanism over LVM. When using QCOW2 formatted storage, Red Hat Enterprise Virtualization relies on the host system process qemu-kvm to map storage blocks on disk to logical blocks in a sequential manner. This allows, for example, the definition of a logical 100 GB disk backed by a 1 GB logical volume. When qemu-kvm crosses a usage threshold set by VDSM, the local VDSM instance makes a request to the SPM for the logical volume to be extended by another one gigabyte. VDSM on the host running a virtual machine in need of volume extension notifies the SPM VDSM that more space is required. The SPM extends the logical volume and the SPM VDSM instance causes the host VDSM to refresh volume group information and recognize that the extend operation is complete. The host can continue operations.
Logical Volume extension does not require that a host know which other host is the SPM; it could even be the SPM itself. The storage extension communication is done via a storage mailbox. The storage mailbox is a dedicated logical volume on the data storage domain. A host that needs the SPM to extend a logical volume writes a message in an area designated to that particular host in the storage mailbox. The SPM periodically reads the incoming mail, performs requested logical volume extensions, and writes a reply in the outgoing mail. After sending the request, a host monitors its incoming mail for responses every two seconds. When the host receives a successful reply to its logical volume extension request, it refreshes the logical volume map in device mapper to recognize the newly allocated storage.
When the physical storage available to a storage pool is nearly exhausted, multiple images can run out of usable storage with no means to replenish their resources. A storage pool that exhausts its storage causes QEMU to return an enospc error, which indicates that the device no longer has any storage available. At this point, running virtual machines are automatically paused and manual intervention is required to add a new LUN to the volume group.
When a new LUN is added to the volume group, the Storage Pool Manager automatically distributes the additional storage to logical volumes that need it. The automatic allocation of additional resources allows the relevant virtual machines to automatically continue operations uninterrupted or resume operations if stopped.
Chapter 3. Network
- 3.1. Network Architecture
- 3.2. Introduction: Basic Networking Terms
- 3.3. Network Interface Controller
- 3.4. Bridge
- 3.5. Bonds
- 3.6. Switch Configuration for Bonding
- 3.7. Virtual Network Interface Cards
- 3.8. Virtual LAN (VLAN)
- 3.9. Cluster Networking
- 3.10. Logical Networks
- 3.11. Required Networks, Optional Networks, and Virtual Machine Networks
- 3.12. Virtual Machine Connectivity
- 3.13. Port Mirroring
- 3.14. Host Networking Configurations
- 3.15. Bridge Configuration
- 3.16. VLAN Configuration
- 3.17. Bridge and Bond Configuration
- 3.18. Multiple Bridge, Multiple VLAN, and NIC Configuration
- 3.19. Multiple Bridge, Multiple VLAN, and Bond Configuration
3.1. Network Architecture
Red Hat Enterprise Virtualization networking can be discussed in terms of basic networking, networking within a cluster, and host networking configurations. Basic networking terms cover the basic hardware and software elements that facilitate networking. Networking within a cluster includes network interactions among cluster level objects such as hosts, logical networks and virtual machines. Host networking configurations covers supported configurations for networking within a host.
A well designed and built network ensures, for example, that high bandwidth tasks receive adequate bandwidth, that user interactions are not crippled by latency, and virtual machines can be successfully migrated within a migration domain. A poorly built network can cause, for example, unacceptable latency, and migration and cloning failures resulting from network flooding.
3.2. Introduction: Basic Networking Terms
Red Hat Enterprise Virtualization provides networking functionality between virtual machines, virtualization hosts, and wider networks using:
- A Network Interface Controller (NIC)
- A Bridge
- A Bond
- A Virtual NIC
- A Virtual LAN (VLAN)
NICs, bridges, and VNICs allow for network communication between hosts, virtual machines, local area networks, and the Internet. Bonds and VLANs are optionally implemented to enhance security, fault tolerance, and network capacity.
3.3. Network Interface Controller
The NIC (Network Interface Controller) is a network adapter or LAN adapter that connects a computer to a computer network. The NIC operates on both the physical and data link layers of the machine and allows network connectivity. All virtualization hosts in a Red Hat Enterprise Virtualization environment have at least one NIC, though it is more common for a host to have two or more NICs.
One physical NIC can have multiple Virtual NICs (VNICs) logically connected to it. A virtual NIC acts as a physical network interface for a virtual machine. To distinguish between a VNIC and the NIC that supports it, the Red Hat Enterprise Virtualization Manager assigns each VNIC a unique MAC address.
3.4. Bridge
A Bridge is a software device that uses packet forwarding in a packet-switched network. Bridging allows multiple network interface devices to share the connectivity of one NIC and appear on a network as separate physical devices. The bridge examines a packet's source addresses to determine relevant target addresses. Once the target address is determined, the bridge adds the location to a table for future reference. This allows a host to redirect network traffic to virtual machine associated VNICs that are members of a bridge.
In Red Hat Enterprise Virtualization a logical network is implemented using a bridge. It is the bridge rather than the physical interface on a host that receives an IP address. The IP address associated with the bridge is not required to be within the same subnet as the virtual machines that use the bridge for connectivity. If the bridge is assigned an IP address on the same subnet as the virtual machines that use it, the host is addressable within the logical network by virtual machines. As a rule it is not recommended to run network exposed services on a Red Hat Enterprise Virtualization host. Guests are connected to a logical network by their VNICs, and the host is connected to remote elements of the logical network using its NIC. Each guest can have the IP address of its VNIC set independently, by DHCP or statically. Bridges can connect to objects outside the host, but such a connection is not mandatory.
Custom properties can be defined for both the bridge and the Ethernet connection. VDSM passes the network definition and custom properties to the setup network hook script.
3.5. Bonds
A bond is an aggregation of multiple network interface cards into a single software-defined device. Because bonded network interfaces combine the transmission capability of the network interface cards included in the bond to act as a single network interface, they can provide greater transmission speed than that of a single network interface card. Also, because all network interface cards in the bond must fail for the bond itself to fail, bonding provides increased fault tolerance. However, one limitation is that the network interface cards that form a bonded network interface must be of the same make and model to ensure that all network interface cards in the bond support the same options and modes.
The packet dispersal algorithm for a bond is determined by the bonding mode used.
Important
Modes 1, 2, 3 and 4 support both virtual machine (bridged) and non-virtual machine (bridgeless) network types. Modes 0, 5 and 6 support non-virtual machine (bridgeless) networks only.
Bonding Modes
Red Hat Enterprise Virtualization uses Mode 4 by default, but supports the following common bonding modes:
Mode 0 (round-robin policy)- Transmits packets through network interface cards in sequential order. Packets are transmitted in a loop that begins with the first available network interface card in the bond and end with the last available network interface card in the bond. All subsequent loops then start with the first available network interface card. Mode 0 offers fault tolerance and balances the load across all network interface cards in the bond. However, Mode 0 cannot be used in conjunction with bridges, and is therefore not compatible with virtual machine logical networks.
Mode 1 (active-backup policy)- Sets all network interface cards to a backup state while one network interface card remains active. In the event of failure in the active network interface card, one of the backup network interface cards replaces that network interface card as the only active network interface card in the bond. The MAC address of the bond in Mode 1 is visible on only one port to prevent any confusion that might otherwise be caused if the MAC address of the bond changed to reflect that of the active network interface card. Mode 1 provides fault tolerance and is supported in Red Hat Enterprise Virtualization.
Mode 2 (XOR policy)- Selects the network interface card through which to transmit packets based on the result of an XOR operation on the source and destination MAC addresses modulo network interface card slave count. This calculation ensures that the same network interface card is selected for each destination MAC address used. Mode 2 provides fault tolerance and load balancing and is supported in Red Hat Enterprise Virtualization.
Mode 3 (broadcast policy)- Transmits all packets to all network interface cards. Mode 3 provides fault tolerance and is supported in Red Hat Enterprise Virtualization.
Mode 4 (IEEE 802.3ad policy)- Creates aggregation groups in which the interfaces share the same speed and duplex settings. Mode 4 uses all network interface cards in the active aggregation group in accordance with the IEEE 802.3ad specification and is supported in Red Hat Enterprise Virtualization.
Mode 5 (adaptive transmit load balancing policy)- Ensures the distribution of outgoing traffic accounts for the load on each network interface card in the bond and that the current network interface card receives all incoming traffic. If the network interface card assigned to receive traffic fails, another network interface card is assigned to the role of receiving incoming traffic. Mode 5 cannot be used in conjunction with bridges, therefore it is not compatible with virtual machine logical networks.
Mode 6 (adaptive load balancing policy)- Combines Mode 5 (adaptive transmit load balancing policy) with receive load balancing for IPv4 traffic without any special switch requirements. ARP negotiation is used for balancing the receive load. Mode 6 cannot be used in conjunction with bridges, therefore it is not compatible with virtual machine logical networks.
3.6. Switch Configuration for Bonding
Switch configurations vary per the requirements of your hardware. Refer to the deployment and networking configuration guides for your operating system.
Important
For every type of switch it is important to set up the switch bonding with the Link Aggregation Control Protocol (LACP) protocol and not the Cisco Port Aggregation Protocol (PAgP) protocol.
3.7. Virtual Network Interface Cards
Virtual network interface cards are virtual network interfaces that are based on the physical network interface cards of a host. Each host can have multiple network interface cards, and each network interface card can be a base for multiple virtual network interface cards.
When you attach a virtual network interface card to a virtual machine, the Red Hat Enterprise Virtualization Manager creates several associations between the virtual machine to which the virtual network interface card is being attached, the virtual network interface card itself, and the physical host network interface card on which the virtual network interface card is based. Specifically, when a virtual network interface card is attached to a virtual machine, a new virtual network interface card and MAC address are created on the physical host network interface card on which the virtual network interface card is based. Then, the first time the virtual machine starts after that virtual network interface card is attached,
libvirt assigns the virtual network interface card a PCI address. The MAC address and PCI address are then used to obtain the name of the virtual network interface card (for example, eth0) in the virtual machine.
The process for assigning MAC addresses and associating those MAC addresses with PCI addresses is slightly different when creating virtual machines based on templates or snapshots. When PCI addresses have already been created for a template or snapshot, the virtual network interface cards on virtual machines created based on that template or snapshot are ordered in accordance with those PCI addresses and MAC addresses allocated in that order. If PCI addresses have not already been created for a template, the virtual network interface cards on virtual machines created based on that template are allocated in the order of the naming of the virtual network interface cards. If PCI addresses have not already been created for a snapshot, the Red Hat Enterprise Virtualization Manager allocates new MAC addresses to the virtual network interface cards on virtual machines based on that snapshot.
Once created, virtual network interface cards are added to a network bridge device. The network bridge devices are how virtual machines are connected to virtual machine logical networks.
Running the
ip addr show command on a Red Hat Enterprise Virtualization host shows all of the virtual network interface cards that are associated with virtual machines on that host. Also visible are any network bridges that have been created to back logical networks, and any network interface cards used by the host.
[root@rhev-host-01 ~]# ip addr show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 16436 qdisc noqueue state UNKNOWN
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
link/ether 00:21:86:a2:85:cd brd ff:ff:ff:ff:ff:ff
inet6 fe80::221:86ff:fea2:85cd/64 scope link
valid_lft forever preferred_lft forever
3: wlan0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc mq state DOWN qlen 1000
link/ether 00:21:6b:cc:14:6c brd ff:ff:ff:ff:ff:ff
5: ;vdsmdummy;: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN
link/ether 4a:d5:52:c2:7f:4b brd ff:ff:ff:ff:ff:ff
6: bond0: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
7: bond4: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
8: bond1: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
9: bond2: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
10: bond3: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN
link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
11: rhevm: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN
link/ether 00:21:86:a2:85:cd brd ff:ff:ff:ff:ff:ff
inet 10.64.32.134/23 brd 10.64.33.255 scope global rhevm
inet6 fe80::221:86ff:fea2:85cd/64 scope link
valid_lft forever preferred_lft forever
The console output from the command shows eleven devices: one loop back device (
lo), one Ethernet device (eth0), one wireless device (wlan0), one VDSM dummy device (;vdsmdummy;), five bond devices (bond0, bond4, bond1, bond2, bond3), and one network bridge (rhevm).
Virtual network interface cards are all members of a network bridge device and logical network. Bridge membership can be displayed using the
brctl show command:
[root@rhev-host-01 ~]# brctl show bridge name bridge id STP enabled interfaces rhevm 8000.e41f13b7fdd4 no vnet002 vnet001 vnet000 eth0
The console output from the
brctl show command shows that the virtio virtual network interface cards are members of the rhevm bridge. All of the virtual machines that the virtual network interface cards are associated with are connected to the rhevm logical network. The eth0 network interface card is also a member of the rhevm bridge. The eth0 device is cabled to a switch that provides connectivity beyond the host.
3.8. Virtual LAN (VLAN)
A VLAN (Virtual LAN) is an attribute that can be applied to network packets. Network packets can be "tagged" into a numbered VLAN. A VLAN is a security feature used to completely isolate network traffic at the switch level. VLANs are completely separate and mutually exclusive. The Red Hat Enterprise Virtualization Manager is VLAN aware and able to tag and redirect VLAN traffic, however VLAN implementation requires a switch that supports VLANs.
At the switch level, ports are assigned a VLAN designation. A switch applies a VLAN tag to traffic originating from a particular port, marking the traffic as part of a VLAN, and ensures that responses carry the same VLAN tag. A VLAN can extend across multiple switches. VLAN tagged network traffic on a switch is completely undetectable except by machines connected to a port designated with the correct VLAN. A given port can be tagged into multiple VLANs, which allows traffic from multiple VLANs to be sent to a single port, to be deciphered using software on the machine that receives the traffic.
3.9. Cluster Networking
Cluster level networking objects include:
- Clusters
- Logical Networks
A data center is a logical grouping of multiple clusters and each cluster is a logical group of multiple hosts. Figure 3.1, “Networking within a cluster” depicts the contents of a single cluster.
Hosts in a cluster all have access to the same storage domains. Hosts in a cluster also have logical networks applied at the cluster level. For a virtual machine logical network to become operational for use with virtual machines, the network must be defined and implemented for each host in the cluster using the Red Hat Enterprise Virtualization Manager. Other logical network types can be implemented on only the hosts that use them.
Multi-host network configuration is available on data centers with 3.1-or-higher compatibility, and automatically applies any updated network settings to all of the hosts within the data center to which the network is assigned.
3.10. Logical Networks
Logical networking allows the Red Hat Enterprise Virtualization environment to separate network traffic by type. For example, the
rhevm network is created by default during the installation of the Red Hat Enterprise Virtualization to be used for management communication between the Manager and hosts. A typical use for logical networks is to group network traffic with similar requirements and usage together. In many cases, a storage network and a display network are created by an administrator to isolate traffic of each respective type for optimization and troubleshooting.
The types of logical network are:
- logical networks that carry virtual machine network traffic,
- logical networks that do not carry virtual machine network traffic,
- optional logical networks,
- and required networks.
All logical networks can either be required or optional.
Logical networks are defined at the data center level, and added to a host. For a required logical network to be operational, it must be implemented for every host in a given cluster.
Each virtual machine logical network in a Red Hat Enterprise Virtualization environment is backed by a network bridge device on a host. So when a new virtual machine logical network is defined for a cluster, a matching bridge device must be created on each host in the cluster before the logical network can become operational to be used by virtual machines. Red Hat Enterprise Virtualization Manager automatically creates required bridges for virtual machine logical networks.
The bridge device created by the Red Hat Enterprise Virtualization Manager to back a virtual machine logical network is associated with a host network interface. If the host network interface that is part of a bridge has network connectivity, then any network interfaces that are subsequently included in the bridge share the network connectivity of the bridge. When virtual machines are created and placed on a particular logical network, their virtual network cards are included in the bridge for that logical network. Those virtual machines can then communicate with each other and with other objects that are connected to the bridge.
Logical networks not used for virtual machine network traffic are associated with host network interfaces directly.
Example 3.1. Example usage of a logical network.
There are two hosts called Red and White in a cluster called Pink in a data center called Purple. Both Red and White have been using the default logical network,
rhevm for all networking functions. The system administrator responsible for Pink decides to isolate network testing for a web server by placing the web server and some client virtual machines on a separate logical network. She decides to call the new logical network network_testing.
First, she defines the logical network for the Purple data center. She then applies it to the Pink cluster. Logical networks must be implemented on a host in maintenance mode. So, the administrator first migrates all running virtual machines to Red, and puts White in maintenance mode. Then she edits the Network associated with the physical network interface that will be included in the bridge. The Link Status for the selected network interface will change from Down to Non-Operational. The non-operational status is because the corresponding bridge must be setup in all hosts in the cluster by adding a physical network interface on each host in the Pink cluster to the
network_testing network. Next she activates White, migrates all of the running virtual machines off of Red, and repeats the process for Red.
When both White and Red both have the
network_testing logical network bridged to a physical network interface, the network_testing logical network becomes Operational and is ready to be used by virtual machines.
3.11. Required Networks, Optional Networks, and Virtual Machine Networks
A required network is a logical network that must be available to all hosts in a cluster. When a host's required network becomes non-operational, virtual machines running on that host are migrated to another host; the extent of this migration is dependent upon the chosen scheduling policy. This is beneficial if you have virtual machines running mission critical workloads.
An optional network is a logical network that has not been explicitly declared as Required. Optional networks can be implemented on only the hosts that use them. The presence or absence of optional networks does not affect the Operational status of a host. When a non-required network becomes non-operational, the virtual machines running on the network are not migrated to another host. This prevents unnecessary I/O overload caused by mass migrations. Note that when a logical network is created and added to clusters, the Required box is checked by default.
To change a network's Required designation, from the Administration Portal, select a network, click the Cluster tab, and click the button.
Virtual machine networks (called a VM network in the user interface) are logical networks designated to carry only virtual machine network traffic. Virtual machine networks can be required or optional. Virtual machines that uses an optional virtual machine network will only start on hosts with that network.
3.12. Virtual Machine Connectivity
In Red Hat Enterprise Virtualization, a virtual machine has its NIC put on a logical network at the time that the virtual machine is created. From that point, the virtual machine is able to communicate with any other destination on the same network.
From the host perspective, when a virtual machine is put on a logical network, the VNIC that backs the virtual machine's NIC is added as a member to the bridge device for the logical network. For example, if a virtual machine is on the
rhevm logical network, its VNIC is added as a member of the rhevm bridge of the host on which that virtual machine runs.
3.13. Port Mirroring
Port mirroring copies layer 3 network traffic on a given logical network and host to a virtual interface on a virtual machine. This virtual machine can be used for network debugging and tuning, intrusion detection, and monitoring the behavior of other virtual machines on the same host and logical network.
The only traffic copied is internal to one logical network on one host. There is no increase on traffic on the network external to the host; however a virtual machine with port mirroring enabled uses more host CPU and RAM than other virtual machines.
Port mirroring is enabled or disabled in the vNIC profiles of logical networks, and has the following requirements and limitations:
- Port mirroring requires an IPv4 IP address.
- Hot plugging profiles with port mirroring is not supported.
- Port mirroring cannot be altered when the vNIC profile is attached to a virtual machine.
Given the above limitations, it is recommended that you enable port mirroring on an additional, dedicated vNIC profile.
Important
Enabling port mirroring reduces the privacy of other network users.
3.14. Host Networking Configurations
Common types of networking configurations for Red Hat Enterprise Virtualization hosts include:
- Bridge and NIC configuration.
- Bridge, VLAN, and NIC configuration.
- Bridge, Bond, and VLAN configuration.
- Multiple Bridge, Multiple VLAN, and NIC configuration.
3.15. Bridge Configuration
The simplest host configuration in Red Hat Enterprise Virtualization is the Bridge and NIC configuration. As Figure 3.3, “Bridge and NIC configuration” depicts, this configuration uses a bridge to connect one or more virtual machines (or guests) to the host's NIC.
An example of this configuration is the automatic creation of the bridge
rhevm when the Red Hat Enterprise Virtualization Manager installs. On installation, the Red Hat Enterprise Virtualization Manager installs VDSM on the host. The VDSM installation process creates the bridge rhevm. The rhevm bridge then obtains the IP address of the host to enable management communication for the host.
3.16. VLAN Configuration
Figure 3.4, “Bridge, VLAN, and NIC configuration” depicts an alternative configuration that includes a virtual LAN (VLAN) to connect the host NIC and bridge.
A VLAN is included to provide a secure channel for data transfer over this network and also to support the option to connect multiple bridges to a single NIC using multiple VLANs.
3.17. Bridge and Bond Configuration
Figure 3.5, “Bridge, Bond, and NIC configuration” displays a configuration that includes a bond to connect multiple host NICs to the same bridge and network.
The included bond creates a logical link that combines the two (or more) physical Ethernet links. The resultant benefits include NIC fault tolerance and potential bandwidth extension, depending on the bonding mode.
3.18. Multiple Bridge, Multiple VLAN, and NIC Configuration
Figure 3.6, “Multiple Bridge, Multiple VLAN, and NIC configuration” depicts a configuration that connects a single NIC to two VLANs. This presumes that the network switch has been configured to pass network traffic that has been tagged into one of the two VLANs to one NIC on the host. The host uses two VNICs to separate VLAN traffic, one for each VLAN. Traffic tagged into either VLAN then connects to a separate bridge by having the appropriate VNIC as a bridge member. Each bridge is in turn connected to by multiple virtual machines.
3.19. Multiple Bridge, Multiple VLAN, and Bond Configuration
Figure 3.7, “Multiple Bridge, Multiple VLAN, and Multiple NIC with Bond connection” displays a configuration that bonds multiple NICs to facilitate a connection with multiple VLANs.
Each VLAN in this configuration is defined over the bond connecting the NICs. Each VLAN connects to an individual bridge and each bridge connects to one or more guests.
Chapter 4. Power Management
4.1. Introduction to Power Management and Fencing
The Red Hat Enterprise Virtualization environment is most flexible and resilient when power management and fencing have been configured. Power management allows the Red Hat Enterprise Virtualization Manager to control host power cycle operations, most importantly to reboot hosts on which problems have been detected. Fencing is used to isolate problem hosts from a functional Red Hat Enterprise Virtualization environment by rebooting them, in order to prevent performance degradation. Fenced hosts can then be returned to responsive status through administrator action and be reintegrated into the environment.
Power management and fencing make use of special dedicated hardware in order to restart hosts independently of host operating systems. The Red Hat Enterprise Virtualization Manager connects to a power management devices using a network IP address or hostname. In the context of Red Hat Enterprise Virtualization, a power management device and a fencing device are the same thing.
4.2. Power Management by Proxy in Red Hat Enterprise Virtualization
The Red Hat Enterprise Virtualization Manager does not communicate directly with fence agents. Instead, the Manager uses a proxy to send power management commands to a host power management device. The Manager uses VDSM to execute power management device actions, so another host in the environment is used as a fencing proxy.
You can select between:
- Any host in the same cluster as the host requiring fencing.
- Any host in the same data center as the host requiring fencing.
A viable fencing proxy host has a status of either UP or Maintenance.
4.3. Power Management
The Red Hat Enterprise Virtualization Manager is capable of rebooting hosts that have entered a non-operational or non-responsive state, as well as preparing to power off under-utilized hosts to save power. This functionality depends on a properly configured power management device. The Red Hat Enterprise Virtualization environment supports the following power management devices:
- American Power Conversion (apc).
- Bladecenter.
- Cisco Unified Computing System (cisco_ucs).
- Dell Remote Access Card 5 (drac5).
- Dell Remote Access Card 7 (drac7).
- Electronic Power Switch (eps).
- HP BladeSystem (hpblade).
- Integrated Lights Out (ilo, ilo2, ilo3, ilo4).
- Intelligent Platform Management Interface (ipmilan).
- Remote Supervisor Adapter (rsa).
- rsb.
- Western Telematic, Inc (wti).
Note
APC 5.x power management devices are not supported by the apc fence agent. Use the apc_snmp fence agent instead.
In order to communicate with the listed power management devices, the Red Hat Enterprise Virtualization Manager makes use of fence agents. The Red Hat Enterprise Virtualization Manager allows administrators to configure a fence agent for the power management device in their environment with parameters the device will accept and respond to. Basic configuration options can be configured using the graphical user interface. Special configuration options can also be entered, and are passed un-parsed to the fence device. Special configuration options are specific to a given fence device, while basic configuration options are for functionalities provided by all supported power management devices. The basic functionalities provided by all power management devices are:
- Status: check the status of the host.
- Start: power on the host.
- Stop: power down the host.
- Restart: restart the host. Actually implemented as stop, wait, status, start, wait, status.
Best practice is to test the power management configuration once when initially configuring it, and occasionally after that to ensure continued functionality.
Resilience is provided by properly configured power management devices in all of the hosts in an environment. Fencing agents allow the Red Hat Enterprise Virtualization Manager to communicate with host power management devices to bypass the operating system on a problem host, and isolate the host from the rest of its environment by rebooting it. The Manager can then reassign the SPM role, if it was held by the problem host, and safely restart any highly available virtual machines on other hosts.
4.4. Fencing
In the context of the Red Hat Enterprise Virtualization environment, fencing is a host reboot initiated by the Manager using a fence agent and performed by a power management device. Fencing allows a cluster to react to unexpected host failures as well as enforce power saving, load balancing, and virtual machine availability policies.
Fencing ensures that the role of Storage Pool Manager (SPM) is always assigned to a functional host. If the fenced host was the SPM, the SPM role is relinquished and reassigned to a responsive host. Because the host with the SPM role is the only host that is able to write data domain structure metadata, a non-responsive, un-fenced SPM host causes its environment to lose the ability to create and destroy virtual disks, take snapshots, extend logical volumes, and all other actions that require changes to data domain structure metadata.
When a host becomes non-responsive, all of the virtual machines that are currently running on that host can also become non-responsive. However, the non-responsive host retains the lock on the virtual machine hard disk images for virtual machines it is running. Attempting to start a virtual machine on a second host and assign the second host write privileges for the virtual machine hard disk image can cause data corruption.
Fencing allows the Red Hat Enterprise Virtualization Manager to assume that the lock on a virtual machine hard disk image has been released; the Manager can use a fence agent to confirm that the problem host has been rebooted. When this confirmation is received, the Red Hat Enterprise Virtualization Manager can start a virtual machine from the problem host on another host without risking data corruption. Fencing is the basis for highly-available virtual machines. A virtual machine that has been marked highly-available can not be safely started on an alternate host without the certainty that doing so will not cause data corruption.
When a host becomes non-responsive, the Red Hat Enterprise Virtualization Manager allows a grace period of thirty (30) seconds to pass before any action is taken, to allow the host to recover from any temporary errors. If the host has not become responsive by the time the grace period has passed, the Manager automatically begins to mitigate any negative impact from the non-responsive host. The Manager uses the fencing agent for the power management card on the host to stop the host, confirm it has stopped, start the host, and confirm that the host has been started. When the host finishes booting, it attempts to rejoin the cluster that it was a part of before it was fenced. If the issue that caused the host to become non-responsive has been resolved by the reboot, then the host is automatically set to Up status and is once again capable of starting and hosting virtual machines.
4.5. Soft-Fencing Hosts
Hosts can sometimes become non-responsive due to an unexpected problem, and though VDSM is unable to respond to requests, the virtual machines that depend upon VDSM remain alive and accessible. In these situations, restarting VDSM returns VDSM to a responsive state and resolves this issue.
Red Hat Enterprise Virtualization 3.3 introduced "soft-fencing over SSH". Prior to Red Hat Enterprise Virtualization 3.3, non-responsive hosts were fenced only by external fencing devices. In Red Hat Enterprise Virtualization 3.3 and above, the fencing process has been expanded to include "SSH Soft Fencing", a process where the Manager attempts to restart VDSM via SSH on non-responsive hosts. If the Manager fails to restart VDSM via SSH, the responsibility for fencing falls to the external fencing agent if an external fencing agent has been configured.
Soft-fencing over SSH works as follows. Fencing must be configured and enabled on the host, and a valid proxy host (a second host, in an UP state, in the data center) must exist. When the connection between the Manager and the host times out, the following happens:
- On the first network failure, the status of the host changes to "connecting".
- The Manager then makes three attempts to ask VDSM for its status, or it waits for an interval determined by the load on the host. The formula for determining the length of the interval is configured by the configuration values TimeoutToResetVdsInSeconds (the default is 60 seconds) + [DelayResetPerVmInSeconds (the default is 0.5 seconds)]*(the count of running virtual machines on host) + [DelayResetForSpmInSeconds (the default is 20 seconds)] * 1 (if host runs as SPM) or 0 (if the host does not run as SPM). To give VDSM the maximum amount of time to respond, the Manager chooses the longer of the two options mentioned above (three attempts to retrieve the status of VDSM or the interval determined by the above formula).
- If the host does not respond when that interval has elapsed,
vdsm restartis executed via SSH. - If
vdsm restartdoes not succeed in re-establishing the connection between the host and the Manager, the status of the host changes toNon Responsiveand, if power management is configured, fencing is handed off to the external fencing agent.
Note
Soft-fencing over SSH can be executed on hosts that have no power management configured. This is distinct from "fencing": fencing can be executed only on hosts that have power management configured.
4.6. Using Multiple Power Management Fencing Agents
Prior to Red Hat Enterprise Virtualization 3.2, a host with power management configured only recognized one fencing agent. Fencing agents configured on version 3.1 and earlier, and single agents, are treated as primary agents. The secondary agent is valid when there are two fencing agents, for example for dual-power hosts in which each power switch has two agents connected to the same power switch. Agents can be of the same or different types.
Having multiple fencing agents on a host increases the reliability of the fencing procedure. For example, when the sole fencing agent on a host fails, the host will remain in a non-operational state until it is manually rebooted. The virtual machines previously running on the host will be suspended, and only fail over to another host in the cluster after the original host is manually fenced. With multiple agents, if the first agent fails, the next agent can be called.
When two fencing agents are defined on a host, they can be configured to use a concurrent or sequential flow:
- Concurrent: Both primary and secondary agents have to respond to the Stop command for the host to be stopped. If one agent responds to the Start command, the host will go up.
- Sequential: To stop or start a host, the primary agent is used first, and if it fails, the secondary agent is used.
Chapter 5. Load Balancing, Scheduling, and Migration
- 5.1. Load Balancing, Scheduling, and Migration
- 5.2. Load Balancing Policy
- 5.3. Load Balancing Policy: VM_Evenly_Distributed
- 5.4. Load Balancing Policy: Evenly_Distributed
- 5.5. Load Balancing Policy: Power_Saving
- 5.6. Load Balancing Policy: None
- 5.7. Highly Available Virtual Machine Reservation
- 5.8. Scheduling
- 5.9. Migration
5.1. Load Balancing, Scheduling, and Migration
Individual hosts have finite hardware resources, and are susceptible to failure. To mitigate against failure and resource exhaustion, hosts are grouped into clusters, which are essentially a grouping of shared resources. A Red Hat Enterprise Virtualization environment responds to changes in demand for host resources using load balancing policy, scheduling, and migration. The Manager is able to ensure that no single host in a cluster is responsible for all of the virtual machines in that cluster. Conversely, the Manager is able to recognize an underutilized host, and migrate all virtual machines off of it, allowing an administrator to shut down that host to save power.
Available resources are checked as a result of three events:
- Virtual machine start - Resources are checked to determine on which host a virtual machine will start.
- Virtual machine migration - Resources are checked in order to determine an appropriate target host.
- Time elapses - Resources are checked at a regular interval to determine whether individual host load is in compliance with cluster load balancing policy.
The Manager responds to changes in available resources by using the load balancing policy for a cluster to schedule the migration of virtual machines from one host in a cluster to another. The relationship between load balancing policy, scheduling, and virtual machine migration are discussed in the following sections.
5.2. Load Balancing Policy
Load balancing policy is set for a cluster, which includes one or more hosts that may each have different hardware parameters and available memory. The Red Hat Enterprise Virtualization Manager uses a load balancing policy to determine which host in a cluster to start a virtual machine on. Load balancing policy also allows the Manager determine when to move virtual machines from over-utilized hosts to under-utilized hosts.
The load balancing process runs once every minute for each cluster in a data center. It determines which hosts are over-utilized, which are hosts under-utilized, and which are valid targets for virtual machine migration. The determination is made based on the load balancing policy set by an administrator for a given cluster. The options for load balancing policies are VM_Evenly_Distributed, Evenly_Distributed, Power_Saving, and None.
5.3. Load Balancing Policy: VM_Evenly_Distributed
A virtual machine evenly distributed load balancing policy distributes virtual machines evenly between hosts based on a count of the virtual machines. The high virtual machine count is the maximum number of virtual machines that can run on each host, beyond which qualifies as overloading the host. The VM_Evenly_Distributed policy allows an administrator to set a high virtual machine count for hosts. The maximum inclusive difference in virtual machine count between the most highly-utilized host and the least-utilized host is also set by an administrator. The cluster is balanced when every host in the cluster has a virtual machine count that falls inside this migration threshold. The administrator also sets the number of slots for virtual machines to be reserved on SPM hosts. The SPM host will have a lower load than other hosts, so this variable defines how many fewer virtual machines than other hosts it can run. If any host is running more virtual machines than the high virtual machine count and at least one host has a virtual machine count that falls outside of the migration threshold, virtual machines are migrated one by one to the host in the cluster that has the lowest CPU utilization. One virtual machine is migrated at a time until every host in the cluster has a virtual machine count that falls within the migration threshold.
5.4. Load Balancing Policy: Evenly_Distributed
An evenly distributed load balancing policy selects the host for a new virtual machine according to lowest CPU utilization. The maximum service level is the maximum CPU utilization that is allowed for hosts in a cluster, beyond which environment performance will degrade. The Evenly_Distributed policy allows an administrator to set a maximum service level for running virtual machines. The length of time a host is allowed to continue at this maximum service level before the Red Hat Enterprise Virtualization Manager intervenes is also set by an administrator. If a host has reached the maximum service level and stays there for more than the set time, virtual machines on that host are migrated one by one to the host in the cluster that has the lowest CPU utilization. Host resources are checked once per minute, and one virtual machine is migrated at a time until the host CPU utilization is below the maximum service threshold.
5.5. Load Balancing Policy: Power_Saving
A power saving load balancing policy selects the host for a new virtual machine according to lowest CPU utilization. The maximum service level is the maximum CPU utilization that is allowed for hosts in a cluster, beyond which environment performance will degrade. The minimum service level is the minimum CPU utilization allowed before the continued operation of a host is considered an inefficient use of electricity. The Power_Saving policy allows an administrator to set a maximum and minimum service level for running virtual machines. The length of time a host is allowed to continue at this maximum or minimum service level before the Red Hat Enterprise Virtualization Manager intervenes is also set by an administrator. If a host has reached the maximum service level and stays there for more than the set time, the virtual machines on that host are migrated one by one to the host that has the lowest CPU utilization. The process continues until the host CPU utilization is below maximum service level. If a host CPU utilization falls below the minimum service level the virtual machines are migrated to other hosts in the cluster if their maximum service level permits. When an under-utilized host is cleared of its remaining virtual machines, the Manager will automatically power down the host machine, and restart it again when load balancing requires or there are not enough free hosts in the cluster.
5.6. Load Balancing Policy: None
If no load balancing policy is selected, virtual machines are started on the host within a cluster with the lowest CPU utilization and available memory. To determine CPU utilization a combined metric is used that takes into account the virtual CPU count and the CPU usage percent. This approach is the least dynamic, as the only host selection point is when a new virtual machine is started. Virtual machines are not automatically migrated to reflect increased demand on a host.
An administrator must decide which host is an appropriate migration target for a given virtual machine. Virtual machines can also be associated with a particular host using pinning. Pinning prevents a virtual machine from being automatically migrated to other hosts. For environments where resources are highly consumed, manual migration is the best approach.
5.7. Highly Available Virtual Machine Reservation
A highly available (HA) virtual machine reservation policy enables the Red Hat Enterprise Virtualization Manager to monitor cluster capacity for highly available virtual machines. The Manager has the capability to flag individual virtual machines for High Availability, meaning that in the event of a host failure, these virtual machines will be rebooted on an alternative hypervisor host. This policy balances highly available virtual machines across the hosts in a cluster. If any host in the cluster fails, the remaining hosts can support the migrating load of highly available virtual machines without affecting cluster performance. When highly available virtual machine reservation is enabled, the Manager ensures that appropriate capacity exists within a cluster for HA virtual machines to migrate in the event that their existing host fails unexpectedly.
5.8. Scheduling
In Red Hat Enterprise Virtualization, scheduling refers to the way the Red Hat Enterprise Virtualization Manager selects a host in a cluster as the target for a new or migrated virtual machine.
For a host to be eligible to start a virtual machine or accept a migrated virtual machine from another host, it must have enough free memory and CPUs to support the requirements of the virtual machine being started on or migrated to it. If multiple hosts are eligible targets, one will be selected based on the load balancing policy for the cluster. For example, if the Evenly_Distributed policy is in effect, the Manager chooses the host with the lowest CPU utilization. If the Power_Saving policy is in effect, the host with the lowest CPU utilization between the maximum and minimum service levels will be selected. The Storage Pool Manager (SPM) status of a given host also affects eligibility as a target for starting virtual machines or virtual machine migration. A non-SPM host is a preferred target host, for instance, the first virtual machine started in a cluster will not run on the SPM host if the SPM role is held by a host in that cluster.
5.9. Migration
The Red Hat Enterprise Virtualization Manager uses migration to enforce load balancing policies for a cluster. Virtual machine migration takes place according to the load balancing policy for a cluster and current demands on hosts within a cluster. Migration can also be configured to automatically occur when a host is fenced or moved to maintenance mode. The Red Hat Enterprise Virtualization Manager first migrates virtual machines with the lowest CPU utilization. This is calculated as a percentage, and does not take into account RAM usage or I/O operations, except as I/O operations affect CPU utilization. If there are more than one virtual machines with the same CPU usage, the one that will be migrated first is the first virtual machine returned by the database query run by the Red Hat Enterprise Virtualization Manager to determine virtual machine CPU usage.
Virtual machine migration has the following limitations by default:
See https://access.redhat.com/solutions/744423 for more details about tuning migration settings.
- A bandwidth limit of 32 MiBps (megabytes per second) is imposed on each virtual machine migration.
- A migration will time out after 64 seconds per GB of virtual machine memory.
- A migration will abort if progress is stalled for 150 seconds.
- Concurrent outgoing migrations are limited to one per CPU core per host, or 3, whichever is smaller.
Chapter 6. Directory Services
6.1. Directory Services
The Red Hat Enterprise Virtualization platform relies on directory services for user authentication and authorization. Interactions with all Manager interfaces, including the User Portal, Administration Portal, and REST API are limited to authenticated, authorized users. Virtual machines within the Red Hat Enterprise Virtualization environment can use the same directory services to provide authentication and authorization, however they must be configured to do so. The currently supported providers of directory services for use with the Red Hat Enterprise Virtualization Manager are Identity Management (IdM), Red Hat Directory Server 9 (RHDS), Active Directory (AD), and OpenLDAP. The Red Hat Enterprise Virtualization Manager interfaces with the directory server for:
- Portal logins (User, Power User, Administrator, REST API).
- Queries to display user information.
- Adding the Manager to a domain.
Authentication is the verification and identification of a party who generated some data, and of the integrity of the generated data. A principal is the party whose identity is verified. The verifier is the party who demands assurance of the principal's identity. In the case of Red Hat Enterprise Virtualization, the Manager is the verifier and a user is a principal. Data integrity is the assurance that the data received is the same as the data generated by the principal.
Confidentiality and authorization are closely related to authentication. Confidentiality protects data from disclosure to those not intended to receive it. Strong authentication methods can optionally provide confidentiality. Authorization determines whether a principal is allowed to perform an operation. Red Hat Enterprise Virtualization uses directory services to associate users with roles and provide authorization accordingly. Authorization is usually performed after the principal has been authenticated, and may be based on information local or remote to the verifier.
During installation, a local, internal domain is automatically configured for administration of the Red Hat Enterprise Virtualization environment. After the installation is complete, more domains can be added.
6.2. Local Authentication: Internal Domain
The Red Hat Enterprise Virtualization Manager creates a limited, internal administration domain during installation. This domain is not the same as an AD or IdM domain, because it exists based on a key in the Red Hat Enterprise Virtualization PostgreSQL database rather than as a directory service user on a directory server. The internal domain is also different from an external domain because the internal domain will only have one user: the
admin@internal user. Taking this approach to initial authentication allows Red Hat Enterprise Virtualization to be evaluated without requiring a complete, functional directory server, and ensures an administrative account is available to troubleshoot any issues with external directory services.
The admin@internal user is for the initial configuration of an environment. This includes installing and accepting hosts, adding external AD or IdM authentication domains, and delegating permissions to users from external domains.
6.3. Remote Authentication Using GSSAPI
In the context of Red Hat Enterprise Virtualization, remote authentication refers to authentication that is handled remotely from the Red Hat Enterprise Virtualization Manager. Remote authentication is used for user or API connections coming to the Manager from within an AD, IdM, or RHDS domain. The Red Hat Enterprise Virtualization Manager must be configured by an administrator using the
engine-manage-domains tool to be a part of an RHDS, AD, or IdM domain. This requires that the Manager be provided with credentials for an account from the RHDS, AD, or IdM directory server for the domain with sufficient privileges to join a system to the domain. After domains have been added, domain users can be authenticated by the Red Hat Enterprise Virtualization Manager against the directory server using a password. The Manager uses a framework called the Simple Authentication and Security Layer (SASL) which in turn uses the Generic Security Services Application Program Interface (GSSAPI) to securely verify the identity of a user, and ascertain the authorization level available to the user.
Chapter 7. Templates and Pools
7.1. Templates and Pools
The Red Hat Enterprise Virtualization environment provides administrators with tools to simplify the provisioning of virtual machines to users. These are templates and pools. A template is a shortcut that allows an administrator to quickly create a new virtual machine based on an existing, pre-configured virtual machine, bypassing operating system installation and configuration. This is especially helpful for virtual machines that will be used like appliances, for example web server virtual machines. If an organization uses many instances of a particular web server, an administrator can create a virtual machine that will be used as a template, installing an operating system, the web server, any supporting packages, and applying unique configuration changes. The administrator can then create a template based on the working virtual machine that will be used to create new, identical virtual machines as they are required.
Virtual machine pools are groups of virtual machines based on a given template that can be rapidly provisioned to users. Permission to use virtual machines in a pool is granted at the pool level; a user who is granted permission to use the pool will be assigned any virtual machine from the pool. Inherent in a virtual machine pool is the transitory nature of the virtual machines within it. Because users are assigned virtual machines without regard for which virtual machine in the pool they have used in the past, pools are not suited for purposes which require data persistence. Virtual machine pools are best suited for scenarios where either user data is stored in a central location and the virtual machine is a means to accessing and using that data, or data persistence is not important. The creation of a pool results in the creation of the virtual machines that populate the pool, in a stopped state. These are then started on user request.
7.2. Templates
To create a template, an administrator creates and customizes a virtual machine. Desired packages are installed, customized configurations are applied, the virtual machine is prepared for its intended purpose in order to minimize the changes that must be made to it after deployment. An optional but recommended step before creating a template from a virtual machine is generalization. Generalization is used to remove details like system user names, passwords, and timezone information that will change upon deployment. Generalization does not affect customized configurations. Generalization of Windows and Linux guests in the Red Hat Enterprise Virtualization environment is discussed it the Red Hat Enterprise Virtualization Administration Guide. Red Hat Enterprise Linux guests are generalized using sys-unconfig. Windows guests are generalized using sys-prep.
When the virtual machine that provides the basis for a template is satisfactorily configured, generalized if desired, and stopped, an administrator can create a template from the virtual machine. Creating a template from a virtual machine causes a read only copy of the specially configured virtual machine disk image to be created. The read only image will form the backing image for all subsequently created virtual machines that are based on that template. In other words, a template is essentially a customized read only disk image with an associated virtual hardware configuration. The hardware can be changed in virtual machines created from a template, for instance provisioning two gigabytes of RAM for a virtual machine created from a template that has one gigabyte of RAM. The template disk image, however, can not be changed as doing so would result in changes for all virtual machines based on the template.
When a template has been created, it can be used as the basis for multiple virtual machines. Virtual machines are created from a given template using a Thin provisioning method or a Clone provisioning method. Virtual machines that are cloned from templates take a complete writable copy of the template base image, sacrificing the space savings of a the thin creation method in exchange for no longer depending on the presence of the template. Virtual machines that are created from a template using the thin method use the read only image from the template as a base image, requiring that the template and all virtual machines created from it be stored on the same storage domain. Changes to data and newly generated data are stored in a copy on write image. Each virtual machine based on a template uses the same base read only image, as well as a copy on write image that is unique to the virtual machine. This provides storage savings by limiting the number of times identical data is kept in storage. Furthermore, frequent use of the read only backing image can cause the data being accessed to be cached, resulting in a net performance increase.
7.3. Pools
Virtual machine pools allow for rapid provisioning of numerous identical virtual machines to users as desktops. Users who have been granted permission to access and use virtual machines from a pool receive an available virtual machine based on their position in a queue of requests. Virtual machines in a pool do not allow data persistence; each time a virtual machine is assigned from a pool, it is allocated in its base state. This is ideally suited to be used in situations where user data is stored centrally.
Virtual machine pools are created from a template. Each virtual machine in a pool uses the same backing read only image, and uses a temporary copy on write image to hold changed and newly generated data. Virtual machines in a pool are different from other virtual machines in that the copy on write layer that holds user generated and changed data is lost at shutdown. The implication of this is that a virtual machine pool requires no more storage than the template that backs it, plus some space for data generated or changed during use. Virtual machine pools are an efficient way to provide computing power to users for some tasks without the storage cost of providing each user with a dedicated virtual desktop.
Example 7.1. Example Pool Usage
A technical support company employs 10 help desk staff. However, only five are working at any given time. Instead of creating ten virtual machines, one for each help desk employee, a pool of five virtual machines can be created. Help desk employees allocate themselves a virtual machine at the beginning of their shift and return it to the pool at the end.
Chapter 8. Virtual Machine Snapshots
8.1. Snapshots
Snapshots are a storage function that allows an administrator to create a restore point of a virtual machine's operating system, applications, and data at a certain point in time. Snapshots save the data currently present in a virtual machine hard disk image as a COW volume and allow for a recovery to the data as it existed at the time the snapshot was taken. A snapshot causes a new COW layer to be created over the current layer. All write actions performed after a snapshot is taken are written to the new COW layer.
It is important to understand that a virtual machine hard disk image is a chain of one or more volumes. From the perspective of a virtual machine, these volumes appear as a single disk image. A virtual machine is oblivious to the fact that its disk is comprised of multiple volumes.
The term COW volume and COW layer are used interchangeably, however, layer more clearly recognizes the temporal nature of snapshots. Each snapshot is created to allow an administrator to discard unsatisfactory changes made to data after the snapshot is taken. Snapshots provide similar functionality to the Undo function present in many word processors.
Note
Snapshots of virtual machine hard disks marked shareable and those that are based on Direct LUN connections are not supported, live or otherwise.
The three primary snapshot operations are:
For task based information about snapshot operations, refer to the Red Hat Enterprise Virtualization Administration Guide.
- Creation, which involves the first snapshot created for a virtual machine.
- Previews, which involves previewing a snapshot to determine whether or not to restore the system data to the point in time that the snapshot was taken.
- Deletion, which involves deleting a restoration point that is no longer required.
8.2. Live Snapshots in Red Hat Enterprise Virtualization
In version 3.1, Red Hat Enterprise Virtualization introduced support for snapshots of running virtual machines.
Snapshots of virtual machine hard disks marked shareable and those that are based on Direct LUN connections are not supported, live or otherwise.
Any other virtual machine that is not being cloned or migrated can have a snapshot taken when running, paused, or stopped.
When a live snapshot of a virtual machine is initiated, the Manager requests that the SPM host create a new volume for the virtual machine to use. When the new volume is ready, the Manager uses VDSM to communicate with libvirt and qemu on the host running the virtual machine that it should begin using the new volume for virtual machine write operations. If the virtual machine is able to write to the new volume, the snapshot operation is considered a success and the virtual machine stops writing to the previous volume. If the virtual machine is unable to write to the new volume, the snapshot operation is considered a failure, and the new volume is deleted.
The virtual machine requires access to both its current volume and the new one from the time when a live snapshot is initiated until after the new volume is ready, so both volumes are opened with read-write access.
Virtual machines with an installed guest agent that supports quiescing can ensure filesystem consistency across snapshots. Registered Red Hat Enterprise Linux guests can install the
qemu-guest-agent to enable quiescing before snapshots.
If a quiescing compatible guest agent is present on a virtual machine when it a snapshot is taken, VDSM uses libvirt to communicate with the agent to prepare for a snapshot. Outstanding write actions are completed, and then filesystems are frozen before a snapshot is taken. When the snapshot is complete, and libvirt has switched the virtual machine to the new volume for disk write actions, the filesystem is thawed, and writes to disk resume.
All live snapshots attempted with quiescing enabled. If the snapshot command fails because there is no compatible guest agent present, the live snapshot is re-initiated without the use-quiescing flag. When a virtual machine is reverted to its pre-snapshot state with quiesced filesystems, it boots cleanly with no filesystem check required. Reverting the previous snapshot using an un-quiesced filesystem requires a filesystem check on boot.
8.3. Snapshot Creation
In Red Hat Enterprise Virtualization the initial snapshot for a virtual machine is different from subsequent snapshots in that the initial snapshot retains its format, either QCOW2 or RAW. The first snapshot for a virtual machine designates existing volumes as a base image. Additional snapshots are additional COW layers tracking the changes made to the data stored in the image since the previous snapshot.
In Red Hat Enterprise Virtualization, a guest virtual machine usually interacts with a RAW disk image unless the image is created as a thinly provisioned image or the user specifically asked for it to be QCOW2. As depicted in Figure 8.1, “Initial Snapshot Creation”, the creation of a snapshot causes the volumes that comprise a virtual machine disk image to serve as the base image for all subsequent snapshots.
Snapshots taken after the initial snapshot result in the creation of new COW volumes in which data that is created or changed after the snapshot is taken will be stored. Each new COW layer begins containing only COW metadata. Data that is created through virtual machine use and operation after a snapshot is written to a new COW layer. When a virtual machine is used to modify data that exists in a previous COW layer, the data is read from the previous layer, and written into the newest layer. Virtual machines locate data by checking each COW layer from most recent to oldest, transparently to the virtual machine.
8.4. Snapshot Previews
To select which snapshot a virtual machine disk image will be reverted to, the administrator can preview all previously created snapshots.
From the available snapshots per guest, the administrator can select a snapshot volume to preview its contents. As depicted in Figure 8.3, “Preview Snapshot”, each snapshot is saved as a COW volume, and when it is previewed, a new preview layer is copied from the snapshot being previewed. The guest interacts with the preview instead of the actual snapshot volume.
After the administrator previews the selected snapshot, the preview can be committed to restore the guest data to the state captured in the snapshot. If the administrator commits the preview, the guest is attached to the preview layer.
After a snapshot is previewed, the administrator can select to discard the preview layer of the viewed snapshot. The layer that contains the snapshot itself is preserved despite the preview layer being discarded.
8.5. Snapshot Deletion
You can delete individual snapshots or a series of snapshots that are no longer required. Deleting a snapshot removes the ability to restore a virtual machine disk image to that particular restoration point. It does not necessarily reclaim the disk space consumed by the snapshot, nor does it delete the data. The disk space will only be reclaimed if a subsequent snapshot has overwritten the data of the deleted snapshot. For example, if the third snapshot out of five snapshots is deleted, the unchanged data in the third snapshot must be preserved on the disk for the fourth and fifth snapshots to be usable; however, if the fourth or fifth snapshot has overwritten the data of the third, then the third snapshot has been made redundant and the disk space can be reclaimed. Aside from potential disk space reclamation, deleting a snapshot may also improve the performance of the virtual machine.
When a snapshot is selected for deletion, QEMU creates a new logical volume of the same size to merge the snapshot being deleted with the subsequent snapshot. This new logical volume is resized to accommodate all differences between the two snapshots. The new logical volume can potentially be the total combined size of the two snapshots. Once the two snapshots are merged, the subsequent snapshot is renamed and flagged for deletion and is replaced by the new logical volume, which takes its name. Both the snapshot originally flagged for deletion and its subsequent snapshot are deleted, and in their place is the single merged snapshot.
For example, snapshot
Delete_snapshot is 200 GB, and the subsequent snapshot, Next_snapshot, is 100 GB. Delete_snapshot is deleted and a new logical volume is created, temporarily named Snapshot_merge, with a size of 200 GB. Snapshot_merge ultimately resizes to 300 GB to accommodate the total merged contents of both Delete_snapshot and Next_snapshot. Next_snapshot is then renamed Delete_me_too_snapshot so that Snapshot_merge can be renamed Next_snapshot. Finally, Delete_snapshot and Delete_me_too_snapshot are deleted.
The logic used to delete snapshots from running virtual machines is slightly different to that for virtual machines that are shut down. Live snapshot deletion is handled as an asynchronous block job in which VDSM maintains a record of the operation in the recovery file for the virtual machine so that the job can be tracked even if VDSM is restarted or the virtual machine is shut down during the operation. Once the operation begins, the snapshot being deleted cannot be previewed or used as a restoration point, even if the operation fails or is interrupted. In operations in which the active layer is to be merged with its parent, the operation is split into a two-stage process during which data is copied from the active layer to the parent layer, and disk writes are mirrored to both the active layer and the parent. Finally, the job is considered complete once the data in the snapshot being deleted has been merged with its parent snapshot and VDSM synchronizes the changes throughout the image chain.
Chapter 9. Hardware Drivers and Devices
9.1. Virtualized Hardware
Red Hat Enterprise Virtualization presents three distinct types of system devices to virtualized guests. These hardware devices all appear as physically attached hardware devices to the virtualized guest but the device drivers work in different ways.
- Emulated devices
- Emulated devices, sometimes referred to as virtual devices, exist entirely in software. Emulated device drivers are a translation layer between the operating system running on the host (which manages the source device) and the operating systems running on the guests. The device level instructions directed to and from the emulated device are intercepted and translated by the hypervisor. Any device of the same type as that being emulated and recognized by the Linux kernel is able to be used as the backing source device for the emulated drivers.
- Para-virtualized Devices
- Para-virtualized devices require the installation of device drivers on the guest operating system providing it with an interface to communicate with the hypervisor on the host machine. This interface is used to allow traditionally intensive tasks such as disk I/O to be performed outside of the virtualized environment. Lowering the overhead inherent in virtualization in this manner is intended to allow guest operating system performance closer to that expected when running directly on physical hardware.
- Physically shared devices
- Certain hardware platforms allow virtualized guests to directly access various hardware devices and components. This process in virtualization is known as passthrough or device assignment. Passthrough allows devices to appear and behave as if they were physically attached to the guest operating system.
9.2. Stable Device Addresses in Red Hat Enterprise Virtualization
Prior to Red Hat Enterprise Virtualization 3.1, the PCI addresses of virtual machine hardware devices were allocated in the order in which the devices were discovered. This meant that if the order in which virtual hardware was discovered changed, the PCI address allocation given to the hardware could also change.
A change in PCI device addresses is particularly detrimental to virtual machines running Windows operating systems. If an important device, like a system hard disk, were to be allocated a different PCI address than the one that Windows was expecting, Windows anti-piracy measures could require a re-activation of the operating system.
Beginning in Red Hat Enterprise Virtualization 3.1, virtual hardware PCI address allocations are persisted in the ovirt-engine database.
PCI addresses are allocated by QEMU at virtual machine creation time, and reported to VDSM by libvirt. VDSM reports them back to the Manager, where they are stored in the ovirt-engine database.
When a virtual machine is started, the Manager sends VDSM the device address out of the database. VDSM passes them to libvirt which starts the virtual machine using the PCI device addresses that were allocated when the virtual machine was run for the first time.
When a device is removed from a virtual machine, all references to it, including the stable PCI address, are also removed. If a device is added to replace the removed device, it is allocated a PCI address by QEMU, which is unlikely to be the same as the device it replaced.
9.3. Central Processing Unit (CPU)
Each Red Hat Enterprise Virtualization Hypervisor within a Cluster has a number of virtual CPUs (vCPUs). The virtual CPUs are in turn exposed to guests running on the hypervisors. All virtual CPUs exposed by Hypervisors within a Cluster are of the type selected when the Cluster was initially created via Red Hat Enterprise Virtualization Manager. Mixing of virtual CPU types within a Cluster is not possible.
Each available virtual CPU type has characteristics based on physical CPUs of the same name. The virtual CPU is indistinguishable from the physical CPU to the guest operating system.
Note
Support for x2APIC:
All virtual CPU models provided by Red Hat Enterprise Linux 6 hosts include support for x2APIC. This provides an Advanced Programmable Interrupt Controller (APIC) to better handle hardware interrupts.
9.4. System Devices
System devices are critical for the guest to run and cannot be removed. Each system device attached to a guest also takes up an available PCI slot. The default system devices are:
- the host bridge,
- the ISA bridge and USB bridge (The USB and ISA bridges are the same device),
- the graphics card (using either the Cirrus or qxl driver), and
- the memory balloon device.
9.5. Network Devices
Red Hat Enterprise Virtualization is able to expose three different types of network interface controller to guests. The type of network interface controller to expose to a guest is chosen when the guest is created but is changeable from the Red Hat Enterprise Virtualization Manager.
- The
e1000network interface controller exposes a virtualized Intel PRO/1000 (e1000) to guests. - The
virtionetwork interface controller exposes a para-virtualized network device to guests. - The
rtl8139network interface controller exposes a virtualizedRealtek Semiconductor Corp RTL8139to guests.
Multiple network interface controllers are permitted per guest. Each controller added takes up an available PCI slot on the guest.
9.6. Graphics Devices
Two emulated graphics devices are provided. These devices can be connected to with the SPICE protocol or with VNC.
- The ac97 emulates a
Cirrus CLGD 5446 PCI VGAcard. - The vga emulates a dummy VGA card with BochsVESA extensions (hardware level, including all non-standard modes).
9.7. Storage Devices
Storage devices and storage pools can use the block device drivers to attach storage devices to virtualized guests. Note that the storage drivers are not storage devices. The drivers are used to attach a backing storage device, file or storage pool volume to a virtualized guest. The backing storage device can be any supported type of storage device, file, or storage pool volume.
- The
IDEdriver exposes an emulated block device to guests. The emulatedIDEdriver can be used to attach any combination of up to four virtualizedIDEhard disks or virtualizedIDECD-ROM drives to each virtualized guest. The emulatedIDEdriver is also used to provide virtualized DVD-ROM drives. - The VirtIO driver exposes a para-virtualized block device to guests. The para-virtualized block driver is a driver for all storage devices supported by the hypervisor attached to the virtualized guest (except for floppy disk drives, which must be emulated).
9.8. Sound Devices
Two emulated sound devices are available:
- The ac97 emulates an
Intel 82801AA AC97 Audiocompatible sound card. - The es1370 emulates an
ENSONIQ AudioPCI ES1370sound card.
9.9. Serial Driver
The para-virtualized serial driver (
virtio-serial) is a bytestream-oriented, character stream driver. The para-virtualized serial driver provides a simple communication interface between the host's user space and the guest's user space where networking is not be available or unusable.
9.10. Balloon Driver
The balloon driver allows guests to express to the hypervisor how much memory they require. The balloon driver allows the host to efficiently allocate and memory to the guest and allow free memory to be allocated to other guests and processes.
Guests using the balloon driver can mark sections of the guest's RAM as not in use (balloon inflation). The hypervisor can free the memory and use the memory for other host processes or other guests on that host. When the guest requires the freed memory again, the hypervisor can reallocate RAM to the guest (balloon deflation).
Chapter 10. Minimum Requirements and Technical Limitations
- 10.1. Minimum Requirements and Supported Limits
- 10.2. Data Center Limitations
- 10.3. Cluster Limitations
- 10.4. Storage Domain Limitations
- 10.5. Red Hat Enterprise Virtualization Manager Limitations
- 10.6. Hypervisor Requirements
- 10.7. Guest Requirements and Support Limits
- 10.8. SPICE Limitations
- 10.9. Additional References
10.1. Minimum Requirements and Supported Limits
There are a number of physical and logical limitations which apply to Red Hat Enterprise Virtualization environments. Environments with configurations outside of these limitations are currently not supported.
10.2. Data Center Limitations
In a managed virtual environment the highest level container for all resources is the data center. A number of limitations apply to the resources which can be contained within each data center.
Table 10.1. data center Limitations
| Item | Limitations |
|---|---|
| Number of storage domains |
|
| Number of hosts |
|
10.3. Cluster Limitations
A cluster is a set of physical hosts that are treated as a resource pool for a set of virtual machines. Hosts in a cluster share the same network infrastructure and the same storage. The cluster is a migration domain within which virtual machines can be moved from host to host. To ensure stability a number of limitations apply to each cluster.
- All managed hypervisors must be in a cluster.
- All managed hypervisors within a cluster must have the same CPU type. Intel and AMD CPUs cannot co-exist within the same cluster.
Note
Further information about clusters is available in the Red Hat Enterprise Virtualization Administration Guide.
10.4. Storage Domain Limitations
Storage domains provide space for the storage of virtual machine disk images and ISO images as well as the import and export of virtual machines. While many storage domains may be created within a given data center there are a number of limitations and recommendations that apply to each storage domain.
Table 10.2. storage domain Limitations
| Item | Limitations |
|---|---|
| Storage Types |
|
| Logical Unit Numbers (LUNs) |
|
|
Logical Volumes (LVs)
|
In Red Hat Enterprise Virtualization, logical volumes represent virtual disks for virtual machines, templates, and virtual machine snapshots.
The root cause of this limitation is the size of LVM metadata. As the number of logical volumes increases, the LVM metadata associated with those logical volumes also increases. When this metadata exceeds 1 MB in size, the performance of provisioning operations such as creating new disks or snapshots decreases, and lvextend operations for thinly provisioning a logical volume when running a QCOW disk take a longer time to run.
|
Note
Further information about storage domains is available in the Red Hat Enterprise Virtualization Administration Guide.
10.5. Red Hat Enterprise Virtualization Manager Limitations
Red Hat Enterprise Virtualization Manager servers must run Red Hat Enterprise Linux 6. A number of additional hardware requirements must also be met.
Table 10.3. Red Hat Enterprise Virtualization Manager Limitations
| Item | Limitations |
|---|---|
| RAM |
|
| PCI Devices |
|
| Storage |
|
Note
Further information about Red Hat Enterprise Virtualization Manager is available in the Red Hat Enterprise Virtualization Installation Guide.
10.6. Hypervisor Requirements
Red Hat Enterprise Virtualization Hypervisors have a number of hardware requirements and supported limits.
Table 10.4. Red Hat Enterprise Virtualization Hypervisor Requirements and Supported Limits
| Item | Support Limit |
|---|---|
| CPU |
|
| RAM |
|
| Storage |
The minimum supported internal storage for a Hypervisor is the total of the following list:
Please note that these are the minimum storage requirements for Hypervisor installation. It is recommended to use the default allocations which use more storage space.
|
| PCI Devices |
|
Important
When the Red Hat Enterprise Virtualization Hypervisor boots a message may appear:
Virtualization hardware is unavailable. (No virtualization hardware was detected on this system)
This warning indicates the virtualization extensions are either disabled or not present on your processor. Ensure that the CPU supports the listed extensions and they are enabled in the system BIOS.
To check that processor has virtualization extensions, and that they are enabled:
- At the Hypervisor boot screen press any key and select the Boot or Boot with serial console entry from the list. Press Tab to edit the kernel parameters for the selected option. After the last kernel parameter listed ensure there is a Space and append the
rescueparameter. - Press Enter to boot into rescue mode.
- At the prompt which appears, determine that your processor has the virtualization extensions and that they are enabled by running this command:
# grep -E 'svm|vmx' /proc/cpuinfo
If any output is shown, the processor is hardware virtualization capable. If no output is shown it is still possible that your processor supports hardware virtualization. In some circumstances manufacturers disable the virtualization extensions in the BIOS. Where you believe this to be the case consult the system's BIOS and the motherboard manual provided by the manufacturer. - As an additional check, verify that the
kvmmodules are loaded in the kernel:# lsmod | grep kvm
If the output includeskvm_intelorkvm_amdthen thekvmhardware virtualization modules are loaded and your system meets requirements.
Important
The Red Hat Enterprise Virtualization Hypervisor does not support installation on
fakeraid devices. Where a fakeraid device is present it must be reconfigured such that it no longer runs in RAID mode.
- Access the RAID controller's BIOS and remove all logical drives from it.
- Change controller mode to be non-RAID. This may be referred to as compatibility or JBOD mode.
Access the manufacturer provided documentation for further information related to the specific device in use.
10.7. Guest Requirements and Support Limits
The following requirements and support limits apply to guests that are run on the Hypervisor:
Table 10.5. Virtualized Hardware
| Item | Limitations |
|---|---|
| CPU |
|
| RAM |
Different guests have different RAM requirements. The amount of RAM required for each guest varies based on the requirements of the guest operating system and the load under which the guest is operating. A number of support limits also apply.
|
| PCI devices |
A maximum of 31 virtualized PCI devices per guest is supported. A number of system devices count against this limit, some of which are mandatory. Mandatory devices which count against the PCI devices limit include the PCI host bridge, ISA bridge, USB bridge, board bridge, graphics card, and the IDE or VirtIO block device.
|
| Storage |
A maximum of 28 virtualized storage devices per guest is supported, composed of a possible 3 IDE and 25 Virtio.
|
10.8. SPICE Limitations
SPICE currently supports a maximum resolution of 2560x1600 pixels.
10.9. Additional References
These additional documentation resources do not form part of the Red Hat Enterprise Virtualization documentation suite. They do however contain useful information for System Administrators managing Red Hat Enterprise Virtualization environments and are available at https://access.redhat.com/documentation/en-US.
- Red Hat Enterprise Linux - Deployment Guide
- A guide to the deployment, configuration and administration of Red Hat Enterprise Linux.
- Red Hat Enterprise Linux - DM-Multipath Guide
- A guide to the use of Device-Mapper Multipathing on Red Hat Enterprise Linux.
- Red Hat Enterprise Linux - Installation Guide
- A guide to the installation of Red Hat Enterprise Linux.
- Red Hat Enterprise Linux - Storage Administration Guide
- A guide to the management of storage devices and file systems on Red Hat Enterprise Linux.
- Red Hat Enterprise Linux - Virtualization Administration Guide
- A guide to the installation, configuration, administration and troubleshooting of virtualization technologies in Red Hat Enterprise Linux.
Part II. The Command Line Interface
1. Introduction to the Command Line Interface
The Red Hat Enterprise Virtualization suite features a command line interface (CLI). This CLI provides users with a means to connect to Red Hat Enterprise Virtualization Manager outside of the standard web interface. The CLI also contains a scripting system, which helps system administrators perform periodic maintenance or repetitive tasks on their virtualization environment via client machines.
Table of Contents
- 11. Using the CLI
- 12. Quick Start Example
- 13. Commands
- 14. Resource Types
- 14.1. brick
- 14.2. cdrom
- 14.3. cluster
- 14.4. datacenter
- 14.5. disk
- 14.6. glustervolume
- 14.7. group
- 14.8. host
- 14.9. network
- 14.10. nic
- 14.11. permission
- 14.12. permit
- 14.13. quotas
- 14.14. role
- 14.15. snapshot
- 14.16. statistic
- 14.17. storageconnection
- 14.18. storagedomain
- 14.19. tag
- 14.20. template
- 14.21. user
- 14.22. vm
- 14.23. vmpool
- 14.24. vnicprofile
- 15. CLI Queries
Chapter 11. Using the CLI
11.1. Installing the CLI
Install the Red Hat Enterprise Virtualization CLI to a client machine:
- Log into the client machine as the
rootuser. - Register your system with the Content Delivery Network, entering your Customer Portal user name and password when prompted:
# subscription-manager register
- Find the
Red Hat Enterprise Virtualizationsubscription pool and note down the pool ID.# subscription-manager list --available
- Use the pool identifiers located in the previous step to attach the
Red Hat Enterprise Virtualizationentitlement to the system:# subscription-manager attach --pool=pool_id
- Enable the required repository:
# subscription-manager repos --enable=rhel-6-server-rhevm-beta-rpms
- Install the CLI package and dependencies:
# yum install rhevm-cli
11.2. TLS/SSL Certification
The Red Hat Enterprise Virtualization Manager API requires Hypertext Transfer Protocol Secure (HTTPS)
[1] for secure interaction with client software, such as the Manager's SDK and CLI components. This involves a process of obtaining a certificate from the Red Hat Enterprise Virtualization Manager and importing it into the certificate store of your client.
Important
Obtain your certificate from the Red Hat Enterprise Virtualization Manager using a secure network connection.
Procedure 11.1. Obtaining a Certificate
You can obtain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to the client machine using one of three methods:
- Method 1 - Use a command line tool to download the certificate from the Manager. Examples of command line tools include cURL and Wget, both of which are available on multiple platforms.
- If using cURL:
$ curl -o rhevm.cer http://[rhevm-server]/ca.crt
- If using Wget:
$ wget -O rhevm.cer http://[rhevm-server]/ca.crt
- Method 2 - Use a web browser to navigate to the certificate located at:
http://[rhevm-server]/ca.crt
Depending on the chosen browser, the certificate either downloads or imports into the browser's keystore.- If the browser downloads the certificate: save the file as
rhevm.cer.If the browser imports the certificate: export it from the browser's certification options and save it asrhevm.cer.
- Method 3 - Log in to the Manager, export the certificate from the truststore and copy it to your client machine.
- Log in to the Manager as the
rootuser. - Export the certificate from the truststore using the Java keytool management utility:
$ keytool -exportcert -keystore /etc/pki/ovirt-engine/.truststore -alias cacert -storepass mypass -file rhevm.cer
This creates a certificate file calledrhevm.cer. - Copy the certificate to the client machine using the
scpcommand:$ scp rhevm.cer [username]@[client-machine]:[directory]
Each of these methods results in a certificate file named
rhevm.cer on your client machine. An API user imports this file into the certificate store of the client.
Procedure 11.2. Importing a Certificate to a Client
- Importing a certificate to a client relies on how the client itself stores and interprets certificates. This guide contains some examples on importing certificates. For clients not using Network Security Services (NSS) or Java KeyStore (JKS), see your client documentation for more information on importing a certificate.
11.3. .rhevmshellrc Configuration
The
.rhevmshellrc is a configuration file that is automatically created and populated when the user first connects to the rhevm-shell. It allows users to configure options for connecting to the Red Hat Enterprise Virtualization environment. The .rhevmshellrc file is located by default in /home/[user name]/.rhevmshellrc.
The configuration information of the
.rhevmshellrc file falls under two section headings, [cli] and [ovirt-shell]. These headings are necessary for the configuration file to be parsed.
Table 11.1. [cli] Parameters
| Name | Type | Description |
|---|---|---|
autoconnect
|
boolean
|
Toggles whether to automatically connect to a rhevm-shell session. The status is either
True or False.
|
autopage
|
boolean
|
Toggles pagination in the shell. The status is either
True or False.
|
Table 11.2. [ovirt-shell] Parameters
| Name | Type | Description |
|---|---|---|
username
|
string
|
User name to be used to log in.
|
timeout
|
integer
|
Specifies timeout for requests. The default is -1.
|
extended_prompt
|
boolean
|
Toggles the extended prompt option, which displays the hostname in the shell command prompt.
|
url
|
string
|
The address of the Red Hat Enterprise Virtualization environment.
|
insecure
|
boolean
|
Toggles CA certificate requirement. The status is either
True or False.
|
renew_session
|
boolean
|
Toggles automatic renewal of the session upon expiration. The status is either
True or False.
|
filter
|
boolean
|
Toggles object filtering. Object filtering allows users to fetch objects according to their permissions. Only admin roles can toggle filtering off. The status is either
True or False.
|
session_timeout
|
integer
|
Specifies timeout (in minutes) for authentication session. Must be a positive number.
|
ca_file
|
string
|
Specifies the server CA certificate to use.
|
dont_validate_cert_chain
|
boolean
|
Toggles validation of server CA certificate. The status is either
True or False.
|
key_file
|
string
|
Specifies client PEM key-file.
|
password
|
string
|
Password to be used for user name.
|
cert_file
|
string
|
Specifies client PEM cert-file.
|
11.4. Running the CLI
Start the CLI application with the following command:
# rhevm-shell
This
rhevm-shell application is an interactive shell for Red Hat Enterprise Virtualization environments.
The URL, user name, certificate authority file, and password for connecting to the Red Hat Enterprise Virtualization Manager can be configured in the
.rhevmshellrc file. The rhevm-shell command uses the parameters in this file to connect to the Manager, so that the user does not need to specify options each time.
Alternatively, users can connect automatically to Red Hat Enterprise Virtualization Manager using the following additional options.
# rhevm-shell -c -l "https://[server]/api" -P [port] -u "[user@domain]" -A "[certificate]"
Ensure to replace the following values:
- server - The hostname or IP Address of the Red Hat Enterprise Virtualization Manager. The CLI connects to the Red Hat Enterprise Virtualization Manager via the REST API.
- user@domain - The user name and directory service domain for the user logging into Red Hat Enterprise Virtualization Manager.
- certificate - The path name of the Certificate Authority file.
The shell will prompt you for the password, and, if not already provided, the username and the URL for the Red Hat Enterprise Virtualization Manager.
Note
You do not need to specify additional options if you have configured your user name, password, URL, and certificate authority file in the
.rhevmshellrc file.
Note
The certificate is the only obligatory option as the others used in this example will be prompted by the shell. Instead of specifying the certificate you can use the '--insecure' option to connect without certification, however this is not recommended as it may allow man-in-the-middle (MITM) attackers to spoof the identity of the server.
Options for rhevm-shell
- -h, --help
- Show help for
rhevm-shell. - -d, --debug
- Enables debugging.
- -l URL, --url=URL
- Specifies the API entry point URL.
- -u USERNAME, --username=USERNAME
- Connect as this user.
- -K KEY_FILE, --key-file=KEY_FILE
- Specify key file.
- -C CERT_FILE, --cert-file=CERT_FILE
- Specify certificate file.
- -A CA_FILE, --ca-file=CA_FILE
- Specify server Certificate Authority file.
- -I, --insecure
- Allow the CLI to connect via SSL without certification. Use this option with caution because it can allow man-in-the-middle (MITM) attackers to spoof the identity of the server.
- -F, --filter
- Enable filtering based upon user permissions.
- -P PORT, --port=PORT
- Specify port.
- -T TIMEOUT, --timeout=TIMEOUT
- Specify timeout.
- -c, --connect
- Automatically connect.
- -e, --extended-prompt
- Enables the extended prompt option for the shell. This option displays the hostname of the environment in the command prompt. Default is 'false'.
- -E "command resource", --execute-command="command resource"
- Connects to the Manager to execute only the given commands, in the form of "command resource;command resource" and prints the output to STDIO.
- -f FILE, --file=FILE
- Read commands from FILE instead of stdin.
- --kerberos
- Use a valid Kerberos ticket to authenticate connection to the shell.
Note
Users with a non-interactive shell are able to connect to the Red Hat Enterprise Virtualization Manager from within the shell, where the --password option can be used.
11.5. Interacting with the CLI
The CLI is an interactive shell for controlling your Red Hat Enterprise Virtualization environment from the command line. Type the required command and any additional parameters.
To support the construction of command and parameter combinations, the CLI includes the functionality to list and automatically complete commands and parameters by pressing the
TAB key twice, similar to the bash shell.
Example 11.2. Listing and automatic completion of commands and parameters
Press double
TAB at a blank prompt to list all available commands.
[RHEVM shell (connected)]# TAB TAB
EOF clear echo history remove summary
action connect exit info shell update
add console file list show
capabilities disconnect help ping status
Choose a command and press double
TAB to view the next set of available parameters for the command. For the show, this lists all resources.
[RHEVM shell (connected)]# show TAB TAB
brick datacenter event group nic
quota statistic template vmpool cdrom
disk file host permission role
storagedomain user cluster domain glustervolume
network permit snapshot tag vm
Double
TAB also completes commands and parameters.
[RHEVM shell (connected)]# show vmTAB TABkwargs name show-all storagedomain [RHEVM shell (connected)]# show vm naTAB TAB[RHEVM shell (connected)]# show vm --name
Note that the double
TAB also automatically formats na to the --name parameter, including the prefix.
If the incomplete parameter matches multiple parameters, double
TAB lists them.
[RHEVM shell (connected)]# show vTAB TAB
vmpool vm
The CLI provides functions to run Linux commands using either the
shell command or the bang (!) character.
Example 11.3. Running Linux shell commands
Use the
shell command:
[RHEVM shell (connected)]# shell ls -la
Or use the bang (
!) character:
[RHEVM shell (connected)]# !ls -la
Similar to the Linux shell, the CLI can pipe data to other commands and sources.
Example 11.4. Piping CLI commands
Pipe CLI data to a Linux shell command:
[RHEVM shell (connected)]# list vms --show-all | grep "Example" name : Example1 name : Example2 name : ExampleEngineering description : An Example description name : BestExampleVM
Pipe CLI data to a file:
[RHEVM shell (connected)]# list vms --show-all > list vms --show-all > VM_List.txt
The CLI also contains an online help system to provide descriptions and syntax for each command via the
help command.
You can also connect to the Manager from the Linux shell to execute specific commands, in the form of "command resource" and print them to STDIO
Example 11.6. Connecting to the Manager to execute specific commands
Use the
--execute or -E parameter to connect to the Manager to execute the specific commands.
# rhevm-shell -c -l "https://[server]/api" -P [port] -u "[user@domain]" -A "[certificate]" -E "list vms;list hosts" [RHEVM shell (connected)]# list vms id : 9e6977f4-4351-4feb-bba0-dc7c22adec30 name : desktop-01 id : 60b12e28-7965-4296-86bf-c991aa32c2d5 name : server-01 [RHEVM shell (connected)]# list hosts id : 3598cdb9-d21b-49bd-9491-59faff89b113 name : Gluster id : a0c384f9-0940-4562-9c42-4ceaadf8f1f1 name : Host-01 id : 593ec966-c3ea-4bdc-84ad-5dc3f9fe64c7 name : Host-03
11.6. Collections
Some command parameters require a collection. A collection is a set of sub-parameter data. Collections are defined using the following syntax.
[RHEVM shell (connected)]# command --param-collection {subparam1=value1;subparam2=value2;subparam3=value3;...},{subparam1=value1;subparam2=value2;subparam3=value3;...},...
Sub-parameters for collections are listed after resource parameter listings on each resource page.
Chapter 12. Quick Start Example
12.1. Creating a Basic Virtualization Environment with the CLI
This chapter provides an example to demonstrate the CLI's ability to add a virtual machine within a basic Red Hat Enterprise Virtualization environment. This example uses the following prerequisites:
- A networked and configured Red Hat Enterprise Linux host for use as a hypervisor;
- A networked and configured NFS storage server with two shares:
/exports/data- The data storage domain; and/exports/iso- The ISO storage domain.
- A networked and configured Red Hat Enterprise Virtualization Manager;
- An installation of the CLI on either the Red Hat Enterprise Virtualization Manager or a client machine; and,
- An ISO file containing a desired virtual machine operating system to install. This chapter uses Red Hat Enterprise Linux Server 6 for our installation ISO example.
Note
Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for each resource. Identifier codes in this example might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.
Procedure 12.1. Quick Start Example
- Load the CLI shell and connect to your Red Hat Enterprise Virtualization Manager.
# rhevm-shell -c --url https://[rhevm-host]/api --username [user]@[domain] --ca-file certificate/authority/path/name
- List all data centers in the environment. This example uses the
Defaultdata center.[RHEVM shell (connected)]# list datacenters id : 5e3b55d8-c585-11e1-a7df-001a4a400e0d name : Default description: The default Data Center
- List all host clusters and note down the relevant cluster ID or cluster name, which will be required when adding the host and for creating a virtual machine. This example uses the
Defaultcluster to group resources in your Red Hat Enterprise Virtualization environment.[RHEVM shell (connected)]# list clusters id : 99408929-82cf-4dc7-a532-9d998063fa95 name : Default description: The default server cluster
- List all CPU profiles and note down the relevant CPU profile ID, which will be required when creating a virtual machine. This example uses the
DefaultCPU profile.[RHEVM shell (connected)]# list cpuprofiles id : 0000001a-001a-001a-001a-00000000035e name : Default
- List all logical networks with the
show-alloption to view the details of the logical networks in the environment. Red Hat Enterprise Virtualization Manager creates a default logical network calledrhevmfor management traffic. This example uses therhevmlogical network on theDefaultdata center.[RHEVM shell (connected)]# list networks --show-all id : 00000000-0000-0000-0000-000000000009 name : rhevm description : Management Network data_center-id: 5e3b55d8-c585-11e1-a7df-001a4a400e0d mtu : 0 required : True status-state : operational stp : False usages-usage : VM
Note thedata_center-idvalue matches theidfor theDefaultdata center. - Add the Red Hat Enterprise Linux host to the virtualization environment as a new hypervisor. The host is activated automatically.
[RHEVM shell (connected)]# add host --name MyHost --address host.example.com --cluster-name Default --root_password p@55w0rd!
- Add an NFS share as a data storage domain by creating, attaching, and activating the NFS share. An NFS data storage domain is an exported NFS share attached to a data center. It provides storage for virtual machines. Ensure to substitute
storage-addressandstorage-pathwith the correct values for the NFS server.- Create a data storage domain.
[RHEVM shell (connected)]# add storagedomain --host-name MyHost --type data --storage-type nfs --storage_format v3 --storage-address x.x.x.x --storage-path /exports/data --name DataStorage
- Verify that the created storage domain is available. The creation process might take several minutes. Once the
status-stateisunattached, you can proceed to the next step.[RHEVM shell (connected)]# show storagedomain --name DataStorage id : xxxx name : DataStorage master : False status-state : unattached ...
- Attach the data storage domain to the data center. The storage domain is activated automatically.
[RHEVM shell (connected)] # add storagedomain --datacenter-identifier Default --name DataStorage
Note
If the storage domain is not activated, activate it manually using the following command:[RHEVM shell (connected)]# action storagedomain DataStorage --datacenter-identifier Default activate
- Add an NFS share as the ISO storage domain by creating, attaching, and activating the NFS share. An NFS ISO storage domain is an exported NFS share attached to a data center. It provides storage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Ensure to substitute
storage-addressandstorage-pathwith the correct values for the NFS server.- Create an ISO storage domain.
[RHEVM shell (connected)]# add storagedomain --host-name MyHost --type iso --storage-type nfs --storage_format v3 --storage-address x.x.x.x --storage-path /exports/iso --name ISOStorage
- Verify that the created storage domain is available. The creation process might take a while. Once the
status-stateisunattached, you can proceed to the next step.[RHEVM shell (connected)]# show storagedomain --name ISOStorage id : xxxx name : ISOStorage master : False status-state : unattached ...
- Attach the ISO storage domain to the data center. The storage domain is activated automatically.
[RHEVM shell (connected)] # add storagedomain --datacenter-identifier Default --name ISOStorage
- Create a new virtual machine.
[RHEVM shell (connected)]# add vm --name MyVM --cluster-name Default --template-name Blank --memory 536870912 --os-boot boot.dev=hd --cpu_profile-id 0000001a-001a-001a-001a-00000000035e
- Use the
add niccommand to add a new network interface. Add thevm-identifieroption to attach the interface as a sub-resource ofMyVMand anetwork-nameoption to connect to therhevmnetwork.[RHEVM shell (connected)]# add nic --vm-identifier MyVM --name nic1 --network-name rhevm --bootable true
- Use the
add diskcommand to add a new virtual hard disk. Add thevm-identifieroption to attach the disk as a sub-resource ofMyVM.[RHEVM shell (connected)]# add disk --vm-identifier MyVM --provisioned_size 8589934592 --interface virtio --format cow --storage_domains-storage_domain storage_domain.name=DataStorage
- On the Manager, upload ISO images to the
ISOStoragedomain for the virtual machines to use. Red Hat Enterprise Virtualization Manager provides an ISO uploader tool that ensures images are uploaded into the correct directory path with the correct user permissions.# engine-iso-uploader --iso-domain=ISOStorage upload rhel-server-6.6-x86_64-dvd.iso Please provide the REST API password for the admin@internal oVirt Engine user (CTRL+D to abort):
- In the CLI shell, use the
list filescommand to list the available ISO files in the storage domain.[RHEVM shell (connected)]# list files --storagedomain-identifier ISOStorage
- Add a virtual CD-ROM drive for your installation media. Add the
vm-identifieroption to attach the CD-ROM as a sub-resource ofMyVM.[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-server-6.6-x86_64-dvd.iso
- Start the virtual machine. The virtual environment is complete and the virtual machine contains all necessary components to function.
[RHEVM shell (connected)]# action vm MyVM start --vm-os-boot boot.dev=cdrom
Note the use of thevm-os-bootoption. This changes the boot device tocdromfor this initial boot session. After installation, the virtual machine restarts and restores the boot device back tohd. - Use the
list eventswith an additionalqueryoption to display specific event types. Thestartaction for the virtual machine adds several entries in theeventscollection.[RHEVM shell (connected)]# list events --query "type=153" id : 105 description: MyVM was started by admin (Host: MyHost).
The"type=153"query refers to events where a user starts a virtual machine. - Use the
show eventcommand to display comprehensive details of an event. This command can be used to show events bytype,name, andid.[RHEVM shell (connected)]# show event --id '60' id : 60 description : New Tag foo was created by admin@internal. code : 432 correlation_id: 3e4d4350 custom_id : -1 flood_rate : 30 origin : oVirt severity : normal time : 2013-07-03 10:57:43.257000+03:00 user-id : fdfc627c-d875-11e0-90f0-83df133b58cc
- Access your virtual machine with the
consolecommand.[RHEVM shell (connected)]# console MyVM
Important
Ensure your client machine has a console application installed to match the virtual machine'sdisplay-type. Protocols available include SPICE (default) and VNC.
Chapter 13. Commands
13.1. Connecting to RHEVM
13.1.1. Connect to RHEVM (connect)
The
connect command connects to Red Hat Enterprise Virtualization Manager. The URL, user name, certificate authority file, and password for connecting to the Red Hat Enterprise Virtualization Manager can be configured in the .rhevmshellrc file. The connect command uses the parameters in this file to connect to the Manager, so that the user does not need to specify options each time.
Syntax
connect [options]
Note
You do not need to specify additional options if you have configured your user name, password, URL, and certificate authority file in the
.rhevmshellrc file.
Table 13.1. Options for connect
| Option | Description | Required |
|---|---|---|
--url | The URL to the Red Hat Enterprise Virtualization Manager's REST API. This takes the form of https://[server]/api. | Yes |
--username | The user name and directory service domain of the user attempting access to the Red Hat Enterprise Virtualization Manager. This takes the form of [username]@[domain]. | Yes |
--password | The password for the user attempting access to the Red Hat Enterprise Virtualization Manager. | Yes |
--key-file | The key file for connection via SSL. | No |
--cert-file | The certificate file for connection via SSL. | No |
--ca-file | The certificate authority file for connection via SSL. | Yes, unless --insecure is used |
--insecure | Allow the CLI to connect via SSL without certification. Use this option with caution because it can allow man-in-the-middle (MITM) attackers to spoof the identity of the server. | Yes, but only if no certificate authority is provided |
--filter | Enable filtering based upon user permissions. | No |
--port | The port number for connection to the REST API, if not specified as part of the --url. | No |
--timeout | The timeout period for connection. | No |
Example 13.1. Example for connect when .rhevmshellrc is not configured
[RHEVM shell (disconnected)]# connect --url "https://rhevm.example.com/api" --username "admin@exampleids.com" --password "p@55w0rd!" --ca-file "/home/user/ca.crt" ========================================== >>> connected to RHEVM manager 3.5.0.0 <<< ========================================== [RHEVM shell (connected)]#
Note
Instead of specifying the certificate you can use the '--insecure' option to connect without certification, however this is not recommended as it may allow man-in-the-middle (MITM) attackers to spoof the identity of the server.
13.1.2. Disconnect from RHEVM (disconnect)
The
disconnect command disconnects from Red Hat Enterprise Virtualization Manager.
Syntax
disconnect
Example 13.2. Example for disconnect
[RHEVM shell (connected)]# disconnect ======================================= >>> disconnected from RHEVM manager <<< ======================================= [RHEVM shell (disconnected)]#
13.2. Resources
13.2.1. List Resources in a Collection (list)
Use the
list command to display all resources of a specific type. Lists also include optional search queries to filter results.
Syntax
list [collection] [options]
Table 13.2. list standard options
| Option | Description |
|---|---|
--show-all | Displays all non-empty properties for each listed resource. Without this option, only the id, name and description properties display. |
--query [QUERY] | Filters the list using a server-side query based upon Red Hat Enterprise Virtualization Manager query language. |
--kwargs [QUERY] | Filters the list using a client-side query. |
--case_sensitive true|false | Match search queries using case sensitivity. |
--max | Maximum number of results for display. |
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 13.3. Examples for list
List virtual machines:
[RHEVM shell (connected)]# list vms
List virtual machines with all properties listed:
[RHEVM shell (connected)]# list vms --show-all
List virtual machines with a status of 'up':
[RHEVM shell (connected)]# list vms --query "status=up"
List users that match the specified user name across all domains with the use of a wildcard:
[RHEVM shell (connected)]# list users --query "usrname=jsmith@*" --case_sensitive false
Get help with list search syntax:
[RHEVM shell (connected)]# list --help
13.2.2. Show a Resource (show)
Use the
show command to display resource properties.
Syntax
show [resource] [id|name] [options]
Table 13.3. show standard options
| Option | Description |
|---|---|
--id [UUID] | Identify resource with the resource's UUID value. |
--name [NAME] | Identify resource with the name value. |
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 13.4. Examples for show
Show virtual machines based upon
id:
[RHEVM shell (connected)]# show vm fcadfd5f-9a12-4a1e-bb9b-2b9d5c2e04c3
Show virtual machines based upon
name:
[RHEVM shell (connected)]# show vm RHEL6-Server
13.2.3. Add a Resource (add)
Use the
add command to add a new resource.
Syntax
add [resource] [options]
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 13.5. Examples for add
Create a virtual machine:
[RHEVM shell (connected)]# add vm [vm-options]
Create a user:
[RHEVM shell (connected)]# add user [user-options]
The
add command can be made synchronous (if supported) by using the expect option:
[RHEVM shell (connected)]# add vm [vm-options] --expect '201-created'
13.2.4. Update a Resource (update)
Use the
update command to modify an existing resource.
Syntax
update [resource] [id|name] [options]
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 13.6. Examples for update
Update a virtual machine:
[RHEVM shell (connected)]# update vm RHEL6-Server [vm-options]
13.2.5. Remove a Resource (remove)
Use the
remove command to remove a resource.
Syntax
remove [resource] [id|name] [options]
Table 13.4. remove standard options
| Option | Description |
|---|---|
--async | Perform an asynchronous removal of the resource. |
--force | Perform a force remove of the resource. This removes all database entries and associations for a particular resource. This action applies only to datacenter and vm resources. |
Note
Options specific to resource types are listed in the definition pages for each resource type.
Example 13.7. Examples for remove
Remove a virtual machine:
[RHEVM shell (connected)]# remove vm RHEL6-Server
Asynchronous removal of a virtual machine:
[RHEVM shell (connected)]# remove vm RHEL6-Server --async true
Force remove virtual machine:
[RHEVM shell (connected)]# remove vm RHEL6-Server --force
13.2.6. Perform Action on a Resource (action)
Use the
action command to perform a special function relevant to resource type.
Syntax
action [resource] [id|name] [action] [options]
Note
Options specific to resource actions are listed in the definition pages for each resource type.
Example 13.8. Examples for action
Start a virtual machine
[RHEVM shell (connected)]# action vm RHEL6-Server start
Stop a virtual machine:
[RHEVM shell (connected)]# action vm RHEL6-Server stop
The
action command can be made synchronous (if supported) by using the async option:
[RHEVM shell (connected)]# action vm [vm-options] --async false
13.2.7. Using Sub-Resources (--RESOURCE-identifier)
Certain resources act as sub-resources of other resources. This means there is a dependent relationship between the sub-resource and its parent resource. Use the
--RESOURCE-identifier [name] option, where RESOURCE is the parent resource type, to target a sub-resource part of a parent resource.
Example 13.9. Examples for creating sub-resources with add
Create a NIC on a virtual machine:
[RHEVM shell (connected)]# add nic --vm-identifier RHEL6-Server [nic-options]
Note the use of the
--vm-identifier RHEL6-Server option. This adds a NIC on the RHEL6-Server virtual machine.
Create a storage disk on a virtual machine:
[RHEVM shell (connected)]# add disk --vm-identifier RHEL6-Server [user-options]
Note the use of the
--vm-identifier RHEL6-Server option. This adds a storage disk on the RHEL6-Server virtual machine.
13.3. Other Commands
- 13.3.1. End of File (EOF)
- 13.3.2. List System Capabilities (capabilities)
- 13.3.3. Clear the Screen (clear)
- 13.3.4. Connect to VM (console)
- 13.3.5. Print Input (echo)
- 13.3.6. Exit from the CLI (exit)
- 13.3.7. Run a Script (file)
- 13.3.8. Show Help (help)
- 13.3.9. Display the User Command History (history)
- 13.3.10. Show CLI Information (info)
- 13.3.11. Test Connection (ping)
- 13.3.12. Run a Shell Command (shell)
- 13.3.13. Show Last Status (status)
- 13.3.14. Show System Summary (summary)
13.3.1. End of File (EOF)
Use the
EOF command to leave the CLI shell using a Ctrl+D sequence.
Syntax
EOF
13.3.2. List System Capabilities (capabilities)
Use the
capabilties --features command to list all version capabilities and new features of the current version.
Syntax
capabilities --features
Example 13.11. Example for capabilities
List system capabilities of the current version:
[RHEVM shell (connected)]# capabilities --features name : Search - Case Sensitivity description : Ability to specify whether a search query should ignore case, by providing a URL parameter url-parameters_set-parameter-name : case_sensitive url-parameters_set-parameter-context: matrix url-parameters_set-parameter-type : boolean :
13.3.4. Connect to VM (console)
Use the
console command to open a graphical console to a virtual machine. This command opens either an external VNC or SPICE client based upon the virtual machine's display-type parameter.
Syntax
console [vm-id|vm-name]
Example 13.13. Example for console
Open graphical console to a virtual machines:
[RHEVM shell (connected)]# console RHEL6-Server
13.3.5. Print Input (echo)
Use the
echo command to print input to the screen. Use the $out variable to print the last shell command output.
Syntax
echo [input]
Example 13.14. Example for echo
Print input:
[RHEVM shell (connected)]# echo "Example text!"
Print last output:
[RHEVM shell (connected)]# echo $out
13.3.7. Run a Script (file)
Use the
file command to run a CLI script file. A script is a plain text file that contains a list of commands for execution.
Syntax
file [file-location]
Example 13.16. Example for file
Run a script file:
[RHEVM shell (connected)]# file /example/example-script
13.3.8. Show Help (help)
Use the
help command displays help for CLI command and resource combinations.
Syntax
help [command] [resource] [options]
Example 13.17. Examples for help
Get CLI help:
[RHEVM shell (connected)]# help
Get help for the
add command:
[RHEVM shell (connected)]# help add
Get help for the
add command on the vm resource type:
[RHEVM shell (connected)]# help add vm
13.3.9. Display the User Command History (history)
Use the
history command to display the history of user commands for the CLI shell.
Syntax
history
Example 13.18. Example for history
Display the user command history:
[RHEVM shell (connected)]# history
Example 13.19. Example for history --first
Display the first specified entries in the user command history with the
--first n parameter:
[RHEVM shell (connected)]# history --first 5
Example 13.20. Example for history --last
Display the last specified entries in the user command history with the
--last n parameter:
[RHEVM shell (connected)]# history --last 5
13.3.10. Show CLI Information (info)
Use the
info command to display environment connection details and version information.
Syntax
info
Example 13.21. Example for info
View CLI information:
[RHEVM shell (connected)]# info backend version: 3.1 sdk version : 3.1.0.4 cli version : 3.1.0.6 python version : 2.7.3.final.0 entry point : https://www.example.com:8443/api
13.3.11. Test Connection (ping)
Use the
ping command tests the connection to your Red Hat Enterprise Virtualization Manager. The command retrieves a remote resource and ensures the URL, user name and password for the connection are correct.
Syntax
ping
Example 13.22. Example for ping
Test your connection:
[RHEVM shell (connected)]# ping success: RHEVM manager could be reached OK.
13.3.12. Run a Shell Command (shell)
Use the
shell command to run a command from the Linux shell. This command helps with performing file management tasks in conjunction with the Red Hat Enterprise Virtualization Manager shell.
Syntax
shell [vm-id|vm-name]
Example 13.23. Examples for shell
List files in current working directory:
[RHEVM shell (connected)]# shell ls
Create a file:
[RHEVM shell (connected)]# shell touch example.txt
Copy a file:
[RHEVM shell (connected)]# shell cp example.txt /example-dir/.
Note
The CLI offers an alternative to the
shell using the bang (!) character. For example:
[RHEVM shell (connected)]# !touch example.txt
13.3.13. Show Last Status (status)
Use the
status command to display the most recently run command status.
Syntax
status
Example 13.24. Example for status
View the last status:
[RHEVM shell (connected)]# status last command status: 0 (OK)
13.3.14. Show System Summary (summary)
Use the
summary command to display a summary of the system status.
Syntax
summary
Example 13.25. Example for summary
Display system status:
[RHEVM shell (connected)]# summary hosts-active : 1 hosts-total : 2 storage_domains-active: 2 storage_domains-total : 3 users-active : 1 users-total : 1 vms-active : 1 vms-total : 1
Chapter 14. Resource Types
- 14.1. brick
- 14.2. cdrom
- 14.3. cluster
- 14.4. datacenter
- 14.5. disk
- 14.6. glustervolume
- 14.7. group
- 14.8. host
- 14.9. network
- 14.10. nic
- 14.11. permission
- 14.12. permit
- 14.13. quotas
- 14.14. role
- 14.15. snapshot
- 14.16. statistic
- 14.17. storageconnection
- 14.18. storagedomain
- 14.19. tag
- 14.20. template
- 14.21. user
- 14.22. vm
- 14.23. vmpool
- 14.24. vnicprofile
14.1. brick
The
brick resource type groups all Gluster bricks in a Red Hat Enterprise Virtualization environment.
Table 14.1. Gluster brick parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--server_id
|
string
|
The address of the Gluster server.
|
Yes
|
Yes
|
No
|
--brick_dir
|
string
|
The brick's directory on the Gluster server.
|
Yes
|
Yes
|
No
|
--replica_count
|
integer
|
Defines the file replication count for a replicated volume.
|
No
|
Yes
|
No
|
--stripe_count
|
Integer
|
Defines the stripe count for a striped volume
|
No
|
Yes
|
No
|
The following table lists additional
glustervolume options for resource-based commands.
Table 14.2. Additional command options
| Option | Description |
|---|---|
--cluster-identifier | Reference to the cluster that contains a glustervolume sub-resource. |
--glustervolume-identifier | Adds the brick to a glustervolume as a sub-resource. |
Example 14.1. Creating a bricks
[RHEVM shell (connected)]# add brick --cluster-identifier Default --glustervolume-identifier GlusterVol1 --server_id="server1" --brick_dir="/exp1"
14.2. cdrom
The
cdrom resource type groups all virtual CD-ROM drive resources in a Red Hat Enterprise Virtualization environment.
Table 14.3. CD-ROM parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--file-id
|
string
|
Defines the file name of the ISO that resides on an ISO storage domain.
|
Yes
|
Yes
|
Yes
|
Example 14.2. Creating a new CD-ROM
[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-server-6.2-x86_64-dvd.iso.iso
Example 14.3. Updating a CD-ROM
[RHEVM shell (connected)]# update cdrom --vm-identifier MyVM --file-id rhel-server-6.3-x86_64-dvd.iso.iso
Example 14.4. Deleting a CD-ROM
[RHEVM shell (connected)]# remove cdrom --vm-identifier MyVM rhel-server-6.3-x86_64-dvd.iso.iso
14.3. cluster
The
cluster resource type groups all host cluster resources in a Red Hat Enterprise Virtualization environment.
Table 14.4. Cluster parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--cpu-id
|
string
|
A server CPU reference that defines the CPU type all hosts must support in the cluster.
|
Yes
|
Yes
|
Yes
|
--data_center-id|name
|
string
|
A reference to the data center for a host cluster.
|
Yes
|
Yes
|
No
|
--name
|
string
|
The name of a host cluster.
|
Yes
|
Yes
|
Yes
|
--version-major
|
int
|
The major version number of the cluster. For example, for Red Hat Enterprise Virtualization 3.6, the major version is 3.
|
Yes
|
Yes
|
Yes
|
--version-minor
|
int
|
The minor version number of the cluster. For example, for Red Hat Enterprise Virtualization 3.6, the minor version is 6.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the host cluster.
|
No
|
Yes
|
Yes
|
--error_handling-on_error
|
string
|
Defines virtual machine handling when a host within a cluster becomes non-operational, including
migrate, do_not_migrate and migrate_highly_available.
|
No
|
Yes
|
Yes
|
--gluster_service
|
Boolean
|
The status is either
true or false.
|
No
|
Yes
|
Yes
|
--memory_policy-overcommit-percent
|
double
|
The percentage of host memory allowed in use before a host can no longer run any more virtual machines. Virtual machines can use more than the available host memory due to memory sharing under KSM. Recommended values include
100 (None), 150 (Server Load) and 200 (Desktop Load).
|
No
|
Yes
|
Yes
|
--memory_policy-transparent_hugepages-enabled
|
Boolean
|
Defines the enabled status of Transparent Hugepages. The status is either
true or false.
|
No
|
Yes
|
Yes
|
--scheduling_policy-policy
|
string
|
The VM scheduling mode for hosts in the cluster, such as
evenly_distributed, power_saving or blank for none.
|
No
|
Yes
|
Yes
|
--scheduling_policy-thresholds-duration
|
int
|
The number of seconds the host can be overloaded before the scheduler starts and moves the load to another host.
|
No
|
Yes
|
Yes
|
--scheduling_policy-thresholds-high
|
int
|
Controls the highest CPU usage percentage the host can have before being considered overloaded.
|
No
|
Yes
|
Yes
|
--scheduling_policy-thresholds-low
|
int
|
Controls the lowest CPU usage percentage the host can have before being considered underutilized.
|
No
|
Yes
|
Yes
|
--threads_as_cores
|
Boolean
|
Hosts treat threads as cores, allowing hosts to run virtual machines with a total number of processor cores greater than the number of cores in the host. The status is either
true or false.
|
No
|
No
|
No
|
--trusted_service
|
Boolean
|
Defines whether an OpenAttestation server is used to verify hosts.
|
No
|
Yes
|
Yes
|
--virt_service
|
Boolean
|
The status is either
true or false.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
Example 14.5. Creating a new cluster
[RHEVM shell (connected)]# add cluster --name Engineering --cpu-id "Intel Penryn Family" --datacenter-name Default --version-major 3 --version-minor 2
Example 14.6. Updating a cluster
[RHEVM shell (connected)]# update cluster Engineering --name Finance
14.4. datacenter
The
datacenter resource type groups all data center resources in a Red Hat Enterprise Virtualization environment.
Table 14.5. Data Center Parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the data center.
|
Yes
|
Yes
|
Yes
|
--storage_type
|
string
|
The type of storage for the data center, including
iscsi, fcp, nfs, localfs or posixfs.
|
Yes
|
Yes
|
Yes
|
--version-major
|
int
|
The major version number of the data center. For example, for Red Hat Enterprise Virtualization 3.6, the major version is 3.
|
Yes
|
Yes
|
Yes
|
--version-minor
|
int
|
The minor version number of the data center. For example, for Red Hat Enterprise Virtualization 3.6, the minor version is 6.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the data center.
|
No
|
Yes
|
Yes
|
--storage_format
|
string
|
The metadata format for the data center, including
v1, v2 or v3.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
Example 14.8. Creating a new data center
[RHEVM shell (connected)]# add datacenter --name Boston --storage-type nfs --version-major 3 --version-minor 2
Example 14.9. Updating a data center
[RHEVM shell (connected)]# update datacenter Boston --name India
14.5. disk
The
disk resource type groups all virtual hard disk resources in a Red Hat Enterprise Virtualization environment.
Table 14.6. Disk parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--provisioned_size
|
int
|
The reserved storage space for the disk. This space is preallocated for the disk to use, even if the disk
size is less than the provisioned_size
|
Yes
|
Yes
|
Yes
|
--interface
|
string
|
The interface type of the disk. Either
ide or virtio.
|
Yes
|
Yes
|
Yes
|
--format
|
string
|
The underlying storage format. Copy On Write (
cow) allows snapshots, with a small performance overhead. Raw (raw) does not allow snapshots, but offers improved performance.
|
Yes
|
Yes
|
Yes
|
--size
|
int
|
The actual size of the disk.
|
No
|
Yes
|
Yes
|
--sparse
|
Boolean
| true if the physical storage for the disk should not be preallocated.
|
No
|
Yes
|
Yes
|
--bootable
|
Boolean
| true if this disk is to be marked as bootable.
|
No
|
Yes
|
Yes
|
--shareable
|
Boolean
| true if this disk is shareable.
|
No
|
Yes
|
Yes
|
--allow_snapshot
|
Boolean
| true if this disk allows snapshots.
|
No
|
Yes
|
Yes
|
--propagate_errors
|
Boolean
| true if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS.
|
No
|
Yes
|
Yes
|
--wipe_after_delete
|
boolean
| true if the underlying physical storage for the disk should be zeroed when the disk is deleted. This increases security but is a more intensive operation and may prolong delete times.
|
No
|
Yes
|
Yes
|
--storage_domains-storage_domain
|
collection
|
Defines a specific storage domain for the disk.
|
No
|
Yes
|
No
|
The
--storage_domains-storage_domain parameter is a collection that uses the sub-parameters in the following table.
Table 14.7. --storage_domains-storage_domain parameters
| Name | Type | Description |
|---|---|---|
storage_domain.id|name
|
string
|
A reference to a storage domain for the disk.
|
The following table lists additional disk options for resource-based commands.
Table 14.8. Additional command options
| Option | Description |
|---|---|
--vm-identifier | Adds the disk to a vm as a sub-resource. |
--alias | Identifies a disk name when using a show command. Use --alias instead of the --name parameter for disk-specific queries. |
Example 14.11. Creating a new disk
[RHEVM shell (connected)]# add disk --name MyDisk --provisioned_size 8589934592 --interface virtio --format cow
Example 14.12. Updating a storage domain
[RHEVM shell (connected)]# update disk MyDisk --shareable true
The following table lists actions for a virtual machine disk resource.
Table 14.9. Virtual machine disk actions
| Action | Description |
|---|---|
activate | Activate a disk on a virtual machine. |
deactivate | Deactivate a disk on a virtual machine. |
14.6. glustervolume
The
glustervolume resource type groups all Gluster storage volume resources in a Red Hat Enterprise Virtualization environment.
Table 14.10. Gluster volume parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the Gluster volume.
|
Yes
|
Yes
|
No
|
--volume_type
|
string
|
Defines the Gluster volume type. Choose from
DISTRIBUTE, REPLICATE, DISTRIBUTED_REPLICATE, STRIPE or DISTRIBUTED_STRIPE.
|
Yes
|
Yes
|
No
|
--bricks-brick
|
collection
|
A new Gluster volume requires a set of Gluster bricks to add and manage. This parameter references a collection of brick details. Specify at least one brick but list multiple
bricks-brick parameters for multiple bricks. See below for collection details.
|
Yes
|
Yes
|
No
|
--transport_types
|
collection
|
A reference to available transport methods for the Gluster volume. See below for collection details.
|
No
|
Yes
|
No
|
--replica_count
|
integer
|
Defines the file replication count for a replicated volume.
|
No
|
Yes
|
No
|
--stripe_count
|
Integer
|
Defines the stripe count for a striped volume
|
No
|
Yes
|
No
|
--options-option
|
collection
|
A reference to options for the Gluster volume. See below for collection details.
|
No
|
Yes
|
No
|
The
--bricks-brick parameter is a collection that uses the sub-parameters in the following table.
Table 14.11. bricks-brick parameters
| Name | Type | Description |
|---|---|---|
brick.server_id
|
string
|
The address of the Gluster server.
|
brick.brick_dir
|
string
|
The brick's directory on the Gluster server.
|
The
--transport_types parameter is a collection that uses the sub-parameters in the following table.
Table 14.12. transport_types parameters
| Name | Type | Description |
|---|---|---|
transport_type
|
string
|
Defines a transport type to use. Specify multiple
transport_type parameters for more than one type. Choose from TCP and RDMA.
|
The
--options-option parameter is a collection that uses the sub-parameters in the following table.
Table 14.13. options-option parameters
| Name | Type | Description |
|---|---|---|
option.name
|
string
|
The Gluster option name.
|
option.value
|
string
|
The Gluster option value.
|
The following table lists additional
glustervolume options for resource-based commands.
Table 14.14. Additional command options
| Option | Description |
|---|---|
--cluster-identifier | Adds the Gluster volume to a cluster as a sub-resource. |
Example 14.14. Creating a Gluster volume with two bricks
[RHEVM shell (connected)]# add glustervolume --cluster-identifier Default --name GlusterVol1 --volume-type DISTRIBUTE --bricks-brick "brick.server_id=UUID,brick.brick_dir=filepath"--bricks-brick "brick.server_id=UUID,brick.brick_dir=filepath"
Example 14.15. Deleting a Gluster volume
[RHEVM shell (connected)]# remove glustervolume --cluster-identifier Default --name GlusterVol1
The following table lists actions for a Gluster volume resource.
Table 14.15. Gluster volume actions
| Action | Description |
|---|---|
start | Makes a Gluster volume available for use. |
stop | Deactivates a Gluster volume. |
setOption | Sets a Gluster volume option. |
resetOption | Resets a Gluster volume option to the default. |
resetAllOptions | Resets all Gluster volume options to defaults. |
14.7. group
The
group resource type defines all identity service groups for a Red Hat Enterprise Virtualization environment.
Table 14.16. Group parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the group, usually the full group path within the identity directory service.
|
No
|
No
|
No
|
Example 14.16. Creating a group
[RHEVM shell (connected)]# add group --name www.example.com/accounts/groups/mygroup --domain-name example.com
14.8. host
The
host resource type groups all host resources in a Red Hat Enterprise Virtualization environment.
Table 14.17. Host parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the host.
|
Yes
|
Yes
|
Yes
|
--address
|
string
|
The IP address or hostname for the host.
|
Yes
|
Yes
|
Yes
|
--root_password
|
string
|
The password for the host's
root user.
|
Yes
|
Yes
|
Yes
|
--cluster-id|name
|
string
|
Defines the cluster that includes the host.
|
Yes
|
Yes
|
Yes
|
--port
|
int
|
The port for communication with the VDSM daemon running on the host.
|
No
|
Yes
|
Yes
|
--storage_manager-priority
|
int
|
Sets the priority of host order for storage pool manager (SPM).
|
No
|
Yes
|
Yes
|
--power_management-type
|
string
|
The type of power management device in the host.
|
No
|
Yes
|
Yes
|
--power_management-enabled
|
boolean
|
Indicates whether power management configuration is enabled or disabled.
|
No
|
Yes
|
Yes
|
--power_management-address
|
string
|
The host name or IP address of the power management device.
|
No
|
Yes
|
Yes
|
--power_management-user_name
|
string
|
A valid user name for power management.
|
No
|
Yes
|
Yes
|
--power_management-password
|
string
|
A valid, robust password for power management.
|
No
|
Yes
|
Yes
|
--power_management-options-option
|
collection
|
Fencing options for the selected
power_management-type.
|
No
|
Yes
|
Yes
|
--reboot_after_installation
|
boolean
|
Defines if the host reboots after VDSM installation.
|
No
|
Yes
|
No
|
The
--power_management-options-option parameter is a collection that uses the sub-parameters in the following table.
Table 14.18. --power_management-options-option parameters
| Name | Type | Description |
|---|---|---|
option.name
|
string
|
Power management option name.
|
option.value
|
string
|
Power management option value.
|
Example 14.17. Creating a new host
[RHEVM shell (connected)]# add host --name Host1 --address host1.example.com --root_password p@55w0rd! --cluster-name Default
The following table lists actions for a host resource.
Table 14.19. Host actions
| Action | Description |
|---|---|
activate | Activate a host. |
approve | Approve a host. |
commitnetconfig | Save the network configuration. |
deactivate | Deactivate a host. |
fence | Fence a host. |
forceselectspm | Select the host to be the Storage Pool Manager. |
install | Install VDSM on a host. |
iscsidiscover | Perform an iSCSI discover command. |
iscsilogin | Perform an iSCSI login command. |
The following table lists additional options for the
fence action.
Table 14.20. Fencing options
| Option | Description |
|---|---|
manual | Manually fence the host. Use this action to confirm to the Manager that the host became non-responsive and was manually rebooted. |
restart | Restart the host, implemented as stop, wait, status, start, wait, status. |
start | Power on the host. |
stop | Power off the host. |
status | Check the operational status of the host. |
Example 14.20. Confirming a host is rebooted
[RHEVM shell (connected)]# action host Host1 fence --fence_type manual
14.9. network
The
network resource type groups all logical network resources in a Red Hat Enterprise Virtualization environment.
Table 14.21. Logical network parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--data_center-id|name
|
string
|
A reference to the data center for a logical network.
|
Yes
|
Yes
|
No
|
--name
|
string
|
A plain text name for the logical network.
|
Yes
|
Yes
|
No
|
--description
|
string
|
A description for the logical network.
|
No
|
Yes
|
Yes
|
--vlan-id
|
string
|
A VLAN tag.
|
No
|
Yes
|
Yes
|
--ip-address
|
string
|
The IP address for the logical network's bridge.
|
No
|
Yes
|
Yes
|
--ip-gateway
|
string
|
The gateway for the logical network's bridge.
|
No
|
Yes
|
Yes
|
--ip-netmask
|
string
|
The netmask for the logical network's bridge.
|
No
|
Yes
|
Yes
|
--display
|
boolean
|
Signifies if a logical network is used for display communication usage. Set to either
true or false.
|
No
|
Yes
|
Yes
|
--stp
|
boolean
|
Set to
true if Spanning Tree Protocol is enabled on this network.
|
No
|
Yes
|
Yes
|
--mtu
|
int
|
Sets a user-defined value for the maximum transmission unit of the logical network.
|
No
|
Yes
|
Yes
|
--usages-usage
|
collection
|
Defines usage parameters for the logical network.
|
No
|
No
|
Yes
|
The
--usages-usage parameter is a collection that uses the sub-parameters in the following table.
Table 14.22. usages-usage parameters
| Name | Type | Description |
|---|---|---|
usage
|
string
|
Usage types for the network. Options include
VM and DISPLAY.
|
The following table lists additional
network options for resource-based commands.
Table 14.23. Additional command options
| Option | Description |
|---|---|
--cluster-identifier | Adds the network to a cluster as a sub-resource. |
Example 14.21. Creating a new network
[RHEVM shell (connected)]# add network --name WebNetwork --datacenter-name Default --cluster-identifier Default
Example 14.22. Updating a network
[RHEVM shell (connected)]# update network WebNetwork --name DataNetwork
14.10. nic
The
nic resource type groups network interface resources in a Red Hat Enterprise Virtualization environment. These resources acts as sub-resources for both host and vm resources but are defined differently for each. This section contains two tables with parameters for each.
Table 14.24. Host network interface parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--network-id|name
|
string
|
A reference to the network, if any, that the interface is attached.
|
Yes
|
Yes
|
Yes
|
--name
|
string
|
The name of the host network interface, e.g.
eth0.
|
Yes
|
Yes
|
Yes
|
--bonding-slaves-host_nic
|
collection
|
A collection of slave network interfaces that form a bonded interface.
|
No
|
Yes
|
Yes
|
--bonding-options-option
|
collection
|
A list of options for a bonded interface. Each option contains property
name and value attributes.
|
No
|
Yes
|
Yes
|
--ip-gateway
|
string
|
The IP address for the network's gateway.
|
No
|
Yes
|
Yes
|
--boot_protocol
|
string
|
The protocol for IP address assignment when the host is booting, such as
dhcp or static.
|
No
|
Yes
|
Yes
|
--mac
|
string
|
The MAC address of the interface.
|
No
|
Yes
|
Yes
|
--ip-address
|
string
|
The IP address of the interface.
|
No
|
Yes
|
Yes
|
--ip-netmask
|
string
|
The netmask for the interface's IP address.
|
No
|
Yes
|
Yes
|
--ip-mtu
|
int
|
The maximum transmission unit for the interface.
|
No
|
No
|
Yes
|
Table 14.25. Virtual Machine network interface parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--network-id|name
|
string
|
A reference to the network, if any, that the interface is attached.
|
Yes
|
Yes
|
Yes
|
--name
|
string
|
The name of the interface, e.g.
eth0.
|
Yes
|
Yes
|
Yes
|
--mac-address
|
string
|
The MAC address of the interface.
|
No
|
Yes
|
Yes
|
--interface
|
string
|
Defines the interface type, such as
e1000, virtio, rtl8139 and rtl8139_virtio.
|
No
|
Yes
|
Yes
|
--port_mirroring-networks-network
|
collection
|
Defines a set of networks to copy (mirror) network data from the network interface.
|
No
|
Yes
|
Yes
|
The
--bonding-slaves-host_nic parameter is a collection that uses the sub-parameters in the following table.
Table 14.26. --bonding-slaves-host_nic
| Name | Type | Description |
|---|---|---|
host_nic.id|name
|
string
|
A reference to another host NIC to bond.
|
The
--bonding-options-option parameter is a collection that uses the sub-parameters in the following table.
Table 14.27. --bonding-options-option
| Name | Type | Description |
|---|---|---|
option.name
|
string
|
The bonding option name.
|
option.value
|
string
|
The bonding option value.
|
type
|
string
|
The bonding option type.
|
The
--port_mirroring-networks-network parameter is a collection that uses the sub-parameters in the following table.
Table 14.28. --port_mirroring-networks-network
| Name | Type | Description |
|---|---|---|
network.id
|
string
|
A reference to the network to mirror.
|
The following table lists additional NIC options for resource-based commands.
Table 14.29. Additional command options
| Option | Description |
|---|---|
--host-identifier | Adds the NIC to a host as a sub-resource. |
--vm-identifier | Adds the NIC to a vm as a sub-resource. |
Example 14.24. Creating a new network interface on a virtual machine
[RHEVM shell (connected)]# add nic --vm-identifier MyVM1 --name eth0 --network-name MyNetwork
Example 14.25. Updating a network interface on a virtual machine
[RHEVM shell (connected)]# update nic eth0 --vm-identifier MyVM1 --ip-address 10.5.68.123
Example 14.26. Deleting a network interface on a virtual machine
[RHEVM shell (connected)]# remove nic eth0 --vm-identifier MyVM1
Example 14.27. Configuring network bonding on a host
[RHEVM shell (connected)]# add nic --host-identifier MyHost1 --name bond1 --network-name MyNetwork --bonding-slaves-host_nic host_nic.name=eth0 --bonding-slaves-host_nic host_nic.name=eth1
Example 14.28. Assigning a logical network to a host network interface
[RHEVM shell (connected)]# action nic eth0 attach --host-identifier MyHost1 --network-name MyNetwork
The following table lists actions for a host NIC resource.
Table 14.30. Host NIC actions
| Action | Description |
|---|---|
attach | Attach a NIC to a host. |
detach | Detach a NIC from a host. |
The following table lists actions for a virtual machine NIC resource.
Table 14.31. Virtual machine NIC actions
| Action | Description |
|---|---|
activate | Activate a NIC on a virtual machine. |
deactivate | Deactivate a NIC on a virtual machine. |
14.11. permission
The
permission resource type groups all permission resources in a Red Hat Enterprise Virtualization environment.
Table 14.32. Permission parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--user-id, --group-id
|
string
|
A reference to the user or group using the permission.
|
Yes
|
Yes
|
No
|
--role-id
|
string
|
A reference to a role to assign for the permission.
|
Yes
|
Yes
|
No
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
The following table lists additional
permission options for resource-based commands.
Table 14.33. Additional command options
| Option | Description |
|---|---|
--cluster-identifier
|
Adds the permission to a cluster.
|
--correlation-id
|
A tagging identifier for cross-system logging.
|
--cpuprofile-identifier
|
Adds the permission to a CPU profile.
|
--datacenter-identifier
|
Adds the permission to a data center.
|
--disk-identifier
|
Adds the permission to a disk.
|
--diskprofile-identifier
|
Adds the permission to a disk profile.
|
--host-identifier
|
Adds the permission to a host.
|
--iscsibond-identifier
|
Adds the permission to an iSCSI bond.
|
--network-identifier
|
Adds the permission to a network.
|
--storagedomain-identifier
|
Adds the permission to a storage domain.
|
--template-identifier
|
Adds the permission to a template.
|
--vm-identifier
|
Adds the permission to a virtual machine.
|
--vmpool-identifier
|
Adds the permission to a virtual machine pool.
|
--vnicprofile-identifier
|
Adds the permission to a VNIC profile.
|
Example 14.29. Creating a new permission
[RHEVM shell (connected)]# add permission --role-id 00000000-0000-0000-0000-000000000001 --user-id 8b9456ae-e2c8-426e-922d-b01bb8a805fb
14.12. permit
The
permit resource type groups all individual permits for roles in a Red Hat Enterprise Virtualization environment.
Table 14.34. Permission parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--id
|
string
|
A reference to the permit to add.
|
Yes
|
Yes
|
No
|
The following table lists additional
permit options for resource-based commands.
Table 14.35. Additional command options
| Option | Description |
|---|---|
--role-identifier
|
Adds the permit to a role.
|
Example 14.30. Creating a new permission
[RHEVM shell (connected)]# add permit --role-identifier MyRole --id 1
14.13. quotas
The
quota resource type groups all datacenter quotas in a Red Hat Enterprise Virtualization environment.
Table 14.36. Quota parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the quota.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the quota.
|
Yes
|
Yes
|
Yes
|
14.14. role
The
role resource type groups all individual roles in a Red Hat Enterprise Virtualization environment.
Table 14.37. Role parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the role.
|
Yes
|
Yes
|
Yes
|
--permits-permit
|
collection
|
A list of permits for initial inclusion with the role. Additional permits included with the permit resource type.
|
Yes
|
Yes
|
No
|
--description
|
string
|
A description for the role.
|
No
|
Yes
|
Yes
|
--administrative
|
Boolean
|
Set to
true if this is an administrative role.
|
No
|
Yes
|
Yes
|
The
--permits-permit parameter is a collection that uses the sub-parameters in the following table.
Table 14.38. --permits-permit parameters
| Name | Type | Description |
|---|---|---|
permit.id
|
string
|
A reference to a permit to add to the role's permits.
|
Example 14.31. Creating a new role
[RHEVM shell (connected)]# add role --name MyRole --permits-permit {permit.id: 1;},{permit.id: 2;)14.15. snapshot
The
snapshot resource type groups all virtual machine snapshot resources in a Red Hat Enterprise Virtualization environment.
Table 14.39. Snapshot parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--description
|
string
|
A description for the snapshot.
|
Yes
|
Yes
|
No
|
The following table lists additional snapshot options for resource-based commands.
Table 14.40. Additional command options
| Option | Description |
|---|---|
--vm-identifier | Adds the disk to a vm as a sub-resource. |
Example 14.32. Creating a new snapshot
[RHEVM shell (connected)]# add snapshot --vm-identifier MyVM --description 'My Snapshot'
The following table lists actions for a virtual machine snapshot resource.
14.16. statistic
The
statistic resource type groups statistics for resources in a Red Hat Enterprise Virtualization environment. Resource statistics are listed based on their resource identifier.
Table 14.42. statistic resource identifiers
| Option | Description |
|---|---|
--brick-identifier | The resource identifier to view statistics for the specified brick. |
--cluster-identifier | The resource identifier to view statistics for the specified cluster. |
--datacenter-identifier | The resource identifier to view statistics for the specified data center. |
--disk-identifier | The resource identifier to view statistics for the specified virtual machine disk. |
--glustervolume-identifier | The resource identifier to view statistics for the specified gluster volume. |
--host-identifier | The resource identifier to view statistics for the specified host. |
--job-identifier | The resource identifier to view statistics for the specified job. |
--nic-identifier | The resource identifier to view statistics for the specified NIC. |
--numanode-identifier | The resource identifier to view statistics for the specified NUMA node. |
--step-identifier | The resource identifier to view statistics for the specified step. |
--storagedomain-identifier | The resource identifier to view statistics for the specified storage domain. |
--vm-identifier | The resource identifier to view statistics for the specified virtual machine. |
View the collection of statistics for each resource by using the
list command and the relevant resource identifier. The following example provides a list of the available statistics for the specified host:
[RHEVM shell (connected)]# list statistics --host-identifier Host_name|id
The
name or id of the provided statistics can be used with the show command and the resource identifier to view further information on the specified statistic. The following example shows the details of the specified statistic for the host:
[RHEVM shell (connected)]# show statistic statistic_name|id --host-identifier Host name|id
14.17. storageconnection
The
storageconnection resource type allows you to add, edit, and delete storage connections.
Table 14.43. Storage connection parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--address
|
string
|
The hostname or IP address of the storage domain.
|
Yes (NFS and iSCSI only)
|
Yes
|
Yes
|
--correlation_id
|
string
|
A tagging identifier for the storage connection.
|
No
|
No
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--iqn
|
string
|
The target IQN for the storage device.
|
Yes (iSCSI only)
|
Yes
|
Yes
|
--mount_options
|
string
|
The options for mounting the PosixFS share.
|
No
|
Yes
|
Yes
|
--nfs_retrans
|
integer
|
The number of retransmissions the NFS client will attempt to complete a request.
|
No
|
Yes
|
Yes
|
--nfs_timeo
|
integer
|
The amount of time, in deciseconds, the NFS client will wait for a request to complete.
|
No
|
Yes
|
Yes
|
--nfs_version
|
string
|
The version of NFS used.
|
No
|
Yes
|
Yes
|
--password
|
string
|
A CHAP password for logging into a target of an iSCSI storage domain.
|
No
|
Yes
|
Yes
|
--path
|
string
|
The mounted file path of the storage domain. The path cannot be updated to one already used by a storage connection.
|
Yes (NFS, local, and PosixFS only)
|
Yes
|
Yes
|
--port
|
integer
|
The TCP port used for the iSCSI storage domain.
|
Yes (iSCSI only)
|
Yes
|
Yes
|
--storagedomain-identifier
|
string
|
A reference to a storage domain for the disk.
|
No
|
No
|
No
|
--type
|
string
|
The type of storage domain.
|
Yes
|
Yes
|
No
|
--username
|
string
|
A CHAP user name for logging into a target of an iSCSI storage domain.
|
No
|
Yes
|
Yes
|
--vfs_type
|
string
|
The Linux-supported file system type of the PosixFS share.
|
Yes (PosixFS only)
|
Yes
|
Yes
|
Example 14.34. Creating a new storage connection
[RHEVM shell (connected)]# add storageconnection --address storage.example.com --path /storage/nfs --type nfs
14.18. storagedomain
The
storagedomain resource type groups all storage domain resources in a Red Hat Enterprise Virtualization environment.
Table 14.44. Storage domain parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the storage domain.
|
No
|
Yes
|
Yes
|
--format
|
Boolean
|
The metadata format for the data center, including
v1, v2 or v3.
|
Yes
|
Yes
|
No
|
--host-id|name
|
string
|
A reference to the host from which this storage domain should be initialized. The only restriction on this host is that it should have access to the physical storage specified.
|
Yes
|
Yes
|
No
|
--storage-address
|
string
|
The IP address or hostname of the storage device.
|
Yes
|
Yes
|
No
|
--storage-logical_unit
|
collection
|
The logical unit information of the storage device.
|
See below
|
Yes
|
No
|
--storage-mount_options
|
string
|
The options for mounting the storage domain.
|
See below
|
Yes
|
No
|
--storage-override_luns
|
Boolean
|
Defines whether to override the logical unit number. The status is either
true or false.
|
See below
|
Yes
|
No
|
--storage-path
|
string
|
The path on the storage device to use for the storage domain.
|
See below
|
Yes
|
No
|
--storage-type
|
string
|
The type of storage for the data center, including
iscsi, fcp, nfs, glusterfs, localfs or posixfs.
|
Yes
|
Yes
|
No
|
--storage-vfs_type
|
string
|
Defines the file system type of the storage domain.
|
See below
|
Yes
|
No
|
--type
|
string
|
The type of storage domain, including
data, iso and export.
|
Yes
|
Yes
|
No
|
The
--storage-logical_unit parameter is a collection that requires all sub-parameters in the following table.
Table 14.45. storage-logical_unit parameters
| Name | Type | Description |
|---|---|---|
logical_unit.address
|
string
|
The address of the server containing the storage device.
|
logical_unit.port
|
integer
|
The port number of the server.
|
logical_unit.target
|
string
|
The target IQN for the storage device.
|
logical_unit.username
|
string
|
A CHAP user name for logging into a target.
|
logical_unit.password
|
string
|
A CHAP password for logging into a target.
|
logical_unit.serial
|
string
|
The serial ID for the target.
|
logical_unit.vendor_id
|
string
|
The vendor name for the target.
|
logical_unit.product_id
|
string
|
The product code for the target.
|
logical_unit.lun_mapping
|
integer
|
The Logical Unit Number device mapping for the target.
|
logical_unit.portal
|
string
|
The logical unit portal.
|
logical_unit.paths
|
integer
|
The logical unit paths.
|
logical_unit.id
|
string
|
A reference to the logical unit ID.
|
Use the following parameters depending on
storage-type.
Table 14.46. Storage type parameters
| Type | Parameters |
|---|---|
nfs
| --storage-address, --storage-path
|
iscsi or fcp
| --storage-address, --storage-logical_unit, --storage-override_luns
|
glusterfs
| --storage-address, --storage-path, --storage-vfs_type
|
local
| --storage-path
|
posixfs
| --storage-path, --storage-vfs_type, --storage-address, --storage-mount_options
|
The following table lists additional
storagedomain options for resource-based commands.
Table 14.47. Additional command options
| Option | Description |
|---|---|
--datacenter-identifier | Adds the storage domain to a datacenter as a sub-resource. |
Example 14.35. Creating a new storage domain
[RHEVM shell (connected)]# add storagedomain --name DataStorage --datacenter-name Default -type data
Example 14.36. Adding a gluster storage domain
[RHEVM shell (connected)]# add storagedomain --type data --storage-type glusterfs --name RHS_01 --storage-address 192.0.2.0 --storage-path Vol_ONE --storage-vfs_type glusterfs
Example 14.37. Updating a storage domain
[RHEVM shell (connected)]# update storagedomain DataStorage --name DataStorageOld
Example 14.38. Deleting a storage domain
[RHEVM shell (connected)]# remove storagedomain DataStorage
The following table lists actions for a storage domain resource.
Table 14.48. Storage domain actions
| Action | Description |
|---|---|
activate | Activate a storage domain on a data center. |
deactivate | Deactivate a storage domain on a data center. |
14.19. tag
The
tag resource type groups all tags in a Red Hat Enterprise Virtualization environment.
Table 14.49. Tag parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the tag.
|
Yes
|
Yes
|
Yes
|
--description
|
string
|
A description for the string.
|
Yes
|
Yes
|
Yes
|
--parent-name
|
string
|
A reference to the parent tag that the tag is attached.
|
Yes
|
Yes
|
Yes
|
Example 14.39. Creating a new tag
[RHEVM shell (connected)]# add tag --name MyTag --description "A virtual machine tag" --parent MyParentTag
14.20. template
The
template resource type groups all virtual machine templates in a Red Hat Enterprise Virtualization environment. Only --vm-id|name and --name are required parameters. If the optional parameters are not specified, the template will inherit the settings from the virtual machine used to make the template.
Table 14.50. Template parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--vm-id|name
|
string
|
A reference to the virtual machine used as the basis for the template.
|
Yes
|
Yes
|
No
|
--name
|
string
|
The name of the virtual machine template.
|
Yes
|
Yes
|
Yes
|
--memory
|
long
|
The amount of memory for the virtual machine template in bytes.
|
No
|
Yes
|
Yes
|
--cpu-topology-cores
|
int
|
The number of CPU cores available to the virtual machine template.
|
No
|
Yes
|
Yes
|
--high_availability-enabled
|
Boolean
|
Set to
true to enable high availability for the virtual machine template.
|
No
|
Yes
|
Yes
|
--os-cmdline
|
string
|
A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--origin
|
string
|
The virtual machine template's origin. Specify
rhev, vmware, or xen.
|
No
|
Yes
|
Yes
|
--high_availability-priority
|
int
|
Sets the priority value (i.e. boot order) of each virtual machine template's high availability.
|
No
|
Yes
|
Yes
|
--timezone
|
string
|
The Sysprep timezone setting for a Windows virtual machine template. Specify formats such as
GMT+00:00.
|
No
|
Yes
|
Yes
|
--domain-name
|
string
|
The domain name of the virtual machine template.
|
No
|
Yes
|
Yes
|
--type
|
string
|
Defines the virtual machine type. Specify either
desktop or server.
|
No
|
Yes
|
Yes
|
--stateless
|
boolean
|
Set to
true if the resulting virtual machines are stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and removed at shutdown. This means state changes do not persist after a reboot.
|
No
|
Yes
|
Yes
|
--delete_protected
|
boolean
|
Set to
true to make it impossible to delete a virtual machine created from this template.
|
No
|
Yes
|
Yes
|
--sso-methods-method
|
collection
|
Defines the single sign-on method used. For example,
--sso-methods-method method.id=GUEST_AGENT.
|
No
|
Yes
|
Yes
|
--rng_device-rate-bytes
|
int
|
Specifies how many bytes are permitted to be consumed per period.
|
No
|
Yes
|
Yes
|
--rng_device-rate-period
|
int
|
Specifies the duration of a period in milliseconds. If specified,
--rng_device-rate-bytes must be specified as well.
|
No
|
Yes
|
Yes
|
--rng_device-source
|
string
|
The source of the random number generator. Specify either
random or hwrng.
|
No
|
Yes
|
Yes
|
--console-enabled
|
boolean
|
Set to
true to enable the VirtIO console device feature.
|
No
|
Yes
|
Yes
|
--placement_policy-affinity
|
string
|
The migration affinity for each virtual machine created from the template. Specify
migratable, user_migratable, or pinned.
|
No
|
Yes
|
Yes
|
--description
|
string
|
A description for the virtual machine template.
|
No
|
Yes
|
Yes
|
--comment
|
string
|
A comment for the virtual machine template.
|
No
|
Yes
|
Yes
|
--custom_properties-custom_property
|
collection
|
A set of user-defined environment variables passed as parameters to custom scripts.
|
No
|
Yes
|
Yes
|
--os-type
|
string
|
The operating system type for the virtual machine template.
|
No
|
Yes
|
Yes
|
--os-boot
|
collection
|
The boot device for the virtual machine template. Specify
cdrom, hd, or network. For example, --os-boot boot.dev=hd.
|
No
|
Yes
|
Yes
|
--cpu-topology-sockets
|
int
|
The number of CPU sockets available to the virtual machine template.
|
No
|
Yes
|
Yes
|
--cpu_shares
|
int
|
The level of CPU resources a virtual machine can demand relative to other virtual machines. For example,
512 for low priority virtual machines, 1024 for medium priority virtual machines, and 2048 for high priority virtual machines.
|
No
|
Yes
|
Yes
|
--cpu-architecture
|
string
|
Defines the CPU architecture. Specify
x86_64, ppc64, or undefined.
|
No
|
Yes
|
Yes
|
--os-kernel
|
string
|
A path to a kernel image the resulting virtual machines are configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--display-type
|
string
|
Defines the display type. Specify either
spice or vnc.
|
No
|
Yes
|
Yes
|
--display-monitors
|
int
|
Defines the number of displays available.
|
No
|
Yes
|
Yes
|
--display-single_qxl_pci
|
boolean
|
Set to
true to drive multiple monitors using a single virtual PCI device.
|
No
|
Yes
|
Yes
|
--display-allow_override
|
boolean
|
Set to
true to allow override of the template console settings.
|
No
|
Yes
|
Yes
|
--display-smartcard_enabled
|
boolean
|
Set to
true to enable the Smart card feature for virtual machines.
|
No
|
Yes
|
Yes
|
--display-file_transfer_enabled
|
boolean
|
Set to
true to enable SPICE file transfer.
|
No
|
Yes
|
Yes
|
--display-copy_paste_enabled
|
boolean
|
Set to
true to enable SPICE clipboard copy and paste.
|
No
|
Yes
|
Yes
|
--display-keyboard_layout
|
string
|
Defines the keyboard layout for the virtual machine. This option is only available when using the VNC protocol. Specify formats such as
en-US.
|
No
|
Yes
|
Yes
|
--os-initRd
|
string
|
A path to an initrd image to be used with a specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--usb-enabled
|
Boolean
|
Set to
true to enable USB support on the virtual machine. This option is only available for virtual machines using the SPICE protocol.
|
No
|
Yes
|
Yes
|
--usb-type
|
string
|
Defines the USB type if USB support is enabled. Specify either
Legacy or Native.
|
No
|
Yes
|
Yes
|
--tunnel_migration
|
boolean
|
Set to
true to enable data transport over a libvirt daemon. A tunneled transport uses a stronger encryption algorithm but increases the data load during transport.
|
No
|
Yes
|
Yes
|
--migration_downtime
|
int
|
Defines the maximum number of milliseconds that the virtual machine can be down during live migration.
|
No
|
Yes
|
Yes
|
--virtio_scsi-enabled
|
boolean
|
Set to
true to allow attaching a VirtIO console device to the virtual machine.
|
No
|
Yes
|
Yes
|
--soundcard_enabled:
|
boolean
|
Set to
true to enable sound cards.
|
No
|
Yes
|
Yes
|
--vm-disks-disk
|
collection
|
References to disks attached to the template.
|
No
|
Yes
|
No
|
--id
|
string
|
The ID of the virtual machine template.
|
No
|
Yes
|
Yes
|
--permissions-clone
|
boolean
|
Set to
true to copy the permissions of the source virtual machine to the template.
|
No
|
Yes
|
Yes
|
--version-version_name
|
string
|
Used with the
--version-base_template-id parameter. Defines the name for the sub template.
|
No
|
Yes
|
Yes
|
--version-base_template-id
|
string
|
Defines the template ID to be used as the root template. Used if you want to create this template as a sub template of a root template.
|
No
|
Yes
|
Yes
|
--cpu-cpu_tune-vcpu_pin
|
collection
|
Defines which virtual CPUs of a virtual machine to pin to the physical CPUs of a host.
|
No
|
Yes
|
Yes
|
--serial_number-policy
|
string
|
Defines the serial number policy for the virtual machine template. Specify
host, vm, or custom. If custom is used, also define the serial number value using --serial_number-value.
|
No
|
Yes
|
Yes
|
--serial_number-value
|
string
|
Defines the serial number for the virtual machine template.
|
No
|
Yes
|
Yes
|
--bios-boot_menu-enabled
|
boolean
|
Set to
true to enable boot menu.
|
No
|
Yes
|
Yes
|
--cluster-id
|
string
|
Defines the cluster to use by specifying the cluster ID.
|
No
|
Yes
|
Yes
|
--cluster-name
|
string
|
Defines the cluster to use by specifying the cluster name.
|
No
|
Yes
|
Yes
|
--cpu_profile-id
|
string
|
Defines the CPU profile to use. Use the
list cpuprofiles command to retrieve a full list of CPU profile IDs.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
Yes
|
Yes
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
Yes
|
The
--sso-methods-method parameter is a collection that uses the sub-parameters in the following table.
Table 14.51. --sso-methods-method parameters
| Name | Type | Description |
|---|---|---|
method.id
|
string
|
The single sign-on method used:
GUEST_AGENT.
|
The
--custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.
Table 14.52. --custom_properties-custom_property parameters
| Name | Type | Description |
|---|---|---|
custom_property.name
|
string
|
The custom property name.
|
custom_property.value
|
string
|
The custom property value.
|
The
--os-boot parameter is a collection that uses the sub-parameters in the following table.
Table 14.53. --os-boot parameters
| Name | Type | Description |
|---|---|---|
boot.dev
|
string
|
The boot device for the virtual machine template. Specify
cdrom, hd, or network.
|
The
--vm-disks-disk parameter is a collection that uses the sub-parameters in the following table.
Table 14.54. --vm-disks-disk parameters
| Name | Type | Description |
|---|---|---|
disk.id
|
string
|
A reference to a virtual machine disk.
|
storage_domains.storage_domain
|
collection
|
Defines a set of sub-parameters for the disk's storage domain.
|
The
--cpu-cpu_tune-vcpu_pin parameter is a collection that uses the sub-parameters in the following table.
Table 14.55. --cpu-cpu_tune-vcpu_pin parameters
| Name | Type | Description |
|---|---|---|
vcpu_pin.vcpu
|
int
|
The virtual CPU to assign.
|
vcpu_pin.cpu_set
|
string
|
The physical CPUs on the host.
|
Example 14.40. Creating a new template
[RHEVM shell (connected)]# add template --name MyTemplate1 --vm-name MyVM1
Example 14.41. Updating a template
[RHEVM shell (connected)]# update template MyTemplate1 --memory 1073741824
The following table lists actions for a virtual machine template resource.
Table 14.56. Virtual machine template actions
| Action | Description |
|---|---|
export | Export a template to an export storage domain. |
14.21. user
The
user resource type groups all users in a Red Hat Enterprise Virtualization environment.
Table 14.57. User parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--user_name
|
string
|
The user name from the directory service.
|
Yes
|
Yes
|
No
|
--domain-id|name
|
string
|
A reference to the directory service domain.
|
Yes
|
Yes
|
No
|
Example 14.43. Creating a new user
[RHEVM shell (connected)]# add user --user_name jsmith --domain-name example.com
14.22. vm
The
vm resource type groups all virtual machine resources in a Red Hat Enterprise Virtualization environment.
Table 14.58. Virtual machine parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the virtual machine
|
Yes
|
Yes
|
Yes
|
--template-id|name
|
string
|
A reference to the template used as the basis for the virtual machine.
|
Yes
|
Yes
|
No
|
--cluster-id|name
|
string
|
A reference to the cluster that includes this VM.
|
Yes
|
Yes
|
Yes
|
--instance_type-id|name
|
string
|
Defines the instance type. Specify
custom, large, medium, small, tiny, or xlarge.
|
No
|
Yes
|
Yes
|
--quota-id
|
string
|
A reference to the quota usage for the virtual machine.
|
No
|
Yes
|
No
|
--timezone
|
string
|
The Sysprep time zone setting for a Windows virtual machine.
|
No
|
Yes
|
Yes
|
--os-boot
|
collection
|
The boot device for the virtual machine. Specify
cdrom, hd, or network.
|
No
|
Yes
|
Yes
|
--custom_properties-custom_property
|
collection
|
A set of user-defined environment variables passed as parameters to custom scripts.
|
No
|
Yes
|
Yes
|
--os-type
|
string
|
The operating system type for this virtual machine.
|
No
|
Yes
|
Yes
|
--usb-enabled
|
boolean
|
Defines the USB policy for a virtual machine. Set to
true to enable USB on the virtual machine.
|
No
|
Yes
|
Yes
|
--usb-type
|
string
|
Defines the USB type if enabled.
|
No
|
Yes
|
Yes
|
--type
|
string
|
Defines the virtual machine type. Specify either
desktop or server.
|
No
|
Yes
|
Yes
|
--os-initRd
|
string
|
A path to an initrd image to be used with a specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--display-monitors
|
int
|
Defines the number of displays available.
|
No
|
Yes
|
Yes
|
--display-single_qxl_pci
|
boolean
|
Set to
true to drive multiple monitors using a single virtual PCI device.
|
No
|
Yes
|
Yes
|
--display-type
|
string
|
Defines the display type. Specify either
spice or vnc.
|
No
|
Yes
|
Yes
|
--display-allow_override
|
boolean
|
Set to
true to allow override of the virtual machine console settings.
|
No
|
Yes
|
Yes
|
--display-smartcard_enabled
|
boolean
|
Set to
true to enable the Smart card feature.
|
No
|
Yes
|
Yes
|
--display-file_transfer_enabled
|
boolean
|
Set to
true to enable SPICE file transfer.
|
No
|
Yes
|
Yes
|
--display-copy_paste_enabled
|
boolean
|
Set to
true to enable SPICE clipboard copy and paste.
|
No
|
Yes
|
Yes
|
--display-keyboard_layout
|
string
|
Defines the keyboard layout for the virtual machine. This option is only available when using the VNC protocol. Specify formats such as
en-US.
|
No
|
Yes
|
Yes
|
--os-cmdline
|
string
|
A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--cpu-topology-cores
|
int
|
The number of CPU cores available to the virtual machine.
|
No
|
Yes
|
Yes
|
--cpu-architecture
|
string
|
Defines the CPU architecture. Specify
x86_64, ppc64, or undefined.
|
No
|
Yes
|
Yes
|
--memory
|
long
|
The amount of memory for the virtual machine in bytes.
|
No
|
Yes
|
Yes
|
--memory_policy-guaranteed
|
long
|
The minimum amount of memory, in bytes, guaranteed on a host in order for the virtual machine to run.
|
No
|
Yes
|
Yes
|
--memory_policy-ballooning
|
boolean
|
Set to
true to enable memory balloon device.
|
No
|
Yes
|
Yes
|
--high_availability-priority
|
int
|
Sets the priority value (migration and restart order) of each virtual machine using high availability.
|
No
|
Yes
|
Yes
|
--high_availability-enabled
|
boolean
|
Defines whether high availability is enabled for the virtual machine.
|
No
|
Yes
|
Yes
|
--domain-name
|
string
|
The domain name of the virtual machine.
|
No
|
Yes
|
Yes
|
--description
|
string
|
A description of the virtual machine.
|
No
|
Yes
|
Yes
|
--comment
|
string
|
A comment for the virtual machine.
|
No
|
Yes
|
Yes
|
--stateless
|
boolean
|
Set to
true if the virtual machine is stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and removed at shutdown. This means state changes do not persist after a reboot.
|
No
|
Yes
|
Yes
|
--permissions-clone
|
boolean
|
Set to
true to copy the permissions of the source virtual machine to the template.
|
No
|
Yes
|
Yes
|
--delete_protected
|
boolean
|
Set to
true to make it impossible to delete a virtual machine created from this template.
|
No
|
Yes
|
Yes
|
--sso-methods-method
|
collection
|
Defines the single sign-on method used. For example,
--sso-methods-method method.id=GUEST_AGENT.
|
No
|
Yes
|
Yes
|
--rng_device-rate-bytes
|
int
|
Specifies how many bytes are permitted to be consumed per period.
|
No
|
Yes
|
Yes
|
--rng_device-rate-period
|
int
|
Specifies the duration of a period in milliseconds. If specified,
--rng_device-rate-bytes must be specified as well.
|
No
|
Yes
|
Yes
|
--rng_device-source
|
string
|
The source of the random number generator. Specify either
random or hwrng.
|
No
|
Yes
|
Yes
|
--console-enabled
|
boolean
|
Set to
true to enable the VirtIO console device feature.
|
No
|
Yes
|
Yes
|
--cpu-mode
|
string
|
Defines the CPU mode. Specify
custom, host_model, or host_passthrough.
|
No
|
Yes
|
Yes
|
--cpu-topology-sockets
|
int
|
The number of CPU sockets available to the virtual machine.
|
No
|
Yes
|
Yes
|
--cpu_shares
|
int
|
The level of CPU resources a virtual machine can demand relative to other virtual machines. For example,
512 for low priority virtual machines, 1024 for medium priority virtual machines, and 2048 for high priority virtual machines.
|
No
|
Yes
|
Yes
|
--placement_policy-affinity
|
string
|
The migration affinity for each virtual machine. Specify
migratable, user_migratable, or pinned.
|
No
|
Yes
|
Yes
|
--placement_policy-host-id|name
|
string
|
A reference to the preferred host for migration affinity.
|
No
|
Yes
|
Yes
|
--origin
|
string
|
The virtual machine's origin. Specify
rhev, vmware, or xen.
|
No
|
Yes
|
Yes
|
--os-kernel
|
string
|
A path to a kernel image the virtual machine is configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
|
No
|
Yes
|
Yes
|
--disks-clone
|
boolean
|
Defines whether to clone the disk from the defined
template.
|
No
|
Yes
|
No
|
--disks-disk
|
collection
|
References to disks attached to the virtual machine.
|
No
|
Yes
|
Yes
|
--tunnel_migration
|
boolean
|
Set to
true to enable data transport over a libvirt daemon. A tunneled transport uses a stronger encryption algorithm but increases the data load during transport.
|
No
|
Yes
|
Yes
|
--migration_downtime
|
int
|
Defines the maximum number of milliseconds that the virtual machine can be down during live migration.
|
No
|
Yes
|
Yes
|
--virtio_scsi-enabled
|
boolean
|
Set to
true to allow attaching a VirtIO console device to the virtual machine.
|
No
|
Yes
|
Yes
|
--soundcard_enabled:
|
boolean
|
Set to
true to enable sound cards.
|
No
|
Yes
|
Yes
|
--payloads-payload
|
collection
|
Defines content to send to the virtual machine upon booting.
|
No
|
Yes
|
Yes
|
--initialization-configuration-type
|
string
| Defines the virtual machine format. Accepts only ovf. |
No
|
Yes
|
Yes
|
--initialization-configuration-data
|
string
|
This parameter must match the
--initialization-configuration-type parameter. Accepts only ovf.
|
No
|
Yes
|
Yes
|
--cpu-cpu_tune-vcpu_pin
|
collection
|
Defines which virtual CPUs of a virtual machine to pin to the physical CPUs of a host.
|
No
|
Yes
|
Yes
|
--serial_number-policy
|
string
|
Defines the serial number policy for the virtual machine template. Specify
host, vm, or custom. If custom is used, also define the serial number value using --serial_number-value.
|
No
|
Yes
|
Yes
|
--serial_number-value
|
string
|
Defines the serial number for the virtual machine template.
|
No
|
Yes
|
Yes
|
--bios-boot_menu-enabled
|
boolean
|
Set to
true to enable boot menu.
|
No
|
Yes
|
Yes
|
--numa_tune_mode
|
string
|
Defines how to allocate memory for the domain process on a NUMA host. Specify
interleave, strict, or preferred. If no value is given, the parameter defaults to strict.
|
No
|
Yes
|
Yes
|
--cpu_profile-id
|
string
|
Defines the CPU profile to use. Use the
list cpuprofiles command to retrieve a full list of CPU profile IDs.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
The
--os-boot parameter is a collection that uses the sub-parameters in the following table.
Table 14.59. --os-boot parameters
| Name | Type | Description |
|---|---|---|
boot.dev
|
string
|
The boot device for the virtual machine template. Specify
cdrom, hd, or network.
|
The
--custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.
Table 14.60. --custom_properties-custom_property parameters
| Name | Type | Description |
|---|---|---|
custom_property.name
|
string
|
The custom property name.
|
custom_property.value
|
string
|
The custom property value.
|
The
--sso-methods-method parameter is a collection that uses the sub-parameters in the following table.
Table 14.61. --sso-methods-method parameters
| Name | Type | Description |
|---|---|---|
method.id
|
string
|
The single sign-on method used:
GUEST_AGENT.
|
The
--disks-disk parameter is a collection that uses the sub-parameters in the following table.
Table 14.62. --disks-disk parameters
| Name | Type | Description |
|---|---|---|
disk.id
|
string
|
A reference to a virtual machine disk.
|
storage_domains.storage_domain
|
collection
|
Defines a set of sub-parameters for the disk's storage domain.
|
The
--payloads-payload parameter is a collection that uses the sub-parameters in the following table.
Table 14.63. --payloads-payload parameters
| Name | Type | Description |
|---|---|---|
payload.type
|
string
|
Payload delivery type. Specify either
cdrom or floppy.
|
payload.file.name
|
string
|
The payload file name and location on the root file system of the virtual machine.
|
payload.file.content
|
string
|
The content to deliver to the file.
|
The
--cpu-cpu_tune-vcpu_pin parameter is a collection that uses the sub-parameters in the following table.
Table 14.64. --cpu-cpu_tune-vcpu_pin
| Name | Type | Description |
|---|---|---|
vcpu_pin.vcpu
|
int
|
The virtual CPU to assign.
|
vcpu_pin.cpu_set
|
string
|
The physical CPUs on the host.
|
Example 14.44. Creating a new virtual machine
[RHEVM shell (connected)]# add vm --name MyVM --template-name Blank --cluster-name Default --memory 536870912
Example 14.45. Updating a virtual machine
[RHEVM shell (connected)]# update vm MyVM --memory 1073741824
The following table lists actions for a virtual machine resource.
Table 14.65. Virtual machine actions
| Action | Description |
|---|---|
start | Launch a virtual machine. |
stop | Stop a virtual machine. |
shutdown | Shut down a virtual machine. |
suspend | Suspend a virtual machine. |
detach | Detach a virtual machine from a pool. |
migrate | Migrate a virtual machine to another host. |
cancelmigration | Stop migration in progress. |
export | Export a virtual machine to an export storage domain. |
move | Move virtual machine disks to another storage domain. |
ticket | Create a ticket for console access. |
logon | Enable user logon for console access using third-party applications. |
14.23. vmpool
The
vmpool resource type groups all virtual machine pool resources in a Red Hat Enterprise Virtualization environment.
Table 14.66. Virtual machine pool parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--cluster-id|name
|
string
|
A reference to the cluster for the virtual machine pool.
|
Yes
|
Yes
|
Yes
|
--template-id|name
|
string
|
A reference to the template for the virtual machine pool.
|
Yes
|
Yes
|
Yes
|
--name
|
string
|
The name of the virtual machine pool.
|
Yes
|
Yes
|
Yes
|
--size
|
integer
|
The number of the virtual machines in the pool.
|
Yes
|
Yes
|
Yes
|
Example 14.47. Creating a new virtual machine pool
[RHEVM shell (connected)]# add vmpool --cluster-name MyCluster --template-name MyTemplate --name MyPool --size 3
Example 14.48. Updating a virtual machine pool
[RHEVM shell (connected)]# update vmpool MyPool --size 4
14.24. vnicprofile
The
vnicprofile resource type groups all VNIC (virtual network interface controller) profiles, also referred to as VM (virtual machine) interface profiles, in a Red Hat Enterprise Virtualization environment.
Table 14.67. Virtual Network Interface Controller Profile Parameters
| Name | Type | Description | Required | User Creatable | User Updatable |
|---|---|---|---|---|---|
--name
|
string
|
The name of the VNIC profile.
|
Yes
|
Yes
|
Yes
|
--network-id
|
string
|
A reference to the logical network to which the profile will be applied.
|
Yes
|
No
|
No
|
--correlation_id
|
string
|
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
|
No
|
Yes
|
No
|
--description
|
string
|
A description for the profile.
|
No
|
Yes
|
Yes
|
--expect
|
'201-created'
|
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
|
No
|
No
|
No
|
--custom_properties-custom_property
|
collection
|
A set of user-defined environment variables passed as parameters to custom scripts.
|
No
|
Yes
|
Yes
|
--port_mirroring
|
Boolean
|
Toggles whether port mirroring is used for the profile. The status is either
True or False. Default is Falses
|
No
|
No
|
No
|
The
--custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.
Table 14.68. --custom_properties-custom_property parameters
| Name | Type | Description |
|---|---|---|
custom_property.name
|
string
|
The custom property name.
|
custom_property.value
|
string
|
The custom property value.
|
Example 14.50. Creating a new vnic profile
[RHEVM shell (connected)]# add vnicprofile --name Gold --network-id 08305a2f-6952-4999-9646-c16137dc6d42
Example 14.51. Updating a vnic profile
[RHEVM shell (connected)]# update vnicprofile Gold --port_mirroring true
Chapter 15. CLI Queries
15.1. Query Syntax
The CLI
list command uses the --query attribute to perform server-side queries, which uses the same format as Red Hat Enterprise Virtualization Manager search query language:
Table 15.1. Example search queries
| Collection | Criteria | Result |
|---|---|---|
hosts | vms.status=up | Displays a list of all hosts running virtual machines that are up. |
vms | domain=qa.company.com | Displays a list of all virtual machines running on the specified domain. |
vms | users.name=mary | Displays a list of all virtual machines belonging to users with the user name mary. |
events | severity>normal sortby time | Displays the list of all events with severity higher than normal and sorted by the time element values. |
events | severity>normal sortby time desc | Displays the list of all events with severity higher than normal and sorted by the time element values in descending order. |
15.2. Wildcards
Search queries substitute part of a value with an asterisk as a wildcard.
Example 15.1. Wildcard search query for name=vm*
[RHEVM shell (connected)]# list vms --query "name=vm*"
This query would result in all virtual machines with names beginning with
vm, such as vm1, vm2, vma or vm-webserver.
Example 15.2. Wildcard search query for name=v*1
[RHEVM shell (connected)]# list vms --query "name=v*1"
This query would result in all virtual machines with names beginning with
v and ending with 1, such as vm1, vr1 or virtualmachine1.
Part III. The REST Application Programming Interface
Table of Contents
- 16. Introduction
- 17. Authentication and Security
- 18. REST API Quick Start Example
- 18.1. Example: Access API Entry Point
- 18.2. Example: List Data Center Collection
- 18.3. Example: List Host Cluster Collection
- 18.4. Example: List Logical Networks Collection
- 18.5. Example: List Host Collection
- 18.6. Example: List CPU Profiles
- 18.7. Example: Approve Host
- 18.8. Example: Create NFS Data Storage
- 18.9. Example: Create NFS ISO Storage
- 18.10. Example: Attach Storage Domains to Data Center
- 18.11. Example: Activate Storage Domains
- 18.12. Example: Create Virtual Machine
- 18.13. Example: Create Virtual Machine NIC
- 18.14. Example: Create Virtual Machine Storage Disk
- 18.15. Example: Attach ISO Image to Virtual Machine
- 18.16. Example: Start Virtual Machine
- 18.17. Example: Check System Events
- 19. Entry Point
- 20. Compatibility Level Versions
- 21. Capabilities
- 22. Common Features
- 23. The Backup and Restore API
- 24. Data Centers
- 25. Clusters
- 26. Networks
- 27. Storage Domains
- 28. Storage Connections
- 29. Hosts
- 30. Virtual Machines
- 31. Floating Disks
- 32. Templates
- 33. Virtual Machine Pools
- 34. Domains
- 35. Groups
- 36. Roles
- 37. Users
- 38. Tags
- 39. Events
Chapter 16. Introduction
Red Hat Enterprise Virtualization Manager provides a Representational State Transfer (REST) API. The API provides software developers and system administrators with control over their Red Hat Enterprise Virtualization environment outside of the standard web interface. The REST API is useful for developers and administrators who aim to integrate the functionality of a Red Hat Enterprise Virtualization environment with custom scripts or external applications that access the API via the standard Hypertext Transfer Protocol (HTTP).
The benefits of the REST API are:
- Broad client support - Any programming language, framework, or system with support for HTTP protocol can use the API;
- Self descriptive - Client applications require minimal knowledge of the virtualization infrastructure as many details are discovered at runtime;
- Resource-based model - The resource-based REST model provides a natural way to manage a virtualization platform.
This provides developers and administrators with the ability to:
- Integrate with enterprise IT systems.
- Integrate with third-party virtualization software.
- Perform automated maintenance or error checking tasks.
- Automate repetitive tasks in a Red Hat Enterprise Virtualization environment with scripts.
This documentation acts as a reference to the Red Hat Enterprise Virtualization Manager REST API. It aims to provide developers and administrators with instructions and examples to help harness the functionality of their Red Hat Enterprise Virtualization environment through the REST API either directly or using the provided Python libraries.
16.1. Representational State Transfer
Representational State Transfer (REST) is a design architecture that focuses on resources for a specific service and their representations. A resource representation is a key abstraction of information that corresponds to one specific managed element on a server. A client sends a request to a server element located at a Uniform Resource Identifier (URI) and performs operations with standard HTTP methods, such as
GET, POST, PUT, and DELETE. This provides a stateless communication between the client and server where each request acts independent of any other request and contains all necessary information to complete the request.
16.2. Red Hat Enterprise Virtualization REST API Prerequisites
Red Hat Enterprise Virtualization REST API Prerequisites
- A networked installation of Red Hat Enterprise Virtualization Manager, which includes the REST API.
- A client or programming library that initiates and receives HTTP requests from the REST API. For example:
- Python software development kit (SDK)
- Java software development kit (SDK)
- cURL command line tool
- RESTClient, a debugger for RESTful web services
- Knowledge of Hypertext Transfer Protocol (HTTP), which is the protocol used for REST API interactions. The Internet Engineering Task Force provides a Request for Comments (RFC) explaining the Hypertext Transfer Protocol at http://www.ietf.org/rfc/rfc2616.txt.
- Knowledge of Extensible Markup Language (XML) or JavaScript Object Notation (JSON), which the API uses to construct resource representations. The W3C provides a full specification on XML at http://www.w3.org/TR/xml/. ECMA International provide a free publication on JSON at http://www.ecma-international.org.
Chapter 17. Authentication and Security
17.1. TLS/SSL Certification
The Red Hat Enterprise Virtualization Manager API requires Hypertext Transfer Protocol Secure (HTTPS)
[2] for secure interaction with client software, such as the Manager's SDK and CLI components. This involves a process of obtaining a certificate from the Red Hat Enterprise Virtualization Manager and importing it into the certificate store of your client.
Important
Obtain your certificate from the Red Hat Enterprise Virtualization Manager using a secure network connection.
Procedure 17.1. Obtaining a Certificate
You can obtain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to the client machine using one of three methods:
- Method 1 - Use a command line tool to download the certificate from the Manager. Examples of command line tools include cURL and Wget, both of which are available on multiple platforms.
- If using cURL:
$ curl -o rhevm.cer http://[rhevm-server]/ca.crt
- If using Wget:
$ wget -O rhevm.cer http://[rhevm-server]/ca.crt
- Method 2 - Use a web browser to navigate to the certificate located at:
http://[rhevm-server]/ca.crt
Depending on the chosen browser, the certificate either downloads or imports into the browser's keystore.- If the browser downloads the certificate: save the file as
rhevm.cer.If the browser imports the certificate: export it from the browser's certification options and save it asrhevm.cer.
- Method 3 - Log in to the Manager, export the certificate from the truststore and copy it to your client machine.
- Log in to the Manager as the
rootuser. - Export the certificate from the truststore using the Java keytool management utility:
$ keytool -exportcert -keystore /etc/pki/ovirt-engine/.truststore -alias cacert -storepass mypass -file rhevm.cer
This creates a certificate file calledrhevm.cer. - Copy the certificate to the client machine using the
scpcommand:$ scp rhevm.cer [username]@[client-machine]:[directory]
Each of these methods results in a certificate file named
rhevm.cer on your client machine. An API user imports this file into the certificate store of the client.
Procedure 17.2. Importing a Certificate to a Client
- Importing a certificate to a client relies on how the client itself stores and interprets certificates. This guide contains some examples on importing certificates. For clients not using Network Security Services (NSS) or Java KeyStore (JKS), see your client documentation for more information on importing a certificate.
17.2. HTTP Authentication
Any user with a Red Hat Enterprise Virtualization account has access to the REST API. An API user submits a mandatory Red Hat Enterprise Virtualization Manager user name and password with all requests to the API. Each request uses HTTP Basic Authentication
[3] to encode these credentials. If a request does not include an appropriate
Authorization header, the API sends a 401 Authorization Required as a result:
Example 17.1. Access to the REST API without appropriate credentials
HEAD [base] HTTP/1.1 Host: [host] HTTP/1.1 401 Authorization Required
Request are issued with an
Authorization header for the specified realm. An API user encodes an appropriate Red Hat Enterprise Virtualization Manager domain and user in the supplied credentials with the username@domain:password convention.
The following table shows the process for encoding credentials in base64.
Table 17.1. Encoding credentials for API access
| Item | Value |
|---|---|
| username | rhevmadmin |
| domain | domain.example.com |
| password | 123456 |
| unencoded credentials | rhevmadmin@domain.example.com:123456 |
| base64 encoded credentials | cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 |
An API user provides the base64 encoded credentials as shown:
Example 17.2. Access to the REST API with appropriate credentials
HEAD [base] HTTP/1.1 Host: [host] Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 HTTP/1.1 200 OK ...
Important
Basic authentication involves potentially sensitive information, such as passwords, sent as plain text. REST API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-level encryption of plain-text requests.
Important
Some base64 libraries break the result into multiple lines and terminate each line with a newline character. This breaks the header and causes a faulty request. The Authorization header requires the encoded credentials on a single line within the header.
17.3. Authentication Sessions
The API also provides the ability for authentication session support. An API user sends an initial request with authentication details, then sends all subsequent requests using a session cookie to authenticate. The following procedure demonstrates how to use an authenticated session.
Procedure 17.3. Requesting an authenticated session
- Send a request with the
AuthorizationandPrefer: persistent-authHEAD [base] HTTP/1.1 Host: [host] Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 Prefer: persistent-auth HTTP/1.1 200 OK ...
This returns a response with the following header:Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/api; Secure
Note theJSESSIONID=value. In this example the value isJSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK. - Send all subsequent requests with the
Prefer: persistent-authandcookieheader with theJSESSIONID=value. TheAuthorizationis no longer needed when using an authenticated session.HEAD [base] HTTP/1.1 Host: [host] Prefer: persistent-auth cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK HTTP/1.1 200 OK ...
- When the session is no longer required, perform a request to the sever without the
Prefer: persistent-authheader.HEAD [base] HTTP/1.1 Host: [host] Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2 HTTP/1.1 200 OK ...
[2]
HTTPS is described in RFC 2818 HTTP Over TLS.
[3]
Basic Authentication is described in RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.
Chapter 18. REST API Quick Start Example
- 18.1. Example: Access API Entry Point
- 18.2. Example: List Data Center Collection
- 18.3. Example: List Host Cluster Collection
- 18.4. Example: List Logical Networks Collection
- 18.5. Example: List Host Collection
- 18.6. Example: List CPU Profiles
- 18.7. Example: Approve Host
- 18.8. Example: Create NFS Data Storage
- 18.9. Example: Create NFS ISO Storage
- 18.10. Example: Attach Storage Domains to Data Center
- 18.11. Example: Activate Storage Domains
- 18.12. Example: Create Virtual Machine
- 18.13. Example: Create Virtual Machine NIC
- 18.14. Example: Create Virtual Machine Storage Disk
- 18.15. Example: Attach ISO Image to Virtual Machine
- 18.16. Example: Start Virtual Machine
- 18.17. Example: Check System Events
This chapter provides an example to demonstrate the REST API's ability to setup a basic Red Hat Enterprise Virtualization environment and create a virtual machine.
In addition to the standard prerequisites, this example requires the following:
- A networked and configured host containing Red Hat Enterprise Virtualization Hypervisor;
- An ISO file containing a desired virtual machine operating system to install. This chapter uses Red Hat Enterprise Linux Server 6 for our installation ISO example; and
- Red Hat Enterprise Virtualization's engine-iso-uploader tool to upload your chosen operating system ISO file.
This example uses cURL to demonstrate REST requests with a client application. Note that any application capable of HTTP requests can substitute for cURL.
Important
For simplicity, the HTTP request headers in this example omit the
Host: and Authorization: fields. However, these fields are mandatory and require data specific to your installation of Red Hat Enterprise Virtualization Manager.
Important
All cURL examples include placeholders for authentication details (
USER:PASS) and certificate location (CERT). Ensure all requests performed with cURL fulfill certification and authentication requirements.
Note
Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for the
id attribute for each resource. Identifier codes in this example might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.
18.1. Example: Access API Entry Point
The following request retrieves a representation of the main entry point of the API.
Example 18.1. Access the API entry point
Request:
GET /api HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
--cacert [CERT] https://[RHEVM Host]:443/api
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<api>
<link rel="capabilities" href="/api/capabilities"/>
<link rel="clusters" href="/api/clusters"/>
<link rel="clusters/search" href="/api/clusters?search={query}"/>
<link rel="datacenters" href="/api/datacenters"/>
<link rel="datacenters/search" href="/api/datacenters?search={query}"/>
<link rel="events" href="/api/events"/>
<link rel="events/search" href="/api/events?search={query}"/>
<link rel="hosts" href="/api/hosts"/>
<link rel="hosts/search" href="/api/hosts?search={query}"/>
<link rel="networks" href="/api/networks"/>
<link rel="roles" href="/api/roles"/>
<link rel="storagedomains" href="/api/storagedomains"/>
<link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
<link rel="tags" href="/api/tags"/>
<link rel="templates" href="/api/templates"/>
<link rel="templates/search" href="/api/templates?search={query}"/>
<link rel="users" href="/api/users"/>
<link rel="groups" href="/api/groups"/>
<link rel="domains" href="/api/domains"/>
<link rel="vmpools" href="/api/vmpools"/>
<link rel="vmpools/search" href="/api/vmpools?search={query}"/>
<link rel="vms" href="/api/vms"/>
<link rel="vms/search" href="/api/vms?search={query}"/>
<special_objects>
<link rel="templates/blank"
href="/api/templates/00000000-0000-0000-0000-000000000000"/>
<link rel="tags/root"
href="/api/tags/00000000-0000-0000-0000-000000000000"/>
</special_objects>
<product_info>
<name>Red Hat Enterprise Virtualization</name>
<vendor>Red Hat</vendor>
<version revision="0" build="0" minor="0" major="3"/>
</product_info>
<summary>
<vms>
<total>5</total>
<active>0</active>
</vms>
<hosts>
<total>1</total>
<active>1</active>
</hosts>
<users>
<total>1</total>
<active>1</active>
</users>
<storage_domains>
<total>2</total>
<active>2</active>
</storage_domains>
</summary>
</api>
The entry point provides a user with links to the collections in a virtualization environment. The
rel= attribute of each collection link provides a reference point for each link. The next step in this example examines the datacenter collection, which is available through the rel="datacenter" link.
The entry point also contains other data such as
product_info, special_objects and summary. This data is covered in chapters outside this example.
18.2. Example: List Data Center Collection
Red Hat Enterprise Virtualization Manager creates a
Default data center on installation. This example uses the Default data center as the basis for our virtual environment.
The following request retrieves a representation of the data center collection:
Example 18.2. List data center collection
Request:
GET /api/datacenters HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
--cacert [CERT] \
https://[RHEVM Host]:443/api/datacenters
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<data_centers>
<data_center href="/api/datacenters/00000002-0002-0002-0002-0000000003ab" id="00000002-0002-0002-0002-0000000003ab">
<name>Default</name>
<description>The default Data Center</description>
<link rel="storagedomains"/>
href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/storagedomains"
<link rel="clusters"/>
href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/clusters"
<link rel="networks"/>
href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/networks"
<link rel="permissions"/>
href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/permissions"
<link rel="quotas"/>
href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/quotas"
<link rel="iscsibonds"/>
href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/iscsibonds"
<link rel="qoss"/>
href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/qoss"
<local>false</local>
<storage_format>v3</storage_format>
<version major="3" minor="5"/>
<supported_versions>
<version major="3" minor="5"/>
</supported_versions>
<status>
<state>up</state>
</status>
</data_center>
</data_centers>
Note the
id code of your Default data center. This code identifies this data center in relation to other resources of your virtual environment.
The data center also contains a link to the
storagedomains sub-collection. The data center uses this sub-collection to attach storage domains from the storagedomains main collection, which this example covers later.
18.3. Example: List Host Cluster Collection
Red Hat Enterprise Virtualization Manager creates a
Default host cluster on installation. This example uses the Default cluster to group resources in your Red Hat Enterprise Virtualization environment.
The following request retrieves a representation of the cluster collection:
Example 18.3. List host clusters collection
Request:
GET /api/clusters HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
--cacert [CERT] \
https://[RHEVM Host]:443/api/clusters
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<clusters>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
<name>Default</name>
<description>The default server cluster</description>
<link rel="networks"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
<link rel="permissions"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
<cpu id="Intel Penryn Family"/>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
<memory_policy>
<overcommit percent="100"/>
<transparent_hugepages>
<enabled>false</enabled>
</transparent_hugepages>
</memory_policy>
<scheduling_policy/>
<version minor="0" major="3"/>
<error_handling>
<on_error>migrate</on_error>
</error_handling>
</cluster>
</clusters>
Note the
id code of your Default host cluster. This code identifies this host cluster in relation to other resources of your virtual environment.
The
Default cluster is associated with the Default data center through a relationship using the id and href attributes of the data_center element.
The
networks sub-collection contains a list of associated network resources for this cluster. The next section examines the networks collection in more detail.
18.4. Example: List Logical Networks Collection
Red Hat Enterprise Virtualization Manager creates a default
rhevm network on installation. This network acts as the management network for Red Hat Enterprise Virtualization Manager to access hypervisor hosts.
This network is associated with our
Default cluster and is a member of the Default data center. This example uses the rhevm network to connect our virtual machines.
The following request retrieves a representation of the logical networks collection:
Example 18.4. List logical networks collection
Request:
GET /api/networks HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
--cacert [CERT] \
https://[RHEVM Host]:443/api/networks
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<networks>
<network id="00000000-0000-0000-0000-000000000009"
href="/api/networks/00000000-0000-0000-0000-000000000009">
<name>rhevm</name>
<description>Management Network</description>
<data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
<stp>false</stp>
<status>
<state>operational</state>
</status>
<display>false</display>
</network>
</networks>
The
rhevm network is attached to the Default data center through a relationship using the data center's id code.
The
rhevm network is also attached to the Default cluster through a relationship in the cluster's network sub-collection.
18.5. Example: List Host Collection
This example uses a Red Hat Enterprise Virtualization Hypervisor host. Red Hat Enterprise Virtualization Manager automatically registers any configured Red Hat Enterprise Virtualization Hypervisor. This example retrieves a representation of the hosts collection and shows a Red Hat Enterprise Virtualization Hypervisor host named
hypervisor registered with the virtualization environment.
Example 18.5. List hosts collection
Request:
GET /api/hosts HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
--cacert [CERT] \
https://[RHEVM Host]:443/api/hosts
Result:
HTTP/1.1 200 OK
Accept: application/xml
<hosts>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
<name>hypervisor</name>
<actions>
<link rel="install"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/install"/>
<link rel="activate"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/activate"/>
<link rel="fence"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/fence"/>
<link rel="deactivate"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/deactivate"/>
<link rel="approve"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve"/>
<link rel="iscsilogin"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsilogin"/>
<link rel="iscsidiscover"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsidiscover"/>
<link rel="commitnetconfig"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/
commitnetconfig"/>
</actions>
<link rel="storage"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/storage"/>
<link rel="nics"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/nics"/>
<link rel="tags"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/tags"/>
<link rel="permissions"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/permissions"/>
<link rel="statistics"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/statistics"/>
<address>10.64.14.110</address>
<status>
<state>non_operational</state>
</status>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<port>54321</port>
<storage_manager>true</storage_manager>
<power_management>
<enabled>false</enabled>
<options/>
</power_management>
<ksm>
<enabled>false</enabled>
</ksm>
<transparent_hugepages>
<enabled>true</enabled>
</transparent_hugepages>
<iscsi>
<initiator>iqn.1994-05.com.example:644949fe81ce</initiator>
</iscsi>
<cpu>
<topology cores="2"/>
<name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
<speed>2993</speed>
</cpu>
<summary>
<active>0</active>
<migrating>0</migrating>
<total>0</total>
</summary>
</host>
</hosts>
Note the
id code of your Default host. This code identifies this host in relation to other resources of your virtual environment.
This host is a member of the
Default cluster and accessing the nics sub-collection shows this host has a connection to the rhevm network.
18.6. Example: List CPU Profiles
The following request retrieves a representation of the CPU profiles:
Example 18.6. List CPU profiles
Request:
GET /api/cpuprofiles HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM Host]:443/api/cpuprofiles
Result:
HTTP/1.1 200 OK
Content-Type: application/xml
<cpu_profiles>
<cpu_profile href="0000001a-001a-001a-001a-00000000035e" id="0000001a-001a-001a-001a-00000000035e">
<name>Default</name>
<link href="/api/cpuprofiles/0000001a-001a-001a-001a-00000000035e/permissions" rel="permissions"/>
<cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
</cpu_profile>
<cpu_profile href="fc4b9188-f87f-44f9-b9c5-c7665e10e0a2" id="fc4b9188-f87f-44f9-b9c5-c7665e10e0a2">
<name>Premium</name>
<description>Full service available</description>
<link href="/api/cpuprofiles/fc4b9188-f87f-44f9-b9c5-c7665e10e0a2/permissions" rel="permissions"/>
<qos href= "/api/datacenters/00000002-0002-0002-0002-0000000000f7/qoss/5afe49e3-aac4-4b7b-bb83-11b9aef285e1" id="5afe49e3-aac4-4b7b-bb83-11b9aef285e1"/>
<cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
</cpu_profile>
<cpu_profile href="48c600f4-6768-49ca-9c16-a877d0e586e5" id="48c600f4-6768-49ca-9c16-a877d0e586e5">
<name>Budget</name>
<description>Limited CPU</description>
<link href="/api/cpuprofiles/48c600f4-6768-49ca-9c16-a877d0e586e5/permissions" rel="permissions"/>
<cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
</cpu_profile>
<cpu_profile href="48c600f4-6768-49ca-9c16-a877d0e586e5" id="48c600f4-6768-49ca-9c16-a877d0e586e5">
<name>Backup</name>
<link href="/api/cpuprofiles/d510b042-42f0-4cb2-9d2e-25fcc28d6c5f/permissions" rel="permissions"/>
<cluster href= "/api/clusters/668cab0c-9185-4eaa-9942-658284eeecdd" id="668cab0c-9185-4eaa-9942-658284eeecdd"/>
</cpu_profile>
</cpu_profiles>
18.7. Example: Approve Host
The
hypervisor host resource contains an approve action. A user accesses this action's URI with a POST request.
Example 18.7. Approve a pre-configured Red Hat Enterprise Virtualization Hypervisor host
Request:
POST /api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action/>" \
https://[RHEVM Host]:443/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve
The POST request requires a body for the message entities to initiate an action. Since the action does not require additional parameters, the body contains an empty
action element.
Use the
approve action only for Red Hat Enterprise Virtualization Hypervisor hosts. Red Hat Enterprise Linux hosts require a different process to connect to the virtualization environment.
This approves and activates the host for use in your virtual environment. The
status for hypervisor changes from non_operational to up.
18.8. Example: Create NFS Data Storage
An NFS data storage domain is an exported NFS share attached to a data center and provides storage for virtualized guest images. Creation of a new storage domain requires a
POST request, with the storage domain representation included, sent to the URL of the storage domain collection.
In Red Hat Enterprise Virtualization 3.6 and later you can enable the wipe after delete option by default on the storage domain. To configure this specify
<wipe_after_delete> in the POST request. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist.
Example 18.8. Create an NFS data storage domain
Request:
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>data1</name>
<type>data</type>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/data1</path>
</storage>
<host>
<name>hypervisor</name>
</host>
</storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>data1</name><type>data</type> \
<storage><type>nfs</type><address>192.168.0.10</address> \
<path>/data1</path></storage> \
<host><name>hypervisor</name></host></storage_domain>" \
https://[RHEVM Host]:443/api/storagedomains
The API creates a NFS data storage domain called
data1 with an export path of 192.168.0.10:/data1 and sets access to the storage domain through the hypervisor host. The API also returns the following representation of the newly created storage domain resource.
Result:
HTTP/1.1 200 OK
Accept: application/xml
<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"
href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac">
<name>data1</name>
<link rel="permissions"
href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/
permissions"/>
<link rel="files"
href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/files"/>
<type>data</type>
<master>false</master>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/data1</path>
</storage>
<available>175019917312</available>
<used>27917287424</used>
<committed>10737418240</committed>
<storage_format>v1</storage_format>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
</storage_domain>
18.9. Example: Create NFS ISO Storage
An NFS ISO storage domain is a mounted NFS share attached to a data center and provides storage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Creation of a new storage domain requires a
POST request, with the storage domain representation included, sent to the URL of the storage domain collection.
In Red Hat Enterprise Virtualization 3.6 and later you can enable the wipe after delete option by default on the storage domain. To configure this specify
<wipe_after_delete> in the POST request. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist.
Example 18.9. Create an NFS ISO storage domain
Request:
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>iso1</name>
<type>iso</type>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/iso1</path>
</storage>
<host>
<name>hypervisor</name>
</host>
</storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>iso1</name><type>iso</type> \
<storage><type>nfs</type><address>192.168.0.10</address> \
<path>/iso1</path></storage> \
<host><name>hypervisor</name></host></storage_domain>" \
https://[RHEVM Host]:443/api/storagedomains
The API creates a NFS iso storage domain called
iso1 with an export path of 192.168.0.10:/iso1 and gets access to the storage domain through the hypervisor host. The API also returns the following representation of the newly created storage domain resource.
Result:
HTTP/1.1 200 OK
Accept: application/xml
<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da">
<name>iso1</name>
<link rel="permissions"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
permissions"/>
<link rel="files"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files"/>
<type>iso</type>
<host id="" href="">
<master>false</master>
<storage>
<type>nfs</type>
<address>192.168.0.10</address>
<path>/iso1</path>
</storage>
<available>82678120448</available>
<used>18253611008</used>
<committed>0</committed>
<storage_format>v1</storage_format>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
</storage_domain>
18.10. Example: Attach Storage Domains to Data Center
The following example attaches the
data1 and iso1 storage domains to the Default data center.
Example 18.10. Attach data1 storage domain to the Default data center
Request:
POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml <storage_domain> <name>data1</name> </storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>data1</name></storage_domain>" \
https://[RHEVM Host]:443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains
Example 18.11. Attach iso1 storage domain to the Default data center
Request:
POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1 Accept: application/xml Content-type: application/xml <storage_domain> <name>iso1</name> </storage_domain>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<storage_domain><name>iso1</name></storage_domain>" \
https://[RHEVM Host]:443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains
These
POST requests place our two new storage_domain resources in the storagedomains sub-collection of the Default data center. This means the storagedomains sub-collection contains attached storage domains of the data center.
18.11. Example: Activate Storage Domains
This example activates the
data1 and iso1 storage domains for the Red Hat Enterprise Virtualization Manager's use.
Example 18.12. Activate data1 storage domain
Request:
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/ 9ca7cb40-9a2a-4513-acef-dc254af57aac/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action/>" \
https://[RHEVM Host]:443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/activate
Example 18.13. Activate iso1 storage domain
Request:
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/ 00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action/>"
https://[RHEVM Host]:443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate
This activates both storage domains for use with the data center.
18.12. Example: Create Virtual Machine
The following example creates a virtual machine called
vm1 on the Default cluster using the virtualization environment's Blank template as a basis. The request also defines the virtual machine's memory as 512 MB and sets the boot device to a virtual hard disk.
Example 18.14. Create a virtual machine
Request:
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>vm1</name>
<cluster>
<name>default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot dev="hd"/>
</os>
<cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os><cpu_profile id='0000001a-001a-001a-001a-00000000035e'/></vm>" https://[RHEVM Host]:443/api/vms
Result:
HTTP/1.1 200 OK
Accept: application/xml
<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48">
<name>vm1</name>
<actions>
<link rel="shutdown"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/>
<link rel="start"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/>
<link rel="stop"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/>
<link rel="reboot"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/reboot"/>
<link rel="suspend"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/suspend"/>
<link rel="detach"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/detach"/>
<link rel="export"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/export"/>
<link rel="move"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/move"/>
<link rel="ticket"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/ticket"/>
<link rel="migrate"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/migrate"/>
<link rel="undo_snapshot"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/undo_snapshot"/>
<link rel="commit_snapshot"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/commit_snapshot"/>
<link rel="preview_snapshot"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/preview_snapshot"/>
<link rel="logon"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/logon"/>
<link rel="cancelmigration"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cancelmigration"/>
<link rel="maintenance"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/maintenance"/>
<link rel="clone"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/clone"/>
</actions>
<link rel="applications"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/applications"/>
<link rel="disks"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks"/>
<link rel="nics"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics"/>
<link rel="cdroms"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms"/>
<link rel="snapshots"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/snapshots"/>
<link rel="tags"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/tags"/>
<link rel="permissions"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/permissions"/>
<link rel="statistics"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/statistics"/>
<link rel="reporteddevices"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/reporteddevices"/>
<link rel="watchdogs"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/watchdogs"/>
<link rel="sessions"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/sessions"/>
<type>desktop</type>
<status>
<state>down</state>
</status>
<memory>536870912</memory>
<cpu>
<topology cores="1" sockets="1"/>
</cpu>
<os type="Unassigned">
<boot dev="cdrom"/>
</os>
<high_availability>
<enabled>false</enabled>
<priority>0</priority>
</high_availability>
<display>
<type>spice</type>
<monitors>1</monitors>
<single_qxl_pci>false</single_qxl_pci>
<allow_override>false</allow_override>
<smartcard_enabled>false</smartcard_enabled>
<file_transfer_enabled>true</file_transfer_enabled>
<copy_paste_enabled>true</copy_paste_enabled>
</display>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<template id="00000000-0000-0000-0000-000000000000"
href="/api/templates/00000000-0000-0000-0000-000000000000"/>
<stop_time>2011-06-15T04:48:02.167Z</stop_time>
<creation_time>2011-06-15T14:48:02.078+10:00</creation_time>
<origin>rhev</origin>
<stateless>false</stateless>
<delete_protected>false</delete_protected>
<sso>
<methods>
<method id="GUEST_AGENT"/>
</methods>
</sso>
<console enabled="false"/>
<timezone>Etc/GMT</timezone>
<initialization>
<configuration>
<type>ovf</type>
<data>...</data>
</configuration>
</initialization>
<placement_policy>
<affinity>migratable</affinity>
</placement_policy>
<memory_policy>
<guaranteed>536870912</guaranteed>
<ballooning>true</ballooning>
</memory_policy>
<usb>
<enabled>false</enabled>
</usb>
<soundcard_enabled>true</soundcard_enabled>
<migration_downtime>-1</migration_downtime>
<virtio_scsi enabled="true"/>
<cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
<next_run_configuration_exists>false</next_run_configuration_exists>
<numa_tune_mode>interleave</numa_tune_mode>
</vm>
18.13. Example: Create Virtual Machine NIC
The following example creates a virtual network interface to connect the example virtual machine to the
rhevm network.
Example 18.15. Create a virtual machine NIC
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml
<nic>
<interface>virtio</interface>
<name>nic1</name>
<network>
<name>rhevm</name>
</network>
</nic>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<nic><name>nic1</name><network><name>rhevm</name></network></nic>" \
https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics
18.14. Example: Create Virtual Machine Storage Disk
The following example creates an 8 GB Copy-On-Write storage disk for the example virtual machine.
Example 18.16. Create a virtual machine storage disk
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<storage_domains>
<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"/>
</storage_domains>
<size>8589934592</size>
<type>system</type>
<interface>virtio</interface>
<format>cow</format>
<bootable>true</bootable>
</disk>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<disk><storage_domains> \
<storage_domain id='9ca7cb40-9a2a-4513-acef-dc254af57aac'/> \
</storage_domains><size>8589934592</size><type>system</type> \
<interface>virtio</interface><format>cow</format> \
<bootable>true</bootable></disk>" \
https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks
The
storage_domain element tells the API to store the disk on the data1 storage domain.
18.15. Example: Attach ISO Image to Virtual Machine
The boot media for our example virtual machine requires an CD-ROM or DVD ISO image for an operating system installation. This example uses a Red Hat Enterprise Server 6 ISO image for installation.
ISO images must be available in the
iso1 ISO domain for the virtual machines to use. Red Hat Enterprise Virtualization Platform provides an uploader tool that ensures that the ISO images are uploaded into the correct directory path with the correct user permissions.
Once the ISO is uploaded, an API user requests the ISO storage domain's
files sub-collection to view the file resource:
Example 18.17. View the files sub-collection in an ISO storage domain
Request:
GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] \
https://[RHEVM Host]:443/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files
The API returns the following representation of the files sub-collection:
<files>
<file id="rhel-server-6.0-x86_64-dvd.iso"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
files/rhel-server-6.0-x86_64-dvd.iso.iso">
<name>rhel-server-6.0-x86_64-dvd.iso.iso</name>
<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
</file>
</files>
An API user attaches the
rhel-server-6.0-x86_64-dvd.iso to our example virtual machine. Attaching an ISO image is equivalent to using the Change CD button in the Administration or User Portal.
Example 18.18. Attach an ISO image to the virtual machine
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms HTTP/1.1 Accept: application/xml Content-type: application/xml <cdrom> <file id="rhel-server-6.0-x86_64-dvd.iso"/> </cdrom>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>" \
https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms
18.16. Example: Start Virtual Machine
The virtual environment is complete and the virtual machine contains all necessary components to function. This example starts the virtual machine using the
start action.
Example 18.19. Start the virtual machine
Request:
POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<vm>
<os>
<boot dev="cdrom"/>
</os>
</vm>
</action>
cURL command:
# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
-u [USER:PASS] --cacert [CERT] \
-d "<action><vm><os><boot dev='cdrom'/></os></vm></action>" \
https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start
The additional message entity sets the virtual machine's boot device to CD-ROM for this boot only. This enables the virtual machine to install Red Hat Enterprise Server 6 from the attached ISO image. The boot device reverts back to
disk for all future boots.
18.17. Example: Check System Events
The
start action for the vm1 creates several entries in the events collection. This example lists the events collection and identifies events specific to the API starting a virtual machine.
Example 18.20. List the events collection
Request:
GET /api/events HTTP/1.1 Accept: application/xml
cURL command:
# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
--cacert [CERT] \
https://[RHEVM Host]:443/api/events
Result:
<events>
...
<event id="103" href="/api/events/103">
<description>User admin logged out.</description>
<code>31</code>
<severity>normal</severity>
<time>2011-06-29T17:42:41.544+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
<event id="102" href="/api/events/102">
<description>vm1 was started by admin (Host: hypervisor).</description>
<code>153</code>
<severity>normal</severity>
<time>2011-06-29T17:42:41.499+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48"/>
<host id="0656f432-923a-11e0-ad20-5254004ac988"
href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988"/>
</event>
<event id="101" href="/api/events/101">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-06-29T17:42:40.505+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
...
</events>
The following events occur:
id="101"- The API authenticates with theadminuser's user name and password.id="102"- The API, acting as theadminuser, startsvm1on thehypervisorhost.id="103"- The API logs out of theadminuser account.
Chapter 19. Entry Point
A user begins interacting with the API through a
GET request on the entry point URI consisting of a host and base.
Example 19.1. Accessing the API Entry Point
If the host is
www.example.com and the base is /api, the entry point appears with the following request:
GET /api HTTP/1.1
Accept: application/xml
Host: www.example.com
Authorization: [base64 encoded credentials]
HTTP/1.1 200 OK
Content-Type: application/xml
<api>
<link rel="hosts" href="/api/hosts"/>
<link rel="vms" href="/api/vms"/>
...
<product_info>
<name>Red Hat Enterprise Virtualization</name>
<vendor>Red Hat</vendor>
<version revision="0" build="0" minor="1" major="3"/>
</product_info>
<special_objects>
<link rel="templates/blank" href="..."/>
<link rel="tags/root" href="..."/>
</special_objects>
<summary>
<vms>
<total>10</total>
<active>3</active>
</vms>
<hosts>
<total>2</total>
<active>2</active>
</hosts>
<users>
<total>8</total>
<active>2</active>
</users>
<storage_domains>
<total>2</total>
<active>2</active>
</storage_domains>
</summary>
</api>
Note
For simplicity, all other examples omit the
Host: and Authorization: request headers and assume the base is the default /api path. This base path differs depending on your implementation.
19.1. Product Information
The entry point contains a
product_info element to help an API user determine the legitimacy of the Red Hat Enterprise Virtualization environment. This includes the name of the product, the vendor and the version.
Example 19.2. Verify a genuine Red Hat Enterprise Virtualization environment
The follow elements identify a genuine Red Hat Enterprise Virtualization 3.2 environment:
<api>
...
<product_info>
<name>Red Hat Enterprise Virtualization</name>
<vendor>Red Hat</vendor>
<version revision="0" build="0" minor="2" major="3"/>
</product_info>
...
</api>
19.2. Link Elements
Access to the Entry Point provides
link elements and URIs for all of the resource collections the API exposes. Each collection uses a relation type to identify the URI a client needs.
Table 19.1. Available Relationship Types
| Relationship | Description |
|---|---|
capabilities | Supported capabilities of the Red Hat Enterprise Virtualization Manager. |
datacenters | Data centers. |
clusters | Host clusters. |
networks | Virtual networks. |
storagedomains | Storage domains. |
hosts | Hosts. |
vms | Virtual machines. |
disks | Virtual machine disks. |
templates | Templates. |
vmpools | Virtual machine pools. |
domains | Identity service domains. |
groups | Imported identity service groups. |
roles | Roles. |
users | Users. |
tags | Tags. |
events | Events. |
Figure 19.1. The relationship between the API entry point and the resource collections exposed by the API
Note
All URIs shown in example responses are illustrative. The format of all URIs returned by the server is opaque. Clients navigate to specific resources through the entry point URI and use the relationship types to access the URIs.
The
link elements also contain a set of search URIs for certain collections. These URIs use URI templates
[5] to integrate search queries. The purpose of the URI template is to accept a search expression using the natural HTTP pattern of a query parameter. The client does not require prior knowledge of the URI structure. Thus clients should treat these templates as being opaque and access them with a URI template library.
Each search query URI template is identified with a relation type using the convention
"collection/search".
Table 19.2. Relationships associated with search query URIs
| Relationship | Description |
|---|---|
datacenters/search | Query data centers. |
clusters/search | Query host clusters. |
storagedomains/search | Query storage domains. |
hosts/search | Query hosts. |
vms/search | Query virtual machines. |
disks/search | Query disks. |
templates/search | Query templates. |
vmpools/search | Query virtual machine pools. |
events/search | Query events. |
users/search | Query users. |
19.3. Special Object Elements
Special object elements define relationships to special fixed resources within the virtualization environment.
Table 19.3. Special Objects
| Relationship | Description |
|---|---|
templates/blank | The default blank virtual machine template for your virtualization environment. This template exists in every cluster as opposed to a standard template, which only exists in a single cluster. |
tags/root | The root tag that acts as a base for tag hierarchy in your virtualization environment. |
19.4. Summary Element
The summary element shows a high level summary of the system's statistics.
Table 19.4. Summary Elements
| Element | Description |
|---|---|
vms | Total number of vms and total number of active vms. |
hosts | Total number of hosts and total number of active hosts. |
users | Total number of users and total number of active users. |
storage_domains | Total number of storage domains and total number of active storage domains. |
19.5. RESTful Service Description Language (RSDL)
RESTful Service Description Language (RSDL) provides a description of the structure and elements in the REST API in one whole XML specification. Invoke the RSDL using the following request.
GET /api?rsdl HTTP/1.1 Accept: application/xml
This produces an XML document in the following format:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
<description>...</description>
<version major="3" minor="1" build="0" revision="0"/>
<schema href="/api?schema" rel="schema">
<name>...</name>
<description>...</description>
</schema>
<links>
<link href="/api/capabilities" rel="get">
...
</link>
...
</links>
</rsdl>
Table 19.5. RSDL Structure Elements
| Element | Description |
|---|---|
description | A plain text description of the RSDL document. |
version | The API version, including major release, minor release, build and revision. |
schema | A link to the XML schema (XSD) file. |
links | Defines each link in the API. |
Each
link element contains the following a structure:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
...
<links>
<link href="/api/..." rel="...">
<request>
<http_method>...</http_method>
<headers>
<header>
<name>...</name>
<value>...</value>
</header>
...
</headers>
<body>
<type>...</type>
<parameters_set>
<parameter required="..." type="...">
<name>...</name>
</parameter>
...
</parameters_set>
</body>
</request>
<response>
<type>...</type>
</response>
</link>
...
</links>
</rsdl>
Table 19.6. RSDL Link Structure Elements
| Element | Description |
|---|---|
link | A URI for API requests. Includes a URI attribute (href) and a relationship type attribute (rel). |
request | Defines the request properties required for the link. |
http_method | The method type to access this link. Includes the standard HTTP methods for REST API access: GET, POST, PUT and DELETE. |
headers | Defines the headers for the HTTP request. Contains a series of header elements, which each contain a header name and value to define the header. |
body | Defines the body for the HTTP request. Contains a resource type and a parameter_set, which contains a sets of parameter elements with attributes to define whether they are required for a request and the data type. The parameter element also includes a name element to define the Red Hat Enterprise Virtualization Manager property to modify and also a further parameter_set subset if type is set to collection. |
response | Defines the output for the HTTP request. Contains a type element to define the resource structure to output. |
Use the RSDL in your applications as a method to map all links and parameter requirements for controlling a Red Hat Enterprise Virtualization environment.
19.6. Red Hat Enterprise Virtualization Windows Guest VSS Support
The Red Hat Enterprise Virtualization Backup and Restore API provides integration with Microsoft Windows Volume Shadow Copy Service (VSS) using qemu-ga. The VSS provider registration is made in the guest level as part of the Guest Tools deployment.
qemu-ga provides VSS support and live snapshots attempt to quiesce whenever possible.
19.7. QEMU Guest Agent Overview
In Red Hat Enterprise Linux 6.4, the QEMU Guest Agent (QEMU GA) provided protection against the corruption of Linux guest virtual machines. Before issuing a snapshot request or creating a backup copy of the disk, the management stack (libvirt) sent a
guest-fsfreeze-freeze QMP command to the QEMU GA via the virtio-serial port. This command caused the guest agent to freeze all of the guest virtual machine's filesystems, via the FIFREEZE ioctl() kernel function. This ioctl() function is implemented by the Linux kernel in the guest virtual machine. The function flushes the filesystem cache in the guest virtual machine's kernel, brings the filesystem into a consistent state, and denies all userspace threads write access to the filesystem.
Only after the QEMU GA reported success, libvirt would proceed with the snapshot. At its completion, libvirt sends the
guest-fsfreeze-thaw QMP command to the QEMU GA over the virtio-serial port. This command tells the QEMU GA to issue a FITHAW ioctl(), which unblocks the userspace threads that were previously denied write access, and resumes normal processing. This process did not ensure that application-level data was in a consistent state when the virtual disk snapshot was taken. This was evident in cases where the fsck utility found no problems on filesystems restored from snapshots, and yet applications were not able to resume processing from the point where the snapshot was taken and userspace processes may not have written their internal buffers to files on the disk.
Red Hat Enterprise Linux 6.5 ensures that both file and application-level synchronization (flushing) are done. Guest system administrators can write and install application-specific freezing and thawing hook scripts. Before freezing the filesystems, the QEMU GA invokes the main hook script (included in the QEMU GA package). The main hook script in turn calls individual application-specific scripts, prepared by the guest system administrators, that temporarily deactivate all guest virtual machine applications. All of these actions occur when the mode is changed to "freeze".
Just before filesystems are frozen, the guest system administrator's scripts cause the databases and other file system applications to flush their working buffers to the virtual disk and to stop accepting further client connections. The applications then bring their data files into a consistent state where resumption of processing, with the reactivated (or a freshly started) instance of the application (after restoring the virtual disk from backup) is possible. When all scripts are done making their respective applications inactive, and the main hook script returns, QEMU GA proceeds to freeze filesystems, and the management stack takes the snapshot. Once all this is done, and it is confirmed that the snapshot is taken, the file system will resume to serve write requests. This process is called thawing.
Thawing is freezing in reverse order. Instructed by libvirt, QEMU GA thaws the guest virtual machine's filesystems. It then invokes individual hook scripts (via the main hook script) to resume or restart applications that had been inactivated during the freeze process.
19.8. VSS Transaction Flow
In processing a backup, the requester and the writers coordinate to do several things: to provide a stable system image from which to back up data (the shadow copied volume), to group files together on the basis of their usage, and to store information on the saved data. This must all be done with minimal interruption of the writer's normal work flow.
A requester (in our case the Backup Vendor) queries writers for their metadata, processes this data, notifies the writers prior to the beginning of the shadow copy and of the backup operations, and then notifies the writers again after the shadow copy and backup operations end.
Here is how the QEMU VSS provider is registered in Windows OS after the Guest Tools installation:
C:\Users\Administrator>vssadmin list providers
vssadmin 1.1 - Volume Shadow Copy Service administrative command-line tool
(C) Copyright 2001-2005 Microsoft Corp.
Provider name: 'QEMU Guest Agent VSS Provider'
Provider type: Software
Provider Id: {3629d4ed-ee09-4e0e-9a5c-6d8ba2872aef}
Version: 0.12.1
[4]
The RFC describing Uniform Resource Locator Generic Syntax provides a Collected ABNF for URI that explains the difference between these forms.
[5]
The Internet-Draft describing the format of a URI Template is available at http://tools.ietf.org/html/draft-gregorio-uritemplate-03.
Chapter 20. Compatibility Level Versions
Each host connected to Red Hat Enterprise Virtualization Manager contains a version of VDSM. VDSM is the agent within the virtualization infrastructure that runs on a hypervisor or host and provides local management for virtual machines, networks and storage. Red Hat Enterprise Virtualization Manager controls hypervisors and hosts using current or older versions of VDSM.
The Manager migrates virtual machines from host to host within a cluster. This means the Manager excludes certain features from a current version of VDSM until all hosts within a cluster have the same VDSM version, or more recent, installed.
The API represents this concept as a
compatibility level for each host, corresponding to the version of VDSM installed. A version element contains major and minor attributes, which describe the compatibility level.
When an administrator upgrades all hosts within a cluster to a certain level, the
version level appears under a supported_versions element. This indicates the cluster's version is now updatable to that level. Once the administrator updates all clusters within a data center to a given level, the data center is updatable to that level.
20.1. Upgrading Compatibility Levels
Example 20.1. Upgrading compatibility levels
The API reports the following compatibility levels for Red Hat Enterprise Virtualization Manager 3.4 instance:
<host ...>
...
<version major="4" minor="14" build="11" revision="0" full_version="vdsm-4.14.11-5.el6ev"/>
...
</host>
<cluster ...>
...
<version major="3" minor="4"/>
...
</cluster>
<data_center ...>
...
<version major="3" minor="4"/>
</supported_versions>
...
</data_center>
All hosts within a cluster are updated to VDSM
3.5 and the API reports:
<host ...>
...
<version major="4" minor="16" build="7" revision="4" full_version="vdsm-4.16.7.4-1.el6ev"/>
...
</host>
<cluster ...>
...
<version major="3" minor="4"/>
<supported_versions>
<version major="3" minor="5"/>
</supported_versions>
...
</cluster>
<data_center ...>
...
<version major="3" minor="4"/>
<supported_versions/>
...
</data_center>
The cluster is now updatable to
3.5. When the cluster is updated, the API reports:
<cluster ...>
...
<version major="3" minor="5"/>
<supported_versions/>
...
</cluster>
<data_center ...>
...
<version major="3" minor="4"/>
<supported_versions>
<version major="3" minor="5"/>
</supported_versions>
...
</data_center>
The API user updates the data center to
3.5. Once upgraded, the API exposes features available in Red Hat Enterprise Virtualization 3.5 for this data center.
Chapter 21. Capabilities
The
capabilities collection provides information about the capabilities that versions of Red Hat Enterprise Virtualization support. These capabilities include active features and available enumerated values for specific properties.
To retrieve a full list of the capabilities for all versions of Red Hat Enterprise Virtualization from 3.2 to the latest version, submit the following request:
GET /api/capabilities/ HTTP/1.1 Content-Type: application/xml Accept: application/xml
21.1. Version-Dependent Capabilities
The
capabilities element contains any number of version elements that describe capabilities dependent on a compatibility level.
The
version element includes attributes for major and minor version numbers. This indicates the current version level.
The following representation shows capabilities specific to Red Hat Enterprise Virtualization Manager
3.0, 3.1, 3.2, 3.3, 3.4, 3.5, and 3.6 respectively:
<capabilities>
<version major="3" minor="0">
...
</version>
<version major="3" minor="1">
...
</version>
<version major="3" minor="2">
...
</version>
<version major="3" minor="3">
...
</version>
<version major="3" minor="4">
...
</version>
<version major="3" minor="5">
...
</version>
<version major="3" minor="6">
...
</version>
...
</capabilities>
Each
version contains a series of capabilities dependent on the version specified.
21.2. Current Version
The
current element signifies if the version specified is the most recent supported compatibility level. The value is a Boolean true or false.
<capabilities>
<version major="3" minor="5">
...
<current>true</current>
...
</version>
</capabilities>
21.3. Features
Each version contains a list of compatible features. The following table lists the features compatible with Red Hat Enterprise Virtualization 3.5.
Table 21.1. Feature Types
| Feature | Description |
|---|---|
| Transparent huge pages memory policy | Allows you to define the availability of transparent huge pages for hosts. Acceptable values are true or false. |
| Gluster support | This features provides support for using Gluster Volumes and Bricks as storage. |
| POSIX-FS storage type | This feature provides support for the POSIX-FS storage type. |
| Port mirroring | Allows you to define the availability of port mirroring for virtual network interface cards. Acceptable values are true or false. |
| Display server time | Displays the current date and time in the API. |
| Display host memory | Displays the total memory for a specific host. |
| Display host sockets | Allows you to define the topology of a host CPU. Takes three attributes - sockets, threads and cores - which define the number of host sockets displayed, the number of threads and the number of cores per socket. |
| Search case sensitivity | Allows you to specify whether a search query is case sensitive by providing the case-sensitive=true|false URL parameter. |
Maximum results for GET requests | Allows you to specify the maximum number of results returned from a GET request. |
| JSON content type | Allows you to define a header that makes it possible to set a correlation ID for POST and PUT requests. |
| Activate and deactivate disks | Allows you to activate or deactivate a disk by specifying activate or deactivate as an action on a specific virtual disk. |
| Activate and deactivate network interface cards | Allows you to activate or deactivate a network interface card by specifying activate or deactivate as an action on a specific network interface card. |
| Snapshot refactoring | Allows you to refactor snapshots for virtual machines. |
| Remove template disks from specified storage domain | Allows you to remove virtual machine template disks from a specific storage domain using a DELETE request. |
| Floating disks | Floating disks are disks that are not attached to any virtual machine. With this feature, such disks also appear in the root collection rather than under specific virtual machines. |
| Asynchronous deletion | Allows you to specify that DELETE requests are to be performed asynchronously by specifying the async URL parameter. |
| Session-based authentication | Allows you to maintain a client-server session by providing an appropriate header, eliminating the need to log in with each request. |
| Virtual machine applications | Allows you to view a list of applications installed on a specific virtual machine. This list is located in the applications element of a specific virtual machine. |
| VirtIO-SCSI support | This feature provides support for para-virtualized SCSI controller devices. |
| Custom resource comments | Allows you to add custom comments to data centers and other resources. |
| Refresh host capabilities | Allows you to synchronize data on hosts and refresh the list of network interfaces available to a specific host. |
| Memory snapshot | Allows you to include the memory state as part of a virtual machine snapshot. |
| Watchdog device | Allows you to create watchdog devices for virtual machines. |
| SSH authentication method | Allows you to authenticate with hosts over SSH using an administrative user password or SSH public key. |
| Force select SPM | Allows you to force the selection of a host as SPM. |
| Console device | Allows you to control the attachment of console devices in virtual machines. |
| Storage server connections for storage domains | Allows you to view storage server connections to or from a specific storage domain. |
| Attach and detach storage server connections | Allows you to attach or detach storage server connections to or from a specific storage domain. |
| Single PCI for Qxl | Allows you to view multiple video devices via a single PCI guest device. |
| Add virtual machine from OVF configuration | Allows you to add a virtual machine from a provided OVF configuration. |
| Virtual network interface card profiles | Allows you to configure a profile that defines quality of service, custom properties and port mirroring for a specific virtual network interface card. |
| Image storage domains (tech preview) | Allows you to import images from and export images to an image storage domain such as an OpenStack image service (Glance). |
| Virtual machine fully qualified domain names | Allows you to retrieve the fully qualified domain name of a specific virtual machine. |
| Attaching disk snapshots to virtual machines | This feature provides support for attaching disk snapshots to virtual machines. |
| Cloud-Init | Allows you to initialize a virtual machine using Cloud Init. |
| Gluster brick management | Allows you to delete gluster bricks with data migration using the actions migrate and DELETE. The migrate action and stopmigrate action allow you to migrate data and reuse the brick. |
| Copy and move back-end disks | Allows you to copy and move disks in additional contexts. |
| Network labels | Allows you to provision networks on hosts using labels. |
| Reboot virtual machines | Allows you to reboot virtual machines via a single action. |
A full list of feature elements and their attributes is located at the top of the section for the relevant version:
<capabilities>
<version major="3" minor="4">
...
<features>
<feature>
<name>Transparent-Huge-Pages Memory Policy</name>
<transparent_huepages/>
</feature>
</features>
...
</version>
</capabilities>
Chapter 22. Common Features
22.1. Element Property Icons
Note
Throughout this guide, the elements of each resource are detailed in tables. These tables include a properties column, displaying icons depicting element properties. The meaning of these icons is shown in Table 22.1, “Element property icons”.
Table 22.1. Element property icons
| Property | Description | Icon |
|---|---|---|
| Required for creation | These elements must be included in the client-provided representation of a resource on creation, but are not mandatory for an update of a resource. | 
|
| Non-updatable | These elements cannot have their value changed when updating a resource. Include these elements in a client-provided representation on update only if their values are not altered by the API user. If altered, the API reports an error. | 
|
| Read-only | These elements are read-only. Values for read-only elements are not created or modified. | 
|
22.2. Representations
22.2.1. Representations
The API structures resource representations in the following XML document structure:
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<description>A description of the resource</description>
...
</resource>
In the context of a virtual machine, the representation appears as follows:
<vm id="5b9bbce5-0d72-4f56-b931-5d449181ee06"
href="/api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
<name>RHEL6-Machine</name>
<description>Red Hat Enterprise Linux 6 Virtual Machine</description>
...
</vm>
22.2.2. Common Attributes to Resource Representations
All resource representations contain a set of common attributes
Table 22.2. Common attributes to resource representations
| Attribute | Type | Description | Properties |
|---|---|---|---|
id | GUID | Each resource in the virtualization infrastructure contains an id, which acts as a globally unique identifier (GUID). The GUID is the primary method of resource identification. | |
href | string | The canonical location of the resource as an absolute path. |
22.2.3. Common Elements to Resource Representations
All resource representations contain a set of common elements.
Table 22.3. Common elements to resource representations
| Element | Type | Description | Properties |
|---|---|---|---|
name | string | A user-supplied human readable name for the resource. The name is unique across all resources of its type. | |
description | string | A free-form user-supplied human readable description of the resource. |
22.3. Collections
- 22.3.1. Collections
- 22.3.2. Listing All Resources in a Collection
- 22.3.3. Listing Extended Resource Sub-Collections
- 22.3.4. Searching Collections with Queries
- 22.3.5. Maximum Results Parameter
- 22.3.6. Case Sensitivity
- 22.3.7. Query Syntax
- 22.3.8. Wildcards
- 22.3.9. Pagination
- 22.3.10. Creating a Resource in a Collection
- 22.3.11. Asynchronous Requests
22.3.1. Collections
A collection is a set of resources of the same type. The API provides both top-level collections and sub-collections. An example of a top-level collection is the
hosts collection which contains all virtualization hosts in the environment. An example of a sub-collection is the host.nics collection which contains resources for all network interface cards attached to a host resource.
22.3.2. Listing All Resources in a Collection
Obtain a listing of resources in a collection with a
GET request on the collection URI obtained from the entry point.
Include an
Accept HTTP header to define the MIME type for the response format.
GET /api/[collection] HTTP/1.1 Accept: [MIME type]
22.3.3. Listing Extended Resource Sub-Collections
The API extends collection representations to include sub-collections when the
Accept header includes the detail parameter.
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection
This includes multiple sub-collection requests using either separated
detail parameters:
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1; detail=subcollection2
Or one
detail parameter that separates the sub-collection with the + operator:
GET /api/collection HTTP/1.1 Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
The API supports extended sub-collections for the following main collections.
Table 22.4. Collections that use extended sub-collections
| Collection | Extended Sub-Collection Support |
|---|---|
hosts | statistics |
vms | statistics, nics, disks |
Example 22.1. A request for extended statistics, NICs and disks sub-collections in the vms collection
GET /api/vms HTTP/1.1 Accept: application/xml; detail=statistics+nics+disks
22.3.4. Searching Collections with Queries
A
GET request on a "collection/search" link results in a search query of that collection. The API only returns resources within the collection that satisfy the search query constraints.
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<collection>
<resource id="resource_id" href="/api/collection/resource_id">
...
</resource>
...
</collection>
22.3.5. Maximum Results Parameter
Use the
max URL parameter to limit the list of results. Previous to Red Hat Enterprise Virtualization 3.4, the default size of the result was limited by the SearchResultsLimit parameter. From Red Hat Enterprise Virtualization 3.4, this parameter does not affect the REST API and an API search query without specifying the max parameter will return all values. Specifying the max parameter is recommended to prevent API search queries from slowing UI performance.
GET /api/collection;max=1 HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<collection>
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<description>A description of the resource</description>
...
</resource>
</collection>
22.3.6. Case Sensitivity
All search queries are case sensitive by default. The URL syntax provides a Boolean option to toggle case sensitivity.
Example 22.2. Case insensitive search query
GET /api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml
22.3.7. Query Syntax
The API uses the URI templates to perform a search
query with a GET request:
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
The
query template value refers to the search query the API directs to the collection. This query uses the same format as Red Hat Enterprise Virtualization Query Language:
(criteria) [sortby (element) asc|desc]
The
sortby clause is optional and only needed when ordering results.
Table 22.5. Example search queries
| Collection | Criteria | Result |
|---|---|---|
hosts | vms.status=up | Displays a list of all hosts running virtual machines that are up. |
vms | domain=qa.company.com | Displays a list of all virtual machines running on the specified domain. |
vms | users.name=mary | Displays a list of all virtual machines belonging to users with the user name mary. |
events | severity>normal sortby time | Displays the list of all events with severity higher than normal and sorted by the time element values. |
events | severity>normal sortby time desc | Displays the list of all events with severity higher than normal and sorted by the time element values in descending order. |
The API requires the
query template to be URL-encoded to translate reserved characters, such as operators and spaces.
Example 22.3. URL-encoded search query
GET /api/vms?search=name%3Dvm1 HTTP/1.1 Accept: application/xml
22.3.8. Wildcards
Search queries substitute part of a value with an asterisk as a wildcard.
Example 22.4. Wildcard search query for name=vm*
GET /api/vms?search=name%3Dvm* HTTP/1.1 Accept: application/xml
This query would result in all virtual machines with names beginning with
vm, such as vm1, vm2, vma or vm-webserver.
Example 22.5. Wildcard search query for name=v*1
GET /api/vms?search=name%3Dv*1 HTTP/1.1 Accept: application/xml
This query would result in all virtual machines with names beginning with
v and ending with 1, such as vm1, vr1 or virtualmachine1.
22.3.9. Pagination
Some Red Hat Enterprise Virtualization environments contain large collections of resources. However, the API only displays a default number of resources for one search query to a collection. To display more than the default, the API separates collections into pages via a search query containing the
page command.
Example 22.6. Paginating resources
This example paginates resources in a collection. The URL-encoded request is:
GET /api/collection?search=page%201 HTTP/1.1 Accept: application/xml
Increase the
page value to view the next page of results:
GET /api/collection?search=page%202 HTTP/1.1 Accept: application/xml
Use the
page command in conjunction with other commands in a search query. For example:
GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1 Accept: application/xml
This query displays the second page in a collection listing ordered by a chosen element.
Important
The REST APIs are stateless; it is not possible to retain a state between different requests since all requests are independent from each other. As a result, if a status change occurs between your requests, then the page results may be inconsistent.
For example, if you request a specific page from a list of VMs, and a status change occurs before you can request the next page, then your results may be missing entries or contain duplicated entries.
22.3.10. Creating a Resource in a Collection
Create a new resource with a
POST request to the collection URI containing a representation of the new resource.
A
POST request requires a Content-Type header. This informs the API of the representation MIME type in the body content as part of the request.
Include an
Accept HTTP header to define the MIME type for the response format.
Each resource type has its own specific required properties. The client supplies these properties when creating a new resource. Refer to the individual resource type documentation for more details.
If a required property is absent, the creation fails with a representation indicating the missing elements.
POST /api/[collection] HTTP/1.1 Accept: [MIME type] Content-Type: [MIME type] [body]
22.3.11. Asynchronous Requests
The API performs asynchronous
POST requests unless the user overrides them with an Expect: 201-created header.
For example, certain resources, such as Virtual Machines, Disks, Snapshots and Templates, are created asynchronously. A request to create an asynchronous resource results in a
202 Accepted status. The initial document structure for a 202 Accepted resource also contains a creation_status element and link for creation status updates. For example:
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<name>Resource-Name</name>
</resource>
HTTP/1.1 202 Accepted
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
<name>Resource-Name</name>
<creation_status>
<state>pending</state>
</creation status>
<link rel="creation_status"
href="/api/collection/resource_id/creation_status/creation_status_id"/>
...
</resource>
A
GET request to the creation_status link provides a creation status update:
GET /api/collection/resource_id/creation_status/creation_status_id HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<creation id="creation_status_id"
href="/api/collection/resource_id/creation_status/creation_status_id">
<status>
<state>complete</state>
</status>
</creation>
Overriding the asynchronous resource creation requires an
Expect: 201-created header:
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created
<resource>
<name>Resource-Name</name>
</resource>
22.4. Resources
22.4.1. Resources
Resources are data sources in a RESTful web service. Each resource type contains a set of common parameters that the REST API abstracts to form a resource representation, usually in XML or JSON. Users can view a resource representation, then edit the parameters and send the representation back to the resource's URL within the API, which modifies the resource. Users can also delete individual resources through REST.
A RESTful web service also groups resources into collections. Users can view a representation of all resources in a collection. Users also send resource representations to a specific collection to create a new resource within that particular collection.
22.4.2. Retrieving a Resource
Obtain the state of a resource with a
GET request on a URI obtained from a collection listing.
Include an
Accept HTTP header to define the MIME type for the response format.
GET /api/[collection]/[resource_id] HTTP/1.1 Accept: [MIME type]
22.4.3. Updating a Resource
Modify resource properties with a
PUT request containing an updated description from a previous GET request for the resource URI. Details on modifiable properties are found in the individual resource type documentation.
A
PUT request requires a Content-Type header. This informs the API of the representation MIME type in the body content as part of the request.
Include an
Accept HTTP header to define the MIME type for the response format.
PUT /api/collection/resource_id HTTP/1.1 Accept: [MIME type] Content-Type: [MIME type] [body]
This does not include immutable resource properties that an API user has attempted to modify. If an attempt is made to modify a strictly immutable resource property, the API reports a conflict with an error message representation in the response body.
Properties omitted from the representation are ignored and not changed.
22.4.4. Deleting a Resource
Delete a resource with a
DELETE request sent to its URI.
Include an
Accept HTTP header to define the MIME type for the response format.
DELETE /api/[collection]/[resource_id] HTTP/1.1 Accept: [MIME type]
Some cases require optional body content in the
DELETE request to specify additional properties. A DELETE request with optional body content requires a Content-Type header to inform the API of the representation MIME type in the body content. If a DELETE request contains no body content, omit the Content-Type header.
22.4.5. Sub-Collection Relationships
A sub-collection relationship defines a hierarchical link between a resource and a sub-collection. The sub-collection exists or has some meaning in the context of a parent resource. For example, a virtual machine contains network interfaces, which means the API maps the relationship between the virtual machine resource and the network interfaces sub-collection.
Sub-collections are used to model the following relationships types:
- Where one parent resource can contain several child resources and vice versa. For example, a virtual machine can contain several disks and some disks are shared among multiple virtual machines.
- Where mapped resources are dependent on a parent resource. Without the parent resource, the dependent resource cannot exist. For example, the link between a virtual machine and snapshots.
- Where mapped resources exist independently from parent resources but data is still associated with the relationship. For example, the link between a cluster and a network.
The API defines a relationship between a resource and a sub-collection using the
link rel= attribute:
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<resource id="resource_id" href="/api/collection/resource_id">
...
<link rel="subcollection"
href="/api/collection/resource_id/subcollection"/>
...
</resource>
The API user now queries the sub-collection.
GET /api/collection/resource_id/subcollection HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<subcollection>
<subresource id="subresource_id"
href="/api/collection/resource_id/subcollection/subresource_id">
...
</subresource>
...
</subcollection>
22.4.6. XML Element Relationships
XML element links act as an alternative to sub-collections to express relationships between resources. XML element links are simply elements with a "href" attribute that points to the linked element.
XML element links are used to model simple 1:N mappings between resources without a dependency and without data associated with the relationship. For example, the relationship between a host and a cluster.
Examples of such relationships include:
- Backlinks from a resource in a sub-collection to a parent resource; or
- Links between resources with an arbitrary relationship.
Example 22.7. Backlinking from a sub-collection resource to a resource using an XML element
GET /api/collection/resource_id/subcollection/subresource_id HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/xml
<subcollection>
<subresource id="subresource_id"
href="/api/collection/resource_id/subcollection/subresource_id">
<resource id="resource_id" href="/api/collection/resource_id"/>
...
</subresource>
</subcollection>
22.4.7. Actions
Most resources include a list of action links to provide functions not achieved through the standard HTTP methods.
<resource>
...
<actions>
<link rel="start" href="/api/collection/resource_id/start"/>
<link rel="stop" href="/api/collection/resource_id/stop"/>
...
</actions>
...
</resource>
The API invokes an action with a
POST request to the supplied URI. The body of the POST requires an action representation encapsulating common and task-specific parameters.
Table 22.6. Common action parameters
| Element | Description |
|---|---|
async | true if the server responds immediately with 202 Accepted and an action representation contains a href link to be polled for completion. |
grace_period | a grace period in milliseconds, which must expire before the action is initiated. |
Individual actions and their parameters are documented in the individual resource type's documentation. Some parameters are mandatory for specific actions and their absence is indicated with a
fault response.
An action also requires a
Content-Type: application/xml header since the POST request requires an XML representation in the body content.
When the action is initiated asynchronously, the immediate
202 Accepted response provides a link to monitor the status of the task:
POST /api/collection/resource_id/action HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<action>
<async>true</async>
</action>
HTTP/1.1 202 Accepted
Content-Type: application/xml
<action id="action_id"
href="/api/collection/resource_id/action/action_id">
<async>true</async>
...
</action>
A subsequent
GET on the action URI provides an indication of the status of the asynchronous task.
Table 22.7. Action statuses
| Status | Description |
|---|---|
pending | Task has not yet started. |
in_progress | Task is in operation. |
complete | Task completed successfully. |
failed | Task failed. The returned action representation would contain a fault describing the failure. |
Once the task has completed, the action is retained for an indeterminate period. Once this has expired, subsequent
GETs are 301 Moved Permanently redirected back to the target resource.
GET /api/collection/resource_id/action/action_id HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<action id="action_id"
href="/api/collection/resource_id/action/action_id">
<status>
<state>pending</state>
</status>
<link rel="parent" /api/collection/resource_id"/>
<link rel="replay" href="/api/collection/resource_id/action"/>
</action>
An action representation also includes some links that are identified by the
rel attribute:
Table 22.8. Action relationships
| Type | Description |
|---|---|
parent | A link back to the resource of this action. |
replay | A link back to the original action URI. POSTing to this URI causes the action to be re-initiated. |
22.4.8. Permissions
Each resource contains a
permissions sub-collection. Each permission contains a user, an assigned role and the specified resource. For example:
GET /api/collection/resource_id/permissions HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<permissions>
<permission id="permission-id"
href="/api/collection/resource_id/permissions/permission_id">
<role id="role_id" href="/api/roles/role_id"/>
<user id="user_id" href="/api/users/user_id"/>
<resource id="resource_id" href="/api/collection/resource_id"/>
</permission>
...
</permissions>
A resource acquires a new permission when an API user sends a
POST request with a permission representation and a Content-Type: application/xml header to the resource's permissions sub-collection. Each new permission requires a role and a user:
POST /api/collection/resource_id/permissions HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<permission>
<role id="role_id"/>
<user id="user_id"/>
</permission>
HTTP/1.1 201 Created
Content-Type: application/xml
<permission id="permission_id"
href="/api/resources/resource_id/permissions/permission_id">
<role id="role_id" href="/api/roles/role_id"/>
<user id="user_id" href="/api/users/user_id"/>
<resource id="resource_id" href="/api/collection/resource_id"/>
</permission>
22.4.9. Handling Errors
Some errors require further explanation beyond a standard HTTP status code. For example, the API reports an unsuccessful resource state update or action with a
fault representation in the response entity body. The fault contains a reason and detail strings. Clients must accommodate failed requests via extracting the fault or the expected resource representation depending on the response status code. Such cases are clearly indicated in the individual resource documentation.
PUT /api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<id>id-update-test</id>
</resource>
HTTP/1.1 409 Conflict
Content-Type: application/xml
<fault>
<reason>Broken immutability constraint</reason>
<detail>Attempt to set immutable field: id</detail>
</fault>
Chapter 23. The Backup and Restore API
The backup and restore API is a collection of functions that allows you to perform full or file-level backup and restoration of virtual machines. The API combines several components of Red Hat Enterprise Virtualization, such as live snapshots and the REST API, to create and work with temporary volumes that can be attached to a virtual machine containing backup software provided by an independent software provider.
For supported third-party backup vendors, consult the Red Hat Enterprise Virtualization Ecosystem at Red Hat Marketplace.
23.1. Backing Up a Virtual Machine
Use the backup and restore API to back up a virtual machine. This procedure assumes you have two virtual machines: the virtual machine to back up, and a virtual machine on which the software for managing the backup is installed.
Procedure 23.1. Backing Up a Virtual Machine
- Using the REST API, create a snapshot of the virtual machine to back up:
POST /api/vms/11111111-1111-1111-1111-111111111111/snapshots/ HTTP/1.1 Accept: application/xml Content-type: application/xml <snapshot> <description>BACKUP</description> </snapshot>Note
When you take a snapshot of a virtual machine, a copy of the configuration data of the virtual machine as at the time the snapshot was taken is stored in thedataattribute of theconfigurationattribute ininitializationunder the snapshot.Important
You cannot take snapshots of disks that are marked as shareable or that are based on direct LUN disks. - Retrieve the configuration data of the virtual machine from the
dataattribute under the snapshot:GET /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1 Accept: application/xml Content-type: application/xml
- Identify the disk ID and snapshot ID of the snapshot:
GET /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111/disks HTTP/1.1 Accept: application/xml Content-type: application/xml
- Attach the snapshot to the backup virtual machine and activate the disk:
POST /api/vms/22222222-2222-2222-2222-222222222222/disks/ HTTP/1.1 Accept: application/xml Content-type: application/xml <disk id="11111111-1111-1111-1111-111111111111"> <snapshot id="11111111-1111-1111-1111-111111111111"/> <active>true</active> </disk> - Use the backup software on the backup virtual machine to back up the data on the snapshot disk.
- Detach the snapshot disk from the backup virtual machine:
DELETE /api/vms/22222222-2222-2222-2222-222222222222/disks/11111111-1111-1111-1111-111111111111 HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <detach>true</detach> </action> - Optionally, delete the snapshot:
DELETE /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1 Accept: application/xml Content-type: application/xml
You have backed up the state of a virtual machine at a fixed point in time using backup software installed on a separate virtual machine.
23.2. Restoring a Virtual Machine
Restore a virtual machine that has been backed up using the backup and restore API. This procedure assumes you have a backup virtual machine on which the software used to manage the previous backup is installed.
Procedure 23.2. Restoring a Virtual Machine
- Use the REST API to create a floating disk on which to restore the backup. See Section 31.3.1, “Creating a Floating Disk” for details on how to create a floating disk.
- Attach the disk to the backup virtual machine:
POST /api/vms/22222222-2222-2222-2222-222222222222/disks/ HTTP/1.1 Accept: application/xml Content-type: application/xml <disk id="11111111-1111-1111-1111-111111111111"> </disk>
- Use the backup software to restore the backup to the disk.
- Detach the disk from the backup virtual machine:
DELETE /api/vms/22222222-2222-2222-2222-222222222222/disks/11111111-1111-1111-1111-111111111111 HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <detach>true</detach> </action> - Create a new virtual machine using the configuration data of the virtual machine being restored:
POST /api/vms/ HTTP/1.1 Accept: application/xml Content-type: application/xml <vm> <cluster> <name>cluster_name</name> </cluster> <name>NAME</name> ... </vm> - Attach the disk to the new virtual machine:
POST /api/vms/33333333-3333-3333-3333-333333333333/disks/ HTTP/1.1 Accept: application/xml Content-type: application/xml <disk id="11111111-1111-1111-1111-111111111111"> </disk>
You have restored a virtual machine using a backup that was created using the backup and restore API.
Chapter 24. Data Centers
24.1. Data Center Elements
The
datacenters collection provides information about the data centers in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="datacenters" link obtained from the entry point URI.
The following table shows specific elements contained in a data center resource representation.
Table 24.1. Data center elements
| Element | Type | Description | Properties |
|---|---|---|---|
name | string | A plain text, human-readable name for the data center. The name is unique across all data center resources. |
|
description | string | A plain text, human-readable description of the data center | |
link rel="storagedomains" | relationship | A link to the sub-collection for storage domains attached to this data center. | |
link rel="clusters" | relationship | A link to the sub-collection for clusters attached to this data center. | |
link rel="networks" | relationship | A link to the sub-collection for networks available to this data center. | |
link rel="permissions" | relationship | A link to the sub-collection for data center permissions. | |
link rel="quotas" | relationship | A link to the sub-collection for quotas associated with this data center. | |
local | Boolean: true or false | Specifies whether the data center is a local data center, such as created in all-in-one instances. |
|
storage_format | enumerated | Describes the storage format version for the data center. A list of enumerated values are available in capabilities. | |
version major= minor= | complex | The compatibility level of the data center. | |
supported_versions | complex | A list of possible version levels for the data center, including version major= minor=. |
|
status | see below | The data center status. |
|
The
status contains one of the following enumerated values: uninitialized, up, maintenance, not_operational, problematic and contend. These states are listed in data_center_states under capabilities.
24.2. XML Representation of a Data Center
Example 24.1. An XML representation of a data center
<data_center href="/api/datacenters/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000">
<name>Default</name>
<description>The default Data Center</description>
<link href="/api/datacenters/00000000-0000-0000-0000-000000000000/storagedomains" rel="storagedomains"/>
<link href="/api/datacenters/00000000-0000-0000-0000-000000000000/clusters" rel="clusters"/>
<link href="/api/datacenters/00000000-0000-0000-0000-000000000000/networks" rel="networks"/>
<link href="/api/datacenters/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
<link href="/api/datacenters/00000000-0000-0000-0000-000000000000/quotas" rel="quotas"/>
<local>false</local>
<storage_format>v3</storage_format>
<version major="3" minor="4"/>
<supported_versions>
<version major="3" minor="4"/>
</supported_versions>
<status>
<state>up</state>
</status>
</data_center>24.3. JSON Representation of a Data Center
Example 24.2. A JSON representation of a data center
{
"data_center" : [ {
"local" : "false",
"storage_format" : "v3",
"version" : {
"major" : "3",
"minor" : "5"
},
"supported_versions" : {
"version" : [ {
"major" : "3",
"minor" : "5"
} ]
},
"status" : {
"state" : "up"
},
"name" : "Default",
"description" : "The default Data Center",
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255",
"id" : "00000002-0002-0002-0002-000000000255",
"link" : [ {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/storagedomains",
"rel" : "storagedomains"
}, {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/clusters",
"rel" : "clusters"
}, {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/networks",
"rel" : "networks"
}, {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/permissions",
"rel" : "permissions"
}, {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/quotas",
"rel" : "quotas"
}, {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/iscsibonds",
"rel" : "iscsibonds"
}, {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/qoss",
"rel" : "qoss"
} ]
} ]
}
24.4. Methods
24.4.1. Creating a New Data Center
Creation of a new data center requires the
name and local elements.
Example 24.3. Creating a data center
POST /api/datacenters HTTP/1.1
Accept: application/xml
Content-type: application/xml
<data_center>
<name>NewDatacenter</name>
<local>false</local>
</data_center>
24.4.2. Updating a Data Center
The
name, description, storage_type, version and storage_format elements are updatable post-creation.
Example 24.4. Updating a data center
PUT /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<data_center>
<name>UpdatedName</name>
<description>An updated description for the data center</description>
</data_center>
24.5. Sub-Collections
24.5.1. Storage Domains Sub-Collection
24.5.1.1. Storage Domains Sub-Collection
Each data center contains a sub-collection for attached storages domain. An API user interacts with this sub-collection using the standard REST methods.
An attached storage domain has a similar representation to a top-level storage domain, with the exception that it has a data center specific
status and set of actions. States for the status element are listed in storage_domain_states under capabilities.
Important
The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement.
24.5.1.2. Attaching and Detaching a Storage Domain
A data center is only ready for use when at least one storage domain is attached, which an API user
POSTs to the data center's storage domains sub-collection.
When attaching a storage domain, its
id or name must be supplied. An example of attaching a storage domain to a data center:
Example 24.6. Attach a storage domain to a data center
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
HTTP/1.1 201 Created
Location: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed
Content-Type: application/xml
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
fabe0451-701f-4235-8f7e-e20e458819ed">
<name>images0</name>
<type>data</type>
<status>
<state>inactive</state>
</status>
<master>true</master>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/images/0</path>
</storage>
<data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
<actions>
<link rel="activate"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate"/>
<link rel="deactivate"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate"/>
</actions>
</storage_domain>
Detach a storage domain from a data center with a
DELETE request. Include an optional async element for this request to be asynchronous.
Example 24.7. Detach a storage domain from a data center
DELETE /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <async>true</async> </action>
24.5.1.3. Actions
24.5.1.3.1. Activate Storage Domain Action
An attached storage domain requires activation on a data center before use. The activate action does not take any action specific parameters.
Example 24.8. Action to active a storage domain on a datacenter
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
24.5.1.3.2. Deactivate Storage Domain Action
An attached storage domain is deactivated on a data center before removal. The deactivate action does not take any action specific parameters.
Example 24.9. Action to deactivate a storage domain on a datacenter
POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
24.5.2. Network Sub-Collection
24.5.2.1. Networks Sub-Collection
Networks associated with a data center are represented with the
networks sub-collection. The representation of a data center's network sub-collection contains the following elements:
Table 24.2. Network elements
| Element | Type | Description |
|---|---|---|
name | string | A plain text, human readable name for the network. |
description | string | A plain text, human readable description of the network. |
rel="permissions" | relationship | A link to the permissions sub-collection for the network. |
rel="vnicprofiles" | relationship | A link to the vnicprofiles sub-collection for the network. |
rel="labels" | relationship | A link to the labels sub-collection for the network. |
data_center id= | relationship | A reference to the data center of which the network is a member. |
stp | Boolean: true or false | Specifies whether spanning tree protocol is enabled for the network. |
mtu | integer | Specifies the maximum transmission unit for the network. |
usages | complex | Defines a set of usage elements for the network. Users can define networks as vm and display networks at this level. |
In the REST API, you can manipulate the
networks sub-collection with the standard REST methods. For example, the POST method can be used to update a network id or name
Example 24.10. Associating a network resource with a data center
POST /api/datacenters/00000000-0000-0000-0000-000000000000/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
<name>rhevm</name>
</network>
HTTP/1.1 201 Created
Location: http://{host}/clusters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000
Content-Type: application/xml
<network href="/api/networks/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000">
<name>Network_001</name>
<link href="/api/networks/00000000-0000-0000-0000-000000000000/permissions"
rel="permissions"/>
<link href="/api/networks/00000000-0000-0000-0000-000000000000/vnicprofiles"
rel="vnicprofiles"/>
<link href="/api/networks/00000000-0000-0000-0000-000000000000/labels"
rel="labels"/>
<data_center href="/api/datacenters/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
<stp>false</stp>
<mtu>0</mtu>
<usages>
<usage>vm</usage>
</usages>
</network>
Update the resource with a
PUT request. The maximum transmission unit of a network is set using a PUT request to specify the integer value of the mtu element.
Example 24.11. Setting the network maximum transmission unit
PUT /api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network>
<mtu>1500</mtu>
</network>
An association is removed with a
DELETE request to the appropriate element in the collection.
Example 24.12. Removing a network association from a data center
DELETE /api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1 HTTP/1.1 204 No Content
24.5.3. Quotas Sub-Collection
24.5.3.1. Quotas Sub-Collection
The quotas sub-collection lists restrictions that Red Hat Enterprise Virtualization Manager implements on resources. An API user views this sub-collection and its resources using the
GET method.
Example 24.13. An XML representation of a quota
<quota href="/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c
/quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe"
id="e13ff85a-b2ba-4f7b-8010-e0d057c03dfe">
<name>MyQuota</name>
<description>A quota for my Red Hat Enterprise
Virtualization environment</description>
<data_center href= "/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c"
id="56087282-d7a6-11e1-af44-001a4a400e0c"/>
</quota>
Creation of a new quota requires the
name and description elements.
Example 24.14. Creating a quota
POST /api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c/quotas HTTP/1.1
Accept: application/xml
Content-type: application/xml
<quota>
<name>VMQuota</name>
<description>My new quota for virtual machines</description>
</quota>
Removal of a quota requires a
DELETE request.
Example 24.15. Removing a quota
DELETE /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe HTTP/1.1 HTTP/1.1 204 No Content
24.6. Actions
24.6.1. Force Remove Data Center Action
An API user forces the removal of a data center when encountering unresolvable problems with storage domains, such as the loss of connection to a master storage domain or a lack of available hosts when deleting storage domains. The API includes a
force action to help with these situations.
This action removes database entries associated with a chosen data center before the API removes the data center from the Red Hat Enterprise Virtualization environment. This means the API removes the data center regardless of associated storage domains.
This action requires a
DELETE method. The request body contains an action representation with the force parameter set to true. The request also requires an additional Content-type: application/xml header to process the XML representation in the body.
Example 24.16. Force remove action on a data center
DELETE /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <force>true</force> </action>
This action:
- Deletes all database information for
datastorage domains associated the data center; - Deletes all database information for resources, such as virtual machines and templates, on
datastorage domains associated the data center; - Detaches
isoandexportstorage domains from the data center; and - Deletes the database information for the data center.
This action overrides the requirement for a data center to be empty before deletion.
Important
This action only removes the database entries for resources associated with the data center. The
data storage domains associated with the data center require manual format before reuse. Metadata for iso and export domains require manual cleaning prior to use on another data center.
Chapter 25. Clusters
25.1. Cluster Elements
The
clusters collection provides information about clusters in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="clusters" link obtained from the entry point URI.
The following table shows specific elements contained in a cluster resource representation.
Table 25.1. Cluster elements
| Element | Type | Description | Properties |
|---|---|---|---|
name | string | A user-supplied, human-readable name for the cluster. The name is unique across all cluster resources. |
|
description | string | A free-form, user-supplied, human-readable description of the cluster. | |
link rel="networks" | relationship | A link to the sub-collection for networks associated with this cluster. | |
link rel="permissions" | relationship | A link to the sub-collection for cluster permissions. | |
link rel="glustervolumes" | relationship | A link to the sub-collection for Red Hat Gluster Storage volumes associated with this cluster. | |
link rel="glusterhooks" | relationship | A link to the sub-collection for Red Hat Gluster Storage volume hooks associated with this cluster. | |
link rel="affinitygroups" | relationship | A link to the sub-collection for virtual machine affinity groups associated with this cluster. | |
cpu id= | complex | A server CPU reference that defines the CPU type all hosts must support in the cluster. |
|
data_center id= | GUID | A reference to the data center membership of this cluster. |
|
memory_policy | complex | Defines the cluster's policy on host memory utilization. |
|
scheduling_policy | complex | Defines the load-balancing or power-saving modes for hosts in the cluster. |
|
version major= minor= | complex | The compatibility level of the cluster. |
|
supported_versions | complex | A list of possible version levels for the cluster. |
|
error_handling | complex/enumerated | Defines virtual machine handling when a host within a cluster becomes non-operational. Requires a single on_error element containing an enumerated type property listed in capabilities. | |
virt_service | Boolean | Defines whether to expose virtualization services for this cluster. | |
gluster_service | Boolean | Defines whether to expose Red Hat Gluster Storage services for this cluster. | |
threads_as_cores | Boolean | Defines whether hosts can run virtual machines with a total number of processor cores greater than the number of cores in the host. | |
tunnel_migration | Boolean | Defines whether virtual machines use a libvirt-to-libvirt tunnel during migration. | |
trusted_service | Boolean | Defines whether an OpenAttestation server is used to verify hosts. | |
ballooning_enabled | Boolean | Defines whether ballooning is enabled for the cluster. | |
ksm | Boolean | Defines whether ksm is enabled for the cluster. |
Note
When a host's free memory drops below 20%, ballooning commands like
mom.Controllers.Balloon - INFO Ballooning guest:half1 from 1096400 to 1991580 are logged to /etc/vdsm/mom.conf. /etc/vdsm/mom.conf is the Memory Overcommit Manager log file. An event will also be added to the event log if a virtual machine does not respect a balloon.
25.2. Memory Policy Elements
The
memory_policy element contains the following elements:
Table 25.2. Memory policy elements
| Element | Type | Description | Properties |
|---|---|---|---|
overcommit percent= | complex | The percentage of host memory allowed in use before no more virtual machines can start on a host. Virtual machines can use more than the available host memory due to memory sharing under KSM. Recommended values include 100 (None), 150 (Server Load) and 200 (Desktop Load). |
|
transparent_hugepages | complex | Define the enabled status of Transparent Hugepages. The status is either true or false. Check capabilities feature set to ensure your version supports transparent hugepages. |
|
25.3. Scheduling Policy Elements
The
scheduling_policy element contains the following elements:
Table 25.3. Scheduling policy elements
| Element | Type | Description | Properties |
|---|---|---|---|
policy | enumerated | The VM scheduling mode for hosts in the cluster. A list of enumerated types are listed in capabilities. |
|
thresholds low= high= duration= | complex | Defines CPU limits for the host. The high attribute controls the highest CPU usage percentage the host can have before being considered overloaded. The low attribute controls the lowest CPU usage percentage the host can have before being considered underutilized. The duration attribute refers to the number of seconds the host needs to be overloaded before the scheduler starts and moves the load to another host. |
|
25.4. XML Representation of a Cluster
Example 25.1. An XML representation of a cluster
<cluster id="00000000-0000-0000-0000-000000000000"
href="/api/clusters/00000000-0000-0000-0000-000000000000">
<name>Default</name>
<description>The default server cluster</description>
<link rel="networks"
href="/api/clusters/00000000-0000-0000-0000-000000000000/networks"/>
<link rel="permissions"
href="/api/clusters/00000000-0000-0000-0000-000000000000/permissions"/>
<link rel="glustervolumes"
href="/api/clusters/00000000-0000-0000-0000-000000000000/glustervolumes"/>
<link rel="glusterhooks"
href="/api/clusters/00000000-0000-0000-0000-000000000000/glusterhooks"/>
<link rel="affinitygroups"
href="/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups"/>
<cpu id="Intel Penryn Family"/>
<architecture>X86_64<architecture/>
<data_center id="00000000-0000-0000-0000-000000000000"
href="/api/datacenters/00000000-0000-0000-0000-000000000000"/>
<memory_policy>
<overcommit percent="100"/>
<transparent_hugepages>
<enabled>false</enabled>
</transparent_hugepages>
</memory_policy>
<scheduling_policies>
<policy>evenly_distributed</policy>
<thresholds low="10" high="75" duration="120"/>
</scheduling_policies>
<version minor="0" major="3"/>
<supported_versions>
<version minor="0"<usage> major="3"/>
</supported_versions>
<error_handling>
<on_error>migrate</on_error>
</error_handling>
<virt_service>true</virt_service>
<gluster_service>false</gluster_service>
<threads_as_cores>false</threads_as_cores>
<tunnel_migration>false</tunnel_migration>
<trusted_service>false</trusted_service>
<ha_reservation>false</ha_reservation>
<ballooning_enabled>false</ballooning_enabled>
<ksm>
<enabled>true</enabled>
</ksm>
</cluster>
25.5. JSON Representation of a Cluster
Example 25.2. A JSON representation of a cluster
{
"cluster" : [ {
"cpu" : {
"architecture" : "X86_64",
"id" : "Intel Penryn Family"
},
"data_center" : {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255",
"id" : "00000002-0002-0002-0002-000000000255"
},
"memory_policy" : {
"overcommit" : {
"percent" : "100"
},
"transparent_hugepages" : {
"enabled" : "true"
}
},
"scheduling_policy" : {
"policy" : "none",
"name" : "none",
"href" : "/api/schedulingpolicies/b4ed2332-a7ac-4d5f-9596-99a439cb2812",
"id" : "b4ed2332-a7ac-4d5f-9596-99a439cb2812"
},
"version" : {
"major" : "3",
"minor" : "5"
},
"error_handling" : {
"on_error" : "migrate"
},
"virt_service" : "true",
"gluster_service" : "false",
"threads_as_cores" : "false",
"tunnel_migration" : "false",
"trusted_service" : "false",
"ha_reservation" : "false",
"optional_reason" : "false",
"ballooning_enabled" : "false",
"ksm" : {
"enabled" : "true"
},
"required_rng_sources" : { },
"name" : "Default",
"description" : "The default server cluster",
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb",
"id" : "00000001-0001-0001-0001-0000000002fb",
"link" : [ {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/networks",
"rel" : "networks"
}, {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/permissions",
"rel" : "permissions"
}, {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/glustervolumes",
"rel" : "glustervolumes"
}, {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/glusterhooks",
"rel" : "glusterhooks"
}, {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/affinitygroups",
"rel" : "affinitygroups"
}, {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/cpuprofiles",
"rel" : "cpuprofiles"
} ]
} ]
}
25.6. Methods
25.6.1. Creating a Cluster
Creation of a new cluster requires the
name, cpu id= and datacenter elements. Identify the datacenter with either the id attribute or name element.
Example 25.3. Creating a cluster
POST /api/clusters HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cluster>
<name>cluster1</name>
<cpu id="Intel Penryn Family"/>
<data_center id="00000000-0000-0000-0000-000000000000"/>
</cluster>
25.6.2. Updating a Cluster
The
name, description, cpu id= and error_handling elements are updatable post-creation.
Example 25.4. Updating a cluster
PUT /api/clusters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cluster>
<description>Cluster 1</description>
</cluster>
25.7. Sub-Collections
25.7.1. Networks Sub-Collection
25.7.1.1. Networks Sub-Collection
Networks associated with a cluster are represented with the
networks sub-collection. Every host within a cluster connects to these associated networks.
The representation of a cluster's
network sub-collection is the same as a standard network resource except for the following additional elements:
Table 25.4. Additional network elements
| Element | Type | Description | Properties |
|---|---|---|---|
cluster id= | relationship | A reference to the cluster of which this network is a member. |
|
required | Boolean | Defines required or optional network status. | |
display | Boolean | Defines the display network status. Used for backward compatibility. | |
usages | complex | Defines a set of usage elements for the network. Users can define networks as VM and DISPLAY networks at this level. |
An API user manipulates the
networks sub-collection with the standard REST methods. POSTing a network id or name reference to the networks sub-collection associates the network with the cluster.
Example 25.6. Associating a network resource with a cluster
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
<name>rhevm</name>
</network>
HTTP/1.1 201 Created
Location: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f
Content-Type: application/xml
<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
da05ac09-00be-45a1-b0b5-4a6a2438665f">
<name>rhevm</name>
<status>
<state>operational</state>
</status>
<description>Display Network</description>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
<data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
<required>true</required>
<usages>
<usage>VM</usage>
</usages>
</network>
Update the resource with a
PUT request.
Example 25.7. Setting the display network status
PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network>
<required>false</required>
<usages>
<usage>VM</usage>
<usage>DISPLAY</usage>
</usages>
</network>
The required or optional network status is set using a
PUT request to specify the Boolean value (true or false) of the required element.
Example 25.8. Setting optional network status
PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<network>
<required>false</required>
</network>
An association is removed with a
DELETE request to the appropriate element in the collection.
Example 25.9. Removing a network association from a cluster
DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1 HTTP/1.1 204 No Content
25.7.2. Storage Volumes Sub-Collection
25.7.2.1. Red Hat Gluster Storage Volumes Sub-Collection
Red Hat Enterprise Virtualization provides a means for creating and managing Red Hat Gluster Storage volumes. Red Hat Gluster Storage volumes are associated with clusters and are represented with the
glustervolumes sub-collection.
The representation of a Red Hat Gluster Storage volume resource in the
glustervolumes sub-collection is defined using the following elements:
Table 25.5. Gluster volume elements
| Element | Type | Description | Properties |
|---|---|---|---|
volume_type | enumerated | Defines the volume type. See the capabilities collection for a list of volume types. |
|
bricks | relationship | The sub-collection for the Red Hat Gluster Storage bricks. When creating a new volume, the request requires a set of brick elements to create and manage in this cluster. Requires the server_id of the Red Hat Gluster Storage server and a brick_dir element for the brick directory |
|
transport_types | complex | Defines a set of volume transport_type elements. See the capabilities collection for a list of available transport types. |
|
replica_count | integer | Defines the file replication count for a replicated volume. |
|
stripe_count | integer | Defines the stripe count for a striped volume |
|
options | complex | A set of additional Red Hat Gluster Storage option elements. Each option includes an option name and a value. |
|
Example 25.10. An XML representation of a Red Hat Gluster Storage volume
<gluster_volume id="99408929-82cf-4dc7-a532-9d998063fa95"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
/glustervolume/e199f877-900a-4e30-8114-8e3177f47651">
<name>GlusterVolume1</name>
<link rel="bricks"
href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
/glustervolume/e199f877-900a-4e30-8114-8e3177f47651/bricks"/>
<volume_type>DISTRIBUTED_REPLICATE</volume_type>
<transport_types>
<transport_type>TCP</transport_type>
</transport_types>
<replica_count>2</replica_count>
<stripe_count>1</stripe_count>
<options>
<option>
<name>cluster.min-free-disk</name>
<value>536870912</value>
</option>
</options>
</gluster_volume>
Create a Red Hat Gluster Storage volume via a
POST request with the required name, volume_type and bricks to the sub-collection.
Example 25.11. Creating a Red Hat Gluster Storage volume
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<gluster_volume>
<name>GlusterVolume1</name>
<volume_type>DISTRIBUTED_REPLICATE</volume_type>
<bricks>
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<bricks>
</gluster_volume>
Remove a Red Hat Gluster Storage volume with a
DELETE request.
Example 25.12. Removing a Red Hat Gluster Storage volume
DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651 HTTP/1.1 HTTP/1.1 204 No Content
Important
Resources in the
glustervolumes sub-collection cannot be updated.
25.7.2.2. Bricks Sub-Collection
The
glustervolumes sub-collection contains its own bricks sub-collection to define individual bricks in a Red Hat Gluster Storage volume. The representation of a volume's bricks sub-collection is defined using the following elements:
Table 25.6. Brick elements
| Element | Type | Description | Properties |
|---|---|---|---|
server_id | string | A reference to the Red Hat Gluster Storage server. |
|
brick_dir | string | Defines a brick directory on the Red Hat Gluster Storage server. |
|
replica_count | integer | Defines the file replication count for the brick in the volume. |
|
stripe_count | integer | Defines the stripe count for the brick in the volume |
|
Create new bricks via a
POST request with the required server_id and brick_dir to the sub-collection.
Example 25.13. Adding a brick
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
Remove a brick with a
DELETE request.
Example 25.14. Removing a brick
DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks/0a473ebe-01d2-444d-8f58-f565a436b8eb HTTP/1.1 HTTP/1.1 204 No Content
Important
Resources in the
bricks sub-collection cannot be updated.
25.7.2.3. Actions
25.7.2.3.1. Start Action
The
start action makes a Gluster volume available for use.
Example 25.15. Starting a Volume
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/start HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
Use an optional
force Boolean element to force the action for a running volume. This is useful for starting disabled brick processes in a running volume.
25.7.2.3.2. Stop Action
The
stop action deactivates a Gluster volume.
Example 25.16. Stopping a Volume
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/stop HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
Use an optional
force Boolean element to brute force the stop action.
25.7.2.3.3. Set Option Action
The
setoption action sets a volume option.
Example 25.17. Set an option
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/setoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<option>
<name>cluster.min-free-disk</name>
<value>536870912</value>
</option>
</action>
25.7.2.3.4. Reset Option Action
The
resetoption action resets a volume option.
Example 25.18. Reset an option
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<option>
<name>cluster.min-free-disk</name>
</option>
</action>
25.7.2.3.5. Reset All Options Action
The
resetalloptions action resets all volume options.
Example 25.19. Reset all options
POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetalloptions HTTP/1.1 Accept: application/xml Content-Type: application/xml <action/>
25.7.3. Affinity Groups Sub-Collection
25.7.3.1. Affinity Group Sub-Collection
The representation of a virtual machine affinity group resource in the
affinitygroups sub-collection is defined using the following elements:
Table 25.7. Affinity group elements
| Element | Type | Description | Properties |
|---|---|---|---|
name | string | A plain text, human readable name for the affinity group. |
|
cluster | relationship | A reference to the cluster to which the affinity group applies. | |
positive | Boolean: true or false | Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are members of that affinity group. | |
enforcing | Boolean: true or false | Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines that are members of that affinity group. |
Example 25.20. An XML representation of a virtual machine affinity group
<affinity_group href="/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<name>AF_GROUP_001</name>
<cluster href="/api/clusters/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group>
Create a virtual machine affinity group via a
POST request with the required name attribute.
Example 25.21. Creating a virtual machine affinity group
POST https://XX.XX.XX.XX/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups HTTP/1.1 Accept: application/xml Content-Type: application/xml <affinity_group> <name>AF_GROUP_001</name> <positive>true</positive> <enforcing>true</enforcing> </affinity_group>
Remove a virtual machine affinity group with a
DELETE request.
Example 25.22. Removing a virtual machine affinity group
DELETE https://XX.XX.XX.XX/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000 HTTP/1.1 HTTP/1.1 204 No Content
Chapter 26. Networks
26.1. Network Elements
The
networks collection provides information about the logical networks in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="networks" link obtained from the entry point URI.
The following table shows specific elements contained in a network resource representation.
Table 26.1. Network elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="vnicprofiles" | relationship | A link to the sub-collection for VNIC profiles attached to this logical network. | |
link rel="labels" | relationship | A link to the sub-collection for labels attached to this logical network. | |
data_center id= | GUID | A reference to the data center of which this cluster is a member. |
|
vlan id= | integer | A VLAN tag. | |
stp | Boolean: true or false | true if Spanning Tree Protocol is enabled on this network. | |
mtu | integer | Sets the maximum transmission unit for the logical network. If omitted, the logical network uses the default value. | |
status | One of operational or non_operational | The status of the network. These states are listed in network_states under capabilities. |
|
usages | complex | Defines a set of usage elements for the network. Users can define networks as VM networks at this level. |
Important
The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement.
26.2. XML Representation of a Network Resource
Example 26.1. An XML representation of a network resource
<network href="/api/networks/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000">
<name>rhevm</name>
<description>Management Network</description>
<link href="/api/networks/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
<link href="/api/networks/00000000-0000-0000-0000-000000000000/vnicprofiles" rel="vnicprofiles"/>
<link href="/api/networks/00000000-0000-0000-0000-000000000000/labels" rel="labels"/>
<data_center href="/api/datacenters/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
<stp>false</stp>
<mtu>0</mtu>
<usages>
<usage>vm</usage>
</usages>
</network>
26.3. JSON Representation of a Network Resource
Example 26.2. A JSON representation of a network resource
{
"network" : [ {
"data_center" : {
"href" : "/api/datacenters/00000002-0002-0002-0002-000000000255",
"id" : "00000002-0002-0002-0002-000000000255"
},
"stp" : "false",
"mtu" : "0",
"usages" : {
"usage" : [ "vm" ]
},
"name" : "rhevm",
"description" : "Management Network",
"href" : "/api/networks/00000000-0000-0000-0000-000000000009",
"id" : "00000000-0000-0000-0000-000000000009",
"link" : [ {
"href" : "/api/networks/00000000-0000-0000-0000-000000000009/permissions",
"rel" : "permissions"
}, {
"href" : "/api/networks/00000000-0000-0000-0000-000000000009/vnicprofiles",
"rel" : "vnicprofiles"
}, {
"href" : "/api/networks/00000000-0000-0000-0000-000000000009/labels",
"rel" : "labels"
} ]
} ]
}
26.4. Methods
26.4.1. Creating a Network Resource
Creation of a new network requires the
name and datacenter elements.
Example 26.3. Creating a network resource
POST /api/networks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<network>
<name>network 1</name>
<data_center id="00000000-0000-0000-0000-000000000000"/>
</network>
26.4.2. Updating a Network Resource
The
name, description, ip, vlan, stp and display elements are updatable post-creation.
Example 26.4. Updating a network resource
PUT /api/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<network>
<description>Network 1</description>
</network>
26.5. Sub-collections
26.5.1. Network VNIC Profile Sub-Collection
VNIC (Virtual Network Interface Controller) profiles, also referred to as virtual machine interface profiles, are customized profiles applied to users and groups to limit network bandwidth. Each
vnicprofile contains the following elements:
Table 26.2. Elements for vnic profiles
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the profile. |
description | string | A plain text description of the profile. |
network | string | The unique identifier of the logical network to which the profile applies. |
port_mirroring | Boolean: true or false | The default is false. |
Example 26.6. An XML representation of the network's vnicprofile sub-collection
<vnic_profile href= "/api/vnicprofiles/f9c2f9f1-3ae2-4100-a9a5-285ebb755c0d" id="f9c2f9f1-3ae2-4100-a9a5-285ebb755c0d"> <name>Peanuts</name> <description>shelled</description> <network href= "/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/> <port_mirroring>false</port_mirroring> </vnic_profile> </vnic_profiles>
26.5.2. Network Labels Sub-Collection
Network labels are plain text, human-readable labels that allow you to automate the association of logical networks with physical host network interfaces. Each
label contains the following elements:
Table 26.3. Elements for labels
| Element | Type | Description |
|---|---|---|
network | string | The href and id of the networks to which the label is attached. |
Example 26.7. An XML representation of the network's labels sub-collection
<labels>
<label href="/api/networks/00000000-0000-0000-0000-000000000000/labels/eth0" id="eth0">
<network href="/api/networks/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
</label>
</labels>
26.5.3. Methods
26.5.3.1. Attach Label to Logical Network Action
You can attach labels to a logical network to automate the association of that logical network with physical host network interfaces to which the same label has been attached.
Example 26.8. Action to attach a label to a logical network
POST /api/networks/00000000-0000-0000-0000-000000000000/labels/ HTTP/1.1 Accept: application/xml Content-type: application/xml <label id="Label_001" />
Chapter 27. Storage Domains
27.1. Storage Domain Elements
The
storagedomains collection provides information about the storage domains in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="storagedomains" link obtained from the entry point URI.
The following table shows specific elements contained in a storage domain resource representation.
Table 27.1. Storage domain elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="permissions" | relationship | A link to the sub-collection for storage domain permissions. | |
link rel="files" | relationship | A link to the files sub-collection for this storage domains. | |
link rel="vms" | relationship | A link to the vms sub-collection for a storage domain with type set to export. | |
link rel="templates" | relationship | A link to the templates sub-collection for a storage domain with type set to export. | |
type | enumerated | The storage domain type. A list of enumerated values are available in capabilities. |
|
master | Boolean: true or false | true if this is the master storage domain of a data center. |
|
host | complex | A reference to the host on which this storage domain should be initialized. The only restriction on this host is that it should have access to the physical storage specified. |
|
storage | complex | Describes the underlying storage of the storage domain. |
|
available | integer | Space available in bytes. |
|
used | integer | Space used in bytes. |
|
committed | integer | Space committed in bytes. |
|
storage_format | enumerated | Describes the storage format version for the storage domain. A list of enumerated values are available in capabilities. |
|
wipe_after_delete | Boolean: true or false | Sets the wipe after delete option by default on the storage domain. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist. | |
warning_low_space_indicator | integer | A percentage value that sets the warning low space indicator option. If the free space available on the storage domain is below this percentage, warning messages are displayed to the user and logged. | |
critical_space_action_blocker | integer | A value in GB that sets the critical space action blocker option. If the free space available on the storage domain is below this value, error messages are displayed to the user and logged, and any new action that consumes space, even temporarily, will be blocked. |
Important
The API as documented in this chapter is experimental and subject to change. It is not covered by the backwards compatibility statement.
27.2. XML Representation of a Storage Domain
Example 27.1. An XML representation of a storage domain
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
<name>data0</name>
<link rel="permissions"
href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
<link rel="files"
href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/files"/>
<type>data</type>
<master>true</master>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/images/0</path>
</storage>
<available>156766306304</available>
<used>433791696896</used>
<committed>617401548800</committed>
<storage_format>v1</storage_format>
<wipe_after_delete>true</wipe_after_delete>
<warning_low_space_indicator>10</warning_low_space_indicator>
<critical_space_action_blocker>5</critical_space_action_blocker>
</storage_domain>
27.3. JSON Representation of a Storage Domain
Example 27.2. A JSON representation of a storage domain
{
"storage_domain" : [ {
"type" : "data",
"master" : "false",
"storage" : {
"address" : "192.0.2.0",
"type" : "nfs",
"path" : "/storage/user/nfs"
},
"available" : 193273528320,
"used" : 17179869184,
"committed" : 0,
"storage_format" : "v3",
"name" : "NFS_01",
"href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba",
"id" : "8827b158-6d2e-442d-a7ee-c6fd4718aaba",
"link" : [ {
"href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/permissions",
"rel" : "permissions"
}, {
"href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/disks",
"rel" : "disks"
}, {
"href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/storageconnections",
"rel" : "storageconnections"
}, {
"href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/disksnapshots",
"rel" : "disksnapshots"
}, {
"href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/diskprofiles",
"rel" : "diskprofiles"
} ]
} ]
}
27.4. Methods
27.4.1. Creating a Storage Domain
Creation of a new storage domain requires the
name, type, host and storage elements. Identify the host element with the id attribute or name element.
In Red Hat Enterprise Virtualization 3.6 and later you can enable the wipe after delete option by default on the storage domain. To configure this specify
<wipe_after_delete> in the POST request. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist.
Example 27.3. Creating a storage domain
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>data1</name>
<type>data</type>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/images/0</path>
</storage>
</storage_domain>
The API user attaches the storage domain to a data center after creation.
27.4.2. Updating a Storage Domain
Only the
name and wipe after delete elements are updatable post-creation. Changing the wipe after delete element will not change the wipe after delete property of disks that already exist.
Example 27.4. Updating a storage domain
PUT /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>data2</name>
...
<wipe_after_delete>true</wipe_after_delete>
...
</storage_domain>
27.5. Storage Types
27.5.1. Storage Types
The
storage element contains a type element, which is an enumerated value found under the capabilities collection.
The storage element also contains additional elements specific to each storage
type. The next few sections examine these additional storage type elements.
27.5.2. NFS Storage
The following table contains
nfs specific elements in a storage description.
Table 27.2. NFS specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
address | string | The host name or IP address of the NFS server. |
|
path | string | The path of NFS mountable directory on the server. |
|
27.5.3. PosixFS Storage
The following table contains
posixfs specific elements in a storage description.
Table 27.3. PosixFS specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
address | string | The host name or IP address of the PosixFS server. |
|
path | string | The path of PosixFS mountable directory on the server. |
|
vfs_type | string | The Linux-supported file system type of the PosixFS share. |
|
mount_options | string | The options for mounting the PosixFS share. |
|
27.5.4. iSCSI and FCP Storage
The following table contains
iscsi and fcp specific elements in a storage description.
Table 27.4. iSCSI and FCP specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
logical_unit id= | complex | The id of the logical unit. A storage domain also accepts multiple iSCSI or FCP logical units. |
|
override_luns | Boolean | Defines whether to replace all logical unit settings with new settings. Set to true to override. |
|
The
logical_unit contains a set of sub-elements.
Table 27.5. Logical unit elements
| Element | Type | Description | Properties |
|---|---|---|---|
address | string | The address of the server containing the storage device. |
|
port | integer | The port number of the server. |
|
target | string | The target IQN for the storage device. |
|
username | string | A CHAP user name for logging into a target. |
|
password | string | A CHAP password for logging into a target. |
|
serial | string | The serial ID for the target. |
|
vendor_id | string | The vendor name for the target. |
|
product_id | string | The product code for the target. |
|
lun_mapping | integer | The Logical Unit Number device mapping for the target. |
|
In the case of iSCSI, if a
logical_unit description also contains details of the iSCSI target with the LUN in question, the target performs an automatic login when the storage domain is created.
27.5.5. LocalFS Storage
The
localfs specific elements in a storage description are:
Table 27.6. Localfs specific elements
| Element | Type | Description | Properties |
|---|---|---|---|
path | string | The path of local storage domain on the host. |
|
A
localfs storage domain requires a data center with storage_type set to localfs. This data center only contains a single host cluster, and the host cluster only contains a single host.
27.6. Export Storage Domains
27.6.1. Export Storage Domains
Storage domains with
type set to export contain vms and templates sub-collections, which list the import candidate VMs and templates stored on that particular storage domain.
Example 27.6. Listing the virtual machines sub-collection of an export storage domain
GET /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<vms>
<vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/
vms/082c794b-771f-452f-83c9-b2b5a19c0399">
<name>vm1</name>
...
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
<actions>
<link rel="import" href="/api/storagedomains/
fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
</actions>
</vm>
</vms>
VMs and templates in these collections have a similar representation to their counterparts in the top-level VMs and templates collection, except they also contain a
storage_domain reference and an import action.
The
import action imports a virtual machine or a template from an export storage domain. The destination cluster and storage domain is specified with cluster and storage_domain references.
Include an optional
name element to give the virtual machine or template a specific name.
Example 27.7. Action to import a virtual machine from an export storage domain
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>Default</name>
</cluster>
</action>
Example 27.8. Action to import a template from an export storage domain
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/templates/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>Default</name>
</cluster>
</action>
Include an optional
clone Boolean element to import the virtual machine as a new entity.
Example 27.9. Action to import a virtual machine as a new entity
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>Default</name>
</cluster>
<clone>true</clone>
<vm>
<name>MyVM</name>
</vm>
...
</action>
Include an optional
disks element to choose which disks to import using individual disk id elements.
Example 27.10. Selecting disks for an import action
POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<cluster>
<name>Default</name>
</cluster>
<vm>
<name>MyVM</name>
</vm>
...
<disks>
<disk id="4825ffda-a997-4e96-ae27-5503f1851d1b"/>
</disks>
</action>
Delete a virtual machine or template from an
export storage domain with a DELETE request.
Example 27.11. Delete virtual machine from an export storage domain
DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/ 082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 Accept: application/xml HTTP/1.1 204 No Content
27.7. Glance Image Storage Domains
27.7.1. Glance Image Storage Domains
Storage domains with type set to
Image represent instances of an OpenStack image service that has been added to the Red Hat Enterprise Virtualization environment as an external provider. These Glance image storage domains contain an images sub-collection with virtual machine images that have been exported to or can be imported from that Glance image storage domain.
Example 27.12. Listing the images sub-collection of a Glance image storage domain
GET /api/storagedomains/00000000-0000-0000-0000-000000000000/images
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<images>
<image href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<actions>
<link href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
00000000-0000-0000-0000-000000000000/import" rel="import"/>
</actions>
<name>RHEL_65_Disk_001</name>
<storage_domain href="/api/storagedomains/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
</image>
<image href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<actions>
<link href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
00000000-0000-0000-0000-000000000000/import" rel="import"/>
</actions>
<name>RHEL_65_Disk_002</name>
<storage_domain href="/api/storagedomains/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
</image>
</images>
The
import action imports a virtual machine image from a Glance image storage domain. The destination storage domain is specified with a storage_domain reference, and the destination cluster with a cluster reference.
Include an optional
name element to give the virtual machine or template a specific name.
Example 27.13. Action to import a virtual machine from a Glance image storage domain
POST /api/storagedomains/00000000-0000-0000-000000000000/images/
00000000-0000-0000-000000000000/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>images0</name>
</cluster>
</action>
You can also import images as templates by specifying the
import_as_template reference:
Example 27.14. Action to import a virtual machine from a Glance image storage domain as a template
POST /api/storagedomains/00000000-0000-0000-000000000000/images/
00000000-0000-0000-000000000000/import HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>images0</name>
</cluster>
</import_as_template>true</import_as_template>
</action>
27.8. Sub-Collections
27.8.1. Files Sub-Collection
The
files sub-collection under each storage domain provides a way for clients to list available files. This sub-collection is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks (VFDs) that an administrator uploads through Red Hat Enterprise Virtualization Manager.
The addition of a CD-ROM device to a VM requires an ISO image from the
files sub-collection of an ISO storage domain.
Example 27.15. Listing the files sub-collection of an ISO storage domain
GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<files>
<file id="en_winxp_pro_with_sp2.iso"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
en_winxp_pro_with_sp2.iso">
<name>en_winxp_pro_with_sp2.iso</name>
<type>iso</type>
<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
</file>
<file id="boot.vfd"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
boot.vfd">
<name>boot.vfd</name>
<type>vfd</type>
<storage_doman id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
</file>
</files>
Like other resources, files have opaque
id and href attributes. The name element contains the filename.
27.9. Actions
27.9.1. Importing an Existing Storage Domain
The API provides a user with the ability to remove an ISO or Export storage domain from one Red Hat Enterprise Virtualization Manager instance without re-formatting the underlying storage and import it into another instance. Importing is achieved similarly to adding a new storage domain, except the
name is not specified.
Example 27.16. Importing an existing export storage domain
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<storage_domain>
<type>export</type>
<storage>
<type>nfs</type>
<address>172.31.0.6</address>
<path>/exports/RHEVX/export-domain</path>
</storage>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</storage_domain>
HTTP/1.1 201 Created
Content-Type: application/xml
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
<name>export1</name>
...
</storage_domain>
27.9.2. Deleting a Storage Domain
A
storage_domain reference is passed in the body of a DELETE request for a storage domain. The storage_domain reference is in the following form:
<storage_domain>
<host id="..."/>
</storage_domain>
OR
<storage_domain>
<host>
<name>...</name>
</host>
</storage_domain>
Format Storage Domain
An API user provides a optional format element to specify whether or not to format the storage domain after deletion.
Example 27.17. Formatting a storage domain after deletion
<storage_domain>
<host id="..."/>
<format>true</format>
</storage_domain>
If no
format element is passed, the storage domain remains unformatted.
Logical Removal of Storage Domain
The API also provides a function for the logical removal of the storage domain. This retains the storage domain's data for import. Use the destroy element to logically remove the storage domain and retain the data.
Example 27.18. Logical removal of a storage domain
<storage_domain>
<host id="..."/>
<destroy>true</destroy>
</storage_domain>
Chapter 28. Storage Connections
28.1. Storage Connection Elements
Table 28.1. Storage Connection Base Elements
| Element | Type | Description | Properties |
|---|---|---|---|
type | One of nfs, posixfs, local, or iscsi | The type of storage domain. |
|
address | string | The hostname or IP address of the storage domain. |
(Only required for NFS and iSCSI)
|
host | string | The id or name of the hypervisor. The host is optional. Providing it will attempt a connection to the storage via the host; not providing it will lead to persisting storage details in the database. |
Table 28.2. Storage Connection File-based Storage Elements
| Element | Type | Description | Properties |
|---|---|---|---|
path | string | The mounted file path of the storage domain. The path cannot be updated to one already used by a storage connection. |
|
mount_options | string | The options for mounting the PosixFS share. | |
vfs_type | string | The Linux-supported file system type of the PosixFS share. |
|
nfs_version | string | The version of NFS used. | |
nfs_timeo | integer | The amount of time, in deciseconds, the NFS client will wait for a request to complete. | |
nfs_retrans | integer | The number of retransmissions the NFS client will attempt to complete a request. |
Table 28.3. Storage Connection iSCSI elements
| Element | Type | Description | Properties |
|---|---|---|---|
port | integer | The TCP port used for the iSCSI storage domain. |
|
target | string | The target IQN for the storage device. |
|
username | string | A CHAP user name for logging into a target. | |
password | string | A CHAP password for logging into a target. |
28.2. XML representation of a Storage Connection Resource
Example 28.1. An XML representation of a storage connection resource
<storage_connections>
<storage_connection href= "/api/storageconnections/608c5b96-9939-4331-96b5-197f28aa2e35" id="608c5b96-9939-4331-96b5-197f28aa2e35">
<address>domain.example.com</address>
<type>nfs</type>
<path>/var/lib/exports/iso</path>
</storage_connection>
<storage_connection href= "/api/storageconnections/2ebb3f78-8c22-4666-8df4-e4bb7fec6b3a" id="2ebb3f78-8c22-4666-8df4-e4bb7fec6b3a">
<address>domain.example.com</address>
<type>posixfs</type>
<path>/export/storagedata/username/data</path>
<vfs_type>nfs</vfs_type>
</storage_connection>
</storage_connections>
28.3. Methods
- 28.3.1. Creating a New Storage Connection
- 28.3.2. Deleting a Storage Connection
- 28.3.3. Updating a Storage Connection
- 28.3.4. Updating an iSCSI Storage Connection
- 28.3.5. Adding New Storage Domain with Existing Storage Connection
- 28.3.6. Attaching an Additional Storage Connection to iSCSI Storage
- 28.3.7. Detaching a Storage Connection from iSCSI Storage
28.3.1. Creating a New Storage Connection
Creating a new storage connection requires a
POST request.
It is possible to create a new storage connection without adding a storage domain. The host
id or name is optional; providing it will attempt a connection to the storage via the host.
Example 28.2. Creating a New Storage Connection
POST /api/storageconnections HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_connection>
<type>nfs</type>
<address>domain.example.com</address>
<path>/export/storagedata/username/data</path>
<host>
<name>Host_Name</name>
</host>
</storage_connection>
28.3.2. Deleting a Storage Connection
Deleting a storage connection requires a
DELETE request. A storage connection can only be deleted if neither storage domain nor LUN disks reference it.
The host
name or id is optional; providing it unmounts the connection from that host.
Example 28.3. Deleting Storage Connection
DELETE /api/storageconnections/Storage_Connection_ID HTTP/1.1 Accept: application/xml Content-type: application/xml <host> <name>Host_Name</name> </host>
28.3.3. Updating a Storage Connection
Updating an existing storage connection requires a
PUT request. The storage domain must be in either maintenance mode or unattached to successfully update the connection.
Providing the host
name or id is optional; if provided, the host attempts a connection to the updated storage details.
Example 28.4. Updating a Storage Connection
PUT /api/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_connection>
<address>updated.example.domain.com</address>
<host>
<name>Host_name</name>
</host>
</storage_connection>
28.3.4. Updating an iSCSI Storage Connection
Updating an existing iSCSI storage connection requires a
PUT request. An iSCSI storage domain must be in maintenance mode or unattached to successfully update the connection.
Example 28.5. Updating a Storage Connection
PUT /api/storageconnections/Storage_Connection_ID HTTP/1.1 Accept: application/xml Content-type: application/xml <storage_connection> <port>3456</port> </storage_connection>
28.3.5. Adding New Storage Domain with Existing Storage Connection
Adding a new storage domain with existing storage connection requires a
POST request. This is only applicable with file-based storage domains: NFS, POSIX, and local.
Example 28.6. Adding a New Storage Domain with Existing Storage Connection
POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
<storage_domain>
<name>New_Domain</name>
<type>data</type>
<storage id="Storage_Connection_ID"/>
<host>
<name>Host_Name</name>
</host>
</storage_domain>
28.3.6. Attaching an Additional Storage Connection to iSCSI Storage
Attaching an additional storage connection to an iSCSI storage domain requires a
POST request.
Example 28.7. Attaching an Additional Storage Connection to iSCSI Storage
POST /api/storagedomains/iSCSI_Domain_ID/storageconnections HTTP/1.1 Accept: application/xml Content-type: application/xml <storage_connection id="Storage_Connection_ID"> </storage_connection>
28.3.7. Detaching a Storage Connection from iSCSI Storage
Detaching a storage connection from an iSCSI storage domain requires a
DELETE request.
Example 28.8. Detaching a Storage Connection from iSCSI Storage
DELETE /api/storagedomains/iSCSI_Domain_ID/storageconnections/Storage_Connection_ID HTTP/1.1 Accept: application/xml Content-type: application/xml
Chapter 29. Hosts
29.1. Host Elements
The
hosts collection provides information about the hosts in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="hosts" link obtained from the entry point URI.
The following table shows specific elements contained in a host resource representation.
Table 29.1. Host elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="storage" | relationship | A link to the storage sub-collection for host storage. |
|
link rel="nics" | relationship | A link to the nics sub-collection for host network interfaces. | |
link rel="tags" | relationship | A link to the tags sub-collection for host tags. | |
link rel="permissions" | relationship | A link to the permissions sub-collection for host permissions. | |
link rel="statistics" | relationship | A link to the statistics sub-collection for host statistics. |
|
link rel="hooks" | relationship | A link to the hooks sub-collection for host hooks. | |
name | string | The unique identifier for the host. | |
root_password | string | The root password of this host, by convention only included in the client-provided host representation on creation. |
|
comment | string | Any comments regarding the host. | |
address | string | The IP address or hostname of the host. |
|
certificate | complex | A reference to the host certificate details, including organization and subject. |
|
status | See below | The host status. |
|
cluster id= | GUID | A reference to the cluster that includes this host. | |
port | integer | The listen port of the VDSM daemon running on this host. |
|
type | One of rhel or rhev-h | The host type. |
|
storage_manager priority= | Boolean: true or false | Specifies whether the host is a storage manager. |
|
version major= minor= build= revision= full_version= | complex | The compatibility level of the host. |
|
hardware_information | complex | Information regarding the hardware of the host, including manufacturer, version, serial_number, product_name, uuid, and family. | |
power_management type= | complex | Configuration options for host power management, including enabled, options, kdump_detection, automatic_pm_enabled, and agents. See Section 29.4, “Power Management Elements” for more information on the host power management options. | |
ksm | Boolean: true or false | true if Kernel SamePage Merging (KSM) is enabled. | |
transparent_hugepages | Boolean: true or false | true if Transparent Hugepages is enabled. | |
iscsi | complex | The SCSI initiator for the host. |
|
ssh | complex | Details regarding the SSH connection with the host, including port and fingerprint. | |
cpu | complex | Statistics for the host CPU. Includes sub-elements for the CPU's name, topology cores=, topology sockets=, topology threads= and speed. The topology cores= aggregates the total cores while the topology sockets= aggregates the total physical CPUs. The total cores available to virtual machines equals the number of sockets multiplied by the cores per socket. |
|
memory | integer | The total amount of host memory in bytes. |
|
max_scheduling_memory | integer | The maximum amount of memory that can be used in scheduling in bytes. |
|
summary | complex | Summary statistics of the virtual machines on the host. Includes sub-elements for numbers of active, migrating and total VMs. |
|
os type= | complex | Details regarding the operating system installed on the host, including version full_version=. |
|
libvirt_version major= minor= build= revision= full_version= | complex | The libvirt compatibility level of the host. |
|
The
status contains one of the following enumerative values: down, error, initializing, installing, install_failed, maintenance, non_operational, non_responsive, pending_approval, preparing_for_maintenance, connecting, reboot, unassigned and up. These states are listed in host_states under capabilities.
29.2. XML Representation of a Host
Example 29.1. An XML representation of a host
<host id="00000000-0000-0000-0000-000000000000"
href="/api/hosts/00000000-0000-0000-0000-000000000000">
<actions>
<link rel="install"
href="/api/hosts/00000000-0000-0000-0000-000000000000/install"/>
<link rel="forceselectspm"
href="/api/hosts/00000000-0000-0000-0000-000000000000/forceselectspm"/>
<link rel="activate"
href="/api/hosts/00000000-0000-0000-0000-000000000000/activate"/>
<link rel="fence"
href="/api/hosts/00000000-0000-0000-0000-000000000000/fence"/>
<link rel="deactivate"
href="/api/hosts/00000000-0000-0000-0000-000000000000/deactivate"/>
<link rel="approve"
href="/api/hosts/00000000-0000-0000-0000-000000000000/approve"/>
<link rel="iscsilogin"
href="/api/hosts/00000000-0000-0000-0000-000000000000/iscsilogin"/>
<link rel="iscsidiscover"
href="/api/hosts/00000000-0000-0000-0000-000000000000/iscsidiscover"/>
<link rel="commitnetconfig"
href="/api/hosts/00000000-0000-0000-0000-000000000000/commitnetconfig"/>
</actions>
<name>host1</name>
<link rel="storage"
href="/api/hosts/00000000-0000-0000-0000-000000000000/storage"/>
<link rel="nics"
href="/api/hosts/00000000-0000-0000-0000-000000000000/nics"/>
<link rel="tags"
href="/api/hosts/00000000-0000-0000-0000-000000000000/tags"/>
<link rel="permissions"
href="/api/hosts/00000000-0000-0000-0000-000000000000/permissions"/>
<link rel="statistics"
href="/api/hosts/00000000-0000-0000-0000-000000000000/statistics"/>
<link rel="hooks"
href="/api/hosts/00000000-0000-0000-0000-000000000000/hooks"/>
<address>host1.example.com</address>
<certificate>
<organization>exampleorg</organization>
<subject>O=exampleorg,CN=XX.XX.XX.XX</subject>
</certificate>
<status>
<state>up</state>
</status>
<cluster href="/api/clusters/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
<port>54321</port>
<type>rhel</type>
<storage_manager priority="2">true</storage_manager>
<version major="4" minor="10" build="2" revision="0" full_version="vdsm-4.10.2-1.13.el6ev"/>
<power_management type="apc">
<enabled>false</enabled>
<options>
<option name="secure" value="false"/>
<options>
<automatic_pm_enabled>true</automatic_pm_enabled>
<kdump_detection>true</kdump_detection>
</power_management>
<ksm>
<enabled>true</enabled>
</ksm>
<transparent_hugepages>
<enabled>true</enabled>
</transparent_hugepages>
<iscsi>
<initiator>iqn.2001-04.com.example:diskarrays-sn-a8675309</initiator>
</iscsi>
<ssh>
<port>22</port>
<fingerprint>00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00</fingerprint>
</ssh>
<cpu>
<topology cores="2" sockets="1"/>
<name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
<speed>2993</speed>
</cpu>
<summary>
<active>2</active>
<migrating>0</migrating>
<total>3</total>
</summary>
<os type="RHEL">
<version full_version="6Server-6.5.0.1.el6"/>
</os>
<libvirt_version major="0" minor="10" build="2" revision="0" full_version="libvirt-0.10.2-15.el6"/>
</host>
29.3. JSON Representation of a Host
Example 29.2. A JSON representation of a host
{
"host" : [ {
"address" : "198.51.100.0",
"certificate" : {
"organization" : "example.com",
"subject" : "O=example.com,CN=192.0.2.0"
},
"status" : {
"state" : "up"
},
"cluster" : {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb",
"id" : "00000001-0001-0001-0001-0000000002fb"
},
"port" : "54321",
"type" : "rhel",
"storage_manager" : {
"value" : "true",
"priority" : "5"
},
"spm" : {
"priority" : "5"
},
"version" : {
"major" : "4",
"minor" : "16",
"build" : "8",
"revision" : "1",
"full_version" : "vdsm-4.16.8.1-6.el6ev"
},
"hardware_information" : {
"manufacturer" : "System Manufacturer To Be Filled By O.E.M.",
"version" : "System Version To Be Filled By O.E.M.",
"serial_number" : "Serial Number To Be Filled By O.E.M.",
"product_name" : "Product Name To Be Filled By O.E.M.",
"uuid" : "9fa0a1a2-a3a4-a5a6-a7a8-a9aaabacadae",
"family" : "Family To Be Filled By O.E.M.",
"supported_rng_sources" : {
"source" : [ "RANDOM" ]
}
},
"power_management" : {
"enabled" : "false",
"options" : {
"option" : [ {
"name" : "secure",
"value" : "false"
} ]
},
"automatic_pm_enabled" : "true",
"kdump_detection" : "true",
"type" : "apc"
},
"ksm" : {
"enabled" : "false"
},
"transparent_hugepages" : {
"enabled" : "true"
},
"iscsi" : {
"initiator" : "iqn.1994-05.com.example:795610ff2632"
},
"ssh" : {
"port" : "22",
"fingerprint" : "77:27:38:25:8f:60:8d:93:9c:2c:b0:cb:5e:19:f4:53"
},
"cpu" : {
"topology" : {
"sockets" : "1",
"cores" : "4",
"threads" : "1"
},
"name" : "Intel(R) Core(TM)2 Quad CPU Q9550 @ 2.83GHz",
"speed" : 2833
},
"memory" : 2989490176,
"max_scheduling_memory" : 2584739840,
"summary" : {
"active" : "0",
"migrating" : "0",
"total" : "0"
},
"protocol" : "stomp",
"os" : {
"version" : {
"full_version" : "6Server - 6.6.0.2.el6"
},
"type" : "RHEL"
},
"libvirt_version" : {
"major" : "0",
"minor" : "10",
"build" : "2",
"revision" : "0",
"full_version" : "libvirt-0.10.2-46.el6_6.2"
},
"kdump_status" : "disabled",
"selinux" : {
"mode" : "enforcing"
},
"auto_numa_status" : "unknown",
"numa_supported" : "false",
"live_snapshot_support" : "true",
"actions" : {
"link" : [ {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/fence",
"rel" : "fence"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/approve",
"rel" : "approve"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/forceselectspm",
"rel" : "forceselectspm"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/iscsilogin",
"rel" : "iscsilogin"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/iscsidiscover",
"rel" : "iscsidiscover"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/commitnetconfig",
"rel" : "commitnetconfig"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/deactivate",
"rel" : "deactivate"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/install",
"rel" : "install"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/activate",
"rel" : "activate"
} ]
},
"name" : "Host-07",
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe",
"id" : "ea7aa772-d2af-4a5c-9350-d86f005c93fe",
"link" : [ {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/storage",
"rel" : "storage"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/nics",
"rel" : "nics"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/numanodes",
"rel" : "numanodes"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/tags",
"rel" : "tags"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/permissions",
"rel" : "permissions"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/statistics",
"rel" : "statistics"
}, {
"href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/hooks",
"rel" : "hooks"
} ]
} ]
}
29.4. Power Management Elements
The
power_management element provides users with the ability to set a power management configuration, which is required for host fencing. Certain sub-elements are required when configuring power_management.
Table 29.2. Power management options
| Element | Type | Description | Properties |
|---|---|---|---|
type= | fencing device code | A list of valid fencing device codes are available in the capabilities collection. |
|
enabled | Boolean: true or false | Indicates whether power management configuration is enabled or disabled. |
|
address | string | The host name or IP address of the host. |
|
username | string | A valid user name for power management. | |
password | string | A valid, robust password for power management. | |
options | complex | Fencing options for the selected type= specified with the option name="" and value="" strings. | |
agents | complex | Specifies fence agent options when multiple fences are used. Use the order sub-element to prioritize the fence agents. Agents are run sequentially according to their order until the fence action succeeds. When two or more fence agents have the same order, they are run concurrently. Other sub-elements include type, ip, user, password, and options. | |
automatic_pm_enabled | Boolean: true or false | Toggles the automated power control of the host in order to save energy. When set to true, the host will be automatically powered down if the cluster's load is low, and powered on again when required. This is set to true when a host is created, unless disabled by the user. | |
kdump_detection | Boolean: true or false | Toggles whether to determine if kdump is running on the host before it is shut down. When set to true, the host will not shut down during a kdump process. This is set to true when a host has power management enabled, unless disabled by the user. |
The
options element requires a list of option sub-elements. Each option requires a name and type attributes. Certain options are only available for specific fencing types as defined in the capabilities collection.
A new host includes an optional
power_management configuration when POSTing to the host resource. The power_management configuration is updatable using a PUT request.
Example 29.3. An XML representation of a host's power management configuration
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
<name>host1</name>
...
<power_management type="ilo">
<enabled>true</enabled>
<address>192.168.1.107</address>
<username>admin</username>
<password>p@55w0Rd!</password>
<options>
<option name="secure" value="true"/>
<option name="port" value="54345"/>
<option name="slot" value="3"/>
</options>
<agents>
<agent id="07f0b9ce-923a-4a96-a532-3c898fa8b6da">
<type>apc</type>
<order>1</order>
<ip>192.168.1.111</ip>
<user>example</user>
<password>p@55w0rd!</password>
<port>9</port>
<options>
<option name="power_wait" value="5"/>
<option name="secure" value="false"/>
</options>
</agent>
<agent id="50c71ba2-8495-11e0-b931-e20e458819ed">
<type>rsa</type>
<order>2</order>
<ip>192.168.1.112</ip>
<user>example</user>
<password>p@55w0rd!</password>
<port>9</port>
<options>
<option name="power_wait" value="5"/>
<option name="secure" value="false"/>
</options>
</agent>
</agents>
<automatic_pm_enabled>true</automatic_pm_enabled>
<kdump_detection>true</kdump_detection>
</power_management>
...
</host>
29.5. Memory Management Elements
The API provides two configuration settings for a host's memory management.
Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference. This helps with optimization for memory density. KSM uses the
ksm element.
Example 29.4. Setting KSM memory management
PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
<ksm>true</ksm>
</host>
Transparent Hugepage support expands the size of memory pages beyond the standard 4kB limit. This reduces memory consumption and increases host performance. Transparent Hugepage support uses the
transparent_hugepages element.
Example 29.5. Setting Transparent Hugepage memory management
PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
<transparent_hugepages>true</transparent_hugepages>
</host>
Availability of Transparent Hugepage support is found in the
capabilities collection.
29.6. Methods
29.6.1. Creating a Host
Creation of a new host requires the
name, address and root_password elements.
Example 29.6. Creating a host
POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host>
<name>host2</name>
<address>host2.example.com</address>
<root_password>p@55w0Rd!</root_password>
</host>
New host creation applies only to the addition of Red Hat Enterprise Linux hosts. Red Hat Enterprise Virtualization Manager detects hypervisor hosts automatically and requires approval for their use.
The
root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent requests.
29.6.2. Updating a Host
The
name, description, cluster, power_management, transparent_hugepages and ksm elements are updatable post-creation.
Example 29.7. Updating a host
POST /api/hosts/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host>
<name>host3</name>
</host>
29.7. Sub-Collections
29.7.1. Host Network Interface Sub-Collection
29.7.1.1. Host Network Interface Sub-Collection
The
nics sub-collection represents a host's physical network interfaces. Each host_nic element in the representation acts as a network interface and contains the following elements:
Table 29.3. Elements for a host's network interfaces
| Element | Type | Description | Properties |
|---|---|---|---|
name | string | The name of the host network interface, e.g. eth0. |
[a]
|
link rel="statistics" | relationship | A link to the statistics sub-collection for a host's network interface statistics. |
|
link rel="labels" | relationship | A link to the labels sub-collection for a host's network interface labels. | |
link rel="master" | relationship | A reference to the master bonded interface, if this is a slave interface. |
|
host id= | GUID | A reference to the host. |
|
network id= | GUID | A reference to the network, if any, that the interface is attached. |
[b] |
mac address= | string | The MAC address of the interface. |
|
ip address= netmask= gateway= mtu= | complex | The IP level configuration of the interface. | |
mtu | complex | The maximum transmission unit for the interface. | |
boot_protocol | enumerated | The protocol for IP address assignment when the host is booting. A list of enumerated values is available in capabilities. | |
status | enumerated | The link status for the network interface. These states are listed in host_nic_states under capabilities. |
|
vlan id | integer | The VLAN which this interface represents. |
|
bonding | complex | A list of options and slave NICs for bonded interfaces. |
[c]
|
bridged | Boolean | Defines the bridged network status. Set to true for a bridged network and false for a bridgeless network. | |
properties | complex | Defines custom property keys for bridge options of the network. Each property contains name and value sub-elements. | |
[a]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[b]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[c]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
| |||
Example 29.9. An XML representation of a network interface on a host
<host_nic id="00000000-0000-0000-0000-000000000000"
href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000">
<actions>
<link rel="attach"
href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000/attach"/>
<link rel="detach"
href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000/detach"/>
</actions>
<name>bond0</name>
<link rel="labels"
href= "/api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000/labels"/>
<link rel="statistics"
href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000/statistics"/>
<host id="00000000-0000-0000-0000-000000000000"
href="/api/hosts/00000000-0000-0000-0000-000000000000"/>
<network id="00000000-0000-0000-0000-000000000000"
href="/api/networks/00000000-0000-0000-0000-000000000000"/>
<mac address="00:00:00:00:00:00"/>
<ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
<boot_protocol>dhcp</boot_protocol>
<status>
<state>up</state>
</status>
<bonding>
<options>
...
</options>
<slaves>
<host_nic id="00000000-0000-0000-0000-000000000000"/>
<host_nic id="00000000-0000-0000-0000-000000000000"/>
</slaves>
</bonding>
<mtu>1500</mtu>
<bridged>true</bridged>
<custom_configuration>false</custom_configuration>
<properties>
<property>
<name>bridge_opts</name>
<value>
forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
</value>
</property>
</properties>
</host_nic>
In the REST API, you can only create bonded interfaces. All other network interfaces contain updatable
network, ip and boot_protocol elements using a PUT request.
When adding a new network interface, the
name and network elements are required. Identify the network element with the id attribute or name element.
POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host_nic>
<name>MyNIC</name>
<network id="00000000-0000-0000-0000-000000000000">
<name>MyNetwork</name>
</network>
</host_nic>
In the REST API, you can modify a network interface with a
PUT request.
PUT /api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<host_nic>
<ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
</host_nic>
In the REST API, you can remove a network interface with a
DELETE request.
DELETE /api/hosts/00000000-0000-0000-0000-000000000000/nics/ 00000000-0000-0000-0000-000000000000 HTTP/1.1 HTTP/1.1 204 No Content
29.7.1.2. Bonded Interfaces
A bonded interface is represented as a
host_nic resource containing a bonding element.
Table 29.4. Bonded interface properties
| Element | Type | Description | Properties |
|---|---|---|---|
options | complex | A list of option elements for a bonded interface. Each option contains property name and value attributes. |
[a]
|
slaves | complex | A list of slave host_nic id= elements for a bonded interface. |
[b]
|
[a]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
[b]
Only required when adding bonded interfaces. Other interfaces are read-only and cannot be added.
| |||
An API user creates a new bond when creating a new
host_nic (POST) or updating a host_nic (PUT). Use either the id or name elements identify the slave host_nic elements.
Example 29.10. Creating a bonded interface
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<host_nic>
<name>bond4</name>
<network id="e657d631-657d-42bb-a536-73501a085d85"/>
<bonding>
<options>
...
</options>
<slaves>
<host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
<host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
</slaves>
</bonding>
</host_nic>
Important
bond0, bond1, bond2, bond3 and bond4 are the only valid names for a bonded interface.
Use a
DELETE request to a bonded interface URI to delete it.
Important
Changes to bonded interface configuration must be explicitly committed.
29.7.1.3. Network Interface Custom Properties
Custom properties can be applied to host network interfaces. Each property contains
name and value sub-elements. To amend the custom properties of a network interface, perform a POST request with the setupnetworks action.
Table 29.5. Elements for custom bridge options for a host's network interface
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the property. Bridge options have the set name of bridge_opts. |
value | string | The bridge options, represented by a valid key and value with the following syntax: [key]=[value]. Separate multiple entries with a whitespace character. The following keys are valid, with the values provided as examples:
|
Example 29.11. An XML representation of a host's network interface properties sub-collection
<host_nic>
...
<properties>
<property>
<name>bridge_opts</name>
<value>
forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
</value>
</property>
</properties>
...
</host_nic>
29.7.1.4. Network Interface Statistics
Each host's network interface exposes a
statistics sub-collection for a host's network interface statistics. Each statistic contains the following elements:
Table 29.6. Elements for a host's network interface statistics
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the statistic entry. |
description | string | A plain text description of the statistic. |
unit | string | The unit or rate to measure the statistical values. |
type | One of GAUGE or COUNTER | The type of statistic measures. |
values type= | One of INTEGER or DECIMAL | The data type for the statistical values that follow. |
value | complex | A data set that contains datum. |
datum | see values type | An individual piece of data from a value. |
host_nic id= | relationship | A relationship to the containing host_nic resource. |
The following table lists the statistic types for network interfaces on hosts.
Table 29.7. Host NIC statistic types
|
Name
|
Description
|
|---|---|
data.current.rx |
The rate in bytes per second of data received.
|
data.current.tx |
The rate in bytes per second of data transmitted.
|
errors.total.rx |
Total errors from receiving data.
|
errors.total.tx |
Total errors from transmitting data.
|
Example 29.12. An XML representation of a host's network interface statistics sub-collection
<statistics>
<statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
c34728e8-4338-4540-ac9b-86b8582e602e/statistics/
ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
<name>data.current.rx</name>
<description>Receive data rate</description>
<values type="DECIMAL">
<value>
<datum>0</datum>
</value>
</values>
<type>GAUGE</type>
<unit>BYTES_PER_SECOND</unit>
<host_nic id="c34728e8-4338-4540-ac9b-86b8582e602e"
href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
c34728e8-4338-4540-ac9b-86b8582e602e"/>
</statistic>
...
</statistics>
Note
This
statistics sub-collection is read-only.
29.7.1.5. Actions
29.7.1.5.1. Attach Network Interface Card to Host Action
A host network interface card is attached to a network, indicating the given network is accessible over that network interface card. Either the
id or name elements identify the network to which the network interface card will be attached.
Example 29.13. Action to attach a host network interface card to a network
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>Important
This networking configuration change must be explicitly committed.
29.7.1.5.2. Detach Network Interface Card from Host Action
Detach a network interface card from a network. Either the
id or name elements identify the network from which the network interface card will be detached.
Example 29.14. Action to detach a host network interface card from a network
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>Important
This networking configuration change must be explicitly committed.
29.7.1.5.3. Multiple Network Setup Action
A host's
nics collection contains an action to perform setup of multiple network interfaces. Perform a POST request on the setupnetworks action.
Example 29.15. Action to setup multiple host network interfaces
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/setupnetworks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<host_nics>
<host_nic id="41561e1c-c653-4b45-b9c9-126630e8e3b9">
<name>em1</name>
<network id="00000000-0000-0000-0000-000000000009"/>
<boot_protocol>dhcp</boot_protocol>
</host_nic<
<host_nic id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
<name>em2</name>
<network id="00000000-0000-0000-0000-000000000010"/>
<ip address="10.35.1.247" netmask="255.255.254.0"
gateway="10.35.1.254"/>
<boot_protocol>static</boot_protocol>
</host_nic>
<checkConnectivity>true</checkConnectivity>
<connectivityTimeout>60</connectivityTimeout>
<force>false</false>
</host_nics>
</action>
This action updates all specified network interface resources with standard NIC elements. The request includes additional elements specified in the following table.
Table 29.8. Additional elements for multiple host network interface setup
| Element | Type | Description |
|---|---|---|
checkConnectivity | Boolean | Set to true to verify connectivity between the host and the Red Hat Enterprise Virtualization Manager. If the connectivity is lost, Red Hat Enterprise Virtualization Manager reverts the settings. |
connectivityTimeout | integer | Defines the timeout for loss of connectivity. |
force | Boolean | Set to true to force changes even if connectivity is lost. |
29.7.1.5.4. Attach Label to Network Interface Card Action
You can attach labels to the network interface card of a host to automate the association of that network interface card with logical networks to which the same label has been attached.
Example 29.16. Action to attach a label to a network interface card
POST /api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels HTTP/1.1 Accept: application/xml Content-type: application/xml <label id="Label_001" />
29.7.1.5.5. Removing a Label From a Network Interface Card
Removal of a label from a physical host network interface card requires a
DELETE request.
Example 29.17. Removing a label from a network interface card
DELETE /api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels/[label_id] HTTP/1.1 HTTP/1.1 204 No Content
29.7.2. Storage Sub-Collection
29.7.2.1. Storage Sub-Collection
The
storage sub-collection provides a list of the iSCSI and FCP storage representations available on the host. This storage is used to create storage domains.
Each
storage representation in the sub-collection represents a SCSI LUN.
Example 29.18. An XML representation of the storage sub-collection on a host
<host_storage>
<storage id="82fb123b-321e-40a1-9889-95dcd2654463"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage/
82fb123b-321e-40a1-9889-95dcd2654463">
<name>LUN0</name>
<type>iscsi</type>
<logical_unit id="LUN0">
<address>mysan.example.com</address>
<target>iqn.2009-08.com.example:mysan.foobar</target>
</logical_unit>
</storage>
</host_storage>
Note
The
host_storage collection is read-only.
Important
The API as documented in this section is experimental and subject to change. It is not covered by the backwards compatibility statement.
29.7.3. Host NUMA Nodes Sub-Collection
29.7.3.1. NUMA Nodes Sub-Collection
The
numanodes sub-collection represents the host's NUMA topology. Each host_numa_node element in the sub-collection represents a NUMA node.
Example 29.19. An XML representation of the numanodes sub-collection on a host
<host_numa_nodes>
<host_numa_node href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-699e-460b-9a70-285f651e7d68" id="91d8537c-699e-460b-9a70-285f651e7d68">
<link href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-699e-460b-9a70-285f651e7d68/statistics" rel="statistics"/>
<host href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2" id="f6735fa9-4ee5-47ce-b750-a87863736cc2"/>
<index>0</index>
<memory>8157</memory>
<cpu>
<cores>
<core index="0"/>
<core index="2"/>
<core index="4"/>
<core index="6"/>
</cores>
</cpu>
<node_distance>10 16</node_distance>
</host_numa_node>
<host_numa_node href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/4b18926e-6faf-43f5-9fc2-0503f1531562" id="4b18926e-6faf-43f5-9fc2-0503f1531562">
<link href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/4b18926e-6faf-43f5-9fc2-0503f1531562/statistics" rel="statistics"/>
<host href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2" id="f6735fa9-4ee5-47ce-b750-a87863736cc2"/>
<index>2</index>
<memory>8175</memory>
<cpu>
<cores>
<core index="1"/>
<core index="3"/>
<core index="5"/>
<core index="7"/>
</cores>
</cpu>
<node_distance>16 10</node_distance>
</host_numa_node>
</host_numa_nodes>Note
The
host_numa_nodes sub-collection is read-only.
29.7.3.2. NUMA Node Statistics
Each host NUMA node exposes a
statistics sub-collection for NUMA node statistics. Each statistic contains the following elements:
Table 29.9. Elements for a host's NUMA node statistics
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the statistic entry. |
description | string | A plain text description of the statistic. |
unit | string | The unit or rate to measure the statistical values. |
type | One of GAUGE or COUNTER | The type of statistic measures. |
values type= | One of INTEGER or DECIMAL | The data type for the statistical values that follow. |
value | complex | A data set that contains datum. |
datum | see values type | An individual piece of data from a value. |
host_numa_node id= | relationship | A relationship to the containing numanode resource. |
The following table lists the statistic types for host NUMA nodes.
Table 29.10. Host NUMA node statistics
| Name | Description |
|---|---|
memory.total | Total memory in bytes on the NUMA node. |
memory.used | Memory in bytes used on the NUMA node. |
memory.free | Memory in bytes free on the NUMA node. |
cpu.current.user | Percentage of CPU usage for users. |
cpu.current.system | Percentage of CPU usage for the system. |
cpu.current.idle | Percentage of idle CPU usage. |
Example 29.20. An XML representation of the host NUMA node's statistics sub-collection
<statistics>
<statistic href="/api/hosts/f6745fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-689e-460b-9a70-285f651e7d68/statistics/7816602b-c05c-3dc7-a4da-3769f7ad8896" id="7816602b-c05c-3dc7-a4da-3769f7ad8896">
<name>memory.total</name>
<description>Total memory</description>
<values type="INTEGER">
<value>
<datum>8157</datum>
</value>
</values>
<type>GAUGE</type>
<unit>BYTES</unit>
<host_numa_node href="/api/hosts/f6745fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-689e-460b-9a70-285f651e7d68" id="91d8537c-689e-460b-9a70-285f651e7d68"/>
</statistic>
...
</statistics>Note
A host NUMA node's
statistics sub-collection is read-only.
29.7.4. Host Statistics Sub-Collection
29.7.4.1. Host Statistics Sub-Collection
Each host resource exposes a
statistics sub-collection for host-specific statistics. Each statistic contains the following elements:
Table 29.11. Elements for host statistics
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the statistic entry. |
description | string | A plain text description of the statistic. |
unit | string | The unit or rate to measure the statistical values. |
type | One of GAUGE or COUNTER | The type of statistic measures. |
values type= | One of INTEGER or DECIMAL | The data type for the statistical values that follow. |
value | complex | A data set that contains datum. |
datum | see values type | An individual piece of data from a value. |
host id= | relationship | A relationship to the containing host resource. |
The following table lists the statistic types for hosts.
Table 29.12. Host statistic types
|
Name
|
Description
|
|---|---|
memory.total |
Total memory in bytes on the host.
|
memory.used |
Memory in bytes used on the host.
|
memory.free |
Memory in bytes free on the host.
|
memory.shared |
Memory in bytes shared on the host.
|
memory.buffers |
I/O buffers in bytes.
|
memory.cached |
OS caches in bytes.
|
swap.total |
Total swap memory in bytes on the host.
|
swap.free |
Swap memory in bytes free on the host.
|
swap.used |
Swap memory in bytes used on the host.
|
swap.cached |
Swap memory in bytes also cached in host's memory.
|
ksm.cpu.current |
Percentage of CPU usage for Kernel SamePage Merging.
|
cpu.current.user |
Percentage of CPU usage for users.
|
cpu.current.system |
Percentage of CPU usage for system.
|
cpu.current.idle |
Percentage of idle CPU usage.
|
cpu.load.avg.5m |
CPU load average per five minutes.
|
Example 29.21. An XML representation of the host's statistics sub-collection
<statistics>
<statistic id="4ae97794-f56d-3f05-a9e7-8798887cd1ac"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/
statistics/4ae97794-f56d-3f05-a9e7-8798887cd1ac">
<name>memory.total</name>
<description>Total memory</description>
<unit>BYTES</unit>
<type>GUAGE</type>
<values type="INTEGER">
<value>
<datum>3983540224<datum>
</value>
</values>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</statistic>
...
</statistics>
Note
A host's
statistics sub-collection is read-only.
29.8. Actions
29.8.1. Install VDSM Action
Install VDSM and related software on the host. The host type defines additional parameters for the action.
- Red Hat Enterprise Linux host - This host type requires a
root_passwordelement that refers to the password for the host'srootuser. - Red Hat Enterprise Virtualization Hypervisor host - This host type requires an
imageelement that refers to an ISO file stored on the Red Hat Enterprise Virtualization Manager server.
Example 29.22. Action to install VDSM to a Red Hat Enterprise Linux host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<root_password>p@55w0Rd!</root_password>
</action>
Example 29.23. Action to install VDSM to a Red Hat Enterprise Virtualization Hypervisor host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<image>/usr/share/rhev-hypervisor/rhev-hypervisor.iso</image>
</action>
29.8.2. Activate Host Action
Activate the host for use, such as running virtual machines.
Example 29.24. Action to activate a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
29.8.3. Fence Host Action
An API user controls a host's power management device with the
fence action. The capabilities lists available fence_type options.
Example 29.25. Action to fence a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/fence
Accept: application/xml
Content-Type: application/xml
<action>
<fence_type>start</fence_type>
</action>
29.8.4. Deactivate Host Action
Deactivate the host to perform maintenance tasks.
Example 29.26. Action to deactivate a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/deactivate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
29.8.5. Approve Host Action
Approve a pre-installed Red Hat Enterprise Virtualization Hypervisor host for usage in the virtualization environment. This action also accepts an optional
cluster element to define the target cluster for this host.
Example 29.27. Action to approve a host
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/approve HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
</action>
29.8.6. Host iSCSI Login Action
The
iscsilogin action enables a host to login to an iSCSI target. Logging into a target makes the contained LUNs available in the host_storage collection.
Example 29.28. Action to enable a host to login to iSCSI target
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsilogin HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<iscsi>
<address>mysan.example.com</address>
<target>iqn.2009-08.com.example:mysan.foobar</target>
<username>jimmy</username>
<password>s3kr37</password>
</iscsi>
</action>
29.8.7. Host iSCSI Discover Action
The
iscsidiscover action enables an iSCSI portal to be queried for its list of targets.
Example 29.29. Action to query a list of targets for iSCSI portal
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<action>
<iscsi>
<address>mysan.example.com</address>
<port>3260</port>
</iscsi>
</action>
29.8.8. Commit Host Network Configuration Action
An API user commits the network configuration to persist a host network interface attachment or detachment, or persist the creation and deletion of a bonded interface.
Example 29.30. Action to commit network configuration
POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/commitnetconfig HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Important
Networking configuration is only committed after the Manager has established that host connectivity is not lost as a result of the configuration changes. If host connectivity is lost, the host requires a reboot and automatically reverts to the previous networking configuration.
Chapter 30. Virtual Machines
30.1. Virtual Machine Elements
The
vms collection provides information about virtual machines in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="vms" link obtained from the entry point URI.
The following table shows specific elements contained in a virtual machine resource representation.
Table 30.1. Virtual machine elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="applications" | relationship | A link to the applications sub-collection for virtual machine resources, which shows the applications installed on the virtual machine. | |
link rel="disks" | relationship | A link to the disks sub-collection for virtual machine resources. | |
link rel="nics" | relationship | A link to the nics sub-collection for virtual machine resources. | |
link rel="numanodes" | relationship | A link to the numanodes sub-collection for virtual machine resources. | |
link rel="cdroms" | relationship | A link to the cdroms sub-collection for virtual machine resources. | |
link rel="snapshots" | relationship | A link to the snapshots sub-collection for virtual machine resources. | |
link rel="tags" | relationship | A link to the tags sub-collection for virtual machine resources. | |
link rel="permissions" | relationship | A link to the permissions sub-collection for virtual machine permissions. | |
link rel="statistics" | relationship | A link to the statistics sub-collection for virtual machine resources. |
|
link rel="reporteddevices" |
relationship
|
A link to the
reporteddevices sub-collection for virtual machine resources.
| |
link rel="watchdogs" |
relationship
|
A link to the
watchdogs sub-collection for virtual machine resources.
| |
link rel="sessions" |
relationship
|
A link to the
sessions sub-collection for virtual machine resources.
| |
type | enumerated | The virtual machine type. A list of enumerated values are available in capabilities. |
|
status | See below | The virtual machine status. |
|
memory | integer | The amount of memory allocated to the guest in bytes. | |
cpu | complex |
Defines CPU details for the virtual machine. The
topology sub-element sets number of logical sockets available to the guest and the number of cores per socket. The total cores available to the virtual machine equals the number of sockets multiplied by the cores per socket.
The
cputune sub-element maps virtual CPUs to physical host CPUs using a series of vcpupin elements. Each vcpupin elements contains a virtual CPU attribute (vcpu) and an attribute to define which physical to use (cpuset). Set the cpuset to either a single CPU (cpuset="0"), multiple CPUs (cpuset="0,2"), a CPU range (cpuset="0-3") or a CPU range with exclusion (cpuset="0-3,^2").
The
cpu_mode sub-element defines how closely the virtual CPU relates to the host CPU. It has three values: custom is the default if no mode is given, host_model copies the host CPU as best as libvirt can understand, and host_passthrough passes all aspects of the host to the guest, even those that libvirt does not recognize. However, host_passthrough will prevent migration of that virtual machine.
| |
os type= | string, e.g. RHEL5 or WindowsXP | The guest operating system type. | |
os boot dev= | enumerated | A list of boot devices described by a dev attribute on a boot element. A list of enumerated values are available in capabilities. | |
os kernel | string | A path to a kernel image the virtual machine is configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader. | |
os initrd | string | A path to an initrd image to be used with the previously specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader. | |
os cmdline | string | A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader. | |
high_availability | complex | Set enabled to true if the virtual machine should be automatically restarted if the virtual machine or its host crashes. A priority element controls the order in which virtual machines are re-started. | |
display | complex |
The display
type (either vnc or spice), port, and the number of monitors. The allow_reconnect Boolean value specifies if a client can reconnect to the machine via display.
The
smartcard_enabled sub-element is a Boolean (true or false) to specify if a Smartcard attached to a client is passed through to a virtual machine. The default is false.
| |
cluster id= | GUID | A reference to the virtual machine's host cluster. |
|
template id= | GUID | A reference to the template on which this virtual machine is based. |
|
domain id= | GUID | A reference to the virtual machine's domain. |
|
start_time | xsd:dateTime format: YYYY-MM-DDThh:mm:ss | The date and time at which this virtual machine was started. |
|
stop_time | xsd:dateTime format: YYYY-MM-DDThh:mm:ss | The date and time at which this virtual machine was stopped. |
|
creation_time | xsd:dateTime format: YYYY-MM-DDThh:mm:ss | The date and time at which this virtual machine was created. |
|
origin | One of rhev, ovirt, vmware or xen | The system from which this virtual machine originated. |
|
stateless | Boolean: true or false | true if the virtual machine is stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and deleted at shutdown. This means state changes do not persist after a reboot. | |
delete_protected | Boolean: true or false | If set to true, the virtual machine cannot be deleted. | |
sso | string | A reference to the method of single sign-on for the virtual machine. Includes a method element with an ip attribute. | |
placement_policy | complex | Sets the placement policy for virtual machine migration. Requires a default host= and an affinity (one of migratable, user_migratable or pinned). Leave the host element empty to set no preferred host. | |
memory_policy | complex | Sets the memory policy for virtual machines. Defines the minimum amount of guaranteed memory on a host in order for the virtual machine to run. | |
quota id= | GUID | Sets a quota for the virtual machine. | |
custom_properties | complex | A set of user-defined environment variable passed as parameters to custom scripts. Each custom_property contains name and value attributes. A list of enumerated values are available in capabilities. | |
usb | complex | Defines the USB policy for a virtual machine. Requires an enabled element set to a Boolean value and a type element set to either native or legacy. | |
migration_downtime | integer | Represents the maximum number of milliseconds the virtual machine can be down during live migration. A value of 0 means that the VDSM default will be used. | |
cpu_profile id= | GUID | A reference to the virtual machine's cpu profile. | |
next_run_configuration | Boolean: true or false | true if changes to the virtual machine's configuration will be applied when the virtual machine is next restarted. | |
numa_tune_mode | string | Reference to the mode of memory allocation (interleave, strict, or preferred) of the host NUMA node. | |
guest_info | complex | A reference to the guest client information. Includes an ip element with an address= attribute. |
|
vmpool | complex | A reference to the virtual machine pool. This element only appears for virtual machines part of a pool. |
|
timezone | tz database format: Area/Location | The Sysprep timezone setting for a Windows virtual machine. | |
domain | complex | The Sysprep domain setting for a Windows virtual machine. Requires a name from the domains collection. | |
initialization | complex |
Defines a list of values applied to the virtual machine on boot using Cloud-Init for Linux-based virtual machines, or Sysprep for Windows-based virtual machines.
Cloud-Init
Sysprep
| |
payloads | complex |
Defines a set of
payload elements to deliver content to a virtual machine upon boot. Each payload requires a type attribute, either cdrom or floppy, and a set of file elements. Within each file element is a name element that specifies the name and location of the file, and a content element that defines the content to deliver to the file.
The
payloads element is used by the cloud-init feature. When cloud-init is used to configure a virtual machine, a payload is automatically created with the type attribute set to cd-rom and two file sub-elements, openstack/latest/meta_data.json and openstack/latest/user_data, which pass configuration parameters to the virtual machine.
|
The
status contains one of the following enumerative values: unassigned, down, up, powering_up, powered_down, paused, migrating_from, migrating_to, unknown, not_responding, wait_for_launch, reboot_in_progress, saving_state, restoring_state, suspended, image_illegal, image_locked or powering_down. These states are listed in vm_states under capabilities.
30.2. XML Representation of a Virtual Machine
Example 30.1. An XML representation of a virtual machine
<vm id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a">
<actions>
<link rel="move"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/move"/>
<link rel="ticket"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/ticket"/>
<link rel="reboot"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/reboot"/>
<link rel="undo_snapshot"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/undo_snapshot"/>
<link rel="commit_snapshot"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/commit_snapshot"/>
<link rel="preview_snapshot"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/preview_snapshot"/>
<link rel="logon"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/logon"/>
<link rel="cancelmigration"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/cancelmigration"/>
<link rel="maintenance"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/maintenance"/>
<link rel="clone"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/clone"/>
<link rel="migrate"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/migrate"/>
<link rel="detach"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/detach"/>
<link rel="export"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/export"/>
<link rel="shutdown"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/shutdown"/>
<link rel="start"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/start"/>
<link rel="stop"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/stop"/>
<link rel="suspend"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/suspend"/>
</actions>
<name>VM_01</name>
<description>Testing Virtual Machine</description>
<link rel="applications"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/applications"/>
<link rel="disks"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/disks"/>
<link rel="nics"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/nics"/>
<link rel="numanodes"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/numanodes"/>
<link rel="cdroms"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/cdroms"/>
<link rel="snapshots"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/snapshots"/>
<link rel="tags"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/tags"/>
<link rel="permissions"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/permissions"/>
<link rel="statistics"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/statistics"/>
<link rel="reporteddevices"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/reporteddevices"/>
<link rel="watchdogs"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/watchdogs"/>
<link rel="sessions"
href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/sessions"/>
<type>server</type>
<status>
<state>down</state>
</status>
<memory>1073741824</memory>
<cpu>
<topology sockets="1" cores="1"/>
<architecture>X86_64</architecture>
</cpu>
<cpu_shares>0</cpu_shares>
<bios>
<boot_menu>
<enabled>false</enabled>
</boot_menu>
</bios>
<os type="other">
<boot dev="hd"/>
</os>
<high_availability>
<enabled>false</enabled>
<priority>1</priority>
</high_availability>
<display>
<type>spice</type>
<monitors>1</monitors>
<single_qxl_pci>false</single_qxl_pci>
<allow_override>true</allow_override>
<smartcard_enabled>false</smartcard_enabled>
<file_transfer_enabled>true</file_transfer_enabled>
<copy_paste_enabled>true</copy_paste_enabled>
</display>
<cluster href="/api/clusters/00000001-0001-0001-0001-0000000002fb" id="00000001-0001-0001-0001-0000000002fb"/>
<template href="/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
<stop_time>2014-12-03T14:25:45.588+10:00</stop_time>
<creation_time>2014-12-03T14:25:45.535+10:00</creation_time>
<origin>ovirt</origin>
<stateless>false</stateless>
<delete_protected>false</delete_protected>
<sso>
<methods>
<method id="GUEST_AGENT"/>
</methods>
</sso>
<timezone>Etc/GMT</timezone>
<placement_policy>
<affinity>migratable</affinity>
</placement_policy>
<memory_policy>
<guaranteed>1073741824</guaranteed>
</memory_policy>
<usb>
<enabled>false</enabled>
</usb>
<migration_downtime>-1</migration_downtime>
<cpu_profile href="/api/cpuprofiles/0000001a-001a-001a-001a-0000000002e3" id="0000001a-001a-001a-001a-0000000002e3"/>
<next_run_configuration_exists>false</next_run_configuration_exists>
<numa_tune_mode>interleave</numa_tune_mode>
</vm>
30.3. XML Representation of Additional OVF Data for a Virtual Machine
Use a
GET request for a virtual machine with the All-Content: true header to include additional OVF data with the representation of the virtual machine.
The
Accept header defaults to application/xml if left blank, and the data is represented with HTML entities so as not to interfere with the XML tags. Specifying the Accept: application/json header will return the data in standard XML tagging. This example representation has been formatted from its standard block format to improve legibility.
Example 30.2. XML representation of additional ovf data for a virtual machine
GET /api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a HTTP/1.1
All-Content: true
<?xml version='1.0' encoding='UTF-8'?>
<ovf:Envelope xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1/"
xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
ovf:version="3.5.0.0">
<References/>
<Section xsi:type="ovf:NetworkSection_Type">
<Info>List of networks</Info>
<Network ovf:name="Network 1"/>
</Section>
<Section xsi:type="ovf:DiskSection_Type">
<Info>List of Virtual Disks</Info>
</Section>
<Content ovf:id="out" xsi:type="ovf:VirtualSystem_Type">
<CreationDate>2014/12/03 04:25:45</CreationDate>
<ExportDate>2015/02/09 14:12:24</ExportDate>
<DeleteProtected>false</DeleteProtected>
<SsoMethod>guest_agent</SsoMethod>
<IsSmartcardEnabled>false</IsSmartcardEnabled>
<TimeZone>Etc/GMT</TimeZone>
<default_boot_sequence>0</default_boot_sequence>
<Generation>1</Generation>
<VmType>1</VmType>
<MinAllocatedMem>1024</MinAllocatedMem>
<IsStateless>false</IsStateless>
<IsRunAndPause>false</IsRunAndPause>
<AutoStartup>false</AutoStartup>
<Priority>1</Priority>
<CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId>
<IsBootMenuEnabled>false</IsBootMenuEnabled>
<IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled>
<IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled>
<Name>VM_export</Name>
<TemplateId>00000000-0000-0000-0000-000000000000</TemplateId>
<TemplateName>Blank</TemplateName>
<IsInitilized>false</IsInitilized>
<Origin>3</Origin>
<DefaultDisplayType>1</DefaultDisplayType>
<TrustedService>false</TrustedService>
<OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId>
<OriginalTemplateName>Blank</OriginalTemplateName>
<UseLatestVersion>false</UseLatestVersion>
<Section ovf:id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
ovf:required="false"
xsi:type="ovf:OperatingSystemSection_Type">
<Info>Guest Operating System</Info>
<Description>other</Description>
</Section>
<Section xsi:type="ovf:VirtualHardwareSection_Type">
<Info>1 CPU, 1024 Memeory</Info>
<System>
<vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
</System>
<Item>
<rasd:Caption>1 virtual cpu</rasd:Caption>
<rasd:Description>Number of virtual CPU</rasd:Description>
<rasd:InstanceId>1</rasd:InstanceId>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:num_of_sockets>1</rasd:num_of_sockets>
<rasd:cpu_per_socket>1</rasd:cpu_per_socket>
</Item>
<Item>
<rasd:Caption>1024 MB of memory</rasd:Caption>
<rasd:Description>Memory Size</rasd:Description>
<rasd:InstanceId>2</rasd:InstanceId>
<rasd:ResourceType>4</rasd:ResourceType>
<rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits>
<rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
</Item>
<Item>
<rasd:Caption>USB Controller</rasd:Caption>
<rasd:InstanceId>3</rasd:InstanceId>
<rasd:ResourceType>23</rasd:ResourceType>
<rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
</Item>
</Section>
</Content>
</ovf:Envelope>
30.4. JSON Representation of a Virtual Machine
Example 30.3. A JSON representation of a virtual machine
{
"type" : "server",
"status" : {
"state" : "down"
},
"stop_reason" : "",
"memory" : 1073741824,
"cpu" : {
"topology" : {
"sockets" : "1",
"cores" : "1"
},
"architecture" : "X86_64"
},
"cpu_shares" : "0",
"bios" : {
"boot_menu" : {
"enabled" : "false"
}
},
"os" : {
"boot" : [ {
"dev" : "hd"
} ],
"type" : "other"
},
"high_availability" : {
"enabled" : "false",
"priority" : "1"
},
"display" : {
"type" : "spice",
"monitors" : "1",
"single_qxl_pci" : "false",
"allow_override" : "false",
"smartcard_enabled" : "false",
"file_transfer_enabled" : "true",
"copy_paste_enabled" : "true"
},
"cluster" : {
"href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb",
"id" : "00000001-0001-0001-0001-0000000002fb"
},
"template" : {
"href" : "/api/templates/00000000-0000-0000-0000-000000000000",
"id" : "00000000-0000-0000-0000-000000000000"
},
"stop_time" : 1423550982110,
"creation_time" : 1423490033647,
"origin" : "ovirt",
"stateless" : "false",
"delete_protected" : "false",
"sso" : {
"methods" : {
"method" : [ {
"id" : "GUEST_AGENT"
} ]
}
},
"timezone" : "Etc/GMT",
"initialization" : {
"regenerate_ssh_keys" : "false",
"nic_configurations" : { }
},
"placement_policy" : {
"affinity" : "migratable"
},
"memory_policy" : {
"guaranteed" : 1073741824,
"ballooning" : "true"
},
"usb" : {
"enabled" : "false"
},
"migration_downtime" : "-1",
"cpu_profile" : {
"href" : "/api/cpuprofiles/0000001a-001a-001a-001a-0000000002e3",
"id" : "0000001a-001a-001a-001a-0000000002e3"
},
"next_run_configuration_exists" : "false",
"numa_tune_mode" : "interleave",
"actions" : {
"link" : [ {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/ticket",
"rel" : "ticket"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/move",
"rel" : "move"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/clone",
"rel" : "clone"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/commit_snapshot",
"rel" : "commit_snapshot"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/preview_snapshot",
"rel" : "preview_snapshot"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/logon",
"rel" : "logon"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/cancelmigration",
"rel" : "cancelmigration"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/maintenance",
"rel" : "maintenance"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/reboot",
"rel" : "reboot"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/undo_snapshot",
"rel" : "undo_snapshot"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/migrate",
"rel" : "migrate"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/detach",
"rel" : "detach"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/export",
"rel" : "export"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/shutdown",
"rel" : "shutdown"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/start",
"rel" : "start"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/stop",
"rel" : "stop"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/suspend",
"rel" : "suspend"
} ]
},
"name" : "VM_01",
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e",
"id" : "42ec2621-7ad6-4ca2-bd68-973a44b2562e",
"link" : [ {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/applications",
"rel" : "applications"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/disks",
"rel" : "disks"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/nics",
"rel" : "nics"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/numanodes",
"rel" : "numanodes"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/cdroms",
"rel" : "cdroms"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/snapshots",
"rel" : "snapshots"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/tags",
"rel" : "tags"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/permissions",
"rel" : "permissions"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/statistics",
"rel" : "statistics"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/reporteddevices",
"rel" : "reporteddevices"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/watchdogs",
"rel" : "watchdogs"
}, {
"href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/sessions",
"rel" : "sessions"
} ]
}
30.5. Methods
30.5.1. Creating a Virtual Machine
Creating a new virtual machine requires the
name, template, and cluster elements. Identify the template and cluster elements with the id attribute or name element. Identify the CPU profile ID with the cpuprofiles attribute.
Example 30.4. Creating a virtual machine with 512 MB that boots from CD-ROM
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>vm2</name>
<description>Virtual Machine 2</description>
<type>desktop</type>
<memory>536870912</memory>
<cluster>
<name>default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<os>
<boot dev="cdrom"/>
</os>
<cdroms>
<cdrom>
<file id="example_windows_7_x64_dvd_u_677543.iso"/>
</cdrom>
</cdroms>
<cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>
Example 30.5. Creating a virtual machine with 512 MB that boots from a virtual hard disk
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>vm2</name>
<description>Virtual Machine 2</description>
<type>desktop</type>
<memory>536870912</memory>
<cluster>
<name>default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<os>
<boot dev="hd"/>
</os>
<cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>
Note
Memory in the previous example is converted to bytes using the following formula:
512MB * 1024 2 = 536870912 bytes
30.5.2. Updating a Virtual Machine
The
name, description, cluster, type, memory, cpu, os, high_availability, display, timezone, domain, stateless, placement_policy, memory_policy, usb, payloads, origin and custom_properties elements are updatable post-creation.
Example 30.6. Updating a virtual machine to contain 1 GB of memory
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<memory>1073741824</memory>
</vm>
Note
Memory in the previous example is converted to bytes using the following formula:
1024MB * 1024 2 = 1073741824 bytes
Note
Memory hot plug is supported from Red Hat Enterprise Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is running.
30.5.3. Removing a Virtual Machine
Removal of a virtual machine requires a
DELETE request.
Example 30.7. Removing a virtual machine
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 HTTP/1.1 204 No Content
30.5.4. Removing a Virtual Machine but not the Virtual Disk
Detach the virtual disk prior to removing the virtual machine. This preserves the virtual disk. Removal of a virtual machine requires a
DELETE request.
Example 30.8. Removing a virtual machine
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<vm>
<disks>
<detach_only>true</detach_only>
</disks>
</vm>
</action>
30.6. Sub-Collections
30.6.1. Disks Sub-Collection
30.6.1.1. Disks Sub-Collection
The
disks sub-collection represents all virtual hard disk devices on a virtual machine. A disk representation contains the following elements:
Table 30.2. Elements for virtual machine disks
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="statistics" | relationship | A link to the statistics sub-collection for a virtual machine's disk statistics. |
|
link rel="permissions" | relationship | A link to the permissions sub-collection. |
|
alias | string | The unique identifier for the disk. Use alias instead of name. | |
image_id | string | A reference to the virtual machine image stored on the defined storage domain. | |
storage_domains | complex | The storage domains associated with this disk. Each storage_domain element contains an id attribute with the associated storage domain's GUID. Update this element with POST to perform live migration of a disk from one data storage domain to another. |
[a] |
size | integer | Size of the disk in bytes. Deprecated; replaced by provisioned_size. |
|
provisioned_size | integer | The provisioned size of the disk in bytes. |
|
actual_size | integer | Actual size of the disk in bytes. |
|
status | One of illegal, invalid, locked or ok | The status of the disk device. These states are listed in disk_states under capabilities. |
|
interface | enumerated | The type of interface driver used to connect to the disk device. A list of enumerated values is available in capabilities. | |
format | enumerated | The underlying storage format. A list of enumerated values is available in capabilities. Copy On Write (COW) allows snapshots, with a small performance overhead. Raw does not allow snapshots, but offers improved performance. |
|
sparse | Boolean: true or false | true if the physical storage for the disk should not be preallocated. |
|
bootable | Boolean: true or false | true if this disk is to be marked as bootable. | |
shareable | Boolean: true or false | true to share the disk with multiple virtual machines. | |
wipe_after_delete | Boolean: true or false | true if the underlying physical storage for the disk should be zeroed when the disk is deleted. This increases security but is a more intensive operation and may prolong delete times. | |
propagate_errors | Boolean: true or false | true if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS. | |
vm id= | GUID | The ID of the containing virtual machine. |
|
quota id= | GUID | Sets a quota for the disk. | |
lun_storage | complex | A reference to a direct LUN mapping for storage usage. Requires a logical_unit element that contains iSCSI or FCP device details. |
|
active | Boolean | Defines if the disk is connected to the virtual machine. |
|
read_only | Boolean | Defines if the disk is read-only. | |
link rel="disk_profile" | relationship | A link to the disk_profile sub-collection. | |
[a]
This element is only required if the disk is being added to a virtual machine and not created from a virtual machine template.
| |||
Example 30.9. An XML representation of a disk device
<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
<link rel="statistics"
href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>
<link rel="permissions"
href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
ed7feafe-9aaf-458c-809a-ed789cdbd5b4/permissions"/>
<vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399"/>
<alias>Classic_VM</alias>
<image_id>cac69a29-ccff-49d4-8a26-e4cdacd83e34</image_id>
<storage_domains>
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
</storage_domains>
<size>12884901888</size>
<provisioned_size>12884901888</provisioned_size>
<actual_size>1073741824</actual_size>
<type>system</type>
<status>
<state>ok</state>
</status>
<interface>virtio</interface>
<format>raw</format>
<bootable>true</bootable>
<shareable>true</shareable>
<wipe_after_disk>true</wipe_after_disk>
<propagate_errors>false</propagate_errors>
<active>true</active>
<read_only>false</read_only>
<disk_profile id="23fb2e0d-3062-4819-8165-3be88f2f587e"
href="/api/diskprofiles/23fb2e0d-3062-4819-8165-3be88f2f587e"/>
<lun_storage>
<logical_unit id="lun1">
...
</logical_unit>
</lun_storage>
</disk>
Add a new virtual disk. When adding a new internal disk, the
provisioned_size element is required. Use the storage_domains element to specify in which storage domain the disk will be created. Multiple disks for the same virtual machine can reside in different storage domains.
Example 30.10. Creating a new disk device on a virtual machine
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<storage_domains>
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
</storage_domains>
<provisioned_size>8589934592</provisioned_size>
<type>system</type>
<interface>virtio</interface>
<format>cow</format>
<bootable>true</bootable>
</disk>
Add a new external (direct LUN) disk to a virtual machine. This method requires the
lun_storage element and the logical_unit element, which contains iSCSI or FCP device details.
Example 30.11. Creating a new direct LUN disk device on a virtual machine
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<interface>virtio</interface>
<lun_storage>
<type>iscsi</type>
<logical_unit id="lun1">
<address>iscsi.example.com</address>
<port>3260</port>
<target>iqn.2010.05.com.example:iscsi.targetX</target>
</logical_unit>
</lun_storage>
</disk>
The
alias, description, storage_domains, provisioned_size, interface, bootable, shareable, wipe_after_delete and propagate_errors elements are updatable post-creation.
Users can resize virtual disks that are in use by one or more virtual machines, without pausing, hibernating or rebooting the virtual machine(s).
Example 30.12. Updating a virtual machine disk
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<bootable>false</bootable>
<shareable>false</shareable>
</disk>
Example 30.13. Updating a virtual machine disk to 20GB
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<provisioned_size>21474836480</provisioned_size>
</disk>
Note
Disk size in the previous example is converted to bytes using the following formula:
20480MB * 1024 2 = 21474836480 bytes
Example 30.14. Renaming a virtual machine disk
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<alias>Classic_VM2</alias>
</disk>
Removal of a virtual machine disk requires a
DELETE request.
Example 30.15. Removing a virtual machine disk
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1 HTTP/1.1 204 No Content
30.6.1.2. Disk Cloning
Clone a disk from a template with the
clone element. Set the clone element to true within the disks sub-collection when creating a virtual machine. This clones a disk from the base template and attaches it to the virtual machine.
Example 30.16. Cloning a disk from a template
The following example clones a disk from a template during the creation of a virtual machine.
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>cloned_vm</name>
<template id="64d4aa08-58c6-4de2-abc4-89f19003b886"/>
<cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
<disks>
<clone>true</clone>
<disk id="4825ffda-a997-4e96-ae27-5503f1851d1b">
<format>COW</format>
</disk>
<disk id="42aef10d-3dd5-4704-aa73-56a023c1464c">
<format>COW</format>
</disk>
</disks>
</vm>
Important
Search queries for virtual machine disks based upon disk name require the
alias search parameter instead of name.
30.6.1.3. Disk Statistics Sub-Collection
Each virtual machine's disk exposes a
statistics sub-collection for disk-specific statistics. Each statistic contains the following elements:
Table 30.3. Elements for virtual machine disk statistics
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the statistic entry. |
description | string | A plain text description of the statistic. |
unit | string | The unit or rate to measure the statistical values. |
type | One of GAUGE or COUNTER | The type of statistic measures. |
values type= | One of INTEGER or DECIMAL | The data type for the statistical values that follow. |
value | complex | A data set that contains datum. |
datum | see values type | An individual piece of data from a value. |
disk id= | relationship | A relationship to the containing disk resource. |
The following table lists the statistic types for virtual machine disks.
Table 30.4. Virtual machine disk statistic types
|
Name
|
Description
|
|---|---|
data.current.read |
The data transfer rate in bytes per second when reading from the disk.
|
data.current.write |
The data transfer rate in bytes per second when writing to the disk.
|
Example 30.17. An XML representation of a virtual machine's statistics sub-collection
<statistics>
<statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/disks/
f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
33b9212b-f9cb-3fd0-b364-248fb61e1272">
<name>data.current.read</name>
<description>Read data rate</description>
<values type="DECIMAL">
<value>
<datum>0</datum>
</value>
</values>
<type>GAUGE</type>
<unit>BYTES_PER_SECOND</unit>
<disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b"
href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
</statistic>
...
</statistics>
Note
This
statistics sub-collection is read-only.
30.6.1.4. Floating Disk Attach and Detach Actions
Attach a disk from the main
rel="disks" collection using a POST request on the virtual machine's disks sub-collection. Include the id of the disk to attach.
Example 30.18. Attach a floating disk
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1 Accept: application/xml Content-type: application/xml <disk id="d135f1c5-b5e1-4238-9381-b3277f5a3742"> </disk>
Detach a disk from a virtual machine's
disks sub-collection using a DELETE request on the disk resource but ensure to include a detach Boolean element so the disk is not destroyed.
Example 30.19. Detach a disk from a virtual machine
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
d135f1c5-b5e1-4238-9381-b3277f5a3742 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<detach>true</detach>
</action>
30.6.1.5. Disk Activate and Deactivate Actions
Each virtual machine's disk provides a set of
activate and deactivate actions to add and remove disks from a virtual machine.
Example 30.20. Action to activate a virtual machine disk
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/activate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Example 30.21. Action to deactivate a virtual machine disk
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/deactivate HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Use these actions to hotplug disks to virtual machines and activate newly attached floating disks.
Important
The hotplugging feature only supports VirtIO disks and virtual machine operating systems that support hotplugging operations. Example operating systems include:
- Red Hat Enterprise Linux 6;
- Red Hat Enterprise Linux 5;
- Windows Server 2008; and,
- Windows Server 2003.
30.6.2. Network Interfaces Sub-Collection
30.6.2.1. Network Interfaces Sub-Collection
The
nics sub-collection represents all network interface devices on a virtual machine. A nic representation contains the following elements:
Table 30.5. Elements for virtual machine network interfaces
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="statistics" | relationship | A link to the statistics sub-collection for a virtual machine's network interface statistics. |
|
network id= | GUID | A reference to the network which the interface should be connected. A blank network id is allowed. |
|
interface | enumerated | The type of driver used for the nic. A list of enumerated values is available in capabilities. | |
mac address= | string | The MAC address of the interface. |
|
port_mirroring | complex | Defines whether the NIC receives mirrored traffic. Define a networks element with a series of network id= references. | |
plugged | Boolean | Defines if the NIC is plugged in to the virtual machine. |
|
linked | Boolean | Defines if the NIC is linked to the virtual machine. |
|
Example 30.22. An XML representation of a network interface
<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e"
ref="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
<link rel="statistics"
href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e/statistics"/>
<name>nic1</name>
<interface>virtio</interface>
<mac address="00:1a:4a:16:84:07"/>
<network id="00000000-0000-0000-0000-000000000009"
href="/api/networks/00000000-0000-0000-0000-000000000009"/>
<vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
<port_mirroring>
<networks>
<network id="56087282-d7a6-11e1-af44-001a4a400e0c"
href="/api/networks/56087282-d7a6-11e1-af44-001a4a400e0c"/>
</networks>
</port_mirroring>
</nic>
When adding a new network interface, the
name and network elements are required. Identify the network element with the id attribute or name element.
Example 30.23. Creating a virtual machine NIC
POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml
<nic>
<name>nic1</name>
<network id="00000000-0000-0000-0000-000000000009"/>
</nic>
An API user modifies a network interface with a
PUT request.
Example 30.24. Updating a virtual machine NIC
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1
Accept: application/xml
Content-type: application/xml
<nic>
<name>nic2</name>
<network id="00000000-0000-0000-0000-000000000010"/>
<type>e1000</type>
</nic>
An API user removes a network interface with a
DELETE request.
Example 30.25. Deleting a virtual machine NIC
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/ 7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1 HTTP/1.1 204 No Content
Important
The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:
- Red Hat Enterprise Linux 6;
- Red Hat Enterprise Linux 5;
- Windows Server 2008; and,
- Windows Server 2003.
30.6.2.2. Network Interface Statistics Sub-Collection
Each virtual machine's network interface exposes a
statistics sub-collection for network interface statistics. Each statistic contains the following elements:
Table 30.6. Elements for a virtual machine's network interface statistics
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the statistic entry. |
description | string | A plain text description of the statistic. |
unit | string | The unit or rate to measure the statistical values. |
type | One of GAUGE or COUNTER | The type of statistic measures. |
values type= | One of INTEGER or DECIMAL | The data type for the statistical values that follow. |
value | complex | A data set that contains datum. |
datum | see values type | An individual piece of data from a value. |
nic id= | relationship | A relationship to the containing nic resource. |
The following table lists the statistic types for network interfaces on virtual machines.
Table 30.7. Virtual machine NIC statistic types
|
Name
|
Description
|
|---|---|
data.current.rx |
The rate in bytes per second of data received.
|
data.current.tx |
The rate in bytes per second of data transmitted.
|
errors.total.rx |
Total errors from receiving data.
|
errors.total.tx |
Total errors from transmitting data.
|
Example 30.26. An XML representation of a virtual machine's NIC statistics sub-collection
<statistics>
<statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/nics/
6cd08e76-57c0-41ba-a728-7eba46ae1e36/statistics/
ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
<name>data.current.rx</name>
<description>Receive data rate</description>
<values type="DECIMAL">
<value>
<datum>0</datum>
</value>
</values>
<type>GAUGE</type>
<unit>BYTES_PER_SECOND</unit>
<nic id="6cd08e76-57c0-41ba-a728-7eba46ae1e36"
href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
nics/6cd08e76-57c0-41ba-a728-7eba46ae1e36"/>
</statistic>
...
</statistics>
Note
This
statistics sub-collection is read-only.
30.6.3. Virtual NUMA Nodes Sub-Collection
The
numanodes sub-collection represents all virtual NUMA nodes on a virtual machine. A vm_numa_node representation contains the following elements:
Table 30.8. Elements for virtual NUMA nodes
| Element | Type | Description | Properties |
|---|---|---|---|
index | integer | The index number of the virtual NUMA node. |
|
memory | integer | The amount of memory allocated to the virtual NUMA node, in MB. |
|
cpu | complex | The CPU topology associated with this virtual NUMA node. Each core element contains an index attribute with the associated core's index number. |
|
vm id= | GUID | The ID of the containing virtual machine. |
|
numa_node_pins | complex | Pins the virtual NUMA node to a host NUMA node. Each numa_node_pin element contains a pinned="true" boolean and the host NUMA node's index number. |
Example 30.27. An XML representation of a virtual NUMA node
<vm_numa_node href="/api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50" id="3290b973-ed3e-4f0b-bbf5-9be10d229e50">
<index>0</index>
<memory>1024</memory>
<cpu>
<cores>
<core index="0"/>
</cores>
</cpu>
<vm href="/api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b" id="c7ecd2dc-dbd3-4419-956f-1249651c0f2b"/>
<numa_node_pins>
<numa_node_pin pinned="true" index="0">
<host_numa_node id="417cdefb-8c47-4838-87f3-dd0498fdf6c7"/>
</numa_node_pin>
</numa_node_pins>
</vm_numa_node>
When adding a new virtual NUMA node, the
index, memory, and cpu elements are required.
Example 30.28. Adding a new virtual NUMA node to a virtual machine
POST /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm_numa_node>
<index>0</index>
<memory>1024</memory>
<cpu>
<cores>
<core index="0"/>
</cores>
</cpu>
</vm_numa_nodes>
Update a virtual NUMA node with a
PUT request. You can use a PUT request to pin a virtual NUMA node to a physical NUMA node on a host.
Example 30.29. Updating a virtual NUMA node
PUT /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm_numa_node>
<numa_node_pins>
<numa_node_pin pinned="true" index="0">
<host_numa_node id="417cdefb-8c47-4838-87f3-dd0498fdf6c7"/>
</numa_node_pin>
</numa_node_pins>
</vm_numa_node>
Remove a virtual NUMA node with a
DELETE request.
Example 30.30. Removing a virtual NUMA node
DELETE /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1 HTTP/1.1 204 No Content
30.6.4. CD-ROMs Sub-Collection
The
cdroms sub-collection represents the CD-ROM device on a virtual machine. A cdrom representation contains the following elements:
Table 30.9. Elements for virtual machine CD-ROMs
| Element | Type | Description | Properties |
|---|---|---|---|
file id= | string/filename | A reference to an ISO image. |
Example 30.31. An XML representation of a CD-ROM device
<cdrom id="00000000-0000-0000-0000-000000000000"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/
00000000-0000-0000-0000-000000000000">
<file id="rhel-server-6.0-x86_64-dvd.iso"/>
<vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</cdrom>
Send a
PUT request with a file id element to add a new CD-ROM resource.
Example 30.32. Adding a new CD-ROM file
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
<file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
The API changes the CD-ROM using a
PUT request:
Example 30.33. Changing a CD-ROM file
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
<file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
The API changes the CD-ROM for the current session only using a
PUT request with an additional current URI argument:
Example 30.34. Changing a CD-ROM file during a current session
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
<file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
To eject the CD-ROM temporarily, send a
PUT request to the cdroms sub-collection of a virtual machine, adding the current=true matrix parameter:
Example 30.35. Ejecting a CD-ROM file during a current session
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1 Accept: application/xml Content-type: application/xml <cdrom> <file id=""/> </cdrom>
Note
Rebooting the virtual machine will connect the CD-ROM again.
To eject the CD-ROM permanently, send a
PUT request to the cdroms sub-collection of a virtual machine:
Example 30.36. Ejecting a CD-ROM file permanently
PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1 Accept: application/xml Content-type: application/xml <cdrom> <file id=""/> </cdrom>
Note
Virtual machines only contain a single CD-ROM device.
30.6.5. Snapshots Sub-Collection
30.6.5.1. Snapshots Sub-Collection
A virtual machine saves and restores disk state as a number of snapshots. These are represented and managed through a
rel="snapshot" sub-collection that behaves similar to other collections.
Each virtual machine snapshot is represented with an individual
snapshot element that contains the following sub-elements:
Table 30.10. Elements for virtual machine snapshots
| Element | Type | Description | Properties |
|---|---|---|---|
vm id= | GUID | The ID and URI of the virtual machine to which this snapshot pertains. |
|
link rel="restore" | relationship | A link to restore the snapshot of the virtual machine. |
|
link rel="prev" | relationship | A link to the previous snapshot of this virtual machine. |
|
type | string | The type of the snapshot. For example, active or regular. |
|
date | xsd:dateTime format: YYYY-MM-DDThh:mm:ss | The date and time at which the snapshot was created. |
|
snapshot_status | string | The current status of the snapshot. |
|
persist_memorystate | Boolean | Defines whether the snapshot also includes the state of the memory of the virtual machine at the time the snapshot was taken. |
|
Note
It is not possible to modify snapshot elements using
PUT.
Example 30.37. An XML representation of a virtual machine snapshot
<snapshot id="00000000-0000-0000-0000-000000000000"
href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
00000000-0000-0000-0000-000000000000">
<actions>
<link rel="restore"
href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
00000000-0000-0000-0000-000000000000/restore"/>
<link rel="prev"
href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
</actions>
<vm id="00000000-0000-0000-0000-000000000000"
href="/api/vms/00000000-0000-0000-0000-000000000000"/>
<description>Virtual Machine 1 - Snapshot A</description>
<type>active</type>
<date>2010-08-16T14:24:29</date>
<snapshot_status>ok</snapshot_status>
<persist_memorystate>false</persist_memorystate>
</snapshot>
Use a
GET request for a virtual machine snapshot with the All-Content: true header to include additional OVF data with the representation of the snapshot.
The
Accept header defaults to application/xml if left blank, and the data is represented with HTML entities so as not to interfere with the XML tags. Specifying the Accept: application/json header will return the data in standard XML tagging. This example representation has been formatted from its standard block format to improve legibility.
Example 30.38. XML representation of additional ovf data for a snapshot
GET /api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/snapshots HTTP/1.1
All-Content: true
<?xml version='1.0' encoding='UTF-8'?>
<ovf:Envelope xmlns:ovf=\"http://schemas.dmtf.org/ovf/envelope/1/\"
xmlns:rasd=\"http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData\"
xmlns:vssd=\"http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData\"
xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" ovf:version=\"3.5.0.0\">
<References>
<File ovf:href=\"ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459\"
ovf:id=\"40456d92-3687-4a85-bab3-87b4cc7af459\" ovf:size=\"10737418240\"
ovf:description=\"Active VM\"/>
<Nic ovf:id=\"be14bfc8-3dbd-4ac1-ba02-c6dfa7fc707c\"/>
</References>
<Section xsi:type=\"ovf:NetworkSection_Type\">
<Info>List of networks</Info><Network ovf:name=\"Network 1\"/>
</Section>
<Section
xsi:type=\"ovf:DiskSection_Type\">
<Info>List of Virtual Disks</Info>
<Disk ovf:diskId=\"40456d92-3687-4a85-bab3-87b4cc7af459\"
ovf:size=\"10\" ovf:actual_size=\"0\"
ovf:vm_snapshot_id=\"a209216d-2909-4802-8886-02aad55dccc8\"
ovf:parentRef=\"\"
ovf:fileRef=\"ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459\"
ovf:format=\"http://www.vmware.com/specifications/vmdk.html#sparse\"
ovf:volume-format=\"RAW\"
ovf:volume-type=\"Preallocated\"
ovf:disk-interface=\"VirtIO\"
ovf:boot=\"true\"
ovf:disk-alias=\"VM_01_Disk1\"
ovf:wipe-after-delete=\"false\"/>
</Section>
<Content
ovf:id=\"out\"
xsi:type=\"ovf:VirtualSystem_Type\">
<CreationDate>2015/02/09 13:53:53</CreationDate>
<ExportDate>2015/02/10 00:39:24</ExportDate>
<DeleteProtected>false</DeleteProtected>
<SsoMethod>guest_agent</SsoMethod>
<IsSmartcardEnabled>false</IsSmartcardEnabled>
<TimeZone>Etc/GMT</TimeZone><default_boot_sequence>0</default_boot_sequence>
<Generation>1</Generation>
<VmType>1</VmType>
<MinAllocatedMem>1024</MinAllocatedMem>
<IsStateless>false</IsStateless>
<IsRunAndPause>false</IsRunAndPause>
<AutoStartup>false</AutoStartup>
<Priority>1</Priority>
<CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId>
<IsBootMenuEnabled>false</IsBootMenuEnabled>
<IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled>
<IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled>
<Name>VM_01</Name>
<TemplateId>00000000-0000-0000-0000-000000000000</TemplateId>
<TemplateName>Blank</TemplateName>
<IsInitilized>true</IsInitilized>
<Origin>3</Origin>
<DefaultDisplayType>1</DefaultDisplayType>
<TrustedService>false</TrustedService>
<OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId>
<OriginalTemplateName>Blank</OriginalTemplateName>
<UseLatestVersion>false</UseLatestVersion>
<Section ovf:id=\"42ec2621-7ad6-4ca2-bd68-973a44b2562e\" ovf:required=\"false\" xsi:type=\"ovf:OperatingSystemSection_Type\">
<Info>Guest Operating System</Info>
<Description>other</Description>
</Section>
<Section xsi:type=\"ovf:VirtualHardwareSection_Type\">
<Info>1 CPU, 1024 Memeory</Info>
<System>
<vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
</System>
<Item>
<rasd:Caption>1 virtual cpu</rasd:Caption>
<rasd:Description>Number of virtual CPU</rasd:Description>
<rasd:InstanceId>1</rasd:InstanceId>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:num_of_sockets>1</rasd:num_of_sockets>
<rasd:cpu_per_socket>1</rasd:cpu_per_socket>
</Item>
<Item>
<rasd:Caption>1024 MB of memory</rasd:Caption>
<rasd:Description>Memory Size</rasd:Description>
<rasd:InstanceId>2</rasd:InstanceId>
<rasd:ResourceType>4</rasd:ResourceType>
<rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits>
<rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
</Item>
<Item>
<rasd:Caption>VM_01_Disk1</rasd:Caption>
<rasd:InstanceId>40456d92-3687-4a85-bab3-87b4cc7af459</rasd:InstanceId>
<rasd:ResourceType>17</rasd:ResourceType>
<rasd:HostResource>ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459</rasd:HostResource>
<rasd:Parent>00000000-0000-0000-0000-000000000000</rasd:Parent>
<rasd:Template>00000000-0000-0000-0000-000000000000</rasd:Template>
<rasd:ApplicationList></rasd:ApplicationList>
<rasd:StoragePoolId>00000002-0002-0002-0002-000000000255</rasd:StoragePoolId>
<rasd:CreationDate>2015/02/09 13:54:41</rasd:CreationDate>
<rasd:LastModified>1970/01/01 00:00:00</rasd:LastModified>
<rasd:last_modified_date>2015/02/10 00:39:22</rasd:last_modified_date>
<Type>disk</Type>
<Device>disk</Device>
<rasd:Address>{slot=0x06, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address>
<BootOrder>1</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>virtio-disk0</Alias>
</Item>
<Item>
<rasd:Caption>Ethernet adapter on rhevm</rasd:Caption>
<rasd:InstanceId>be14bfc8-3dbd-4ac1-ba02-c6dfa7fc707c</rasd:InstanceId>
<rasd:ResourceType>10</rasd:ResourceType>
<rasd:OtherResourceType>rhevm</rasd:OtherResourceType>
<rasd:ResourceSubType>3</rasd:ResourceSubType>
<rasd:Connection>rhevm</rasd:Connection>
<rasd:Linked>true</rasd:Linked>
<rasd:Name>nic1</rasd:Name>
<rasd:MACAddress>00:1a:4a:87:cb:00</rasd:MACAddress>
<rasd:speed>1000</rasd:speed>
<Type>interface</Type>
<Device>bridge</Device>
<rasd:Address>{slot=0x03, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>net0</Alias>
</Item>
<Item>
<rasd:Caption>USB Controller</rasd:Caption>
<rasd:InstanceId>3</rasd:InstanceId>
<rasd:ResourceType>23</rasd:ResourceType>
<rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
</Item>
<Item>
<rasd:Caption>Graphical Controller</rasd:Caption>
<rasd:InstanceId>17bbf0db-7cf0-4529-9b53-dee6dee41cfd</rasd:InstanceId>
<rasd:ResourceType>20</rasd:ResourceType>
<rasd:VirtualQuantity>1</rasd:VirtualQuantity>
<rasd:SinglePciQxl>false</rasd:SinglePciQxl>
<Type>video</Type>
<Device>qxl</Device>
<rasd:Address>{slot=0x02, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>true</IsReadOnly>
<Alias>video0</Alias>
<SpecParams>
<vram>32768</vram>
<heads>1</heads>
</SpecParams>
</Item>
<Item>
<rasd:Caption>CDROM</rasd:Caption>
<rasd:InstanceId>7ce1bd14-d98a-43ba-beee-520bdfd9c698</rasd:InstanceId>
<rasd:ResourceType>15</rasd:ResourceType>
<Type>disk</Type>
<Device>cdrom</Device>
<rasd:Address>{bus=1, controller=0, type=drive, target=0, unit=0}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>true</IsReadOnly>
<Alias>ide0-1-0</Alias></Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>8758c42f-7523-461b-82bb-41d91e46fd36</rasd:InstanceId>
<Type>controller</Type>
<Device>usb</Device>
<rasd:Address>{slot=0x01, bus=0x00, domain=0x0000, type=pci, function=0x2}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>usb0</Alias>
</Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>58f1a596-553e-4e95-9331-64b5d8cebe2e</rasd:InstanceId>
<Type>controller</Type>
<Device>ide</Device>
<rasd:Address>{slot=0x01, bus=0x00, domain=0x0000, type=pci, function=0x1}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>ide0</Alias>
</Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>2f4f8aa5-25eb-4a31-b841-50dc48fce4a7</rasd:InstanceId>
<Type>channel</Type>
<Device>unix</Device>
<rasd:Address>{bus=0, controller=0, type=virtio-serial, port=1}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>channel0</Alias>
</Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>edaac3ed-2ab6-48b1-ae77-cc98f8b45bd8</rasd:InstanceId>
<Type>channel</Type>
<Device>unix</Device>
<rasd:Address>{bus=0, controller=0, type=virtio-serial, port=2}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>channel1</Alias>
</Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>8dfed248-5164-41d3-8b6e-46aef9798d84</rasd:InstanceId>
<Type>channel</Type>
<Device>spicevmc</Device>
<rasd:Address>{bus=0, controller=0, type=virtio-serial, port=3}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>channel2</Alias>
</Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>d184185e-ee19-442a-88f5-6a48f14164e1</rasd:InstanceId>
<Type>controller</Type>
<Device>virtio-scsi</Device>
<rasd:Address>{slot=0x04, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>scsi0</Alias>
</Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>374d219e-e2ff-4755-a544-d537c87e82df</rasd:InstanceId>
<Type>controller</Type>
<Device>virtio-serial</Device>
<rasd:Address>{slot=0x05, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>false</IsReadOnly>
<Alias>virtio-serial0</Alias>
</Item>
<Item>
<rasd:ResourceType>0</rasd:ResourceType>
<rasd:InstanceId>cf3d7121-9db0-4fd1-bd12-50ce4e1ce379</rasd:InstanceId>
<Type>balloon</Type>
<Device>memballoon</Device>
<rasd:Address>{slot=0x07, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address>
<BootOrder>0</BootOrder>
<IsPlugged>true</IsPlugged>
<IsReadOnly>true</IsReadOnly>
<Alias>balloon0</Alias>
<SpecParams>
<model>virtio</model>
</SpecParams>
</Item>
</Section>
</Content>
</ovf:Envelope>
You can create a snapshot of a virtual machine that is running (a live snapshot) or shut down by using the
POST method:
Example 30.39. Creating a Virtual Machine Snapshot
POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/ HTTP/1.1 Accept: application/xml Content-type: application/xml <snapshot> <description>Snapshot description</description> </snapshot>
You can restore a virtual machine snapshot using the
rel="restore" action link in the snapshot representation:
Example 30.40. Restoring a Virtual Machine Snapshot
POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/00000000-0000-0000-0000-000000000000/restore HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
30.6.5.2. Clone a Virtual Machine from a Snapshot
API provides a function to create virtual machines from a snapshot of a previous machine. API users create a new virtual machine while retaining the original virtual machine with all snapshots intact.
Creation of a virtual machines from a snapshot requires an additional
snapshots element to a standard representation of a virtual machine, which a user sends in a POST request to the vms collection.
The
snapshots element contains a snapshot id= element to define the specific snapshot to use as a basis for the virtual machine.
Example 30.41. Clone Virtual Machine from Snapshot
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
...
<snapshots>
<snapshot id="3f68ee63-0016-4f8c-9b8a-11d9f28f7c9e"/>
</snapshots>
...
</vm>
30.6.6. Statistics Sub-Collection
Each virtual machine resource exposes a
statistics sub-collection for virtual machine-specific statistics. Each statistic contains the following elements:
Table 30.11. Elements for virtual machine statistics
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the statistic entry. |
description | string | A plain text description of the statistic. |
unit | string | The unit or rate to measure the statistical values. |
type | One of GAUGE or COUNTER | The type of statistic measures. |
values type= | One of INTEGER or DECIMAL | The data type for the statistical values that follow. |
value | complex | A data set that contains datum. |
datum | see values type | An individual piece of data from a value. |
vm id= | relationship | A relationship to the containing vm resource. |
The following table lists the statistic types for virtual machines.
Table 30.12. Virtual machine statistic types
|
Name
|
Description
|
|---|---|
memory.installed |
Total memory in bytes allocated for the virtual machine's use.
|
memory.used |
Current memory in bytes used by the virtual machine.
|
cpu.current.guest |
Percentage of CPU used by the guest.
|
cpu.current.hypervisor |
Percentage of CPU overhead on the hypervisor.
|
cpu.current.total |
Total percentage of the current CPU in use.
|
Example 30.42. An XML representation of a virtual machine's statistics sub-collection
<statistics>
<statistic id="ef802239-b74a-329f-9955-be8fea6b50a4"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/
statistics/ef802239-b74a-329f-9955-be8fea6b50a4">
<name>memory.installed</name>
<description>Total memory configured</description>
<unit>BYTES</unit>
<type>GUAGE</type>
<values type="DECIMAL">
<value>
<datum>1073741824<datum>
</value>
</values>
<vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</statistic>
...
</statistics>
Note
A virtual machine's
statistics sub-collection is read-only.
30.6.7. Displaying Virtual Machine Session Information
Submit a
GET request for a virtual machine and use the session sub-collection to view the session information for the user that initiated the SPICE console session and the user logged in to the virtual machine.
The
session information of a virtual machine is listed as a sub-collection:
Example 30.43. Displaying the session information of a virtual machine
GET /api/roles/a1a701f1-aa06-4f02-af17-158be31489b3/sessions HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<sessions>
<session id="37a6259c-c0c1-dae2-99a7-866489dff0bd"
href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd">
<vm href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
<ip address="192.0.2.0"/>
<user href= "/api/users/fdfc627c-d875-11e0-90f0-83df133b58cc" id="fdfc627c-d875-11e0-90f0-83df133b58cc">
<domain href= "/api/domains/696e7465-726e-616c-696e-7465726e616c" id="696e7465-726e-616c-696e-7465726e616c">
<name>internal</name>
</domain>
<user_name>admin</user_name>
</user>
<console_user>true</console_user>
</session>
<session id="37a6259c-c0c1-dae2-99a7-866489dff0bd"
href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd" >
<vm href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
<user>
<user_name>root</user_name>
</user>
</session>
</sessions>
30.7. Actions
- 30.7.1. Start Virtual Machine Action
- 30.7.2. Start Virtual Machine with Cloud-Init Action
- 30.7.3. Stop Virtual Machine Action
- 30.7.4. Shutdown Virtual Machine Action
- 30.7.5. Suspend Virtual Machine Action
- 30.7.6. Reboot Virtual Machine Action
- 30.7.7. Enable user logon to access a virtual machine from an external console
- 30.7.8. Detach Virtual Machine from Pool Action
- 30.7.9. Migrate Virtual Machine Action
- 30.7.10. Cancel Virtual Machine Migration Action
- 30.7.11. Export Virtual Machine Action
- 30.7.12. Virtual Machine Ticket Action
- 30.7.13. Force Remove Virtual Machine Action
30.7.1. Start Virtual Machine Action
The start action launches a stopped, shutdown, or suspended virtual machine.
Example 30.44. Action to start a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
The start action allows a
vm element to be provided as a parameter. If a vm element is provided, the virtual machine uses the values from the provided element and overrides system settings at start time. Using the start action with the vm element in REST API is equivalent to using the Run Once window in the Administration or User Portal. These settings persist until a user stops the virtual machine. Examples of these elements include os, domain, placement_policy, cdroms, stateless and display type.
Example 30.45. Action to start a virtual machine with overridden parameters
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<pause>true</pause>
<vm>
<stateless>true</stateless>
<display>
<type>spice</type>
</display>
<os>
<boot dev="cdrom"/>
</os>
<cdroms>
<cdrom>
<file id="windows-xp.iso"/>
</cdrom>
</cdroms>
<floppies>
<floppy>
<file id="virtio-win_x86.vfd"/>
</floppy>
</floppies>
<domain>
<name>domain.example.com</name>
<user>
<user_name>domain_user</user_name>
<password>domain_password</password>
</user>
</domain>
<placement_policy>
<host id="02447ac6-bcba-448d-ba2b-f0f453544ed2"/>
</placement_policy>
</vm>
</action>
Note
- The
domainelement is used for Windows systems only for overriding parameters on boot with thestartaction. Thedomainelement determines the domain that the Windows virtual machine joins. If the domain does not exist in thedomainscollection, this element requires additionaluserauthentication details, including auser_nameandpassword. If the domain exists in thedomainscollection, the action requires no additionaluserauthentication details. - The CD image and floppy disk file must be available in the ISO domain already. If not, use the ISO uploader tool to upload the files. See The ISO Uploader Tool for more information.
30.7.2. Start Virtual Machine with Cloud-Init Action
Cloud-Init is a tool for automating the initial setup of virtual machines. You can use the tool to configure the host name, network interfaces, the DNS service, authorized keys, and set user names and passwords. You can also use the
custom_script tag to specify a custom script to run on the virtual machine when it boots.
Note
The
cloud-init element can only be used to start virtual machines with the cloud-init package installed. When the cloud-init element is used, any element within the initialization element but outside the cloud-init element will be ignored.
Example 30.46. Action to start a virtual machine using Cloud-Init
This example shows you how to start a virtual machine using the Cloud-Init tool to set the host name, change the root password, set a static IP for the
eth0 interface, configure DNS, and add an SSH key for the root user.
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<vm>
<initialization>
<cloud_init>
<host>
<address>MyHost.MyDomain.com</address>
</host>
<users>
<user>
<user_name>root</user_name>
<password>p@55w0rd!</password>
</user>
</users>
<network_configuration>
<nics>
<nic>
<name>eth0</name>
<boot_protocol>static</boot_protocol>
<network>
<ip address="192.168.122.31" netmask="255.255.255.0" gateway="192.168.122.1"/>
</network>
<on_boot>true</on_boot>
</nic>
</nics>
<dns>
<servers>
<host>
<address>192.168.122.1</address>
</host>
</servers>
<search_domains>
<host>
<address>MyDomain.com</address>
</host>
</search_domains>
</dns>
</network_configuration>
<authorized_keys>
<authorized_key>
<user>
<user_name>root</user_name>
</user>
<key>ssh-rsa AAAAB3Nza[...]75zkdD root@MyDomain.com</key>
</authorized_key>
</authorized_keys>
</cloud_init>
<custom_script><![CDATA[your script]]></custom_script>
</initialization>
</vm>
</action>
30.7.3. Stop Virtual Machine Action
The stop action forces a virtual machine to power-off.
Example 30.47. Action to stop a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
30.7.4. Shutdown Virtual Machine Action
The shutdown action sends a shutdown request to a virtual machine.
Example 30.48. Action to send a shutdown request to a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
30.7.5. Suspend Virtual Machine Action
The suspend action saves the virtual machine state to disk and stops it. Start a suspended virtual machine and restore the virtual machine state with the start action.
Example 30.49. Action to save virtual machine state and suspend the machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
30.7.6. Reboot Virtual Machine Action
The reboot action sends a reboot request to a virtual machine.
Example 30.50. Action to send a reboot request to a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/reboot HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
30.7.7. Enable user logon to access a virtual machine from an external console
The logon action enables users to access a virtual machine from consoles outside of the Red Hat Enterprise Virtualization environment.
This action requires the rhevm-guest-agent-gdm-plugin and the rhevm-guest-agent-pam-module packages to be installed and the
ovirt-guest-agent service to be running on the virtual machine.
Users require the appropriate user permissions for the virtual machine in order to access the virtual machine from an external console.
Example 30.51. Logging onto a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/logon HTTP/1.1
Content-Type: application/json
Content-Length: 2
{}
30.7.8. Detach Virtual Machine from Pool Action
The detach action detaches a virtual machine from a pool.
Example 30.52. Action to detach a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
30.7.9. Migrate Virtual Machine Action
The migrate action migrates a virtual machine to another physical host. The destination
host element is an optional element as Red Hat Enterprise Virtualization Manager automatically selects a default host for migration. If an API user requires a specific host, the user can specify the host with either an id or name parameter.
Example 30.53. Action to migrate a virtual machine to another host
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/migrate HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>
30.7.10. Cancel Virtual Machine Migration Action
The cancel migration action stops any migration of a virtual machine to another physical host.
Example 30.54. Action to cancel migration of a virtual machine to another host
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/cancelmigration HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
30.7.11. Export Virtual Machine Action
The export action exports a virtual machine to an
export storage domain. A destination storage domain must be specified with a storage_domain reference.
The export action reports a failed action if a virtual machine of the same name exists in the destination domain. Set the
exclusive parameter to true to change this behavior and overwrite any existing virtual machine.
If snapshots of the virtual machine are not included with the exported virtual machine, set the
discard_snapshots parameter to true.
Example 30.55. Action to export a virtual machine to an export storage domain
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/export HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain>
<name>export1</name>
</storage_domain>
<exclusive>true</exclusive>
<discard_snapshots>true</discard_snapshots>
</action>
30.7.12. Virtual Machine Ticket Action
The ticket action generates a time-sensitive authentication token for accessing a virtual machine's display. The client-provided
action optionally includes a ticket representation containing a value (if the token string needs to take on a particular form) and/or an expiry time in minutes. In any case, the response specifies the actual ticket value and expiry used.
Example 30.56. Action to generate authentication token for a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<ticket>
<expiry>120</expiry>
</ticket>
</action>
200 OK
Content-Type: application/xml
<action id="94e07552-14ba-4c27-8ce6-2cc75190d3ef"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket/
94e07552-14ba-4c27-8ce6-2cc75190d3ef">
<status>
<state>complete</state>
</status>
<ticket>
<value>5c7CSzK8Sw41</value>
<expiry>120</expiry>
</ticket>
<link rel="parent"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
<link rel="replay"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket"/>
</action>
30.7.13. Force Remove Virtual Machine Action
An API user forces the removal of a faulty virtual machine with the
force action. This action requires a DELETE method. The request body contains an action representation with the force parameter set to true. The request also requires an additional Content-type: application/xml header to process the XML representation in the body.
Example 30.57. Force remove action on a virtual machine
DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<force>true</force>
</action>
Chapter 31. Floating Disks
31.1. Floating Disk Elements
The
disks collection provides information about all disks in a Red Hat Enterprise Virtualization environment. A user attaches and detaches disks from any virtual machine and floats them between virtual machines. An API user accesses this information through the rel="disks" link obtained from the entry point URI.
The following table shows specific elements contained in a
disks resource representation.
Table 31.1. Elements for floating disks
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="statistics" | relationship | A link to the statistics sub-collection for a virtual machine's disk statistics. |
|
image_id | GUID | A reference to the virtual machine image stored on the defined storage domain. |
|
storage_domains | Complex | The storage domains associated with this disk. Each storage_domain element contains an id attribute with the associated storage domain's GUID. Update this element with POST to perform live migration of a disk from one data storage domain to another. |
|
size | integer | Size of the disk in bytes. |
|
provisioned_size | integer | The provisioned size of the disk in bytes. |
|
actual_size | integer | Actual size of the disk in bytes. |
|
status | One of illegal, invalid, locked or ok | The status of the disk device. These states are listed in disk_states under capabilities. |
|
interface | enumerated | The type of interface driver used to connect to the disk device. A list of enumerated values is available in capabilities. | |
format | enumerated | The underlying storage format. A list of enumerated values is available in capabilities. Copy On Write (COW) allows snapshots, with a small performance overhead. Raw does not allow snapshots, but offers improved performance. |
|
sparse | Boolean: true or false | true if the physical storage for the disk should not be preallocated. |
|
bootable | Boolean: true or false | true if this disk is to be marked as bootable. | |
shareable | Boolean: true or false | true to share the disk with multiple virtual machines. | |
wipe_after_delete | Boolean: true or false | true if the underlying physical storage for the disk should be zeroed when the disk is deleted. This increases security but is a more intensive operation and may prolong delete times. | |
propagate_errors | Boolean: true or false | true if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the guest OS. | |
quota id= | GUID | Sets a quota for the disk. | |
lunStorage | complex | A reference to a direct LUN mapping for storage usage. Requires a storage element that contains iSCSI or FCP device details. |
|
active | Boolean | Defines if the disk is connected to the virtual machine. |
|
Important
Search queries for disks based upon name require the
alias search parameter instead of name.
31.2. XML Representation of a Floating Disk
Example 31.1. An XML representation of a disk device
<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
href="/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
<link rel="statistics"
href="/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>
<storage_domains>
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
</storage_domains>
<size>10737418240</size>
<type>system</type>
<status>
<state>ok</state>
</status>
<interface>virtio</interface>
<format>raw</format>
<bootable>true</bootable>
<shareable>true</shareable>
<lunStorage>
<storage>
<logical_unit id="lun1">
...
</logical_unit>
<storage>
</lunStorage>
</disk>
31.3. Methods
31.3.1. Creating a Floating Disk
When creating a new floating disk, the API requires the
size and storage_domains elements.
Example 31.2. Creating a new a floating disk device
POST /api/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml
<disk>
<storage_domains>
<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
</storage_domains>
<size>8589934592</size>
<type>system</type>
<interface>virtio</interface>
<format>cow</format>
</disk>
31.4. Sub-Collections
31.4.1. Statistics Sub-Collection
Each floating disk exposes a
statistics sub-collection for disk-specific statistics. Each statistic contains the following elements:
Table 31.2. Elements for virtual machine disk statistics
| Element | Type | Description |
|---|---|---|
name | string | The unique identifier for the statistic entry. |
description | string | A plain text description of the statistic. |
unit | string | The unit or rate to measure the statistical values. |
type | One of GAUGE or COUNTER | The type of statistic measures. |
values type= | One of INTEGER or DECIMAL | The data type for the statistical values that follow. |
value | complex | A data set that contains datum. |
datum | see values type | An individual piece of data from a value. |
disk id= | relationship | A relationship to the containing disk resource. |
The following table lists the statistic types for floating disks.
Table 31.3. Disk statistic types
|
Name
|
Description
|
|---|---|
data.current.read |
The data transfer rate in bytes per second when reading from the disk.
|
data.current.write |
The data transfer rate in bytes per second when writing to the disk.
|
Example 31.3. An XML representation of a virtual machine's statistics sub-collection
<statistics>
<statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
33b9212b-f9cb-3fd0-b364-248fb61e1272">
<name>data.current.read</name>
<description>Read data rate</description>
<values type="DECIMAL">
<value>
<datum>0</datum>
</value>
</values>
<type>GAUGE</type>
<unit>BYTES_PER_SECOND</unit>
<disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b"
href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
</statistic>
...
</statistics>
Note
This
statistics sub-collection is read-only.
Chapter 32. Templates
32.1. Virtual Machine Template Elements
The
templates collection provides information about the virtual machine templates in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="templates" link obtained from the entry point URI.
The following table shows specific elements contained in a virtual machine template resource representation.
Table 32.1. Virtual machine template elements
| Element | Type | Description | Properties |
|---|---|---|---|
link rel="disks" | relationship | A link to the disks sub-collection for virtual machine template resources. |
|
link rel="nics" | relationship | A link to the nics sub-collection for virtual machine template resources. | |
link rel="cdroms" | relationship | A link to the cdroms sub-collection for virtual machine template resources. |
|
link rel="permissions" | relationship | A link to the permissions sub-collection for virtual machine template permissions. | |
type | enumerated | The type of virtual machine the template provides. A list of enumerated values are available in capabilities. | |
status | One of illegal, locked or ok | The template status. These states are listed in template_states under capabilities. |
|
memory | integer | The amount of memory allocated to the guest, in bytes. | |
cpu | complex | The CPU topology (i.e. number of sockets and cores) available to the guest. | |
os type= | string, e.g. RHEL5 or WindowsXP | The guest operating system type. | |
os boot dev= | enumerated | A list of boot devices, described by a dev attribute on a boot element. A list of enumerated values are available in capabilities. | |
os kernel | string | A path to a kernel image which the template is configured to boot from. | |
os initrd | string | A path to an initrd image to be used with the kernel above. | |
os cmdline | string | A kernel command line parameter string to be used with the kernel above. | |
cluster id= | GUID | A reference to the template's host cluster. |
|
vm id= | GUID | A reference to the VM on which this template is based. |
|
domain id= | GUID | A reference to the template's domain. |
|
creation_time | xsd:dateTime format: YYYY-MM-DDThh:mm:ss | The date and time at which this template was created. |
|
origin | One of rhev, ovirt, vmware or xen | The system from which this template originated. |
|
high_availability | complex | Set enabled to true if the VM should be automatically restarted if the host crashes. A priority element controls the order in which VMs are re-started. | |
display | complex | The display type (either vnc or spice), port, and the number of monitors. The allow_reconnect Boolean value specifies if a client can reconnect to the machine via display. | |
stateless | Boolean: true or false | A stateless template contains a snapshot of its disk image taken at boot and deleted at shutdown. This means state changes do not persist after a reboot. | |
usb | complex | Defines the USB policy for a virtual machine template. Requires an enabled element set to a Boolean value and a type element set to either native or legacy. | |
placement_policy | complex | Sets the placement policy for virtual machine migration. Requires a default host= and an affinity (one of migratable, user_migratable or pinned). Leave the host element empty to set no preferred host. | |
custom_properties | complex | A set of user-defined environment variable passed as parameters to custom scripts. Each custom_property contains name and value attributes. A list of enumerated values are available in capabilities. | |
timezone | tz database format: Area/Location | The the Sysprep timezone setting for a Windows virtual machine template. | |
domain | complex | The the Sysprep domain setting for a Windows virtual machine template. Requires a name from the domains collection. |
32.2. XML Representation of a Virtual Machine Template
Example 32.1. An XML representation of a virtual machine template
<template href="/api/templates/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000">
<actions>
<link href="/api/templates/00000000-0000-0000-0000-000000000000/export"
rel="export"/>
</actions>
<name>Blank</name>
<description>Blank template</description>
<comment>Blank template</comment>
<link href="/api/templates/00000000-0000-0000-0000-000000000000/disks"
rel="disks"/>
<link href="/api/templates/00000000-0000-0000-0000-000000000000/nics"
rel="nics"/>
<link href="/api/templates/00000000-0000-0000-0000-000000000000/cdroms"
rel="cdroms"/>
<link href="/api/templates/00000000-0000-0000-0000-000000000000/permissions"
rel="permissions"/>
<link href="/api/templates/00000000-0000-0000-0000-000000000000/watchdogs"
rel="watchdogs"/>
<type>server</type>
<status>
<state>ok</state>
</status>
<memory>536870912</memory>
<cpu>
<topology sockets="1" cores="1"/>
<architecture>X86_64<architecture/>
</cpu>
<cpu_shares>0</cpu_shares>
<os type="rhel_6x64">
<boot dev="hd"/>
<boot dev="cdrom"/>;
</os>
<cluster id="00000000-0000-0000-0000-000000000000"
href="/api/clusters/00000000-0000-0000-0000-000000000000"/>
<creation_time>2010-08-16T14:24:29</creation_time>
<origin>ovirt</origin>
<high_availability>
<enabled>true</enabled>
<priority>100</priority>
</high_availability>
<display>
<type>spice</type>
<monitors>1</monitors>
<single_qxl_pci>false</single_qxl_pci>
<allow_override>true</allow_override>
<smartcard_enabled>true</smartcard_enabled>
</display>
<stateless>false</stateless>
<delete_protected>false</delete_protected>
<sso>
<methods>
<method id="GUEST_AGENT">true</enabled>
</methods>
</sso>
<usb>
<enabled>true</enabled>
</usb>
<migration_downtime>-1</migration_downtime>
<version>
<base_template href="/api/templates/00000000-0000-0000-0000-000000000000"
id="00000000-0000-0000-0000-000000000000"/>
<version_number>2</version_number>
<version_name>RHEL65_TMPL_001</version_name>
</version>
</template>32.3. Methods
32.3.1. Creating a New Template
Creation of a new template requires the
name and vm elements. Identify the vm with the id attribute or name element.
Example 32.2. Creating a template from a virtual machine
POST /api/templates HTTP/1.1
Accept: application/xml
Content-type: application/xml
<template>
<name>template1</name>
<vm id="00000000-0000-0000-0000-000000000000"/>
</template>
32.3.2. Creating a New Template Sub Version
Creation of a new template sub version requires the
name and vm elements for the new template, and the base_template and version_name elements for the new template version. The base_template and version_name elements must be specified within a version section enclosed in the template section. Identify the vm with the id attribute or name element.
Example 32.3. Creating a template sub version from a virtual machine
POST /api/templates HTTP/1.1
Accept: application/xml
Content-type: application/xml
<template>
<name>template1_001</name>
<vm id="00000000-0000-0000-0000-000000000000"/>
<version>
<base_template id="00000000-0000-0000-0000-000000000000"/>
<version_name>"template1_001"</version_name>
</version>
</template>32.3.3. Updating a Template
The
name, description, type, memory, cpu topology, os, high_availability, display, stateless, usb and timezone elements can be updated after a template has been created.
Example 32.4. Updating a virtual machine template to contain 1 GB of memory
PUT /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<template>
<memory>1073741824</memory>
</template>
32.3.4. Updating a Template Sub Version
Only the
version_name element can be updated after a template sub version has been created.
Example 32.5. Updating a virtual machine template sub version name
PUT /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<template>
<version>
<version_name>template1_002</version_name>
</version>
</template>
32.4. Actions
32.4.1. Export Template Action
The
templates collection contains an export action.
The export action exports a template to an
Export storage domain. A destination storage domain is specified with a storage_domain reference.
The export action reports a failed action if a virtual machine template of the same name exists in the destination domain. Set the
exclusive parameter to true to change this behavior and overwrite any existing virtual machine template.
Example 32.7. Action to export a template to an export storage domain
POST /api/templates/00000000-0000-0000-0000-000000000000/export HTTP/1.1
Accept: application/xml
Content-type: application/xml
<action>
<storage_domain id="00000000-0000-0000-0000-000000000000"/>
<exclusive>true<exclusive/>
</action>
Chapter 33. Virtual Machine Pools
33.1. Virtual Machine Pool Elements
The
vmpools collection provides information about the virtual machine pools in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="vmpools" link obtained from the entry point URI.
The following table shows specific elements contained in a virtual machine pool resource representation.
Table 33.1. Virtual machine pool elements
| Element | Type | Description | Properties |
|---|---|---|---|
name | string | A user-supplied, human readable name for the pool. The name is unique across all pool resources. |
|
description | string | A user-supplied, human readable description of the virtual machine pool. | |
link rel="permissions" | relationship | A link to the permissions sub-collection for virtual machine pool permissions. | |
size | integer | The number of virtual machines in the pool. | |
cluster id= | GUID | A reference to the cluster resource in which virtual machines in this pool run. |
|
template id= | GUID | A reference to the template resource on which virtual machines in this pool are based. |
|
prestarted_vms | integer | The number of prestarted virtual machines in the virtual machine pool. | |
max_user_vms | integer | The maximum number of virtual machines any one user can take from the virtual machine pool. |
Important
The API as documented in this chapter is experimental and subject to change. It is not covered by the backwards compatibility statement.
33.2. XML Representation of a Virtual Machine Pool
Example 33.1. An XML representation of a virtual machine pool
<vmpool href="/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e">
id="2d2d5e26-1b6e-11e1-8cda-001320f76e8e"
<actions>
<link href="/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e/allocatevm"
rel="allocatevm"/>
</actions>
<name>VMPool1</name>
<description>Virtual Machine Pool 1</description>
<size>2</size>
<cluster href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
id="99408929-82cf-4dc7-a532-9d998063fa95"
<template href="/api/templates/00000000-0000-0000-0000-000000000000"/>
id="00000000-0000-0000-0000-000000000000"
<prestarted_vms>0</prestarted_vms>
<max_user_vms>1</max_user_vms>
</vmpool>33.3. Methods
33.3.1. Creating a New Virtual Machine Pool
A new pool requires the
name, cluster and template elements. Identify the cluster and template with the id attribute or name element.
Example 33.2. Creating a virtual machine pool
POST /api/vmpools HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vmpool>
<name>VM_Pool_A</name>
<cluster href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
id="99408929-82cf-4dc7-a532-9d998063fa95"
<template href="/api/templates/00000000-0000-0000-0000-000000000000"/>
id="00000000-0000-0000-0000-000000000000"
</vmpool>33.3.2. Updating a Virtual Machine Pool
The
name, description, size, prestarted_vms and max_user_vms can be updated after the virtual machine has been created.
Example 33.3. Updating a virtual machine pool
PUT /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vmpool>
<name>VM_Pool_B</name>
<description>Virtual Machine Pool B</description>
<size>3</size>
<prestarted_vms>1</size>
<max_user_vms>2</size>
</vmpool>33.4. Actions
33.4.1. Allocate Virtual Machine Action
The allocate virtual machine action allocates a virtual machine in the virtual machine pool.
Example 33.5. Action to allocate a virtual machine from a virtual machine pool
POST /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e/allocatevm HTTP/1.1 Accept: application/xml Content-type: application/xml <action/>
Chapter 34. Domains
34.1. Domain Elements
The API provides the ability to access user and group information from the organization's directory service using the
domains collection. Domain information is referenced with the rel="domains" link.
Table 34.1. Domain elements
| Element | Type | Description |
|---|---|---|
name | string | The domain name. |
link rel="users" | relationship | A link to the sub-collection for users associated with this domain. |
link rel="groups" | relationship | A link to the sub-collection for groups associated with this domain. |
The links to
users and groups sub-collections also accept search queries.
Note
The
domains collection and its sub-collections are read-only.
34.2. XML Representation of a Domain Resource
Example 34.1. An XML representation of a domain resource
<domain id="77696e32-6b38-7268-6576-2e656e676c61"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61">
<name>domain.example.com</name>
<link rel="users"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users"/>
<link rel="groups"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups"/>
<link rel="users/search"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
users?search={query}"/>
<link rel="groups/search"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
groups?search={query}"/>
</domain>
34.3. Sub-Collections
34.3.1. Domain Users Sub-Collection
The
users sub-collection contains all users in the directory service. This information is used to add new users to the Red Hat Enterprise Virtualization environment.
Table 34.2. Domain user elements
| Element | Type | Description |
|---|---|---|
name | string | The name of the user. |
last_name | string | The surname of the user. |
user_name | string | The user name from directory service. |
domain id | GUID | The containing directory service domain. |
groups | complex | A list of directory service groups for this user. |
Example 34.2. An XML representation of a user in the users sub-collection
<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users/
d3b4e7be-5f57-4dac-b937-21e1771a501f">
<name>RHEV-M Admin</name>
<user_name>rhevmadmin@domain.example.com</user_name>
<domain id="77696e32-6b38-7268-6576-2e656e676c61"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
<groups>
<group>
<name>domain.example.com/Users/Enterprise Admins</name>
</group>
<group>
<name>domain.example.com/Users/Domain Admins</name>
</group>
...
</groups>
</user>
34.3.2. Domain Groups Sub-Collection
The
groups sub-collection contains all groups in the directory service. A domain group resource contains a set of elements.
Table 34.3. Domain group elements
| Element | Type | Description |
|---|---|---|
name | string | The name of the group. |
domain id | GUID | The containing directory service domain. |
Example 34.3. An XML representation of a group in the groups sub-collection
<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups/
85bf8d97-273c-4a5c-b801-b17d58330dab">
<name>example.com/Users/Enterprise Admins</name>
<domain id="77696e32-6b38-7268-6576-2e656e676c61"
href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
</group>
Chapter 35. Groups
35.1. Imported Group Elements
The
groups collection contains imported groups from directory services. A group resource contains a set of elements.
Table 35.1. Imported group elements
| Element | Type | Description |
|---|---|---|
link rel="tags" | relationship | A link to the tags sub-collection for tags attached to this group. |
link rel="permissions" | relationship | A link to the permissions sub-collection for permissions attached to this group. |
link rel="roles" | relationship | A link to the roles sub-collection for roles attached to this group. |
35.2. XML Representation of a Group Resource
Example 35.1. An XML representation of a group resource
<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab">
<name>Everyone</name>
<link rel="tags"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/tags"/>
<link rel="permissions"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/permissions"/>
<link rel="roles"
href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/roles"/>
<domain_entry_id>
65656530303030302D303030302D303030302D303030
</domain_entry_id>
<namespace>*</namespace>
</group>
35.3. Adding a Group from a Directory Service
The API adds existing directory service groups to the Red Hat Enterprise Virtualization Manager database with a
POST request to the groups collection.
Example 35.2. Adding a group from a directory service
POST /api/group HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<group>
<name>www.example.com/accounts/groups/mygroup</name>
<domain>
<name>example.com</name>
</domain>
</group>
Chapter 36. Roles
36.1. Role Elements
The
rel="roles" link obtained from the entry point URI provides access to a static set of system roles. Each individual role element contains the following:
Table 36.1. Role elements
| Element | Type | Description | Properties |
|---|---|---|---|
link="permits" | relationship | A link to the permits sub-collection for role permits. |
|
mutable | Boolean: true or false | Defines the ability to update or delete the role. Roles with mutable set to false are roles built into the Red Hat Enterprise Virtualization environment. |
|
administrative | Boolean: true or false | Defines the role as administrative-only. |
36.2. XML Representation of the Roles Collection
Example 36.1. An XML representation of the roles collection
<roles>
<role id="00000000-0000-0000-0000-000000000001"
href="/api/roles/00000000-0000-0000-0000-000000000001">
<name>SuperUser</name>
<description>Roles management administrator</description>
<link rel="permits"
href="/api/roles/00000000-0000-0000-0000-000000000001/permits"/>
<mutable>false</mutable>
<administrative>true</administrative>
</role>
<role id="00000000-0000-0000-0001-000000000001"
href="/api/roles/00000000-0000-0000-0001-000000000001">
<name>RHEVMUser</name>
<description>RHEVM user</description>
<link rel="permits"
href="/api/roles/00000000-0000-0000-0001-000000000001/permits"/>
<mutable>false</mutable>
<administrative>false</administrative>
</role>
<role id="00000000-0000-0000-0001-000000000002"
href="/api/roles/00000000-0000-0000-0001-000000000002">
<name>RHEVMPowerUser</name>
<description>RHEVM power user</description>
<link rel="permits"
href="/api/roles/00000000-0000-0000-0001-000000000002/permits"/>
<mutable>false</mutable>
<administrative>false</administrative>
</role>
</roles>
36.3. Methods
36.3.1. Creating a Role
Creation of a role requires values for
name, administrative and a list of initial permits.
Example 36.2. Creating a role
POST /api/roles HTTP/1.1
Accept: application/xml
Content-type: application/xml
<role>
<name>Finance Role</name>
<administrative>true</administrative>
<permits>
<permit id="1"/>
</permits>
</role>
36.3.2. Updating a Role
The
name, description and administrative elements are updatable post-creation.
Example 36.3. Updating a role
PUT /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<role>
<name>Engineering Role</name>
<description>Standard users in the Engineering Role</description>
<administrative>false</administrative>
</role>
36.4. Roles Permits Sub-Collection
36.4.1. Roles Permits Sub-Collection
Each role contains a set of allowable actions, or
permits, which the API lists in capabilities.
A role's
permits are listed as a sub-collection:
Example 36.5. Listing a role's permits
GET /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<permits>
<permit id="1"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
<name>create_vm</name>
<administrative>false</administrative>
<role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
</permit>
...
</permits>
36.4.2. Assign a Permit to a Role
Assign a
permit to a role with a POST request to the permits sub-collection. Use either an id attribute or a name element to specify the permit to assign.
Example 36.6. Assign a permit to a role
POST /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<permit id="1"/>
HTTP/1.1 201 Created
Content-Type: application/xml
<permits>
<permit id="1"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
<name>create_vm</name>
<administrative>false</administrative>
<role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
</permit>
</permits>
Chapter 37. Users
37.1. User Elements
Users are exposed in a top-level collection and are referenced with the
rel="users" link. Individual user elements contain the following:
Table 37.1. User elements
| Element | Type | Description | Properties |
|---|---|---|---|
user_name | string | The user principal name (UPN). The UPN is used as a more convenient identifier when adding a new user. |
|
link rel="tags" | relationship | A link to the tags sub-collection for user resources. | |
link rel="roles" | relationship | A link to the roles sub-collection for user resources. | |
name | string | A free-text name for the user. |
|
domain | string | The containing directory service domain. |
|
groups | complex | A list of directory service groups for this user. |
|
37.2. XML representation of a User Resource
Example 37.1. An XML representation of a user resource
GET /api/users HTTP/1.1
Accept: application/xml
<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1">
<name>RHEV-M Admin</name>
<actions/>
<link rel="roles"
href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles"/>
<link rel="tags"
href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/tags"/>
<domain>domain.example.com</domain>
<logged_in>false</logged_in>
<user_name>rhevmadmin@domain.example.com</user_name>
<groups>
<group>Group Policy Creator Owners@domain.example.com/Users</group>
<group>Domain Admins@domain.example.com/Users</group>
<group>Enterprise Admins@domain.example.com/Users</group>
<group>Schema Admins@domain.example.com/Users</group>
<group>Administrators@domain.example.com/Builtin</group>
</groups>
</user>
37.3. Methods
37.3.1. Adding a User
The API adds an existing directory service user to the Red Hat Enterprise Virtualization Manager database with a
POST request to the users collection. The client-provided new user representation includes an embedded roles list with at least one initial role to assign to the user. For example, the following request assigns two initial roles to the user joe@domain.example.com:
Example 37.2. Adding a user from directory service and assigning two roles
POST /api/users HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<user>
<user_name>joe@domain.example.com</user_name>
<roles>
<role>
<name>RHEVMPowerUser</name>
</role>
<role id="00000000-0000-0000-0001-000000000003"/>
</roles>
</user>
The new user is identified either by Red Hat Enterprise Virtualization Manager user ID or via the directory service user principal name (UPN). The user ID format reported from the directory service domain might be different to the expected Red Hat Enterprise Virtualization Manager format, such as in LDIF
[6] , the ID has the opposite byte order and is base-64 encoded. Hence it is usually more convenient to refer to the new user by UPN.
Note
The user exists in the directory service domain before it is added to the Red Hat Enterprise Virtualization Manager database. An API user has the option to query this domain through the
domains collection prior to creation of the user.
Roles are identified either by name or ID. The example above shows both approaches.
37.3.2. Adding Roles to a User
Further roles are attached or detached with
POST or DELETE requests to the roles sub-collection of an individual user. The example below illustrates how the API adds the RHEVMVDIUser role to the role assignments for a particular user.
Note
The embedded user roles list of the
user element is only used for the initial creation. All interactions post-creation with the user's role assignments go through the roles sub-collection.
Example 37.3. Adding roles to a user
POST /api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<role>
<name>RHEVMVDIUser</name>
</role>
Chapter 38. Tags
38.1. Tag Elements
The
tags collection provides information about tags in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="tags" link obtained from the entry point URI.
The following table shows specific elements contained in a tag resource representation.
Table 38.1. Tag elements
| Element | Type | Description | Properties |
|---|---|---|---|
host | GUID | A reference to the host which the tag is attached. |
|
user | GUID | A reference to the user which the tag is attached. |
|
vm | GUID | A reference to the VM which the tag is attached. |
|
parent | complex | A reference to the VM which the tag is attached. |
38.2. XML Representation of a Tag Resource
Example 38.1. An XML representation of a tag resource
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
<name>Finance</name>
<description>Resources for the Finance department</description>
<parent>
<tag id="-1" href="/api/tags/-1"/>
</parent>
</tag>
38.3. Associating Tags
38.3.1. Associating Tags With a Host, User or VM
The collection referenced by
link rel="tags" from a host, user or vms represents the set of tags associated with the entity.
These
tag representations also contain a host id, user id or vm id reference to the entity in question.
Associating a tag with an entity is achieved by
POSTing a tag reference (identifying the tag either by its id or name) to the collection.
Example 38.2. Associating a tag with a virtual machine
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<name>Finance</name>
</tag>
HTTP/1.1 201 Created
Content-Type: application/xml
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/
f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
<name>Finance</name>
<description>Resources for the Finance department</description>
<vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>
38.3.2. Removing a Tag
Removing an association is achieved with a
DELETE request to the appropriate element in the collection.
Example 38.3. Removing a tag from a virtual machine
DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1 HTTP/1.1 204 No Content
38.3.3. Querying a Collection for Tagged Resources
To query the set of entities associated with a given tag, the
collection/search URI template for the appropriate collection should be used to search for entities matching tag=MyTag.
Example 38.4. Querying a collection for tagged resources
GET /api/vms?search=tag%3DFinance HTTP/1.1
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<vms>
<vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
...
</vm>
...
</vms>
38.4. Parent Tags
38.4.1. Parent Tags
An API user assigns a
parent element to a tag to create a hierarchical link to a parent tag. The tags are presented as a flat collection, which descends from the root tag, with tag representations containing a link element to a parent tag
Note
The
root tag is a special pseudo-tag assumed as the default parent tag if no parent tag is specified. The root tag cannot be deleted nor assigned a parent tag.
This tag hierarchy is expressed in the following way:
Example 38.5. Tag Hierarchy
<tags>
<tag id="-1" href="/api/tags/-1">
<name>root</name>
<description>root</description>
<parent>
<tag id="-1" href="/api/tags/-1"/>
</parent>
</tag>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
<name>Finance</name>
<description>Resources for the Finance department</description>
<parent>
<tag id="-1" href="/api/tags/-1"/>
</parent>
</tag>
<tag id="ac18dabf-23e5-12be-a383-a38b165ca7bd"
href="/api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd">
<name>Billing</name>
<description>Billing Resources</description>
<parent>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
</parent>
</tag>
</tags>
In this XML representation, the tags follow this hierarchy:
root (id: -1)
- Finance (id: f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e)
- Billing (id: ac18dabf-23e5-12be-a383-a38b165ca7bd)
38.4.2. Setting a Parent Tag
POSTing a new tag with a parent element creates an association with a parent tag, using either the id attribute or the name element to reference the parent tag
Example 38.6. Setting an association with a parent tag with the id attribute
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<tag>
<name>Billing</name>
<description>Billing Resources</description>
<parent>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
</parent>
</tag>
Example 38.7. Setting an association with a parent tag with the name element
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml
<tag>
<name>Billing</name>
<description>Billing Resources</description>
<parent>
<tag>
<name>Finance</name>
</tag>
</parent>
</tag>
38.4.3. Changing a Parent Tag
A tag changes a parent using a
PUT request:
Example 38.8. Changing the parent tag
PUT /api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<tag>
<parent>
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
</parent>
</tag>
Chapter 39. Events
39.1. Event Elements
The
rel="events" link obtained from the entry point URI accesses the events collection and lists system events from Red Hat Enterprise Virtualization Manager.
Table 39.1. Event elements
| Element | Type | Description |
|---|---|---|
description | string | A description of the system event |
code | integer | The integer event code. |
severity | One of normal, warning, error or alert | The level of severity for the event. |
time | xsd:dateTime format: YYYY-MM-DDThh:mm:ss | The timestamp indicating when the event happened. |
user id | GUID | The identification code for the user who triggered the event. |
Note
The
events collection is read-only.
39.2. XML Representation of the Events Collection
Example 39.1. An XML representation of the events collection
<events>
<event id="537" href="/api/events/537">
<description>User vdcadmin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-01-12T10:48:27.827+02:00</time>
<user id="9b9002d1-ec33-4083-8a7b-31f6b8931648"
href="/api/users/9b9002d1-ec33-4083-8a7b-31f6b8931648"/>
</event>
...
</events>
39.3. XML Representation of a Virtual Machine Creation Event
In addition to
user, an event representation also contains a set of XML element relationships to resources relevant to the event.
Example 39.2. An XML representation of a virtual machine creation event
<event id="635" href="/api/events/635">
<description>VM bar was created by rhevadmin.</description>
<code>34</code>
<severity>normal</severity>
<time>2011-07-11T16:32:03.172+02:00</time>
<user id="4621b611-43eb-4d2b-ae5f-1180850268c4"
href="/api/users/4621b611-43eb-4d2b-ae5f-1180850268c4"/>
<vm id="9b22d423-e16b-4dd8-9c06-c8e9358fbc66"
href="/api/vms/9b22d423-e16b-4dd8-9c06-c8e9358fbc66"/>
<storage_domain id="a8a0e93d-c570-45ab-9cd6-3c68ab31221f"
href="/api/storagedomains/a8a0e93d-c570-45ab-9cd6-3c68ab31221f"/>
</event>
This example representation provides XML element relationships to a virtual machine resource and a storage domain resource.
39.4. Searching Events
The
events collection provides search queries similar to other resource collections. An additional feature when searching the events collection is the ability to search from a certain event. This queries all of events since a specified event.
Querying from an event requires an additional
from parameter added before the search query. This from argument references an event id code.
Example 39.3. Searching from an event
GET /api/events;from=1012?search=type%3D30 HTTP/1.1 Accept: application/xml
This displays all events with
type set to 30 since id="1012"
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
<event id="1018" href="/api/events/1018">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-07-11T14:03:22.485+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
<event id="1016" href="/api/events/1016">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-07-11T14:03:07.236+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
<event id="1014" href="/api/events/1014">
<description>User admin logged in.</description>
<code>30</code>
<severity>normal</severity>
<time>2011-07-11T14:02:16.009+10:00</time>
<user id="80b71bae-98a1-11e0-8f20-525400866c73"
href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
</event>
</events>
Example 39.4. Searching using a specific event severity
GET /api/events?search=severity>normal HTTP/1.1 Accept: application/xml
This displays all events with severity higher than
normal. Severity levels include normal, warning, error and alert.
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
<event id="2823" href="/api/events/2823">
<description>Host Host-05 has time-drift of 36002 seconds while maximum configured value is 300 seconds.</description>
<code>604</code>
<severity>warning</severity>
<time>2015-07-11T14:03:22.485+10:00</time>
<host href= "/api/hosts/44e52bb2-27d6-4d35-8038-0c4b4db89789" id="44e52bb2-27d6-4d35-8038-0c4b4db89789"/>
<cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
<origin>oVirt</origin>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
</event>
...
</events>
39.5. Paginating Events
A virtualization environment generates a large amount of events after a period of time. However, the API only displays a default number of events for one search query. To display more than the default, the API separates results into pages with the
page command in a search query.
The following search query tells the API to paginate results using a
page value in combination with the sortby clause:
sortby time asc page 1
The
sortby clause defines the base element to order of the results and whether the results are ascending or descending. For search queries of events, set the base element to time and the order to ascending (asc) so the API displays all events from the creation of your virtualization environment.
The
page condition defines the page number. One page equals the default number of events to list. Pagination begins at page 1. To view more pages, increase the page value:
sortby time asc page 2
sortby time asc page 3
sortby time asc page 4
Example 39.5. Paginating events
This example paginates
event resources. The URL-encoded request is:
GET /api/events?search=sortby%20time%20asc%20page%201 HTTP/1.1 Accept: application/xml
Increase the
page value to view the next page of results.
GET /api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1 Accept: application/xml
Use an additional
from argument to set the starting id.
GET /api/events?search=sortby%20time%20asc%20page%202&from=30 HTTP/1.1 Accept: application/xml
Part IV. The Python Sofware Development Kit
Table of Contents
- 40. Software Development Kit Overview
- 41. Python Quick Start Example
- 41.1. Python Quick Start Introduction
- 41.2. Example: Accessing the API Entry Point using Python
- 41.3. Example: Listing the Data Center Collection using Python
- 41.4. Example: Listing the Cluster Collection using Python
- 41.5. Example: Listing the Logical Networks Collection using Python
- 41.6. Example: Listing the Host Collection using Python
- 41.7. Example: Listing the ISO Files in an ISO Storage Domain
- 41.8. Example: Listing the Size of a Virtual Machine
- 41.9. Example: Approving a Host using Python
- 41.10. Example: Creating NFS Data Storage using Python
- 41.11. Example: Creating NFS ISO Storage using Python
- 41.12. Example: Attaching Storage Domains to a Data Center using Python
- 41.13. Example: Activating Storage Domains using Python
- 41.14. Example: Creating a Virtual Machine using Python
- 41.15. Example: Creating a Virtual Machine NIC using Python
- 41.16. Example: Creating a Virtual Machine Storage Disk using Python
- 41.17. Example: Attaching an ISO Image to a Virtual Machine using Python
- 41.18. Example: Detaching a Disk using Python
- 41.19. Example: Starting a Virtual Machine using Python
- 41.20. Example: Starting a Virtual Machine with Overridden Parameters using Python
- 41.21. Example: Starting a Virtual Machine with Cloud-Init using Python
- 41.22. Example: Checking System Events using Python
- 42. Using the Software Development Kit
- 42.1. Connecting to the API using Python
- 42.2. Resources and Collections
- 42.3. Retrieving Resources from a Collection
- 42.4. Retrieving a Specific Resource from a Collection
- 42.5. Retrieving a List of Resources from a Collection
- 42.6. Adding a Resource to a Collection
- 42.7. Updating a Resource in a Collection
- 42.8. Removing a Resource from a Collection
- 42.9. Handling Errors
- 43. Python Reference Documentation
Chapter 40. Software Development Kit Overview
40.1. Overview
The Python software development kit is a collection of classes and functions that allows you to interact with the Red Hat Enterprise Virtualization Manager in Python-based projects. By downloading these classes and functions and adding them to your project, you can access a range of functionality for high-level automation of administrative tasks.
The Python software development kit uses the rhevm-sdk-python package, which is available to systems subscribed to a
Red Hat Enterprise Virtualization entitlement pool in Red Hat Subscription Manager.
40.2. Prerequisites
To install the Python software development kit, you must have:
- A system where Red Hat Enterprise Linux 6.6 or 7 is installed. Both the Server and Workstation variants are supported.
- A subscription to Red Hat Enterprise Virtualization entitlements.
Important
The rhevm-sdk-python package must be installed on each system where scripts that use the software development kit will be run.
Important
The software development kit is an interface for the Red Hat Enterprise Virtualization REST API. As such, you must use the version of the software development kit that corresponds to the version of your Red Hat Enterprise Virtualization environment. For example, if you are using Red Hat Enterprise Virtualization 3.5, you must use the version of the software development kit designed for 3.5.
40.3. Installing the Python Software Development Kit
Install the Python software development kit.
Procedure 40.1. Installing the Python Software Development Kit
- Ensure your system is subscribed to the
Red Hat Enterprise Virtualizationentitlement in Red Hat Subscription Manager:# subscription-manager list --available | grep -A8 "Red Hat Enterprise Virtualization" # subscription-manager attach --pool=pool_id # subscription-manager repos --enable=rhel-6-server-rhevm-3.6-beta-rpms
- Install the required packages:
# yum install rhevm-sdk-python
The Python software development kit and accompanying documentation are downloaded to the
/usr/lib/python2.7/site-packages/ovirtsdk/ directory, and can now be added to Python projects.
Chapter 41. Python Quick Start Example
- 41.1. Python Quick Start Introduction
- 41.2. Example: Accessing the API Entry Point using Python
- 41.3. Example: Listing the Data Center Collection using Python
- 41.4. Example: Listing the Cluster Collection using Python
- 41.5. Example: Listing the Logical Networks Collection using Python
- 41.6. Example: Listing the Host Collection using Python
- 41.7. Example: Listing the ISO Files in an ISO Storage Domain
- 41.8. Example: Listing the Size of a Virtual Machine
- 41.9. Example: Approving a Host using Python
- 41.10. Example: Creating NFS Data Storage using Python
- 41.11. Example: Creating NFS ISO Storage using Python
- 41.12. Example: Attaching Storage Domains to a Data Center using Python
- 41.13. Example: Activating Storage Domains using Python
- 41.14. Example: Creating a Virtual Machine using Python
- 41.15. Example: Creating a Virtual Machine NIC using Python
- 41.16. Example: Creating a Virtual Machine Storage Disk using Python
- 41.17. Example: Attaching an ISO Image to a Virtual Machine using Python
- 41.18. Example: Detaching a Disk using Python
- 41.19. Example: Starting a Virtual Machine using Python
- 41.20. Example: Starting a Virtual Machine with Overridden Parameters using Python
- 41.21. Example: Starting a Virtual Machine with Cloud-Init using Python
- 41.22. Example: Checking System Events using Python
41.1. Python Quick Start Introduction
This chapter provides a series of examples demonstrating the steps to create a virtual machine within a basic Red Hat Enterprise Virtualization environment, using the Python SDK.
These examples use the ovirtsdk Python library provided by the rhevm-sdk-python package. This package is available to systems subscribed to a
Red Hat Enterprise Virtualization entitlement pool in Red Hat Subscription Manager. See Section 40.3, “Installing the Python Software Development Kit” for more information on subscribing your system(s) to download the software.
You will also need:
- A networked installation of Red Hat Enterprise Virtualization Manager.
- A networked and configured Red Hat Enterprise Virtualization Hypervisor.
- An ISO image file containing an operating system for installation on a virtual machine.
- A working understanding of both the logical and physical objects that make up a Red Hat Enterprise Virtualization environment.
- A working understanding of the Python programming language.
Important
All Python examples include placeholders for authentication details (USER for user name, and PASS for password). Ensure all requests performed with Python fulfill the authentication requirements of your environment.
Note
Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for the
id attribute for each resource. Identifier codes in these examples might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.
Note
These Python examples contain only basic exception and error handling logic. For more information on the exception handling specific to the SDK, refer to the pydoc for the
ovirtsdk.infrastructure.errors module.
$ pydoc ovirtsdk.infrastructure.errors
41.2. Example: Accessing the API Entry Point using Python
The ovirtsdk Python library provides the
API class, which acts as the entry point for the API.
Example 41.1. Accessing the API entry point using Python
This python example connects to an instance of the REST API provided by the Red Hat Enterprise Virtualization Manager at
rhevm.demo.redhat.com. To connect the example creates an instance of the API class If connection was successful a message is printed. Finally the disconnect() method of the API class is called to close the connection.
The parameters provided to the constructor for the
The constructor for the
API class in this example are:
- The
urlof the Manager to which to connect. - The
usernameof the user by which to authenticate. - The
passwordof the user by which to authenticate. - The
ca_file, which is the path to a certificate. The certificate is expected to be a copy of the one for the Manager's Certificate Authority. It can be obtained fromhttps://HOST/ca.crt.
API class supports other parameters. Only mandatory parameters are specified in this example.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
print "Connected to %s successfully!" % api.get_product_info().name
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the connection attempt was successful, the example outputs the text:
Connected to Red Hat Enterprise Virtualization Manager successfully!
41.3. Example: Listing the Data Center Collection using Python
The
API class provides access to a data centers collection, named datacenters. This collection contains all data centers in the environment.
Example 41.2. Listing the Data Center Collection using Python
This Python example lists the data centers in the
datacenters collection. It also outputs some basic information about each data center in the collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
dc_list = api.datacenters.list()
for dc in dc_list:
print "%s (%s)" % (dc.get_name(), dc.get_id())
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
In an environment where only the
Default data center exists, and it is not activated, the example outputs:
Default (d8b74b20-c6e1-11e1-87a3-00163e77e2ed)
41.4. Example: Listing the Cluster Collection using Python
The API class provides a clusters collection, named
clusters. This collection contains all clusters in the environment.
Example 41.3. Listing the clusters collection using Python
This Python example lists the clusters in the
clusters collection. It also outputs some basic information about each cluster in the collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
c_list = api.clusters.list()
for c in c_list:
print "%s (%s)" % (c.get_name(), c.get_id())
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
In an environment where only the
Default cluster exists, the example outputs:
Default (99408929-82cf-4dc7-a532-9d998063fa95)
41.5. Example: Listing the Logical Networks Collection using Python
The
API class provides access to a logical networks collection, named networks. This collection contains all logical networks in the environment.
Example 41.4. Listing the logical networks collection using Python
This Python example lists the logical networks in the
networks collection. It also outputs some basic information about each network in the collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
n_list = api.networks.list()
for n in n_list:
print "%s (%s)" % (n.get_name(), n.get_id())
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
In an environment where only the default management network exists, the example outputs:
rhevm (00000000-0000-0000-0000-000000000009)
41.6. Example: Listing the Host Collection using Python
The
API class provides access to a hosts collection, named hosts. This collection contains all hosts in the environment.
Example 41.5. Listing the host collection using Python
This Python example lists the hosts in the
hosts collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
h_list = api.hosts.list()
for h in h_list:
print "%s (%s)" % (h.get_name(), h.get_id())
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
In an environment where only one host, named
Atlantic, has been attached the example outputs:
Atlantic (5b333c18-f224-11e1-9bdd-00163e77e2ed)
41.7. Example: Listing the ISO Files in an ISO Storage Domain
The
API class provides access to a storage domain collection, named storagedomains. This collection in turn contains a files collection that describes the files in a storage domain.
Example 41.6. Listing the ISO Files in an ISO Storage Domain
This Python example prints a list of the ISO files in each ISO storage domain in the Red Hat Enterprise Virtualization environment:
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
storage_domains = api.storagedomains.list()
for storage_domain in storage_domains:
if(storage_domain.get_type() == "iso"):
print(storage_domain.get_name() + ":\n")
files = storage_domain.files.list()
for file in files:
print(" %s" % file.get_name())
print()
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
41.8. Example: Listing the Size of a Virtual Machine
The
API class provides access to a virtual machine collection, named vms. This collection in turn contains a disks collection that describes the details of each disk attached to a virtual machine.
Example 41.7. Listing the Size of a Virtual Machine
This Python example prints a list of the virtual machines in the Red Hat Enterprise Virtualization environment along with their total disk size in bytes:
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
virtual_machines = api.vms.list()
if len(virtual_machines) > 0:
print("%-30s %s" % ("Name","Disk Size"))
print("==================================================")
for virtual_machine in virtual_machines:
disks = virtual_machine.disks.list()
disk_size = 0
for disk in disks:
disk_size += disk.get_size()
print("%-30s: %d" % (virtual_machine.get_name(), disk_size))
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
41.9. Example: Approving a Host using Python
Red Hat Enterprise Virtualization Hypervisor hosts are added to the Red Hat Enterprise Virtualization Manager during their configuration. Once you have added a Hypervisor it requires approval in the Manager before it can actually be used in the environment.
Example 41.8. Approving a host using Python
This Python example calls the
approve method for a host named Atlantic.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
h = api.hosts.get(name="Atlantic")
if(h.approve()):
print "Host '%s' approved (Status: %s)." % (h.get_name(), h.get_status().get_state())
else:
print "Approval of '%s' failed." % h.get_name()
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
approve request is successful then the script will output:
Host 'Atlantic' approved (Status: Up).
Note that the
status reflects that the host has been approved and is now considered to be up.
41.10. Example: Creating NFS Data Storage using Python
When a Red Hat Enterprise Virtualization environment is first being created it is necessary to define at least a data storage domain, and an ISO storage domain. The data storage domain will be used to store virtual machine disk images while the ISO storage domain will be used to store installation media for guest operating systems.
The
API class provides access to a storage domains collection, named storagedomains. This collection contains all the storage domains in the environment. The storagedomains collection can also be used to add and remove storage domains.
Note
The code provided in this example assumes that the remote NFS share has been pre-configured for use with Red Hat Enterprise Virtualization. Refer to the Red Hat Enterprise Virtualization Administration Guide for more information on preparing NFS shares for use.
Example 41.9. Creating NFS data storage using Python
This Python example adds an NFS data domain to the
storagedomains collection. Adding an NFS storage domain in Python can be broken down into several steps:
- Identify the data center to which the storage must be attached, using the
getmethod of thedatacenterscollection.dc = api.datacenters.get(name="Default")
- Identify the host that must be used to attach the storage, using the
getmethod of thehostscollection.h = api.hosts.get(name="Atlantic")
- Define the
Storageparameters for the NFS storage domain. In this example the NFS location192.0.43.10/storage/datais being used.s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs")
- Request creation of the storage domain, using the
addmethod of thestoragedomainscollection. In addition to theStorageparameters it is necessary to pass:- A name for the storage domain.
- The data center object that was retrieved from the
datacenterscollection. - The host object that was retrieved from the
hostscollection. - The type of storage domain being added (
data,iso, orexport). - The storage format to use (
v1,v2, orv3).
Once these steps are combined, the completed script is:
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
dc = api.datacenters.get(name="Default")
h = api.hosts.get(name="Atlantic")
s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs")
sd_params = params.StorageDomain(name="data1", data_center=dc, host=h, type_="data", storage_format="v3", storage=s)
try:
sd = api.storagedomains.add(sd_params)
print "Storage Domain '%s' added (%s)." % (sd.get_name())
except Exception as ex:
print "Adding storage domain failed: %s" % ex
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
add method call is successful then the script will output:
Storage Domain 'data1' added (bd954c03-d180-4d16-878c-2aedbdede566).
41.11. Example: Creating NFS ISO Storage using Python
To create a virtual machine you must be able to provide installation media for the guest operating system. In a Red Hat Enterprise Virtualization environment you store the installation media on an ISO storage domain.
Note
The code provided in this example assumes that the remote NFS share has been pre-configured for use with Red Hat Enterprise Virtualization. Refer to the Red Hat Enterprise Virtualization Administration Guide for more information on preparing NFS shares for use.
Example 41.10. Creating NFS ISO storage using Python
This Python example adds an NFS ISO domain to the
storagedomains collection. Adding an NFS storage domain in Python can be broken down into several steps:
- Identify the data center to which the storage must be attached, using the
getmethod of thedatacenterscollection.dc = api.datacenters.get( name="Default" )
- Identify the host that must be used to attach the storage, using the
getmethod of thehostscollection.h = api.hosts.get(name="Atlantic")
- Define the
Storageparameters for the NFS storage domain. In this example the NFS location192.0.43.10/storage/isois being used.s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs")
- Request creation of the storage domain, using the
addmethod of thestoragedomainscollection. In addition to theStorageparameters it is necessary to pass:- A name for the storage domain.
- The data center object that was retrieved from the
datacenterscollection. - The host object that was retrieved from the
hostscollection. - The type of storage domain being added (
data,iso, orexport). - The storage format to use (
v1,v2, orv3).
Once these steps are combined, the completed script is:
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
dc = api.datacenters.get(name="Default")
h = api.hosts.get(name="Atlantic")
s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs")
sd_params = params.StorageDomain(name="iso1", data_center=dc, host=h, type_="iso", storage_format="v3", storage=s)
try:
sd = api.storagedomains.add(sd_params)
print "Storage Domain '%s' added (%s)." % (sd.get_name())
except Exception as ex:
print "Adding storage domain failed: %s" % ex
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
add method call is successful then the script will output:
Storage Domain 'iso1' added (789814a7-7b90-4a39-a1fd-f6a98cc915d8).
41.12. Example: Attaching Storage Domains to a Data Center using Python
Once you have added storage domains to Red Hat Enterprise Virtualization you must attach them to a data center and activate them before they will be ready for use.
Example 41.11. Attaching storage domains to a data center using Python
This Python example attaches a data storage domain named
data1, and an ISO storage domain named iso1 to the default data center. The attach action is facilitated by the add method of the data center's storagedomains collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
dc = api.datacenters.get(name="Default")
sd_data = api.storagedomains.get(name="data1")
sd_iso = api.storagedomains.get(name="iso1")
try:
dc_sd = dc.storagedomains.add(sd_data)
print "Attached data storage domain '%s' to data center '%s' (Status: %s)." %
(dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state())
except Exception as ex:
print "Attaching data storage domain to data center failed: %s." % ex
try:
dc_sd = dc.storagedomains.add(sd_iso)
print "Attached ISO storage domain '%s' to data center '%s' (Status: %s)." %
(dc_sd.get_name(), dc.get_name, dc_sd.get_status().get_state())
except Exception as ex:
print "Attaching ISO storage domain to data center failed: %s." % ex
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the calls to the
add methods are successful then the script will output:
Attached data storage domain 'data1' to data center 'Default' (Status: maintenance). Attached ISO storage domain 'iso1' to data center 'Default' (Status: maintenance).
Note that the
status reflects that the storage domains still need to be activated.
41.13. Example: Activating Storage Domains using Python
Once you have added storage domains to Red Hat Enterprise Virtualization and attached them to a data center you must activate them before they will be ready for use.
Example 41.12. Activating storage domains using Python
This Python example activates a data storage domain named
data1, and an ISO storage domain named iso1. Both storage domains are attached to the Default data center. The activate action is facilitated by the activate method of the storage domain.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
dc = api.datacenters.get(name="Default")
sd_data = dc.storagedomains.get(name="data1")
sd_iso = dc.storagedomains.get(name="iso1")
try:
sd_data.activate()
print "Activated data storage domain '%s' in data center '%s' (Status: %s)." %
(sd_data.get_name(), dc.get_name, sd_data.get_status().get_state())
except Exception as ex:
print "Activating data storage domain in data center failed: %s." % ex
try:
sd_iso.activate()
print "Activated ISO storage domain '%s' in data center '%s' (Status: %s)." %
(sd_iso.get_name(), dc.get_name, sd_iso.get_status().get_state())
except Exception as ex:
print "Activating ISO storage domain in data center failed: %s." % ex
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
activate requests are successful then the script will output:
Activated data storage domain 'data1' in data center 'Default' (Status: active). Activated ISO storage domain 'iso1' in data center 'Default' (Status: active).
Note that the
status reflects that the storage domains have been activated.
41.14. Example: Creating a Virtual Machine using Python
Virtual machine creation is performed in several steps. The first step, covered here, is to create the virtual machine object itself.
Example 41.13. Creating a virtual machine using Python
This Python example creates a virtual machine named
These options are combined into a virtual machine parameter object, before using the
vm1. The virtual machine in this example:
- Must have 512 MB of memory, expressed in bytes.
vm_memory = 512 * 1024 * 1024
- Must be attached to the
Defaultcluster, and therefore theDefaultdata center.vm_cluster = api.clusters.get(name="Default")
- Must be based on the default
Blanktemplate.vm_template = api.templates.get(name="Blank")
- Must boot from the virtual hard disk drive.
vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")])
add method of the vms collection to create the virtual machine itself.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
vm_name = "vm1"
vm_memory = 512 * 1024 * 1024
vm_cluster = api.clusters.get(name="Default")
vm_template = api.templates.get(name="Blank")
vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")])
vm_params = params.VM(name=vm_name,
memory=vm_memory,
cluster=vm_cluster,
template=vm_template,
os=vm_os)
try:
api.vms.add(vm=vm_params)
print "Virtual machine '%s' added." % vm_name
except Exception as ex:
print "Adding virtual machine '%s' failed: %s" % (vm_name, ex)
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Virtual machine 'vm1' added.
41.15. Example: Creating a Virtual Machine NIC using Python
To ensure a newly created virtual machine has network access you must create and attach a virtual NIC.
Example 41.14. Creating a virtual machine NIC using Python
This Python example creates an NIC named
These options are combined into an NIC parameter object, before using the
nic1 and attaches it to the virtual machine named vm1. The NIC in this example:
- Must be a
virtionetwork device.nic_interface = "virtio"
- Must be linked to the
rhevmmanagement network.nic_network = api.networks.get(name="rhevm")
add method of the virtual machine's nics collection to create the NIC.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
vm = api.vms.get(name="vm1")
nic_name = "nic1"
nic_interface = "virtio"
nic_network = api.networks.get(name="rhevm")
nic_params = params.NIC(name=nic_name, interface=nic_interface, network=nic_network)
try:
nic = vm.nics.add(nic_params)
print "Network interface '%s' added to '%s'." % (nic.get_name(), vm.get_name())
except Exception as ex:
print "Adding network interface to '%s' failed: %s" % (vm.get_name(), ex)
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Network interface 'nic1' added to 'vm1'.
41.16. Example: Creating a Virtual Machine Storage Disk using Python
To ensure a newly created virtual machine has access to persistent storage you must create and attach a disk.
Example 41.15. Creating a virtual machine storage disk using Python
This Python example creates an 8 GB
These options are combined into a disk parameter object, before using the
virtio disk drive and attaches it to the virtual machine named vm1. The disk in this example:
- must be stored on the storage domain named
data1,disk_storage_domain = params.StorageDomains(storage_domain=[api.storagedomains.get(name="data1")])
- must be 8 GB in size,
disk_size = 8*1024*1024
- must be a
systemtype disk (as opposed todata),disk_type = "system"
- must be
virtiostorage device,disk_interface = "virtio"
- must be stored in
cowformat, anddisk_format = "cow"
- must be marked as a usable boot device.
disk_bootable = True
add method of the virtual machine's disks collection to create the disk itself.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
vm = api.vms.get(name="vm1")
sd = params.StorageDomains(storage_domain=[api.storagedomains.get(name="data1")])
disk_size = 8*1024*1024
disk_type = "system"
disk_interface = "virtio"
disk_format = "cow"
disk_bootable = True
disk_params = params.Disk(storage_domains=sd,
size=disk_size,
type_=disk_type,
interface=disk_interface,
format=disk_format,
bootable=disk_bootable)
try:
d = vm.disks.add(disk_params)
print "Disk '%s' added to '%s'." % (d.get_name(), vm.get_name())
except Exception as ex:
print "Adding disk to '%s' failed: %s" % (vm.get_name(), ex)
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Disk 'vm1_Disk1' added to 'vm1'.
41.17. Example: Attaching an ISO Image to a Virtual Machine using Python
To begin installing a guest operating system on a newly created virtual machine you must attach an ISO file containing the operating system installation media.
Example 41.16. Identifying ISO images
ISO images are found in the
files collection attached to the ISO storage domain. This example lists the contents of the files collection on an ISO storage domain.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
sd = api.storagedomains.get(name="iso1")
iso = sd.files.list()
for i in iso:
print "%s" % i.get_name()
except Exception as ex:
print "Unexpected error: %s" % ex
If successful the script will output an entry like this for each file found in the
files collection:
RHEL6.3-Server-x86_64-DVD1.iso
Note that because files on the ISO domain must be uniquely named the
id and name attributes of the file are shared.
Example 41.17. Attaching an ISO image to a virtual machine using Python
This Python example attaches the
RHEL6.3-Server-x86_64-DVD1.iso ISO image file to the vm1 virtual machine. Once identified the image file is attached using the add method of the virtual machine's cdroms collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
username="USER@DOMAIN",
password="PASS,
ca_file="ca.crt")
sd = api.storagedomains.get(name="iso1")
cd_iso = sd.files.get(name="RHEL6.3-Server-x86_64-DVD1.iso")
cd_vm = api.vms.get(name="vm1")
cd_params = params.CdRom(file=cd_iso)
try:
cd_vm.cdroms.add(cd_params)
print "Attached CD to '%s'." % cd_vm.get_name()
except Exception as ex:
print "Failed to attach CD to '%s': %s" % (cd_vm.get_name(), ex)
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
add request is successful then the script will output:
Attached CD to 'vm1'.
Note
This procedure is for attaching an ISO image to virtual machines with a status of
Down. To attach an ISO to a virtual machine with an Up status, amend the second try statement to the following:
try: cdrom=cd_vm.cdroms.get(id="00000000-0000-0000-0000-000000000000") cdrom.set_file(cd_iso) cdrom.update(current=True) print "Attached CD to '%s'." % cd_vm.get_name() except: print "Failed to attach CD to '%s': %s" % (cd_vm.get_name(), ex)
Example 41.18. Ejecting a cdrom from a Virtual Machine using Python
Eject an ISO from a virtual machine's
cdrom collection.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
username="USER@DOMAIN",
password="PASS,
ca_file="ca.crt")
sd = api.storagedomains.get(name="iso1")
vm = api.vms.get(name="vm1")
try:
vm.cdroms.get(id="00000000-0000-0000-0000-000000000000").delete()
print "Removed CD from '%s'." % vm.get_name()
except Exception as ex:
print "Failed to remove CD from '%s': %s" % (vm.get_name(), ex)
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
41.18. Example: Detaching a Disk using Python
You can use the Python software development kit to detach a virtual disk from a virtual machine.
Example 41.19. Detaching a disk using Python
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
vm = api.vms.get(name="VM_NAME")
disk = vm.disks.get(name="DISK_NAME")
detach = params.Action(detach=True)
disk.delete(action=detach)
print "Detached disk %s successfully!" % disk
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
41.19. Example: Starting a Virtual Machine using Python
Starting a virtual machine
Example 41.20. Starting a virtual machine using Python
This example starts the virtual machine using the
start method.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
vm = api.vms.get(name="vm1")
try:
vm.start()
print "Started '%s'." % vm.get_name()
except Exception as ex:
print "Unable to start '%s': %s" % (vm.get_name(), ex)
api.disconnect()
except Exception as ex:
print "Unexpected error: %s" % ex
If the
start request is successful then the script will output:
Started 'vm1'.
Note that the
status reflects that the virtual machine has been started and is now up.
41.20. Example: Starting a Virtual Machine with Overridden Parameters using Python
Starting a virtual machine with overridden parameters.
Example 41.21. Starting a virtual machine with overridden parameters using Python
This example boots a virtual machine with a Windows ISO and attaches the
virtio-win_x86.vfd floppy disk which contains Windows drivers. This action is equivalent to using the Run Once window in the Administration or User Portal to start a virtual machine.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
except Exception as ex:
print "Failed to connect to API: %s" % ex
try:
vm = api.vms.get(name="Win_machine")
except Exception as ex:
print "Failed to retrieve VM: %s" % ex
cdrom = params.CdRom(file=params.File(id="windows_example.iso"))
floppy = params.Floppy(file=params.File(id="virtio-win_x86.vfd"))
try:
vm.start(
action=params.Action(
vm=params.VM(
os=params.OperatingSystem(
boot=[params.Boot(dev="cdrom")]
),
cdroms=params.CdRoms(cdrom=[cdrom]),
floppies=params.Floppies(floppy=[floppy])
)
)
)
except Exception as ex:
print "Failed to start VM: %s" % ex
Note
The CD image and floppy disk file must be available in the ISO domain already. If not, use the ISO uploader tool to upload the files. See The ISO Uploader Tool for more information.
41.21. Example: Starting a Virtual Machine with Cloud-Init using Python
Starting a virtual machine with Cloud-Init using Python.
Example 41.22. Starting a virtual machine with Cloud-Init using Python
This example shows you how to start a virtual machine using the Cloud-Init tool to set a host name and a static IP for the eth0 interface.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
except Exception as ex:
print "Failed to connect to API: %s" % ex
try:
vm = api.vms.get(name="MyVM")
except Exception as ex:
print "Failed to retrieve VM: %s" % ex
try:
vm.start(
action=params.Action(
vm=params.VM(
initialization=params.Initialization(
cloud_init=params.CloudInit(
host=params.Host(address="MyHost.example.com"),
network_configuration=params.NetworkConfiguration(
nics=params.Nics(
nic=[params.NIC(
name="eth0",
boot_protocol="static",
on_boot=True,
network=params.Network(
ip=params.IP(
address="10.10.10.1",
netmask="255.255.255.0",
gateway="10.10.10.1"
)
)
)
]
)
)
)
)
)
)
)
except Exception as ex:
print "Failed to start VM: %s" % ex
41.22. Example: Checking System Events using Python
Red Hat Enterprise Virtualization Manager records and logs many system events. These event logs are accessible through the user interface, the system log files, and using the API. The ovirtsdk library exposes events using the
events collection.
Example 41.23. Checking System Events using Python
In this example the
events collection is listed. Note that:
- The
queryparameter of thelistmethod is used to ensure that all available pages of results are returned. By default thelistmethod will only return the first page of results which defaults to a maximum of100records in length. - The resultant list is reversed to ensure that events are included in the output in the order that they occurred.
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API (url="https://HOST",
username="USER@DOMAIN",
password="PASS",
ca_file="ca.crt")
event_list = []
event_page_index = 1
event_page_current = api.events.list(query="page %s" % event_page_index)
while(len(event_page_current) != 0):
event_list = event_list + event_page_current
event_page_index = event_page_index + 1
try:
event_page_current = api.events.list(query="page %s" % event_page_index)
except Exception as ex:
print "Error retrieving page %s of list: %s" % (event_page_index, ex)
event_list.reverse()
for event in event_list:
print "%s %s CODE %s - %s" % (event.get_time(),
event.get_severity().upper(),
event.get_code(),
event.get_description())
except Exception as ex:
print "Unexpected error: %s" % ex
Output from this script will look like this - albeit with different events depending on the state of the environment:
2012-09-25T18:40:10.065-04:00 NORMAL CODE 30 - User admin@internal logged in. 2012-09-25T18:40:10.368-04:00 NORMAL CODE 153 - VM vm1 was started by admin@internal (Host: Atlantic). 2012-09-25T18:40:10.470-04:00 NORMAL CODE 30 - User admin@internal logged in.
Chapter 42. Using the Software Development Kit
- 42.1. Connecting to the API using Python
- 42.2. Resources and Collections
- 42.3. Retrieving Resources from a Collection
- 42.4. Retrieving a Specific Resource from a Collection
- 42.5. Retrieving a List of Resources from a Collection
- 42.6. Adding a Resource to a Collection
- 42.7. Updating a Resource in a Collection
- 42.8. Removing a Resource from a Collection
- 42.9. Handling Errors
42.1. Connecting to the API using Python
To connect to the REST API using Python you must create an instance of the
API class from the ovirtsdk.api module. To be able to do this it is necessary to first import the class at the start of the script:
from ovirtsdk.api import API
The constructor of the
API class takes a number of arguments. Supported arguments are:
- url
- Specifies the URL of the Manager to connect to, including the
/apipath. This parameter is mandatory. - username
- Specifies the user name to connect using, in User Principal Name (UPN) format. This parameter is mandatory.
- password
- Specifies the password for the user name provided by the
usernameparameter. This parameter is mandatory. - kerberos
- Uses a valid Kerberos ticket to authenticate the connection. Valid values are
TrueandFalse. This parameter is optional. - key_file
- Specifies a PEM formatted key file containing the private key associated with the certificate specified by
cert_file. This parameter is optional. - cert_file
- Specifies a PEM formatted client certificate to be used for establishing the identity of the client on the server. This parameter is optional.
- ca_file
- Specifies the certificate file of the certificate authority for the server. This parameter is mandatory unless the
insecureparameter is set toTrue. - port
- Specifies the port to connect using, where it has not been provided as component of the
urlparameter. This parameter is optional. - timeout
- Specifies the amount of time in seconds that is allowed to pass before a request is to be considered as having timed out. This parameter is optional.
- persistent_auth
- Specifies whether persistent authentication is enabled for this connection. Valid values are
TrueandFalse. This parameter is optional and defaults toFalse. - insecure
- Allows a connection via SSL without certificate authority. Valid values are
TrueandFalse. If theinsecureparameter is set toFalse- which is the default - then theca_filemust be supplied to secure the connection.This option should be used with caution, as it may allow man-in-the-middle (MITM) attackers to spoof the identity of the server. - filter
- Specifies whether or not user permission based filter is on or off. Valid values are
TrueandFalse. If thefilterparameter is set toFalse- which is the default - then the authentication credentials provided must be those of an administrative user. If thefilterparameter is set toTruethen any user can be used and the Manager will filter the actions available to the user based on their permissions. - debug
- Specifies whether debug mode is enabled for this connection. Valid values are
TrueandFalse. This parameter is optional.
You can communicate with multiple Red Hat Enterprise Virtualization Managers by creating and manipulating separate instances of the ovirtsdk.API Python class.
This example script creates an instance of the
API class, checks that the connection is working using the test() method, and disconnects using the disconnect() method.
from ovirtsdk.api import API
api_instance = API ( url="https://rhevm31.demo.redhat.com",
username="admin@internal",
password="Password",
ca_file="/etc/pki/ovirt-engine/ca.pem")
print "Connected successfully!"
api_instance.disconnect()
For a full list of methods supported by the
API class refer to the pydoc output for the ovirtsdk.api module.
$ pydoc ovirtsdk.api
42.2. Resources and Collections
The RESTful nature of the API is evident throughout the Python bindings for both theoretical and practical reasons. All RESTful APIs have two key concepts that you need to be aware of:
- Collections
- A collection is a set of resources of the same type. The API provides both top-level collections and sub-collections. An example of a top-level collection is the
hostscollection which contains all virtualization hosts in the environment. An example of a sub-collection is thehost.nicscollection which contains resources for all network interface cards attached to a host resource.The interface for interacting with collections provides methods for adding resources (add), getting resources (get), and listing resources (list). - Resources
- A resource in a RESTful API is an object with a fixed interface that also contains a set of attributes that are relevant to the specific type of resource being represented. The interface for interacting with resources provides methods for updating (
update) and deleting (delete) resources. Additionally some resources support actions specific to the resource type. An example is theapprovemethod ofHostresources.
42.3. Retrieving Resources from a Collection
Resources are retrieved from a collection using the
get and list methods.
- get
- Retrieves a single resource from the collection. The item to retrieve is determined based on the name provided as an argument. The
getmethod takes these arguments:name- The name of the resource to retrieve from the collection.id- The globally unique identifier (GUID) of the resource to retrieve from the collection.
- list
- Retrieves any number of resources from the collection. The items to retrieve are determined based on the criteria provided. The
listmethod takes these arguments:**kwargs- A dictionary of additional arguments allowing keyword based filtering.query- A query written in the same format as that used for searches executed using the Red Hat Enterprise Virtualization user interfaces.max- The maximum number of resources to retrieve.case_sensitive- Whether or not search terms are to be treated as case sensitive (TrueorFalse, the default isTrue).
42.4. Retrieving a Specific Resource from a Collection
In these examples a specific resource is retrieved from a collection using the
get method.
Example 42.1. Retrieving a Specific Resource by Name
Retrieving the
Default data center from the datacenters collection using the name parameter of the get method:
dc = api.datacenters.get("Default")
This syntax is equivalent:
dc = api.datacenters.get(name="Default")
42.5. Retrieving a List of Resources from a Collection
In these examples a list of resources is retrieved from a collection using the
list method.
Example 42.2. Retrieving a List of all Resources in a Collection
Retrieving a list of all resources in the
datacenters collection. The query parameter of the list method allows the use of engine based queries. In this way the SDK supports the use of queries in the same format as those executed in the Administration and User Portals. The query parameter is also the mechanism for providing pagination arguments while iterating through the collection.
dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)
while(len(dc_page_current) != 0):
dc_list = dc_list + dc_page_current
dc_page_index = dc_page_index + 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index)
In this example the list of resources contained in the
datacenters collection is ultimately stored in the locally defined dc_list list variable.
Warning
The
list method of a collection is restricted to returning only as many elements as allowed by the SearchResultsLimit Red Hat Enterprise Virtualization Manager configuration key.
To ensure that all records in a the
list are returned it is recommended that you paginate through the results as illustrated in this example.
Alternatively you may choose to set the
max parameter of the list method to the maximum number of records that you wish to retrieve.
Example 42.3. Retrieving a List of Resources in a Collection Matching a Keyword Based Filter
Retrieving a list of all resources in the
datacenters collection that have a storage type of nfs. In this example both the query parameter and **kwargs parameter are supplied. The query is used for pagination in the same way as illustrated in the previous example. The **kwargs parameter is used to filter based on the storage type of the data center.
dc_list = []
dc_page_index = 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})
while(len(dc_page_current) != 0):
dc_list = dc_list + dc_page_current
dc_page_index = dc_page_index + 1
dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})
In this example the list of resources contained in the
datacenters collection with a storage type of nfs is ultimately stored in the locally defined dc_list list variable.
42.6. Adding a Resource to a Collection
The
add method of a collection adds a resource. The resource to be added is created based on the parameters provided. Parameters are provided to the add method using an instance of an object from the ovirtsdk.xml.params module. Which specific class from the module needs to be used varies based on the type of resource being created.
Example 42.4. Adding a Resource to a Collection
In this example a virtual machine resource is created.
vm_params = params.VM(name="DemoVM",
cluster=api.clusters.get("Default"),
template=api.templates.get("Blank"),
memory=536870912)
vm = api.vms.add(vm_params)
While the virtual machine created by this example is not yet ready to run it illustrates the process for creating any Red Hat Enterprise Virtualization resource:
- Create an instance of the parameter object for the type of resource being created.
- Identify the collection to which the resource will be added.
- Call the
addmethod of the collection passing the parameter object as a parameter.
Some parameter objects also have complex parameters of their own.
Example 42.5. Complex Parameters
In this example an NFS data center running in full version 3.2 compatibility mode is being created. To do this it is necessary to first construct a
ovirtsdk.xml.params.Version object. Then this is used as a parameter when creating an instance of a ovirtsdk.xml.params.DataCenter object containing parameters of the data center to be created. The resource is then created using the add method of the datacenters collection.
v_params = params.Version(major=3, minor=2) dc_params = params.DataCenter(name="DemoDataCenter", storage_type="NFS", version=v_params) dc = api.datacenters.add(dc_params)
42.7. Updating a Resource in a Collection
To update a resource you must retrieve it from the collection it resides in, modify the desired parameters, and then call the
update method for the resource to save the changes. Parameter modification is performed by using the set_* methods of the retrieved resource.
Example 42.6. Updating a Resource
In this example the data center named
DemoDataCenter has its description updated.
dc = api.datacenters.get("DemoDataCenter")
dc.set_description("This data center description provided using the Python SDK")
dc.update()
42.8. Removing a Resource from a Collection
To remove a resource you must retrieve it from the collection that contains it and call the
delete method of the resource.
Example 42.7. Removing a Resource from a Collection
Deleting a virtual machine named
DemoVM from the vms collection:
vm = api.vms.get("DemoVM")
vm.delete()
42.9. Handling Errors
Where errors are encountered the Software Development Kit uses exceptions to highlight them. The Software Development Kit defines exception types in addition to those defined by the Python interpreter itself. These exceptions are located in the
ovirtsdk.infrastructure.errors module:
- ConnectionError
- Raised when a transport layer error has occurred.
- DisconnectedError
- Raised when attempting to use SDK after it was explicitly disconnected.
- ImmutableError
- Raised when initiating SDK while an SDK instance already exists under the same domain. Applicable to SDK version 3.2 and higher.
- NoCertificatesError
- Raised when no CA is provided and --insecure is 'False'.
- RequestError
- Raised at any kind of oVirt server error.
- UnsecuredConnectionAttemptError
- Raised when HTTP protocol is used while server is running HTTPS.
- MissingParametersError
- Raised when you are trying to use get() method without providing either id or name.
These exceptions can be caught and handled like any other Python exception:
Example 42.8. Catching a ConnectionError Exception
from ovirtsdk.api import API
from ovirtsdk.xml import params
try:
api = API(url="https://HOST",
user="USER,
pass="PASS,
ca_file="/etc/pki/ovirt-engine/ca.pem")
except ConnectionError, err:
print "Connection failed: %s" % errChapter 43. Python Reference Documentation
43.1. Python Reference Documentation
Documentation generated using pydoc is available for the following modules. The documentation is provided by the rhevm-sdk-python package.
- ovirtsdk.api
- ovirtsdk.infrastructure.brokers
- ovirtsdk.infrastructure.errors
Run the following command on the machine on which the Red Hat Enterprise Virtualization Manager is installed to view the latest version of these documents:
$ pydoc [MODULE]
Part V. The Java Software Development Kit
Table of Contents
- 44. Software Development Kit Overview
- 45. Using the Software Development Kit
- 45.1. Connecting to the Red Hat Enterprise Virtualization Manager
- 45.2. Listing Entities
- 45.3. Modifying the Attributes of Resources
- 45.4. Getting a Resource
- 45.5. Adding Resources
- 45.6. Performing Actions on Resources
- 45.7. Listing Sub-Resources
- 45.8. Getting Sub-Resources
- 45.9. Adding Sub-Resources to a Resource
- 45.10. Modifying Sub-Resources
- 45.11. Performing Actions on Sub-Resources
- 45.12. Recommended Practices
- 45.13. Configuring SSL
Chapter 44. Software Development Kit Overview
44.1. Overview
The Java software development kit is a collection of classes that allows you to interact with the Red Hat Enterprise Virtualization Manager in Java-based projects. By downloading these classes and adding them to your project, you can access a range of functionality for high-level automation of administrative tasks.
The Java software development kit uses the rhevm-sdk-java package, which is available to systems subscribed to a
Red Hat Enterprise Virtualization entitlement pool in Red Hat Subscription Manager.
44.2. Installing the Java Software Development Kit
Install the Java software development kit and accompanying documentation.
Procedure 44.1. Installing the Java Software Development Kit
- Ensure your system is subscribed to the
Red Hat Enterprise Virtualizationentitlement in Red Hat Subscription Manager:# subscription-manager list --available | grep -A8 "Red Hat Enterprise Virtualization" # subscription-manager attach --pool=pool_id # subscription-manager repos --enable=rhel-6-server-rpms # subscription-manager repos --enable=rhel-6-server-rhevm-3.6-beta-rpms # subscription-manager repos --enable=jb-eap-6-for-rhel-6-server-rpms
- Install the required packages:
# yum install rhevm-sdk-java # yum install rhevm-sdk-java-javadoc
The Java software development kit and accompanying documentation are downloaded to the
/usr/share/java/rhevm-sdk-java directory, and can now be added to Java projects.
Chapter 45. Using the Software Development Kit
- 45.1. Connecting to the Red Hat Enterprise Virtualization Manager
- 45.2. Listing Entities
- 45.3. Modifying the Attributes of Resources
- 45.4. Getting a Resource
- 45.5. Adding Resources
- 45.6. Performing Actions on Resources
- 45.7. Listing Sub-Resources
- 45.8. Getting Sub-Resources
- 45.9. Adding Sub-Resources to a Resource
- 45.10. Modifying Sub-Resources
- 45.11. Performing Actions on Sub-Resources
- 45.12. Recommended Practices
- 45.13. Configuring SSL
This chapter outlines several examples of how to use the Java Software Development Kit.
45.1. Connecting to the Red Hat Enterprise Virtualization Manager
The
Api class is the main class you use to connect to and manipulate objects in a Red Hat Enterprise Virtualization environment. There are a number of overloaded constructors to the Api class that allow you to specify different options for connecting to the Red Hat Enterprise Virtualization environment, such as authentication details. This section provides examples of how to use these constructors to initialize an instance of the Api class using basic authentication and using session-based authentication.
Note
For the full list of arguments that can be passed to constructors of the
Api class, see Section 45.1.3, “Arguments to Constructors of the Api Class”.
45.1.1. Basic Authentication
The following is an example of a simple Java SE program that creates a connection with a Red Hat Enterprise Virtualization environment using basic authentication, then gracefully shuts down and closes the connection:
Example 45.1. Basic Authentication
package rhevm;
import org.ovirt.engine.sdk.Api;
import java.io.IOException;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.ovirt.engine.sdk.exceptions.ServerException;
import org.ovirt.engine.sdk.exceptions.UnsecuredConnectionAttemptError;
public class rhevm {
public static void main(String[] args) {
Api api = null;
try {
api = new Api("https://example.com:443/api/", "admin@interal", "p@ssw0rd", "/home/username/server.truststore");
api.shutdown();
} catch (ServerException | UnsecuredConnectionAttemptError | IOException ex) {
Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex);
} finally {
if (api != null) {
try {
api.close();
} catch (Exception ex) {
Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex);
}
}
}
}
}Note
Note that the
Api class does not implement the Autocloseable interface. As such, it is recommended that you shut down instances of the Api class in a finally block as per the above example to ensure the connection with the Red Hat Enterprise Virtualization Manager is closed gracefully.
45.1.2. Session-Based Authentication
The following is an example of a simple Java SE program that creates a connection with a Red Hat Enterprise Virtualization environment using a session ID, then gracefully shuts down and closes the connection:
Example 45.2. Session-Based Authentication
package rhevm;
import org.ovirt.engine.sdk.Api;
import java.io.IOException;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.ovirt.engine.sdk.exceptions.ServerException;
import org.ovirt.engine.sdk.exceptions.UnsecuredConnectionAttemptError;
public class rhevm {
public static void main(String[] args) {
Api api = null;
try {
api = new Api("https://example.com:443/api/", "admin@internal", "p@ssw0rd", "JSESSIONID=XXXXXXXXXXXXXXXXXXXXXXXX", 443, 60, 10, true, "/home/username/server.truststore", "p@ssw0rd", true, false);
api.shutdown();
} catch (ServerException | UnsecuredConnectionAttemptError | IOException ex) {
Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex);
} finally {
if (api != null) {
try {
api.close();
} catch (Exception ex) {
Logger.getLogger(Ovirt.class.getName()).log(Level.SEVERE, null, ex);
}
}
}
}
}Note
Note that the
Api class does not implement the Autocloseable interface. As such, it is recommended that you shut down instances of the Api class in a finally block as per the above example to ensure the connection with the Red Hat Enterprise Virtualization Manager is closed gracefully.
45.1.3. Arguments to Constructors of the Api Class
The following table outlines the key arguments available to constructors for the
Api class.
Table 45.1. Arguments to Constructors of the Api Class
| Method | Argument Type | Description |
|---|---|---|
url | String | The IP address or fully qualified domain name of the Manager. |
user | String | The name of the user with which to connect to the Manager. You must specify both the user name and domain, such as admin@internal. This method must be used together with the password method. |
password | String | The password of the user with which to connect to the Manager. |
sessionID | String | The identifier of a session with which to connect to the Manager. If you have already authenticated with the Manager and a session is available, you can specify this argument instead of specifying a user name and password. The value must be in the format of JSESSIONID=[SESSION_ID]. See Section 17.3, “Authentication Sessions” for instructions on how to determine the session identifier. |
requestTimeout | Integer | The timeout, in seconds, to wait for responses to requests. If a request takes longer than this value to respond, the request is cancelled, and an exception is thrown. This argument is optional. |
sessionTimeout | Integer | The timeout, in minutes, after which an active session is destroyed if no requests are made to the Manager. This argument is optional. |
persistentAuth | Boolean | Enables or disables persistent authentication using cookies. This option is enabled by default, so this method is only required to disable this option. |
noHostVerification | Boolean | Enables or disables verification of the host name in the SSL certificate presented by the server where the Manager is hosted. By default, the identity of host names is verified, and the connection is rejected if the host name is not correct, so this method is only required to disable this option. |
keyStorePath | String | Specifies the location of a file containing the CA certificate used to verify the certificate presented by the server where the Manager is hosted. This method must be used together with the keyStorePassword method. |
keyStorePassword | String | The password used to access the keystore file specified in the keyStorePath method. |
filter | Boolean | Enables or disables filtering of objects based on the permissions of the user making the request. By default, this option is disabled, which allows any user to see all objects in the environment. This method is only required to restrict the objects in the environment to those visible to the user making the request. |
debug | Boolean | Enables or disables debug output. By default, this option is disabled. |
45.2. Listing Entities
The following example outlines how to list entities in the Red Hat Enterprise Virtualization Manager. In this example, the entities to be listed are virtual machines, which are listed using the
getVMs() method of the Api class.
Procedure 45.1. Listing Entities
- Declare a
Listof the type of entity to be listed and use the corresponding method to get the list of entities:List<VM> vms = api.getVMs().list();
45.3. Modifying the Attributes of Resources
The following example outlines how to modify the attributes of a resource. In this example, the attribute to be modified is the description of the virtual machine with the name 'test', which is changed to 'java_sdk'.
Procedure 45.2. Modifying the Attributes of a Resource
- Declare an instance of the resource whose attributes are to be modified:
VM vm = api.getVMs().get("test"); - Set the new value of the attribute:
vm.setDescription("java_sdk"); - Update the virtual machine to apply the change:
VM newVM = vm.update();
45.4. Getting a Resource
In the Java Software Development Kit, resources can be referred to via two attributes:
name, and UUID. Both return an object with the specified attribute if that object exists.
To get a resource using the value of the
name attribute:
VM vm = api.getVMs().get("test");
To get a resource using the value of the
UUID attribute:
VM vm = api.getVMs().get(UUID.fromString("5a89a1d2-32be-33f7-a0d1-f8b5bc974ff6"));45.5. Adding Resources
The following examples outline two ways to add resources to the Red Hat Enterprise Virtualization Manager. In these examples, the resource to be added is a virtual machine.
Example 1
In this example, an instance of the VM class is declared to represent the new virtual machine to be added. Next, the attributes of that virtual machine set to the preferred values. Finally, the new virtual machine is added to the Manager.
org.ovirt.engine.sdk.entities.VM vmParams = new org.ovirt.engine.sdk.entities.VM();
vmParams.setName("myVm");
vmParams.setCluster(api.getClusters().get("myCluster"));
vmParams.setTemplate(api.getTemplates().get("myTemplate"));
...VM vm = api.getVMs().add(vmParams);
Example 2
In this example, an instance of the VM class is declared in the same way as Example 1. However, rather than using the get method to reference existing objects in the Manager, each attribute is referenced by declaring an instance of that attribute. Finally, the new virtual machine is added to the Manager.
org.ovirt.engine.sdk.entities.VM vmParams = new org.ovirt.engine.sdk.entities.VM();
vmParams.setName("myVm");
org.ovirt.engine.sdk.entities.Cluster clusterParam = new Cluster();
clusterParam.setName("myCluster");
vmParams.setCluster(clusterParam);
org.ovirt.engine.sdk.entities.Template templateParam = new Template();
templateParam.setName("myTemplate");
vmParams.setTemplate(templateParam);
...VM vm = api.getVMs().add(vmParams);
45.6. Performing Actions on Resources
The following example outlines how to perform actions on a resource. In this example, a virtual machine with the name 'test' is started.
Procedure 45.3. Performing an Action on a Resource
- Declare an instance of the resource:
VM vm = api.getVMs().get("test"); - Declare action parameters to send to the resource:
Action actionParam = new Action(); org.ovirt.engine.sdk.entities.VM vmParam = new org.ovirt.engine.sdk.entities.VM(); actionParam.setVm(vmParam);
- Perform the action:
Action res = vm.start(actionParam);
Alternatively, you can perform the action as an inner method:
Action res = vm.start(new Action()
{
{
setVm(new org.ovirt.engine.sdk.entities.VM());
}
});
45.7. Listing Sub-Resources
The following example outlines how to list the sub-resources of a resource. In this example, the sub-resources of a virtual machine with the name 'test' are listed.
Procedure 45.4. Listing Sub-Resources
- Declare an instance of the resource whose sub-resources are to be listed:
VM vm = api.getVMs().get("test"); - List the sub-resources:
List<VMDisk> disks = vm.getDisks().list();
45.8. Getting Sub-Resources
The following example outlines how to reference the sub-resources of a resource. In this example, a disk with the name 'my disk' that belongs to a virtual machine with the name 'test' is referenced.
Procedure 45.5. Getting the Sub-Resources of a Resource
- Declare an instance of the resource whose sub-resources are to be referenced:
VM vm = api.getVMs().get("test"); - Declare an instance of the sub-resource to be referenced:
VMDisk disk = vm.getDisks().get("my disk");
45.9. Adding Sub-Resources to a Resource
The following example outlines how to add sub-resources to a resource. In this example, a new disk with a size of '1073741824L', interface 'virtio' and format 'cow' are added to a virtual machine with the name 'test'.
Procedure 45.6. Adding a Sub-Resource to a Resource
- Declare an instance of the resource to which sub-resources are to be added:
VM vm = api.getVMs().get("test"); - Create parameters to define the attributes of the resource:
Disk diskParam = new Disk(); diskParam.setProvisionedSize(1073741824L); diskParam.setInterface("virtio"); diskParam.setFormat("cow"); - Add the sub-resource:
Disk disk = vm.getDisks().add(diskParam);
45.10. Modifying Sub-Resources
The following example outlines how to modify sub-resources. In this example, the name of a disk with the name 'test_Disk1' belonging to a virtual machine with the name 'test' is changed to 'test_Disk1_updated'.
Procedure 45.7. Updating a Sub-Resource
- Declare an instance of the resource whose sub-resource is to be modified:
VM vm = api.getVMs().get("test"); - Declare an instance of the sub-resource to be modified:
VMDisk disk = vm.getDisks().get("test_Disk1"); - Set the new value of the attribute:
disk.setAlias("test_Disk1_updated"); - Update the sub-resource:
VMDisk updateDisk = disk.update();
45.11. Performing Actions on Sub-Resources
The following example outlines how to perform actions on sub-resources. In this example, a disk with the name 'test_Disk1' belonging to a virtual machine with the name 'test' is activated.
Procedure 45.8. Performing an Action on a Sub-Resource
- Declare an instance of the resource containing the sub-resource on which the action is to be performed:
VM vm = api.getVMs().get("test"); - Declare an instance of the sub-resource:
VMDisk disk = vm.getDisks().get("test_Disk1"); - Declare action parameters to send to the sub-resource:
Action actionParam = new Action();
- Perform the action:
Action result = disk.activate(actionParam);
45.12. Recommended Practices
Instances of the
Api class should be shut down in a finally block to free daemon resources:
Api api = new Api(URL, USER, PASSWORD);
try {
api.getDataCenters().add(new DataCenter());
...
}
finally {
api.shutdown();
}
45.13. Configuring SSL
The Red Hat Enterprise Virtualization Manager Java SDK provides full support for HTTP over Secure Socket Layer (SSL) and the IETF Transport Layer Security (TLS) protocol using the Java Secure Socket Extension (JSSE). JSSE has been integrated into the Java 2 platform as of version 1.4 and works with the Java SDK out of the box. On older Java 2 versions, JSSE must be manually installed and configured.
Procedure 45.9. Configuring SSL
- Download the certificate for the Red Hat Enterprise Virtualization Manager:
https://[your manager's address]:[port]/ca.crt
- Generate a keystore:
keytool -import -alias "server.crt truststore" -file ca.crt -keystore server.truststore
- Make the Java software development kit aware of the keystore via one of the following methods:
- Create a keystore lookup path:
$ mkdir ~/.ovirtsdk/ $ cp server.truststore ~/.ovirtsdk/ovirtsdk-keystore.truststore
Once ovirtsdk-keystore.truststore is copied to the~/.ovirtsdkdirectory, it will be used for host identity validation upon handshake with the destination host. - Use the following signature to specify a custom truststore when declaring instances of the
Apiclass:Api api = new Api(url, user, password, "/path/server.truststore");
Note
Validation of host identities can also be disabled. This method should not be used for production systems due to security reasons, unless it is a conscious decision and you are perfectly aware of the security implications of not validating host identity. To disable host identity validation, use the following signature when declaring instances of the
Api class:
Api api = new Api(url, user, password, true);
Appendix A. API Usage with cURL
A.1. API Usage with cURL
This appendix provides instructions on adapting REST requests for use with cURL. cURL is a command line tool for transferring data across various protocols, including HTTP, and supports multiple platforms such as Linux, Windows, Mac and Solaris. Most Linux distributions include cURL as a package.
A.2. Installing cURL
A Red Hat Enterprise Linux user installs cURL with the following terminal command:
yum install curl
For other platforms, seek installation instructions on the cURL website (http://curl.haxx.se/).
A.3. Using cURL
cURL uses a command line interface to send requests to a HTTP server. Integrating a request requires the following command syntax:
Usage: curl [options] uri
The
uri refers to target HTTP address to send the request. This is a location on your Red Hat Enterprise Virtualization Manager host within the API entry point path (/api).
cURL options
- -X COMMAND, --request COMMAND
- The request command to use. In the context of the REST API, use
GET,POST,PUTorDELETE.Example:-X GET - -H LINE, --header LINE
- HTTP header to include with the request. Use multiple header options if more than one header is required.Example:
-H "Accept: application/xml" -H "Content-Type: application/xml" - -u USERNAME:PASSWORD, --user USERNAME:PASSWORD
- The user name and password of the Red Hat Enterprise Virtualization user. This attribute acts as a convenient replacement for the
Authorization:header.Example:-u admin@internal:p@55w0rd! - --cacert CERTIFICATE
- The location of the certificate file for SSL communication to the REST API. The certificate file is saved locally on the client machine. Use the
-kattribute to bypass SSL.Example:--cacert ~/Certificates/rhevm.cer - -d BODY, --data BODY
- The body to send for requests. Use with
POST,PUTandDELETErequests. Ensure to specify theContent-Type: application/xmlheader if a body exists in the request.Example:-d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>"
A.4. Examples
A.4.1. GET Request with cURL
Example A.1. GET request
The following
GET request lists the virtual machines in the vms collection. Note that a GET request does not contain a body.
GET /api/vms HTTP/1.1 Accept: application/xml
Adapt the method (
GET), header (Accept: application/xml) and URI (https://[RHEVM-Host]:443/api/vms) into the following cURL command:
$ curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:443/api/vms
An XML representation of the
vms collection displays.
A.4.2. POST Request with cURL
Example A.2. POST request
The following
POST request creates a virtual machine in the vms collection. Note that a POST request requires a body.
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<name>vm1</name>
<cluster>
<name>default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot dev="hd"/>
</os>
</vm>
Adapt the method (
POST), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:443/api/vms) and request body into the following cURL command:
$ curl -X POST -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os></vm>" https://[RHEVM-Host]:443/api/vms
The REST API creates a new virtual machine and displays an XML representation of the resource.
A.4.3. PUT Request with cURL
Example A.3. PUT request
The following
PUT request updates the memory of a virtual machine resource. Note that a PUT request requires a body.
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<vm>
<memory>1073741824</memory>
</vm>
Adapt the method (
PUT), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) and request body into the following cURL command:
$ curl -X PUT -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><memory>1073741824</memory></vm>" https://[RHEVM-Host]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API updates the virtual machine with a new memory configuration.
A.4.4. DELETE Request with cURL
Example A.4. DELETE request
The following
DELETE request removes a virtual machine resource.
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Adapt the method (
DELETE) and URI (https://[RHEVM-Host]:443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) into the following cURL command:
$ curl -X DELETE -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API removes the virtual machine. Note the
Accept: application/xml request header is optional due to the empty result of DELETE requests.
A.4.5. DELETE Request Including Body with cURL
Example A.5. DELETE request with body
The following
DELETE request force removes a virtual machine resource as indicated with the optional body.
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1 Accept: application/xml Content-type: application/xml <action> <force>true</force> </action>
Adapt the method (
DELETE), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHEVM-Host]:443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) and request body into the following cURL command:
$ curl -X DELETE -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<action><force>true</force></action>" https://[RHEVM-Host]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
The REST API force removes the virtual machine.
Appendix B. UI Plugins
B.1. Installing the Red Hat Support Plug-in
The Red Hat Support Plug-in provides access to Red Hat Access services from the Red Hat Enterprise Virtualization Administration Portal.
Procedure B.1. Installing the Red Hat Support Plug-in
Note
The Red Hat Support Plug-in is installed by default in Red Hat Enterprise Virtualization 3.3. The Red Hat Support Plug-in is not installed by default in Red Hat Enterprise Virtualization 3.2. It is not necessary to run this procedure in Red Hat Enterprise Virtualization 3.3.
- Use yum to install the redhat-support-plugin-rhev plug-in:
#yum install redhat-support-plugin-rhev
Appendix C. Enumerated Value Translation
C.1. Enumerated Value Translation
The API uses Red Hat Enterprise Virtualization Query Language to perform search queries. For more information on the Query Language, read the full specification in Performing Searches in Red Hat Enterprise Virtualization of the Red Hat Enterprise Virtualization Administration Guide.
Note that certain enumerated values in the API require a different search query when using the Query Language. The following table provides a translation for these key enumerated values.
Table C.1. Enumerated Value Translations
|
Resource Type
|
API Enumerable Type
|
API Enumerable Value
|
Query Language Property
|
Query Language Value
|
|---|---|---|---|---|
|
Data Centers
| data_center_states | not_operational | status | notoperational |
|
Hosts
| host_states | non_responsive | status | nonresponsive |
install_failed | installfailed | |||
preparing_for_maintenance | preparingformaintenance | |||
non_operational | nonoperational | |||
pending_approval | pendingapproval | |||
|
Virtual Machines
| vm_states | powering_up | status | poweringup |
powering_down | poweringdown | |||
migrating | migratingfrom | |||
migrating | migratingto | |||
not_responding | notresponding | |||
wait_for_launch | waitforlaunch | |||
reboot_in_progress | rebootinprogress | |||
saving_state | savingstate | |||
restoring_state | restoringstate | |||
image_locked | imagelocked |
Appendix D. Event Codes
D.1. Event Codes
This table lists all event codes.
Table D.1. Event codes
| Code | Name | Severity | Message |
|---|---|---|---|
0 | UNASSIGNED | Info | |
1 | VDC_START | Info | Starting oVirt Engine. |
2 | VDC_STOP | Info | Stopping oVirt Engine. |
12 | VDS_FAILURE | Error | Host ${VdsName} is non responsive. |
13 | VDS_DETECTED | Info | Status of host ${VdsName} was set to ${HostStatus}. |
14 | VDS_RECOVER | Info | Host ${VdsName} is rebooting. |
15 | VDS_MAINTENANCE | Warning | Host ${VdsName} was switched to Maintenance Mode. |
16 | VDS_ACTIVATE | Info | Host ${VdsName} was activated by ${UserName}. |
17 | VDS_MAINTENANCE_FAILED | Error | Failed to switch Host ${VdsName} to Maintenance mode. |
18 | VDS_ACTIVATE_FAILED | Error | Failed to activate Host ${VdsName}.(User: ${UserName}). |
19 | VDS_RECOVER_FAILED | Error | Host ${VdsName} failed to recover. |
20 | USER_VDS_START | Info | Host ${VdsName} was started by ${UserName}. |
21 | USER_VDS_STOP | Info | Host ${VdsName} was stopped by ${UserName}. |
22 | IRS_FAILURE | Error | Failed to access Storage on Host ${VdsName}. |
23 | VDS_LOW_DISK_SPACE | Warning | Warning, Low disk space. Host ${VdsName} has less than ${DiskSpace} MB of free space left on: ${Disks}. |
24 | VDS_LOW_DISK_SPACE_ERROR | Error | Critical, Low disk space. Host ${VdsName} has less than ${DiskSpace} MB of free space left on: ${Disks}. |
25 | VDS_NO_SELINUX_ENFORCEMENT | Warning | Host ${VdsName} does not enforce SELinux. |
26 | IRS_DISK_SPACE_LOW | Warning | Warning, Low disk space. ${StorageDomainName} domain has ${DiskSpace} GB of free space. |
27 | VDS_STATUS_CHANGE_FAILED_DUE_TO_STOP_SPM_FAILURE | Warning | Failed to change status of host '${VdsName}' due to a failure to stop the spm. |
28 | VDS_PROVISION | Warning | Installing OS on Host ${VdsName} using Hostgroup ${HostGroupName}. |
29 | USER_ADD_VM_TEMPLATE_SUCCESS | Info | Template ${VmTemplateName} was created successfully. |
31 | USER_VDC_LOGOUT | Info | User ${UserName} logged out. |
32 | USER_RUN_VM | Info | VM ${VmName} started on Host ${VdsName} |
33 | USER_STOP_VM | Info | VM ${VmName} powered off by ${UserName} (Host: ${VdsName}) (Reason: ${Reason}). |
34 | USER_ADD_VM | Info | VM ${VmName} was created by ${UserName}. |
35 | USER_UPDATE_VM | Info | VM ${VmName} configuration was updated by ${UserName}. |
36 | USER_ADD_VM_TEMPLATE_FAILURE | Error | Failed creating Template ${VmTemplateName}. |
37 | USER_ADD_VM_STARTED | Info | VM ${VmName} creation was initiated by ${UserName}. |
38 | USER_CHANGE_DISK_VM | Info | CD ${DiskName} was inserted to VM ${VmName} by ${UserName} |
39 | USER_PAUSE_VM | Info | VM ${VmName} was suspended by ${UserName} (Host: ${VdsName}). |
40 | USER_RESUME_VM | Info | VM ${VmName} was resumed by ${UserName} (Host: ${VdsName}). |
41 | USER_VDS_RESTART | Info | Host ${VdsName} was restarted by ${UserName}. |
42 | USER_ADD_VDS | Info | Host ${VdsName} was added by ${UserName}. |
43 | USER_UPDATE_VDS | Info | Host ${VdsName} configuration was updated by ${UserName}. |
44 | USER_REMOVE_VDS | Info | Host ${VdsName} was removed by ${UserName}. |
45 | USER_CREATE_SNAPSHOT | Info | Snapshot '${SnapshotName}' creation for VM '${VmName}' was initiated by ${UserName}. |
46 | USER_TRY_BACK_TO_SNAPSHOT | Info | Snapshot-Preview ${SnapshotName} for VM ${VmName} was initiated by ${UserName}. |
47 | USER_RESTORE_FROM_SNAPSHOT | Info | VM ${VmName} restored from Snapshot by ${UserName}. |
48 | USER_ADD_VM_TEMPLATE | Info | Creation of Template ${VmTemplateName} from VM ${VmName} was initiated by ${UserName}. |
49 | USER_UPDATE_VM_TEMPLATE | Info | Template ${VmTemplateName} configuration was updated by ${UserName}. |
50 | USER_REMOVE_VM_TEMPLATE | Info | Removal of Template ${VmTemplateName} was initiated by ${UserName}. |
51 | USER_ADD_VM_TEMPLATE_FINISHED_SUCCESS | Info | Creation of Template ${VmTemplateName} from VM ${VmName} has been completed. |
52 | USER_ADD_VM_TEMPLATE_FINISHED_FAILURE | Error | Failed to complete creation of Template ${VmTemplateName} from VM ${VmName}. |
53 | USER_ADD_VM_FINISHED_SUCCESS | Info | VM ${VmName} creation has been completed. |
54 | USER_FAILED_RUN_VM | Error | Failed to run VM ${VmName} (User: ${UserName}). |
55 | USER_FAILED_PAUSE_VM | Error | Failed to suspend VM ${VmName} (Host: ${VdsName}, User: ${UserName}). |
56 | USER_FAILED_STOP_VM | Error | Failed to power off VM ${VmName} (Host: ${VdsName}, User: ${UserName}). |
57 | USER_FAILED_ADD_VM | Error | Failed to create VM ${VmName} (User: ${UserName}). |
58 | USER_FAILED_UPDATE_VM | Error | Failed to update VM ${VmName} (User: ${UserName}). |
59 | USER_FAILED_REMOVE_VM | Error | |
60 | USER_ADD_VM_FINISHED_FAILURE | Error | Failed to complete VM ${VmName} creation. |
61 | VM_DOWN | Info | VM ${VmName} is down. ${ExitMessage} |
62 | VM_MIGRATION_START | Info | Migration started (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}, User: ${UserName}). |
63 | VM_MIGRATION_DONE | Info | Migration completed (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}, Duration: ${Duration}). |
64 | VM_MIGRATION_ABORT | Warning | Migration failed: ${MigrationError} (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}). |
65 | VM_MIGRATION_FAILED | Error | Migration failed${DueToMigrationError} (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}). |
66 | VM_FAILURE | Error | VM ${VmName} cannot be found on Host ${VdsName}. |
67 | VM_MIGRATION_START_SYSTEM_INITIATED | Info | Migration initiated by system (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}). |
68 | USER_CREATE_SNAPSHOT_FINISHED_SUCCESS | Info | Snapshot '${SnapshotName}' creation for VM '${VmName}' has been completed. |
69 | USER_CREATE_SNAPSHOT_FINISHED_FAILURE | Error | Failed to complete snapshot '${SnapshotName}' creation for VM '${VmName}'. |
70 | USER_RUN_VM_AS_STATELESS_FINISHED_FAILURE | Error | Failed to complete starting of VM ${VmName}. |
71 | USER_TRY_BACK_TO_SNAPSHOT_FINISH_SUCCESS | Info | Snapshot-Preview ${SnapshotName} for VM ${VmName} has been completed. |
72 | USER_CHANGE_FLOPPY_VM | Info | Floppy ${DiskName} was inserted in VM ${VmName} by ${UserName} |
73 | USER_INITIATED_SHUTDOWN_VM | Info | VM shutdown initiated by ${UserName} on VM ${VmName} (Host: ${VdsName}) (Reason: ${Reason}). |
74 | USER_FAILED_SHUTDOWN_VM | Error | Failed to initiate shutdown on VM ${VmName} (Host: ${VdsName}, User: ${UserName}). |
75 | USER_FAILED_CHANGE_FLOPPY_VM | Error | Failed to change floppy ${DiskName} (User: ${UserName}). |
76 | USER_STOPPED_VM_INSTEAD_OF_SHUTDOWN | Info | VM ${VmName} was powered off ungracefully by ${UserName} (Host: ${VdsName}) (Reason: ${Reason}). |
77 | USER_FAILED_STOPPING_VM_INSTEAD_OF_SHUTDOWN | Error | Failed to power off VM ${VmName} (Host: ${VdsName}, User: ${UserName}). |
78 | USER_ADD_DISK_TO_VM | Info | Add-Disk operation of ${DiskAlias} was initiated on VM ${VmName} by ${UserName}. |
79 | USER_FAILED_ADD_DISK_TO_VM | Error | Operation Add-Disk failed on VM ${VmName} (User: ${UserName}). |
80 | USER_REMOVE_DISK_FROM_VM | Info | Disk was removed from VM ${VmName} by ${UserName}. |
81 | USER_FAILED_REMOVE_DISK_FROM_VM | Error | Failed to remove Disk from VM ${VmName} (User: ${UserName}). |
82 | USER_MOVED_VM | Info | VM ${VmName} moving to Domain ${StorageDomainName} was initiated by ${UserName}. |
83 | USER_FAILED_MOVE_VM | Error | Failed to initiate moving of VM ${VmName} to Domain ${StorageDomainName} (User: ${UserName}). |
84 | USER_MOVED_TEMPLATE | Info | Template ${VmTemplateName} moving to Domain ${StorageDomainName} was initiated by ${UserName}. |
85 | USER_FAILED_MOVE_TEMPLATE | Error | Failed to initiate moving Template ${VmTemplateName} to Domain ${StorageDomainName} (User: ${UserName}). |
86 | USER_COPIED_TEMPLATE | Info | Template ${VmTemplateName} copy to Domain ${StorageDomainName} was initiated by ${UserName}. |
87 | USER_FAILED_COPY_TEMPLATE | Error | Failed to initiate copy of Template ${VmTemplateName} to Domain ${StorageDomainName} (User: ${UserName}). |
88 | USER_UPDATE_VM_DISK | Info | VM ${VmName} ${DiskAlias} disk was updated by ${UserName}. |
89 | USER_FAILED_UPDATE_VM_DISK | Error | Failed to update VM ${VmName} disk ${DiskAlias} (User: ${UserName}). |
90 | VDS_FAILED_TO_GET_HOST_HARDWARE_INFO | Warning | Could not get hardware information for host ${VdsName} |
91 | USER_MOVED_VM_FINISHED_SUCCESS | Info | Moving VM ${VmName} to Domain ${StorageDomainName} has been completed. |
92 | USER_MOVED_VM_FINISHED_FAILURE | Error | Failed to complete moving of VM ${VmName} to Domain ${StorageDomainName}. |
93 | USER_MOVED_TEMPLATE_FINISHED_SUCCESS | Info | Template ${VmTemplateName} moving to Domain ${StorageDomainName} has been completed. |
94 | USER_MOVED_TEMPLATE_FINISHED_FAILURE | Error | Failed to complete moving of Template ${VmTemplateName} to Domain ${StorageDomainName}. |
95 | USER_COPIED_TEMPLATE_FINISHED_SUCCESS | Info | Template ${VmTemplateName} copy to Domain ${StorageDomainName} has been completed. |
96 | USER_COPIED_TEMPLATE_FINISHED_FAILURE | Error | Failed to complete copy of Template ${VmTemplateName} to Domain ${StorageDomainName}. |
97 | USER_ADD_DISK_TO_VM_FINISHED_SUCCESS | Info | The disk ${DiskAlias} was successfully added to VM ${VmName}. |
98 | USER_ADD_DISK_TO_VM_FINISHED_FAILURE | Error | Operation Add-Disk failed to complete on VM ${VmName}. |
99 | USER_TRY_BACK_TO_SNAPSHOT_FINISH_FAILURE | Error | Failed to complete Snapshot-Preview ${SnapshotName} for VM ${VmName}. |
100 | USER_RESTORE_FROM_SNAPSHOT_FINISH_SUCCESS | Info | VM ${VmName} restoring from Snapshot has been completed. |
101 | USER_RESTORE_FROM_SNAPSHOT_FINISH_FAILURE | Error | Failed to complete restoring from Snapshot of VM ${VmName}. |
102 | USER_FAILED_CHANGE_DISK_VM | Error | Failed to change disk in VM ${VmName} (Host: ${VdsName}, User: ${UserName}). |
103 | USER_FAILED_RESUME_VM | Error | Failed to resume VM ${VmName} (Host: ${VdsName}, User: ${UserName}). |
104 | USER_FAILED_ADD_VDS | Error | Failed to add Host ${VdsName} (User: ${UserName}). |
105 | USER_FAILED_UPDATE_VDS | Error | Failed to update Host ${VdsName} (User: ${UserName}). |
106 | USER_FAILED_REMOVE_VDS | Error | Failed to remove Host ${VdsName} (User: ${UserName}). |
107 | USER_FAILED_VDS_RESTART | Error | Failed to restart Host ${VdsName}, (User: ${UserName}). |
108 | USER_FAILED_ADD_VM_TEMPLATE | Error | Failed to initiate creation of Template ${VmTemplateName} from VM ${VmName} (User: ${UserName}). |
109 | USER_FAILED_UPDATE_VM_TEMPLATE | Error | Failed to update Template ${VmTemplateName} (User: ${UserName}). |
110 | USER_FAILED_REMOVE_VM_TEMPLATE | Error | Failed to initiate removal of Template ${VmTemplateName} (User: ${UserName}). |
111 | USER_STOP_SUSPENDED_VM | Info | Suspended VM ${VmName} has had its save state cleared by ${UserName} (Reason: ${Reason}). |
112 | USER_STOP_SUSPENDED_VM_FAILED | Error | Failed to power off suspended VM ${VmName} (User: ${UserName}). |
113 | USER_REMOVE_VM_FINISHED | Info | VM ${VmName} was successfully removed. |
114 | USER_VDC_LOGIN_FAILED | Error | User ${UserName} failed to log in. |
115 | USER_FAILED_TRY_BACK_TO_SNAPSHOT | Error | Failed to preview Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}). |
116 | USER_FAILED_RESTORE_FROM_SNAPSHOT | Error | Failed to restore VM ${VmName} from Snapshot (User: ${UserName}). |
117 | USER_FAILED_CREATE_SNAPSHOT | Error | Failed to create Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}). |
118 | USER_FAILED_VDS_START | Error | Failed to start Host ${VdsName}, (User: ${UserName}). |
119 | VM_DOWN_ERROR | Error | VM ${VmName} is down with error. ${ExitMessage}. |
120 | VM_MIGRATION_FAILED_FROM_TO | Error | Migration failed${DueToMigrationError} (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}). |
121 | SYSTEM_VDS_RESTART | Info | Host ${VdsName} was restarted by the engine. |
122 | SYSTEM_FAILED_VDS_RESTART | Error | A restart initiated by the engine to Host ${VdsName} has failed. |
123 | VDS_SLOW_STORAGE_RESPONSE_TIME | Warning | Slow storage response time on Host ${VdsName}. |
124 | VM_IMPORT | Info | Started VM import of ${ImportedVmName} (User: ${UserName}) |
125 | VM_IMPORT_FAILED | Error | Failed to import VM ${ImportedVmName} (User: ${UserName}) |
126 | VM_NOT_RESPONDING | Warning | VM ${VmName} is not responding. |
127 | VDS_RUN_IN_NO_KVM_MODE | Error | Host ${VdsName} running without virtualization hardware acceleration |
128 | VM_MIGRATION_TRYING_RERUN | Error | Migration failed${DueToMigrationError}. Trying to migrate to another Host (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}). |
129 | VM_CLEARED | Info | Unused |
130 | USER_SUSPEND_VM_FINISH_FAILURE_WILL_TRY_AGAIN | Error | Failed to complete suspending of VM ${VmName}, will try again. |
131 | USER_EXPORT_VM | Info | VM ${VmName} exported to ${ExportPath} by ${UserName} |
132 | USER_EXPORT_VM_FAILED | Error | Failed to export VM ${VmName} to ${ExportPath} (User: ${UserName}) |
133 | USER_EXPORT_TEMPLATE | Info | Template ${VmTemplateName} exported to ${ExportPath} by ${UserName} |
134 | USER_EXPORT_TEMPLATE_FAILED | Error | Failed to export Template ${VmTemplateName} to ${ExportPath} (User: ${UserName}) |
135 | TEMPLATE_IMPORT | Info | Started Template import of ${ImportedVmTemplateName} (User: ${UserName}) |
136 | TEMPLATE_IMPORT_FAILED | Error | Failed to import Template ${ImportedVmTemplateName} (User: ${UserName}) |
137 | USER_FAILED_VDS_STOP | Error | Failed to stop Host ${VdsName}, (User: ${UserName}). |
138 | VM_PAUSED_ENOSPC | Error | VM ${VmName} has paused due to no Storage space error. |
139 | VM_PAUSED_ERROR | Error | VM ${VmName} has paused due to unknown storage error. |
140 | VM_MIGRATION_FAILED_DURING_MOVE_TO_MAINTENANCE | Error | Migration failed${DueToMigrationError} while Host is in 'preparing for maintenance' state.\n Consider manual intervention\: stopping/migrating Vms as Host's state will not\n turn to maintenance while VMs are still running on it.(VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}). |
141 | VDS_VERSION_NOT_SUPPORTED_FOR_CLUSTER | Error | Host ${VdsName} is installed with VDSM version (${VdsSupportedVersions}) and cannot join cluster ${VdsGroupName} which is compatible with VDSM versions ${CompatibilityVersion}. |
142 | VM_SET_TO_UNKNOWN_STATUS | Warning | VM ${VmName} was set to the Unknown status. |
143 | VM_WAS_SET_DOWN_DUE_TO_HOST_REBOOT_OR_MANUAL_FENCE | Info | Vm ${VmName} was shut down due to ${VdsName} host reboot or manual fence |
144 | VM_IMPORT_INFO | Info | Value of field ${FieldName} of imported VM ${VmName} is ${FieldValue}. The field is reset to the default value |
145 | VM_PAUSED_EIO | Error | VM ${VmName} has paused due to storage I/O problem. |
146 | VM_PAUSED_EPERM | Error | VM ${VmName} has paused due to storage permissions problem. |
147 | VM_POWER_DOWN_FAILED | Warning | Shutdown of VM ${VmName} failed. |
148 | VM_MEMORY_UNDER_GUARANTEED_VALUE | Error | VM ${VmName} on host ${VdsName} was guaranteed ${MemGuaranteed} MB but currently has ${MemActual} MB |
149 | USER_ADD | Info | User '${NewUserName}' was added successfully to the system. |
150 | USER_INITIATED_RUN_VM | Info | Starting VM ${VmName} was initiated by ${UserName}. |
151 | USER_INITIATED_RUN_VM_FAILED | Warning | Failed to run VM ${VmName} on Host ${VdsName}. |
152 | USER_RUN_VM_ON_NON_DEFAULT_VDS | Warning | Guest ${VmName} started on Host ${VdsName}. (Default Host parameter was ignored - assigned Host was not available). |
153 | USER_STARTED_VM | Info | VM ${VmName} was started by ${UserName} (Host: ${VdsName}). |
154 | VDS_CLUSTER_VERSION_NOT_SUPPORTED | Error | Host ${VdsName} is compatible with versions (${VdsSupportedVersions}) and cannot join Cluster ${VdsGroupName} which is set to version ${CompatibilityVersion}. |
155 | VDS_ARCHITECTURE_NOT_SUPPORTED_FOR_CLUSTER | Error | Host ${VdsName} has architecture ${VdsArchitecture} and cannot join Cluster ${VdsGroupName} which has architecture ${VdsGroupArchitecture}. |
156 | CPU_TYPE_UNSUPPORTED_IN_THIS_CLUSTER_VERSION | Error | Host ${VdsName} moved to Non-Operational state as host CPU type is not supported in this cluster compatibility version or is not supported at all |
157 | USER_REBOOT_VM | Info | User ${UserName} initiated reboot of VM ${VmName}. |
158 | USER_FAILED_REBOOT_VM | Error | Failed to reboot VM ${VmName} (User: ${UserName}). |
159 | USER_FORCE_SELECTED_SPM | Info | Host ${VdsName} was force selected by ${UserName} |
160 | USER_ACCOUNT_DISABLED_OR_LOCKED | Error | User ${UserName} cannot login, as it got disabled or locked. Please contact the system administrator. |
161 | VM_CANCEL_MIGRATION | Info | Migration cancelled (VM: ${VmName}, Source: ${VdsName}, User: ${UserName}). |
162 | VM_CANCEL_MIGRATION_FAILED | Error | Failed to cancel migration for VM: ${VmName} |
163 | VM_STATUS_RESTORED | Info | VM ${VmName} status was restored to ${VmStatus}. |
164 | VM_SET_TICKET | Info | user ${UserName} initiated console session for VM ${VmName} |
165 | VM_SET_TICKET_FAILED | Error | user ${UserName} failed to initiate a console session for VM ${VmName} |
166 | VM_MIGRATION_FAILED_NO_VDS_TO_RUN_ON | Warning | Migration failed, No available host found (VM: ${VmName}, Source: ${VdsName}). |
167 | VM_CONSOLE_CONNECTED | Info | User ${UserName} is connected to VM ${VmName}. |
168 | VM_CONSOLE_DISCONNECTED | Info | User ${UserName} got disconnected from VM ${VmName}. |
169 | VM_FAILED_TO_PRESTART_IN_POOL | Warning | Cannot pre-start VM in pool '${VmPoolName}'. The system will continue trying. |
170 | USER_CREATE_LIVE_SNAPSHOT_FINISHED_FAILURE | Warning | Failed to create live snapshot '${SnapshotName}' for VM '${VmName}'. VM restart is recommended. Note that using the created snapshot might cause data inconsistency. |
171 | USER_RUN_VM_AS_STATELESS_WITH_DISKS_NOT_ALLOWING_SNAPSHOT | Warning | VM ${VmName} was run as stateless with one or more of disks that do not allow snapshots (User:${UserName}). |
172 | USER_REMOVE_VM_FINISHED_WITH_ILLEGAL_DISKS | Warning | VM ${VmName} has been removed, but the following disks could not be removed: ${DisksNames}. These disks will appear in the main disks tab in illegal state, please remove manually when possible. |
173 | USER_CREATE_LIVE_SNAPSHOT_NO_MEMORY_FAILURE | Error | Failed to save memory as part of Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}). |
174 | VM_IMPORT_FROM_CONFIGURATION_EXECUTED_SUCCESSFULLY | Info | VM ${VmName} has been successfully imported from the given configuration. |
175 | VM_IMPORT_FROM_CONFIGURATION_ATTACH_DISKS_FAILED | Warning | VM ${VmName} has been imported from the given configuration but the following disk(s) failed to attach: ${DiskAliases}. |
176 | VM_BALLOON_DRIVER_ERROR | Error | The Balloon driver on VM ${VmName} on host ${VdsName} is requested but unavailable. |
177 | VM_BALLOON_DRIVER_UNCONTROLLED | Error | The Balloon device on VM ${VmName} on host ${VdsName} is inflated but the device cannot be controlled (guest agent is down). |
178 | VM_MEMORY_NOT_IN_RECOMMENDED_RANGE | Warning | VM ${VmName} was configured with ${VmMemInMb}mb of memory while the recommended value range is ${VmMinMemInMb}mb - ${VmMaxMemInMb}mb |
179 | USER_INITIATED_RUN_VM_AND_PAUSE | Info | Starting in paused mode VM ${VmName} was initiated by ${UserName}. |
180 | TEMPLATE_IMPORT_FROM_CONFIGURATION_SUCCESS | Info | Template ${VmTemplateName} has been successfully imported from the given configuration. |
181 | TEMPLATE_IMPORT_FROM_CONFIGURATION_FAILED | Error | Failed to import Template ${VmTemplateName} from the given configuration. |
182 | USER_FAILED_ATTACH_USER_TO_VM | Error | Failed to attach User ${AdUserName} to VM ${VmName} (User: ${UserName}). |
183 | USER_ATTACH_TAG_TO_TEMPLATE | Info | Tag ${TagName} was attached to Templates(s) ${TemplatesNames} by ${UserName}. |
184 | USER_ATTACH_TAG_TO_TEMPLATE_FAILED | Error | Failed to attach Tag ${TagName} to Templates(s) ${TemplatesNames} (User: ${UserName}). |
185 | USER_DETACH_TEMPLATE_FROM_TAG | Info | Tag ${TagName} was detached from Template(s) ${TemplatesNames} by ${UserName}. |
186 | USER_DETACH_TEMPLATE_FROM_TAG_FAILED | Error | Failed to detach Tag ${TagName} from TEMPLATE(s) ${TemplatesNames} (User: ${UserName}). |
187 | VDS_STORAGE_CONNECTION_FAILED_BUT_LAST_VDS | Error | Failed to connect Host ${VdsName} to Data Center, due to connectivity errors with the Storage. Host ${VdsName} will remain in Up state (but inactive), as it is the last Host in the Data Center, to enable manual intervention by the Administrator. |
188 | VDS_STORAGES_CONNECTION_FAILED | Error | Failed to connect Host ${VdsName} to the Storage Domains ${failedStorageDomains}. |
189 | VDS_STORAGE_VDS_STATS_FAILED | Error | Host ${VdsName} reports about one of the Active Storage Domains as Problematic. |
190 | UPDATE_OVF_FOR_STORAGE_DOMAIN_FAILED | Info | Failed to update VMs/Templates OVF data for Storage Domain ${StorageDomainName} in Data Center ${StoragePoolName}. |
191 | CREATE_OVF_STORE_FOR_STORAGE_DOMAIN_FAILED | Warning | Failed to create OVF store disk for Storage Domain ${StorageDomainName}.\n The Disk with the id ${DiskId} might be removed manually for automatic attempt to create new one. \n OVF updates won't be attempted on the created disk. |
192 | CREATE_OVF_STORE_FOR_STORAGE_DOMAIN_INITIATE_FAILED | Info | Failed to create OVF store disk for Storage Domain ${StorageDomainName}. \n OVF data won't be updated meanwhile for that domain. |
193 | DELETE_OVF_STORE_FOR_STORAGE_DOMAIN_FAILED | Info | Failed to delete the OVF store disk for Storage Domain ${StorageDomainName}.\n In order to detach the domain please remove it manually or try to detach the domain again for another attempt. |
200 | IMPORTEXPORT_GET_VMS_INFO_FAILED | Error | Failed to retrieve VM/Templates information from export domain ${StorageDomainName} |
201 | IRS_DISK_SPACE_LOW_ERROR | Error | Critical, Low disk space. ${StorageDomainName} domain has ${DiskSpace} GB of free space. |
204 | IRS_HOSTED_ON_VDS | Info | Storage Pool Manager runs on Host ${VdsName} (Address: ${ServerIp}). |
205 | PROVIDER_ADDED | Info | Provider ${ProviderName} was added. (User: ${UserName}) |
206 | PROVIDER_ADDITION_FAILED | Error | Failed to add provider ${ProviderName}. (User: ${UserName}) |
207 | PROVIDER_UPDATED | Info | Provider ${ProviderName} was updated. (User: ${UserName}) |
208 | PROVIDER_UPDATE_FAILED | Error | Failed to update provider ${ProviderName}. (User: ${UserName}) |
209 | PROVIDER_REMOVED | Info | Provider ${ProviderName} was removed. (User: ${UserName}) |
210 | PROVIDER_REMOVAL_FAILED | Error | Failed to remove provider ${ProviderName}. (User: ${UserName}) |
213 | PROVIDER_CERTIFICATE_IMPORTED | Info | Certificate for provider ${ProviderName} was imported. (User: ${UserName}) |
214 | PROVIDER_CERTIFICATE_IMPORT_FAILED | Error | Failed importing Certificate for provider ${ProviderName}. (User: ${UserName}) |
250 | USER_UPDATE_VM_CLUSTER_DEFAULT_HOST_CLEARED | Info | ${VmName} cluster was updated by ${UserName}, Default host was reset to auto assign. |
251 | USER_REMOVE_VM_TEMPLATE_FINISHED | Info | Removal of Template ${VmTemplateName} has been completed. |
252 | SYSTEM_FAILED_UPDATE_VM | Error | Failed to Update VM ${VmName} that was initiated by system. |
253 | SYSTEM_UPDATE_VM | Info | VM ${VmName} configuration was updated by system. |
254 | VM_ALREADY_IN_REQUESTED_STATUS | Info | VM ${VmName} is already ${VmStatus}, ${Action} was skipped. User: ${UserName}. |
300 | USER_ADD_VM_POOL | Info | VM Pool ${VmPoolName} was created by ${UserName}. |
301 | USER_ADD_VM_POOL_FAILED | Error | Failed to create VM Pool ${VmPoolName} (User: ${UserName}). |
302 | USER_ADD_VM_POOL_WITH_VMS | Info | VM Pool ${VmPoolName} (containing ${VmsCount} VMs) was created by ${UserName}. |
303 | USER_ADD_VM_POOL_WITH_VMS_FAILED | Error | Failed to create VM Pool ${VmPoolName}(User: ${UserName}). |
304 | USER_REMOVE_VM_POOL | Info | VM Pool ${VmPoolName} was removed by ${UserName}. |
305 | USER_REMOVE_VM_POOL_FAILED | Error | Failed to remove VM Pool ${VmPoolName} (User: ${UserName}). |
306 | USER_ADD_VM_TO_POOL | Info | VM ${VmName} was added to VM Pool ${VmPoolName} by ${UserName}. |
307 | USER_ADD_VM_TO_POOL_FAILED | Error | Failed to add VM ${VmName} to VM Pool ${VmPoolName}(User: ${UserName}). |
308 | USER_REMOVE_VM_FROM_POOL | Info | VM ${VmName} was removed from VM Pool ${VmPoolName} by ${UserName}. |
309 | USER_REMOVE_VM_FROM_POOL_FAILED | Error | Failed to remove VM ${VmName} from VM Pool ${VmPoolName} (User: ${UserName}). |
310 | USER_ATTACH_USER_TO_POOL | Info | User ${AdUserName} was attached to VM Pool ${VmPoolName} by ${UserName}. |
311 | USER_ATTACH_USER_TO_POOL_FAILED | Error | Failed to attach User ${AdUserName} to VM Pool ${VmPoolName} (User: ${UserName}). |
312 | USER_DETACH_USER_FROM_POOL | Info | User ${AdUserName} was detached from VM Pool ${VmPoolName} by ${UserName}. |
313 | USER_DETACH_USER_FROM_POOL_FAILED | Error | Failed to detach User ${AdUserName} from VM Pool ${VmPoolName} (User: ${UserName}). |
314 | USER_UPDATE_VM_POOL | Info | VM Pool ${VmPoolName} configuration was updated by ${UserName}. |
315 | USER_UPDATE_VM_POOL_FAILED | Error | Failed to update VM Pool ${VmPoolName} configuration (User: ${UserName}). |
316 | USER_ATTACH_USER_TO_VM_FROM_POOL | Info | Attaching User ${AdUserName} to VM ${VmName} in VM Pool ${VmPoolName} was initiated by ${UserName}. |
317 | USER_ATTACH_USER_TO_VM_FROM_POOL_FAILED | Error | Failed to attach User ${AdUserName} to VM from VM Pool ${VmPoolName} (User: ${UserName}). |
318 | USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_SUCCESS | Info | User ${AdUserName} successfully attached to VM ${VmName} in VM Pool ${VmPoolName}. |
319 | USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_FAILURE | Error | Failed to attach user ${AdUserName} to VM ${VmName} in VM Pool ${VmPoolName}. |
320 | USER_ADD_VM_POOL_WITH_VMS_ADD_VDS_FAILED | Error | Pool ${VmPoolName} Created, but some Vms failed to create (User: ${UserName}). |
325 | USER_REMOVE_ADUSER | Info | User ${AdUserName} was removed by ${UserName}. |
326 | USER_FAILED_REMOVE_ADUSER | Error | Failed to remove User ${AdUserName} (User: ${UserName}). |
327 | USER_FAILED_ADD_ADUSER | Warning | Failed to add User '${NewUserName}' to the system. |
342 | USER_REMOVE_SNAPSHOT | Info | Snapshot '${SnapshotName}' deletion for VM '${VmName}' was initiated by ${UserName}. |
343 | USER_FAILED_REMOVE_SNAPSHOT | Error | Failed to remove Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}). |
344 | USER_UPDATE_VM_POOL_WITH_VMS | Info | VM Pool ${VmPoolName} was updated by ${UserName}, ${VmsCount} VMs were added. |
345 | USER_UPDATE_VM_POOL_WITH_VMS_FAILED | Error | Failed to update VM Pool ${VmPoolName}(User: ${UserName}). |
346 | USER_PASSWORD_CHANGED | Info | Password changed successfully for ${UserName} |
347 | USER_PASSWORD_CHANGE_FAILED | Error | Failed to change password. (User: ${UserName}) |
348 | USER_CLEAR_UNKNOWN_VMS | Info | All VMs' status on Non Responsive Host ${VdsName} were changed to 'Down' by ${UserName} |
349 | USER_FAILED_CLEAR_UNKNOWN_VMS | Error | Failed to clear VMs' status on Non Responsive Host ${VdsName}. (User: ${UserName}). |
350 | USER_ADD_BOOKMARK | Info | Bookmark ${BookmarkName} was added by ${UserName}. |
351 | USER_ADD_BOOKMARK_FAILED | Error | Failed to add bookmark: ${BookmarkName} (User: ${UserName}). |
352 | USER_UPDATE_BOOKMARK | Info | Bookmark ${BookmarkName} was updated by ${UserName}. |
353 | USER_UPDATE_BOOKMARK_FAILED | Error | Failed to update bookmark: ${BookmarkName} (User: ${UserName}) |
354 | USER_REMOVE_BOOKMARK | Info | Bookmark ${BookmarkName} was removed by ${UserName}. |
355 | USER_REMOVE_BOOKMARK_FAILED | Error | Failed to remove bookmark ${BookmarkName} (User: ${UserName}) |
356 | USER_REMOVE_SNAPSHOT_FINISHED_SUCCESS | Info | Snapshot '${SnapshotName}' deletion for VM '${VmName}' has been completed. |
357 | USER_REMOVE_SNAPSHOT_FINISHED_FAILURE | Error | Failed to delete snapshot '${SnapshotName}' for VM '${VmName}'. |
358 | USER_VM_POOL_MAX_SUBSEQUENT_FAILURES_REACHED | Warning | Not all VMs where successfully created in VM Pool ${VmPoolName}. |
359 | USER_REMOVE_SNAPSHOT_FINISHED_FAILURE_PARTIAL_SNAPSHOT | Warning | Due to partial snapshot removal, Snapshot '${SnapshotName}' of VM '${VmName}' now contains only the following disks: '${DiskAliases}'. |
360 | USER_DETACH_USER_FROM_VM | Info | User ${AdUserName} was detached from VM ${VmName} by ${UserName}. |
361 | USER_FAILED_DETACH_USER_FROM_VM | Error | Failed to detach User ${AdUserName} from VM ${VmName} (User: ${UserName}). |
370 | USER_EXTEND_DISK_SIZE_FAILURE | Error | Failed to extend size of the disk '${DiskAlias}' to ${NewSize} GB, User: ${UserName}. |
371 | USER_EXTEND_DISK_SIZE_SUCCESS | Info | Size of the disk '${DiskAlias}' was successfully updated to ${NewSize} GB by ${UserName}. |
372 | USER_EXTEND_DISK_SIZE_UPDATE_VM_FAILURE | Warning | Failed to update VM '${VmName}' with the new volume size. VM restart is recommended. |
373 | USER_REMOVE_DISK_SNAPSHOT | Info | Disk '${DiskAlias}' from Snapshot(s) '${Snapshots}' of VM '${VmName}' deletion was initiated by ${UserName}. |
374 | USER_FAILED_REMOVE_DISK_SNAPSHOT | Error | Failed to delete Disk '${DiskAlias}' from Snapshot(s) ${Snapshots} of VM ${VmName} (User: ${UserName}). |
375 | USER_REMOVE_DISK_SNAPSHOT_FINISHED_SUCCESS | Info | Disk '${DiskAlias}' from Snapshot(s) '${Snapshots}' of VM '${VmName}' deletion has been completed (User: ${UserName}). |
376 | USER_REMOVE_DISK_SNAPSHOT_FINISHED_FAILURE | Error | Failed to complete deletion of Disk '${DiskAlias}' from snapshot(s) '${Snapshots}' of VM '${VmName}' (User: ${UserName}). |
400 | USER_ATTACH_VM_TO_AD_GROUP | Info | Group ${GroupName} was attached to VM ${VmName} by ${UserName}. |
401 | USER_ATTACH_VM_TO_AD_GROUP_FAILED | Error | Failed to attach Group ${GroupName} to VM ${VmName} (User: ${UserName}). |
402 | USER_DETACH_VM_TO_AD_GROUP | Info | Group ${GroupName} was detached from VM ${VmName} by ${UserName}. |
403 | USER_DETACH_VM_TO_AD_GROUP_FAILED | Error | Failed to detach Group ${GroupName} from VM ${VmName} (User: ${UserName}). |
404 | USER_ATTACH_VM_POOL_TO_AD_GROUP | Info | Group ${GroupName} was attached to VM Pool ${VmPoolName} by ${UserName}. |
405 | USER_ATTACH_VM_POOL_TO_AD_GROUP_FAILED | Error | Failed to attach Group ${GroupName} to VM Pool ${VmPoolName} (User: ${UserName}). |
406 | USER_DETACH_VM_POOL_TO_AD_GROUP | Info | Group ${GroupName} was detached from VM Pool ${VmPoolName} by ${UserName}. |
407 | USER_DETACH_VM_POOL_TO_AD_GROUP_FAILED | Error | Failed to detach Group ${GroupName} from VM Pool ${VmPoolName} (User: ${UserName}). |
408 | USER_REMOVE_AD_GROUP | Info | Group ${GroupName} was removed by ${UserName}. |
409 | USER_REMOVE_AD_GROUP_FAILED | Error | Failed to remove group ${GroupName} (User: ${UserName}). |
430 | USER_UPDATE_TAG | Info | Tag ${TagName} configuration was updated by ${UserName}. |
431 | USER_UPDATE_TAG_FAILED | Error | Failed to update Tag ${TagName} (User: ${UserName}). |
432 | USER_ADD_TAG | Info | New Tag ${TagName} was created by ${UserName}. |
433 | USER_ADD_TAG_FAILED | Error | Failed to create Tag named ${TagName} (User: ${UserName}). |
434 | USER_REMOVE_TAG | Info | Tag ${TagName} was removed by ${UserName}. |
435 | USER_REMOVE_TAG_FAILED | Error | Failed to remove Tag ${TagName} (User: ${UserName}). |
436 | USER_ATTACH_TAG_TO_USER | Info | Tag ${TagName} was attached to User(s) ${AttachUsersNames} by ${UserName}. |
437 | USER_ATTACH_TAG_TO_USER_FAILED | Error | Failed to attach Tag ${TagName} to User(s) ${AttachUsersNames} (User: ${UserName}). |
438 | USER_ATTACH_TAG_TO_USER_GROUP | Info | Tag ${TagName} was attached to Group(s) ${AttachGroupsNames} by ${UserName}. |
439 | USER_ATTACH_TAG_TO_USER_GROUP_FAILED | Error | Failed to attach Group(s) ${AttachGroupsNames} to Tag ${TagName} (User: ${UserName}). |
440 | USER_ATTACH_TAG_TO_VM | Info | Tag ${TagName} was attached to VM(s) ${VmsNames} by ${UserName}. |
441 | USER_ATTACH_TAG_TO_VM_FAILED | Error | Failed to attach Tag ${TagName} to VM(s) ${VmsNames} (User: ${UserName}). |
442 | USER_ATTACH_TAG_TO_VDS | Info | Tag ${TagName} was attached to Host(s) ${VdsNames} by ${UserName}. |
443 | USER_ATTACH_TAG_TO_VDS_FAILED | Error | Failed to attach Tag ${TagName} to Host(s) ${VdsNames} (User: ${UserName}). |
444 | USER_DETACH_VDS_FROM_TAG | Info | Tag ${TagName} was detached from Host(s) ${VdsNames} by ${UserName}. |
445 | USER_DETACH_VDS_FROM_TAG_FAILED | Error | Failed to detach Tag ${TagName} from Host(s) ${VdsNames} (User: ${UserName}). |
446 | USER_DETACH_VM_FROM_TAG | Info | Tag ${TagName} was detached from VM(s) ${VmsNames} by ${UserName}. |
447 | USER_DETACH_VM_FROM_TAG_FAILED | Error | Failed to detach Tag ${TagName} from VM(s) ${VmsNames} (User: ${UserName}). |
448 | USER_DETACH_USER_FROM_TAG | Info | Tag ${TagName} detached from User(s) ${DetachUsersNames} by ${UserName}. |
449 | USER_DETACH_USER_FROM_TAG_FAILED | Error | Failed to detach Tag ${TagName} from User(s) ${DetachUsersNames} (User: ${UserName}). |
450 | USER_DETACH_USER_GROUP_FROM_TAG | Info | Tag ${TagName} was detached from Group(s) ${DetachGroupsNames} by ${UserName}. |
451 | USER_DETACH_USER_GROUP_FROM_TAG_FAILED | Error | Failed to detach Tag ${TagName} from Group(s) ${DetachGroupsNames} (User: ${UserName}). |
452 | USER_ATTACH_TAG_TO_USER_EXISTS | Warning | Tag ${TagName} already attached to User(s) ${AttachUsersNamesExists}. |
453 | USER_ATTACH_TAG_TO_USER_GROUP_EXISTS | Warning | Tag ${TagName} already attached to Group(s) ${AttachGroupsNamesExists}. |
454 | USER_ATTACH_TAG_TO_VM_EXISTS | Warning | Tag ${TagName} already attached to VM(s) ${VmsNamesExists}. |
455 | USER_ATTACH_TAG_TO_VDS_EXISTS | Warning | Tag ${TagName} already attached to Host(s) ${VdsNamesExists}. |
456 | USER_LOGGED_IN_VM | Info | User ${GuestUser} logged in to VM ${VmName}. |
457 | USER_LOGGED_OUT_VM | Info | User ${GuestUser} logged out from VM ${VmName}. |
458 | USER_LOCKED_VM | Info | User ${GuestUser} locked VM ${VmName}. |
459 | USER_UNLOCKED_VM | Info | User ${GuestUser} unlocked VM ${VmName}. |
460 | USER_ATTACH_TAG_TO_TEMPLATE_EXISTS | Warning | Tag ${TagName} already attached to Template(s) ${TemplatesNamesExists}. |
467 | UPDATE_TAGS_VM_DEFAULT_DISPLAY_TYPE | Info | Vm ${VmName} tag default display type was updated |
468 | UPDATE_TAGS_VM_DEFAULT_DISPLAY_TYPE_FAILED | Info | Failed to update Vm ${VmName} tag default display type |
470 | USER_ATTACH_VM_POOL_TO_AD_GROUP_INTERNAL | Info | Group ${GroupName} was attached to VM Pool ${VmPoolName}. |
471 | USER_ATTACH_VM_POOL_TO_AD_GROUP_FAILED_INTERNAL | Error | Failed to attach Group ${GroupName} to VM Pool ${VmPoolName}. |
472 | USER_ATTACH_USER_TO_POOL_INTERNAL | Info | User ${AdUserName} was attached to VM Pool ${VmPoolName}. |
473 | USER_ATTACH_USER_TO_POOL_FAILED_INTERNAL | Error | Failed to attach User ${AdUserName} to VM Pool ${VmPoolName} (User: ${UserName}). |
493 | VDS_ALREADY_IN_REQUESTED_STATUS | Warning | Host ${HostName} is already ${AgentStatus}, Power Management ${Operation} operation skipped. |
494 | VDS_MANUAL_FENCE_STATUS | Info | Manual fence for host ${VdsName} was started. |
495 | VDS_MANUAL_FENCE_STATUS_FAILED | Error | Manual fence for host ${VdsName} failed. |
496 | VDS_FENCE_STATUS | Info | Host ${VdsName} power management was verified successfully. |
497 | VDS_FENCE_STATUS_FAILED | Error | Failed to verify Host ${VdsName} power management. |
498 | VDS_APPROVE | Info | Host ${VdsName} was successfully approved by user ${UserName}. |
499 | VDS_APPROVE_FAILED | Error | Failed to approve Host ${VdsName}. |
500 | VDS_FAILED_TO_RUN_VMS | Error | Host ${VdsName} will be switched to Error status for ${Time} minutes because it failed to run a VM. |
501 | USER_SUSPEND_VM | Info | Suspending VM ${VmName} was initiated by User ${UserName} (Host: ${VdsName}). |
502 | USER_FAILED_SUSPEND_VM | Error | Failed to suspend VM ${VmName} (Host: ${VdsName}). |
503 | USER_SUSPEND_VM_OK | Info | VM ${VmName} on Host ${VdsName} is suspended. |
504 | VDS_INSTALL | Info | Host ${VdsName} installed |
505 | VDS_INSTALL_FAILED | Error | Host ${VdsName} installation failed. ${FailedInstallMessage}. |
506 | VDS_INITIATED_RUN_VM | Info | VM ${VmName} was restarted on Host ${VdsName} |
507 | VDS_INITIATED_RUN_VM_FAILED | Error | Failed to restart VM ${VmName} on Host ${VdsName} |
509 | VDS_INSTALL_IN_PROGRESS | Info | Installing Host ${VdsName}. ${Message}. |
510 | VDS_INSTALL_IN_PROGRESS_WARNING | Warning | Host ${VdsName} installation in progress . ${Message}. |
511 | VDS_INSTALL_IN_PROGRESS_ERROR | Error | Failed to install Host ${VdsName}. ${Message}. |
512 | USER_SUSPEND_VM_FINISH_SUCCESS | Info | Suspending VM ${VmName} has been completed. |
513 | VDS_RECOVER_FAILED_VMS_UNKNOWN | Error | Host ${VdsName} cannot be reached, VMs state on this host are marked as Unknown. |
514 | VDS_INITIALIZING | Warning | Host ${VdsName} is initializing. Message: ${ErrorMessage} |
515 | VDS_CPU_LOWER_THAN_CLUSTER | Warning | Host ${VdsName} moved to Non-Operational state as host does not meet the cluster's minimum CPU level. Missing CPU features : ${CpuFlags} |
516 | VDS_CPU_RETRIEVE_FAILED | Warning | Failed to determine Host ${VdsName} CPU level - could not retrieve CPU flags. |
517 | VDS_SET_NONOPERATIONAL | Info | Host ${VdsName} moved to Non-Operational state. |
518 | VDS_SET_NONOPERATIONAL_FAILED | Error | Failed to move Host ${VdsName} to Non-Operational state. |
519 | VDS_SET_NONOPERATIONAL_NETWORK | Warning | Host ${VdsName} does not comply with the cluster ${VdsGroupName} networks, the following networks are missing on host: '${Networks}' |
520 | USER_ATTACH_USER_TO_VM | Info | User ${AdUserName} was attached to VM ${VmName} by ${UserName}. |
521 | USER_SUSPEND_VM_FINISH_FAILURE | Error | Failed to complete suspending of VM ${VmName}. |
522 | VDS_SET_NONOPERATIONAL_DOMAIN | Warning | Host ${VdsName} cannot access the Storage Domain(s) ${StorageDomainNames} attached to the Data Center ${StoragePoolName}. Setting Host state to Non-Operational. |
523 | VDS_SET_NONOPERATIONAL_DOMAIN_FAILED | Error | Host ${VdsName} cannot access the Storage Domain(s) ${StorageDomainNames} attached to the Data Center ${StoragePoolName}. Failed to set Host state to Non-Operational. |
524 | VDS_DOMAIN_DELAY_INTERVAL | Warning | Storage domain ${StorageDomainName} experienced a high latency of ${Delay} seconds from host ${VdsName}. This may cause performance and functional issues. Please consult your Storage Administrator. |
525 | VDS_INITIATED_RUN_AS_STATELESS_VM_NOT_YET_RUNNING | Info | Starting VM ${VmName} as stateless was initiated. |
528 | USER_EJECT_VM_DISK | Info | CD was ejected from VM ${VmName} by ${UserName} |
529 | USER_EJECT_VM_FLOPPY | Info | Floppy was ejected from VM ${VmName} by ${UserName} |
530 | VDS_MANUAL_FENCE_FAILED_CALL_FENCE_SPM | Warning | Manual fence did not revoke the selected SPM (${VdsName}) since the master storage domain\n was not active or could not use another host for the fence operation. |
531 | VDS_LOW_MEM | Warning | Available memory of host ${HostName} [${AvailableMemory} MB] is under defined threshold [${Threshold} MB]. |
532 | VDS_HIGH_MEM_USE | Warning | Used memory of host ${HostName} [${UsedMemory}%] exceeded defined threshold [${Threshold}%]. |
533 | VDS_HIGH_NETWORK_USE | Warning | |
534 | VDS_HIGH_CPU_USE | Warning | Used CPU of host ${HostName} [${UsedCpu}%] exceeded defined threshold [${Threshold}%]. |
535 | VDS_HIGH_SWAP_USE | Warning | Used swap memory of host ${HostName} [${UsedSwap}%] exceeded defined threshold [${Threshold}%]. |
536 | VDS_LOW_SWAP | Warning | Available swap memory of host ${HostName} [${AvailableSwapMemory} MB] is under defined threshold [${Threshold} MB]. |
537 | VDS_INITIATED_RUN_VM_AS_STATELESS | Info | VM ${VmName} was restarted on Host ${VdsName} as stateless |
538 | USER_RUN_VM_AS_STATELESS | Info | VM ${VmName} started on Host ${VdsName} as stateless |
539 | VDS_AUTO_FENCE_STATUS | Info | Auto fence for host ${VdsName} was started. |
540 | VDS_AUTO_FENCE_STATUS_FAILED | Error | Auto fence for host ${VdsName} failed. |
541 | VDS_AUTO_FENCE_FAILED_CALL_FENCE_SPM | Warning | Auto fence did not revoke the selected SPM (${VdsName}) since the master storage domain\n was not active or could not use another host for the fence operation. |
555 | USER_MOVE_TAG | Info | Tag ${TagName} was moved from ${OldParnetTagName} to ${NewParentTagName} by ${UserName}. |
556 | USER_MOVE_TAG_FAILED | Error | Failed to move Tag ${TagName} from ${OldParnetTagName} to ${NewParentTagName} (User: ${UserName}). |
600 | USER_VDS_MAINTENANCE | Info | Host ${VdsName} was switched to Maintenance mode by ${UserName}. |
601 | CPU_FLAGS_NX_IS_MISSING | Warning | Host ${VdsName} is missing the NX cpu flag. This flag can be enabled via the host BIOS. Please set Disable Execute (XD) for an Intel host, or No Execute (NX) for AMD. Please make sure to completely power off the host for this change to take effect. |
602 | USER_VDS_MAINTENANCE_MIGRATION_FAILED | Warning | Host ${VdsName} cannot change into maintenance mode - not all Vms have been migrated successfully. Consider manual intervention: stopping/migrating Vms: ${failedVms} (User: ${UserName}). |
603 | VDS_SET_NONOPERATIONAL_IFACE_DOWN | Warning | Host ${VdsName} moved to Non-Operational state because interfaces which are down are needed by required networks in the current cluster: '${NicsWithNetworks}'. |
604 | VDS_TIME_DRIFT_ALERT | Warning | Host ${VdsName} has time-drift of ${Actual} seconds while maximum configured value is ${Max} seconds. |
605 | PROXY_HOST_SELECTION | Info | Host ${Proxy} from ${Origin} was chosen as a proxy to execute ${Command} command on Host ${VdsName}. |
606 | HOST_REFRESHED_CAPABILITIES | Info | Successfully refreshed the capabilities of host ${VdsName}. |
607 | HOST_REFRESH_CAPABILITIES_FAILED | Error | Failed to refresh the capabilities of host ${VdsName}. |
608 | HOST_INTERFACE_HIGH_NETWORK_USE | Warning | Host ${HostName} has network interface which exceeded the defined threshold [${Threshold}%] (${InterfaceName}: transmit rate[${TransmitRate}%], receive rate [${ReceiveRate}%]) |
609 | HOST_INTERFACE_STATE_UP | Normal | Interface ${InterfaceName} on host ${VdsName}, changed state to up |
610 | HOST_INTERFACE_STATE_DOWN | Warning | Interface ${InterfaceName} on host ${VdsName}, changed state to down |
611 | HOST_BOND_SLAVE_STATE_UP | Normal | Slave ${SlaveName} of bond ${BondName} on host ${VdsName}, changed state to up |
612 | HOST_BOND_SLAVE_STATE_DOWN | Warning | Slave ${SlaveName} of bond ${BondName} on host ${VdsName}, changed state to down |
613 | FENCE_KDUMP_LISTENER_IS_NOT_ALIVE | Error | Unable to determine if Kdump is in progress on host '${VdsName}', because fence_kdump listener is not running. |
614 | KDUMP_FLOW_DETECTED_ON_VDS | Info | Kdump flow is in progress on host '${VdsName}'. |
615 | KDUMP_FLOW_NOT_DETECTED_ON_VDS | Info | Kdump flow is not in progress on host '${VdsName}'. |
616 | KDUMP_FLOW_FINISHED_ON_VDS | Info | Kdump flow finished on host '${VdsName}'. |
617 | KDUMP_DETECTION_NOT_CONFIGURED_ON_VDS | Warning | Kdump integration is enabled for host '${VdsName}', but kdump is not configured properly on host. |
700 | DISK_ALIGNMENT_SCAN_START | Info | Starting alignment scan of disk '${DiskAlias}'. |
701 | DISK_ALIGNMENT_SCAN_FAILURE | Warning | Alignment scan of disk '${DiskAlias}' failed. |
702 | DISK_ALIGNMENT_SCAN_SUCCESS | Info | Alignment scan of disk '${DiskAlias}' is complete. |
809 | USER_ADD_VDS_GROUP | Info | Cluster ${VdsGroupName} was added by ${UserName} |
810 | USER_ADD_VDS_GROUP_FAILED | Error | Failed to add Host cluster (User: ${UserName}) |
811 | USER_UPDATE_VDS_GROUP | Info | Host cluster ${VdsGroupName} was updated by ${UserName} |
812 | USER_UPDATE_VDS_GROUP_FAILED | Error | Failed to update Host cluster (User: ${UserName}) |
813 | USER_REMOVE_VDS_GROUP | Info | Host cluster ${VdsGroupName} was removed by ${UserName} |
814 | USER_REMOVE_VDS_GROUP_FAILED | Error | Failed to remove Host cluster (User: ${UserName}) |
815 | USER_VDC_LOGOUT_FAILED | Error | Failed to log User ${UserName} out. |
816 | MAC_POOL_EMPTY | Warning | No MAC addresses left in the MAC Address Pool. |
817 | CERTIFICATE_FILE_NOT_FOUND | Error | Could not find oVirt Engine Certificate file. |
818 | RUN_VM_FAILED | Error | Cannot run VM ${VmName} on Host ${VdsName}. Error: ${ErrMsg} |
819 | VDS_REGISTER_ERROR_UPDATING_HOST | Error | Host registration failed - cannot update Host Name for Host ${VdsName2}. (Host: ${VdsName1}) |
820 | VDS_REGISTER_ERROR_UPDATING_HOST_ALL_TAKEN | Error | Host registration failed - all available Host Names are taken. (Host: ${VdsName1}) |
821 | VDS_REGISTER_HOST_IS_ACTIVE | Error | Host registration failed - cannot change Host Name of active Host ${VdsName2}. (Host: ${VdsName1}) |
822 | VDS_REGISTER_ERROR_UPDATING_NAME | Error | Host registration failed - cannot update Host Name for Host ${VdsName2}. (Host: ${VdsName1}) |
823 | VDS_REGISTER_ERROR_UPDATING_NAMES_ALL_TAKEN | Error | Host registration failed - all available Host Names are taken. (Host: ${VdsName1}) |
824 | VDS_REGISTER_NAME_IS_ACTIVE | Error | Host registration failed - cannot change Host Name of active Host ${VdsName2}. (Host: ${VdsName1}) |
825 | VDS_REGISTER_AUTO_APPROVE_PATTERN | Error | Host registration failed - auto approve pattern error. (Host: ${VdsName1}) |
826 | VDS_REGISTER_FAILED | Error | Host registration failed. (Host: ${VdsName1}) |
827 | VDS_REGISTER_EXISTING_VDS_UPDATE_FAILED | Error | Host registration failed - cannot update existing Host. (Host: ${VdsName1}) |
828 | VDS_REGISTER_SUCCEEDED | Info | Host ${VdsName1} registered. |
829 | VM_MIGRATION_ON_CONNECT_CHECK_FAILED | Error | VM migration logic failed. (VM name: ${VmName}) |
830 | VM_MIGRATION_ON_CONNECT_CHECK_SUCCEEDED | Info | Migration check failed to execute. |
833 | MAC_ADDRESS_IS_IN_USE | Warning | Network Interface ${IfaceName} has MAC address ${MACAddr} which is in use. |
834 | VDS_REGISTER_EMPTY_ID | Warning | Host registration failed, empty host id (Host: ${VdsHostName}) |
835 | SYSTEM_UPDATE_VDS_GROUP | Info | Host cluster ${VdsGroupName} was updated by system |
836 | SYSTEM_UPDATE_VDS_GROUP_FAILED | Info | Failed to update Host cluster by system |
837 | MAC_ADDRESSES_POOL_NOT_INITIALIZED | Warning | Mac Address Pool is not initialized. ${Message} |
838 | MAC_ADDRESS_IS_IN_USE_UNPLUG | Warning | Network Interface ${IfaceName} has MAC address ${MACAddr} which is in use, therefore it is being unplugged from VM ${VmName}. |
850 | USER_ADD_PERMISSION | Info | User/Group ${SubjectName}, Namespace ${Namespace}, Authorization provider: ${Authz} was granted permission for Role ${RoleName} on ${VdcObjectType} ${VdcObjectName}, by ${UserName}. |
851 | USER_ADD_PERMISSION_FAILED | Error | User ${UserName} failed to grant permission for Role ${RoleName} on ${VdcObjectType} ${VdcObjectName} to User/Group ${SubjectName}. |
852 | USER_REMOVE_PERMISSION | Info | User/Group ${SubjectName} Role ${RoleName} permission was removed from ${VdcObjectType} ${VdcObjectName} by ${UserName} |
853 | USER_REMOVE_PERMISSION_FAILED | Error | User ${UserName} failed to remove permission for Role ${RoleName} from ${VdcObjectType} ${VdcObjectName} to User/Group ${SubjectName} |
854 | USER_ADD_ROLE | Info | Role ${RoleName} granted to ${UserName} |
855 | USER_ADD_ROLE_FAILED | Error | Failed to grant role ${RoleName} (User ${UserName}) |
856 | USER_UPDATE_ROLE | Info | ${UserName} Role was updated to the ${RoleName} Role |
857 | USER_UPDATE_ROLE_FAILED | Error | Failed to update role ${RoleName} to ${UserName} |
858 | USER_REMOVE_ROLE | Info | Role ${RoleName} removed from ${UserName} |
859 | USER_REMOVE_ROLE_FAILED | Error | Failed to remove role ${RoleName} (User ${UserName}) |
860 | USER_ATTACHED_ACTION_GROUP_TO_ROLE | Info | Action group ${ActionGroup} was attached to Role ${RoleName} by ${UserName} |
861 | USER_ATTACHED_ACTION_GROUP_TO_ROLE_FAILED | Error | Failed to attach Action group ${ActionGroup} to Role ${RoleName} (User: ${UserName}) |
862 | USER_DETACHED_ACTION_GROUP_FROM_ROLE | Info | Action group ${ActionGroup} was detached from Role ${RoleName} by ${UserName} |
863 | USER_DETACHED_ACTION_GROUP_FROM_ROLE_FAILED | Error | Failed to attach Action group ${ActionGroup} to Role ${RoleName} by ${UserName} |
864 | USER_ADD_ROLE_WITH_ACTION_GROUP | Info | Role ${RoleName} was added by ${UserName} |
865 | USER_ADD_ROLE_WITH_ACTION_GROUP_FAILED | Error | Failed to add role ${RoleName} |
866 | USER_ADD_SYSTEM_PERMISSION | Info | User/Group ${SubjectName} was granted permission for Role ${RoleName} on ${VdcObjectType} by ${UserName}. |
867 | USER_ADD_SYSTEM_PERMISSION_FAILED | Error | User ${UserName} failed to grant permission for Role ${RoleName} on ${VdcObjectType} to User/Group ${SubjectName}. |
868 | USER_REMOVE_SYSTEM_PERMISSION | Info | User/Group ${SubjectName} Role ${RoleName} permission was removed from ${VdcObjectType} by ${UserName} |
869 | USER_REMOVE_SYSTEM_PERMISSION_FAILED | Error | User ${UserName} failed to remove permission for Role ${RoleName} from ${VdcObjectType} to User/Group ${SubjectName} |
900 | AD_COMPUTER_ACCOUNT_SUCCEEDED | Info | Account creation successful. |
901 | AD_COMPUTER_ACCOUNT_FAILED | Error | Account creation failed. |
918 | USER_FORCE_REMOVE_STORAGE_POOL | Info | Data Center ${StoragePoolName} was forcibly removed by ${UserName} |
919 | USER_FORCE_REMOVE_STORAGE_POOL_FAILED | Error | Failed to forcibly remove Data Center ${StoragePoolName}. (User: ${UserName}) |
920 | NETWORK_ATTACH_NETWORK_TO_VDS | Info | Attach network: ${NetworkName} to Host: ${VdsName} by ${UserName}. |
921 | NETWORK_ATTACH_NETWORK_TO_VDS_FAILED | Error | Failed to attach network: ${NetworkName} to Host: ${VdsName} (User: ${UserName}). |
922 | NETWORK_DETACH_NETWORK_FROM_VDS | Info | Detach network: ${NetworkName} from Host: ${VdsName} by ${UserName}. |
923 | NETWORK_DETACH_NETWORK_FROM_VDS_FAILED | Error | Failed to detach network: ${NetworkName} from Host: ${VdsName} (User: ${UserName}). |
924 | NETWORK_ADD_BOND | Info | Add bond: ${BondName} with interfaces: ${Interfaces} for Host: ${VdsName} by ${UserName}. |
925 | NETWORK_ADD_BOND_FAILED | Error | Failed to add bond: ${BondName} with interfaces: ${Interfaces} for Host: ${VdsName} (User:${UserName}). |
926 | NETWORK_REMOVE_BOND | Info | Remove bond: ${BondName} for Host: ${VdsName} (User:${UserName}). |
927 | NETWORK_REMOVE_BOND_FAILED | Error | Failed to remove bond: ${BondName} for Host: ${VdsName} (User:${UserName}). |
928 | NETWORK_VDS_NETWORK_MATCH_CLUSTER | Info | Vds ${VdsName} network match to cluster ${VdsGroupName} |
929 | NETWORK_VDS_NETWORK_NOT_MATCH_CLUSTER | Error | Vds ${VdsName} network does not match to cluster ${VdsGroupName} |
930 | NETWORK_REMOVE_VM_INTERFACE | Info | Interface ${InterfaceName} (${InterfaceType}) was removed from VM ${VmName}. (User: ${UserName}) |
931 | NETWORK_REMOVE_VM_INTERFACE_FAILED | Error | Failed to remove Interface ${InterfaceName} (${InterfaceType}) from VM ${VmName}. (User: ${UserName}) |
932 | NETWORK_ADD_VM_INTERFACE | Info | Interface ${InterfaceName} (${InterfaceType}) was added to VM ${VmName}. (User: ${UserName}) |
933 | NETWORK_ADD_VM_INTERFACE_FAILED | Error | Failed to add Interface ${InterfaceName} (${InterfaceType}) to VM ${VmName}. (User: ${UserName}) |
934 | NETWORK_UPDATE_VM_INTERFACE | Info | Interface ${InterfaceName} (${InterfaceType}) was updated for VM ${VmName}. ${LinkState} (User: ${UserName}) |
935 | NETWORK_UPDATE_VM_INTERFACE_FAILED | Error | Failed to update Interface ${InterfaceName} (${InterfaceType}) for VM ${VmName}. (User: ${UserName}) |
936 | NETWORK_ADD_TEMPLATE_INTERFACE | Info | Interface ${InterfaceName} (${InterfaceType}) was added to Template ${VmTemplateName}. (User: ${UserName}) |
937 | NETWORK_ADD_TEMPLATE_INTERFACE_FAILED | Error | Failed to add Interface ${InterfaceName} (${InterfaceType}) to Template ${VmTemplateName}. (User: ${UserName}) |
938 | NETWORK_REMOVE_TEMPLATE_INTERFACE | Info | Interface ${InterfaceName} (${InterfaceType}) was removed from Template ${VmTemplateName}. (User: ${UserName}) |
939 | NETWORK_REMOVE_TEMPLATE_INTERFACE_FAILED | Error | Failed to remove Interface ${InterfaceName} (${InterfaceType}) from Template ${VmTemplateName}. (User: ${UserName}) |
940 | NETWORK_UPDATE_TEMPLATE_INTERFACE | Info | Interface ${InterfaceName} (${InterfaceType}) was updated for Template ${VmTemplateName}. (User: ${UserName}) |
941 | NETWORK_UPDATE_TEMPLATE_INTERFACE_FAILED | Error | Failed to update Interface ${InterfaceName} (${InterfaceType}) for Template ${VmTemplateName}. (User: ${UserName}) |
942 | NETWORK_ADD_NETWORK | Info | Network ${NetworkName} was added to Data Center: ${StoragePoolName} |
943 | NETWORK_ADD_NETWORK_FAILED | Error | Failed to add Network ${NetworkName} to Data Center: ${StoragePoolName} |
944 | NETWORK_REMOVE_NETWORK | Info | Network ${NetworkName} was removed from Data Center: ${StoragePoolName} |
945 | NETWORK_REMOVE_NETWORK_FAILED | Error | Failed to remove Network ${NetworkName} from Data Center: ${StoragePoolName} |
946 | NETWORK_ATTACH_NETWORK_TO_VDS_GROUP | Info | Network ${NetworkName} attached to Cluster ${VdsGroupName} |
947 | NETWORK_ATTACH_NETWORK_TO_VDS_GROUP_FAILED | Error | Failed to attach Network ${NetworkName} to Cluster ${VdsGroupName} |
948 | NETWORK_DETACH_NETWORK_TO_VDS_GROUP | Info | Network ${NetworkName} detached from Cluster ${VdsGroupName} |
949 | NETWORK_DETACH_NETWORK_TO_VDS_GROUP_FAILED | Error | Failed to detach Network ${NetworkName} from Cluster ${VdsGroupName} |
950 | USER_ADD_STORAGE_POOL | Info | Data Center ${StoragePoolName}, Compatibility Version ${CompatibilityVersion} and Quota Type ${QuotaEnforcementType} was added by ${UserName} |
951 | USER_ADD_STORAGE_POOL_FAILED | Error | Failed to add Data Center ${StoragePoolName}. (User: ${UserName}) |
952 | USER_UPDATE_STORAGE_POOL | Info | Data Center ${StoragePoolName} was updated by ${UserName} |
953 | USER_UPDATE_STORAGE_POOL_FAILED | Error | Failed to update Data Center ${StoragePoolName}. (User: ${UserName}) |
954 | USER_REMOVE_STORAGE_POOL | Info | Data Center ${StoragePoolName} was removed by ${UserName} |
955 | USER_REMOVE_STORAGE_POOL_FAILED | Error | Failed to remove Data Center ${StoragePoolName}. (User: ${UserName}) |
956 | USER_ADD_STORAGE_DOMAIN | Info | Storage Domain ${StorageDomainName} was added by ${UserName} |
957 | USER_ADD_STORAGE_DOMAIN_FAILED | Error | Failed to add Storage Domain ${StorageDomainName}. (User: ${UserName}) |
958 | USER_UPDATE_STORAGE_DOMAIN | Info | Storage Domain ${StorageDomainName} was updated by ${UserName} |
959 | USER_UPDATE_STORAGE_DOMAIN_FAILED | Error | Failed to update Storage Domain ${StorageDomainName}. (User: ${UserName}) |
960 | USER_REMOVE_STORAGE_DOMAIN | Info | Storage Domain ${StorageDomainName} was removed by ${UserName} |
961 | USER_REMOVE_STORAGE_DOMAIN_FAILED | Error | Failed to remove Storage Domain ${StorageDomainName}. (User: ${UserName}) |
962 | USER_ATTACH_STORAGE_DOMAIN_TO_POOL | Info | Storage Domain ${StorageDomainName} was attached to Data Center ${StoragePoolName} by ${UserName} |
963 | USER_ATTACH_STORAGE_DOMAIN_TO_POOL_FAILED | Error | Failed to attach Storage Domain ${StorageDomainName} to Data Center ${StoragePoolName}. (User: ${UserName}) |
964 | USER_DETACH_STORAGE_DOMAIN_FROM_POOL | Info | Storage Domain ${StorageDomainName} was detached from Data Center ${StoragePoolName} by ${UserName} |
965 | USER_DETACH_STORAGE_DOMAIN_FROM_POOL_FAILED | Error | Failed to detach Storage Domain ${StorageDomainName} to Data Center ${StoragePoolName}. (User: ${UserName}) |
966 | USER_ACTIVATED_STORAGE_DOMAIN | Info | Storage Domain ${StorageDomainName} (Data Center ${StoragePoolName}) was activated by ${UserName} |
967 | USER_ACTIVATE_STORAGE_DOMAIN_FAILED | Error | Failed to activate Storage Domain ${StorageDomainName} (Data Center ${StoragePoolName}) by ${UserName} |
968 | USER_DEACTIVATED_STORAGE_DOMAIN | Info | Storage Domain ${StorageDomainName} (Data Center ${StoragePoolName}) was deactivated. |
969 | USER_DEACTIVATE_STORAGE_DOMAIN_FAILED | Error | Failed to deactivate Storage Domain ${StorageDomainName} (Data Center ${StoragePoolName}). |
970 | SYSTEM_DEACTIVATED_STORAGE_DOMAIN | Warning | Storage Domain ${StorageDomainName} (Data Center ${StoragePoolName}) was deactivated by system because it's not visible by any of the hosts. |
971 | SYSTEM_DEACTIVATE_STORAGE_DOMAIN_FAILED | Error | Failed to deactivate Storage Domain ${StorageDomainName} (Data Center ${StoragePoolName}). |
972 | USER_EXTENDED_STORAGE_DOMAIN | Info | Storage ${StorageDomainName} has been extended by ${UserName}. Please wait for refresh. |
973 | USER_EXTENDED_STORAGE_DOMAIN_FAILED | Error | Failed to extend Storage Domain ${StorageDomainName}. (User: ${UserName}) |
974 | USER_REMOVE_VG | Info | Volume group ${VgId} was removed by ${UserName}. |
975 | USER_REMOVE_VG_FAILED | Error | Failed to remove Volume group ${VgId}. (User: UserName) |
976 | USER_ACTIVATE_STORAGE_POOL | Info | Data Center ${StoragePoolName} was activated. (User: ${UserName}) |
977 | USER_ACTIVATE_STORAGE_POOL_FAILED | Error | Failed to activate Data Center ${StoragePoolName}. (User: ${UserName}) |
978 | SYSTEM_FAILED_CHANGE_STORAGE_POOL_STATUS | Error | Failed to change Data Center ${StoragePoolName} status. |
979 | SYSTEM_CHANGE_STORAGE_POOL_STATUS_NO_HOST_FOR_SPM | Error | Fencing failed on Storage Pool Manager ${VdsName} for Data Center ${StoragePoolName}. Setting status to Non-Operational. |
980 | SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC | Warning | Invalid status on Data Center ${StoragePoolName}. Setting status to Non Responsive. |
981 | USER_FORCE_REMOVE_STORAGE_DOMAIN | Info | Storage Domain ${StorageDomainName} was forcibly removed by ${UserName} |
982 | USER_FORCE_REMOVE_STORAGE_DOMAIN_FAILED | Error | Failed to forcibly remove Storage Domain ${StorageDomainName}. (User: ${UserName}) |
983 | RECONSTRUCT_MASTER_FAILED_NO_MASTER | Warning | No valid Data Storage Domains are available in Data Center ${StoragePoolName} (please check your storage infrastructure). |
984 | RECONSTRUCT_MASTER_DONE | Info | Reconstruct Master Domain for Data Center ${StoragePoolName} completed. |
985 | RECONSTRUCT_MASTER_FAILED | Error | Failed to Reconstruct Master Domain for Data Center ${StoragePoolName}. |
986 | SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_SEARCHING_NEW_SPM | Warning | Data Center is being initialized, please wait for initialization to complete. |
987 | SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_WITH_ERROR | Warning | Invalid status on Data Center ${StoragePoolName}. Setting Data Center status to Non Responsive (On host ${VdsName}, Error: ${Error}). |
988 | USER_CONNECT_HOSTS_TO_LUN_FAILED | Error | Failed to connect Host ${VdsName} to device. (User: ${UserName}) |
989 | SYSTEM_CHANGE_STORAGE_POOL_STATUS_PROBLEMATIC_FROM_NON_OPERATIONAL | Info | Try to recover Data Center ${StoragePoolName}. Setting status to Non Responsive. |
990 | SYSTEM_MASTER_DOMAIN_NOT_IN_SYNC | Warning | Sync Error on Master Domain between Host ${VdsName} and oVirt Engine. Domain: ${StorageDomainName} is marked as Master in oVirt Engine database but not on the Storage side. Please consult with Support on how to fix this issue. |
991 | RECOVERY_STORAGE_POOL | Info | Data Center ${StoragePoolName} was recovered by ${UserName} |
992 | RECOVERY_STORAGE_POOL_FAILED | Error | Failed to recover Data Center ${StoragePoolName} (User:${UserName}) |
993 | SYSTEM_CHANGE_STORAGE_POOL_STATUS_RESET_IRS | Info | Data Center ${StoragePoolName} was reset. Setting status to Non Responsive (Elect new Storage Pool Manager). |
994 | CONNECT_STORAGE_SERVERS_FAILED | Warning | Failed to connect Host ${VdsName} to Storage Servers |
995 | CONNECT_STORAGE_POOL_FAILED | Warning | Failed to connect Host ${VdsName} to Storage Pool ${StoragePoolName} |
996 | STORAGE_DOMAIN_ERROR | Error | The error message for connection ${Connection} returned by VDSM was: ${ErrorMessage} |
997 | REFRESH_REPOSITORY_IMAGE_LIST_FAILED | Error | Refresh image list failed for domain(s): ${imageDomains}. Please check domain activity. |
998 | REFRESH_REPOSITORY_IMAGE_LIST_SUCCEEDED | Info | Refresh image list succeeded for domain(s): ${imageDomains} |
999 | STORAGE_ALERT_VG_METADATA_CRITICALLY_FULL | Error | The system has reached the 80% watermark on the VG metadata area size on ${StorageDomainName}.\nThis is due to a high number of Vdisks or large Vdisks size allocated on this specific VG. |
1000 | STORAGE_ALERT_SMALL_VG_METADATA | Warning | The allocated VG metadata area size is smaller than 50MB on ${StorageDomainName},\nwhich might limit its capacity (the number of Vdisks and/or their size). |
1001 | USER_RUN_VM_FAILURE_STATELESS_SNAPSHOT_LEFT | Error | Failed to start VM ${VmName}, because exist snapshot for stateless state. Snapshot will be deleted. |
1002 | USER_ATTACH_STORAGE_DOMAINS_TO_POOL | Info | Storage Domains were attached to Data Center ${StoragePoolName} by ${UserName} |
1003 | USER_ATTACH_STORAGE_DOMAINS_TO_POOL_FAILED | Error | Failed to attach Storage Domains to Data Center ${StoragePoolName}. (User: ${UserName}) |
1004 | STORAGE_DOMAIN_TASKS_ERROR | Warning | Storage Domain ${StorageDomainName} is down while there are tasks running on it. These tasks may fail. |
1005 | UPDATE_OVF_FOR_STORAGE_POOL_FAILED | Warning | Failed to update VMs/Templates OVF data in Data Center ${StoragePoolName}. |
1006 | UPGRADE_STORAGE_POOL_ENCOUNTERED_PROBLEMS | Warning | Data Center ${StoragePoolName} has encountered problems during upgrade process. |
1007 | REFRESH_REPOSITORY_IMAGE_LIST_INCOMPLETE | Warning | Refresh image list probably incomplete for domain ${imageDomain}, only ${imageListSize} images discovered. |
1008 | NUNBER_OF_LVS_ON_STORAGE_DOMAIN_EXCEEDED_THRESHOLD | Warning | The number of LVs on the domain ${storageDomainName} exceeded ${maxNumOfLVs}, you are approaching the limit where performance may degrade. |
1010 | RELOAD_CONFIGURATIONS_SUCCESS | Info | System Configurations reloaded successfully. |
1011 | RELOAD_CONFIGURATIONS_FAILURE | Error | System Configurations failed to reload. |
1012 | NETWORK_ACTIVATE_VM_INTERFACE_SUCCESS | Info | Network Interface ${InterfaceName} (${InterfaceType}) was plugged to VM ${VmName}. (User: ${UserName}) |
1013 | NETWORK_ACTIVATE_VM_INTERFACE_FAILURE | Error | Failed to plug Network Interface ${InterfaceName} (${InterfaceType}) to VM ${VmName}. (User: ${UserName}) |
1014 | NETWORK_DEACTIVATE_VM_INTERFACE_SUCCESS | Info | Network Interface ${InterfaceName} (${InterfaceType}) was unplugged from VM ${VmName}. (User: ${UserName}) |
1015 | NETWORK_DEACTIVATE_VM_INTERFACE_FAILURE | Error | Failed to unplug Network Interface ${InterfaceName} (${InterfaceType}) from VM ${VmName}. (User: ${UserName}) |
1016 | UPDATE_FOR_OVF_STORES_FAILED | Warning | Failed to update OVF disks ${DisksIds}, OVF data isn't updated on those OVF stores (Data Center ${DataCenterName}, Storage Domain ${StorageDomainName}). |
1017 | RETRIEVE_OVF_STORE_FAILED | Warning | Failed to retrieve VMs and Templates from the OVF disk of Storage Domain ${StorageDomainName}. |
1018 | OVF_STORE_DOES_NOT_EXISTS | Warning | The Storage Domain does not contain any OVF_STORE disks. Usually the Storage Domain does not contain OVF_STORE disks when the Storage Domain has been previously managed with a Data Center version lower then 3.5. |
1019 | UPDATE_DESCRIPTION_FOR_DISK_FAILED | Error | Failed to update the meta data description of disk ${DiskName} (Data Center ${DataCenterName}, Storage Domain ${StorageDomainName}). |
1020 | UPDATE_DESCRIPTION_FOR_DISK_SKIPPED_SINCE_STORAGE_DOMAIN_NOT_ACTIVE | Warning | Not updating the metadata of Disk ${DiskName} (Data Center ${DataCenterName}. Since the Storage Domain ${StorageDomainName} is not in active. |
1021 | RETRIEVE_UNREGISTERED_ENTITIES_NOT_SUPPORTED_IN_DC_VERSION | Warning | Skipping retrieval attempt of VMs and Templates from the OVF_STORE disk of Storage Domain ${StorageDomainName} since it is not supported by the Data Center version. |
1098 | NETWORK_UPDATE_DISPLAY_FOR_HOST_WITH_ACTIVE_VM | Warning | Display Network was updated on Host ${VdsName} with active VMs attached. The change will be applied to those VMs after their next reboot. Running VMs might loose display connectivity until then. |
1099 | NETWORK_UPDATE_DISPLAY_FOR_CLUSTER_WITH_ACTIVE_VM | Warning | Display Network (${NetworkName}) was updated for Cluster ${VdsGroupName} with active VMs attached. The change will be applied to those VMs after their next reboot. |
1100 | NETWORK_UPDATE_DISPLAY_TO_VDS_GROUP | Info | Update Display Network (${NetworkName}) for Cluster ${VdsGroupName}. (User: ${UserName}) |
1101 | NETWORK_UPDATE_DISPLAY_TO_VDS_GROUP_FAILED | Error | Failed to update Display Network (${NetworkName}) for Cluster ${VdsGroupName}. (User: ${UserName}) |
1102 | NETWORK_UPDATE_NETWORK_TO_VDS_INTERFACE | Info | Update Network ${NetworkName} in Host ${VdsName}. (User: ${UserName}) |
1103 | NETWORK_UPDATE_NETWORK_TO_VDS_INTERFACE_FAILED | Error | Failed to update Network ${NetworkName} in Host ${VdsName}. (User: ${UserName}) |
1104 | NETWORK_COMMINT_NETWORK_CHANGES | Info | Network changes were saved on host ${VdsName} |
1105 | NETWORK_COMMINT_NETWORK_CHANGES_FAILED | Error | Failed to commit network changes on ${VdsName} |
1106 | NETWORK_HOST_USING_WRONG_CLUSER_VLAN | Warning | ${VdsName} is having wrong vlan id: ${VlanIdHost}, expected vlan id: ${VlanIdCluster} |
1107 | NETWORK_HOST_MISSING_CLUSER_VLAN | Warning | ${VdsName} is missing vlan id: ${VlanIdCluster} that is expected by the cluster |
1108 | VDS_NETWORK_MTU_DIFFER_FROM_LOGICAL_NETWORK | Info | |
1109 | BRIDGED_NETWORK_OVER_MULTIPLE_INTERFACES | Warning | Bridged network ${NetworkName} is attached to multiple interfaces: ${Interfaces} on Host ${VdsName}. |
1110 | VDS_NETWORKS_OUT_OF_SYNC | Warning | Host ${VdsName}'s following network(s) are not synchronized with their Logical Network configuration: ${Networks}. |
1112 | NETWORK_UPDTAE_NETWORK_ON_CLUSTER | Info | Network ${NetworkName} on Cluster ${VdsGroupName} updated. |
1113 | NETWORK_UPDTAE_NETWORK_ON_CLUSTER_FAILED | Error | Failed to update Network ${NetworkName} on Cluster ${VdsGroupName}. |
1114 | NETWORK_UPDATE_NETWORK | Info | Network ${NetworkName} was updated on Data Center: ${StoragePoolName} |
1115 | NETWORK_UPDATE_NETWORK_FAILED | Error | Failed to update Network ${NetworkName} on Data Center: ${StoragePoolName} |
1116 | NETWORK_UPDATE_VM_INTERFACE_LINK_UP | Info | Link State is UP. |
1117 | NETWORK_UPDATE_VM_INTERFACE_LINK_DOWN | Info | Link State is DOWN. |
1118 | INVALID_INTERFACE_FOR_MANAGEMENT_NETWORK_CONFIGURATION | Error | Failed to configure management network on host ${VdsName}. Host ${VdsName} has an invalid interface ${InterfaceName} for the management network configuration. |
1119 | VLAN_ID_MISMATCH_FOR_MANAGEMENT_NETWORK_CONFIGURATION | Error | Failed to configure management network on host ${VdsName}. Host ${VdsName} has an interface ${InterfaceName} for the management network configuration with VLAN-ID (${VlanId}), which is different from data-center definition (${MgmtVlanId}). |
1120 | SETUP_NETWORK_FAILED_FOR_MANAGEMENT_NETWORK_CONFIGURATION | Error | Failed to configure management network on host ${VdsName} due to setup networks failure. |
1121 | PERSIST_NETWORK_FAILED_FOR_MANAGEMENT_NETWORK | Warning | Failed to activate host ${VdsName} due to failure in persisting the management network configuration. |
1122 | ADD_VNIC_PROFILE | Info | VM network interface profile ${VnicProfileName} was added to network ${NetworkName} in Data Center: ${DataCenterName}. (User: ${UserName}) |
1123 | ADD_VNIC_PROFILE_FAILED | Error | Failed to add VM network interface profile ${VnicProfileName} to network ${NetworkName} in Data Center: ${DataCenterName} (User: ${UserName}) |
1124 | UPDATE_VNIC_PROFILE | Info | VM network interface profile ${VnicProfileName} was updated for network ${NetworkName} in Data Center: ${DataCenterName}. (User: ${UserName}) |
1125 | UPDATE_VNIC_PROFILE_FAILED | Error | Failed to update VM network interface profile ${VnicProfileName} for network ${NetworkName} in Data Center: ${DataCenterName}. (User: ${UserName}) |
1126 | REMOVE_VNIC_PROFILE | Info | VM network interface profile ${VnicProfileName} was removed from network ${NetworkName} in Data Center: ${DataCenterName}. (User: ${UserName}) |
1127 | REMOVE_VNIC_PROFILE_FAILED | Error | Failed to remove VM network interface profile ${VnicProfileName} from network ${NetworkName} in Data Center: ${DataCenterName}. (User: ${UserName}) |
1128 | NETWORK_WITHOUT_INTERFACES | Warning | Network ${NetworkName} is not attached to any interface on host ${VdsName}. |
1129 | VNIC_PROFILE_UNSUPPORTED_FEATURES | Warning | VM ${VmName} has network interface ${NicName} which is using profile ${VnicProfile} with unsupported feature(s) '${UnsupportedFeatures}' by VM cluster ${VdsGroupName} (version ${CompatibilityVersion}). |
1130 | ADD_NETWORK_BY_LABEL_FAILED | Error | Network ${Network} cannot be configured using the label ${Label} in data-center ${StoragePoolName} on the following hosts: ${HostNames}. |
1131 | REMOVE_NETWORK_BY_LABEL_FAILED | Error | Network ${Network} cannot be removed from the following hosts: ${HostNames} in data-center ${StoragePoolName}. |
1132 | LABEL_NETWORK | Info | Network ${NetworkName} was labeled ${Label} in data-center ${StoragePoolName}. |
1133 | LABEL_NETWORK_FAILED | Error | Failed to label network ${NetworkName} with label ${Label} in data-center ${StoragePoolName}. |
1134 | UNLABEL_NETWORK | Info | Network ${NetworkName} was unlabeled in data-center ${StoragePoolName}. |
1135 | UNLABEL_NETWORK_FAILED | Error | Failed to unlabel network ${NetworkName} in data-center ${StoragePoolName}. |
1136 | LABEL_NIC | Info | Network interface card ${NicName} was labeled ${Label} on host ${VdsName}. |
1137 | LABEL_NIC_FAILED | Error | Failed to label network interface card ${NicName} with label ${Label} on host ${VdsName}. |
1138 | UNLABEL_NIC | Info | Label ${Label} was removed from network interface card ${NicName} on host ${VdsName}. |
1139 | UNLABEL_NIC_FAILED | Error | Failed to remove label ${Label} from network interface card ${NicName} on host ${VdsName}. |
1140 | SUBNET_REMOVED | Info | Subnet ${SubnetName} was removed from provider ${ProviderName}. (User: ${UserName}) |
1141 | SUBNET_REMOVAL_FAILED | Error | Failed to remove subnet ${SubnetName} from provider ${ProviderName}. (User: ${UserName}) |
1142 | SUBNET_ADDED | Info | Subnet ${SubnetName} was added on provider ${ProviderName}. (User: ${UserName}) |
1143 | SUBNET_ADDITION_FAILED | Error | Failed to add subnet ${SubnetName} on provider ${ProviderName}. (User: ${UserName}) |
1144 | CONFIGURE_NETWORK_BY_LABELS_WHEN_CHANGING_CLUSTER_FAILED | Error | Failed to configure networks on host ${VdsName} while changing its cluster. |
1145 | PERSIST_NETWORK_ON_HOST | Info | (${Sequence}/${Total}): Applying changes for network(s) ${NetworkNames} on host ${VdsName}. (User: ${UserName}) |
1146 | PERSIST_NETWORK_ON_HOST_FINISHED | Info | (${Sequence}/${Total}): Successfully applied changes for network(s) ${NetworkNames} on host ${VdsName}. (User: ${UserName}) |
1147 | PERSIST_NETWORK_ON_HOST_FAILED | Error | (${Sequence}/${Total}): Failed to apply changes for network(s) ${NetworkNames} on host ${VdsName}. (User: ${UserName}) |
1148 | MULTI_UPDATE_NETWORK_NOT_POSSIBLE | Warning | Cannot apply network ${NetworkName} changes to hosts on unsupported data center ${StoragePoolName}. (User: ${UserName}) |
1149 | REMOVE_PORT_FROM_EXTERNAL_PROVIDER_FAILED | Warning | Failed to remove vNIC ${NicName} from external network provider ${ProviderName}. The vNIC can be identified on the provider by device id ${NicId}. |
1150 | IMPORTEXPORT_EXPORT_VM | Info | Vm ${VmName} was exported successfully to ${StorageDomainName} |
1151 | IMPORTEXPORT_EXPORT_VM_FAILED | Error | Failed to export Vm ${VmName} to ${StorageDomainName} |
1152 | IMPORTEXPORT_IMPORT_VM | Info | Vm ${VmName} was imported successfully to Data Center ${StoragePoolName}, Cluster ${VdsGroupName} |
1153 | IMPORTEXPORT_IMPORT_VM_FAILED | Error | Failed to import Vm ${VmName} to Data Center ${StoragePoolName}, Cluster ${VdsGroupName} |
1154 | IMPORTEXPORT_REMOVE_TEMPLATE | Info | Template ${VmTemplateName} was removed from ${StorageDomainName} |
1155 | IMPORTEXPORT_REMOVE_TEMPLATE_FAILED | Error | Failed to remove Template ${VmTemplateName} from ${StorageDomainName} |
1156 | IMPORTEXPORT_EXPORT_TEMPLATE | Info | Template ${VmTemplateName} was exported successfully to ${StorageDomainName} |
1157 | IMPORTEXPORT_EXPORT_TEMPLATE_FAILED | Error | Failed to export Template ${VmTemplateName} to ${StorageDomainName} |
1158 | IMPORTEXPORT_IMPORT_TEMPLATE | Info | Template ${VmTemplateName} was imported successfully to Data Center ${StoragePoolName}, Cluster ${VdsGroupName} |
1159 | IMPORTEXPORT_IMPORT_TEMPLATE_FAILED | Error | Failed to import Template ${VmTemplateName} to Data Center ${StoragePoolName}, Cluster ${VdsGroupName} |
1160 | IMPORTEXPORT_REMOVE_VM | Info | Vm ${VmName} was removed from ${StorageDomainName} |
1161 | IMPORTEXPORT_REMOVE_VM_FAILED | Error | Failed to remove Vm ${VmName} remove from ${StorageDomainName} |
1162 | IMPORTEXPORT_STARTING_EXPORT_VM | Info | Starting export Vm ${VmName} to ${StorageDomainName} |
1163 | IMPORTEXPORT_STARTING_IMPORT_TEMPLATE | Info | Starting to import Template ${VmTemplateName} to Data Center ${StoragePoolName}, Cluster ${VdsGroupName} |
1164 | IMPORTEXPORT_STARTING_EXPORT_TEMPLATE | Info | Starting to export Template ${VmTemplateName} to ${StorageDomainName} |
1165 | IMPORTEXPORT_STARTING_IMPORT_VM | Info | Starting to import Vm ${VmName} to Data Center ${StoragePoolName}, Cluster ${VdsGroupName} |
1166 | IMPORTEXPORT_STARTING_REMOVE_TEMPLATE | Info | Starting to remove Template ${VmTemplateName} remove ${StorageDomainName} |
1167 | IMPORTEXPORT_STARTING_REMOVE_VM | Info | Starting to remove Vm ${VmName} remove from ${StorageDomainName} |
1168 | IMPORTEXPORT_FAILED_TO_IMPORT_VM | Warning | Failed to read VM '${ImportedVmName}' OVF, it may be corrupted |
1169 | IMPORTEXPORT_FAILED_TO_IMPORT_TEMPLATE | Warning | Failed to read Template '${Template}' OVF, it may be corrupted |
1170 | IMPORTEXPORT_IMPORT_TEMPLATE_INVALID_INTERFACES | Normal | While importing Template ${EntityName}, the Network/s ${Networks} were found to be Non-VM Networks or do not exist in Cluster. Network Name was not set in the Interface/s ${Interfaces}. |
1171 | USER_ACCOUNT_PASSWORD_EXPIRED | Error | User ${UserName} cannot login, as the user account password has expired. Please contact the system administrator. |
1172 | AUTH_FAILED_INVALID_CREDENTIALS | Error | User ${UserName} cannot login, please verify the username and password. |
1173 | AUTH_FAILED_CLOCK_SKEW_TOO_GREAT | Error | User ${UserName} cannot login, the engine clock is not synchronized with directory services. Please contact the system administrator. |
1174 | AUTH_FAILED_NO_KDCS_FOUND | Error | User ${UserName} cannot login, authentication domain cannot be found. Please contact the system administrator. |
1175 | AUTH_FAILED_DNS_ERROR | Error | User ${UserName} cannot login, there's an error in DNS configuration. Please contact the system administrator. |
1176 | AUTH_FAILED_OTHER | Error | User ${UserName} cannot login, unknown kerberos error. Please contact the system administrator. |
1177 | AUTH_FAILED_DNS_COMMUNICATION_ERROR | Error | User ${UserName} cannot login, cannot lookup DNS for SRV records. Please contact the system administrator. |
1178 | AUTH_FAILED_CONNECTION_TIMED_OUT | Error | User ${UserName} cannot login, connection to LDAP server has timed out. Please contact the system administrator. |
1179 | AUTH_FAILED_WRONG_REALM | Error | User ${UserName} cannot login, please verify your domain name. |
1180 | AUTH_FAILED_CONNECTION_ERROR | Error | User ${UserName} cannot login, connection refused or some configuration problems exist. Possible DNS error. Please contact the system administrator. |
1181 | AUTH_FAILED_CANNOT_FIND_LDAP_SERVER_FOR_DOMAIN | Error | User ${UserName} cannot login, cannot find valid LDAP server for domain. Please contact the system administrator. |
1182 | AUTH_FAILED_NO_USER_INFORMATION_WAS_FOUND | Error | User ${UserName} cannot login, no user information was found. Please contact the system administrator. |
1183 | AUTH_FAILED_CLIENT_NOT_FOUND_IN_KERBEROS_DATABASE | Error | User ${UserName} cannot login, user was not found in domain. Please contact the system administrator. |
1184 | AUTH_FAILED_INTERNAL_KERBEROS_ERROR | Error | User ${UserName} cannot login, an internal error has ocurred in the Kerberos implementation of the JVM. Please contact the system administrator. |
1185 | USER_ACCOUNT_EXPIRED | Error | The account for ${UserName} got expired. Please contact the system administrator. |
1189 | IMPORTEXPORT_IMPORT_VM_FAILED_UPDATING_OVF | Error | Failed to import Vm ${VmName} to Data Center ${StoragePoolName}, Cluster ${VdsGroupName}, could not update VM data in export. |
1190 | USER_RESTORE_FROM_SNAPSHOT_START | Info | Restoring VM ${VmName} from snapshot started by user ${UserName}. |
1200 | ENTITY_RENAMED | Info | ${EntityType} ${OldEntityName} was renamed from ${OldEntityName} to ${NewEntityName} by ${UserName}. |
1300 | NUMA_ADD_VM_NUMA_NODE_SUCCESS | Info | Add VM NUMA node successfully. |
1301 | NUMA_ADD_VM_NUMA_NODE_FAILED | Error | Add VM NUMA node failed. |
1310 | NUMA_UPDATE_VM_NUMA_NODE_SUCCESS | Info | Update VM NUMA node successfully. |
1311 | NUMA_UPDATE_VM_NUMA_NODE_FAILED | Error | Update VM NUMA node failed. |
1320 | NUMA_REMOVE_VM_NUMA_NODE_SUCCESS | Info | Remove VM NUMA node successfully. |
1321 | NUMA_REMOVE_VM_NUMA_NODE_FAILED | Error | Remove VM NUMA node failed. |
2000 | USER_HOTPLUG_DISK | Info | VM ${VmName} disk ${DiskAlias} was plugged by ${UserName}. |
2001 | USER_FAILED_HOTPLUG_DISK | Error | Failed to plug disk ${DiskAlias} to VM ${VmName} (User: ${UserName}). |
2002 | USER_HOTUNPLUG_DISK | Info | VM ${VmName} disk ${DiskAlias} was unplugged by ${UserName}. |
2003 | USER_FAILED_HOTUNPLUG_DISK | Error | Failed to unplug disk ${DiskAlias} from VM ${VmName} (User: ${UserName}). |
2004 | USER_COPIED_TEMPLATE_DISK | Info | User ${UserName} is copying template disk ${DiskAlias} to domain ${StorageDomainName}. |
2005 | USER_FAILED_COPY_TEMPLATE_DISK | Error | User ${UserName} failed to copy template disk ${DiskAlias} to domain ${StorageDomainName}. |
2006 | USER_COPIED_TEMPLATE_DISK_FINISHED_SUCCESS | Info | User ${UserName} finished copying template disk ${DiskAlias} to domain ${StorageDomainName}. |
2007 | USER_COPIED_TEMPLATE_DISK_FINISHED_FAILURE | Error | User ${UserName} finished with error copying template disk ${DiskAlias} to domain ${StorageDomainName}. |
2008 | USER_MOVED_VM_DISK | Info | User ${UserName} moving disk ${DiskAlias} to domain ${StorageDomainName}. |
2009 | USER_FAILED_MOVED_VM_DISK | Error | User ${UserName} failed to move disk ${DiskAlias} to domain ${StorageDomainName}. |
2010 | USER_MOVED_VM_DISK_FINISHED_SUCCESS | Info | User ${UserName} finished moving disk ${DiskAlias} to domain ${StorageDomainName}. |
2011 | USER_MOVED_VM_DISK_FINISHED_FAILURE | Error | User ${UserName} have failed to move disk ${DiskAlias} to domain ${StorageDomainName}. |
2012 | USER_FINISHED_REMOVE_DISK_NO_DOMAIN | Info | Disk ${DiskAlias} was successfully removed (User ${UserName}). |
2013 | USER_FINISHED_FAILED_REMOVE_DISK_NO_DOMAIN | Warning | Failed to remove disk ${DiskAlias} (User ${UserName}). |
2014 | USER_FINISHED_REMOVE_DISK | Info | Disk ${DiskAlias} was successfully removed from domain ${StorageDomainName} (User ${UserName}). |
2015 | USER_FINISHED_FAILED_REMOVE_DISK | Warning | Failed to remove disk ${DiskAlias} from storage domain ${StorageDomainName} (User: ${UserName}). |
2016 | USER_ATTACH_DISK_TO_VM | Info | Disk ${DiskAlias} was successfully attached to VM ${VmName} by ${UserName}. |
2017 | USER_FAILED_ATTACH_DISK_TO_VM | Error | Failed to attach Disk ${DiskAlias} to VM ${VmName} (User: ${UserName}). |
2018 | USER_DETACH_DISK_FROM_VM | Info | Disk ${DiskAlias} was successfully detached from VM ${VmName} by ${UserName}. |
2019 | USER_FAILED_DETACH_DISK_FROM_VM | Error | Failed to detach Disk ${DiskAlias} from VM ${VmName} (User: ${UserName}). |
2020 | USER_ADD_DISK | Info | Add-Disk operation of '${DiskAlias}' was initiated by ${UserName}. |
2021 | USER_ADD_DISK_FINISHED_SUCCESS | Info | The disk '${DiskAlias}' was successfully added. |
2022 | USER_ADD_DISK_FINISHED_FAILURE | Error | Operation Add-Disk failed to complete. |
2023 | USER_FAILED_ADD_DISK | Error | Operation Add-Disk failed (User: ${UserName}). |
2024 | USER_RUN_UNLOCK_ENTITY_SCRIPT | Info | |
2025 | USER_MOVE_IMAGE_GROUP_FAILED_TO_DELETE_SRC_IMAGE | Warning | Possible failure while deleting ${DiskAlias} from the source Storage Domain ${StorageDomainName} during the move operation. The Storage Domain may be manually cleaned-up from possible leftovers (User:${UserName}). |
2026 | USER_MOVE_IMAGE_GROUP_FAILED_TO_DELETE_DST_IMAGE | Warning | Possible failure while clearing possible leftovers of ${DiskAlias} from the target Storage Domain ${StorageDomainName} after the move operation failed to copy the image to it properly. The Storage Domain may be manually cleaned-up from possible leftovers (User:${UserName}). |
2027 | USER_IMPORT_IMAGE | Info | User ${UserName} importing image ${RepoImageName} to domain ${StorageDomainName}. |
2028 | USER_IMPORT_IMAGE_FINISHED_SUCCESS | Info | User ${UserName} successfully imported image ${RepoImageName} to domain ${StorageDomainName}. |
2029 | USER_IMPORT_IMAGE_FINISHED_FAILURE | Error | User ${UserName} failed to import image ${RepoImageName} to domain ${StorageDomainName}. |
2030 | USER_EXPORT_IMAGE | Info | User ${UserName} exporting image ${RepoImageName} to domain ${DestinationStorageDomainName}. |
2031 | USER_EXPORT_IMAGE_FINISHED_SUCCESS | Info | User ${UserName} successfully exported image ${RepoImageName} to domain ${DestinationStorageDomainName}. |
2032 | USER_EXPORT_IMAGE_FINISHED_FAILURE | Error | User ${UserName} failed to export image ${RepoImageName} to domain ${DestinationStorageDomainName}. |
2033 | HOT_SET_NUMBER_OF_CPUS | Info | VM ${vmName} number of CPUs is hot set to ${numberOfCpus} |
2034 | FAILED_HOT_SET_NUMBER_OF_CPUS | Error | Failed to hot set number of CPUS to VM ${vmName}. Underlying error message: ${ErrorMessage} |
2035 | USER_ISCSI_BOND_HOST_RESTART_WARNING | Warning | The following Networks has been removed from the iSCSI bond ${IscsiBondName}: ${NetworkNames}. for those changes to take affect, the hosts must be moved to maintenance and activated again. |
2036 | ADD_DISK_INTERNAL | Info | Add-Disk operation of '${DiskAlias}' was initiated by the system. |
2037 | ADD_DISK_INTERNAL_FAILURE | Info | Add-Disk operation of '${DiskAlias}' failed to complete. |
3000 | USER_ADD_QUOTA | Info | Quota ${QuotaName} has been added by ${UserName}. |
3001 | USER_FAILED_ADD_QUOTA | Error | Failed to add Quota ${QuotaName}. The operation was initiated by ${UserName}. |
3002 | USER_UPDATE_QUOTA | Info | Quota ${QuotaName} has been updated by ${UserName}. |
3003 | USER_FAILED_UPDATE_QUOTA | Error | Failed to update Quota ${QuotaName}. The operation was initiated by ${UserName}.. |
3004 | USER_DELETE_QUOTA | Info | Quota ${QuotaName} has been deleted by ${UserName}. |
3005 | USER_FAILED_DELETE_QUOTA | Error | Failed to delete Quota ${QuotaName}. The operation was initiated by ${UserName}.. |
3006 | USER_EXCEEDED_QUOTA_VDS_GROUP_GRACE_LIMIT | Error | Cluster-Quota ${QuotaName} limit exceeded and operation was blocked. Utilization: ${Utilization}, Requested: ${Requested} - Please select a different quota or contact your administrator to extend the quota. |
3007 | USER_EXCEEDED_QUOTA_VDS_GROUP_LIMIT | Warning | Cluster-Quota ${QuotaName} limit exceeded and entered the grace zone. Utilization: ${Utilization} (It is advised to select a different quota or contact your administrator to extend the quota). |
3008 | USER_EXCEEDED_QUOTA_VDS_GROUP_THRESHOLD | Warning | Cluster-Quota ${QuotaName} is about to exceed. Utilization: ${Utilization} |
3009 | USER_EXCEEDED_QUOTA_STORAGE_GRACE_LIMIT | Error | Storage-Quota ${QuotaName} limit exceeded and operation was blocked. Utilization(used/requested): ${CurrentStorage}%/${Requested}% - Please select a different quota or contact your administrator to extend the quota. |
3010 | USER_EXCEEDED_QUOTA_STORAGE_LIMIT | Warning | Storage-Quota ${QuotaName} limit exceeded and entered the grace zone. Utilization: ${CurrentStorage}% (It is advised to select a different quota or contact your administrator to extend the quota). |
3011 | USER_EXCEEDED_QUOTA_STORAGE_THRESHOLD | Warning | Storage-Quota ${QuotaName} is about to exceed. Utilization: ${CurrentStorage}% |
3012 | QUOTA_STORAGE_RESIZE_LOWER_THEN_CONSUMPTION | Warning | Storage-Quota ${QuotaName}: the new size set for this quota is less than current disk utilization. |
3013 | MISSING_QUOTA_STORAGE_PARAMETERS_PERMISSIVE_MODE | Warning | Missing Quota for Disk, proceeding since in Permissive (Audit) mode. |
3014 | MISSING_QUOTA_CLUSTER_PARAMETERS_PERMISSIVE_MODE | Warning | Missing Quota for VM ${VmName}, proceeding since in Permissive (Audit) mode. |
3015 | USER_EXCEEDED_QUOTA_VDS_GROUP_GRACE_LIMIT_PERMISSIVE_MODE | Warning | Cluster-Quota ${QuotaName} limit exceeded, proceeding since in Permissive (Audit) mode. Utilization: ${Utilization}, Requested: ${Requested} - Please select a different quota or contact your administrator to extend the quota. |
3016 | USER_EXCEEDED_QUOTA_STORAGE_GRACE_LIMIT_PERMISSIVE_MODE | Warning | Storage-Quota ${QuotaName} limit exceeded, proceeding since in Permissive (Audit) mode. Utilization(used/requested): ${CurrentStorage}%/${Requested}% - Please select a different quota or contact your administrator to extend the quota. |
4000 | GLUSTER_VOLUME_CREATE | Info | Gluster Volume ${glusterVolumeName} created. |
4001 | GLUSTER_VOLUME_CREATE_FAILED | Error | Creation of Gluster Volume ${glusterVolumeName} failed. |
4002 | GLUSTER_VOLUME_OPTION_ADDED | Info | Volume Option ${Key} |
4003 | GLUSTER_VOLUME_OPTION_SET_FAILED | Error | Volume Option ${Key} |
4004 | GLUSTER_VOLUME_START | Info | Gluster Volume ${glusterVolumeName} started. |
4005 | GLUSTER_VOLUME_START_FAILED | Error | Could not start Gluster Volume ${glusterVolumeName}. |
4006 | GLUSTER_VOLUME_STOP | Info | Gluster Volume ${glusterVolumeName} stopped. |
4007 | GLUSTER_VOLUME_STOP_FAILED | Error | Could not stop Gluster Volume ${glusterVolumeName}. |
4008 | GLUSTER_VOLUME_OPTIONS_RESET | Info | Volume Option ${Key} |
4009 | GLUSTER_VOLUME_OPTIONS_RESET_FAILED | Error | Could not reset Gluster Volume ${glusterVolumeName} Options. |
4010 | GLUSTER_VOLUME_DELETE | Info | Gluster Volume ${glusterVolumeName} deleted. |
4011 | GLUSTER_VOLUME_DELETE_FAILED | Error | Could not delete Gluster Volume ${glusterVolumeName}. |
4012 | GLUSTER_VOLUME_REBALANCE_START | Info | Gluster Volume ${glusterVolumeName} rebalance started. |
4013 | GLUSTER_VOLUME_REBALANCE_START_FAILED | Error | Could not start Gluster Volume ${glusterVolumeName} rebalance. |
4014 | GLUSTER_VOLUME_REMOVE_BRICKS | Info | Bricks removed from Gluster Volume ${glusterVolumeName}. |
4015 | GLUSTER_VOLUME_REMOVE_BRICKS_FAILED | Error | Could not remove Gluster Volume ${glusterVolumeName} Bricks. |
4016 | GLUSTER_VOLUME_REPLACE_BRICK_FAILED | Error | Replace Gluster Volume ${glusterVolumeName} Brick failed |
4017 | GLUSTER_VOLUME_REPLACE_BRICK_START | Info | Gluster Volume ${glusterVolumeName} Replace Brick started. |
4018 | GLUSTER_VOLUME_REPLACE_BRICK_START_FAILED | Error | Could not start Gluster Volume ${glusterVolumeName} Replace Brick. |
4019 | GLUSTER_VOLUME_ADD_BRICK | Info | ${NoOfBricks} brick(s) added to volume ${glusterVolumeName}. |
4020 | GLUSTER_VOLUME_ADD_BRICK_FAILED | Error | Gluster Volume ${glusterVolumeName} add brick failed. |
4021 | GLUSTER_SERVER_REMOVE_FAILED | Error | Failed to remove host ${VdsName} from Cluster ${VdsGroupName}. |
4022 | GLUSTER_VOLUME_PROFILE_START | Info | Gluster Volume ${glusterVolumeName} Profile started. |
4023 | GLUSTER_VOLUME_PROFILE_START_FAILED | Error | Could not start Profiling on gluster volume ${glusterVolumeName} |
4024 | GLUSTER_VOLUME_PROFILE_STOP | Info | Gluster Volume ${glusterVolumeName} Profile stopped. |
4025 | GLUSTER_VOLUME_PROFILE_STOP_FAILED | Error | Could not stop Profiling on gluster volume ${glusterVolumeName}. |
4026 | GLUSTER_VOLUME_CREATED_FROM_CLI | Warning | Detected new volume ${glusterVolumeName} on cluster ${VdsGroupName}, and added it to engine DB. |
4027 | GLUSTER_VOLUME_DELETED_FROM_CLI | Warning | Detected deletion of volume ${glusterVolumeName} on cluster ${VdsGroupName}, and deleted it from engine DB. |
4028 | GLUSTER_VOLUME_OPTION_SET_FROM_CLI | Warning | Detected new option ${key} |
4029 | GLUSTER_VOLUME_OPTION_RESET_FROM_CLI | Warning | Detected option ${key} |
4030 | GLUSTER_VOLUME_PROPERTIES_CHANGED_FROM_CLI | Warning | Detected changes in properties of volume ${glusterVolumeName} of cluster ${VdsGroupName}, and updated the same in engine DB. |
4031 | GLUSTER_VOLUME_BRICK_ADDED_FROM_CLI | Warning | Detected new brick ${brick} on volume ${glusterVolumeName} of cluster ${VdsGroupName}, and added it to engine DB. |
4032 | GLUSTER_VOLUME_BRICK_REMOVED_FROM_CLI | Warning | Detected brick ${brick} removed from Volume ${glusterVolumeName} of cluster ${VdsGroupName}, and removed it from engine DB. |
4033 | GLUSTER_SERVER_REMOVED_FROM_CLI | Warning | Detected server ${VdsName} removed from Cluster ${VdsGroupName}, and removed it from engine DB. |
4034 | GLUSTER_VOLUME_INFO_FAILED | Error | Failed to fetch gluster volume list from server ${VdsName}. |
4035 | GLUSTER_COMMAND_FAILED | Error | Gluster command [${Command}] failed on server ${VdsName}. |
4038 | GLUSTER_SERVER_REMOVE | Info | Host ${VdsName} removed from Cluster ${VdsGroupName}. |
4039 | GLUSTER_VOLUME_STARTED_FROM_CLI | Warning | Detected that Volume ${glusterVolumeName} of Cluster ${VdsGroupName} was started, and updated engine DB with it's new status. |
4040 | GLUSTER_VOLUME_STOPPED_FROM_CLI | Warning | Detected that Volume ${glusterVolumeName} of Cluster ${VdsGroupName} was stopped, and updated engine DB with it's new status. |
4041 | GLUSTER_VOLUME_OPTION_CHANGED_FROM_CLI | Info | Detected change in value of option ${key} from ${oldValue} to ${newValue} on volume ${glusterVolumeName} of cluster ${VdsGroupName}, and updated it to engine DB. |
4042 | GLUSTER_HOOK_ENABLE | Info | Gluster Hook ${GlusterHookName} enabled on cluster ${VdsGroupName}. |
4043 | GLUSTER_HOOK_ENABLE_FAILED | Error | Failed to enable Gluster Hook ${GlusterHookName} on cluster ${VdsGroupName}. ${FailureMessage} |
4044 | GLUSTER_HOOK_ENABLE_PARTIAL | Warning | Gluster Hook ${GlusterHookName} enabled on some of the servers on cluster ${VdsGroupName}. ${FailureMessage} |
4045 | GLUSTER_HOOK_DISABLE | Info | Gluster Hook ${GlusterHookName} disabled on cluster ${VdsGroupName}. |
4046 | GLUSTER_HOOK_DISABLE_FAILED | Error | Failed to disable Gluster Hook ${GlusterHookName} on cluster ${VdsGroupName}. ${FailureMessage} |
4047 | GLUSTER_HOOK_DISABLE_PARTIAL | Warning | Gluster Hook ${GlusterHookName} disabled on some of the servers on cluster ${VdsGroupName}. ${FailureMessage} |
4048 | GLUSTER_HOOK_LIST_FAILED | Error | Failed to retrieve hook list from ${VdsName} of Cluster ${VdsGroupName}. |
4049 | GLUSTER_HOOK_CONFLICT_DETECTED | Warning | Detected conflict in hook ${HookName} of Cluster ${VdsGroupName}. |
4050 | GLUSTER_HOOK_DETECTED_NEW | Info | Detected new hook ${HookName} in Cluster ${VdsGroupName}. |
4051 | GLUSTER_HOOK_DETECTED_DELETE | Info | Detected removal of hook ${HookName} in Cluster ${VdsGroupName}. |
4052 | GLUSTER_VOLUME_OPTION_MODIFIED | Info | Volume Option ${Key} changed to ${Value} from ${oldvalue} on ${glusterVolumeName}. |
4053 | GLUSTER_HOOK_GETCONTENT_FAILED | Error | Failed to read content of hook ${HookName} in Cluster ${VdsGroupName}. |
4054 | GLUSTER_SERVICES_LIST_FAILED | Error | Could not fetch statuses of services from server ${VdsName}. Updating statuses of all services on this server to UNKNOWN. |
4055 | GLUSTER_SERVICE_TYPE_ADDED_TO_CLUSTER | Info | Service type ${ServiceType} was not mapped to cluster ${VdsGroupName}. Mapped it now. |
4056 | GLUSTER_CLUSTER_SERVICE_STATUS_CHANGED | Info | Status of service type ${ServiceType} changed from ${OldStatus} to ${NewStatus} on cluster ${VdsGroupName} |
4057 | GLUSTER_SERVICE_ADDED_TO_SERVER | Info | Service ${ServiceName} was not mapped to server ${VdsName}. Mapped it now. |
4058 | GLUSTER_SERVER_SERVICE_STATUS_CHANGED | Info | Status of service ${ServiceName} on server ${VdsName} changed from ${OldStatus} to ${NewStatus}. Updating in engine now. |
4059 | GLUSTER_HOOK_UPDATED | Info | Gluster Hook ${GlusterHookName} updated on conflicting servers. |
4060 | GLUSTER_HOOK_UPDATE_FAILED | Error | Failed to update Gluster Hook ${GlusterHookName} on conflicting servers. ${FailureMessage} |
4061 | GLUSTER_HOOK_ADDED | Info | Gluster Hook ${GlusterHookName} added on conflicting servers. |
4062 | GLUSTER_HOOK_ADD_FAILED | Error | Failed to add Gluster Hook ${GlusterHookName} on conflicting servers. ${FailureMessage} |
4063 | GLUSTER_HOOK_REMOVED | Info | Gluster Hook ${GlusterHookName} removed from all servers in cluster ${VdsGroupName}. |
4064 | GLUSTER_HOOK_REMOVE_FAILED | Error | Failed to remove Gluster Hook ${GlusterHookName} from cluster ${VdsGroupName}. ${FailureMessage} |
4065 | GLUSTER_HOOK_REFRESH | Info | Refreshed gluster hooks in Cluster ${VdsGroupName}. |
4066 | GLUSTER_HOOK_REFRESH_FAILED | Error | Failed to refresh gluster hooks in Cluster ${VdsGroupName}. |
4067 | GLUSTER_SERVICE_STARTED | Info | ${servicetype} service started on host ${VdsName} on cluster ${VdsGroupName}. |
4068 | GLUSTER_SERVICE_START_FAILED | Error | Could not start ${servicetype} service on host ${VdsName} on cluster ${VdsGroupName}. |
4069 | GLUSTER_SERVICE_STOPPED | Info | ${servicetype} services stopped on host ${VdsName} on cluster ${VdsGroupName}. |
4070 | GLUSTER_SERVICE_STOP_FAILED | Error | Could not stop ${servicetype} service on host ${VdsName} on cluster ${VdsGroupName}. |
4071 | GLUSTER_SERVICES_LIST_NOT_FETCHED | Info | Could not fetch list of services from ${ServiceGroupType} named ${ServiceGroupName}. |
4072 | GLUSTER_SERVICE_RESTARTED | Info | ${servicetype} service re-started on host ${VdsName} on cluster ${VdsGroupName}. |
4073 | GLUSTER_SERVICE_RESTART_FAILED | Error | Could not re-start ${servicetype} service on host ${VdsName} on cluster ${VdsGroupName}. |
4074 | GLUSTER_VOLUME_OPTIONS_RESET_ALL | Info | All Volume Options reset on ${glusterVolumeName}. |
4075 | GLUSTER_HOST_UUID_NOT_FOUND | Error | Could not find gluster uuid of server ${VdsName} on Cluster ${VdsGroupName}. |
4076 | GLUSTER_VOLUME_BRICK_ADDED | Info | Brick [${brickpath}] on host [${servername}] added to volume [${glusterVolumeName}] |
4077 | GLUSTER_CLUSTER_SERVICE_STATUS_ADDED | Info | Status of service type ${ServiceType} set to ${NewStatus} on cluster ${VdsGroupName} |
4078 | GLUSTER_VOLUME_REBALANCE_STOP | Info | Gluster Volume ${glusterVolumeName} rebalance stopped. |
4079 | GLUSTER_VOLUME_REBALANCE_STOP_FAILED | Error | Could not stop rebalance of gluster volume ${glusterVolumeName}. |
4080 | START_REMOVING_GLUSTER_VOLUME_BRICKS | Info | Started removing bricks from Volume ${glusterVolumeName} |
4081 | START_REMOVING_GLUSTER_VOLUME_BRICKS_FAILED | Error | Could not start remove bricks from Volume ${glusterVolumeName} |
4082 | GLUSTER_VOLUME_REMOVE_BRICKS_STOP | Info | Stopped removing bricks from Volume ${glusterVolumeName} |
4083 | GLUSTER_VOLUME_REMOVE_BRICKS_STOP_FAILED | Error | Failed to stop remove bricks from Volume ${glusterVolumeName} |
4084 | GLUSTER_VOLUME_REMOVE_BRICKS_COMMIT | Info | Gluster volume ${glusterVolumeName} remove bricks committed. ${NoOfBricks} brick(s) removed from volume ${glusterVolumeName}. |
4085 | GLUSTER_VOLUME_REMOVE_BRICKS_COMMIT_FAILED | Error | Gluster volume ${glusterVolumeName} remove bricks could not be commited |
4086 | GLUSTER_BRICK_STATUS_CHANGED | Warning | Detected change in status of brick ${brickpath} of volume ${glusterVolumeName} from ${oldValue} to ${newValue}. |
4087 | GLUSTER_VOLUME_REBALANCE_FINISHED | Info | ${action} ${status} on volume ${glusterVolumeName}. |
4088 | GLUSTER_VOLUME_MIGRATE_BRICK_DATA_FINISHED | Info | ${action} ${status} for brick(s) on volume ${glusterVolumeName}. Please review to abort or commit. |
4089 | GLUSTER_VOLUME_REBALANCE_START_DETECTED_FROM_CLI | Info | Detected start of rebalance on volume ${glusterVolumeName} of Cluster ${VdsGroupName} from CLI. |
4090 | START_REMOVING_GLUSTER_VOLUME_BRICKS_DETECTED_FROM_CLI | Info | Detected start of brick removal for bricks ${brick} on volume ${glusterVolumeName} of Cluster ${VdsGroupName} from CLI. |
4091 | GLUSTER_VOLUME_REBALANCE_NOT_FOUND_FROM_CLI | Warning | Could not find information for rebalance on volume ${glusterVolumeName} of Cluster ${VdsGroupName} from CLI. Marking it as unknown. |
4092 | REMOVE_GLUSTER_VOLUME_BRICKS_NOT_FOUND_FROM_CLI | Warning | Could not find information for remove brick on volume ${glusterVolumeName} of Cluster ${VdsGroupName} from CLI. Marking it as unknown. |
4093 | GLUSTER_VOLUME_DETAILS_REFRESH | Info | Refreshed details of the volume ${glusterVolumeName}. |
4094 | GLUSTER_VOLUME_DETAILS_REFRESH_FAILED | Error | Failed to refresh the details of volume ${glusterVolumeName}. |
4095 | GLUSTER_HOST_UUID_ALREADY_EXISTS | Error | Gluster UUID of host ${VdsName} on Cluster ${VdsGroupName} already exists. |
4096 | USER_FORCE_SELECTED_SPM_STOP_FAILED | Error | Failed to force select ${VdsName} as the SPM due to a failure to stop the current SPM. |
4436 | GLUSTER_SERVER_ADD_FAILED | Error | Failed to add host ${VdsName} into Cluster ${VdsGroupName}. |
4437 | GLUSTER_SERVERS_LIST_FAILED | Error | Failed to fetch gluster peer list from server ${VdsName} on Cluster ${VdsGroupName}. |
9000 | VDS_ALERT_FENCE_IS_NOT_CONFIGURED | Info | Failed to verify Power Management configuration for Host ${VdsName}. |
9001 | VDS_ALERT_FENCE_TEST_FAILED | Info | Power Management test failed for Host ${VdsName}.${Reason} |
9002 | VDS_ALERT_FENCE_OPERATION_FAILED | Info | Failed to power fence host ${VdsName}. Please check the host status and it's power management settings, and then manually reboot it and click "Confirm Host Has Been Rebooted" |
9003 | VDS_ALERT_FENCE_OPERATION_SKIPPED | Info | Host ${VdsName} became non responsive. It has no power management configured. Please check the host status, manually reboot it, and click "Confirm Host Has Been Rebooted" |
9004 | VDS_ALERT_FENCE_NO_PROXY_HOST | Info | There is no other host in the data center that can be used to test the power management settings. |
9005 | VDS_ALERT_FENCE_STATUS_VERIFICATION_FAILED | Info | Failed to verify Host ${Host} ${Status} status, Please ${Status} Host ${Host} manually. |
9006 | CANNOT_HIBERNATE_RUNNING_VMS_AFTER_CLUSTER_CPU_UPGRADE | Warning | Hibernation of VMs after CPU upgrade of Cluster ${VdsGroup} is not supported. Please stop and restart those VMs in case you wish to hibernate them |
9007 | VDS_ALERT_SECONDARY_AGENT_USED_FOR_FENCE_OPERATION | Info | Secondary fence agent was used to ${Operation} Host ${VdsName} |
9009 | VDS_ALERT_PM_HEALTH_CHECK_FAILED_FOR_SEQ_PRIMARY_AGENT | Info | Health check failed on Host ${VdsName} primary sequential agent, future fence operations may fail if secondary agent is not defined properly. |
9010 | VDS_ALERT_PM_HEALTH_CHECK_FAILED_FOR_SEQ_SECONDARY_AGENT | Info | Health check failed on Host ${VdsName} secondary sequential agent, future fence operations may fail if primary agent is not defined properly. |
9011 | VDS_ALERT_PM_HEALTH_CHECK_FAILED_FOR_CON_PRIMARY_AGENT | Info | Health check failed on Host ${VdsName} primary concurrent agent, future fence operations may fail on this Host. |
9012 | VDS_ALERT_PM_HEALTH_CHECK_FAILED_FOR_CON_SECONDARY_AGENT | Info | Health check failed on Host ${VdsName} secondary concurrent agent, future fence operations may fail on this Host. |
9013 | VDS_ALERT_FENCE_OPERATION_SKIPPED_BROKEN_CONNECTIVITY | Info | Host ${VdsName} became non responsive and was not restarted due to Fencing Policy: ${Percents} percents of the Hosts in the Cluster have connectivity issues. |
9014 | VDS_ALERT_NOT_RESTARTED_DUE_TO_POLICY | Info | Host ${VdsName} became non responsive and was not restarted due to the Cluster Fencing Policy. |
9015 | VDS_ALERT_FENCE_DISABLED_BY_CLUSTER_POLICY | Info | Host ${VdsName} became Non Responsive and was not restarted due to disabled fencing in the Cluster Fencing Policy. |
9016 | FENCING_DISABLED_IN_CLUSTER_POLICY | Info | Fencing is disabled in Fencing Policy of the Cluster ${VdsGroupName}, so HA VMs running on a non-responsive host will not be restarted elsewhere. |
9500 | TASK_STOPPING_ASYNC_TASK | Info | Stopping async task ${CommandName} that started at ${Date} |
9501 | TASK_CLEARING_ASYNC_TASK | Info | Clearing asynchronous task ${CommandName} that started at ${Date} |
9506 | USER_ACTIVATE_STORAGE_DOMAIN_FAILED_ASYNC | Warning | Failed to autorecover Storage Domain ${StorageDomainName} (Data Center ${StoragePoolName}). |
9600 | IMPORTEXPORT_IMPORT_VM_INVALID_INTERFACES | Warning | While importing VM ${EntityName}, the Network/s ${Networks} were found to be Non-VM Networks or do not exist in Cluster or are missing a suitable VM network interface profile. Network Name was not set in the Interface/s ${Interfaces}. |
9601 | VDS_SET_NON_OPERATIONAL_VM_NETWORK_IS_BRIDGELESS | Warning | Host ${VdsName} does not comply with the cluster ${VdsGroupName} networks, the following VM networks are non-VM networks: '${Networks}' |
9602 | HA_VM_FAILED | Error | Highly Available VM ${VmName} failed. It will be restarted automatically. |
9603 | HA_VM_RESTART_FAILED | Error | Restart of the Highly Available VM ${VmName} failed. |
9604 | EMULATED_MACHINES_INCOMPATIBLE_WITH_CLUSTER | Warning | Host ${VdsName} does not comply with the cluster ${VdsGroupName} emulated machines. The Hosts emulated machines are ${hostSupportedEmulatedMachines} and the cluster is ${clusterEmulatedMachines}} |
9605 | EXCEEDED_MAXIMUM_NUM_OF_RESTART_HA_VM_ATTEMPTS | Error | Highly Available VM ${VmName} could not be restarted automatically, exceeded the maximum number of attempts. |
9606 | IMPORTEXPORT_SNAPSHOT_VM_INVALID_INTERFACES | Warning | While previewing a snapshot of VM ${EntityName}, the Network/s ${Networks} were found to be Non-VM Networks or do not exist in Cluster. Network Name was not set in the Interface/s ${Interfaces}. |
9607 | ADD_VM_FROM_SNAPSHOT_INVALID_INTERFACES | Warning | While adding vm ${EntityName} from snapshot, the Network/s ${Networks} were found to be Non-VM Networks or do not exist in Cluster. Network Name was not set in the Interface/s ${Interfaces}. |
9608 | RNG_SOURCES_INCOMPATIBLE_WITH_CLUSTER | Warning | Host ${VdsName} does not comply with the cluster ${VdsGroupName} Random Number Generator sources. The Hosts supported sources are: ${hostSupportedRngSources}; and the cluster requirements are: ${clusterRequiredRngSources}. |
9610 | MIXING_RHEL_VERSIONS_IN_CLUSTER | Warning | Not possible to mix RHEL 6.x and 7.x hosts in one cluster. Tried adding ${addingRhel} host to a cluster with ${previousRhel} hosts. |
9700 | DWH_STARTED | Info | History Service started. |
9701 | DWH_STOPPED | Info | History Service stopped. |
9704 | DWH_ERROR | Error | Error in History Service. |
9801 | EXTERNAL_EVENT_NORMAL | Info | An external event with NORMAL severity has been added. |
9802 | EXTERNAL_EVENT_WARNING | Warning | An external event with WARNING severity has been added. |
9803 | EXTERNAL_EVENT_ERROR | Error | An external event with ERROR severity has been added. |
9804 | EXTERNAL_ALERT | Info | An external event with ALERT severity has been added. |
9901 | WATCHDOG_EVENT | Warning | Watchdog event (${wdaction}) triggered on ${VmName} at ${wdevent} (host time). |
9910 | USER_ADD_CLUSTER_POLICY | Info | Scheduling Policy ${ClusterPolicy} was added. (User: ${UserName}) |
9911 | USER_FAILED_TO_ADD_CLUSTER_POLICY | Error | Failed to add Scheduling Policy: ${ClusterPolicy}. (User: ${UserName}) |
9912 | USER_UPDATE_CLUSTER_POLICY | Info | Scheduling Policy ${ClusterPolicy} was updated. (User: ${UserName}) |
9913 | USER_FAILED_TO_UPDATE_CLUSTER_POLICY | Error | Failed to update Scheduling Policy: ${ClusterPolicy}. (User: ${UserName}) |
9914 | USER_REMOVE_CLUSTER_POLICY | Info | Scheduling Policy ${ClusterPolicy} was removed. (User: ${UserName}) |
9915 | USER_FAILED_TO_REMOVE_CLUSTER_POLICY | Error | Failed to remove Scheduling Policy: ${ClusterPolicy}. (User: ${UserName}) |
9920 | FAILED_TO_CONNECT_TO_SCHEDULER_PROXY | Error | Failed to connect to external scheduler proxy. External filters, scoring functions and load balancing will not be performed. |
10000 | VDS_UNTRUSTED | Error | Host ${VdsName} was set to non-operational. Host is not trusted by the attestation service. |
10001 | USER_UPDATE_VM_FROM_TRUSTED_TO_UNTRUSTED | Warning | The VM ${VmName} was updated from trusted cluster to non-trusted cluster. |
10002 | USER_UPDATE_VM_FROM_UNTRUSTED_TO_TRUSTED | Warning | The VM ${VmName} was updated from non-trusted cluster to trusted cluster. |
10003 | IMPORTEXPORT_IMPORT_VM_FROM_TRUSTED_TO_UNTRUSTED | Warning | The VM ${VmName} was created in trusted cluster and imported into a non-trusted cluster |
10004 | IMPORTEXPORT_IMPORT_VM_FROM_UNTRUSTED_TO_TRUSTED | Warning | The VM ${VmName} was created in non-trusted cluster and imported into a trusted cluster |
10005 | USER_ADD_VM_FROM_TRUSTED_TO_UNTRUSTED | Warning | The VM ${VmName} was created in an untrusted cluster. It was originated from the Template ${VmTemplateName} which was created in a trusted cluster. |
10006 | USER_ADD_VM_FROM_UNTRUSTED_TO_TRUSTED | Warning | The VM ${VmName} was created in a trusted cluster. It was originated from the Template ${VmTemplateName} which was created in an untrusted cluster. |
10007 | IMPORTEXPORT_IMPORT_TEMPLATE_FROM_TRUSTED_TO_UNTRUSTED | Warning | The Template ${VmTemplateName} was created in trusted cluster and imported into a non-trusted cluster |
10008 | IMPORTEXPORT_IMPORT_TEMPLATE_FROM_UNTRUSTED_TO_TRUSTED | Warning | The Template ${VmTemplateName} was created in non-trusted cluster and imported into a trusted cluster |
10009 | USER_ADD_VM_TEMPLATE_FROM_TRUSTED_TO_UNTRUSTED | Warning | The non-trusted Template ${VmTemplateName} was created from trusted Vm ${VmName}. |
10010 | USER_ADD_VM_TEMPLATE_FROM_UNTRUSTED_TO_TRUSTED | Warning | The trusted template ${VmTemplateName} was created from non-trusted Vm ${VmName}. |
10011 | USER_UPDATE_VM_TEMPLATE_FROM_TRUSTED_TO_UNTRUSTED | Warning | The Template ${VmTemplateName} was updated from trusted cluster to non-trusted cluster. |
10012 | USER_UPDATE_VM_TEMPLATE_FROM_UNTRUSTED_TO_TRUSTED | Warning | The Template ${VmTemplateName} was updated from non-trusted cluster to trusted cluster. |
10100 | USER_ADDED_NETWORK_QOS | Info | Network QoS ${QosName} was added. (User: ${UserName}) |
10101 | USER_FAILED_TO_ADD_NETWORK_QOS | Error | Failed to add Network QoS ${QosName}. (User: ${UserName}) |
10102 | USER_REMOVED_NETWORK_QOS | Info | Network QoS ${QosName} was removed. (User: ${UserName}) |
10103 | USER_FAILED_TO_REMOVE_NETWORK_QOS | Error | Failed to remove Network QoS ${QosName}. (User: ${UserName}) |
10104 | USER_UPDATED_NETWORK_QOS | Info | Network QoS ${QosName} was updated. (User: ${UserName}) |
10105 | USER_FAILED_TO_UPDATE_NETWORK_QOS | Error | Failed to update Network QoS ${QosName}. (User: ${UserName}) |
10110 | USER_ADDED_QOS | Info | QoS ${QoSName} was added. (User: ${UserName}) |
10111 | USER_FAILED_TO_ADD_QOS | Error | Failed to add QoS ${QoSName}. (User: ${UserName}) |
10112 | USER_REMOVED_QOS | Info | QoS ${QoSName} was removed. (User: ${UserName}) |
10113 | USER_FAILED_TO_REMOVE_QOS | Error | Failed to remove QoS ${QoSName}. (User: ${UserName}) |
10114 | USER_UPDATED_QOS | Info | QoS ${QoSName} was updated. (User: ${UserName}) |
10115 | USER_FAILED_TO_UPDATE_QOS | Error | Failed to update QoS ${QoSName}. (User: ${UserName}) |
10120 | USER_ADDED_DISK_PROFILE | Info | |
10121 | USER_FAILED_TO_ADD_DISK_PROFILE | Error | |
10122 | USER_REMOVED_DISK_PROFILE | Info | |
10123 | USER_FAILED_TO_REMOVE_DISK_PROFILE | Error | |
10124 | USER_UPDATED_DISK_PROFILE | Info | |
10125 | USER_FAILED_TO_UPDATE_DISK_PROFILE | Error | |
10130 | USER_ADDED_CPU_PROFILE | Info | |
10131 | USER_FAILED_TO_ADD_CPU_PROFILE | Error | |
10132 | USER_REMOVED_CPU_PROFILE | Info | |
10133 | USER_FAILED_TO_REMOVE_CPU_PROFILE | Error | |
10134 | USER_UPDATED_CPU_PROFILE | Info | |
10135 | USER_FAILED_TO_UPDATE_CPU_PROFILE | Error | |
10200 | USER_UPDATED_MOM_POLICIES | Info | Mom policy was updated on host ${VdsName}. |
10201 | USER_FAILED_TO_UPDATE_MOM_POLICIES | Warning | Mom policy could not be updated on host ${VdsName}. |
10250 | PM_POLICY_UP_TO_MAINTENANCE | Info | Host ${Host} is not currently needed, activating maintenance mode in preparation for shutdown. |
10251 | PM_POLICY_MAINTENANCE_TO_DOWN | Info | Host ${Host} is not currently needed, shutting down. |
10252 | PM_POLICY_TO_UP | Info | Reactivating host ${Host} according to the current power management policy. |
10300 | CLUSTER_ALERT_HA_RESERVATION | Info | Cluster ${ClusterName} failed the HA Reservation check, HA VMs on host(s): ${Hosts} will fail to migrate in case of a failover, consider adding resources or shutting down unused VMs. |
10301 | CLUSTER_ALERT_HA_RESERVATION_DOWN | Info | Cluster ${ClusterName} passed the HA Reservation check. |
10350 | USER_ADDED_AFFINITY_GROUP | Info | Affinity Group ${affinityGroupName} was added. (User: ${UserName}) |
10351 | USER_FAILED_TO_ADD_AFFINITY_GROUP | Error | Failed to add Affinity Group ${affinityGroupName}. (User: ${UserName}) |
10352 | USER_UPDATED_AFFINITY_GROUP | Info | Affinity Group ${affinityGroupName} was updated. (User: ${UserName}) |
10353 | USER_FAILED_TO_UPDATE_AFFINITY_GROUP | Error | Failed to update Affinity Group ${affinityGroupName}. (User: ${UserName}) |
10354 | USER_REMOVED_AFFINITY_GROUP | Info | Affinity Group ${affinityGroupName} was removed. (User: ${UserName}) |
10355 | USER_FAILED_TO_REMOVE_AFFINITY_GROUP | Error | Failed to remove Affinity Group ${affinityGroupName}. (User: ${UserName}) |
10400 | ISCSI_BOND_ADD_SUCCESS | Info | iSCSI bond '${IscsiBondName}' was successfully created in Data Center '${StoragePoolName}'. |
10401 | ISCSI_BOND_ADD_FAILED | Error | Failed to create iSCSI bond '${IscsiBondName}' in Data Center '${StoragePoolName}'. |
10402 | ISCSI_BOND_EDIT_SUCCESS | Info | iSCSI bond '${IscsiBondName}' was successfully updated. |
10403 | ISCSI_BOND_EDIT_FAILED | Error | Failed to update iSCSI bond '${IscsiBondName}'. |
10404 | ISCSI_BOND_REMOVE_SUCCESS | Info | iSCSI bond '${IscsiBondName}' was removed from Data Center '${StoragePoolName}' |
10405 | ISCSI_BOND_REMOVE_FAILED | Error | Failed to remove iSCSI bond '${IscsiBondName}' from Data Center '${StoragePoolName}' |
10406 | ISCSI_BOND_EDIT_SUCCESS_WITH_WARNING | Warning | iSCSI bond '${IscsiBondName}' was successfully updated but some of the hosts encountered connection issues. |
10407 | ISCSI_BOND_ADD_SUCCESS_WITH_WARNING | Warning | iSCSI bond '${IscsiBondName}' was successfully created in Data Center '${StoragePoolName}' but some of the hosts encountered connection issues. |
10450 | USER_SET_HOSTED_ENGINE_MAINTENANCE | Info | Hosted Engine HA maintenance mode was updated on host ${VdsName}. |
10451 | USER_FAILED_TO_SET_HOSTED_ENGINE_MAINTENANCE | Error | Hosted Engine HA maintenance mode could not be updated on host ${VdsName}. |
10452 | VDS_MAINTENANCE_MANUAL_HA | Warning | Host ${VdsName} was switched to Maintenance mode, but Hosted Engine HA maintenance could not be enabled. Please enable it manually. |
10453 | USER_VDS_MAINTENANCE_MANUAL_HA | Warning | Host ${VdsName} was switched to Maintenance mode by ${UserName}, but Hosted Engine HA maintenance could not be enabled. Please enable it manually. |
10454 | VDS_ACTIVATE_MANUAL_HA | Warning | Host ${VdsName} was activated by ${UserName}, but the Hosted Engine HA service may still be in maintenance mode. If necessary, please correct this manually. |
10455 | VDS_ACTIVATE_MANUAL_HA_ASYNC | Warning | Host ${VdsName} was autorecovered, but the Hosted Engine HA service may still be in maintenance mode. If necessary, please correct this manually. |
10500 | EXTERNAL_SCHEDULER_PLUGIN_ERROR | Error | Running the external scheduler plugin '${PluginName}' failed: '${ErrorMessage}' |
10501 | EXTERNAL_SCHEDULER_ERROR | Error | Running the external scheduler failed: '${ErrorMessage}' |
10550 | VM_SLA_POLICY | Info | VM ${VmName} SLA Policy was set. CPU limit is set to ${cpuLimit} |
10551 | FAILED_VM_SLA_POLICY | Error | Failed to set SLA Policy to VM ${VmName}. Underlying error message: ${ErrorMessage} |
10600 | USER_REMOVE_AUDIT_LOG | Info | Event log message ${AuditLogId} was removed by User ${UserName}. |
10601 | USER_REMOVE_AUDIT_LOG_FAILED | Error | User ${UserName} failed to remove event log message ${AuditLogId}. |
10602 | USER_CLEAR_ALL_DISMISSED_AUDIT_LOG | Info | User ${UserName} had restored all deleted event log messages. |
10603 | USER_CLEAR_ALL_DISMISSED_AUDIT_LOG_FAILED | Error | User ${UserName} failed to restore all deleted audit log messages. |
11000 | USER_ADD_EXTERNAL_JOB | Info | New external Job ${description} was added by user ${UserName} |
11001 | USER_ADD_EXTERNAL_JOB_FAILED | Error | Failed to add new external Job ${description} |
Appendix E. Timezones
E.1. Timezones
The API maps Windows Standard Format timezone names to tz database format when specifying a timezone for a virtual machine or VM template. This means the API only accepts certain tz database codes, which the following table lists:
Table E.1. Accepted tz database codes
| tz database Format | Windows Standard Format |
|---|---|
Africa/Cairo | Egypt Standard Time |
Africa/Casablanca | Morocco Standard Time |
Africa/Johannesburg | South Africa Standard Time |
Africa/Lagos | W. Central Africa Standard Time |
Africa/Nairobi | E. Africa Standard Time |
Africa/Reykjavik | Greenwich Standard Time |
Africa/Windhoek | Namibia Standard Time |
America/Anchorage | Alaskan Standard Time |
America/Bogota | SA Pacific Standard Time |
America/Buenos_Aires | Argentina Standard Time |
America/Caracas | Venezuela Standard Time |
America/Chicago | Central Standard Time |
America/Chihuahua | Mexico Standard Time |
America/Chihuahua | Mountain Standard Time |
America/Denver | Mountain Standard Time |
America/Godthab | Greenland Standard Time |
America/Guatemala | Central America Standard Time |
America/Halifax | Atlantic Standard Time |
America/La_Paz | SA Western Standard Time |
America/Los_Angeles | Pacific Standard Time |
America/Manaus | Central Brazilian Standard Time |
America/Mexico_City | Central Standard Time |
America/Mexico_City | Mexico Standard Time |
America/Montevideo | Montevideo Standard Time |
America/New_York | Eastern Standard Time |
America/Phoenix | US Mountain Standard Time |
America/Regina | Canada Central Standard Time |
America/Santiago | Pacific SA Standard Time |
America/Sao_Paulo | E. South America Standard Time |
America/St_Johns | Newfoundland Standard Time |
America/Tijuana | Pacific Standard Time |
Asia/Amman | Jordan Standard Time |
Asia/Baghdad | Arabic Standard Time |
Asia/Baku | Azerbaijan Standard Time |
Asia/Bangkok | SE Asia Standard Time |
Asia/Beirut | Middle East Standard Time |
Asia/Calcutta | India Standard Time |
Asia/Colombo | Sri Lanka Standard Time |
Asia/Dhaka | Central Asia Standard Time |
Asia/Dubai | Arabian Standard Time |
Asia/Irkutsk | North Asia East Standard Time |
Asia/Jerusalem | Israel Standard Time |
Asia/Kabul | Afghanistan Standard Time |
Asia/Karachi | Pakistan Standard Time |
Asia/Katmandu | Nepal Standard Time |
Asia/Krasnoyarsk | North Asia Standard Time |
Asia/Novosibirsk | N. Central Asia Standard Time |
Asia/Rangoon | Myanmar Standard Time |
Asia/Riyadh | Arab Standard Time |
Asia/Seoul | Korea Standard Time |
Asia/Shanghai | China Standard Time |
Asia/Singapore | Singapore Standard Time |
Asia/Taipei | Taipei Standard Time |
Asia/Tashkent | West Asia Standard Time |
Asia/Tehran | Iran Standard Time |
Asia/Tokyo | Tokyo Standard Time |
Asia/Vladivostok | Vladivostok Standard Time |
Asia/Yakutsk | Yakutsk Standard Time |
Asia/Yekaterinburg | Ekaterinburg Standard Time |
Asia/Yerevan | Armenian Standard Time |
Asia/Yerevan | Caucasus Standard Time |
Atlantic/Azores | Azores Standard Time |
Atlantic/Cape_Verde | Cape Verde Standard Time |
Atlantic/South_Georgia | Mid-Atlantic Standard Time |
Australia/Adelaide | Cen. Australia Standard Time |
Australia/Brisbane | E. Australia Standard Time |
Australia/Darwin | AUS Central Standard Time |
Australia/Hobart | Tasmania Standard Time |
Australia/Perth | W. Australia Standard Time |
Australia/Sydney | AUS Eastern Standard Time |
Etc/GMT-3 | Georgian Standard Time |
Etc/GMT+12 | Dateline Standard Time |
Etc/GMT+3 | SA Eastern Standard Time |
Etc/GMT+5 | US Eastern Standard Time |
Europe/Berlin | W. Europe Standard Time |
Europe/Budapest | Central Europe Standard Time |
Europe/Istanbul | GTB Standard Time |
Europe/Kiev | FLE Standard Time |
Europe/London | GMT Standard Time |
Europe/Minsk | E. Europe Standard Time |
Europe/Moscow | Russian Standard Time |
Europe/Paris | Romance Standard Time |
Europe/Warsaw | Central European Standard Time |
Indian/Mauritius | Mauritius Standard Time |
Pacific/Apia | Samoa Standard Time |
Pacific/Auckland | New Zealand Standard Time |
Pacific/Fiji | Fiji Standard Time |
Pacific/Guadalcanal | Central Pacific Standard Time |
Pacific/Honolulu | Hawaiian Standard Time |
Pacific/Port_Moresby | West Pacific Standard Time |
Pacific/Tongatapu | Tonga Standard Time |
Appendix F. Revision History
| Revision History | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Revision 3.5-40 | Wed 25 May 2016 | ||||||||||
| |||||||||||
| Revision 3.5-39 | Wed 04 May 2016 | ||||||||||
| |||||||||||
| Revision 3.5-38 | Mon 8 Feb 2016 | ||||||||||
| |||||||||||
| Revision 3.5-37 | Thu 14 Jan 2016 | ||||||||||
| |||||||||||
| Revision 3.5-36 | Fri 20 Nov 2015 | ||||||||||
| |||||||||||
| Revision 3.5-35 | Mon 26 Oct 2015 | ||||||||||
| |||||||||||
| Revision 3.5-34 | Tue 04 Aug 2015 | ||||||||||
| |||||||||||
| Revision 3.5-33 | Wed 03 Jun 2015 | ||||||||||
| |||||||||||
| Revision 3.5-32 | Tue 12 May 2015 | ||||||||||
| |||||||||||
| Revision 3.5-31 | Tue 28 Apr 2015 | ||||||||||
| |||||||||||
| Revision 3.5-30 | Wed 11 Mar 2015 | ||||||||||
| |||||||||||
| Revision 3.5-29 | Wed 11 Feb 2015 | ||||||||||
| |||||||||||
| Revision 3.5-28 | Tue 10 Feb 2015 | ||||||||||
| |||||||||||
| Revision 3.5-27 | Tue 18 Nov 2014 | ||||||||||
| |||||||||||
| Revision 3.5-26 | Fri 14 Nov 2014 | ||||||||||
| |||||||||||
| Revision 3.5-25 | Thu 6 Nov 2014 | ||||||||||
| |||||||||||
| Revision 3.5-24 | Wed 5 Nov 2014 | ||||||||||
| |||||||||||
| Revision 3.5-23 | Thu 23 Oct 2014 | ||||||||||
| |||||||||||
| Revision 3.5-22 | Wed 22 Oct 2014 | ||||||||||
| |||||||||||
| Revision 3.5-21 | Wed 22 Oct 2014 | ||||||||||
| |||||||||||
| Revision 3.5-20 | Tue 14 Oct 2014 | ||||||||||
| |||||||||||
| Revision 3.5-19 | Tue 14 Oct 2014 | ||||||||||
| |||||||||||
| Revision 3.5-18 | Wed 8 Oct 2014 | ||||||||||
| |||||||||||
| Revision 3.5-17 | Fri 3 Oct 2014 | ||||||||||
| |||||||||||
| Revision 3.5-16 | Fri 26 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-15 | Fri 19 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-14 | Thu 18 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-13 | Sat 13 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-12 | Wed 10 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-11 | Mon 8 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-10 | Fri 5 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-9 | Tues 2 Sep 2014 | ||||||||||
| |||||||||||
| Revision 3.5-8 | Fri 22 Aug 2014 | ||||||||||
| |||||||||||
| Revision 3.5-7 | Fri 22 Aug 2014 | ||||||||||
| |||||||||||
| Revision 3.5-6 | Wed 20 Aug 2014 | ||||||||||
| |||||||||||
| Revision 3.5-5 | Thu 14 Aug 2014 | ||||||||||
| |||||||||||
| Revision 3.5-4 | Fri 01 Aug 2014 | ||||||||||
| |||||||||||
| Revision 3.5-3 | Tue 01 Jul 2014 | ||||||||||
| |||||||||||
| Revision 3.5-2 | Mon 30 Jun 2014 | ||||||||||
| |||||||||||
| Revision 3.5-1 | Thu 5 Jun 2014 | ||||||||||
| |||||||||||