Red Hat Enterprise Virtualization 3.5 Technical Guide

Red Hat Enterprise Virtualizat ion Documentat ion Team

Red Hat Enterprise Virtualization 3.5Technical Guide

Technical Concepts and Developer Tools for Red Hat EnterpriseVirtualizat ion

Red Hat Enterprise Virtualizat ion 3.5 Technical Guide

Technical Concepts and Developer Tools for Red Hat EnterpriseVirtualizat ion

Red Hat Enterprise Virtualization Documentation TeamRed Hat Customer Content [email protected]

Legal Notice

Copyright © 2015 Red Hat.

This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0Unported License. If you distribute this document, o r a modified version o f it, you must provideattribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all RedHat trademarks must be removed.

Red Hat, as the licensor o f this document, waives the right to enforce, and agrees not to assert,Section 4d o f CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the InfinityLogo, and RHCE are trademarks o f Red Hat, Inc., registered in the United States and o thercountries.

Linux ® is the registered trademark o f Linus Torvalds in the United States and o ther countries.

Java ® is a registered trademark o f Oracle and/or its affiliates.

XFS ® is a trademark o f Silicon Graphics International Corp. or its subsidiaries in the UnitedStates and/or o ther countries.

MySQL ® is a registered trademark o f MySQL AB in the United States, the European Union andother countries.

Node.js ® is an o fficial trademark o f Joyent. Red Hat Software Collections is not fo rmallyrelated to or endorsed by the o fficial Joyent Node.js open source or commercial pro ject.

The OpenStack ® Word Mark and OpenStack Logo are either registered trademarks/servicemarks or trademarks/service marks o f the OpenStack Foundation, in the United States and o thercountries 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 o ther trademarks are the property o f their respective owners.

AbstractA comprehensive guide to the underlying technical concepts behind and developer too lsavailable in Red Hat Enterprise Virtualization.

http://creativecommons.org/licenses/by-sa/3.0/

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Table of Contents

Part I. T echnical Reference

Chapt er 1 . Int roduct ion1.1. Red Hat Enterp rise Virtualizatio n Manag er1.2. Red Hat Virtualizatio n Hyp erviso r1.3. Features Req uiring a Co mp atib il i ty Up g rad e to Red Hat Enterp rise Virtualizatio n 3.51.4. Interfaces fo r Accessing the Manag er1.5. Co mp o nents that Sup p o rt the Manag er1.6 . Sto rag e1.7. Netwo rk1.8 . Data Centers

Chapt er 2 . St orage2.1. Sto rag e Do mains Overview2.2. Typ es o f Sto rag e Backing Sto rag e Do mains2.3. Sto rag e Do main Typ es2.4. Sto rag e Fo rmats fo r Virtual Machine Disk Imag es2.5. Virtual Machine Disk Imag e Sto rag e Allo catio n Po lic ies2.6 . Setting s to Wip e Virtual Disks After Deletio n2.7. Sto rag e Do main Auto reco very in Red Hat Enterp rise Virtualizatio n2.8 . The Sto rag e Po o l Manag er2.9 . Sto rag e Po o l Manag er Selectio n Pro cess2.10 . Exclusive Reso urces and Sanlo ck in Red Hat Enterp rise Virtualizatio n2.11. Thin Pro vis io ning and Sto rag e Over-Co mmitment2.12. Lo g ical Vo lume Extensio n

Chapt er 3. Net work3.1. Netwo rk Architecture3.2. Intro d uctio n: Basic Netwo rking Terms3.3. Netwo rk Interface Co ntro ller3.4. Brid g e3.5. Bo nd s3.6 . Switch Co nfig uratio n fo r Bo nd ing3.7. Virtual Netwo rk Interface Card s3.8 . Virtual LAN (VLAN)3.9 . Cluster Netwo rking3.10 . Lo g ical Netwo rks3.11. Req uired Netwo rks, Op tio nal Netwo rks, and Virtual Machine Netwo rks3.12. Virtual Machine Co nnectivity3.13. Po rt Mirro ring3.14. Ho st Netwo rking Co nfig uratio ns3.15. Brid g e Co nfig uratio n3.16 . VLAN Co nfig uratio n3.17. Brid g e and Bo nd Co nfig uratio n3.18 . Multip le Brid g e, Multip le VLAN, and NIC Co nfig uratio n3.19 . Multip le Brid g e, Multip le VLAN, and Bo nd Co nfig uratio n

Chapt er 4 . Power Management4.1. Intro d uctio n to Po wer Manag ement and Fencing4.2. Po wer Manag ement b y Pro xy in Red Hat Enterp rise Virtualizatio n4.3. Po wer Manag ement4.4. Fencing4.5. So ft-Fencing Ho sts

9

1 01010121314151719

2 0202021212222232324252627

2 828282828293030323233353636373738383940

4 14141414243

T able of Cont ent s

1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.5. So ft-Fencing Ho sts4.6 . Using Multip le Po wer Manag ement Fencing Ag ents

Chapt er 5. Load Balancing, Scheduling, and Migrat ion5.1. Lo ad Balancing , Sched uling , and Mig ratio n5.2. Lo ad Balancing Po licy5.3. Lo ad Balancing Po licy: VM_Evenly_Distrib uted5.4. Lo ad Balancing Po licy: Evenly_Distrib uted5.5. Lo ad Balancing Po licy: Po wer_Saving5.6 . Lo ad Balancing Po licy: No ne5.7. Hig hly Availab le Virtual Machine Reservatio n5.8 . Sched uling5.9 . Mig ratio n

Chapt er 6 . Direct ory Services6 .1. Directo ry Services6 .2. Lo cal Authenticatio n: Internal Do main6 .3. Remo te Authenticatio n Using GSSAPI

Chapt er 7 . T emplat es and Pools7.1. Temp lates and Po o ls7.2. Temp lates7.3. Po o ls

Chapt er 8 . Virt ual Machine Snapshot s8 .1. Snap sho ts8 .2. Live Snap sho ts in Red Hat Enterp rise Virtualizatio n8 .3. Snap sho t Creatio n8 .4. Snap sho t Previews8 .5. Snap sho t Deletio n

Chapt er 9 . Hardware Drivers and Devices9 .1. Virtualized Hard ware9 .2. Stab le Device Ad d resses in Red Hat Enterp rise Virtualizatio n9 .3. Central Pro cessing Unit (CPU)9 .4. System Devices9 .5. Netwo rk Devices9 .6 . Grap hics Devices9 .7. Sto rag e Devices9 .8 . So und Devices9 .9 . Serial Driver9 .10 . Ballo o n Driver

Chapt er 1 0 . Minimum Requirement s and T echnical Limit at ions10 .1. Minimum Req uirements and Sup p o rted Limits10 .2. Data Center Limitatio ns10 .3. Cluster Limitatio ns10 .4. Sto rag e Do main Limitatio ns10 .5. Red Hat Enterp rise Virtualizatio n Manag er Limitatio ns10 .6 . Hyp erviso r Req uirements10 .7. Guest Req uirements and Sup p o rt Limits10 .8 . SPICE Limitatio ns10 .9 . Ad d itio nal References

Part II. T he Command Line Int erface1. Intro d uctio n to the Co mmand Line Interface

4344

4 5454545464646464747

4 8484848

50505051

525252535555

5757575858585959595959

6 06 06 06 06 06 26 26 56 76 7

6 86 8

T echnical Guide

2

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1. Intro d uctio n to the Co mmand Line Interface

Chapt er 1 1 . Using t he CLI11.1. Install ing the CLI11.2. TLS/SSL Certificatio n11.3. .rhevmshellrc Co nfig uratio n11.4. Running the CLI11.5. Interacting with the CLI11.6 . Co llectio ns

Chapt er 1 2 . Quick St art Example12.1. Creating a Basic Virtualizatio n Enviro nment with the CLI

Chapt er 1 3. Commands13.1. Co nnecting to RHEVM13.2. Reso urces13.3. O ther Co mmand s

Chapt er 1 4 . Resource T ypes14.1. b rick14.2. cd ro m14.3. c luster14.4. d atacenter14.5. d isk14.6 . g lustervo lume14.7. g ro up14.8 . ho st14.9 . netwo rk14.10 . nic14.11. p ermissio n14.12. p ermit14.13. q uo tas14.14. ro le14.15. snap sho t14.16 . s tatis tic14.17. s to rag eco nnectio n14.18 . s to rag ed o main14.19 . tag14.20 . temp late14.21. user14.22. vm14.23. vmp o o l14.24. vnicp ro fi le

Chapt er 1 5. CLI Queries15.1. Query Syntax15.2. Wild card s

Part III. T he REST Applicat ion Programming Int erface

Chapt er 1 6 . Int roduct ion16 .1. Rep resentatio nal State Transfer16 .2. Red Hat Enterp rise Virtualizatio n REST API Prereq uis ites

Chapt er 1 7 . Aut hent icat ion and Securit y17.1. TLS/SSL Certificatio n17.2. HTTP Authenticatio n

6 8

6 96 96 970717376

7 777

8 28 28 38 8

9 49 49 49 59 79 8

10 010 110 210 410 510 810 910 9110110111112113116116121122128129

1 31131131

1 32

1 33133133

1 35135136


3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17.2. HTTP Authenticatio n17.3. Authenticatio n Sessio ns

Chapt er 1 8 . REST API Quick St art Example18 .1. Examp le: Access API Entry Po int18 .2. Examp le: Lis t Data Center Co llectio n18 .3. Examp le: Lis t Ho st Cluster Co llectio n18 .4. Examp le: Lis t Lo g ical Netwo rks Co llectio n18 .5. Examp le: Lis t Ho st Co llectio n18 .6 . Examp le: Lis t CPU Pro fi les18 .7. Examp le: Ap p ro ve Ho st18 .8 . Examp le: Create NFS Data Sto rag e18 .9 . Examp le: Create NFS ISO Sto rag e18 .10 . Examp le: Attach Sto rag e Do mains to Data Center18 .11. Examp le: Activate Sto rag e Do mains18 .12. Examp le: Create Virtual Machine18 .13. Examp le: Create Virtual Machine NIC18 .14. Examp le: Create Virtual Machine Sto rag e Disk18 .15. Examp le: Attach ISO Imag e to Virtual Machine18 .16 . Examp le: Start Virtual Machine18 .17. Examp le: Check System Events

Chapt er 1 9 . Ent ry Point19 .1. Pro d uct Info rmatio n19 .2. Link Elements19 .3. Sp ecial Ob ject Elements19 .4. Summary Element19 .5. RESTful Service Descrip tio n Lang uag e (RSDL)19 .6 . Red Hat Enterp rise Virtualizatio n Wind o ws Guest VSS Sup p o rt19 .7. QEMU Guest Ag ent Overview19 .8 . VSS Transactio n Flo w

Chapt er 2 0 . Compat ibilit y Level Versions20 .1. Up g rad ing Co mp atib il i ty Levels

Chapt er 2 1 . Capabilit ies21.1. Vers io n-Dep end ent Cap ab il ities21.2. Current Vers io n21.3. Features

Chapt er 2 2 . Common Feat ures22.1. Element Pro p erty Ico ns22.2. Rep resentatio ns22.3. Co llectio ns22.4. Reso urces

Chapt er 2 3. T he Backup and Rest ore API23.1. Backing Up a Virtual Machine23.2. Resto ring a Virtual Machine

Chapt er 2 4 . Dat a Cent ers24.1. Data Center Elements24.2. XML Rep resentatio n o f a Data Center24.3. JSON Rep resentatio n o f a Data Center24.4. Metho d s24.5. Sub -Co llectio ns

136137

1 3913914114214314414614814815015115215315715715815916 0

1 6 216 316 316 516 516 516 716 716 8

1 6 916 9

1 7 1171171172

1 7 517517517618 2

1 8 818 818 9

1 9 119 119 219 219 319 4

T echnical Guide

4

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

24.5. Sub -Co llectio ns24.6 . Actio ns

Chapt er 2 5. Clust ers25.1. Cluster Elements25.2. Memo ry Po licy Elements25.3. Sched uling Po licy Elements25.4. XML Rep resentatio n o f a Cluster25.5. JSON Rep resentatio n o f a Cluster25.6 . Metho d s25.7. Sub -Co llectio ns

Chapt er 2 6 . Net works26 .1. Netwo rk Elements26 .2. XML Rep resentatio n o f a Netwo rk Reso urce26 .3. JSON Rep resentatio n o f a Netwo rk Reso urce26 .4. Metho d s26 .5. Sub -co llectio ns

Chapt er 2 7 . St orage Domains27.1. Sto rag e Do main Elements27.2. XML Rep resentatio n o f a Sto rag e Do main27.3. JSON Rep resentatio n o f a Sto rag e Do main27.4. Metho d s27.5. Sto rag e Typ es27.6 . Exp o rt Sto rag e Do mains27.7. G lance Imag e Sto rag e Do mains27.8 . Sub -Co llectio ns27.9 . Actio ns

Chapt er 2 8 . St orage Connect ions28 .1. Sto rag e Co nnectio n Elements28 .2. XML rep resentatio n o f a Sto rag e Co nnectio n Reso urce28 .3. Metho d s

Chapt er 2 9 . Host s29 .1. Ho st Elements29 .2. XML Rep resentatio n o f a Ho st29 .3. JSON Rep resentatio n o f a Ho st29 .4. Po wer Manag ement Elements29 .5. Memo ry Manag ement Elements29 .6 . Metho d s29 .7. Sub -Co llectio ns29 .8 . Actio ns

Chapt er 30 . Virt ual Machines30 .1. Virtual Machine Elements30 .2. XML Rep resentatio n o f a Virtual Machine30 .3. XML Rep resentatio n o f Ad d itio nal OVF Data fo r a Virtual Machine30 .4. JSON Rep resentatio n o f a Virtual Machine30 .5. Metho d s30 .6 . Sub -Co llectio ns30 .7. Actio ns

Chapt er 31 . Float ing Disks31.1. Flo ating Disk Elements

19 419 9

2 0 120 120 220 320 320 420 620 7

2 1 6216216217218219

2 2 1221222223224225227229231232

2 35235236236

2 4 024024224424724925025126 4

2 6 926 927427627828 228 430 9

31 7317


5

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31.2. XML Rep resentatio n o f a Flo ating Disk31.3. Metho d s31.4. Sub -Co llectio ns

Chapt er 32 . T emplat es32.1. Virtual Machine Temp late Elements32.2. XML Rep resentatio n o f a Virtual Machine Temp late32.3. Metho d s32.4. Actio ns

Chapt er 33. Virt ual Machine Pools33.1. Virtual Machine Po o l Elements33.2. XML Rep resentatio n o f a Virtual Machine Po o l33.3. Metho d s33.4. Actio ns

Chapt er 34 . Domains34.1. Do main Elements34.2. XML Rep resentatio n o f a Do main Reso urce34.3. Sub -Co llectio ns

Chapt er 35. Groups35.1. Imp o rted Gro up Elements35.2. XML Rep resentatio n o f a Gro up Reso urce35.3. Ad d ing a Gro up fro m a Directo ry Service

Chapt er 36 . Roles36 .1. Ro le Elements36 .2. XML Rep resentatio n o f the Ro les Co llectio n36 .3. Metho d s36 .4. Ro les Permits Sub -Co llectio n

Chapt er 37 . Users37.1. User Elements37.2. XML rep resentatio n o f a User Reso urce37.3. Metho d s

Chapt er 38 . T ags38 .1. Tag Elements38 .2. XML Rep resentatio n o f a Tag Reso urce38 .3. Asso ciating Tag s38 .4. Parent Tag s

Chapt er 39 . Event s39 .1. Event Elements39 .2. XML Rep resentatio n o f the Events Co llectio n39 .3. XML Rep resentatio n o f a Virtual Machine Creatio n Event39 .4. Searching Events39 .5. Pag inating Events

Part IV. T he Pyt hon Sofware Development Kit

Chapt er 4 0 . Soft ware Development Kit Overview40 .1. Overview40 .2. Prereq uis ites40 .3. Install ing the Pytho n So ftware Develo p ment Kit

318319319

32 1321323324326

32 7327327328329

330330330330

333333333333

335335335336337

339339339340

34 2342342342344

34 7347347347348349

351

352352352352

T echnical Guide

6

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapt er 4 1 . Pyt hon Quick St art Example41.1. Pytho n Quick Start Intro d uctio n41.2. Examp le: Accessing the API Entry Po int us ing Pytho n41.3. Examp le: Lis ting the Data Center Co llectio n using Pytho n41.4. Examp le: Lis ting the Cluster Co llectio n using Pytho n41.5. Examp le: Lis ting the Lo g ical Netwo rks Co llectio n using Pytho n41.6 . Examp le: Lis ting the Ho st Co llectio n using Pytho n41.7. Examp le: Lis ting the ISO Files in an ISO Sto rag e Do main41.8 . Examp le: Lis ting the Size o f a Virtual Machine41.9 . Examp le: Ap p ro ving a Ho st us ing Pytho n41.10 . Examp le: Creating NFS Data Sto rag e using Pytho n41.11. Examp le: Creating NFS ISO Sto rag e using Pytho n41.12. Examp le: Attaching Sto rag e Do mains to a Data Center us ing Pytho n41.13. Examp le: Activating Sto rag e Do mains using Pytho n41.14. Examp le: Creating a Virtual Machine using Pytho n41.15. Examp le: Creating a Virtual Machine NIC using Pytho n41.16 . Examp le: Creating a Virtual Machine Sto rag e Disk using Pytho n41.17. Examp le: Attaching an ISO Imag e to a Virtual Machine using Pytho n41.18 . Examp le: Detaching a Disk using Pytho n41.19 . Examp le: Starting a Virtual Machine using Pytho n41.20 . Examp le: Starting a Virtual Machine with Overrid d en Parameters using Pytho n41.21. Examp le: Starting a Virtual Machine with Clo ud -Init us ing Pytho n41.22. Examp le: Checking System Events using Pytho n

Chapt er 4 2 . Using t he Soft ware Development Kit42.1. Co nnecting to the API using Pytho n42.2. Reso urces and Co llectio ns42.3. Retrieving Reso urces fro m a Co llectio n42.4. Retrieving a Sp ecific Reso urce fro m a Co llectio n42.5. Retrieving a List o f Reso urces fro m a Co llectio n42.6 . Ad d ing a Reso urce to a Co llectio n42.7. Up d ating a Reso urce in a Co llectio n42.8 . Remo ving a Reso urce fro m a Co llectio n42.9 . Hand ling Erro rs

Chapt er 4 3. Pyt hon Reference Document at ion43.1. Pytho n Reference Do cumentatio n

Part V. T he Java Soft ware Development Kit

Chapt er 4 4 . Soft ware Development Kit Overview44.1. Overview44.2. Install ing the Java So ftware Develo p ment Kit

Chapt er 4 5. Using t he Soft ware Development Kit45.1. Co nnecting to the Red Hat Enterp rise Virtualizatio n Manag er45.2. Lis ting Entities45.3. Mo d ifying the Attrib utes o f Reso urces45.4. Getting a Reso urce45.5. Ad d ing Reso urces45.6 . Perfo rming Actio ns o n Reso urces45.7. Lis ting Sub -Reso urces45.8 . Getting Sub -Reso urces45.9 . Ad d ing Sub -Reso urces to a Reso urce45.10 . Mo d ifying Sub -Reso urces

35435435435535635735735835935936 036 236 336 536 636 736 8370372372373374375

37 737737837937938 038 138 238 238 2

38 438 4

38 5

38 638 638 6

38 738 739 039 139 139 139 239 339 339 339 4


7

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

45.10 . Mo d ifying Sub -Reso urces45.11. Perfo rming Actio ns o n Sub -Reso urces45.12. Reco mmend ed Practices45.13. Co nfig uring SSL

Appendix A. API Usage wit h cURLA.1. API Usag e with cURLA.2. Install ing cURLA.3. Using cURLA.4. Examp les

Appendix B. UI PluginsB.1. Install ing the Red Hat Sup p o rt Plug -in

Appendix C. Enumerat ed Value T ranslat ionC.1. Enumerated Value Translatio n

Appendix D. Event CodesD.1. Event Co d es

Appendix E. T imezonesE.1. Timezo nes

Appendix F. Revision Hist ory

39 439 439 539 5

39 739 739 739 739 8

4 0 140 1

4 0 240 2

4 0 340 3

4 6 746 7

4 7 0

T echnical Guide

8

Part I. Technical Reference

Part I. T echnical Reference

9

Chapter 1. Introduction

1.1. Red Hat Enterprise Virtualizat ion Manager

The Red Hat Enterprise Virtualization Manager provides centralized management for a virtualizedenvironment. A number of different interfaces can be used to access the Red Hat EnterpriseVirtualization Manager. Each interface facilitates access to the virtualized environment in a differentmanner.

Figure 1.1. Red Hat Enterprise Virtualiz at ion Manager Architecture

The Red Hat Enterprise Virtualization Manager provides graphical interfaces and an ApplicationProgramming Interface (API). Each interface connects to the Manager, an application delivered by anembedded instance of the Red Hat JBoss Enterprise Application Platform. There are a number of othercomponents which support the Red Hat Enterprise Virtualization Manager in addition to Red HatJBoss Enterprise Application Platform.

1.2. Red Hat Virtualizat ion Hypervisor

A Red Hat Enterprise Virtualization environment has one or more hosts attached to it. A host is aserver that provides the physical hardware that virtual machines make use of.

Red Hat Enterprise Virtualization Hypervisor hosts run an optimized operating system installed usinga special, customized installation media specifically for creating virtualization hosts.

Red Hat Enterprise Linux hosts are servers running a standard Red Hat Enterprise Linux operatingsystem 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 virtualizedenvironment in the same way, and so, will both referred to as hosts.

T echnical Guide

10

Figure 1.2. Host Architecture

Kernel-based Virtual Machine (KVM)

The Kernel-based Virtual Machine (KVM) is a loadable kernel module that provides fullvirtualization through the use of the Intel VT or AMD-V hardware extensions. Though KVMitself runs in kernel space, the guests running upon it run as individual QEMU processes inuser 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 afull system, for example a PC, including one or more processors, and peripherals. QEMUcan be used to launch different operating systems or to debug system code. QEMU, workingin conjunction with KVM and a processor with appropriate virtualization extensions,provides full hardware assisted virtualization.

Red Hat Enterprise Virtualiz at ion Manager Host Agent , VDSM

In Red Hat Enterprise Virtualization, VDSM initiates actions on virtual machines andstorage. It also facilitates inter-host communication. VDSM monitors host resources suchas memory, storage, and networking. Additionally, VDSM manages tasks such as virtualmachine creation, statistics accumulation, and log collection. A VDSM instance runs oneach host and receives management commands from the Red Hat Enterprise VirtualizationManager using the re-configurable port 54321.

VDSM-REG

VDSM uses VDSM-REG to register each host with the Red Hat Enterprise VirtualizationManager. VDSM-REG supplies information about itself and its host using port 80 or port 443.

libvirt

Libvirt facilitates the management of virtual machines and their associated virtual devices.When Red Hat Enterprise Virtualization Manager initiates virtual machine life-cyclecommands (start, stop, reboot), VDSM invokes libvirt on the relevant host machines toexecute them.

Storage Pool Manager, SPM

Chapt er 1 . Int roduct ion

11

The Storage Pool Manager (SPM) is a role assigned to one host in a data center. The SPMhost has sole authority to make all storage domain structure metadata changes for the datacenter. This includes creation, deletion, and manipulation of virtual disk images,snapshots, and templates. It also includes allocation of storage for sparse block deviceson a Storage Area Network(SAN). The role of SPM can be migrated to any host in a datacenter. As a result, all hosts in a data center must have access to all the storage domainsdefined in the data center.

Red Hat Enterprise Virtualization Manager ensures that the SPM is always available. Incase of storage connectivity errors, the Manager re-assigns the SPM role to another host.

Guest Operat ing System

Guest operating systems can be installed without modification on virtual machines in a RedHat Enterprise Virtualization environment. The guest operating system, and anyapplications 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 tovirtualized devices. You can also install the Red Hat Enterprise Virtualization Guest Agenton guests, which provides enhanced guest information to the management console.

1.3. Features Requiring a Compat ibilit y Upgrade to Red Hat EnterpriseVirtualizat ion 3.5

Some of the features provided by Red Hat Enterprise Virtualization 3.5 are only available if your datacenters, clusters, and storage have a compatibility version of 3.5.

Table 1.1. Features Requiring a Compat ib ility Upgrade to Red Hat EnterpriseVirtualiz at ion 3.5

Feature Descript ionPara-virtualized random number generator(RNG) device support

This feature adds support for enabling a para-virtualized random number generator in virtualmachines. To use this feature, the randomnumber generator source must be set at clusterlevel to ensure all hosts support and reportdesired RNG device sources. This feature issupported in Red Hat Enterprise Linux hosts ofversion 6.6 and higher.

Serial number policy support This feature adds support for setting a customserial number for virtual machines. Serialnumber 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 OpenVirtualization Format files, including virtualmachine templates, to be stored on any domainin a supported pool.

Boot menu support This feature adds support for enabling a bootdevice menu in a virtual machine.

Import data storage domains This feature adds support for users to addexisting data storage domains to theirenvironment. The Manager then detects andadds all the virtual machines in that storagedomain.

T echnical Guide

12

SPICE copy and paste support This feature adds support for users to enable ordisable SPICE clipboard copy and paste.

Storage pool metadata removal This feature adds support for storage poolmetadata to be stored and maintained in theengine database only.

Network custom properties support This feature adds support for users to definecustom properties when a network isprovisioned on a host.

Feature Descript ion

1.4 . Interfaces for Accessing the Manager

User Portal

Desktop virtualization provides users with a desktop environment that is similar a personalcomputer's desktop environment. The User Portal is for delivering Virtual DesktopInfrastructure to users. Users access the User Portal through a web browser to display andaccess their assigned virtual desktops. The actions available to a user in the User Portalare set by a system administrator. Standard users can start, stop, and use desktops thatare assigned to them by the system administrator. Power users can perform someadministrative actions. Both types of user access the User Portal from the same URL, andare presented with options appropriate to their permission level on login.

Standard User Access

Standard users are able to power their virtual desktops on and off and connect to themthrough the User Portal. Direct connection to virtual machines is facilitated with SimpleProtocol for Independent Computing Environments (SPICE) or Virtual Network Computing(VNC) clients. Both protocols provide the user with an environment similar to a locallyinstalled desktop environment. The administrator specifies the protocol used to connectto 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 supportedbrowsers and clients can be found in the User Guide.

Power User Access

The Red Hat Enterprise Virtualization User Portal provides power users with a graphicaluser interface to create, use, and monitor virtual resources. System administrators candelegate some administration tasks by granting users power user access. In addition tothe 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.


13

Power users can perform virtual machine administration tasks to be delegated. Datacenter and cluster level administration tasks are saved for the environmentadministrator.

Administ rat ion Portal

The Administration Portal is the graphical administration interface of the Red Hat EnterpriseVirtualization Manager server. Using it administrators can monitor, create, and maintain allelements of the virtualized environment using from web browsers. Tasks which can beperformed 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 EnterpriseVirtualization Administration Guide. Information on the browsers and platforms that aresupported by the Administration Portal can be found in the Red Hat Enterprise VirtualizationInstallation Guide.

Representat ional State Transfer (REST) API

The Red Hat Enterprise Virtualization REST API provides a software interface for theinterrogation and control of the Red Hat Enterprise Virtualization environment. The RESTAPI 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 Virtualizationenvironment.

See the Red Hat Enterprise Virtualization REST API Guide for the API specification andusage examples.

1.5. Components that Support the Manager

Red Hat JBoss Enterprise Applicat ion Plat form

Red Hat JBoss Enterprise Application Platform is a Java application server. It provides aframework to support efficient development and delivery of cross-platform Javaapplications. The Red Hat Enterprise Virtualization Manager is delivered using Red HatJBoss Enterprise Application Platform.

T echnical Guide

14

Important

The version of the Red Hat JBoss Enterprise Application Platform bundled with RedHat Enterprise Virtualization Manager is not to be used to serve other applications. Ithas been customized for the specific purpose of serving the Red Hat EnterpriseVirtualization Manager. Using the Red Hat JBoss Enterprise Application Platform thatis included with the Manager for additional purposes adversely affects its ability toservice the Red Hat Enterprise Virtualization environment.

Gathering Reports and Historical Data

The Red Hat Enterprise Virtualization Manager includes a data warehouse that collectsmonitoring data about hosts, virtual machines, and storage. A number of pre-definedreports are available. Customers can analyze their environments and create reports usingany 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 EnterpriseVirtualization 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 statisticalmetrics which are collated over time from the engine operational database. Theconfiguration data in the engine database is examined every minute, and changes arereplicated to the ovirt_engine_history database. Tracking the changes to the databaseprovides information on the objects in the database. This enables you to analyze andenhance the performance of your Red Hat Enterprise Virtualization environment andresolve difficulties.

For more information on generating reports based on the ovirt_engine_history databasesee the Red Hat Enterprise Virtualization Administration Guide.

Important

The replication of data in the ovirt_engine_history database is performed by theRHEVM History Service , ovirt-engine-dwhd.

Directory services

Directory services provide centralized network-based storage of user and organizationalinformation. Types of information stored include application settings, user profiles, groupdata, policies, and access control. The Red Hat Enterprise Virtualization Manager supportsActive Directory, Identity Management (IdM), OpenLDAP, and Red Hat Directory Server 9.There is also a local, internal domain for administration purposes only. This internaldomain 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


15

comprised of storage domains. A storage domain is a combination of storage capacity and metadatathat 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 isexclusive to a single data center. Export and ISO domains are optional. Storage domains are sharedresources, and must be accessible to all hosts in a data center.

Storage networking can be implemented using Network File System (NFS), Internet Small ComputerSystem Interface (iSCSI), GlusterFS, or Fibre Channel Protocol (FCP). Red Hat EnterpriseVirtualization additionally provides the unsupported ability to use any POSIX compliant networkedfilesystem as a data domain.

On NFS (and other POSIX compliant filesystems) domains, all virtual disks, templates, andsnapshots are simple files.

On SAN (iSCSI/FCP) domains, block devices are aggregated by Logical Volume Manager (LVM)intoa 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.

Figure 1.3. Storage Architecture

Data storage domain

Data domains hold the virtual hard disk images of all the virtual machines running in theenvironment. Templates and snapshots of the virtual machines are also stored in the datadomain. A data domain cannot be shared across data centers, and the data domain mustbe of the same type as the data center. For example, a data center of iSCSI type must havean iSCSI data domain.

Export storage domain

An export domain is a temporary storage repository that is used to copy and move imagesbetween data centers and Red Hat Enterprise Virtualization environments. The exportdomain can be used to back up virtual machines and templates. An export domain can bemoved between data centers, but can only be active in one data center at a time.

ISO storage domain

T echnical Guide

16

ISO domains store ISO files, which are logical CD-ROMs used to install operating systemsand applications for the virtual machines. As a logical entity that replaces a library ofphysical CD-ROMs or DVDs, an ISO domain removes the data center's need for physicalmedia. An ISO domain can be shared across different data centers.

1.7. Network

The Red Hat Enterprise Virtualization network architecture facilitates connectivity between thedifferent elements of the Red Hat Enterprise Virtualization environment. The network architecture notonly supports network connectivity, it also allows for network segregation.

Figure 1.4 . Network Architecture

Networking is defined in Red Hat Enterprise Virtualization in several layers. The underlying physicalnetworking infrastructure must be in place and configured to allow connectivity between thehardware and the logical components of the Red Hat Enterprise Virtualization environment.

Networking In f rast ructure Layer

The Red Hat Enterprise Virtualization network architecture relies on some commonhardware and software devices:

Network Interface Controllers (NICs) are physical network interface devices that connect ahost to the network.

Virtual NICs (VNICs) are logical NICs that operate using the host's physical NICs. Theyprovide 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 thebasis of virtual machine logical networks.

Logical Networks

Logical networks allow segregation of network traffic based on environment requirements.


17

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 levelas a software bridge device. By default, one logical network is defined during theinstallation of the Red Hat Enterprise Virtualization Manager: the rhevm managementnetwork.

Other logical networks that can be added by an administrator are: a dedicated storagelogical network, and a dedicated display logical network. Logical networks that do notcarry virtual machine traffic do not have an associated bridge device on hosts. They areassociated with host network interfaces directly.

Red Hat Enterprise Virtualization segregates management-related network traffic frommigration-related network traffic. This makes it possible to use a dedicated network (withoutrouting) for live migration, and ensures that the management network (rhevm) does not loseits connection to hypervisors during migrations.

Explanat ion of log ical networks on d if ferent layers

Logical networks have different implications for each layer of the virtualization environment.

Data Center Layer

Logical 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. Alogical network that is defined for a data center must also be added to the clusters that usethe logical network.

Cluster Layer

Logical networks are made available from a data center, and must be added to the clustersthat will use them. Each cluster is connected to the management network by default. Youcan optionally add to a cluster logical networks that have been defined for the cluster'sparent data center. When a required logical network has been added to a cluster, it must beimplemented for each host in the cluster. Optional logical networks can be added to hostsas needed.

Host Layer

Virtual machine logical networks are implemented for each host in a cluster as a softwarebridge device associated with a given network interface. Non-virtual machine logicalnetworks do not have associated bridges, and are associated with host network interfacesdirectly. Each host has the management network implemented as a bridge using one of itsnetwork devices as a result of being included in a Red Hat Enterprise Virtualizationenvironment. Further required logical networks that have been added to a cluster must beassociated with network interfaces on each host to become operational for the cluster.

T echnical Guide

18

Virtual Machine Layer

Logical networks can be made available to virtual machines in the same way that a networkcan be made available to a physical machine. A virtual machine can have its virtual NICconnected to any virtual machine logical network that has been implemented on the hostthat runs it. The virtual machine then gains connectivity to any other devices ordestinations that are available on the logical network it is connected to.

Example 1.1. Management Network

The management logical network, named rhevm, is created automatically when the RedHat Enterprise Virtualization Manager is installed. The rhevm network is dedicated tomanagement traffic between the Red Hat Enterprise Virtualization Manager and hosts. Ifno other specifically-purposed bridges are set up, rhevm is the default bridge for alltraffic.

1.8. Data Centers

A data center is the highest level of abstraction in Red Hat Enterprise Virtualization. A data center is acontainer that is comprised of three types of sub-containers:

The storage container holds information about storage types and storage domains, includingconnectivity information for storage domains. Storage is defined for a data center, and availableto all clusters in the data center. All host clusters within a data center have access to the samestorage domains.

The network container holds information about the data center's logical networks. This includesdetails such as network addresses, VLAN tags and STP support. Logical networks are defined fora 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 multipleclusters, and each cluster can contain multiple hosts.


19

Chapter 2. Storage

2.1. Storage Domains Overview

A storage domain is a collection of images that have a common storage interface. A storage domaincontains complete images of templates and virtual machines (including snapshots), ISO files, andmetadata about themselves. A storage domain can be made of either block devices (SAN - iSCSI orFCP) 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 areaggregated into a logical entity called a volume group, and then divided by LVM (Logical VolumeManager) into logical volumes for use as virtual hard disks. See Red Hat Enterprise Linux LogicalVolume 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 eitherSparse or Preallocated. Snapshots are always sparse but can be taken for disks created either asRAW or sparse.

Virtual machines that share the same storage domain can be migrated between hosts that belong tothe 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 andstorage 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 Virtualizationenvironment.

NFS storage is managed by a Red Hat Enterprise Linux NFS server, or other third partynetwork 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 volumegroups 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 ofLVM by scanning volume groups for changes. When changes are detected, VDSM updates

T echnical Guide

20

individual hosts by telling them to refresh their volume group information. The hosts dividethe volume group into logical volumes, writing logical volume metadata to disk. If morestorage capacity is added to an existing storage domain, the Red Hat EnterpriseVirtualization 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 blockstorage protocols, iSCSI, FCoE, or SAS, is used to connect to a LUN. The Red HatEnterprise Virtualization Manager manages software iSCSI connections to the LUNs. Allother block storage connections are managed externally to the Red Hat EnterpriseVirtualization environment. Any changes in a block based storage environment, such asthe creation of logical volumes, extension or deletion of logical volumes and the addition ofa new LUN are handled by LVM on a specially selected host called the Storage PoolManager. Changes are then synced by VDSM which storage metadata refreshes across allhosts in the cluster.

2.3. Storage Domain Types

Red Hat Enterprise Virtualization supports these types of storage domains, and the storage types thateach of the storage domains supports:

The Data Storage Domain stores the hard disk images of all virtual machines in the Red HatEnterprise Virtualization environment. Disk images may contain an installed operating system ordata 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 datacenters. Additionally, it is required that the data center and data storage domain use the sameprotocol (for example, both must be iSCSI based).

The Export Storage Domain provides transitory storage for hard disk images and virtual machinetemplates being transferred between data centers. Additionally, export storage domains storebacked up copies of virtual machines. Export storage domains support NFS storage. Multipledata centers can access a single export storage domain but only one data center can use it at atime.

The ISO Storage Domain stores ISO files, also called images. ISO files are representations ofphysical CDs or DVDs. In the Red Hat Enterprise Virtualization environment the common types ofISO files are operating system installation disks, application installation disks, and guest agentinstallation disks. These images can be attached to virtual machines and booted in the same waythat physical disks are inserted into a disk drive and booted. ISO storage domains allow all hostswithin the data center to share ISOs, eliminating the need for physical optical media.

2.4 . Storage Formats for Virtual Machine Disk Images

QCOW2 Format ted Virtual Machine Storage

QCOW2 is a storage format for virtual machine disk images. QCOW stands for QEMU copyon write. The QCOW2 format decouples the physical storage layer from the virtual layer byadding a mapping between logical and physical blocks. Each logical block is mapped toits 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 relevantblock is read from the backing volume, modified with the new information and written into anew snapshot QCOW2 volume. Then the map is updated to point to the new place.

RAW

Chapt er 2 . St orage

21

The RAW storage format has a performance advantage over QCOW2 in that no formattingis applied to virtual machine disk images stored in the RAW format. Virtual machine dataoperations 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 thesame offset on the backing file or logical volume.

Raw format requires that the entire space of the defined image be preallocated unless usingexternally managed thin provisioned LUNs from a storage array.

2.5. Virtual Machine Disk Image Storage Allocat ion Policies

Preallocated Storage

All of the storage required for a virtual machine disk image is allocated prior to virtualmachine creation. If a 20 GB disk image is created for a virtual machine, the disk imageuses 20 GB of storage domain capacity. Preallocated disk images cannot be enlarged.Preallocating storage can mean faster write times because no storage allocation takesplace during runtime, at the cost of flexibility. Allocating storage this way reduces thecapacity of the Red Hat Enterprise Virtualization Manager to overcommit storage.Preallocated storage is recommended for virtual machines used for high intensity I/O taskswith less tolerance for latency in storage. Generally, server virtual machines fit thisdescription.

Note

If thin provisioning functionality provided by your storage back-end is being used,preallocated storage should still be selected from the Administration Portal whenprovisioning 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 thevirtual machine writes data to disk, until the upper limit is reached. Capacity is not returnedto the storage domain when data in the disk image is removed. Sparsely allocated storageis appropriate for virtual machines with low or medium intensity I/O tasks with sometolerance 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 beused as the preferred implementation of thin provisioning. Storage should beprovisioned from the graphical user interface as preallocated, leaving thinprovisioning to the back-end solution.

2.6. Set t ings to Wipe Virtual Disks After Delet ion

T echnical Guide

22

The wipe_after_delete flag, viewed in the Administration Portal as the Wipe After Deletecheck box, enables the initialization of the virtual disk upon deletion. If it is set to false, which is thedefault, deleting the disk will open up those blocks for re-use but will not specifically wipe the data. Itis 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 hascontained any sensitive data. This is a more intensive operation and users may experiencedegradation in performance and prolonged delete times.

The wipe_after_delete flag default can be changed to true using the engine configuration toolon the Red Hat Enterprise Virtualization Manager. Restart the engine for the setting change to takeeffect.

Procedure 2.1. Set t ing SANWipeAf terDelete to Default to True Using the EngineConf igurat ion Tool

1. Run the engine configuration tool with the --set action:

# engine-config --set SANWipeDelete=true

2. Restart the engine for the change to take effect:

# service ovirt-engine restart

2.7. Storage Domain Autorecovery in Red Hat Enterprise Virtualizat ion

Hosts in a Red Hat Enterprise Virtualization environment monitor storage domains in their datacenters by reading metadata from each domain. A storage domain becomes inactive when all hostsin a data center report that they cannot access the storage domain.

Prior to Red Hat Enterprise Virtualization 3.1, storage domains that became inactive weredisconnected by the Manager. Reconnecting to storage when connection issues had been resolvedrequired manual administrator intervention.

Red Hat Enterprise Virtualization 3.1 introduced storage domain autorecovery. Rather thandisconnecting an inactive storage domain, the Manager now assumes that the storage domain hasbecome inactive temporarily, because of a temporary network outage for example. Once every 5minutes, the Manager attempts to re-activate any inactive storage domains.

Administrator intervention may be required to remedy the cause of the storage connectivityinterruption, 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 storagedomain metadata based on a single writer, and multiple readers configuration. Storage domainstructural metadata tracks image and snapshot creation and deletion, and volume and domainextension.

The Red Hat Enterprise Virtualization host that can make changes to the structure of the data domainis known as the Storage Pool Manager (SPM). The SPM coordinates all metadata changes in thedata center, such as creating and deleting disk images, creating and merging snapshots, copyingimages between storage domains, creating templates and storage allocation for block devices. There


23

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 EnterpriseVirtualization Manager. The Manager assigns the SPM role by causing a potential SPM host toattempt to assume a storage-centric lease. The lease allows the SPM host to write storage metadata. Itis storage-centric because it is written to the storage domain rather than being tracked by theManager or hosts. Storage-centric leases are written to a special logical volume in the master storagedomain called leases. Metadata about the structure of the data domain is written to a speciallogical volume called metadata. Changes to the metadata logical volume are protected against bythe leases logical volume.

The Manager uses VDSM to issue the spmStart command to a host, causing VDSM on that host toattempt to assume the storage-centric lease. If the host is successful it becomes the SPM and retainsthe storage-centric lease until the Red Hat Enterprise Virtualization Manager requests that a new hostassume 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 leasevolume is full and no write operation can be performed.

the SPM host crashes.

Figure 2.1. The Storage Pool Manager Exclusively Writes St ructural Metadata.

2.9. Storage Pool Manager Select ion Process

T echnical Guide

24

If a host has not been manually assigned the Storage Pool Manager (SPM) role, the SPM selectionprocess 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 thestorage-centric lease.

The Red Hat Enterprise Virtualization Manager tracks the history of SPM assignment from the initialcreation 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 SPMstatus 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 EnterpriseVirtualization 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 beenconfigured for the host, it is automatically fenced. If not, it requires manual fencing. The Storage PoolManager 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 Managerassigns 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 addsthe host to a list containing hosts the operation has failed on, marking these hosts as ineligible forthe SPM role. This list is cleared at the beginning of the next SPM selection process so that all hostsare again eligible.

The Red Hat Enterprise Virtualization Manager continues request that the Storage Pool Manager roleand storage-centric lease be assumed by a randomly selected host that is not on the list of failedhosts until the SPM selection succeeds.

Each time the current SPM is unresponsive or unable to fulfill its responsibilities, the Red HatEnterprise Virtualization Manager initiates the Storage Pool Manager selection process.

2.10. Exclusive Resources and Sanlock in Red Hat EnterpriseVirtualizat ion

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 arisk 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 aVDSM feature called safelease. The lease was written to a special area on all of the storage domainsin a data center. All of the hosts in an environment could track SPM status in a network-independentway. 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 belocked. Sanlock is more flexible because it allows additional resources to be locked.

Applications that require resource locking can register with Sanlock. Registered applications canthen 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.


25

Locks are tracked on disk in a lockspace. There is one lockspace for every storage domain. In thecase of the lock on the SPM resource, each host's liveness is tracked in the lockspace by the host'sability to renew the hostid it received from the Manager when it connected to storage, and to write atimestamp to the lockspace at a regular interval. The ids logical volume tracks the unique identifiersof each host, and is updated every time a host renews its hostid. The SPM resource can only be heldby a live host.

Resources are tracked on disk in the leases logical volume. A resource is said to be taken when itsrepresentation on disk has been updated with the unique identifier of the process that has taken it. Inthe 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 aretaken. After an initial check, Sanlock can monitor the lockspaces until timestamp of the host with alocked resource becomes stale.

Sanlock monitors the applications that use resources. For example, VDSM is monitored for SPMstatus and hostid. If the host is unable to renew it's hostid from the Manager, it loses exclusivity on allresources 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 givenamount 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 lockspacecan be taken by another host.

If VDSM on the SPM host does not respond to requests to release resources, Sanlock on the hostkills the VDSM process. If the kill command is unsuccessful, Sanlock escalates by attempting to killVDSM using sigkill. If the sigkill is unsuccessful, Sanlock depends on the watchdog daemon to rebootthe host.

Every time VDSM on the host renews its hostid and writes a timestamp to the lockspace, the watchdogdaemon receives a pet. When VDSM is unable to do so, the watchdog daemon is no longer beingpetted. After the watchdog daemon has not received a pet for a given amount of time, it reboots thehost. This final level of escalation, if reached, guarantees that the SPM resource is released, and canbe taken by another host.

2.11. Thin Provisioning and Storage Over-Commitment

The Red Hat Enterprise Virtualization Manager provides provisioning policies to optimize storageusage within the virtualization environment. A thin provisioning policy allows you to over-commitstorage resources, provisioning storage based on the actual storage usage of your virtualizationenvironment.

Storage over-commitment is the allocation of more storage to virtual machines than is physicallyavailable in the storage pool. Generally, virtual machines use less storage than what has beenallocated to them. Thin provisioning allows a virtual machine to operate as if the storage defined forit 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 provisioningfunction, you should use the thin provisioning functionality of your storage back-end if itprovides one.

To support storage over-commitment, a threshold is defined in VDSM which compares logicalstorage allocation with actual storage usage. This threshold is used to make sure that the data

T echnical Guide

26

written to a disk image is smaller than the logical volume that backs it. QEMU identifies the highestoffset written to in a logical volume, which indicates the point of greatest storage use. VDSM monitorsthe highest offset marked by QEMU to ensure that the usage does not cross the defined threshold. Solong as VDSM continues to indicate that the highest offset remains below the threshold, the Red HatEnterprise Virtualization Manager knows that the logical volume in question has sufficient storage tocontinue operations.

When QEMU indicates that usage has risen to exceed the threshold limit, VDSM communicates to theManager that the disk image will soon reach the size of it's logical volume. The Red Hat EnterpriseVirtualization Manager requests that the SPM host extend the logical volume. This process can berepeated as long as the data storage domain for the data center has available space. When the datastorage domain runs out of available free space, you must manually add storage capacity to expandit.

2.12. Logical Volume Extension

The Red Hat Enterprise Virtualization Manager uses thin provisioning to overcommit the storageavailable in a storage pool, and allocates more storage than is physically available. Virtualmachines write data as they operate. A virtual machine with a thinly-provisioned disk image willeventually write more data than the logical volume backing its disk image can hold. When thishappens, logical volume extension is used to provide additional storage and facilitate the continuedoperations for the virtual machine.

Red Hat Enterprise Virtualization provides a thin provisioning mechanism over LVM. When usingQCOW2 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, forexample, the definition of a logical 100 GB disk backed by a 1 GB logical volume. When qemu-kvmcrosses a usage threshold set by VDSM, the local VDSM instance makes a request to the SPM for thelogical volume to be extended by another one gigabyte. VDSM on the host running a virtual machinein need of volume extension notifies the SPM VDSM that more space is required. The SPM extendsthe logical volume and the SPM VDSM instance causes the host VDSM to refresh volume groupinformation 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 couldeven be the SPM itself. The storage extension communication is done via a storage mailbox. Thestorage mailbox is a dedicated logical volume on the data storage domain. A host that needs theSPM to extend a logical volume writes a message in an area designated to that particular host in thestorage mailbox. The SPM periodically reads the incoming mail, performs requested logical volumeextensions, and writes a reply in the outgoing mail. After sending the request, a host monitors itsincoming mail for responses every two seconds. When the host receives a successful reply to itslogical volume extension request, it refreshes the logical volume map in device mapper to recognizethe newly allocated storage.

When the physical storage available to a storage pool is nearly exhausted, multiple images can runout of usable storage with no means to replenish their resources. A storage pool that exhausts itsstorage causes QEMU to return an enospc error, which indicates that the device no longer hasany storage available. At this point, running virtual machines are automatically paused and manualintervention 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 distributesthe additional storage to logical volumes that need it. The automatic allocation of additionalresources allows the relevant virtual machines to automatically continue operations uninterrupted orresume operations if stopped.


27

Chapter 3. Network

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 thebasic hardware and software elements that facilitate networking. Networking within a cluster includesnetwork interactions among cluster level objects such as hosts, logical networks and virtualmachines. Host networking configurations covers supported configurations for networking within ahost.

A well designed and built network ensures, for example, that high bandwidth tasks receive adequatebandwidth, that user interactions are not crippled by latency, and virtual machines can besuccessfully 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. Int roduct ion: 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, localarea networks, and the Internet. Bonds and VLANs are optionally implemented to enhance security,fault tolerance, and network capacity.

3.3. Network Interface Cont roller

The NIC (Network Interface Controller) is a network adapter or LAN adapter that connects a computer toa computer network. The NIC operates on both the physical and data link layers of the machine andallows network connectivity. All virtualization hosts in a Red Hat Enterprise Virtualizationenvironment 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 actsas a physical network interface for a virtual machine. To distinguish between a VNIC and the NIC thatsupports 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. Bridgingallows multiple network interface devices to share the connectivity of one NIC and appear on anetwork as separate physical devices. The bridge examines a packet's source addresses todetermine relevant target addresses. Once the target address is determined, the bridge adds the

T echnical Guide

28

location to a table for future reference. This allows a host to redirect network traffic to virtual machineassociated VNICs that are members of a bridge.

In Red Hat Enterprise Virtualization a logical network is implemented using a bridge. It is the bridgerather than the physical interface on a host that receives an IP address. The IP address associatedwith the bridge is not required to be within the same subnet as the virtual machines that use thebridge for connectivity. If the bridge is assigned an IP address on the same subnet as the virtualmachines that use it, the host is addressable within the logical network by virtual machines. As a ruleit 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 remoteelements of the logical network using its NIC. Each guest can have the IP address of its VNIC setindependently, by DHCP or statically. Bridges can connect to objects outside the host, but such aconnection is not mandatory.

Custom properties can be defined for both the bridge and the Ethernet connection. VDSM passes thenetwork 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 interfacecards included in the bond to act as a single network interface, they can provide greatertransmission speed than that of a single network interface card. Also, because all network interfacecards 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 mustbe of the same make and model to ensure that all network interface cards in the bond support thesame 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 commonbonding modes:

Mode 0 (round-robin policy)

Transmits packets through network interface cards in sequential order. Packets aretransmitted in a loop that begins with the first available network interface card in the bondand end with the last available network interface card in the bond. All subsequent loopsthen start with the first available network interface card. Mode 0 offers fault tolerance andbalances the load across all network interface cards in the bond. However, Mode 0 cannotbe used in conjunction with bridges, and is therefore not compatible with virtual machinelogical networks.

Mode 1 (active-backup policy)

Sets all network interface cards to a backup state while one network interface card remains

Chapt er 3. Net work

29

active. In the event of failure in the active network interface card, one of the backup networkinterface cards replaces that network interface card as the only active network interfacecard in the bond. The MAC address of the bond in Mode 1 is visible on only one port toprevent any confusion that might otherwise be caused if the MAC address of the bondchanged to reflect that of the active network interface card. Mode 1 provides fault toleranceand 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 ofan XOR operation on the source and destination MAC addresses modulo network interfacecard slave count. This calculation ensures that the same network interface card is selectedfor each destination MAC address used. Mode 2 provides fault tolerance and loadbalancing 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 issupported in Red Hat Enterprise Virtualization.

Mode 4 (IEEE 802.3ad policy)

Creates aggregation groups in which the interfaces share the same speed and duplexsettings. Mode 4 uses all network interface cards in the active aggregation group inaccordance with the IEEE 802.3ad specification and is supported in Red Hat EnterpriseVirtualization.

Mode 5 (adaptive transmit load balancing policy)

Ensures the distribution of outgoing traffic accounts for the load on each network interfacecard in the bond and that the current network interface card receives all incoming traffic. Ifthe network interface card assigned to receive traffic fails, another network interface card isassigned to the role of receiving incoming traffic. Mode 5 cannot be used in conjunctionwith 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 forIPv4 traffic without any special switch requirements. ARP negotiation is used for balancingthe receive load. Mode 6 cannot be used in conjunction with bridges, therefore it is notcompatible with virtual machine logical networks.

3.6. Switch Configurat ion for Bonding

Switch configurations vary per the requirements of your hardware. Refer to the deployment andnetworking configuration guides for your operating system.

Important

For every type of switch it is important to set up the switch bonding with the Link AggregationControl Protocol (LACP) protocol and not the Cisco Port Aggregation Protocol (PAgP) protocol.

3.7. Virtual Network Interface Cards

T echnical Guide

30

Virtual network interface cards are virtual network interfaces that are based on the physical networkinterface cards of a host. Each host can have multiple network interface cards, and each networkinterface 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 EnterpriseVirtualization Manager creates several associations between the virtual machine to which the virtualnetwork interface card is being attached, the virtual network interface card itself, and the physicalhost network interface card on which the virtual network interface card is based. Specifically, when avirtual network interface card is attached to a virtual machine, a new virtual network interface cardand MAC address are created on the physical host network interface card on which the virtualnetwork interface card is based. Then, the first time the virtual machine starts after that virtual networkinterface card is attached, libvirt assigns the virtual network interface card a PCI address. TheMAC 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 PCIaddresses 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 networkinterface cards on virtual machines created based on that template or snapshot are ordered inaccordance with those PCI addresses and MAC addresses allocated in that order. If PCI addresseshave not already been created for a template, the virtual network interface cards on virtual machinescreated based on that template are allocated in the order of the naming of the virtual networkinterface cards. If PCI addresses have not already been created for a snapshot, the Red HatEnterprise Virtualization Manager allocates new MAC addresses to the virtual network interface cardson virtual machines based on that snapshot.

Once created, virtual network interface cards are added to a network bridge device. The networkbridge 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 thevirtual network interface cards that are associated with virtual machines on that host. Also visible areany network bridges that have been created to back logical networks, and any network interfacecards 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 forever2: 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 forever3: 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:ff5: ;vdsmdummy;: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN link/ether 4a:d5:52:c2:7f:4b brd ff:ff:ff:ff:ff:ff6: bond0: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff7: bond4: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff8: bond1: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff9: bond2: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN


31

link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff10: bond3: <BROADCAST,MULTICAST,MASTER> mtu 1500 qdisc noop state DOWN link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff11: 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 ), oneEthernet device (eth0 ), one wireless device (wlan0 ), one VDSM dummy device (;vdsmdummy;), fivebond 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 showbridge name bridge id STP enabled interfacesrhevm 8000.e41f13b7fdd4 no vnet002 vnet001 vnet000 eth0

The console output from the brctl show command shows that the virtio virtual network interfacecards are members of the rhevm bridge. All of the virtual machines that the virtual network interfacecards are associated with are connected to the rhevm logical network. The eth0 network interfacecard is also a member of the rhevm bridge. The eth0 device is cabled to a switch that providesconnectivity 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 trafficat the switch level. VLANs are completely separate and mutually exclusive. The Red Hat EnterpriseVirtualization Manager is VLAN aware and able to tag and redirect VLAN traffic, however VLANimplementation requires a switch that supports VLANs.

At the switch level, ports are assigned a VLAN designation. A switch applies a VLAN tag to trafficoriginating from a particular port, marking the traffic as part of a VLAN, and ensures that responsescarry the same VLAN tag. A VLAN can extend across multiple switches. VLAN tagged network traffic ona switch is completely undetectable except by machines connected to a port designated with thecorrect VLAN. A given port can be tagged into multiple VLANs, which allows traffic from multipleVLANs to be sent to a single port, to be deciphered using software on the machine that receives thetraffic.

3.9. Cluster Networking

Cluster level networking objects include:

Clusters

Logical Networks

T echnical Guide

32

Figure 3.1. Networking with in a cluster

A data center is a logical grouping of multiple clusters and each cluster is a logical group of multiplehosts. 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 logicalnetworks applied at the cluster level. For a virtual machine logical network to become operational foruse with virtual machines, the network must be defined and implemented for each host in the clusterusing the Red Hat Enterprise Virtualization Manager. Other logical network types can be implementedon only the hosts that use them.

Multi-host network configuration is available on data centers with 3.1-or-higher compatibility, andautomatically applies any updated network settings to all of the hosts within the data center to whichthe network is assigned.

3.10. Logical Networks

Logical networking allows the Red Hat Enterprise Virtualization environment to separate networktraffic by type. For example, the rhevm network is created by default during the installation of the RedHat Enterprise Virtualization to be used for management communication between the Manager andhosts. A typical use for logical networks is to group network traffic with similar requirements andusage together. In many cases, a storage network and a display network are created by anadministrator to isolate traffic of each respective type for optimization and troubleshooting.


33

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 logicalnetwork 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 bya network bridge device on a host. So when a new virtual machine logical network is defined for acluster, a matching bridge device must be created on each host in the cluster before the logicalnetwork can become operational to be used by virtual machines. Red Hat Enterprise VirtualizationManager automatically creates required bridges for virtual machine logical networks.

The bridge device created by the Red Hat Enterprise Virtualization Manager to back a virtual machinelogical network is associated with a host network interface. If the host network interface that is part ofa bridge has network connectivity, then any network interfaces that are subsequently included in thebridge share the network connectivity of the bridge. When virtual machines are created and placedon a particular logical network, their virtual network cards are included in the bridge for that logicalnetwork. Those virtual machines can then communicate with each other and with other objects thatare connected to the bridge.

Logical networks not used for virtual machine network traffic are associated with host networkinterfaces directly.

T echnical Guide

34

Figure 3.2. The rhevm logical network.

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 networkingfunctions. The system administrator responsible for Pink decides to isolate network testing for aweb server by placing the web server and some client virtual machines on a separate logicalnetwork. 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 Pinkcluster. Logical networks must be implemented on a host in maintenance mode. So, theadministrator first migrates all running virtual machines to Red, and puts White in maintenancemode. Then she edits the Network associated with the physical network interface that will beincluded in the bridge. The Link Status for the selected network interface will change from Downto Non-Operational . The non-operational status is because the corresponding bridge must besetup in all hosts in the cluster by adding a physical network interface on each host in the Pinkcluster to the network_testing network. Next she activates White, migrates all of the runningvirtual 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 physicalnetwork interface, the network_testing logical network becomes Operational and is ready tobe used by virtual machines.

3.11. Required Networks, Opt ional Networks, and Virtual MachineNetworks


35

Networks

A required network is a logical network that must be available to all hosts in a cluster. When a host'srequired network becomes non-operational, virtual machines running on that host are migrated toanother host; the extent of this migration is dependent upon the chosen scheduling policy. This isbeneficial 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 ofoptional networks does not affect the Operational status of a host. When a non-required networkbecomes non-operational, the virtual machines running on the network are not migrated to anotherhost. This prevents unnecessary I/O overload caused by mass migrations. Note that when a logicalnetwork 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, clickthe Cluster tab, and click the Manage Networks button.

Virtual machine networks (called a VM network in the user interface) are logical networksdesignated to carry only virtual machine network traffic. Virtual machine networks can be required oroptional. Virtual machines that uses an optional virtual machine network will only start on hosts withthat network.

3.12. Virtual Machine Connect ivit y

In Red Hat Enterprise Virtualization, a virtual machine has its NIC put on a logical network at the timethat the virtual machine is created. From that point, the virtual machine is able to communicate withany other destination on the same network.

From the host perspective, when a virtual machine is put on a logical network, the VNIC that backsthe virtual machine's NIC is added as a member to the bridge device for the logical network. Forexample, 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 interfaceon a virtual machine. This virtual machine can be used for network debugging and tuning, intrusiondetection, and monitoring the behavior of other virtual machines on the same host and logicalnetwork.

The only traffic copied is internal to one logical network on one host. There is no increase on trafficon the network external to the host; however a virtual machine with port mirroring enabled uses morehost CPU and RAM than other virtual machines.

Port mirroring is enabled or disabled in the vNIC profiles of logical networks, and has the followingrequirements 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.

T echnical Guide

36

Important

Enabling port mirroring reduces the privacy of other network users.

3.14. Host Networking Configurat ions

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 Configurat ion

The simplest host configuration in Red Hat Enterprise Virtualization is the Bridge and NICconfiguration. As Figure 3.3, “Bridge and NIC configuration” depicts, this configuration uses abridge to connect one or more virtual machines (or guests) to the host's NIC.

Figure 3.3. Bridge and NIC conf igurat ion

An example of this configuration is the automatic creation of the bridge rhevm when the Red HatEnterprise Virtualization Manager installs. On installation, the Red Hat Enterprise VirtualizationManager 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 thehost.


37

3.16. VLAN Configurat ion

Figure 3.4, “Bridge, VLAN, and NIC configuration” depicts an alternative configuration that includesa virtual LAN (VLAN) to connect the host NIC and bridge.

Figure 3.4 . Bridge, VLAN, and NIC conf igurat ion

A VLAN is included to provide a secure channel for data transfer over this network and also tosupport the option to connect multiple bridges to a single NIC using multiple VLANs.

3.17. Bridge and Bond Configurat ion

Figure 3.5, “Bridge, Bond, and NIC configuration” displays a configuration that includes a bond toconnect multiple host NICs to the same bridge and network.

T echnical Guide

38

Figure 3.5. Bridge, Bond, and NIC conf igurat ion

The included bond creates a logical link that combines the two (or more) physical Ethernet links. Theresultant benefits include NIC fault tolerance and potential bandwidth extension, depending on thebonding mode.

3.18. Mult iple Bridge, Mult iple VLAN, and NIC Configurat ion

Figure 3.6, “Multiple Bridge, Multiple VLAN, and NIC configuration” depicts a configuration thatconnects a single NIC to two VLANs. This presumes that the network switch has been configured topass network traffic that has been tagged into one of the two VLANs to one NIC on the host. The hostuses two VNICs to separate VLAN traffic, one for each VLAN. Traffic tagged into either VLAN thenconnects to a separate bridge by having the appropriate VNIC as a bridge member. Each bridge is inturn connected to by multiple virtual machines.


39

Figure 3.6 . Mult ip le Bridge, Mult ip le VLAN, and NIC conf igurat ion

3.19. Mult iple Bridge, Mult iple VLAN, and Bond Configurat ion

Figure 3.7, “Multiple Bridge, Multiple VLAN, and Multiple NIC with Bond connection” displays aconfiguration that bonds multiple NICs to facilitate a connection with multiple VLANs.

Figure 3.7. Mult ip le Bridge, Mult ip le VLAN, and Mult ip le NIC with Bond connect ion

Each VLAN in this configuration is defined over the bond connecting the NICs. Each VLAN connectsto an individual bridge and each bridge connects to one or more guests.

T echnical Guide

4 0

Chapter 4. Power Management

4.1. Int roduct ion to Power Management and Fencing

The Red Hat Enterprise Virtualization environment is most flexible and resilient when powermanagement and fencing have been configured. Power management allows the Red Hat EnterpriseVirtualization Manager to control host power cycle operations, most importantly to reboot hosts onwhich problems have been detected. Fencing is used to isolate problem hosts from a functional RedHat Enterprise Virtualization environment by rebooting them, in order to prevent performancedegradation. Fenced hosts can then be returned to responsive status through administrator actionand be reintegrated into the environment.

Power management and fencing make use of special dedicated hardware in order to restart hostsindependently of host operating systems. The Red Hat Enterprise Virtualization Manager connects toa power management devices using a network IP address or hostname. In the context of Red HatEnterprise Virtualization, a power management device and a fencing device are the same thing.

4.2. Power Management by Proxy in Red Hat Enterprise Virtualizat ion

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 powermanagement device. The Manager uses VDSM to execute power management device actions, soanother 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 anon-operational or non-responsive state, as well as preparing to power off under-utilized hosts tosave power. This functionality depends on a properly configured power management device. TheRed 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).

Chapt er 4 . Power Management

4 1

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 EnterpriseVirtualization Manager makes use of fence agents. The Red Hat Enterprise Virtualization Managerallows administrators to configure a fence agent for the power management device in theirenvironment with parameters the device will accept and respond to. Basic configuration options canbe 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 givenfence device, while basic configuration options are for functionalities provided by all supportedpower management devices. The basic functionalities provided by all power management devicesare:

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, andoccasionally after that to ensure continued functionality.

Resilience is provided by properly configured power management devices in all of the hosts in anenvironment. Fencing agents allow the Red Hat Enterprise Virtualization Manager to communicatewith host power management devices to bypass the operating system on a problem host, and isolatethe 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 otherhosts.

4.4 . Fencing

In the context of the Red Hat Enterprise Virtualization environment, fencing is a host reboot initiatedby the Manager using a fence agent and performed by a power management device. Fencing allowsa cluster to react to unexpected host failures as well as enforce power saving, load balancing, andvirtual machine availability policies.

Fencing ensures that the role of Storage Pool Manager (SPM) is always assigned to a functionalhost. If the fenced host was the SPM, the SPM role is relinquished and reassigned to a responsivehost. Because the host with the SPM role is the only host that is able to write data domain structuremetadata, a non-responsive, un-fenced SPM host causes its environment to lose the ability to createand destroy virtual disks, take snapshots, extend logical volumes, and all other actions that requirechanges to data domain structure metadata.

When a host becomes non-responsive, all of the virtual machines that are currently running on thathost can also become non-responsive. However, the non-responsive host retains the lock on the

T echnical Guide

4 2

virtual machine hard disk images for virtual machines it is running. Attempting to start a virtualmachine on a second host and assign the second host write privileges for the virtual machine harddisk image can cause data corruption.

Fencing allows the Red Hat Enterprise Virtualization Manager to assume that the lock on a virtualmachine hard disk image has been released; the Manager can use a fence agent to confirm that theproblem host has been rebooted. When this confirmation is received, the Red Hat EnterpriseVirtualization Manager can start a virtual machine from the problem host on another host withoutrisking data corruption. Fencing is the basis for highly-available virtual machines. A virtual machinethat has been marked highly-available can not be safely started on an alternate host without thecertainty that doing so will not cause data corruption.

When a host becomes non-responsive, the Red Hat Enterprise Virtualization Manager allows a graceperiod of thirty (30) seconds to pass before any action is taken, to allow the host to recover from anytemporary errors. If the host has not become responsive by the time the grace period has passed, theManager automatically begins to mitigate any negative impact from the non-responsive host. TheManager uses the fencing agent for the power management card on the host to stop the host, confirmit has stopped, start the host, and confirm that the host has been started. When the host finishesbooting, it attempts to rejoin the cluster that it was a part of before it was fenced. If the issue thatcaused the host to become non-responsive has been resolved by the reboot, then the host isautomatically 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 isunable to respond to requests, the virtual machines that depend upon VDSM remain alive andaccessible. In these situations, restarting VDSM returns VDSM to a responsive state and resolves thisissue.

Red Hat Enterprise Virtualization 3.3 introduced "soft-fencing over SSH". Prior to Red Hat EnterpriseVirtualization 3.3, non-responsive hosts were fenced only by external fencing devices. In Red HatEnterprise Virtualization 3.3 and above, the fencing process has been expanded to include "SSHSoft Fencing", a process where the Manager attempts to restart VDSM via SSH on non-responsivehosts. If the Manager fails to restart VDSM via SSH, the responsibility for fencing falls to the externalfencing 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 avalid proxy host (a second host, in an UP state, in the data center) must exist. When the connectionbetween the Manager and the host times out, the following happens:

1. On the first network failure, the status of the host changes to "connecting".

2. The Manager then makes three attempts to ask VDSM for its status, or it waits for an intervaldetermined by the load on the host. The formula for determining the length of the interval isconfigured by the configuration values TimeoutToResetVdsInSeconds (the default is 60seconds) + [DelayResetPerVmInSeconds (the default is 0.5 seconds)]*(the count of runningvirtual machines on host) + [DelayResetForSpmInSeconds (the default is 20 seconds)] * 1 (ifhost runs as SPM) or 0 (if the host does not run as SPM). To give VDSM the maximumamount of time to respond, the Manager chooses the longer of the two options mentionedabove (three attempts to retrieve the status of VDSM or the interval determined by the aboveformula).

3. If the host does not respond when that interval has elapsed, vdsm restart is executed viaSSH.

Chapt er 4 . Power Management

4 3

4. If vdsm restart does not succeed in re-establishing the connection between the host andthe Manager, the status of the host changes to Non Responsive and, if power managementis 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 powermanagement configured.

4.6. Using Mult iple Power Management Fencing Agents

Prior to Red Hat Enterprise Virtualization 3.2, a host with power management configured onlyrecognized one fencing agent. Fencing agents configured on version 3.1 and earlier, and singleagents, are treated as primary agents. The secondary agent is valid when there are two fencingagents, for example for dual-power hosts in which each power switch has two agents connected tothe 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. Forexample, when the sole fencing agent on a host fails, the host will remain in a non-operational stateuntil 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. Withmultiple 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 orsequential flow:

Concurrent : Both primary and secondary agents have to respond to the Stop command for thehost to be stopped. If one agent responds to the Start command, the host will go up.

Sequent ial : To stop or start a host, the primary agent is used first, and if it fails, the secondaryagent is used.

T echnical Guide

4 4

Chapter 5. Load Balancing, Scheduling, and Migration

5.1. Load Balancing, Scheduling, and Migrat ion

Individual hosts have finite hardware resources, and are susceptible to failure. To mitigate againstfailure and resource exhaustion, hosts are grouped into clusters, which are essentially a grouping ofshared resources. A Red Hat Enterprise Virtualization environment responds to changes in demandfor host resources using load balancing policy, scheduling, and migration. The Manager is able toensure 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 machinesoff 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 willstart.

Virtual machine migration - Resources are checked in order to determine an appropriate targethost.

Time elapses - Resources are checked at a regular interval to determine whether individual hostload is in compliance with cluster load balancing policy.

The Manager responds to changes in available resources by using the load balancing policy for acluster to schedule the migration of virtual machines from one host in a cluster to another. Therelationship between load balancing policy, scheduling, and virtual machine migration arediscussed 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 havedifferent hardware parameters and available memory. The Red Hat Enterprise Virtualization Manageruses a load balancing policy to determine which host in a cluster to start a virtual machine on. Loadbalancing 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 determineswhich hosts are over-utilized, which are hosts under-utilized, and which are valid targets for virtualmachine migration. The determination is made based on the load balancing policy set by anadministrator 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_Dist ributed

A virtual machine evenly distributed load balancing policy distributes virtual machines evenlybetween hosts based on a count of the virtual machines. The high virtual machine count is themaximum number of virtual machines that can run on each host, beyond which qualifies asoverloading the host. The VM_Evenly_Distributed policy allows an administrator to set a high virtualmachine count for hosts. The maximum inclusive difference in virtual machine count between themost highly-utilized host and the least-utilized host is also set by an administrator. The cluster isbalanced when every host in the cluster has a virtual machine count that falls inside this migrationthreshold. The administrator also sets the number of slots for virtual machines to be reserved on SPMhosts. The SPM host will have a lower load than other hosts, so this variable defines how many fewervirtual machines than other hosts it can run. If any host is running more virtual machines than the

Chapt er 5. Load Balancing, Scheduling, and Migrat ion

4 5

high virtual machine count and at least one host has a virtual machine count that falls outside of themigration threshold, virtual machines are migrated one by one to the host in the cluster that has thelowest CPU utilization. One virtual machine is migrated at a time until every host in the cluster has avirtual machine count that falls within the migration threshold.

5.4 . Load Balancing Policy: Evenly_Dist ributed

An evenly distributed load balancing policy selects the host for a new virtual machine according tolowest CPU utilization. The maximum service level is the maximum CPU utilization that is allowed forhosts in a cluster, beyond which environment performance will degrade. The Evenly_Distributedpolicy allows an administrator to set a maximum service level for running virtual machines. Thelength of time a host is allowed to continue at this maximum service level before the Red HatEnterprise Virtualization Manager intervenes is also set by an administrator. If a host has reached themaximum service level and stays there for more than the set time, virtual machines on that host aremigrated one by one to the host in the cluster that has the lowest CPU utilization. Host resources arechecked once per minute, and one virtual machine is migrated at a time until the host CPU utilizationis 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 lowestCPU utilization. The maximum service level is the maximum CPU utilization that is allowed for hostsin a cluster, beyond which environment performance will degrade. The minimum service level is theminimum CPU utilization allowed before the continued operation of a host is considered an inefficientuse of electricity. The Power_Saving policy allows an administrator to set a maximum and minimumservice level for running virtual machines. The length of time a host is allowed to continue at thismaximum or minimum service level before the Red Hat Enterprise Virtualization Manager intervenes isalso set by an administrator. If a host has reached the maximum service level and stays there formore than the set time, the virtual machines on that host are migrated one by one to the host that hasthe lowest CPU utilization. The process continues until the host CPU utilization is below maximumservice level. If a host CPU utilization falls below the minimum service level the virtual machines aremigrated to other hosts in the cluster if their maximum service level permits. When an under-utilizedhost is cleared of its remaining virtual machines, the Manager will automatically power down the hostmachine, and restart it again when load balancing requires or there are not enough free hosts in thecluster.

5.6. Load Balancing Policy: None

If no load balancing policy is selected, virtual machines are started on the host within a cluster withthe lowest CPU utilization and available memory. To determine CPU utilization a combined metric isused that takes into account the virtual CPU count and the CPU usage percent. This approach is theleast dynamic, as the only host selection point is when a new virtual machine is started. Virtualmachines 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 virtualmachine. Virtual machines can also be associated with a particular host using pinning. Pinningprevents a virtual machine from being automatically migrated to other hosts. For environments whereresources are highly consumed, manual migration is the best approach.

5.7. Highly Available Virtual Machine Reservat ion

A highly available (HA) virtual machine reservation policy enables the Red Hat EnterpriseVirtualization Manager to monitor cluster capacity for highly available virtual machines. The

T echnical Guide

4 6

Manager has the capability to flag individual virtual machines for High Availability, meaning that inthe 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 inthe cluster fails, the remaining hosts can support the migrating load of highly available virtualmachines without affecting cluster performance. When highly available virtual machine reservation isenabled, the Manager ensures that appropriate capacity exists within a cluster for HA virtualmachines 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 VirtualizationManager 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 anotherhost, it must have enough free memory and CPUs to support the requirements of the virtual machinebeing started on or migrated to it. If multiple hosts are eligible targets, one will be selected based onthe load balancing policy for the cluster. For example, if the Evenly_Distributed policy is in effect, theManager chooses the host with the lowest CPU utilization. If the Power_Saving policy is in effect, thehost with the lowest CPU utilization between the maximum and minimum service levels will beselected. The Storage Pool Manager (SPM) status of a given host also affects eligibility as a targetfor 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 roleis held by a host in that cluster.

5.9. Migrat ion

The Red Hat Enterprise Virtualization Manager uses migration to enforce load balancing policies fora cluster. Virtual machine migration takes place according to the load balancing policy for a clusterand current demands on hosts within a cluster. Migration can also be configured to automaticallyoccur when a host is fenced or moved to maintenance mode. The Red Hat Enterprise VirtualizationManager first migrates virtual machines with the lowest CPU utilization. This is calculated as apercentage, and does not take into account RAM usage or I/O operations, except as I/O operationsaffect CPU utilization. If there are more than one virtual machines with the same CPU usage, the onethat will be migrated first is the first virtual machine returned by the database query run by the RedHat Enterprise Virtualization Manager to determine virtual machine CPU usage.

Virtual machine migration has the following limitations by default:

A bandwidth limit of 32 MiBps (megabytes per second) is imposed on each virtual machinemigration.

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 issmaller.

See https://access.redhat.com/solutions/744423 for more details about tuning migration settings.

Chapt er 5. Load Balancing, Scheduling, and Migrat ion

4 7

https://access.redhat.com/solutions/744423

Chapter 6. Directory Services

6.1. Directory Services

The Red Hat Enterprise Virtualization platform relies on directory services for user authentication andauthorization. Interactions with all Manager interfaces, including the User Portal, AdministrationPortal, and REST API are limited to authenticated, authorized users. Virtual machines within the RedHat Enterprise Virtualization environment can use the same directory services to provideauthentication and authorization, however they must be configured to do so. The currently supportedproviders of directory services for use with the Red Hat Enterprise Virtualization Manager are IdentityManagement (IdM), Red Hat Directory Server 9 (RHDS), Active Directory (AD), and OpenLDAP. The RedHat 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 theintegrity of the generated data. A principal is the party whose identity is verified. The verifier is theparty who demands assurance of the principal's identity. In the case of Red Hat EnterpriseVirtualization, the Manager is the verifier and a user is a principal. Data integrity is the assurancethat the data received is the same as the data generated by the principal.

Confidentiality and authorization are closely related to authentication. Confidentiality protects datafrom disclosure to those not intended to receive it. Strong authentication methods can optionallyprovide confidentiality. Authorization determines whether a principal is allowed to perform anoperation. Red Hat Enterprise Virtualization uses directory services to associate users with roles andprovide authorization accordingly. Authorization is usually performed after the principal has beenauthenticated, 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 RedHat Enterprise Virtualization environment. After the installation is complete, more domains can beadded.

6.2. Local Authent icat ion: Internal Domain

The Red Hat Enterprise Virtualization Manager creates a limited, internal administration domainduring installation. This domain is not the same as an AD or IdM domain, because it exists based ona key in the Red Hat Enterprise Virtualization PostgreSQL database rather than as a directory serviceuser on a directory server. The internal domain is also different from an external domain because theinternal domain will only have one user: the admin@internal user. Taking this approach to initialauthentication allows Red Hat Enterprise Virtualization to be evaluated without requiring a complete,functional directory server, and ensures an administrative account is available to troubleshoot anyissues with external directory services.

The admin@internal user is for the initial configuration of an environment. This includes installingand accepting hosts, adding external AD or IdM authentication domains, and delegatingpermissions to users from external domains.

6.3. Remote Authent icat ion Using GSSAPI

In the context of Red Hat Enterprise Virtualization, remote authentication refers to authentication that

T echnical Guide

4 8

is handled remotely from the Red Hat Enterprise Virtualization Manager. Remote authentication isused 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 theManager be provided with credentials for an account from the RHDS, AD, or IdM directory server forthe 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 thedirectory server using a password. The Manager uses a framework called the Simple Authentication andSecurity 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 tothe user.

Figure 6 .1. GSSAPI Authent icat ion

Chapt er 6 . Direct ory Services

4 9

Chapter 7. Templates and Pools

7.1. Templates and Pools

The Red Hat Enterprise Virtualization environment provides administrators with tools to simplify theprovisioning of virtual machines to users. These are templates and pools. A template is a shortcut thatallows an administrator to quickly create a new virtual machine based on an existing, pre-configuredvirtual machine, bypassing operating system installation and configuration. This is especiallyhelpful for virtual machines that will be used like appliances, for example web server virtualmachines. If an organization uses many instances of a particular web server, an administrator cancreate a virtual machine that will be used as a template, installing an operating system, the webserver, any supporting packages, and applying unique configuration changes. The administratorcan 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 rapidlyprovisioned to users. Permission to use virtual machines in a pool is granted at the pool level; a userwho 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. Becauseusers are assigned virtual machines without regard for which virtual machine in the pool they haveused in the past, pools are not suited for purposes which require data persistence. Virtual machinepools are best suited for scenarios where either user data is stored in a central location and thevirtual 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 astopped state. These are then started on user request.

7.2. Templates

To create a template, an administrator creates and customizes a virtual machine. Desired packagesare installed, customized configurations are applied, the virtual machine is prepared for its intendedpurpose in order to minimize the changes that must be made to it after deployment. An optional butrecommended step before creating a template from a virtual machine is generalization. Generalizationis used to remove details like system user names, passwords, and timezone information that willchange upon deployment. Generalization does not affect customized configurations. Generalizationof Windows and Linux guests in the Red Hat Enterprise Virtualization environment is discussed it theRed Hat Enterprise Virtualization Administration Guide. Red Hat Enterprise Linux guests are generalizedusing sys-unconf ig . 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 configuredvirtual machine disk image to be created. The read only image will form the backing image for allsubsequently created virtual machines that are based on that template. In other words, a template isessentially 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 provisioningtwo 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 allvirtual machines based on the template.

When a template has been created, it can be used as the basis for multiple virtual machines. Virtualmachines are created from a given template using a Thin provisioning method or a Cloneprovisioning method. Virtual machines that are cloned from templates take a complete writable copyof the template base image, sacrificing the space savings of a the thin creation method in exchangefor no longer depending on the presence of the template. Virtual machines that are created from a

T echnical Guide

50

template using the thin method use the read only image from the template as a base image, requiringthat 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 virtualmachine based on a template uses the same base read only image, as well as a copy on write imagethat is unique to the virtual machine. This provides storage savings by limiting the number of timesidentical data is kept in storage. Furthermore, frequent use of the read only backing image can causethe 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 usersas desktops. Users who have been granted permission to access and use virtual machines from apool receive an available virtual machine based on their position in a queue of requests. Virtualmachines in a pool do not allow data persistence; each time a virtual machine is assigned from apool, it is allocated in its base state. This is ideally suited to be used in situations where user data isstored centrally.

Virtual machine pools are created from a template. Each virtual machine in a pool uses the samebacking read only image, and uses a temporary copy on write image to hold changed and newlygenerated data. Virtual machines in a pool are different from other virtual machines in that the copyon write layer that holds user generated and changed data is lost at shutdown. The implication ofthis is that a virtual machine pool requires no more storage than the template that backs it, plus somespace for data generated or changed during use. Virtual machine pools are an efficient way toprovide computing power to users for some tasks without the storage cost of providing each userwith 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 anygiven time. Instead of creating ten virtual machines, one for each help desk employee, a pool offive virtual machines can be created. Help desk employees allocate themselves a virtual machineat the beginning of their shift and return it to the pool at the end.

Chapt er 7 . T emplat es and Pools

51

Chapter 8. Virtual Machine Snapshots

8.1. Snapshots

Snapshots are a storage function that allows an administrator to create a restore point of a virtualmachine's operating system, applications, and data at a certain point in time. Snapshots save thedata currently present in a virtual machine hard disk image as a COW volume and allow for arecovery to the data as it existed at the time the snapshot was taken. A snapshot causes a new COWlayer to be created over the current layer. All write actions performed after a snapshot is taken arewritten to the new COW layer.

It is important to understand that a virtual machine hard disk image is a chain of one or morevolumes. From the perspective of a virtual machine, these volumes appear as a single disk image. Avirtual 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 clearlyrecognizes the temporal nature of snapshots. Each snapshot is created to allow an administrator todiscard unsatisfactory changes made to data after the snapshot is taken. Snapshots provide similarfunctionality 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:

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 systemdata to the point in time that the snapshot was taken.

Deletion, which involves deleting a restoration point that is no longer required.

For task based information about snapshot operations, refer to the Red Hat Enterprise VirtualizationAdministration Guide.

8.2. Live Snapshots in Red Hat Enterprise Virtualizat ion

In version 3.1, Red Hat Enterprise Virtualization introduced support for snapshots of running virtualmachines.

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 whenrunning, paused, or stopped.

When a live snapshot of a virtual machine is initiated, the Manager requests that the SPM host createa new volume for the virtual machine to use. When the new volume is ready, the Manager uses VDSMto communicate with libvirt and qemu on the host running the virtual machine that it should beginusing the new volume for virtual machine write operations. If the virtual machine is able to write to thenew volume, the snapshot operation is considered a success and the virtual machine stops writing tothe previous volume. If the virtual machine is unable to write to the new volume, the snapshot

T echnical Guide

52

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 alive 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 filesystemconsistency 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 writeactions are completed, and then filesystems are frozen before a snapshot is taken. When thesnapshot is complete, and libvirt has switched the virtual machine to the new volume for disk writeactions, the filesystem is thawed, and writes to disk resume.

All live snapshots attempted with quiescing enabled. If the snapshot command fails because there isno 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 bootscleanly with no filesystem check required. Reverting the previous snapshot using an un-quiescedfilesystem requires a filesystem check on boot.

8.3. Snapshot Creat ion

In Red Hat Enterprise Virtualization the initial snapshot for a virtual machine is different fromsubsequent snapshots in that the initial snapshot retains its format, either QCOW2 or RAW. The firstsnapshot for a virtual machine designates existing volumes as a base image. Additional snapshotsare additional COW layers tracking the changes made to the data stored in the image since theprevious snapshot.

In Red Hat Enterprise Virtualization, a guest virtual machine usually interacts with a RAW disk imageunless the image is created as a thinly provisioned image or the user specifically asked for it to beQCOW2. As depicted in Figure 8.1, “ Initial Snapshot Creation” , the creation of a snapshot causes thevolumes that comprise a virtual machine disk image to serve as the base image for all subsequentsnapshots.

Chapt er 8 . Virt ual Machine Snapshot s

53

Figure 8.1. In it ial Snapshot Creat ion

Snapshots taken after the initial snapshot result in the creation of new COW volumes in which datathat is created or changed after the snapshot is taken will be stored. Each new COW layer beginscontaining only COW metadata. Data that is created through virtual machine use and operation aftera snapshot is written to a new COW layer. When a virtual machine is used to modify data that existsin 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 tothe virtual machine.

Figure 8.2. Addit ional Snapshot Creat ion

T echnical Guide

54

8.4 . Snapshot Previews

To select which snapshot a virtual machine disk image will be reverted to, the administrator canpreview all previously created snapshots.

From the available snapshots per guest, the administrator can select a snapshot volume to previewits contents. As depicted in Figure 8.3, “Preview Snapshot” , each snapshot is saved as a COWvolume, 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 theguest data to the state captured in the snapshot. If the administrator commits the preview, the guest isattached to the preview layer.

After a snapshot is previewed, the administrator can select Undo to discard the preview layer of theviewed snapshot. The layer that contains the snapshot itself is preserved despite the preview layerbeing discarded.

Figure 8.3. Preview Snapshot

8.5. Snapshot Delet ion

You can delete individual snapshots or a series of snapshots that are no longer required. Deleting asnapshot removes the ability to restore a virtual machine disk image to that particular restorationpoint. It does not necessarily reclaim the disk space consumed by the snapshot, nor does it deletethe data. The disk space will only be reclaimed if a subsequent snapshot has overwritten the data ofthe deleted snapshot. For example, if the third snapshot out of five snapshots is deleted, theunchanged data in the third snapshot must be preserved on the disk for the fourth and fifthsnapshots 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 frompotential disk space reclamation, deleting a snapshot may also improve the performance of thevirtual machine.

When a snapshot is selected for deletion, QEMU creates a new logical volume of the same size tomerge the snapshot being deleted with the subsequent snapshot. This new logical volume is resizedto accommodate all differences between the two snapshots. The new logical volume can potentiallybe the total combined size of the two snapshots. Once the two snapshots are merged, the subsequent

Chapt er 8 . Virt ual Machine Snapshot s

55

snapshot is renamed and flagged for deletion and is replaced by the new logical volume, whichtakes its name. Both the snapshot originally flagged for deletion and its subsequent snapshot aredeleted, 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 to300 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.

Figure 8.4 . Snapshot Delet ion

The logic used to delete snapshots from running virtual machines is slightly different to that forvirtual machines that are shut down. Live snapshot deletion is handled as an asynchronous blockjob in which VDSM maintains a record of the operation in the recovery file for the virtual machine sothat the job can be tracked even if VDSM is restarted or the virtual machine is shut down during theoperation. Once the operation begins, the snapshot being deleted cannot be previewed or used as arestoration point, even if the operation fails or is interrupted. In operations in which the active layer isto be merged with its parent, the operation is split into a two-stage process during which data iscopied from the active layer to the parent layer, and disk writes are mirrored to both the active layerand the parent. Finally, the job is considered complete once the data in the snapshot being deletedhas been merged with its parent snapshot and VDSM synchronizes the changes throughout theimage chain.

T echnical Guide

56

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 guestbut the device drivers work in different ways.

Emulated devices

Emulated devices, sometimes referred to as virtual devices, exist entirely in software. Emulateddevice 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. Thedevice level instructions directed to and from the emulated device are intercepted andtranslated by the hypervisor. Any device of the same type as that being emulated andrecognized by the Linux kernel is able to be used as the backing source device for theemulated drivers.

Para-virtualiz ed Devices

Para-virtualized devices require the installation of device drivers on the guest operatingsystem providing it with an interface to communicate with the hypervisor on the hostmachine. This interface is used to allow traditionally intensive tasks such as disk I/O to beperformed outside of the virtualized environment. Lowering the overhead inherent invirtualization in this manner is intended to allow guest operating system performance closerto that expected when running directly on physical hardware.

Physically shared devices

Certain hardware platforms allow virtualized guests to directly access various hardwaredevices and components. This process in virtualization is known as passthrough or deviceassignment. Passthrough allows devices to appear and behave as if they were physicallyattached to the guest operating system.

9.2. Stable Device Addresses in Red Hat Enterprise Virtualizat ion

Prior to Red Hat Enterprise Virtualization 3.1, the PCI addresses of virtual machine hardware deviceswere allocated in the order in which the devices were discovered. This meant that if the order in whichvirtual hardware was discovered changed, the PCI address allocation given to the hardware couldalso change.

A change in PCI device addresses is particularly detrimental to virtual machines running Windowsoperating systems. If an important device, like a system hard disk, were to be allocated a different PCIaddress than the one that Windows was expecting, Windows anti-piracy measures could require are-activation of the operating system.

Beginning in Red Hat Enterprise Virtualization 3.1, virtual hardware PCI address allocations arepersisted in the ovirt-engine database.

PCI addresses are allocated by QEMU at virtual machine creation time, and reported to VDSM byl ibvirt . 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 l ibvirt which starts the virtual machine using the PCI device addresses thatwere allocated when the virtual machine was run for the first time.

Chapt er 9 . Hardware Drivers and Devices

57

When a device is removed from a virtual machine, all references to it, including the stable PCIaddress, are also removed. If a device is added to replace the removed device, it is allocated a PCIaddress by QEMU , which is unlikely to be the same as the device it replaced.

9.3. Cent ral 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 CPUsexposed by Hypervisors within a Cluster are of the type selected when the Cluster was initially createdvia Red Hat Enterprise Virtualization Manager. Mixing of virtual CPU types within a Cluster is notpossible.

Each available virtual CPU type has characteristics based on physical CPUs of the same name. Thevirtual 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 forx2APIC. This provides an Advanced Programmable Interrupt Controller (APIC) to better handlehardware interrupts.

9.4 . System Devices

System devices are critical for the guest to run and cannot be removed. Each system device attachedto 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 controllerto guests. The type of network interface controller to expose to a guest is chosen when the guest iscreated but is changeable from the Red Hat Enterprise Virtualization Manager.

The e1000 network interface controller exposes a virtualized Intel PRO/1000 (e1000) to guests.

The virtio network interface controller exposes a para-virtualized network device to guests.

The rtl8139 network interface controller exposes a virtualized Realtek Semiconductor Corp RTL8139 to guests.

Multiple network interface controllers are permitted per guest. Each controller added takes up anavailable PCI slot on the guest.

T echnical Guide

58

9.6. Graphics Devices

Two emulated graphics devices are provided. These devices can be connected to with the SPICEprotocol or with VNC.

The ac9 7 emulates a Cirrus CLGD 5446 PCI VGA card.

The vga emulates a dummy VGA card with BochsVESA extensions (hardware level, including allnon-standard modes).

9.7. Storage Devices

Storage devices and storage pools can use the block device drivers to attach storage devices tovirtualized guests. Note that the storage drivers are not storage devices. The drivers are used toattach a backing storage device, file or storage pool volume to a virtualized guest. The backingstorage device can be any supported type of storage device, file, or storage pool volume.

The IDE driver exposes an emulated block device to guests. The emulated IDE driver can beused to attach any combination of up to four virtualized IDE hard disks or virtualized IDE CD-ROM drives to each virtualized guest. The emulated IDE driver is also used to provide virtualizedDVD-ROM drives.

The Virt IO driver exposes a para-virtualized block device to guests. The para-virtualized blockdriver is a driver for all storage devices supported by the hypervisor attached to the virtualizedguest (except for floppy disk drives, which must be emulated).

9.8. Sound Devices

Two emulated sound devices are available:

The ac9 7 emulates an Intel 82801AA AC97 Audio compatible sound card.

The es1370 emulates an ENSONIQ AudioPCI ES1370 sound card.

9.9. Serial Driver

The para-virtualized serial driver (virtio-serial ) is a bytestream-oriented, character streamdriver. The para-virtualized serial driver provides a simple communication interface between thehost'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. Theballoon driver allows the host to efficiently allocate and memory to the guest and allow free memoryto be allocated to other guests and processes.

Guests using the balloon driver can mark sections of the guest's RAM as not in use (ballooninflation). The hypervisor can free the memory and use the memory for other host processes or otherguests on that host. When the guest requires the freed memory again, the hypervisor can reallocateRAM to the guest (balloon deflation).

Chapt er 9 . Hardware Drivers and Devices

59

Chapter 10. Minimum Requirements and Technical Limitations

10.1. Minimum Requirements and Supported Limits

There are a number of physical and logical limitations which apply to Red Hat EnterpriseVirtualization environments. Environments with configurations outside of these limitations arecurrently not supported.

10.2. Data Center Limitat ions

In a managed virtual environment the highest level container for all resources is the data center. Anumber of limitations apply to the resources which can be contained within each data center.

Table 10.1. data center Limitat ions

Item Limitat ionsNumber of storage domains

A minimum of 2 storage domains per datacenter is recommended. One data storagedomain is required, and an ISO storagedomain per data center is recommended.

Number of hostsA maximum of 200 hosts per data center issupported.

10.3. Cluster Limitat ions

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 amigration domain within which virtual machines can be moved from host to host. To ensure stabilitya 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 CPUscannot co-exist within the same cluster.

Note

Further information about clusters is available in the Red Hat Enterprise VirtualizationAdministration Guide.

10.4 . Storage Domain Limitat ions

Storage domains provide space for the storage of virtual machine disk images and ISO images aswell as the import and export of virtual machines. While many storage domains may be created withina given data center there are a number of limitations and recommendations that apply to eachstorage domain.

T echnical Guide

60

Table 10.2. storage domain Limitat ions

Item Limitat ionsStorage Types

Supported storage types are:Fibre Channel Protocol (FCP)Internet Small Computer System Interface(iSCSI)Network File System (NFS)

All data storage domains within a data centermust be of the same type. The type isspecified as a step in the creation of thestorage domain.

The data storage domain can be any ofFCP, iSCSI, and NFSLegacy FCP or iSCSI export storagedomains from Red Hat EnterpriseVirtualization 2.2 environments can beattached to data centers in Red HatEnterprise Virtualization 3.0. New ISO andexport storage domains must be providedby NFS.

Logical Unit Numbers (LUNs)No more than 300 LUNs are permitted foreach storage domain that is provided byiSCSI or FCP.

Logical Volumes (LVs) In Red Hat Enterprise Virtualization, logicalvolumes represent virtual disks for virtualmachines, templates, and virtual machinesnapshots.

No more than 350 logical volumes arerecommended for each storage domain thatis provided by iSCSI or FCP. If the number oflogical volumes in a given storage domainexceeds this number, splitting availablestorage into separate storage domains withno more than 350 logical volumes each isrecommended.

The root cause of this limitation is the size ofLVM metadata. As the number of logical volumesincreases, the LVM metadata associated withthose logical volumes also increases. When thismetadata exceeds 1 MB in size, the performanceof provisioning operations such as creating newdisks or snapshots decreases, and lvextendoperations for thinly provisioning a logicalvolume when running a QCOW disk take alonger time to run.

Chapt er 1 0 . Minimum Requirement s and T echnical Limit at ions

61

Note

Further information about storage domains is available in the Red Hat Enterprise VirtualizationAdministration Guide.

10.5. Red Hat Enterprise Virtualizat ion Manager Limitat ions

Red Hat Enterprise Virtualization Manager servers must run Red Hat Enterprise Linux 6. A number ofadditional hardware requirements must also be met.

Table 10.3. Red Hat Enterprise Virtualiz at ion Manager Limitat ions

Item Limitat ionsRAM

A minimum of 4 GB of RAM is required.

PCI DevicesAt least one network controller with aminimum bandwidth of 1 Gbps isrecommended.

StorageA minimum of 25 GB of available local diskspace is recommended.

Note

Further information about Red Hat Enterprise Virtualization Manager is available in the RedHat Enterprise Virtualization Installation Guide.

10.6. Hypervisor Requirements

Red Hat Enterprise Virtualization Hypervisors have a number of hardware requirements andsupported limits.

Table 10.4 . Red Hat Enterprise Virtualiz at ion Hypervisor Requirements and SupportedLimits

Item Support Limit

T echnical Guide

62

CPUA minimum of 1 physical CPU is required.Red Hat Enterprise Virtualization supportsthe use of these CPU models in virtualizationhosts:

AMD Opteron G1AMD Opteron G2AMD Opteron G3AMD Opteron G4AMD Opteron G5Intel ConroeIntel PenrynIntel NehalemIntel WestmereIntel HaswellIntel SandyBridge FamilyIBM POWER 8

All CPUs must have support for the Intel® 64or AMD64 CPU extensions, and the AMD-V™or Intel VT® hardware virtualizationextensions enabled. Support for the No eXecute flag (NX) is also required.

RAMA minimum of 2 GB of RAM is recommended.The amount of RAM required for each virtualmachine varies depending on:

guest operating system requirements,guest application requirements, andmemory activity and usage of virtualmachines.

Additionally KVM is able to over-commitphysical RAM for virtual machines. It doesthis by only allocating RAM for virtualmachines as required and shiftingunderutilized virtual machines into swap.

A maximum of 2 TB of RAM is supported.

Storage The minimum supported internal storage for aHypervisor is the total of the following list:

The root partitions require at least 512 MB ofstorage.The configuration partition requires at least 8MB of storage.The recommended minimum size of thelogging partition is 2048 MB.The data partition requires at least 256 MB ofstorage. Use of a smaller data partition mayprevent future upgrades of the Hypervisorfrom the Red Hat Enterprise Virtualization

Item Support Limit


63

Manager. By default all disk space remainingafter allocation of swap space will beallocated to the data partition.The swap partition requires at least 8 MB ofstorage. The recommended size of the swappartition varies depending on both thesystem the Hypervisor is being installedupon and the anticipated level of overcommitfor the environment. Overcommit allows theRed Hat Enterprise Virtualizationenvironment to present more RAM to virtualmachines than is actually physically present.The default overcommit ratio is 0.5.

The recommended size of the swap partitioncan be determined by:

Multiplying the amount of system RAM bythe expected overcommit ratio, andadding2 GB of swap space for systems with 4 GBof RAM or less, or4 GB of swap space for systems withbetween 4 GB and 16 GB of RAM, or8 GB of swap space for systems withbetween 16 GB and 64 GB of RAM, or16 GB of swap space for systems withbetween 64 GB and 256 GB of RAM.

Example 10.1. Calculat ing SwapPart it ion Siz e

For a system with 8 GB of RAM this meansthe formula for determining the amount ofswap space to allocate is:

(8 GB x 0.5) + 4 GB = 8 GB

Please note that these are the minimum storagerequirements for Hypervisor installation. It isrecommended to use the default allocationswhich use more storage space.

PCI DevicesAt least one network controller is requiredwith a recommended minimum bandwidth of1 Gbps.

Item Support Limit

T echnical Guide

64

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 yourprocessor. Ensure that the CPU supports the listed extensions and they are enabled in thesystem 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 virtualizationextensions 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 isshown it is still possible that your processor supports hardware virtualization. In somecircumstances manufacturers disable the virtualization extensions in the BIOS. Where youbelieve this to be the case consult the system's BIOS and the motherboard manualprovided by the manufacturer.

As an additional check, verify that the kvm modules are loaded in the kernel:

# lsmod | grep kvm

If the output includes kvm_intel or kvm_amd then the kvm hardware virtualizationmodules are loaded and your system meets requirements.

Important

The Red Hat Enterprise Virtualization Hypervisor does not support installation on fakeraiddevices. Where a fakeraid device is present it must be reconfigured such that it no longerruns in RAID mode.

1. Access the RAID controller's BIOS and remove all logical drives from it.2. 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 specificdevice in use.

10.7. Guest Requirements and Support Limits


65

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. Virtualiz ed Hardware

Item Limitat ionsCPU

A maximum of 160 virtualized CPUs perguest is supported in Red Hat EnterpriseLinux 6.A maximum of 240 virtualized CPUs perguest is supported in Red Hat EnterpriseLinux 7.

RAM Different guests have different RAMrequirements. The amount of RAM required foreach guest varies based on the requirements ofthe guest operating system and the load underwhich the guest is operating. A number ofsupport limits also apply.

A minimum of 512 MB of virtualized RAM perguest is supported. Creation of guests withless than 512 MB of virtualized RAM whilepossible is not supported.A maximum of 4000 GB of virtualized RAMper 64 bit guest is supported.The supported virtualized RAM maximum for32 bit virtual machines varies depending onthe virtual machine. 32 bit virtual machinesoperating in standard 32 bit mode have asupported virtualized RAM maximum of 4 GBvirtualized RAM per virtual machine.However, note that some virtualizedoperating systems will only use 2 GB of thesupported 4 GB. 32 bit virtual machinesoperating in PAE (Page Address Extension)mode have a supported virtualized RAMmaximum of 64 GB per virtual machine.However, not all virtualized operatingsystems can be configured to use thisamount of virtualized RAM.

PCI devices A maximum of 31 virtualized PCI devices perguest is supported. A number of system devicescount against this limit, some of which aremandatory. Mandatory devices which countagainst the PCI devices limit include the PCIhost bridge, ISA bridge, USB bridge, boardbridge, graphics card, and the IDE or VirtIOblock device.

Storage A maximum of 28 virtualized storage devices perguest is supported, composed of a possible 3IDE and 25 Virtio.

10.8. SPICE Limitat ions

T echnical Guide

66

10.8. SPICE Limitat ions

SPICE currently supports a maximum resolution of 2560x1600 pixels.

10.9. Addit ional References

These additional documentation resources do not form part of the Red Hat Enterprise Virtualizationdocumentation suite. They do however contain useful information for System Administratorsmanaging Red Hat Enterprise Virtualization environments and are available athttps://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 EnterpriseLinux.

Red Hat Enterprise Linux - Virtualization Administration Guide

A guide to the installation, configuration, administration and troubleshooting ofvirtualization technologies in Red Hat Enterprise Linux.


67

https://access.redhat.com/documentation/en-US

Part II. The Command Line Interface

1. Int roduct ion to the Command Line Interface

The Red Hat Enterprise Virtualization suite features a command line interface (CLI). This CLI providesusers with a means to connect to Red Hat Enterprise Virtualization Manager outside of the standardweb interface. The CLI also contains a scripting system, which helps system administrators performperiodic maintenance or repetitive tasks on their virtualization environment via client machines.

T echnical Guide

68

Chapter 11. Using the CLI

11.1. Installing the CLI

Install the Red Hat Enterprise Virtualization CLI to a client machine:

1. Log into the client machine as the root user.

2. Register your system with the Content Delivery Network, entering your Customer Portal username and password when prompted:

# subscription-manager register

3. Find the Red Hat Enterprise Virtualization subscription pool and note down thepool ID.

# subscription-manager list --available

4. Use the pool identifiers located in the previous step to attach the Red Hat Enterprise Virtualization entitlement to the system:

# subscription-manager attach --pool=pool_id

5. Enable the required repository:

# subscription-manager repos --enable=rhel-6-server-rhevm-beta-rpms

6. Install the CLI package and dependencies:

# yum install rhevm-cli

11.2. TLS/SSL Cert ificat ion

The Red Hat Enterprise Virtualization Manager API requires Hypertext Transfer Protocol Secure

(HTTPS) for secure interaction with client software, such as the Manager's SDK and CLIcomponents. This involves a process of obtaining a certificate from the Red Hat EnterpriseVirtualization Manager and importing it into the certificate store of your client.

Important

Obtain your certificate from the Red Hat Enterprise Virtualization Manager using a securenetwork connection.

Procedure 11.1. Obtain ing a Cert if icate

You can obtain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to theclient machine using one of three methods:

[1]

Chapt er 1 1 . Using t he CLI

69

1. Method 1 - Use a command line tool to download the certificate from the Manager. Examplesof command line tools include cURL and Wget , both of which are available on multipleplatforms.

a. If using cURL:

$ curl -o rhevm.cer http://[rhevm-server]/ca.crt

b. If using Wget :

$ wget -O rhevm.cer http://[rhevm-server]/ca.crt

2. 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 thebrowser's keystore.

a. If the browser downloads the cert if icate: save the file as rhevm.cer.

If the browser imports the cert if icate: export it from the browser's certificationoptions and save it as rhevm.cer.

3. Method 3 - Log in to the Manager, export the certificate from the truststore and copy it to yourclient machine.

a. Log in to the Manager as the root user.

b. 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 called rhevm.cer.

c. Copy the certificate to the client machine using the scp command:

$ scp rhevm.cer [username]@[client-machine]:[directory]

Each of these methods results in a certificate file named rhevm.cer on your client machine. An APIuser imports this file into the certificate store of the client.

Procedure 11.2. Import ing a Cert if icate 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 NetworkSecurity Services (NSS) or Java KeyStore (JKS), see your client documentation for moreinformation on importing a certificate.

11.3. .rhevmshellrc Configurat ion

T echnical Guide

70

The .rhevmshellrc is a configuration file that is automatically created and populated when theuser first connects to the rhevm-shell . It allows users to configure options for connecting to theRed 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 Descript ionautoconnect 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 Descript ionusername 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 cantoggle filtering off. The status is either True or False.

session_timeout

integer Specifies timeout (in minutes) for authentication session. Must bea 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 Virtualizationenvironments.


71

The URL, user name, certificate authority file, and password for connecting to the Red Hat EnterpriseVirtualization Manager can be configured in the .rhevmshellrc file. The rhevm-shell commanduses the parameters in this file to connect to the Manager, so that the user does not need to specifyoptions each time.

Alternatively, users can connect automatically to Red Hat Enterprise Virtualization Manager using thefollowing 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 CLIconnects 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 HatEnterprise 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 URLfor 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 promptedby the shell. Instead of specifying the certificate you can use the '--insecure' option to connectwithout certification, however this is not recommended as it may allow man-in-the-middle(MITM) attackers to spoof the identity of the server.

Opt ions 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.

T echnical Guide

72

-K KEY_FILE, - -key- f ile= KEY_FILE

Specify key file.

-C CERT_FILE, - -cert - f ile= CERT_FILE

Specify certificate file.

-A CA_FILE, - -ca- f ile= CA_FILE

Specify server Certificate Authority file.

- I , - - insecure

Allow the CLI to connect via SSL without certification. Use this option with caution becauseit can allow man-in-the-middle (MITM) attackers to spoof the identity of the server.

-F, - - f i lter

Enable filtering based upon user permissions.

-P PORT, - -port= PORT

Specify port.

-T TIMEOUT, - - t imeout= TIMEOUT

Specify timeout.

-c, - -connect

Automatically connect.

-e, - -extended-prompt

Enables the extended prompt option for the shell. This option displays the hostname of theenvironment 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 "commandresource;command resource" and prints the output to STDIO.

- f FILE, - - f i le= 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 VirtualizationManager from within the shell, where the --password option can be used.

11.5. Interact ing with the CLI


73

The CLI is an interactive shell for controlling your Red Hat Enterprise Virtualization environment fromthe command line. Type the required command and any additional parameters.

Example 11.1. Entering a shell command

[RHEVM shell (connected)]# show vm --name desktop_vms

To support the construction of command and parameter combinations, the CLI includes thefunctionality to list and automatically complete commands and parameters by pressing the TAB keytwice, similar to the bash shell.

Example 11.2. List ing and automat ic complet ion of commands and parameters

Press double TAB at a blank prompt to list all available commands.

[RHEVM shell (connected)]# TAB TABEOF 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 thecommand. For the show, this lists all resources.

[RHEVM shell (connected)]# show TAB TABbrick datacenter event group nicquota statistic template vmpool cdromdisk file host permission rolestoragedomain user cluster domain glustervolumenetwork permit snapshot tag vm

Double TAB also completes commands and parameters.

[RHEVM shell (connected)]# show vm TAB 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 theprefix.

If the incomplete parameter matches multiple parameters, double TAB lists them.

[RHEVM shell (connected)]# show vTAB TABvmpool vm

The CLI provides functions to run Linux commands using either the shell command or the bang (! )character.

T echnical Guide

74

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 . Pip ing CLI commands

Pipe CLI data to a Linux shell command:

[RHEVM shell (connected)]# list vms --show-all | grep "Example"name : Example1name : Example2name : ExampleEngineeringdescription : An Example descriptionname : 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 commandvia the help command.

Example 11.5. Using online help for the show command

[RHEVM shell (connected)]# help show

You can also connect to the Manager from the Linux shell to execute specific commands, in the formof "command resource" and print them to STDIO

Example 11.6 . Connect ing to the Manager to execute specif ic 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


75

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. Collect ions

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.

[1] HTTPS is d escrib ed in RFC 28 18 HTTP Over TLS.

T echnical Guide

76

http://tools.ietf.org/html/rfc2818

Chapter 12. Quick Start Example

12.1. Creat ing a Basic Virtualizat ion Environment with the CLI

This chapter provides an example to demonstrate the CLI's ability to add a virtual machine within abasic 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 clientmachine; and,

An ISO file containing a desired virtual machine operating system to install. This chapter usesRed Hat Enterprise Linux Server 6 for our installation ISO example.

Note

Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) foreach resource. Identifier codes in this example might appear different to the identifier codes inyour Red Hat Enterprise Virtualization environment.

Procedure 12.1. Quick Start Example

1. 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

2. List all data centers in the environment. This example uses the Default data center.

[RHEVM shell (connected)]# list datacenters

id : 5e3b55d8-c585-11e1-a7df-001a4a400e0dname : Defaultdescription: The default Data Center

3. List all host clusters and note down the relevant cluster ID or cluster name, which will berequired when adding the host and for creating a virtual machine. This example uses the Default cluster to group resources in your Red Hat Enterprise Virtualization environment.

[RHEVM shell (connected)]# list clusters

id : 99408929-82cf-4dc7-a532-9d998063fa95name : Defaultdescription: The default server cluster

Chapt er 1 2 . Quick St art Example

77

4. List all CPU profiles and note down the relevant CPU profile ID, which will be required whencreating a virtual machine. This example uses the Default CPU profile.

[RHEVM shell (connected)]# list cpuprofiles

id : 0000001a-001a-001a-001a-00000000035ename : Default

5. List all logical networks with the show-all option to view the details of the logical networksin the environment. Red Hat Enterprise Virtualization Manager creates a default logicalnetwork called rhevm for management traffic. This example uses the rhevm logical networkon the Default data center.

[RHEVM shell (connected)]# list networks --show-all

id : 00000000-0000-0000-0000-000000000009name : rhevmdescription : Management Networkdata_center-id: 5e3b55d8-c585-11e1-a7df-001a4a400e0dmtu : 0required : Truestatus-state : operationalstp : Falseusages-usage : VM

Note the data_center-id value matches the id for the Default data center.

6. 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!

7. Add an NFS share as a data storage domain by creating, attaching, and activating the NFSshare. An NFS data storage domain is an exported NFS share attached to a data center. Itprovides storage for virtual machines. Ensure to substitute storage-address and storage-path with the correct values for the NFS server.

a. 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

b. Verify that the created storage domain is available. The creation process might takeseveral minutes. Once the status-state is unattached , you can proceed to thenext step.

[RHEVM shell (connected)]# show storagedomain --name DataStorageid : xxxxname : DataStorage

T echnical Guide

78

master : Falsestatus-state : unattached...

c. Attach the data storage domain to the data center. The storage domain is activatedautomatically.

[RHEVM shell (connected)] # add storagedomain --datacenter-identifier Default --name DataStorage

Note

If the storage domain is not activated, activate it manually using the followingcommand:

[RHEVM shell (connected)]# action storagedomain DataStorage --datacenter-identifier Default activate

8. Add an NFS share as the ISO storage domain by creating, attaching, and activating the NFSshare. An NFS ISO storage domain is an exported NFS share attached to a data center. Itprovides storage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Ensure tosubstitute storage-address and storage-path with the correct values for the NFS server.

a. 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

b. Verify that the created storage domain is available. The creation process might take awhile. Once the status-state is unattached , you can proceed to the next step.

[RHEVM shell (connected)]# show storagedomain --name ISOStorageid : xxxxname : ISOStoragemaster : Falsestatus-state : unattached...

c. Attach the ISO storage domain to the data center. The storage domain is activatedautomatically.

[RHEVM shell (connected)] # add storagedomain --datacenter-identifier Default --name ISOStorage

9. Create a new virtual machine.

[RHEVM shell (connected)]# add vm --name MyVM --cluster-name Default --template-name Blank --memory 536870912 --os-boot


79

boot.dev=hd --cpu_profile-id 0000001a-001a-001a-001a-00000000035e

10. Use the add nic command to add a new network interface. Add the vm-identifier optionto attach the interface as a sub-resource of MyVM and a network-name option to connect tothe rhevm network.

[RHEVM shell (connected)]# add nic --vm-identifier MyVM --name nic1 --network-name rhevm --bootable true

11. Use the add disk command to add a new virtual hard disk. Add the vm-identifieroption to attach the disk as a sub-resource of MyVM.

[RHEVM shell (connected)]# add disk --vm-identifier MyVM --provisioned_size 8589934592 --interface virtio --format cow --storage_domains-storage_domain storage_domain.name=DataStorage

12. On the Manager, upload ISO images to the ISOStorage domain for the virtual machines touse. Red Hat Enterprise Virtualization Manager provides an ISO uploader tool that ensuresimages 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.isoPlease provide the REST API password for the admin@internal oVirt Engine user (CTRL+D to abort):

13. In the CLI shell, use the list files command to list the available ISO files in the storagedomain.

[RHEVM shell (connected)]# list files --storagedomain-identifier ISOStorage

14. Add a virtual CD-ROM drive for your installation media. Add the vm-identifier option toattach the CD-ROM as a sub-resource of MyVM.

[RHEVM shell (connected)]# add cdrom --vm-identifier MyVM --file-id rhel-server-6.6-x86_64-dvd.iso

15. Start the virtual machine. The virtual environment is complete and the virtual machinecontains all necessary components to function.

[RHEVM shell (connected)]# action vm MyVM start --vm-os-boot boot.dev=cdrom

Note the use of the vm-os-boot option. This changes the boot device to cdrom for thisinitial boot session. After installation, the virtual machine restarts and restores the boot deviceback to hd .

16. Use the list events with an additional query option to display specific event types. The start action for the virtual machine adds several entries in the events collection.

T echnical Guide

80

[RHEVM shell (connected)]# list events --query "type=153"

id : 105description: MyVM was started by admin (Host: MyHost).

The "type=153" query refers to events where a user starts a virtual machine.

17. Use the show event command to display comprehensive details of an event. This commandcan be used to show events by type, name, and id .

[RHEVM shell (connected)]# show event --id '60'

id : 60description : New Tag foo was created by [email protected] : 432correlation_id: 3e4d4350custom_id : -1flood_rate : 30origin : oVirtseverity : normaltime : 2013-07-03 10:57:43.257000+03:00user-id : fdfc627c-d875-11e0-90f0-83df133b58cc

18. Access your virtual machine with the console command.

[RHEVM shell (connected)]# console MyVM

Important

Ensure your client machine has a console application installed to match the virtualmachine's display-type. Protocols available include SPICE (default) and VNC .


81

Chapter 13. Commands

13.1. Connect ing 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 VirtualizationManager can be configured in the .rhevmshellrc file. The connect command uses theparameters in this file to connect to the Manager, so that the user does not need to specify optionseach 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. Opt ions for connect

Opt ion Descript ion 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 userattempting access to the Red Hat Enterprise VirtualizationManager. This takes the form of [username]@[domain].

Yes

--password The password for the user attempting access to the Red HatEnterprise 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 isused

--insecure Allow the CLI to connect via SSL without certification. Usethis option with caution because it can allow man-in-the-middle (MITM) attackers to spoof the identity of the server.

Yes, butonly if nocertificateauthorityisprovided

--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 conf igured

T echnical Guide

82

[RHEVM shell (disconnected)]# connect --url "https://rhevm.example.com/api" --username "[email protected]" --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 withoutcertification, 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 Collect ion (list )

Use the list command to display all resources of a specific type. Lists also include optional searchqueries to filter results.

Syntax

list [collection] [options]

Table 13.2. list standard opt ions

Chapt er 1 3. Commands

83

Opt ion Descript ion--show-all Displays all non-empty properties for each listed resource.

Without this option, only the id , name and descriptionproperties display.

--query [QUERY] Filters the list using a server-side query based upon Red HatEnterprise 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 opt ions

T echnical Guide

84

Opt ion Descript ion--id [UUID] Identify resource with the resource's UUID value.--name [NAME] Identify resource with the name value.

Note


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


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)


85

13.2.4 . Update a Resource (update)

Use the update command to modify an existing resource.

Syntax

update [resource] [id|name] [options]

Note


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 opt ions

Opt ion Descript ion--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. Thisaction applies only to datacenter and vm resources.

Note


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

T echnical Guide

86

Force remove virtual machine:

[RHEVM shell (connected)]# remove vm RHEL6-Server --force

13.2.6. Perform Act ion on a Resource (act ion)

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-ident ifier)

Certain resources act as sub-resources of other resources. This means there is a dependentrelationship 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 aparent resource.

Example 13.9 . Examples for creat ing 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:


87

[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 theRHEL6-Server virtual machine.

13.3. Other Commands

13.3.1. End of File (EOF)

Use the EOF command to leave the CLI shell using a Ctrl+D sequence.

Syntax

EOF

Example 13.10. Example for EOF

Leave the CLI shell:

[RHEVM shell (connected)]# EOF

13.3.2. List System Capabilit ies (capabilit ies)

Use the capabilties --features command to list all version capabilities and new features of thecurrent 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 Sensitivitydescription : Ability to specify whether a search query should ignore case, by providing a URL parameterurl-parameters_set-parameter-name : case_sensitiveurl-parameters_set-parameter-context: matrixurl-parameters_set-parameter-type : boolean:

13.3.3. Clear the Screen (clear)

T echnical Guide

88

Use the clear command to clear the CLI screen.

Syntax

clear

Example 13.12. Example for clear

Clear the screen:

[RHEVM shell (connected)]# clear

13.3.4 . Connect to VM (console)

Use the console command to open a graphical console to a virtual machine. This command openseither 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 shellcommand 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.6. Exit from the CLI (exit )


89

Use the exit command to leave a CLI.

Syntax

exit

Example 13.15. Example for exit

Leave the CLI:

[RHEVM shell (connected)]# exit

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 ofcommands 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

T echnical Guide

90

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 Informat ion (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.1sdk version : 3.1.0.4cli version : 3.1.0.6python version : 2.7.3.final.0

entry point : https://www.example.com:8443/api


91

13.3.11. T est Connect ion (ping)

Use the ping command tests the connection to your Red Hat Enterprise Virtualization Manager. Thecommand retrieves a remote resource and ensures the URL, user name and password for theconnection 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 withperforming file management tasks in conjunction with the Red Hat Enterprise Virtualization Managershell.

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/.

T echnical Guide

92

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 : 1hosts-total : 2storage_domains-active: 2storage_domains-total : 3users-active : 1users-total : 1vms-active : 1vms-total : 1


93

Chapter 14. Resource Types

14.1. brick

The brick resource type groups all Gluster bricks in a Red Hat Enterprise Virtualizationenvironment.

Table 14 .1. G luster brick parameters

Name Type Descript ion Required

UserCreatable

UserUpdatable

--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 replicatedvolume.

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. Addit ional command opt ions

Opt ion Descript ion--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. Creat ing 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 EnterpriseVirtualization environment.

Table 14 .3. CD-ROM parameters


UserCreatable

UserUpdatable

--file-id string Defines the file name of the ISO that resides onan ISO storage domain.

Yes Yes Yes

T echnical Guide

94

Example 14 .2. Creat ing 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. Updat ing 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 . Delet ing 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 Virtualizationenvironment.

Table 14 .4 . Cluster parameters


UserCreatable

UserUpdatable

--cpu-id string A server CPU reference that defines the CPU typeall 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. Forexample, for Red Hat Enterprise Virtualization3.6, the major version is 3.

Yes Yes Yes

--version-minor

int The minor version number of the cluster. Forexample, for Red Hat Enterprise Virtualization3.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 hostwithin 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

Chapt er 1 4 . Resource T ypes

95

--memory_policy-overcommit-percent

double

The percentage of host memory allowed in usebefore a host can no longer run any more virtualmachines. Virtual machines can use more thanthe available host memory due to memorysharing under KSM. Recommended valuesinclude 100 (None), 150 (Server Load) and 200(Desktop Load).

No Yes Yes

--memory_policy-transparent_hugepages-enabled

Boolean

Defines the enabled status of TransparentHugepages. 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 beoverloaded before the scheduler starts andmoves the load to another host.

No Yes Yes

--scheduling_policy-thresholds-high

int Controls the highest CPU usage percentage thehost can have before being consideredoverloaded.

No Yes Yes

--scheduling_policy-thresholds-low

int Controls the lowest CPU usage percentage thehost can have before being consideredunderutilized.

No Yes Yes

--threads_as_cores

Boolean

Hosts treat threads as cores, allowing hosts torun virtual machines with a total number ofprocessor cores greater than the number ofcores in the host. The status is either true or false.

No No No

--trusted_service

Boolean

Defines whether an OpenAttestation server isused 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 theexpected HTTP header is returned. Useful forlong-running tasks that would otherwise returnas successful before the task is completed.

No No No

--correlation_id

string A tagging identifier of an action for cross-systemlogging. If the client does not define the identifier,one will be generated.

No Yes No


UserCreatable

UserUpdatable

T echnical Guide

96

Example 14 .5. Creat ing 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 . Updat ing a cluster

[RHEVM shell (connected)]# update cluster Engineering --name Finance

Example 14 .7. Delet ing a cluster

[RHEVM shell (connected)]# remove cluster Engineering

14.4 . datacenter

The datacenter resource type groups all data center resources in a Red Hat EnterpriseVirtualization environment.

Table 14 .5. Data Center Parameters


UserCreatable

UserUpdatable

--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. Forexample, for Red Hat Enterprise Virtualization3.6, the major version is 3.

Yes Yes Yes

--version-minor

int The minor version number of the data center. Forexample, for Red Hat Enterprise Virtualization3.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



No No No

--correlation_id


No Yes No


97

Example 14 .8. Creat ing a new data center

[RHEVM shell (connected)]# add datacenter --name Boston --storage-type nfs --version-major 3 --version-minor 2

Example 14 .9 . Updat ing a data center

[RHEVM shell (connected)]# update datacenter Boston --name India

Example 14 .10. Delet ing a data center

[RHEVM shell (connected)]# remove datacenter Boston

14.5. disk

The disk resource type groups all virtual hard disk resources in a Red Hat Enterprise Virtualizationenvironment.

Table 14 .6 . Disk parameters


UserCreatable

UserUpdatable

--provisioned_size

int The reserved storage space for the disk. Thisspace is preallocated for the disk to use, even ifthe 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 smallperformance overhead. Raw (raw) does notallow snapshots, but offers improvedperformance.

Yes Yes Yes

--size int The actual size of the disk. No Yes Yes--sparse Bool

eantrue if the physical storage for the disk shouldnot 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 virtualmachine to be paused and, instead, disk errorsshould be propagated to the guest OS.

No Yes Yes

T echnical Guide

98

--wipe_after_delete

boolean

true if the underlying physical storage for thedisk should be zeroed when the disk is deleted.This increases security but is a more intensiveoperation and may prolong delete times.

No Yes Yes

--storage_domains-storage_domain

collection

Defines a specific storage domain for the disk. No Yes No


UserCreatable

UserUpdatable

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 Descript ionstorage_domain.id|name

string A reference to a storage domain for the disk.

The following table lists additional disk options for resource-based commands.


Opt ion Descript ion--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. Creat ing a new disk

[RHEVM shell (connected)]# add disk --name MyDisk --provisioned_size 8589934592 --interface virtio --format cow

Example 14 .12. Updat ing a storage domain

[RHEVM shell (connected)]# update disk MyDisk --shareable true

Example 14 .13. Delet ing a storage domain

[RHEVM shell (connected)]# remove disk MyDisk

The following table lists actions for a virtual machine disk resource.

Table 14 .9 . Virtual machine d isk act ions


99

Act ion Descript ionactivate 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 HatEnterprise Virtualization environment.

Table 14 .10. G luster vo lume parameters


UserCreatable

UserUpdatable

--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 Glusterbricks to add and manage. This parameterreferences a collection of brick details. Specify atleast one brick but list multiple bricks-brickparameters for multiple bricks. See below forcollection details.

Yes Yes No

--transport_types

collection

A reference to available transport methods for theGluster volume. See below for collection details.

No Yes No

--replica_count

integer

Defines the file replication count for a replicatedvolume.

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. Seebelow 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 Descript ionbrick.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 followingtable.

Table 14 .12. t ransport_types parameters

T echnical Guide

100

Name Type Descript iontransport_type string Defines a transport type to use. Specify multiple

transport_type parameters for more than one type. Choosefrom TCP and RDMA.

The --options-option parameter is a collection that uses the sub-parameters in the followingtable.

Table 14 .13. opt ions-opt ion parameters

Name Type Descript ionoption.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 . Addit ional command opt ions

Opt ion Descript ion--cluster-identifier Adds the Gluster volume to a cluster as a sub-resource.

Example 14 .14 . Creat ing a G luster vo lume 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. Delet ing a G luster vo lume

[RHEVM shell (connected)]# remove glustervolume --cluster-identifier Default --name GlusterVol1

The following table lists actions for a Gluster volume resource.

Table 14 .15. G luster vo lume act ions

Act ion Descript ionstart 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 Virtualizationenvironment.


101

Table 14 .16 . Group parameters


UserCreatable

UserUpdatable

--name string The name of the group, usually the full grouppath within the identity directory service.

No No No

Example 14 .16 . Creat ing 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


UserCreatable

UserUpdatable

--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 VDSMdaemon running on the host.

No Yes Yes

--storage_manager-priority

int Sets the priority of host order for storage poolmanager (SPM).

No Yes Yes

--power_management-type

string The type of power management device in thehost.

No Yes Yes

--power_management-enabled

boolean

Indicates whether power managementconfiguration is enabled or disabled.

No Yes Yes

--power_management-address

string The host name or IP address of the powermanagement device.

No Yes Yes

--power_management-user_name

string A valid user name for power management. No Yes Yes

T echnical Guide

102

--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 VDSMinstallation.

No Yes No


UserCreatable

UserUpdatable

The --power_management-options-option parameter is a collection that uses the sub-parameters in the following table.

Table 14 .18. - -power_management -opt ions-opt ion parameters

Name Type Descript ionoption.name string Power management option name.option.value string Power management option value.

Example 14 .17. Creat ing a new host

[RHEVM shell (connected)]# add host --name Host1 --address host1.example.com --root_password p@55w0rd! --cluster-name Default

Example 14 .18. Updat ing a host

[RHEVM shell (connected)]# update host Host1 --name Host2

Example 14 .19 . Delet ing a host

[RHEVM shell (connected)]# remove host Host1

The following table lists actions for a host resource.

Table 14 .19 . Host act ions

Act ion Descript ionactivate Activate a host.approve Approve a host.commitnetconfig Save the network configuration.deactivate Deactivate a host.fence Fence a host.


103

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.

Act ion Descript ion

The following table lists additional options for the fence action.

Table 14 .20. Fencing opt ions

Opt ion Descript ionmanual Manually fence the host. Use this action to confirm to the

Manager that the host became non-responsive and was manuallyrebooted.

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. Conf irming 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 EnterpriseVirtualization environment.

Table 14 .21. Logical network parameters


UserCreatable

UserUpdatable

--data_center-id|name

string A reference to the data center for a logicalnetwork.

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 displaycommunication usage. Set to either true or false.

No Yes Yes

T echnical Guide

104

--stp boolean

Set to true if Spanning Tree Protocol is enabledon this network.

No Yes Yes

--mtu int Sets a user-defined value for the maximumtransmission unit of the logical network.

No Yes Yes

--usages-usage

collection

Defines usage parameters for the logicalnetwork.

No No Yes


UserCreatable

UserUpdatable

The --usages-usage parameter is a collection that uses the sub-parameters in the following table.

Table 14 .22. usages-usage parameters

Name Type Descript ionusage string Usage types for the network. Options include VM and DISPLAY .

The following table lists additional network options for resource-based commands.


Opt ion Descript ion--cluster-identifier Adds the network to a cluster as a sub-resource.

Example 14 .21. Creat ing a new network

[RHEVM shell (connected)]# add network --name WebNetwork --datacenter-name Default --cluster-identifier Default

Example 14 .22. Updat ing a network

[RHEVM shell (connected)]# update network WebNetwork --name DataNetwork

Example 14 .23. Delet ing a network

[RHEVM shell (connected)]# remove network WebNetwork

14.10. nic

The nic resource type groups network interface resources in a Red Hat Enterprise Virtualizationenvironment. These resources acts as sub-resources for both host and vm resources but are defineddifferently for each. This section contains two tables with parameters for each.

Table 14 .24 . Host network in terface parameters


105


UserCreatable

UserUpdatable

--network-id|name

string A reference to the network, if any, that theinterface 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 forma bonded interface.

No Yes Yes

--bonding-options-option

collection

A list of options for a bonded interface. Eachoption contains property name and valueattributes.

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 thehost 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 in terface parameters


UserCreatable

UserUpdatable

--network-id|name

string A reference to the network, if any, that theinterface 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 thefollowing table.

Table 14 .26 . - -bonding-slaves-host_nic

Name Type Descript ionhost_nic.id|name

string A reference to another host NIC to bond.

T echnical Guide

106

The --bonding-options-option parameter is a collection that uses the sub-parameters in thefollowing table.

Table 14 .27. - -bonding-opt ions-opt ion

Name Type Descript ionoption.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 Descript ionnetwork.id string A reference to the network to mirror.

The following table lists additional NIC options for resource-based commands.

Table 14 .29 . Addit ional command opt ions

Opt ion Descript ion--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 . Creat ing a new network in terface on a virtual machine

[RHEVM shell (connected)]# add nic --vm-identifier MyVM1 --name eth0 --network-name MyNetwork

Example 14 .25. Updat ing a network in terface on a virtual machine

[RHEVM shell (connected)]# update nic eth0 --vm-identifier MyVM1 --ip-address 10.5.68.123

Example 14 .26 . Delet ing a network in terface on a virtual machine

[RHEVM shell (connected)]# remove nic eth0 --vm-identifier MyVM1

Example 14 .27. Conf iguring 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 in terface


107

[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 act ions

Act ion Descript ionattach 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 act ions

Act ion Descript ionactivate 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 EnterpriseVirtualization environment.

Table 14 .32. Permission parameters


UserCreatable

UserUpdatable

--user-id , --group-id

string A reference to the user or group using thepermission.

Yes Yes No

--role-id string A reference to a role to assign for the permission. Yes Yes No--expect '201-

created'


No No No

The following table lists additional permission options for resource-based commands.


Opt ion Descript ion--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.

T echnical Guide

108

--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.

Opt ion Descript ion

Example 14 .29 . Creat ing 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 EnterpriseVirtualization environment.

Table 14 .34 . Permission parameters


UserCreatable

UserUpdatable

--id string A reference to the permit to add. Yes Yes No

The following table lists additional permit options for resource-based commands.


Opt ion Descript ion--role-identifier Adds the permit to a role.

Example 14 .30. Creat ing 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 Virtualizationenvironment.

Table 14 .36 . Quota parameters


109


UserCreatable

UserUpdatable

--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 Virtualizationenvironment.

Table 14 .37. Role parameters


UserCreatable

UserUpdatable

--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 permitresource 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 followingtable.

Table 14 .38. - -permits-permit parameters

Name Type Descript ionpermit.id string A reference to a permit to add to the role's permits.

Example 14 .31. Creat ing a new ro le

[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 EnterpriseVirtualization environment.

Table 14 .39 . Snapshot parameters

T echnical Guide

110


UserCreatable

UserUpdatable

--description

string A description for the snapshot. Yes Yes No

The following table lists additional snapshot options for resource-based commands.

Table 14 .4 0. Addit ional command opt ions

Opt ion Descript ion--vm-identifier Adds the disk to a vm as a sub-resource.

Example 14 .32. Creat ing a new snapshot

[RHEVM shell (connected)]# add snapshot --vm-identifier MyVM --description 'My Snapshot'


[RHEVM shell (connected)]# remove snapshot [snapshot_id]

The following table lists actions for a virtual machine snapshot resource.

Table 14 .4 1. Virtual machine snapshot act ions

Act ion Descript ionrestore Restore a snapshot.

14.16. stat ist ic

The statistic resource type groups statistics for resources in a Red Hat Enterprise Virtualizationenvironment. Resource statistics are listed based on their resource identifier.

Table 14 .4 2. stat ist ic resource ident if iers

Opt ion Descript ion--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 glustervolume.

--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.


111

--numanode-identifier The resource identifier to view statistics for the specified NUMAnode.

--step-identifier The resource identifier to view statistics for the specified step.--storagedomain-identifier

The resource identifier to view statistics for the specified storagedomain.

--vm-identifier The resource identifier to view statistics for the specified virtualmachine.

Opt ion Descript ion

View the collection of statistics for each resource by using the list command and the relevantresource identifier. The following example provides a list of the available statistics for the specifiedhost:

[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 resourceidentifier to view further information on the specified statistic. The following example shows the detailsof the specified statistic for the host:

[RHEVM shell (connected)]# show statistic statistic_name|id --host-identifier Host name|id

14.17. storageconnect ion

The storageconnection resource type allows you to add, edit, and delete storage connections.

Table 14 .4 3. Storage connect ion parameters


UserCreatable

UserUpdatable

--address string The hostname or IP address of the storagedomain.

Yes(NFSandiSCSIonly)

Yes Yes

--correlation_id

string A tagging identifier for the storage connection. No No Yes



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 clientwill attempt to complete a request.

No Yes Yes

T echnical Guide

112

--nfs_timeo integer

The amount of time, in deciseconds, the NFSclient 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 aniSCSI storage domain.

No Yes Yes

--path string The mounted file path of the storage domain. Thepath cannot be updated to one already used bya storage connection.

Yes(NFS,local,andPosixFSonly)

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 thePosixFS share.

Yes(PosixFSonly)

Yes Yes


UserCreatable

UserUpdatable

Example 14 .34 . Creat ing a new storage connect ion

[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 EnterpriseVirtualization environment.

Table 14 .4 4 . Storage domain parameters


UserCreatable

UserUpdatable

--name string The name of the storage domain. No Yes Yes--format Boole

anThe metadata format for the data center,including v1, v2 or v3.

Yes Yes No


113

--host-id|name

string A reference to the host from which this storagedomain should be initialized. The only restrictionon this host is that it should have access to thephysical storage specified.

Yes Yes No

--storage-address

string The IP address or hostname of the storagedevice.

Yes Yes No

--storage-logical_unit

collection

The logical unit information of the storagedevice.

Seebelow

Yes No

--storage-mount_options

string The options for mounting the storage domain. Seebelow

Yes No

--storage-override_luns

Boolean

Defines whether to override the logical unitnumber. The status is either true or false.

Seebelow

Yes No

--storage-path

string The path on the storage device to use for thestorage domain.

Seebelow

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 storagedomain.

Seebelow

Yes No

--type string The type of storage domain, including data, iso and export.

Yes Yes No


UserCreatable

UserUpdatable

The --storage-logical_unit parameter is a collection that requires all sub-parameters in thefollowing table.

Table 14 .4 5. storage- logical_unit parameters

Name Type Descript ionlogical_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.

T echnical Guide

114

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.

Name Type Descript ion

Use the following parameters depending on storage-type.

Table 14 .4 6 . Storage type parameters

Type Parametersnfs --storage-address, --storage-pathiscsi or fcp --storage-address, --storage-logical_unit, --storage-

override_luns

glusterfs --storage-address, --storage-path, --storage-vfs_typelocal --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 .4 7. Addit ional command opt ions

Opt ion Descript ion--datacenter-identifier Adds the storage domain to a datacenter as a sub-resource.

Example 14 .35. Creat ing a new storage domain

[RHEVM shell (connected)]# add storagedomain --name DataStorage --datacenter-name Default -type data

Example 14 .36 . Adding a g luster 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. Updat ing a storage domain

[RHEVM shell (connected)]# update storagedomain DataStorage --name DataStorageOld


[RHEVM shell (connected)]# remove storagedomain DataStorage


115

The following table lists actions for a storage domain resource.

Table 14 .4 8. Storage domain act ions

Act ion Descript ionactivate Activate a storage domain on a data center.deactivate Deactivate a storage domain on a data center.

14.19. t ag

The tag resource type groups all tags in a Red Hat Enterprise Virtualization environment.

Table 14 .4 9 . Tag parameters


UserCreatable

UserUpdatable

--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 isattached.

Yes Yes Yes

Example 14 .39 . Creat ing a new tag

[RHEVM shell (connected)]# add tag --name MyTag --description "A virtual machine tag" --parent MyParentTag

14.20. t emplate

The template resource type groups all virtual machine templates in a Red Hat EnterpriseVirtualization environment. Only --vm-id|name and --name are required parameters. If theoptional parameters are not specified, the template will inherit the settings from the virtual machineused to make the template.

Table 14 .50. Template parameters


UserCreatable

UserUpdatable

--vm-id|name

string A reference to the virtual machine used as thebasis 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 virtualmachine template.

No Yes Yes

T echnical Guide

116

--high_availability-enabled

Boolean

Set to true to enable high availability for thevirtual machine template.

No Yes Yes

--os-cmdline

string A kernel command line parameter string to beused with the defined kernel. This optionsupports booting a Linux kernel directly ratherthan 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 eachvirtual machine template's high availability.

No Yes Yes

--timezone string The Sysprep timezone setting for a Windowsvirtual machine template. Specify formats suchas GMT+00:00 .

No Yes Yes

--domain-name

string The domain name of the virtual machinetemplate.

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 arestateless. A stateless virtual machine contains asnapshot of its disk image taken at boot andremoved at shutdown. This means state changesdo not persist after a reboot.

No Yes Yes

--delete_protected

boolean

Set to true to make it impossible to delete avirtual machine created from this template.

No Yes Yes

--sso-methods-method

collection

Defines the single sign-on method used. Forexample, --sso-methods-method method.id=GUEST_AGENT .

No Yes Yes

--rng_device-rate-bytes

int Specifies how many bytes are permitted to beconsumed per period.

No Yes Yes

--rng_device-rate-period

int Specifies the duration of a period inmilliseconds. 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 devicefeature.

No Yes Yes

--placement_policy-affinity

string The migration affinity for each virtual machinecreated 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


UserCreatable

UserUpdatable


117

--custom_properties-custom_property

collection

A set of user-defined environment variablespassed as parameters to custom scripts.

No Yes Yes

--os-type string The operating system type for the virtual machinetemplate.

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 thevirtual machine template.

No Yes Yes

--cpu_shares

int The level of CPU resources a virtual machinecan demand relative to other virtual machines.For example, 512 for low priority virtualmachines, 1024 for medium priority virtualmachines, and 2048 for high priority virtualmachines.

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 virtualmachines are configured to boot. This optionsupports booting a Linux kernel directly ratherthan through the BIOS bootloader.

No Yes Yes

--display-type

string Defines the display type. Specify either spice orvnc.

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 asingle virtual PCI device.

No Yes Yes

--display-allow_override

boolean

Set to true to allow override of the templateconsole settings.

No Yes Yes

--display-smartcard_enabled

boolean

Set to true to enable the Smart card feature forvirtual 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 andpaste.

No Yes Yes

--display-keyboard_layout

string Defines the keyboard layout for the virtualmachine. This option is only available whenusing the VNC protocol. Specify formats such as en-US.

No Yes Yes


UserCreatable

UserUpdatable

T echnical Guide

118

--os-initRd string A path to an initrd image to be used with aspecified kernel. This option supports booting aLinux kernel directly rather than through theBIOS bootloader.

No Yes Yes

--usb-enabled

Boolean

Set to true to enable USB support on the virtualmachine. This option is only available for virtualmachines 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 astronger encryption algorithm but increases thedata load during transport.

No Yes Yes

--migration_downtime

int Defines the maximum number of millisecondsthat the virtual machine can be down during livemigration.

No Yes Yes

--virtio_scsi-enabled

boolean

Set to true to allow attaching a VirtIO consoledevice 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 sourcevirtual machine to the template.

No Yes Yes

--version-version_name

string Used with the --version-base_template-idparameter. Defines the name for the subtemplate.

No Yes Yes

--version-base_template-id

string Defines the template ID to be used as the roottemplate. Used if you want to create this templateas a sub template of a root template.

No Yes Yes

--cpu-cpu_tune-vcpu_pin

collection

Defines which virtual CPUs of a virtual machineto pin to the physical CPUs of a host.

No Yes Yes

--serial_number-policy

string Defines the serial number policy for the virtualmachine template. Specify host, vm, or custom.If custom is used, also define the serial numbervalue using --serial_number-value.

No Yes Yes

--serial_number-value

string Defines the serial number for the virtual machinetemplate.

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 thecluster ID.

No Yes Yes


UserCreatable

UserUpdatable


119

--cluster-name

string Defines the cluster to use by specifying thecluster name.

No Yes Yes

--cpu_profile-id

string Defines the CPU profile to use. Use the list cpuprofiles command to retrieve a full list ofCPU profile IDs.

No Yes Yes



No Yes Yes

--correlation_id


No Yes Yes


UserCreatable

UserUpdatable

The --sso-methods-method parameter is a collection that uses the sub-parameters in thefollowing table.

Table 14 .51. - -sso-methods-method parameters

Name Type Descript ionmethod.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_propert ies-custom_property parameters

Name Type Descript ioncustom_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 Descript ionboot.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 followingtable.

Table 14 .54 . - -vm-disks-d isk parameters

Name Type Descript iondisk.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.

T echnical Guide

120

The --cpu-cpu_tune-vcpu_pin parameter is a collection that uses the sub-parameters in thefollowing table.

Table 14 .55. - -cpu-cpu_tune-vcpu_pin parameters

Name Type Descript ionvcpu_pin.vcpu int The virtual CPU to assign.vcpu_pin.cpu_set

string The physical CPUs on the host.

Example 14 .4 0. Creat ing a new template

[RHEVM shell (connected)]# add template --name MyTemplate1 --vm-name MyVM1

Example 14 .4 1. Updat ing a template

[RHEVM shell (connected)]# update template MyTemplate1 --memory 1073741824

Example 14 .4 2. Delet ing a template

[RHEVM shell (connected)]# remove template MyTemplate1

The following table lists actions for a virtual machine template resource.

Table 14 .56 . Virtual machine template act ions

Act ion Descript ionexport 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


UserCreatable

UserUpdatable

--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 .4 3. Creat ing a new user

[RHEVM shell (connected)]# add user --user_name jsmith --domain-name example.com


121

14.22. vm

The vm resource type groups all virtual machine resources in a Red Hat Enterprise Virtualizationenvironment.

Table 14 .58. Virtual machine parameters


UserCreatable

UserUpdatable

--name string The name of the virtual machine Yes Yes Yes--template-id|name

string A reference to the template used as the basisfor the virtual machine.

Yes Yes No

--cluster-id|name

string A reference to the cluster that includes thisVM.

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 virtualmachine.

No Yes No

--timezone

string The Sysprep time zone setting for aWindows virtual machine.

No Yes Yes

--os-boot collection The boot device for the virtual machine.Specify cdrom, hd , or network.

No Yes Yes


collection A set of user-defined environment variablespassed as parameters to custom scripts.

No Yes Yes

--os-type string The operating system type for this virtualmachine.

No Yes Yes

--usb-enabled

boolean Defines the USB policy for a virtualmachine. Set to true to enable USB on thevirtual 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 aspecified kernel. This option supportsbooting a Linux kernel directly rather thanthrough 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 usinga single virtual PCI device.

No Yes Yes

T echnical Guide

122

--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 virtualmachine 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 copyand paste.

No Yes Yes

--display-keyboard_layout

string Defines the keyboard layout for the virtualmachine. This option is only available whenusing the VNC protocol. Specify formatssuch as en-US.

No Yes Yes

--os-cmdline

string A kernel command line parameter string tobe used with the defined kernel. This optionsupports booting a Linux kernel directlyrather than through the BIOS bootloader.

No Yes Yes

--cpu-topology-cores

int The number of CPU cores available to thevirtual 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 virtualmachine in bytes.

No Yes Yes

--memory_policy-guaranteed

long The minimum amount of memory, in bytes,guaranteed on a host in order for the virtualmachine to run.

No Yes Yes

--memory_policy-ballooning

boolean Set to true to enable memory balloondevice.

No Yes Yes

--high_availability-priority

int Sets the priority value (migration and restartorder) of each virtual machine using highavailability.

No Yes Yes


UserCreatable

UserUpdatable


123

--high_availability-enabled

boolean Defines whether high availability is enabledfor 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 isstateless. A stateless virtual machinecontains a snapshot of its disk image takenat boot and removed at shutdown. Thismeans state changes do not persist after areboot.

No Yes Yes

--permissions-clone

boolean Set to true to copy the permissions of thesource virtual machine to the template.

No Yes Yes

--delete_protected

boolean Set to true to make it impossible to delete avirtual machine created from this template.

No Yes Yes

--sso-methods-method

collection Defines the single sign-on method used. Forexample, --sso-methods-method method.id=GUEST_AGENT .

No Yes Yes

--rng_device-rate-bytes

int Specifies how many bytes are permitted tobe consumed per period.

No Yes Yes

--rng_device-rate-period

int Specifies the duration of a period inmilliseconds. If specified, --rng_device-rate-bytes must be specified as well.

No Yes Yes

--rng_device-source

string The source of the random numbergenerator. Specify either random or hwrng .

No Yes Yes

--console-enabled

boolean Set to true to enable the VirtIO consoledevice 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 thevirtual machine.

No Yes Yes

--cpu_shares

int The level of CPU resources a virtualmachine can demand relative to other virtualmachines. For example, 512 for low priorityvirtual machines, 1024 for medium priorityvirtual machines, and 2048 for high priorityvirtual machines.

No Yes Yes


UserCreatable

UserUpdatable

T echnical Guide

124

--placement_policy-affinity

string The migration affinity for each virtualmachine. Specify migratable, user_migratable, or pinned .

No Yes Yes

--placement_policy-host-id|name

string A reference to the preferred host formigration 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 machineis configured to boot. This option supportsbooting a Linux kernel directly rather thanthrough the BIOS bootloader.

No Yes Yes

--disks-clone

boolean Defines whether to clone the disk from thedefined template.

No Yes No

--disks-disk

collection References to disks attached to the virtualmachine.

No Yes Yes

--tunnel_migration

boolean Set to true to enable data transport over a libvirt daemon. A tunneled transportuses a stronger encryption algorithm butincreases the data load during transport.

No Yes Yes

--migration_downtime

int Defines the maximum number ofmilliseconds that the virtual machine can bedown during live migration.

No Yes Yes

--virtio_scsi-enabled

boolean Set to true to allow attaching a VirtIOconsole 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 virtualmachine upon booting.

No Yes Yes

--initialization-configuration-type

string Defines the virtual machine format. Acceptsonly 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 virtualmachine to pin to the physical CPUs of ahost.

No Yes Yes


UserCreatable

UserUpdatable


125

--serial_number-policy

string Defines the serial number policy for thevirtual machine template. Specify host, vm,or custom. If custom is used, also definethe serial number value using --serial_number-value.

No Yes Yes

--serial_number-value

string Defines the serial number for the virtualmachine 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 thedomain process on a NUMA host. Specify interleave, strict, or preferred . If novalue 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 fulllist of CPU profile IDs.

No Yes Yes

--expect '201-created' Request becomes asynchronous until theexpected HTTP header is returned. Usefulfor long-running tasks that would otherwisereturn as successful before the task iscompleted.

No No No

--correlation_id

string A tagging identifier of an action for cross-system logging. If the client does not definethe identifier, one will be generated.

No Yes No


UserCreatable

UserUpdatable

The --os-boot parameter is a collection that uses the sub-parameters in the following table.

Table 14 .59 . - -os-boot parameters

Name Type Descript ionboot.dev string The boot device for the virtual machine template. Specify cdrom,

hd , or network.


Table 14 .6 0. - -custom_propert ies-custom_property parameters





The --sso-methods-method parameter is a collection that uses the sub-parameters in thefollowing table.

T echnical Guide

126

Table 14 .6 1. - -sso-methods-method parameters

Name Type Descript ionmethod.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 .6 2. - -d isks-d isk parameters

Name Type Descript iondisk.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 followingtable.

Table 14 .6 3. - -payloads-payload parameters

Name Type Descript ionpayload.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 thevirtual 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 thefollowing table.

Table 14 .6 4 . - -cpu-cpu_tune-vcpu_pin

Name Type Descript ionvcpu_pin.vcpu int The virtual CPU to assign.vcpu_pin.cpu_set

string The physical CPUs on the host.

Example 14 .4 4 . Creat ing a new virtual machine

[RHEVM shell (connected)]# add vm --name MyVM --template-name Blank --cluster-name Default --memory 536870912

Example 14 .4 5. Updat ing a virtual machine

[RHEVM shell (connected)]# update vm MyVM --memory 1073741824

Example 14 .4 6 . Delet ing a virtual machine

[RHEVM shell (connected)]# remove vm MyVM


127

The following table lists actions for a virtual machine resource.

Table 14 .6 5. Virtual machine act ions

Act ion Descript ionstart 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 EnterpriseVirtualization environment.

Table 14 .6 6 . Virtual machine pool parameters


UserCreatable

UserUpdatable

--cluster-id|name

string A reference to the cluster for the virtual machinepool.

Yes Yes Yes

--template-id|name

string A reference to the template for the virtual machinepool.

Yes Yes Yes

--name string The name of the virtual machine pool. Yes Yes Yes--size intege

rThe number of the virtual machines in the pool. Yes Yes Yes

Example 14 .4 7. Creat ing a new virtual machine pool

[RHEVM shell (connected)]# add vmpool --cluster-name MyCluster --template-name MyTemplate --name MyPool --size 3

Example 14 .4 8. Updat ing a virtual machine pool

[RHEVM shell (connected)]# update vmpool MyPool --size 4

Example 14 .4 9 . Delet ing a virtual machine pool

[RHEVM shell (connected)]# remove vmpool MyPool

T echnical Guide

128

14.24. vnicprofile

The vnicprofile resource type groups all VNIC (virtual network interface controller) profiles, alsoreferred to as VM (virtual machine) interface profiles, in a Red Hat Enterprise Virtualizationenvironment.

Table 14 .6 7. Virtual Network In terface Contro ller Prof ile Parameters


UserCreatable

UserUpdatable

--name string The name of the VNIC profile. Yes Yes Yes--network-id

string A reference to the logical network to which theprofile will be applied.

Yes No No

--correlation_id


No Yes No

--description

string A description for the profile. No Yes Yes



No No No


collection

A set of user-defined environment variablespassed as parameters to custom scripts.

No Yes Yes

--port_mirroring

Boolean

Toggles whether port mirroring is used for theprofile. The status is either True or False.Default is Falses

No No No


Table 14 .6 8. - -custom_propert ies-custom_property parameters





Example 14 .50. Creat ing a new vnic prof ile

[RHEVM shell (connected)]# add vnicprofile --name Gold --network-id 08305a2f-6952-4999-9646-c16137dc6d42

Example 14 .51. Updat ing a vnic prof ile


129

[RHEVM shell (connected)]# update vnicprofile Gold --port_mirroring true

Example 14 .52. Delet ing a vnic prof ile

[RHEVM shell (connected)]# remove vnicprofile Gold

T echnical Guide

130

Chapter 15. CLI Queries

15.1. Query Syntax

The CLI list command uses the --query attribute to perform server-side queries, which uses thesame format as Red Hat Enterprise Virtualization Manager search query language:

Table 15.1. Example search queries

Collect ion Criteria Resulthosts vms.status=up Displays a list of all hosts

running virtual machines thatare up.

vms domain=qa.company.com Displays a list of all virtualmachines running on thespecified domain.

vms users.name=mary Displays a list of all virtualmachines belonging to userswith the user name mary.

events severity>normal sortby time

Displays the list of all eventswith severity higher than normal and sorted by the time element values.

events severity>normal sortby time desc

Displays the list of all eventswith severity higher than normal and sorted by the time element values indescending 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.

Chapt er 1 5. CLI Queries

131

Part III. The REST Application Programming Interface

T echnical Guide

132

Chapter 16. Introduction

Red Hat Enterprise Virtualization Manager provides a Representat ional State Transfer (REST)API. The API provides software developers and system administrators with control over their Red HatEnterprise Virtualization environment outside of the standard web interface. The REST API is usefulfor developers and administrators who aim to integrate the functionality of a Red Hat EnterpriseVirtualization environment with custom scripts or external applications that access the API via thestandard Hypertext Transfer Protocol (HTTP).

The benefits of the REST API are:

Broad client support - Any programming language, framework, or system with support for HTTPprotocol can use the API;

Self descriptive - Client applications require minimal knowledge of the virtualization infrastructureas many details are discovered at runtime;

Resource-based model - The resource-based REST model provides a natural way to manage avirtualization 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. Itaims to provide developers and administrators with instructions and examples to help harness thefunctionality of their Red Hat Enterprise Virtualization environment through the REST API eitherdirectly or using the provided Python libraries.

16.1. Representat ional State Transfer

Representat ional State Transfer (REST) is a design architecture that focuses on resources fora specific service and their representations. A resource representation is a key abstraction ofinformation that corresponds to one specific managed element on a server. A client sends a requestto a server element located at a Uniform Resource Identifier (URI) and performs operations withstandard HTTP methods, such as GET , POST , PUT , and DELETE. This provides a statelesscommunication between the client and server where each request acts independent of any otherrequest and contains all necessary information to complete the request.

16.2. Red Hat Enterprise Virtualizat ion REST API Prerequisit es

Red Hat Enterprise Virtualiz at ion REST API Prerequisites

A networked installation of Red Hat Enterprise Virtualization Manager, which includes the RESTAPI.

A client or programming library that initiates and receives HTTP requests from the REST API. Forexample:

Python software development kit (SDK)

Chapt er 1 6 . Int roduct ion

133

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 APIinteractions. 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), whichthe API uses to construct resource representations. The W3C provides a full specification on XMLat http://www.w3.org/TR/xml/. ECMA International provide a free publication on JSON athttp://www.ecma-international.org.

T echnical Guide

134

http://www.ietf.org/rfc/rfc2616.txt

http://www.w3.org/TR/xml/

http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf

Chapter 17. Authentication and Security

17.1. TLS/SSL Cert ificat ion

The Red Hat Enterprise Virtualization Manager API requires Hypertext Transfer Protocol Secure

(HTTPS) for secure interaction with client software, such as the Manager's SDK and CLIcomponents. This involves a process of obtaining a certificate from the Red Hat EnterpriseVirtualization Manager and importing it into the certificate store of your client.

Important

Obtain your certificate from the Red Hat Enterprise Virtualization Manager using a securenetwork connection.

Procedure 17.1. Obtain ing a Cert if icate

You can obtain a certificate from the Red Hat Enterprise Virtualization Manager and transfer it to theclient machine using one of three methods:

1. Method 1 - Use a command line tool to download the certificate from the Manager. Examplesof command line tools include cURL and Wget , both of which are available on multipleplatforms.

a. If using cURL:

$ curl -o rhevm.cer http://[rhevm-server]/ca.crt

b. If using Wget :

$ wget -O rhevm.cer http://[rhevm-server]/ca.crt

2. 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 thebrowser's keystore.

a. If the browser downloads the cert if icate: save the file as rhevm.cer.

If the browser imports the cert if icate: export it from the browser's certificationoptions and save it as rhevm.cer.

3. Method 3 - Log in to the Manager, export the certificate from the truststore and copy it to yourclient machine.

a. Log in to the Manager as the root user.

b. Export the certificate from the truststore using the Java keytool management utility:

[2]

Chapt er 1 7 . Aut hent icat ion and Securit y

135

$ keytool -exportcert -keystore /etc/pki/ovirt-engine/.truststore -alias cacert -storepass mypass -file rhevm.cer

This creates a certificate file called rhevm.cer.

c. Copy the certificate to the client machine using the scp command:

$ scp rhevm.cer [username]@[client-machine]:[directory]

Each of these methods results in a certificate file named rhevm.cer on your client machine. An APIuser imports this file into the certificate store of the client.

Procedure 17.2. Import ing a Cert if icate 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 NetworkSecurity Services (NSS) or Java KeyStore (JKS), see your client documentation for moreinformation on importing a certificate.

17.2. HTTP Authent icat ion

Any user with a Red Hat Enterprise Virtualization account has access to the REST API. An API usersubmits a mandatory Red Hat Enterprise Virtualization Manager user name and password with all

requests to the API. Each request uses HTTP Basic Authentication to encode these credentials. Ifa 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 credent ials

HEAD [base] HTTP/1.1Host: [host]

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. An API user encodes anappropriate Red Hat Enterprise Virtualization Manager domain and user in the supplied credentialswith the username@domain:password convention.

The following table shows the process for encoding credentials in base64.

Table 17.1. Encoding credent ials for API access

Item Valueusername rhevmadmindomain domain.example.compassword 123456unencoded credentials [email protected]:123456base64 encodedcredentials

cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

[3]

T echnical Guide

136

An API user provides the base64 encoded credentials as shown:

Example 17.2. Access to the REST API with appropriate credent ials

HEAD [base] HTTP/1.1Host: [host]Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

HTTP/1.1 200 OK...

Important

Basic authentication involves potentially sensitive information, such as passwords, sent asplain text. REST API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-levelencryption of plain-text requests.

Important

Some base64 libraries break the result into multiple lines and terminate each line with anewline character. This breaks the header and causes a faulty request. The Authorizationheader requires the encoded credentials on a single line within the header.

17.3. Authent icat ion Sessions

The API also provides the ability for authentication session support. An API user sends an initialrequest with authentication details, then sends all subsequent requests using a session cookie toauthenticate. The following procedure demonstrates how to use an authenticated session.

Procedure 17.3. Request ing an authent icated session

1. Send a request with the Authorization and Prefer: persistent-auth

HEAD [base] HTTP/1.1Host: [host]Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2Prefer: persistent-auth

HTTP/1.1 200 OK...

This returns a response with the following header:

Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/api; Secure

Chapt er 1 7 . Aut hent icat ion and Securit y

137

Note the JSESSIONID= value. In this example the value is JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK.

2. Send all subsequent requests with the Prefer: persistent-auth and cookie headerwith the JSESSIONID= value. The Authorization is no longer needed when using anauthenticated session.

HEAD [base] HTTP/1.1Host: [host]Prefer: persistent-authcookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK

HTTP/1.1 200 OK...

3. When the session is no longer required, perform a request to the sever without the Prefer: persistent-auth header.

HEAD [base] HTTP/1.1Host: [host]Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

HTTP/1.1 200 OK...

[2] HTTPS is d escrib ed in RFC 28 18 HTTP Over TLS.

[3] Basic Authenticatio n is d escrib ed in RFC 26 17 HTTP Authenticatio n: Basic and Dig est AccessAuthenticatio n.

T echnical Guide

138



Chapter 18. REST API Quick Start Example

This chapter provides an example to demonstrate the REST API's ability to setup a basic Red HatEnterprise 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 usesRed Hat Enterprise Linux Server 6 for our installation ISO example; and

Red Hat Enterprise Virtualization's engine- iso-uploader tool to upload your chosen operatingsystem ISO file.

This example uses cURL to demonstrate REST requests with a client application. Note that anyapplication 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 toyour installation of Red Hat Enterprise Virtualization Manager.

Important

All cURL examples include placeholders for authentication details (USER:PASS) andcertificate location (CERT ). Ensure all requests performed with cURL fulfill certification andauthentication requirements.

Note

Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for theid attribute for each resource. Identifier codes in this example might appear different to theidentifier codes in your Red Hat Enterprise Virtualization environment.

18.1. Example: Access API Ent ry Point

The following request retrieves a representation of the main entry point of the API.

Example 18.1. Access the API ent ry point

Request :

GET /api HTTP/1.1Accept: application/xml

Chapt er 1 8 . REST API Quick St art Example

139

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] https://[RHEVM Host]:443/api

Result :

HTTP/1.1 200 OKContent-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>

T echnical Guide

14 0

</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 exampleexamines 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 Collect ion

Red Hat Enterprise Virtualization Manager creates a Default data center on installation. Thisexample 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 co llect ion

Request :

GET /api/datacenters HTTP/1.1Accept: application/xml

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/api/datacenters

Result :


<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"


14 1

<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 toother resources of your virtual environment.

The data center also contains a link to the storagedomains sub-collection. The data center usesthis sub-collection to attach storage domains from the storagedomains main collection, which thisexample covers later.

18.3. Example: List Host Cluster Collect ion

Red Hat Enterprise Virtualization Manager creates a Default host cluster on installation. Thisexample uses the Default cluster to group resources in your Red Hat Enterprise Virtualizationenvironment.

The following request retrieves a representation of the cluster collection:

Example 18.3. List host clusters collect ion

Request :

GET /api/clusters HTTP/1.1Accept: application/xml

cURL command:

T echnical Guide

14 2

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/api/clusters

Result :


<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 toother 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. Thenext section examines the networks collection in more detail.

18.4 . Example: List Logical Networks Collect ion

Red Hat Enterprise Virtualization Manager creates a default rhevm network on installation. Thisnetwork acts as the management network for Red Hat Enterprise Virtualization Manager to accesshypervisor hosts.


14 3

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 log ical networks collect ion

Request :

GET /api/networks HTTP/1.1Accept: application/xml

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \ --cacert [CERT] \ https://[RHEVM Host]:443/api/networks

Result :


<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 datacenter'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 Collect ion

This example uses a Red Hat Enterprise Virtualization Hypervisor host. Red Hat EnterpriseVirtualization Manager automatically registers any configured Red Hat Enterprise VirtualizationHypervisor. This example retrieves a representation of the hosts collection and shows a Red HatEnterprise Virtualization Hypervisor host named hypervisor registered with the virtualizationenvironment.

T echnical Guide

14 4

Example 18.5. List hosts collect ion

Request :

GET /api/hosts HTTP/1.1Accept: 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 OKAccept: 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"/>


14 5

<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 resourcesof your virtual environment.

This host is a member of the Default cluster and accessing the nics sub-collection shows thishost has a connection to the rhevm network.

18.6. Example: List CPU Profiles

The following request retrieves a representation of the CPU profiles:

T echnical Guide

14 6

Example 18.6 . List CPU prof iles

Request :

GET /api/cpuprofiles HTTP/1.1Accept: application/xml

cURL command:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM Host]:443/api/cpuprofiles

Result :


<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"/>


14 7

<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 witha POST request.

Example 18.7. Approve a pre-conf igured Red Hat Enterprise Virtualiz at ion Hypervisorhost

Request :

POST /api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve HTTP/1.1Accept: application/xmlContent-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 actiondoes not require additional parameters, the body contains an empty action element.

Use the approve action only for Red Hat Enterprise Virtualization Hypervisor hosts. Red HatEnterprise 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 providesstorage for virtualized guest images. Creation of a new storage domain requires a POST request, withthe 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 bydefault on the storage domain. To configure this specify <wipe_after_delete> in the POSTrequest. This option can be edited after the domain is created, but doing so will not change the wipeafter delete property of disks that already exist.

T echnical Guide

14 8

Example 18.8. Create an NFS data storage domain

Request :

POST /api/storagedomains HTTP/1.1Accept: application/xmlContent-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 :


<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>


14 9

<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 storagefor DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Creation of a new storage domainrequires a POST request, with the storage domain representation included, sent to the URL of thestorage domain collection.


Example 18.9 . Create an NFS ISO storage domain

Request :


<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> \

T echnical Guide

150

<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 :


<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: At tach Storage Domains to Data Center

The following example attaches the data1 and iso1 storage domains to the Default data center.

Example 18.10. At tach data1 storage domain to the Default data center

Request :

POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1Accept: application/xmlContent-type: application/xml


151

<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. At tach iso1 storage domain to the Default data center

Request :

POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1Accept: application/xmlContent-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 storagedomainssub-collection of the Default data center. This means the storagedomains sub-collectioncontains attached storage domains of the data center.

18.11. Example: Act ivate Storage Domains

This example activates the data1 and iso1 storage domains for the Red Hat EnterpriseVirtualization Manager's use.

Example 18.12. Act ivate data1 storage domain

Request :

T echnical Guide

152

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/activate HTTP/1.1Accept: application/xmlContent-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. Act ivate iso1 storage domain

Request :

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate HTTP/1.1Accept: application/xmlContent-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 thevirtualization environment's Blank template as a basis. The request also defines the virtualmachine's memory as 512 MB and sets the boot device to a virtual hard disk.

Example 18.14 . Create a virtual machine


153

Request :

POST /api/vms HTTP/1.1Accept: application/xmlContent-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 :


<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"

T echnical Guide

154

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>


155

</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"/>

T echnical Guide

156

<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 tothe rhevm network.

Example 18.15. Create a virtual machine NIC

Request :

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics HTTP/1.1Accept: application/xmlContent-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 d isk

Request :

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks HTTP/1.1Accept: application/xmlContent-type: application/xml


157

<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: At tach ISO Image to Virtual Machine

The boot media for our example virtual machine requires an CD-ROM or DVD ISO image for anoperating system installation. This example uses a Red Hat Enterprise Server 6 ISO image forinstallation.

ISO images must be available in the iso1 ISO domain for the virtual machines to use. Red HatEnterprise Virtualization Platform provides an uploader tool that ensures that the ISO images areuploaded 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 toview the file resource:

Example 18.17. View the f iles sub-collect ion in an ISO storage domain

Request :

GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1Accept: application/xml

cURL command:

T echnical Guide

158

# 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 UserPortal.

Example 18.18. At tach an ISO image to the virtual machine

Request :

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms HTTP/1.1Accept: application/xmlContent-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 tofunction. This example starts the virtual machine using the start action.

Example 18.19 . Start the virtual machine


159

Request :

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start HTTP/1.1Accept: application/xmlContent-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 theevents collection and identifies events specific to the API starting a virtual machine.

Example 18.20. List the events collect ion

Request :

GET /api/events HTTP/1.1Accept: 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">

T echnical Guide

160

<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 the admin user's user name and password.

id="102" - The API, acting as the admin user, starts vm1 on the hypervisor host.

id="103" - The API logs out of the admin user account.


161

Chapter 19. Entry Point

A user begins interacting with the API through a GET request on the entry point URI consisting of ahost and base .

Example 19 .1. Accessing the API Ent ry Point

If the host is www.example.com and the base is /api , the entry point appears with thefollowing request:

GET /api HTTP/1.1Accept: application/xmlHost: www.example.comAuthorization: [base64 encoded credentials]


<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>

T echnical Guide

162

Note

For simplicity, all other examples omit the Host: and Authorization: request headers andassume the base is the default /api path. This base path differs depending on yourimplementation.

19.1. Product Informat ion

The entry point contains a product_info element to help an API user determine the legitimacy ofthe Red Hat Enterprise Virtualization environment. This includes the name of the product, the vendorand the version.

Example 19 .2. Verify a genuine Red Hat Enterprise Virtualiz at ion 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 APIexposes. Each collection uses a relation type to identify the URI a client needs.

Table 19 .1. Availab le Relat ionship Types

Relat ionship Descript ioncapabilities 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.

Chapt er 1 9 . Ent ry Point

163

roles Roles.users Users.tags Tags.events Events.

Relat ionship Descript ion

Figure 19 .1. The relat ionship between the API ent ry point and the resource collect ionsexposed by the API

Note

All URIs shown in example responses are illustrative. The format of all URIs returned by theserver is opaque. Clients navigate to specific resources through the entry point URI and usethe relationship types to access the URIs.

The server chooses to include absolute URIs or absolute paths in the link element's href attribute, so clients are required to handle either form.

The link elements also contain a set of search URIs for certain collections. These URIs use URI

templates to integrate search queries. The purpose of the URI template is to accept a searchexpression using the natural HTTP pattern of a query parameter. The client does not require priorknowledge of the URI structure. Thus clients should treat these templates as being opaque andaccess 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. Relat ionships associated with search query URIs

Relat ionship Descript iondatacenters/search Query data centers.clusters/search Query host clusters.storagedomains/search Query storage domains.hosts/search Query hosts.

[4]

[5]

T echnical Guide

164

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.

Relat ionship Descript ion

19.3. Special Object Elements

Special object elements define relationships to special fixed resources within the virtualizationenvironment.

Table 19 .3. Special Objects

Relat ionship Descript iontemplates/blank The default blank virtual machine template for your virtualization

environment. This template exists in every cluster as opposed to astandard template, which only exists in a single cluster.

tags/root The root tag that acts as a base for tag hierarchy in yourvirtualization environment.

19.4 . Summary Element

The summary element shows a high level summary of the system's statistics.

Table 19 .4 . Summary Elements

Element Descript ionvms 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 Descript ion Language (RSDL)

RESTful Service Description Language (RSDL) provides a description of the structure and elementsin the REST API in one whole XML specification. Invoke the RSDL using the following request.

GET /api?rsdl HTTP/1.1Accept: 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"/>


165

<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 St ructure Elements

Element Descript iondescription 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>

T echnical Guide

166

Table 19 .6 . RSDL Link St ructure Elements

Element Descript ionlink 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 todefine the header.

body Defines the body for the HTTP request. Contains a resource typeand a parameter_set, which contains a sets of parameter elementswith attributes to define whether they are required for a request andthe data type. The parameter element also includes a name elementto define the Red Hat Enterprise Virtualization Manager property tomodify 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 todefine the resource structure to output.

Use the RSDL in your applications as a method to map all links and parameter requirements forcontrolling a Red Hat Enterprise Virtualization environment.

19.6. Red Hat Enterprise Virtualizat ion Windows Guest VSS Support

The Red Hat Enterprise Virtualization Backup and Restore API provides integration with MicrosoftWindows Volume Shadow Copy Service (VSS) using qemu-ga . The VSS provider registration ismade 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 thecorruption of Linux guest virtual machines. Before issuing a snapshot request or creating a backupcopy of the disk, the management stack (libvirt) sent a guest-fsfreeze-freeze QMP command tothe QEMU GA via the virtio-serial port. This command caused the guest agent to freeze all of theguest 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 thefilesystem 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, l ibvirt would proceed with the snapshot. At itscompletion, l ibvirt sends the guest-fsfreeze-thaw QMP command to the QEMU GA over thevirtio-serial port. This command tells the QEMU GA to issue a FITHAW ioctl(), which unblocksthe 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 disksnapshot was taken. This was evident in cases where the fsck utility found no problems onfilesystems restored from snapshots, and yet applications were not able to resume processing fromthe point where the snapshot was taken and userspace processes may not have written their internalbuffers to files on the disk.

Red Hat Enterprise Linux 6.5 ensures that both file and application-level synchronization (flushing)


167

are done. Guest system administrators can write and install application-specific freezing andthawing 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 guestvirtual 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 andother file system applications to flush their working buffers to the virtual disk and to stop acceptingfurther client connections. The applications then bring their data files into a consistent state whereresumption of processing, with the reactivated (or a freshly started) instance of the application (afterrestoring the virtual disk from backup) is possible. When all scripts are done making their respectiveapplications 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 thesnapshot is taken, the file system will resume to serve write requests. This process is called thawing.

Thawing is freezing in reverse order. Instructed by l ibvirt , QEMU GA thaws the guest virtualmachine's filesystems. It then invokes individual hook scripts (via the main hook script) to resume orrestart applications that had been inactivated during the freeze process.

19.8. VSS Transact ion Flow

In processing a backup, the requester and the writers coordinate to do several things: to provide astable system image from which to back up data (the shadow copied volume), to group files togetheron the basis of their usage, and to store information on the saved data. This must all be done withminimal 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 thennotifies 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 providersvssadmin 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 d escrib ing Unifo rm Reso urce Lo cato r Generic Syntax p ro vid es a Co llected ABNF fo r URIthat exp lains the d ifference b etween these fo rms.

[5] The Internet-Draft d escrib ing the fo rmat o f a URI Temp late is availab le athttp ://to o ls.ietf.o rg /html/d raft-g reg o rio -uritemp late-0 3.

T echnical Guide

168

http://tools.ietf.org/html/rfc3986#appendix-A

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 andprovides local management for virtual machines, networks and storage. Red Hat EnterpriseVirtualization 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 Managerexcludes certain features from a current version of VDSM until all hosts within a cluster have thesame VDSM version, or more recent, installed.

The API represents this concept as a compatibility level for each host, corresponding to theversion of VDSM installed. A version element contains major and minor attributes, whichdescribe the compatibility level.

When an administrator upgrades all hosts within a cluster to a certain level, the version levelappears under a supported_versions element. This indicates the cluster's version is nowupdatable to that level. Once the administrator updates all clusters within a data center to a givenlevel, the data center is updatable to that level.

20.1. Upgrading Compat ibilit y Levels

Example 20.1. Upgrading compat ib ility levels

The API reports the following compatibility levels for Red Hat Enterprise Virtualization Manager 3.4instance:

<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"

Chapt er 2 0 . Compat ibilit y Level Versions

169

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 availablein Red Hat Enterprise Virtualization 3.5 for this data center.

T echnical Guide

170

Chapter 21. Capabilities

The capabilities collection provides information about the capabilities that versions of Red HatEnterprise Virtualization support. These capabilities include active features and availableenumerated values for specific properties.

To retrieve a full list of the capabilities for all versions of Red Hat Enterprise Virtualization from 3.2 tothe latest version, submit the following request:

GET /api/capabilities/ HTTP/1.1Content-Type: application/xmlAccept: application/xml

21.1. Version-Dependent Capabilit ies

The capabilities element contains any number of version elements that describe capabilitiesdependent on a compatibility level.

The version element includes attributes for major and minor version numbers. This indicates thecurrent version level.

The following representation shows capabilities specific to Red Hat Enterprise Virtualization Manager3.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

Chapt er 2 1 . Capabilit ies

171

The current element signifies if the version specified is the most recent supported compatibilitylevel. 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 compatiblewith Red Hat Enterprise Virtualization 3.5.

Table 21.1. Feature Types

Feature Descript ionTransparent huge pages memorypolicy

Allows you to define the availability of transparent hugepages for hosts. Acceptable values are true or false.

Gluster support This features provides support for using Gluster Volumesand Bricks as storage.

POSIX-FS storage type This feature provides support for the POSIX-FS storagetype.

Port mirroring Allows you to define the availability of port mirroring forvirtual 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 - whichdefine the number of host sockets displayed, the numberof threads and the number of cores per socket.

Search case sensitivity Allows you to specify whether a search query is casesensitive by providing the case-sensitive=true|false URL parameter.

Maximum results for GET requests Allows you to specify the maximum number of resultsreturned from a GET request.

JSON content type Allows you to define a header that makes it possible to seta 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 specificvirtual disk.

Activate and deactivate networkinterface cards

Allows you to activate or deactivate a network interfacecard by specifying activate or deactivate as anaction on a specific network interface card.

Snapshot refactoring Allows you to refactor snapshots for virtual machines.Remove template disks from specifiedstorage domain

Allows you to remove virtual machine template disks froma specific storage domain using a DELETE request.

T echnical Guide

172

Floating disks Floating disks are disks that are not attached to anyvirtual machine. With this feature, such disks also appearin the root collection rather than under specific virtualmachines.

Asynchronous deletion Allows you to specify that DELETE requests are to beperformed asynchronously by specifying the async URLparameter.

Session-based authentication Allows you to maintain a client-server session byproviding an appropriate header, eliminating the need tolog in with each request.

Virtual machine applications Allows you to view a list of applications installed on aspecific 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 SCSIcontroller devices.

Custom resource comments Allows you to add custom comments to data centers andother resources.

Refresh host capabilities Allows you to synchronize data on hosts and refresh thelist of network interfaces available to a specific host.

Memory snapshot Allows you to include the memory state as part of a virtualmachine snapshot.

Watchdog device Allows you to create watchdog devices for virtualmachines.

SSH authentication method Allows you to authenticate with hosts over SSH using anadministrative 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 forstorage domains

Allows you to view storage server connections to or from aspecific storage domain.

Attach and detach storage serverconnections

Allows you to attach or detach storage server connectionsto or from a specific storage domain.

Single PCI for Qxl Allows you to view multiple video devices via a single PCIguest device.

Add virtual machine from OVFconfiguration

Allows you to add a virtual machine from a provided OVFconfiguration.

Virtual network interface card profiles Allows you to configure a profile that defines quality ofservice, custom properties and port mirroring for a specificvirtual network interface card.

Image storage domains (tech preview) Allows you to import images from and export images to animage storage domain such as an OpenStack imageservice (Glance).

Virtual machine fully qualified domainnames

Allows you to retrieve the fully qualified domain name of aspecific virtual machine.

Attaching disk snapshots to virtualmachines

This feature provides support for attaching disksnapshots 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 migrateaction and stopmigrate action allow you to migratedata and reuse the brick.


Chapt er 2 1 . Capabilit ies

173

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 relevantversion:

<capabilities> <version major="3" minor="4"> ... <features> <feature> <name>Transparent-Huge-Pages Memory Policy</name> <transparent_huepages/> </feature> </features> ... </version></capabilities>

T echnical Guide

174

Chapter 22. Common Features

22.1. Element Property Icons

Note

Throughout this guide, the elements of each resource are detailed in tables. These tablesinclude a properties column, displaying icons depicting element properties. The meaning ofthese icons is shown in Table 22.1, “Element property icons” .

Table 22.1. Element property icons

Property Descript ion IconRequired for creation These elements must be included in the client-provided

representation of a resource on creation, but are notmandatory for an update of a resource.

Non-updatable These elements cannot have their value changed whenupdating a resource. Include these elements in a client-provided representation on update only if their valuesare not altered by the API user. If altered, the API reportsan error.

Read-only These elements are read-only. Values for read-onlyelements are not created or modified.

22.2. Representat ions

22.2.1. Representat ions

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 At t ributes to Resource Representat ions

All resource representations contain a set of common attributes

Chapt er 2 2 . Common Feat ures

175

Table 22.2. Common at t ributes to resource representat ions

At t ribute Type Descript ion Propert iesid GUID Each resource in the virtualization

infrastructure contains an id , whichacts as a globally unique identifier(GUID). The GUID is the primarymethod of resource identification.

href string The canonical location of theresource as an absolute path.

22.2.3. Common Elements to Resource Representat ions

All resource representations contain a set of common elements.

Table 22.3. Common elements to resource representat ions

Element Type Descript ion Propert iesname string A user-supplied human readable

name for the resource. The name isunique across all resources of itstype.

description string A free-form user-supplied humanreadable description of the resource.

22.3. Collect ions

22.3.1. Collect ions

A collection is a set of resources of the same type. The API provides both top-level collections andsub-collections. An example of a top-level collection is the hosts collection which contains allvirtualization hosts in the environment. An example of a sub-collection is the host.nics collectionwhich contains resources for all network interface cards attached to a host resource.

22.3.2. List ing All Resources in a Collect ion

Obtain a listing of resources in a collection with a GET request on the collection URI obtained fromthe entry point.

Include an Accept HTTP header to define the MIME type for the response format.

GET /api/[collection] HTTP/1.1Accept: [MIME type]

22.3.3. List ing Extended Resource Sub-Collect ions

The API extends collection representations to include sub-collections when the Accept headerincludes the detail parameter.

GET /api/collection HTTP/1.1Accept: application/xml; detail=subcollection

T echnical Guide

176

This includes multiple sub-collection requests using either separated detail parameters:

GET /api/collection HTTP/1.1Accept: application/xml; detail=subcollection1; detail=subcollection2

Or one detail parameter that separates the sub-collection with the + operator:

GET /api/collection HTTP/1.1Accept: application/xml; detail=subcollection1+subcollection2+subcollection3

The API supports extended sub-collections for the following main collections.

Table 22.4 . Collect ions that use extended sub-collect ions

Collect ion Extended Sub-Collect ion Supporthosts statistics

vms statistics, nics, disks

Example 22.1. A request for extended stat ist ics, NICs and d isks sub-collect ions inthe vms collect ion

GET /api/vms HTTP/1.1Accept: application/xml; detail=statistics+nics+disks

22.3.4 . Searching Collect ions with Queries

A GET request on a "collection/search" link results in a search query of that collection. The APIonly returns resources within the collection that satisfy the search query constraints.

GET /api/collection?search={query} HTTP/1.1Accept: 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 HatEnterprise Virtualization 3.4, this parameter does not affect the REST API and an API search querywithout specifying the max parameter will return all values. Specifying the max parameter isrecommended to prevent API search queries from slowing UI performance.


177

GET /api/collection;max=1 HTTP/1.1Accept: 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 Sensit ivity

All search queries are case sensitive by default. The URL syntax provides a Boolean option to togglecase sensitivity.

Example 22.2. Case insensit ive search query

GET /api/collection;case-sensitive=false?search={query} HTTP/1.1Accept: 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.1Accept: application/xml

The query template value refers to the search query the API directs to the collection. This queryuses 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

Collect ion Criteria Resulthosts vms.status=up Displays a list of all hosts

running virtual machines thatare up.

vms domain=qa.company.com Displays a list of all virtualmachines running on thespecified domain.

vms users.name=mary Displays a list of all virtualmachines belonging to userswith the user name mary.

T echnical Guide

178

events severity>normal sortby time

Displays the list of all eventswith severity higher than normal and sorted by the time element values.

events severity>normal sortby time desc

Displays the list of all eventswith severity higher than normal and sorted by the time element values indescending order.

Collect ion Criteria Result

The API requires the query template to be URL-encoded to translate reserved characters, such asoperators and spaces.

Example 22.3. URL-encoded search query

GET /api/vms?search=name%3Dvm1 HTTP/1.1Accept: 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.1Accept: 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.1Accept: 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. Paginat ion

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. Todisplay more than the default, the API separates collections into pages via a search query containingthe page command.

Example 22.6 . Paginat ing resources


179

This example paginates resources in a collection. The URL-encoded request is:

GET /api/collection?search=page%201 HTTP/1.1Accept: application/xml

Increase the page value to view the next page of results:

GET /api/collection?search=page%202 HTTP/1.1Accept: 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.1Accept: 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 sinceall requests are independent from each other. As a result, if a status change occurs betweenyour 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 occursbefore you can request the next page, then your results may be missing entries or containduplicated entries.

22.3.10. Creat ing a Resource in a Collect ion

Create a new resource with a POST request to the collection URI containing a representation of thenew resource.

A POST request requires a Content-Type header. This informs the API of the representation MIMEtype in the body content as part of the request.


Each resource type has its own specific required properties. The client supplies these propertieswhen 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 missingelements.

POST /api/[collection] HTTP/1.1Accept: [MIME type]Content-Type: [MIME type]

[body]

22.3.11. Asynchronous Requests

T echnical Guide

180

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, arecreated asynchronously. A request to create an asynchronous resource results in a 202 Acceptedstatus. 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.1Accept: application/xmlContent-Type: application/xml

<resource> <name>Resource-Name</name></resource>

HTTP/1.1 202 AcceptedContent-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.1Accept: 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.1Accept: application/xmlContent-Type: application/xmlExpect: 201-created


181

<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 commonparameters that the REST API abstracts to form a resource representat ion , usually in XML orJSON. Users can view a resource representation, then edit the parameters and send therepresentation back to the resource's URL within the API, which modifies the resource. Users can alsodelete individual resources through REST.

A RESTful web service also groups resources into collect ions . Users can view a representation ofall resources in a collection. Users also send resource representations to a specific collection tocreate a new resource within that particular collection.

22.4 .2. Ret rieving a Resource

Obtain the state of a resource with a GET request on a URI obtained from a collection listing.


GET /api/[collection]/[resource_id] HTTP/1.1Accept: [MIME type]

22.4 .3. Updat ing 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 individualresource type documentation.

A PUT request requires a Content-Type header. This informs the API of the representation MIMEtype in the body content as part of the request.


PUT /api/collection/resource_id HTTP/1.1Accept: [MIME type]Content-Type: [MIME type]

[body]

This does not include immutable resource properties that an API user has attempted to modify. If anattempt is made to modify a strictly immutable resource property, the API reports a conflict with anerror message representation in the response body.

Properties omitted from the representation are ignored and not changed.

22.4 .4 . Delet ing a Resource

T echnical Guide

182

Delete a resource with a DELETE request sent to its URI.


DELETE /api/[collection]/[resource_id] HTTP/1.1Accept: [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 ofthe representation MIME type in the body content. If a DELETE request contains no body content,omit the Content-Type header.

22.4 .5. Sub-Collect ion Relat ionships

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, avirtual machine contains network interfaces, which means the API maps the relationship between thevirtual 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, avirtual machine can contain several disks and some disks are shared among multiple virtualmachines.

Where mapped resources are dependent on a parent resource. Without the parent resource, thedependent 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 associatedwith 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.1Accept: 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.1Accept: application/xml


<subcollection>


183

<subresource id="subresource_id" href="/api/collection/resource_id/subcollection/subresource_id"> ... </subresource> ...</subcollection>

22.4 .6. XML Element Relat ionships

XML element links act as an alternative to sub-collections to express relationships betweenresources. XML element links are simply elements with a "href" attribute that points to the linkedelement.

XML element links are used to model simple 1:N mappings between resources without a dependencyand without data associated with the relationship. For example, the relationship between a host anda 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 f rom a sub-collect ion resource to a resource using an XMLelement

GET /api/collection/resource_id/subcollection/subresource_id HTTP/1.1


<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. Act ions

Most resources include a list of action links to provide functions not achieved through the standardHTTP methods.

<resource> ... <actions> <link rel="start" href="/api/collection/resource_id/start"/> <link rel="stop" href="/api/collection/resource_id/stop"/> ... </actions> ...</resource>

T echnical Guide

184

The API invokes an action with a POST request to the supplied URI. The body of the POST requiresan action representation encapsulating common and task-specific parameters.

Table 22.6 . Common act ion parameters

Element Descript ionasync true if the server responds immediately with 202 Accepted and an

action representation contains a href link to be polled forcompletion.

grace_period a grace period in milliseconds, which must expire before the action isinitiated.

Individual actions and their parameters are documented in the individual resource type'sdocumentation. Some parameters are mandatory for specific actions and their absence is indicatedwith a fault response.

An action also requires a Content-Type: application/xml header since the POST requestrequires an XML representation in the body content.

When the action is initiated asynchronously, the immediate 202 Accepted response provides a linkto monitor the status of the task:

POST /api/collection/resource_id/action HTTP/1.1Content-Type: application/xmlAccept: application/xml

<action> <async>true</async></action>

HTTP/1.1 202 AcceptedContent-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. Act ion statuses

Status Descript ionpending 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 hasexpired, subsequent GETs are 301 Moved Permanently redirected back to the target resource.

GET /api/collection/resource_id/action/action_id HTTP/1.1Accept: application/xml


185


<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. Act ion relat ionships

Type Descript ionparent 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, anassigned role and the specified resource. For example:

GET /api/collection/resource_id/permissions HTTP/1.1Accept: 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 permissionrepresentation 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.1Content-Type: application/xmlAccept: application/xml

<permission> <role id="role_id"/> <user id="user_id"/>

T echnical Guide

186

</permission>

HTTP/1.1 201 CreatedContent-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 APIreports an unsuccessful resource state update or action with a fault representation in the responseentity body. The fault contains a reason and detail strings. Clients must accommodate failedrequests via extracting the fault or the expected resource representation depending on theresponse status code. Such cases are clearly indicated in the individual resource documentation.

PUT /api/collection/resource_id HTTP/1.1Accept: application/xmlContent-Type: application/xml

<resource> <id>id-update-test</id></resource>

HTTP/1.1 409 ConflictContent-Type: application/xml

<fault> <reason>Broken immutability constraint</reason> <detail>Attempt to set immutable field: id</detail></fault>


187

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-levelbackup and restoration of virtual machines. The API combines several components of Red HatEnterprise Virtualization, such as live snapshots and the REST API, to create and work withtemporary volumes that can be attached to a virtual machine containing backup software providedby an independent software provider.

For supported third-party backup vendors, consult the Red Hat Enterprise Virtualization Ecosystemat 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 twovirtual machines: the virtual machine to back up, and a virtual machine on which the software formanaging the backup is installed.

Procedure 23.1. Backing Up a Virtual Machine

1. 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.1Accept: application/xmlContent-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 thevirtual machine as at the time the snapshot was taken is stored in the data attribute ofthe configuration attribute in initialization under the snapshot.

Important

You cannot take snapshots of disks that are marked as shareable or that are based ondirect LUN disks.

2. Retrieve the configuration data of the virtual machine from the data attribute under thesnapshot:

GET /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1Accept: application/xmlContent-type: application/xml

T echnical Guide

188

http://marketplace.redhat.com/rhev/products

3. 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.1Accept: application/xmlContent-type: application/xml

4. Attach the snapshot to the backup virtual machine and activate the disk:

POST /api/vms/22222222-2222-2222-2222-222222222222/disks/ HTTP/1.1Accept: application/xmlContent-type: application/xml

<disk id="11111111-1111-1111-1111-111111111111"> <snapshot id="11111111-1111-1111-1111-111111111111"/> <active>true</active></disk>

5. Use the backup software on the backup virtual machine to back up the data on the snapshotdisk.

6. 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.1Accept: application/xmlContent-type: application/xml

<action> <detach>true</detach></action>

7. Optionally, delete the snapshot:

DELETE /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1Accept: application/xmlContent-type: application/xml

You have backed up the state of a virtual machine at a fixed point in time using backup softwareinstalled 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. Thisprocedure assumes you have a backup virtual machine on which the software used to manage theprevious backup is installed.

Procedure 23.2. Restoring a Virtual Machine

1. 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.

Chapt er 2 3. T he Backup and Rest ore API

189

2. Attach the disk to the backup virtual machine:


<disk id="11111111-1111-1111-1111-111111111111"></disk>

3. Use the backup software to restore the backup to the disk.

4. Detach the disk from the backup virtual machine:

DELETE /api/vms/22222222-2222-2222-2222-222222222222/disks/11111111-1111-1111-1111-111111111111 HTTP/1.1Accept: application/xmlContent-type: application/xml


5. Create a new virtual machine using the configuration data of the virtual machine beingrestored:

POST /api/vms/ HTTP/1.1Accept: application/xmlContent-type: application/xml

<vm> <cluster> <name>cluster_name</name> </cluster> <name>NAME</name> ...</vm>

6. Attach the disk to the new virtual machine:


<disk id="11111111-1111-1111-1111-111111111111"></disk>

You have restored a virtual machine using a backup that was created using the backup and restoreAPI.

T echnical Guide

190

Chapter 24. Data Centers

24.1. Data Center Elements

The datacenters collection provides information about the data centers in a Red Hat EnterpriseVirtualization 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 Descript ion Propert iesname string A plain text, human-readable

name for the data center. Thename is unique across alldata center resources.

description string A plain text, human-readabledescription of the data center

link rel="storagedomains"

relationship A link to the sub-collectionfor storage domainsattached to this data center.

link rel="clusters" relationship A link to the sub-collectionfor clusters attached to thisdata center.

link rel="networks" relationship A link to the sub-collectionfor networks available to thisdata center.

link rel="permissions"

relationship A link to the sub-collectionfor data center permissions.

link rel="quotas" relationship A link to the sub-collectionfor quotas associated withthis data center.

local Boolean: true orfalse

Specifies whether the datacenter is a local data center,such as created in all-in-oneinstances.

storage_format enumerated Describes the storage formatversion for the data center. Alist of enumerated values areavailable in capabilities.

version major= minor= complex The compatibility level of thedata center.

supported_versions complex A list of possible versionlevels for the data center,including version major= minor= .

status see below The data center status.

Chapt er 2 4 . Dat a Cent ers

191

The status contains one of the following enumerated values: uninitialized , up, maintenance,not_operational , problematic and contend . These states are listed in data_center_statesunder capabilities.

24.2. XML Representat ion of a Data Center

Example 24 .1. An XML representat ion 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 Representat ion of a Data Center

Example 24 .2. A JSON representat ion of a data center

{ "data_center" : [ { "local" : "false", "storage_format" : "v3", "version" : { "major" : "3", "minor" : "5" }, "supported_versions" : { "version" : [ { "major" : "3", "minor" : "5"

T echnical Guide

192

} ] }, "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. Creat ing a New Data Center

Creation of a new data center requires the name and local elements.

Example 24 .3. Creat ing a data center

POST /api/datacenters HTTP/1.1Accept: application/xmlContent-type: application/xml


193

<data_center> <name>NewDatacenter</name> <local>false</local></data_center>

24 .4 .2. Updat ing a Data Center

The name, description, storage_type, version and storage_format elements are updatablepost-creation.

Example 24 .4 . Updat ing a data center

PUT /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-type: application/xml

<data_center> <name>UpdatedName</name> <description>An updated description for the data center</description></data_center>

24 .4 .3. Removing a Data Center

Removal of a data center requires a DELETE request.

Example 24 .5. Removing a data center

DELETE /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

24.5. Sub-Collect ions

24 .5.1. Storage Domains Sub-Collect ion

24.5 .1 .1 . St o rage Do mains Sub-Co llect io n

Each data center contains a sub-collection for attached storages domain. An API user interacts withthis sub-collection using the standard REST methods.

An attached storage domain has a similar representation to a top-level storage domain, with theexception that it has a data center specific status and set of actions. States for the status elementare listed in storage_domain_states under capabilities.

T echnical Guide

194

Important

The API as documented in this section is experimental and subject to change. It is not coveredby the backwards compatibility statement.

24.5 .1 .2 . At t aching and Det aching a St o rage Do main

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 astorage domain to a data center:

Example 24 .6 . At tach a storage domain to a data center

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1Accept: application/xmlContent-type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>

HTTP/1.1 201 CreatedLocation: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819edContent-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/


195

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 asyncelement for this request to be asynchronous.

Example 24 .7. Detach a storage domain f rom a data center

DELETE /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <async>true</async></action>

24.5 .1 .3. Act io ns

24 .5.1.3.1. Act ivate Storage Domain Act ion

An attached storage domain requires activation on a data center before use. The activate actiondoes not take any action specific parameters.

Example 24 .8. Act ion to act ive a storage domain on a datacenter

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

24 .5.1.3.2. Deact ivate Storage Domain Act ion

An attached storage domain is deactivated on a data center before removal. The deactivate actiondoes not take any action specific parameters.

Example 24 .9 . Act ion to deact ivate a storage domain on a datacenter

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate HTTP/1.1Accept: application/xml

T echnical Guide

196

Content-type: application/xml

<action/>

24 .5.2. Network Sub-Collect ion

24.5 .2 .1 . Net wo rks Sub-Co llect io n

Networks associated with a data center are represented with the networks sub-collection. Therepresentation of a data center's network sub-collection contains the following elements:

Table 24 .2. Network elements

Element Type Descript ionname 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. Associat ing a network resource with a data center

POST /api/datacenters/00000000-0000-0000-0000-000000000000/networks HTTP/1.1Accept: application/xmlContent-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"> <name>rhevm</name></network>

HTTP/1.1 201 CreatedLocation: http://{host}/clusters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000


197

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. Set t ing the network maximum t ransmission unit

PUT /api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-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 associat ion f rom a data center

DELETE /api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1


24 .5.3. Quotas Sub-Collect ion

24.5 .3.1 . Quo t as Sub-Co llect io n

T echnical Guide

198

The quotas sub-collection lists restrictions that Red Hat Enterprise Virtualization Managerimplements on resources. An API user views this sub-collection and its resources using the GETmethod.

Example 24 .13. An XML representat ion 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 . Creat ing a quota

POST /api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c/quotas HTTP/1.1Accept: application/xmlContent-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


24.6. Act ions

24 .6.1. Force Remove Data Center Act ion

An API user forces the removal of a data center when encountering unresolvable problems withstorage domains, such as the loss of connection to a master storage domain or a lack of availablehosts when deleting storage domains. The API includes a force action to help with these situations.


199

This action removes database entries associated with a chosen data center before the API removesthe data center from the Red Hat Enterprise Virtualization environment. This means the API removesthe data center regardless of associated storage domains.

This action requires a DELETE method. The request body contains an action representation withthe 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 act ion on a data center

DELETE /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <force>true</force></action>

This action:

Deletes all database information for data storage 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 iso and export storage 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 beforereuse. Metadata for iso and export domains require manual cleaning prior to use onanother data center.

T echnical Guide

200

Chapter 25. Clusters

25.1. Cluster Elements

The clusters collection provides information about clusters in a Red Hat Enterprise Virtualizationenvironment. An API user accesses this information through the rel="clusters" link obtained fromthe entry point URI.

The following table shows specific elements contained in a cluster resource representation.

Table 25.1. Cluster elements

Element Type Descript ion Propert ies

name string A user-supplied, human-readablename for the cluster. The name isunique 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 fornetworks associated with thiscluster.


relationship A link to the sub-collection forcluster permissions.

link rel="glustervolumes"

relationship A link to the sub-collection for RedHat Gluster Storage volumesassociated with this cluster.

link rel="glusterhooks"

relationship A link to the sub-collection for RedHat Gluster Storage volume hooksassociated with this cluster.

link rel="affinitygroups"

relationship A link to the sub-collection forvirtual machine affinity groupsassociated with this cluster.

cpu id= complex A server CPU reference that definesthe CPU type all hosts must supportin the cluster.

data_center id= GUID A reference to the data centermembership of this cluster.

memory_policy complex Defines the cluster's policy on hostmemory utilization.

scheduling_policy

complex Defines the load-balancing orpower-saving modes for hosts inthe cluster.

version major= minor=

complex The compatibility level of thecluster.

supported_versions

complex A list of possible version levels forthe cluster.

Chapt er 2 5. Clust ers

201

error_handling complex/enumerated Defines virtual machine handlingwhen a host within a clusterbecomes non-operational. Requiresa single on_error elementcontaining an enumerated typeproperty listed in capabilities.

virt_service Boolean Defines whether to exposevirtualization services for thiscluster.

gluster_service Boolean Defines whether to expose Red HatGluster Storage services for thiscluster.

threads_as_cores Boolean Defines whether hosts can runvirtual machines with a totalnumber of processor cores greaterthan the number of cores in thehost.

tunnel_migration Boolean Defines whether virtual machinesuse a libvirt-to-libvirt tunnel duringmigration.

trusted_service Boolean Defines whether an OpenAttestationserver is used to verify hosts.

ballooning_enabled

Boolean Defines whether ballooning isenabled for the cluster.

ksm Boolean Defines whether ksm is enabled forthe 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 MemoryOvercommit Manager log file. An event will also be added to the event log if a virtual machinedoes not respect a balloon.

25.2. Memory Policy Elements

The memory_policy element contains the following elements:

Table 25.2. Memory policy elements


T echnical Guide

202

overcommit percent= complex The percentage of host memoryallowed in use before no morevirtual machines can start on ahost. Virtual machines can usemore than the available hostmemory due to memory sharingunder KSM. Recommended valuesinclude 100 (None), 150 (ServerLoad) and 200 (Desktop Load).

transparent_hugepages complex Define the enabled status ofTransparent Hugepages. Thestatus is either true or false. Check capabilities feature set toensure your version supports transparent hugepages.


25.3. Scheduling Policy Elements

The scheduling_policy element contains the following elements:

Table 25.3. Scheduling policy elements


policy enumerated The VM scheduling mode for hostsin the cluster. A list of enumeratedtypes are listed in capabilities.

thresholds low= high= duration=

complex Defines CPU limits for the host. The high attribute controls the highestCPU usage percentage the hostcan have before being consideredoverloaded. The low attributecontrols the lowest CPU usagepercentage the host can havebefore being consideredunderutilized. The durationattribute refers to the number ofseconds the host needs to beoverloaded before the schedulerstarts and moves the load toanother host.

25.4 . XML Representat ion of a Cluster

Example 25.1. An XML representat ion of a cluster

<cluster id="00000000-0000-0000-0000-000000000000" href="/api/clusters/00000000-0000-0000-0000-000000000000"> <name>Default</name>


203

<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 Representat ion of a Cluster

Example 25.2. A JSON representat ion of a cluster

T echnical Guide

204

{ "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",


205

"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. Creat ing 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. Creat ing a cluster

POST /api/clusters HTTP/1.1Accept: application/xmlContent-type: application/xml

<cluster> <name>cluster1</name> <cpu id="Intel Penryn Family"/> <data_center id="00000000-0000-0000-0000-000000000000"/></cluster>

25.6.2. Updat ing a Cluster

The name, description, cpu id= and error_handling elements are updatable post-creation.

Example 25.4 . Updat ing a cluster

PUT /api/clusters/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-type: application/xml

T echnical Guide

206

<cluster> <description>Cluster 1</description></cluster>

25.6.3. Removing a Cluster

Removal of a cluster requires a DELETE request.

Example 25.5. Removing a cluster

DELETE /api/clusters/00000000-0000-0000-0000-000000000000 HTTP/1.1



25.7.1. Networks Sub-Collect ion

25.7 .1 .1 . Net wo rks Sub-Co llect io n

Networks associated with a cluster are represented with the networks sub-collection. Every hostwithin a cluster connects to these associated networks.

The representation of a cluster's network sub-collection is the same as a standard networkresource except for the following additional elements:

Table 25.4 . Addit ional network elements


cluster id= relationship A reference to the cluster of whichthis network is a member.

required Boolean Defines required or optionalnetwork status.

display Boolean Defines the display network status.Used for backward compatibility.

usages complex Defines a set of usage elements forthe network. Users can definenetworks as VM and DISPLAYnetworks at this level.

An API user manipulates the networks sub-collection with the standard REST methods. POST ing anetwork id or name reference to the networks sub-collection associates the network with the cluster.

Example 25.6 . Associat ing a network resource with a cluster

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1


207

Accept: application/xmlContent-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"> <name>rhevm</name></network>

HTTP/1.1 201 CreatedLocation: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665fContent-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. Set t ing the d isplay network status

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1Accept: application/xmlContent-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 (trueor false) of the required element.

Example 25.8. Set t ing opt ional network status

T echnical Guide

208

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1Accept: application/xmlContent-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 associat ion f rom a cluster

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1


25.7.2. Storage Volumes Sub-Collect ion

25.7 .2 .1 . Red Hat Glust er St o rage Vo lumes Sub-Co llect io n

Red Hat Enterprise Virtualization provides a means for creating and managing Red Hat GlusterStorage volumes. Red Hat Gluster Storage volumes are associated with clusters and are representedwith 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. G luster vo lume elements


volume_type enumerated Defines the volume type. See the capabilities collection for a listof volume types.

bricks relationship The sub-collection for the Red HatGluster Storage bricks. Whencreating a new volume, the requestrequires a set of brick elements tocreate and manage in this cluster.Requires the server_id of the RedHat Gluster Storage server and a brick_dir element for the brickdirectory

transport_types complex Defines a set of volume transport_type elements. See thecapabilities collection for a listof available transport types.


209

replica_count integer Defines the file replication count fora replicated volume.

stripe_count integer Defines the stripe count for astriped volume

options complex A set of additional Red Hat GlusterStorage option elements. Each option includes an option nameand a value.


Example 25.10. An XML representat ion of a Red Hat G luster 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_typeand bricks to the sub-collection.

Example 25.11. Creat ing a Red Hat G luster Storage volume

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes HTTP/1.1Accept: application/xmlContent-Type: application/xml

<gluster_volume> <name>GlusterVolume1</name> <volume_type>DISTRIBUTED_REPLICATE</volume_type> <bricks> <brick> <server_id>server1</server_id>

T echnical Guide

210

<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 G luster Storage volume

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651 HTTP/1.1


Important

Resources in the glustervolumes sub-collection cannot be updated.

25.7 .2 .2 . Bricks Sub-Co llect io n

The glustervolumes sub-collection contains its own bricks sub-collection to define individualbricks in a Red Hat Gluster Storage volume. The representation of a volume's bricks sub-collectionis defined using the following elements:

Table 25.6 . Brick elements


server_id string A reference to the Red Hat GlusterStorage server.

brick_dir string Defines a brick directory on the RedHat Gluster Storage server.

replica_count integer Defines the file replication count forthe brick in the volume.

stripe_count integer Defines the stripe count for the brickin 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


211

Accept: application/xmlContent-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


Important

Resources in the bricks sub-collection cannot be updated.

25.7 .2 .3. Act io ns

25.7.2.3.1. Start Act ion

The start action makes a Gluster volume available for use.

Example 25.15. Start ing a Volume

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/start HTTP/1.1Accept: application/xmlContent-Type: application/xml

<action/>

Use an optional force Boolean element to force the action for a running volume. This is useful forstarting disabled brick processes in a running volume.

25.7.2.3.2. Stop Act ion

The stop action deactivates a Gluster volume.

Example 25.16 . Stopping a Volume

T echnical Guide

212

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/stop HTTP/1.1Accept: application/xmlContent-Type: application/xml

<action/>

Use an optional force Boolean element to brute force the stop action.

25.7.2.3.3. Set Opt ion Act ion

The setoption action sets a volume option.

Example 25.17. Set an opt ion

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/setoption HTTP/1.1Accept: application/xmlContent-Type: application/xml

<action> <option> <name>cluster.min-free-disk</name> <value>536870912</value> </option></action>

25.7.2.3.4 . Reset Opt ion Act ion

The resetoption action resets a volume option.

Example 25.18. Reset an opt ion

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetoption HTTP/1.1Accept: application/xmlContent-Type: application/xml

<action> <option> <name>cluster.min-free-disk</name> </option></action>

25.7.2.3.5. Reset All Opt ions Act ion

The resetalloptions action resets all volume options.


213

Example 25.19 . Reset all opt ions

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetalloptions HTTP/1.1Accept: application/xmlContent-Type: application/xml

<action/>

25.7.3. Affinity Groups Sub-Collect ion

25.7 .3.1 . Affinit y Gro up Sub-Co llect io n

The representation of a virtual machine affinity group resource in the affinitygroups sub-collection is defined using the following elements:

Table 25.7. Af f in ity group elements


name string A plain text, human readable namefor the affinity group.

cluster relationship A reference to the cluster to whichthe affinity group applies.

positive Boolean: true or false Specifies whether the affinity groupapplies positive affinity or negativeaffinity to virtual machines that aremembers of that affinity group.

enforcing Boolean: true or false Specifies whether the affinity groupuses hard or soft enforcement of theaffinity applied to virtual machinesthat are members of that affinitygroup.

Example 25.20. An XML representat ion of a virtual machine af f in ity 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.

T echnical Guide

214

Example 25.21. Creat ing a virtual machine af f in ity group

POST https://XX.XX.XX.XX/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups HTTP/1.1Accept: application/xmlContent-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 af f in ity group

DELETE https://XX.XX.XX.XX/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000 HTTP/1.1



215

Chapter 26. Networks

26.1. Network Elements

The networks collection provides information about the logical networks in a Red Hat EnterpriseVirtualization environment. An API user accesses this information through the rel="networks" linkobtained from the entry point URI.

The following table shows specific elements contained in a network resource representation.

Table 26 .1. Network elements


link rel="vnicprofiles"

relationship A link to the sub-collection for VNICprofiles attached to this logicalnetwork.

link rel="labels"

relationship A link to the sub-collection forlabels attached to this logicalnetwork.

data_center id= GUID A reference to the data center ofwhich 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 defaultvalue.

status One of operationalor non_operational

The status of the network. Thesestates are listed in network_states under capabilities.

usages complex Defines a set of usage elements forthe network. Users can definenetworks as VM networks at thislevel.

Important


26.2. XML Representat ion of a Network Resource

Example 26 .1. An XML representat ion of a network resource

<network href="/api/networks/00000000-0000-0000-0000-000000000000"

T echnical Guide

216

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 Representat ion of a Network Resource

Example 26 .2. A JSON representat ion 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",

Chapt er 2 6 . Net works

217

"rel" : "labels" } ] } ]}

26.4 . Methods

26.4 .1. Creat ing a Network Resource

Creation of a new network requires the name and datacenter elements.

Example 26 .3. Creat ing a network resource

POST /api/networks HTTP/1.1Accept: application/xmlContent-type: application/xml

<network> <name>network 1</name> <data_center id="00000000-0000-0000-0000-000000000000"/></network>

26.4 .2. Updat ing a Network Resource

The name, description, ip, vlan, stp and display elements are updatable post-creation.

Example 26 .4 . Updat ing a network resource

PUT /api/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-type: application/xml

<network> <description>Network 1</description></network>

26.4 .3. Removing a Network Resource

Removal of a network requires a DELETE request.

Example 26 .5. Removing a network

DELETE /api/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1


T echnical Guide

218

26.5. Sub-collect ions

26.5.1. Network VNIC Profile Sub-Collect ion

VNIC (Virtual Network Interface Controller) profiles, also referred to as virtual machine interfaceprofiles, are customized profiles applied to users and groups to limit network bandwidth. Each vnicprofile contains the following elements:

Table 26 .2. Elements for vn ic prof iles

Element Type Descript ionname 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

falseThe default is false.

Example 26 .6 . An XML representat ion of the network's vnicprof ile sub-collect ion

<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-Collect ion

Network labels are plain text, human-readable labels that allow you to automate the association oflogical networks with physical host network interfaces. Each label contains the following elements:

Table 26 .3. Elements for labels

Element Type Descript ionnetwork string The href and id of the networks to which the label is

attached.

Example 26 .7. An XML representat ion of the network's labels sub-collect ion

<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>

Chapt er 2 6 . Net works

219

26.5.3. Methods

26.5 .3.1 . At t ach Label t o Lo gical Net wo rk Act io n

You can attach labels to a logical network to automate the association of that logical network withphysical host network interfaces to which the same label has been attached.

Example 26 .8. Act ion to at tach a label to a logical network

POST /api/networks/00000000-0000-0000-0000-000000000000/labels/ HTTP/1.1Accept: application/xmlContent-type: application/xml

<label id="Label_001" />

26.5 .3.2 . Remo ving a Label Fro m a Lo gical Net wo rk

Removal of a label from a logical network requires a DELETE request.

Example 26 .9 . Removing a label f rom a logical network

DELETE /api/networks/00000000-0000-0000-0000-000000000000/labels/[label_id] HTTP/1.1


T echnical Guide

220

Chapter 27. Storage Domains

27.1. Storage Domain Elements

The storagedomains collection provides information about the storage domains in a Red HatEnterprise 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



relationship A link to the sub-collection forstorage domain permissions.

link rel="files" relationship A link to the files sub-collectionfor this storage domains.

link rel="vms" relationship A link to the vms sub-collection fora storage domain with type set to export.

link rel="templates"

relationship A link to the templates sub-collection for a storage domain withtype set to export.

type enumerated The storage domain type. A list ofenumerated values are available in capabilities.

master Boolean: true or false true if this is the master storagedomain of a data center.

host complex A reference to the host on which thisstorage domain should beinitialized. The only restriction onthis host is that it should haveaccess to the physical storagespecified.

storage complex Describes the underlying storage ofthe 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 formatversion for the storage domain. Alist of enumerated values areavailable in capabilities.

Chapt er 2 7 . St orage Domains

221

wipe_after_delete Boolean: true or false Sets the wipe after delete option bydefault on the storage domain. Thisoption can be edited after thedomain is created, but doing so willnot change the wipe after deleteproperty of disks that already exist.

warning_low_space_indicator

integer A percentage value that sets thewarning low space indicator option.If the free space available on thestorage domain is below thispercentage, warning messages aredisplayed to the user and logged.

critical_space_action_blocker

integer A value in GB that sets the criticalspace action blocker option. If thefree space available on the storagedomain is below this value, errormessages are displayed to the userand logged, and any new actionthat consumes space, eventemporarily, will be blocked.


Important

The API as documented in this chapter is experimental and subject to change. It is not coveredby the backwards compatibility statement.

27.2. XML Representat ion of a Storage Domain

Example 27.1. An XML representat ion 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>

T echnical Guide

222

<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 Representat ion of a Storage Domain

Example 27.2. A JSON representat ion 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" } ] } ]}


223

27.4 . Methods

27.4 .1. Creat ing a Storage Domain

Creation of a new storage domain requires the name, type, host and storage elements. Identify thehost element with the id attribute or name element.


Example 27.3. Creat ing a storage domain

POST /api/storagedomains HTTP/1.1Accept: application/xmlContent-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. Updat ing 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 . Updat ing a storage domain

PUT /api/storagedomains HTTP/1.1Accept: application/xmlContent-type: application/xml <storage_domain> <name>data2</name> ... <wipe_after_delete>true</wipe_after_delete> ...</storage_domain>

T echnical Guide

224

27.4 .3. Removing a Storage Domain

Removal of a storage domain requires a DELETE request.

Example 27.5. Removing a storage domain

DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1


27.5. Storage Types

27.5.1. Storage T ypes

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 fewsections 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 specif ic elements


address string The host name or IP address of theNFS server.

path string The path of NFS mountabledirectory on the server.

27.5.3. PosixFS Storage

The following table contains posixfs specific elements in a storage description.

Table 27.3. PosixFS specif ic elements


address string The host name or IP address of thePosixFS server.

path string The path of PosixFS mountabledirectory on the server.

vfs_type string The Linux-supported file systemtype of the PosixFS share.


225

mount_options string The options for mounting thePosixFS 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 specif ic elements


logical_unit id= complex The id of the logical unit. A storagedomain also accepts multiple iSCSIor FCP logical units.

override_luns Boolean Defines whether to replace alllogical unit settings with newsettings. Set to true to override.

The logical_unit contains a set of sub-elements.

Table 27.5. Logical unit elements


address string The address of the servercontaining the storage device.

port integer The port number of the server.

target string The target IQN for the storagedevice.

username string A CHAP user name for logging intoa target.

password string A CHAP password for logging intoa 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 devicemapping for the target.

In the case of iSCSI, if a logical_unit description also contains details of the iSCSI target withthe LUN in question, the target performs an automatic login when the storage domain is created.

T echnical Guide

226

27.5.5. LocalFS Storage

The localfs specific elements in a storage description are:

Table 27.6 . Localfs specif ic elements


path string The path of local storage domainon the host.

A localfs storage domain requires a data center with storage_type set to localfs. This datacenter 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 listthe import candidate VMs and templates stored on that particular storage domain.

Example 27.6 . List ing the virtual machines sub-collect ion of an export storagedomain

GET /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vmsAccept: 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.


227

The import action imports a virtual machine or a template from an export storage domain. Thedestination cluster and storage domain is specified with cluster and storage_domainreferences.

Include an optional name element to give the virtual machine or template a specific name.

Example 27.7. Act ion to import a virtual machine f rom an export storage domain

POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <storage_domain> <name>images0</name> </storage_domain> <cluster> <name>Default</name> </cluster></action>

Example 27.8. Act ion to import a template f rom an export storage domain

POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/templates/082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1Accept: application/xmlContent-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 . Act ion to import a virtual machine as a new ent ity


<action> <storage_domain> <name>images0</name> </storage_domain>

T echnical Guide

228

<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 idelements.

Example 27.10. Select ing d isks for an import act ion


<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 f rom an export storage domain

DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1Accept: application/xml


27.7. Glance Image Storage Domains

27.7.1. Glance Image Storage Domains


229

Storage domains with type set to Image represent instances of an OpenStack image service that hasbeen added to the Red Hat Enterprise Virtualization environment as an external provider. TheseGlance image storage domains contain an images sub-collection with virtual machine images thathave been exported to or can be imported from that Glance image storage domain.

Example 27.12. List ing the images sub-collect ion of a G lance image storage domain

GET /api/storagedomains/00000000-0000-0000-0000-000000000000/imagesAccept: 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. Thedestination storage domain is specified with a storage_domain reference, and the destinationcluster with a cluster reference.

Include an optional name element to give the virtual machine or template a specific name.

Example 27.13. Act ion to import a virtual machine f rom a G lance image storagedomain

T echnical Guide

230

POST /api/storagedomains/00000000-0000-0000-000000000000/images/00000000-0000-0000-000000000000/import HTTP/1.1Accept: application/xmlContent-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 . Act ion to import a virtual machine f rom a G lance image storagedomain as a template

POST /api/storagedomains/00000000-0000-0000-000000000000/images/00000000-0000-0000-000000000000/import HTTP/1.1Accept: application/xmlContent-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.1. Files Sub-Collect ion

The files sub-collection under each storage domain provides a way for clients to list availablefiles. This sub-collection is specifically targeted to ISO storage domains, which contain ISO imagesand virtual floppy disks (VFDs) that an administrator uploads through Red Hat EnterpriseVirtualization Manager.

The addition of a CD-ROM device to a VM requires an ISO image from the files sub-collection ofan ISO storage domain.

Example 27.15. List ing the f iles sub-collect ion of an ISO storage domain

GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1


231

Accept: 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 thefilename.

27.9. Act ions

27.9.1. Import ing an Exist ing Storage Domain

The API provides a user with the ability to remove an ISO or Export storage domain from one Red HatEnterprise Virtualization Manager instance without re-formatting the underlying storage and import itinto another instance. Importing is achieved similarly to adding a new storage domain, except the name is not specified.

Example 27.16 . Import ing an exist ing export storage domain

POST /api/storagedomains HTTP/1.1Accept: application/xmlContent-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>

T echnical Guide

232

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/></storage_domain>


<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed" href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"> <name>export1</name> ...</storage_domain>

27.9.2. Delet ing a Storage Domain

A storage_domain reference is passed in the body of a DELETE request for a storage domain. Thestorage_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 storagedomain after deletion.

Example 27.17. Format t ing a storage domain af ter delet ion

<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 thestorage domain's data for import. Use the destroy element to logically remove the storage domainand retain the data.

Example 27.18. Logical removal o f a storage domain


233

<storage_domain> <host id="..."/> <destroy>true</destroy></storage_domain>

T echnical Guide

234

Chapter 28. Storage Connections

28.1. Storage Connect ion Elements

Table 28.1. Storage Connect ion Base Elements


type One of nfs, posixfs,local , or iscsi

The type of storage domain.

address string The hostname or IP address of thestorage domain.

(Onlyrequiredfor NFSand iSCSI)

host string The id or name of the hypervisor.The host is optional. Providing itwill attempt a connection to thestorage via the host; not providingit will lead to persisting storagedetails in the database.

Table 28.2. Storage Connect ion File-based Storage Elements


path string The mounted file path of the storagedomain. The path cannot beupdated to one already used by astorage connection.

mount_options string The options for mounting thePosixFS share.

vfs_type string The Linux-supported file systemtype 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 requestto complete.

nfs_retrans integer The number of retransmissions theNFS client will attempt to complete arequest.

Table 28.3. Storage Connect ion iSCSI elements


port integer The TCP port used for the iSCSIstorage domain.

Chapt er 2 8 . St orage Connect ions

235

target string The target IQN for the storagedevice.

username string A CHAP user name for logging intoa target.

password string A CHAP password for logging intoa target.


28.2. XML representat ion of a Storage Connect ion Resource

Example 28.1. An XML representat ion of a storage connect ion 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. Creat ing a New Storage Connect ion

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. Creat ing a New Storage Connect ion

POST /api/storageconnections HTTP/1.1Accept: application/xmlContent-type: application/xml

<storage_connection> <type>nfs</type> <address>domain.example.com</address> <path>/export/storagedata/username/data</path>

T echnical Guide

236

<host> <name>Host_Name</name> </host></storage_connection>

28.3.2. Delet ing a Storage Connect ion

Deleting a storage connection requires a DELETE request. A storage connection can only be deletedif 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. Delet ing Storage Connect ion

DELETE /api/storageconnections/Storage_Connection_ID HTTP/1.1Accept: application/xmlContent-type: application/xml

<host> <name>Host_Name</name></host>

28.3.3. Updat ing a Storage Connect ion

Updating an existing storage connection requires a PUT request. The storage domain must be ineither 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 updatedstorage details.

Example 28.4 . Updat ing a Storage Connect ion

PUT /api/storageconnections/Storage_Connection_ID HTTP/1.1Accept: application/xmlContent-type: application/xml

<storage_connection> <address>updated.example.domain.com</address> <host> <name>Host_name</name> </host></storage_connection>

28.3.4 . Updat ing an iSCSI Storage Connect ion

Updating an existing iSCSI storage connection requires a PUT request. An iSCSI storage domainmust be in maintenance mode or unattached to successfully update the connection.


237

Example 28.5. Updat ing a Storage Connect ion

PUT /api/storageconnections/Storage_Connection_ID HTTP/1.1Accept: application/xmlContent-type: application/xml

<storage_connection> <port>3456</port></storage_connection>

28.3.5. Adding New Storage Domain with Exist ing Storage Connect ion

Adding a new storage domain with existing storage connection requires a POST request. This is onlyapplicable with file-based storage domains: NFS, POSIX, and local .

Example 28.6 . Adding a New Storage Domain with Exist ing Storage Connect ion


<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. At taching an Addit ional Storage Connect ion to iSCSI Storage

Attaching an additional storage connection to an iSCSI storage domain requires a POST request.

Example 28.7. At taching an Addit ional Storage Connect ion to iSCSI Storage

POST /api/storagedomains/iSCSI_Domain_ID/storageconnections HTTP/1.1Accept: application/xmlContent-type: application/xml

<storage_connection id="Storage_Connection_ID"></storage_connection>

28.3.7. Detaching a Storage Connect ion from iSCSI Storage

Detaching a storage connection from an iSCSI storage domain requires a DELETE request.

T echnical Guide

238

Example 28.8. Detaching a Storage Connect ion f rom iSCSI Storage

DELETE /api/storagedomains/iSCSI_Domain_ID/storageconnections/Storage_Connection_ID HTTP/1.1Accept: application/xmlContent-type: application/xml


239

Chapter 29. Hosts

29.1. Host Elements

The hosts collection provides information about the hosts in a Red Hat Enterprise Virtualizationenvironment. An API user accesses this information through the rel="hosts" link obtained from theentry point URI.

The following table shows specific elements contained in a host resource representation.

Table 29 .1. Host elements


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 forhost network interfaces.

link rel="tags" relationship A link to the tags sub-collection forhost tags.


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-collectionfor host hooks.

name string The unique identifier for the host. root_password string The root password of this host, by

convention only included in theclient-provided host representationon 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 certificatedetails, including organizationand subject.

status See below The host status.

cluster id= GUID A reference to the cluster thatincludes this host.

port integer The listen port of the VDSM daemonrunning on this host.

type One of rhel or rhev-h

The host type.

storage_manager priority=

Boolean: true orfalse

Specifies whether the host is astorage manager.

version major= minor= build= revision= full_version=

complex The compatibility level of the host.

T echnical Guide

24 0

hardware_information complex Information regarding the hardwareof the host, including manufacturer, version, serial_number, product_name, uuid , and family.

power_management type=

complex Configuration options for hostpower management, including enabled , options, kdump_detection, automatic_pm_enabled , and agents. See Section 29.4, “PowerManagement Elements” for moreinformation on the host powermanagement options.

ksm Boolean: true orfalse

true if Kernel SamePage Merging(KSM) is enabled.

transparent_hugepages Boolean: true orfalse

true if Transparent Hugepages isenabled.

iscsi complex The SCSI initiator for the host.

ssh complex Details regarding the SSHconnection with the host, including port and fingerprint.

cpu complex Statistics for the host CPU. Includessub-elements for the CPU's name, topology cores= , topology sockets= , topology threads=and speed . The topology cores= aggregates the total coreswhile the topology sockets=aggregates the total physical CPUs.The total cores available to virtualmachines equals the number ofsockets multiplied by the cores persocket.

memory integer The total amount of host memory inbytes.

max_scheduling_memory integer The maximum amount of memorythat can be used in scheduling inbytes.

summary complex Summary statistics of the virtualmachines on the host. Includessub-elements for numbers of active, migrating and totalVMs.

os type= complex Details regarding the operatingsystem installed on the host,including version full_version= .


Chapt er 2 9 . Host s

24 1

libvirt_version major= minor= build= revision= full_version=

complex The libvirt compatibility level of thehost.


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 Representat ion of a Host

Example 29 .1. An XML representat ion 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"

T echnical Guide

24 2

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>


24 3

<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 Representat ion of a Host

Example 29 .2. A JSON representat ion 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" ] }

T echnical Guide

24 4

}, "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" },


24 5

"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"

T echnical Guide

24 6

}, { "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 managementconfiguration, which is required for host fencing. Certain sub-elements are required when configuringpower_management.

Table 29 .2. Power management opt ions


type= fencing device code A list of valid fencing device codesare available in the capabilities collection.

enabled Boolean: true or false Indicates whether powermanagement configuration isenabled or disabled.

address string The host name or IP address of thehost.

username string A valid user name for powermanagement.

password string A valid, robust password for powermanagement.

options complex Fencing options for the selected type= specified with the option name="" and value="" strings.


24 7

agents complex Specifies fence agent options whenmultiple fences are used. Use the order sub-element to prioritize thefence agents. Agents are runsequentially according to theirorder until the fence actionsucceeds. When two or more fenceagents have the same order, theyare run concurrently. Other sub-elements include type, ip, user, password , and options.

automatic_pm_enabled

Boolean: true or false Toggles the automated powercontrol of the host in order to saveenergy. When set to true, the hostwill be automatically powered downif the cluster's load is low, andpowered on again when required.This is set to true when a host iscreated, unless disabled by theuser.

kdump_detection Boolean: true or false Toggles whether to determine ifkdump is running on the hostbefore it is shut down. When set to true, the host will not shut downduring a kdump process. This is setto true when a host has powermanagement enabled, unlessdisabled 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 POST ing to the hostresource. The power_management configuration is updatable using a PUT request.

Example 29 .3. An XML representat ion of a host 's power management conf igurat ion

<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>

T echnical Guide

24 8

<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 identicalpages to a single page reference. This helps with optimization for memory density. KSM uses the ksmelement.

Example 29 .4 . Set t ing KSM memory management

PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1Accept: application/xmlContent-Type: application/xml

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3" href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"> <ksm>true</ksm></host>


24 9

Transparent Hugepage support expands the size of memory pages beyond the standard 4kBlimit. This reduces memory consumption and increases host performance. Transparent Hugepagesupport uses the transparent_hugepages element.

Example 29 .5. Set t ing Transparent Hugepage memory management

PUT /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3 HTTP/1.1Accept: application/xmlContent-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. Creat ing a Host

Creation of a new host requires the name, address and root_password elements.

Example 29 .6 . Creat ing a host

POST /api/hosts HTTP/1.1Accept: application/xmlContent-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 EnterpriseVirtualization 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 notexposed in the representations returned from subsequent requests.

29.6.2. Updat ing a Host

The name, description, cluster, power_management, transparent_hugepages and ksmelements are updatable post-creation.

Example 29 .7. Updat ing a host

POST /api/hosts/00000000-0000-0000-0000-000000000000 HTTP/1.1

T echnical Guide

250

Accept: application/xmlContent-type: application/xml

<host> <name>host3</name></host>

29.6.3. Removing a Host

Removal of a host requires a DELETE request.

Example 29 .8. Removing a host

DELETE /api/hosts/00000000-0000-0000-0000-000000000000 HTTP/1.1



29.7.1. Host Network Interface Sub-Collect ion

29.7 .1 .1 . Ho st Net wo rk Int erface Sub-Co llect io n

The nics sub-collection represents a host's physical network interfaces. Each host_nic element inthe representation acts as a network interface and contains the following elements:

Table 29 .3. Elements for a host 's network in terfaces


name string The name of the host networkinterface, e.g. eth0 .

link rel="statistics"

relationship A link to the statistics sub-collection for a host's networkinterface statistics.

link rel="labels"

relationship A link to the labels sub-collectionfor a host's network interface labels.

link rel="master" relationship A reference to the master bondedinterface, 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.

[a]

[b ]


251

mac address= string The MAC address of the interface.

ip address= netmask= gateway= mtu=

complex The IP level configuration of theinterface.

mtu complex The maximum transmission unit forthe interface.

boot_protocol enumerated The protocol for IP addressassignment when the host isbooting. A list of enumerated valuesis available in capabilities.

status enumerated The link status for the networkinterface. These states are listed in host_nic_states under capabilities.

vlan id integer The VLAN which this interfacerepresents.

bonding complex A list of options and slave NICsfor bonded interfaces.

bridged Boolean Defines the bridged network status.Set to true for a bridged networkand false for a bridgelessnetwork.

properties complex Defines custom property keys forbridge options of the network. Each property contains name and value sub-elements.


Example 29 .9 . An XML representat ion of a network in terface 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>

[c ]

[a] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b ead d ed .

[b ] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b ead d ed .

[c] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b ead d ed .

T echnical Guide

252

<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 containupdatable 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.1Accept: application/xmlContent-type: application/xml

<host_nic> <name>MyNIC</name> <network id="00000000-0000-0000-0000-000000000000"> <name>MyNetwork</name> </network></host_nic>


253

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.1Accept: application/xmlContent-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


29.7 .1 .2 . Bo nded Int erfaces

A bonded interface is represented as a host_nic resource containing a bonding element.

Table 29 .4 . Bonded interface propert ies


options complex A list of option elements for abonded interface. Each optioncontains property name and valueattributes.

slaves complex A list of slave host_nic id=elements for a bonded interface.

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. Creat ing a bonded interface

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics HTTP/1.1Accept: application/xmlContent-Type: application/xml

<host_nic> <name>bond4</name> <network id="e657d631-657d-42bb-a536-73501a085d85"/>

[a]

[b ]

[a] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b ead d ed .

[b ] Only req uired when ad d ing b o nd ed interfaces. O ther interfaces are read -o nly and canno t b ead d ed .

T echnical Guide

254

<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. Net wo rk Int erface Cust o m Pro pert ies

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 requestwith the setupnetworks action.

Table 29 .5. Elements for custom bridge opt ions for a host 's network in terface

Element Type Descript ionname string The unique identifier for the property. Bridge options

have the set name of bridge_opts.


255

value string The bridge options, represented by a valid key andvalue with the following syntax: [key]=[value]. Separatemultiple entries with a whitespace character. Thefollowing keys are valid, with the values provided asexamples:forward_delay=1500gc_timer=3765 group_addr=1:80:c2:0:0:0group_fwd_mask=0x0hash_elasticity=4hash_max=512hello_time=200hello_timer=70max_age=2000multicast_last_member_count=2multicast_last_member_interval=100multicast_membership_interval=26000multicast_querier=0multicast_querier_interval=25500multicast_query_interval=13000multicast_query_response_interval=1000multicast_query_use_ifaddr=0multicast_router=1multicast_snooping=1multicast_startup_query_count=2multicast_startup_query_interval=3125

Element Type Descript ion

Example 29 .11. An XML representat ion of a host 's network in terface propert ies sub-collect ion

<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 . Net wo rk Int erface St at ist ics

Each host's network interface exposes a statistics sub-collection for a host's network interfacestatistics. Each statistic contains the following elements:

Table 29 .6 . Elements for a host 's network in terface stat ist ics

T echnical Guide

256

Element Type Descript ionname 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

COUNTERThe 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 stat ist ic types

Name Descript iondata.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 representat ion of a host 's network in terface stat ist ics sub-collect ion

<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.


257

29.7 .1 .5 . Act io ns

29 .7.1.5.1. At tach Network In terface Card to Host Act ion

A host network interface card is attached to a network, indicating the given network is accessible overthat network interface card. Either the id or name elements identify the network to which the networkinterface card will be attached.

Example 29 .13. Act ion to at tach a host network in terface card to a network

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach HTTP/1.1Accept: application/xmlContent-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 In terface Card f rom Host Act ion

Detach a network interface card from a network. Either the id or name elements identify the networkfrom which the network interface card will be detached.

Example 29 .14 . Act ion to detach a host network in terface card f rom a network

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach HTTP/1.1Accept: application/xmlContent-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. Mult ip le Network Setup Act ion

A host's nics collection contains an action to perform setup of multiple network interfaces. Perform aPOST request on the setupnetworks action.

T echnical Guide

258

Example 29 .15. Act ion to setup mult ip le host network in terfaces

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/setupnetworks HTTP/1.1Accept: application/xmlContent-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. Therequest includes additional elements specified in the following table.

Table 29 .8. Addit ional elements for mult ip le host network in terface setup

Element Type Descript ioncheckConnectivity Boolean Set to true to verify connectivity between

the host and the Red Hat EnterpriseVirtualization Manager. If theconnectivity is lost, Red Hat EnterpriseVirtualization Manager reverts thesettings.

connectivityTimeout integer Defines the timeout for loss ofconnectivity.

force Boolean Set to true to force changes even ifconnectivity is lost.

29 .7.1.5.4 . At tach Label to Network In terface Card Act ion

You can attach labels to the network interface card of a host to automate the association of thatnetwork interface card with logical networks to which the same label has been attached.

Example 29 .16 . Act ion to at tach a label to a network in terface card

POST /api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-


259

0000-0000-0000-000000000000/labels HTTP/1.1Accept: application/xmlContent-type: application/xml

<label id="Label_001" />

29 .7.1.5.5. Removing a Label From a Network In terface Card

Removal of a label from a physical host network interface card requires a DELETE request.

Example 29 .17. Removing a label f rom a network in terface card

DELETE /api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels/[label_id] HTTP/1.1


29.7.2. Storage Sub-Collect ion

29.7 .2 .1 . St o rage Sub-Co llect io n

The storage sub-collection provides a list of the iSCSI and FCP storage representations availableon 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 representat ion of the storage sub-collect ion 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.

T echnical Guide

260

Important


29.7.3. Host NUMA Nodes Sub-Collect ion

29.7 .3.1 . NUMA No des Sub-Co llect io n

The numanodes sub-collection represents the host's NUMA topology. Each host_numa_nodeelement in the sub-collection represents a NUMA node.

Example 29 .19 . An XML representat ion of the numanodes sub-collect ion 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>


261

</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 No de St at ist ics

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 stat ist ics





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 stat ist ics

Name Descript ionmemory.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 representat ion of the host NUMA node's stat ist ics sub-collect ion

<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">

T echnical Guide

262

<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 Stat ist ics Sub-Collect ion

29.7 .4 .1 . Ho st St at ist ics Sub-Co llect io n

Each host resource exposes a statistics sub-collection for host-specific statistics. Each statistic contains the following elements:

Table 29 .11. Elements for host stat ist ics





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 stat ist ic types

Name Descript ionmemory.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.


263

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.

Name Descript ion

Example 29 .21. An XML representat ion of the host 's stat ist ics sub-collect ion

<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. Act ions

29.8.1. Install VDSM Act ion

Install VDSM and related software on the host. The host type defines additional parameters for theaction.

Red Hat Enterprise Linux host - This host type requires a root_password element thatrefers to the password for the host's root user.

T echnical Guide

264

Red Hat Enterprise Virtualiz at ion 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. Act ion to install VDSM to a Red Hat Enterprise Linux host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <root_password>p@55w0Rd!</root_password></action>

Example 29 .23. Act ion to install VDSM to a Red Hat Enterprise Virtualiz at ionHypervisor host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/install HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <image>/usr/share/rhev-hypervisor/rhev-hypervisor.iso</image></action>

29.8.2. Act ivate Host Act ion

Activate the host for use, such as running virtual machines.

Example 29 .24 . Act ion to act ivate a host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/activate HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

29.8.3. Fence Host Act ion

An API user controls a host's power management device with the fence action. The capabilitieslists available fence_type options.

Example 29 .25. Act ion to fence a host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/fenceAccept: application/xmlContent-Type: application/xml


265

<action> <fence_type>start</fence_type></action>

29.8.4 . Deact ivate Host Act ion

Deactivate the host to perform maintenance tasks.

Example 29 .26 . Act ion to deact ivate a host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/deactivate HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

29.8.5. Approve Host Act ion

Approve a pre-installed Red Hat Enterprise Virtualization Hypervisor host for usage in thevirtualization environment. This action also accepts an optional cluster element to define the targetcluster for this host.

Example 29 .27. Act ion to approve a host

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/approve HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/></action>

29.8.6. Host iSCSI Login Act ion

The iscsilogin action enables a host to login to an iSCSI target. Logging into a target makes thecontained LUNs available in the host_storage collection.

Example 29 .28. Act ion to enable a host to login to iSCSI target

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsilogin HTTP/1.1Accept: application/xmlContent-Type: application/xml

<action> <iscsi> <address>mysan.example.com</address>

T echnical Guide

266

<target>iqn.2009-08.com.example:mysan.foobar</target> <username>jimmy</username> <password>s3kr37</password> </iscsi></action>

29.8.7. Host iSCSI Discover Act ion

The iscsidiscover action enables an iSCSI portal to be queried for its list of targets.

Example 29 .29 . Act ion to query a list o f targets for iSCSI portal

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/iscsidiscover HTTP/1.1Accept: application/xmlContent-Type: application/xml

<action> <iscsi> <address>mysan.example.com</address> <port>3260</port> </iscsi></action>

29.8.8. Commit Host Network Configurat ion Act ion

An API user commits the network configuration to persist a host network interface attachment ordetachment, or persist the creation and deletion of a bonded interface.

Example 29 .30. Act ion to commit network conf igurat ion

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/commitnetconfig HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

Important

Networking configuration is only committed after the Manager has established that hostconnectivity is not lost as a result of the configuration changes. If host connectivity is lost, thehost requires a reboot and automatically reverts to the previous networking configuration.

29.8.9. Set t ing SPM


267

Manually set a host as the Storage Pool Manager (SPM).

Example 29 .31. Act ion to Set Host as SPM

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/forceselectspm HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

T echnical Guide

268

Chapter 30. Virtual Machines

30.1. Virtual Machine Elements

The vms collection provides information about virtual machines in a Red Hat Enterprise Virtualizationenvironment. An API user accesses this information through the rel="vms" link obtained from theentry point URI.

The following table shows specific elements contained in a virtual machine resource representation.

Table 30.1. Virtual machine elements


link rel="applications"

relationship A link to the applications sub-collection forvirtual machine resources, which shows theapplications installed on the virtual machine.

link rel="disks"

relationship A link to the disks sub-collection for virtualmachine resources.

link rel="nics"

relationship A link to the nics sub-collection for virtualmachine resources.

link rel="numanodes"

relationship A link to the numanodes sub-collection forvirtual machine resources.

link rel="cdroms"

relationship A link to the cdroms sub-collection for virtualmachine resources.

link rel="snapshots"

relationship A link to the snapshots sub-collection forvirtual machine resources.

link rel="tags"

relationship A link to the tags sub-collection for virtualmachine resources.


relationship A link to the permissions sub-collection forvirtual machine permissions.


relationship A link to the statistics sub-collection forvirtual machine resources.

link rel="reporteddevices"

relationship A link to the reporteddevices sub-collectionfor virtual machine resources.

link rel="watchdogs"

relationship A link to the watchdogs sub-collection forvirtual machine resources.

link rel="sessions"

relationship A link to the sessions sub-collection for virtualmachine resources.

type enumerated The virtual machine type. A list of enumeratedvalues are available in capabilities.

status See below The virtual machine status.

memory integer The amount of memory allocated to the guest inbytes.

Chapt er 30 . Virt ual Machines

269

cpu complex Defines CPU details for the virtual machine. The topology sub-element sets number of logical sockets available to the guest and the numberof cores per socket. The total cores available tothe virtual machine equals the number ofsockets multiplied by the cores per socket.

The cputune sub-element maps virtual CPUs tophysical host CPUs using a series of vcpupinelements. Each vcpupin elements contains avirtual CPU attribute (vcpu) and an attribute todefine 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 closelythe virtual CPU relates to the host CPU. It hasthree values: custom is the default if no mode isgiven, host_model copies the host CPU asbest as libvirt can understand, and host_passthrough passes all aspects of thehost to the guest, even those that libvirt does notrecognize. However, host_passthrough willprevent migration of that virtual machine.

os type= string, e.g. RHEL5or WindowsXP

The guest operating system type.

os boot dev= enumerated A list of boot devices described by a devattribute on a boot element. A list of enumeratedvalues are available in capabilities.

os kernel string A path to a kernel image the virtual machine isconfigured to boot. This option supportsbooting a Linux kernel directly rather thanthrough the BIOS bootloader.

os initrd string A path to an initrd image to be used with thepreviously specified kernel. This optionsupports booting a Linux kernel directly ratherthan through the BIOS bootloader.

os cmdline string A kernel command line parameter string to beused with the defined kernel. This optionsupports booting a Linux kernel directly ratherthan through the BIOS bootloader.

high_availability

complex Set enabled to true if the virtual machineshould be automatically restarted if the virtualmachine or its host crashes. A priorityelement controls the order in which virtualmachines are re-started.


T echnical Guide

270

display complex The display type (either vnc or spice), port,and the number of monitors. The allow_reconnect Boolean value specifies if aclient can reconnect to the machine via display.

The smartcard_enabled sub-element is aBoolean (true or false) to specify if aSmartcard attached to a client is passedthrough 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 virtualmachine is based.

domain id= GUID A reference to the virtual machine's domain.

start_time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which this virtual machinewas started.

stop_time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which this virtual machinewas stopped.

creation_time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which this virtual machinewas created.

origin One of rhev, ovirt, vmware orxen

The system from which this virtual machineoriginated.

stateless Boolean: true orfalse

true if the virtual machine is stateless. Astateless virtual machine contains a snapshot ofits disk image taken at boot and deleted atshutdown. This means state changes do notpersist after a reboot.

delete_protected


If set to true, the virtual machine cannot bedeleted.

sso string A reference to the method of single sign-on forthe virtual machine. Includes a method elementwith an ip attribute.



271

placement_policy

complex Sets the placement policy for virtual machinemigration. 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 guaranteedmemory on a host in order for the virtualmachine to run.

quota id= GUID Sets a quota for the virtual machine. custom_properties

complex A set of user-defined environment variablepassed as parameters to custom scripts. Each custom_property contains name and valueattributes. A list of enumerated values areavailable in capabilities.

usb complex Defines the USB policy for a virtual machine.Requires an enabled element set to a Booleanvalue and a type element set to either nativeor legacy.

migration_downtime

integer Represents the maximum number ofmilliseconds the virtual machine can be downduring live migration. A value of 0 means thatthe VDSM default will be used.

cpu_profile id=

GUID A reference to the virtual machine's cpu profile.

next_run_configuration


true if changes to the virtual machine'sconfiguration will be applied when the virtualmachine is next restarted.

numa_tune_mode

string Reference to the mode of memory allocation(interleave, strict, or preferred ) of thehost 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. Thiselement only appears for virtual machines partof a pool.

timezone tz databaseformat: Area/Location

The Sysprep timezone setting for a Windowsvirtual machine.

domain complex The Sysprep domain setting for a Windowsvirtual machine. Requires a name from the domains collection.

initialization

complex Defines a list of values applied to the virtualmachine on boot using Cloud-Init for Linux-based virtual machines, or Sysprep forWindows-based virtual machines.Cloud- In it

host_name: The host name of the virtualmachine.


T echnical Guide

272

timezone: The time zone for the virtualmachine.user_name: The user name for the virtualmachine.root_password : The password for the user,or root password if no user is specified.authorized_ssh_keys: SSH keys to beadded to the authorized keys file of thevirtual machine. You can enter multiple SSHkeys by separating each SSH key with a linebreak.regenerate_ssh_keys: Whether toregenerate SSH key for the virtual machine.Possible values are true or false.dns_servers: A space-separated list ofDNS servers.dns_search: A space-separated list of DNSsearch domains.nic_configurations: Defines a networkinterface controller for the virtual machine.Network interface controllers are defined as nic_configuration objects under thiscollection that each specify the name, ip, boot_protocol , and on_boot.custom_script: A custom script to run onthe virtual machine when it starts.

Sysprep

host_name: The host name of the virtualmachine.domain: The domain of which the virtualmachine is a member.authorized_ssh_keys: SSH keys to beadded to the authorized keys file of thevirtual machine. You can enter multiple SSHkeys by separating each SSH key with a linebreak.regenerate_ssh_keys: Whether toregenerate SSH key for the virtual machine.Possible values are true or false.timezone: The time zone for the virtualmachine.root_password : The password for theadmin user of the virtual machine.custom_script: A custom script to run onthe virtual machine when it starts.input_locale: The locale for user input.ui_language: The language used for userinterface elements such as buttons andmenus.system_locale: The locale for the overallsystem.user_locale: The locale for users.



273

active_directory_ou: Theorganizational unit in the Active Directorydomain to which the virtual machinebelongs.org_name: The name of the organization towhich the virtual machine belongs.

payloads complex Defines a set of payload elements to delivercontent 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 elementthat specifies the name and location of the file,and a content element that defines the contentto deliver to the file.

The payloads element is used by the cloud-init feature. When cloud-init is used toconfigure a virtual machine, a payload isautomatically created with the type attribute setto cd-rom and two file sub-elements, openstack/latest/meta_data.json and openstack/latest/user_data, which passconfiguration 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. Thesestates are listed in vm_states under capabilities.

30.2. XML Representat ion of a Virtual Machine

Example 30.1. An XML representat ion 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"

T echnical Guide

274

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>


275

<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 Representat ion of Addit ional OVF Data for a Virtual Machine

T echnical Guide

276

Use a GET request for a virtual machine with the All-Content: true header to include additionalOVF data with the representation of the virtual machine.

The Accept header defaults to application/xml if left blank, and the data is represented withHTML entities so as not to interfere with the XML tags. Specifying the Accept: application/jsonheader will return the data in standard XML tagging. This example representation has been formattedfrom its standard block format to improve legibility.

Example 30.2. XML representat ion of addit ional ovf data for a virtual machine

GET /api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a HTTP/1.1All-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>


277

<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 Representat ion of a Virtual Machine

Example 30.3. A JSON representat ion of a virtual machine

{ "type" : "server", "status" : { "state" : "down" }, "stop_reason" : "", "memory" : 1073741824,

T echnical Guide

278

"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" : { }


279

}, "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",

T echnical Guide

280

"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" }, {


281

"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. Creat ing 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 IDwith the cpuprofiles attribute.

Example 30.4 . Creat ing a virtual machine with 512 MB that boots f rom CD-ROM


<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. Creat ing a virtual machine with 512 MB that boots f rom a virtual harddisk

T echnical Guide

282


<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. Updat ing 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 . Updat ing a virtual machine to contain 1 GB of memory

PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1Accept: application/xmlContent-type: application/xml

<vm> <memory>1073741824</memory></vm>


283

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 canuse 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


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. Removalof a virtual machine requires a DELETE request.

Example 30.8. Removing a virtual machine

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <vm> <disks> <detach_only>true</detach_only> </disks> </vm></action>


30.6.1. Disks Sub-Collect ion

T echnical Guide

284

30.6 .1 .1 . Disks Sub-Co llect io n

The disks sub-collection represents all virtual hard disk devices on a virtual machine. A diskrepresentation contains the following elements:

Table 30.2. Elements for virtual machine d isks



relationship A link to the statistics sub-collection for a virtual machine'sdisk statistics.


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 machineimage stored on the defined storagedomain.

storage_domains complex The storage domains associatedwith this disk. Each storage_domain elementcontains an id attribute with theassociated storage domain's GUID.Update this element with POST toperform live migration of a disk fromone data storage domain toanother.

size integer Size of the disk in bytes.Deprecated; replaced by provisioned_size.

provisioned_size integer The provisioned size of the disk inbytes.

actual_size integer Actual size of the disk in bytes.

status One of illegal , invalid , locked or ok

The status of the disk device. Thesestates are listed in disk_statesunder capabilities.

interface enumerated The type of interface driver used toconnect to the disk device. A list ofenumerated values is available in capabilities.

format enumerated The underlying storage format. Alist of enumerated values isavailable in capabilities. CopyOn Write (COW) allows snapshots,with a small performance overhead.Raw does not allow snapshots, butoffers improved performance.

sparse Boolean: true or false true if the physical storage for thedisk should not be preallocated.

bootable Boolean: true or false true if this disk is to be marked asbootable.

[a]


285

shareable Boolean: true or false true to share the disk with multiplevirtual machines.

wipe_after_delete Boolean: true or false true if the underlying physicalstorage for the disk should bezeroed when the disk is deleted.This increases security but is amore intensive operation and mayprolong delete times.

propagate_errors Boolean: true or false true if disk errors should not causevirtual machine to be paused and,instead, disk errors should bepropagated to the guest OS.

vm id= GUID The ID of the containing virtualmachine.

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 thatcontains iSCSI or FCP devicedetails.

active Boolean Defines if the disk is connected tothe 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.


Example 30.9 . An XML representat ion of a d isk 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>

[a] This element is o nly req uired if the d isk is b eing ad d ed to a virtual machine and no t created fro m avirtual machine temp late.

T echnical Guide

286

<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 isrequired. Use the storage_domains element to specify in which storage domain the disk will becreated. Multiple disks for the same virtual machine can reside in different storage domains.

Example 30.10. Creat ing a new disk device on a virtual machine

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1Accept: application/xmlContent-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_storageelement and the logical_unit element, which contains iSCSI or FCP device details.

Example 30.11. Creat ing a new direct LUN disk device on a virtual machine

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1Accept: application/xmlContent-type: application/xml <disk>


287

<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. Updat ing a virtual machine d isk

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1Accept: application/xmlContent-type: application/xml

<disk> <bootable>false</bootable> <shareable>false</shareable></disk>

Example 30.13. Updat ing a virtual machine d isk to 20GB


<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 d isk

T echnical Guide

288


<disk> <alias>Classic_VM2</alias></disk>

Removal of a virtual machine disk requires a DELETE request.

Example 30.15. Removing a virtual machine d isk

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1


30.6 .1 .2 . Disk Clo ning

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 templateand attaches it to the virtual machine.

Example 30.16 . Cloning a d isk f rom 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.1Accept: application/xmlContent-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>


289

Important

Search queries for virtual machine disks based upon disk name require the alias searchparameter instead of name.

30.6 .1 .3. Disk St at ist ics Sub-Co llect io n

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 d isk stat ist ics





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 d isk stat ist ic types

Name Descript iondata.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 representat ion of a virtual machine's stat ist ics sub-collect ion

<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"

T echnical Guide

290

href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/ disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/> </statistic> ...</statistics>

Note


30.6 .1 .4 . Flo at ing Disk At t ach and Det ach Act io ns

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. At tach a f loat ing d isk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1Accept: application/xmlContent-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 diskresource but ensure to include a detach Boolean element so the disk is not destroyed.

Example 30.19 . Detach a d isk f rom a virtual machine

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/ d135f1c5-b5e1-4238-9381-b3277f5a3742 HTTP/1.1Accept: application/xmlContent-type: application/xml


30.6 .1 .5 . Disk Act ivat e and Deact ivat e Act io ns

Each virtual machine's disk provides a set of activate and deactivate actions to add andremove disks from a virtual machine.

Example 30.20. Act ion to act ivate a virtual machine d isk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-


291

410d-a392-a6980d873e5d/activate HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

Example 30.21. Act ion to deact ivate a virtual machine d isk

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/deactivate HTTP/1.1Accept: application/xmlContent-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 Virt IO disks and virtual machine operating systemsthat 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-Collect ion

30.6 .2 .1 . Net wo rk Int erfaces Sub-Co llect io n

The nics sub-collection represents all network interface devices on a virtual machine. A nicrepresentation contains the following elements:

Table 30.5. Elements for virtual machine network in terfaces



relationship A link to the statistics sub-collection for a virtual machine'snetwork interface statistics.

network id= GUID A reference to the network which theinterface should be connected. Ablank network id is allowed.

interface enumerated The type of driver used for the nic. Alist of enumerated values isavailable in capabilities.

T echnical Guide

292

mac address= string The MAC address of the interface.

port_mirroring complex Defines whether the NIC receivesmirrored traffic. Define a networkselement with a series of network id= references.

plugged Boolean Defines if the NIC is plugged in tothe virtual machine.

linked Boolean Defines if the NIC is linked to thevirtual machine.


Example 30.22. An XML representat ion of a network in terface

<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. Creat ing a virtual machine NIC

POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics HTTP/1.1Accept: application/xmlContent-type: application/xml

<nic> <name>nic1</name> <network id="00000000-0000-0000-0000-000000000009"/></nic>


293

An API user modifies a network interface with a PUT request.

Example 30.24 . Updat ing a virtual machine NIC

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1Accept: application/xmlContent-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. Delet ing a virtual machine NIC

DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1


Important

The hotplugging feature only supports virtual machine operating systems with hotpluggingoperations. 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 . Net wo rk Int erface St at ist ics Sub-Co llect io n

Each virtual machine's network interface exposes a statistics sub-collection for network interfacestatistics. Each statistic contains the following elements:

Table 30.6 . Elements for a virtual machine's network in terface stat ist ics



T echnical Guide

294



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 stat ist ic types

Name Descript iondata.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 representat ion of a virtual machine's NIC stat ist ics sub-collect ion

<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


30.6.3. Virtual NUMA Nodes Sub-Collect ion

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


295

Table 30.8. Elements for virtual NUMA nodes


index integer The index number of the virtualNUMA node.

memory integer The amount of memory allocated tothe virtual NUMA node, in MB.

cpu complex The CPU topology associated withthis virtual NUMA node. Each coreelement contains an indexattribute with the associated core'sindex number.

vm id= GUID The ID of the containing virtualmachine.

numa_node_pins complex Pins the virtual NUMA node to ahost NUMA node. Each numa_node_pin element containsa pinned="true" boolean andthe host NUMA node's indexnumber.

Example 30.27. An XML representat ion 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.1Accept: application/xmlContent-type: application/xml

T echnical Guide

296

<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 NUMAnode to a physical NUMA node on a host.

Example 30.29 . Updat ing a virtual NUMA node

PUT /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1Accept: application/xmlContent-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


30.6.4 . CD-ROMs Sub-Collect ion

The cdroms sub-collection represents the CD-ROM device on a virtual machine. A cdromrepresentation contains the following elements:

Table 30.9 . Elements for virtual machine CD-ROMs


file id= string/filename A reference to an ISO image.


297

Example 30.31. An XML representat ion 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 f ile

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-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 f ile

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-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 f ile during a current session

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1Accept: application/xmlContent-type: application/xml

T echnical Guide

298

<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 virtualmachine, adding the current=true matrix parameter:

Example 30.35. Eject ing a CD-ROM f ile during a current session

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1Accept: application/xmlContent-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 virtualmachine:

Example 30.36 . Eject ing a CD-ROM f ile permanent ly

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-type: application/xml<cdrom> <file id=""/></cdrom>

Note

Virtual machines only contain a single CD-ROM device.

30.6.5. Snapshots Sub-Collect ion

30.6 .5 .1 . Snapsho t s Sub-Co llect io n

A virtual machine saves and restores disk state as a number of snapshots. These are representedand managed through a rel="snapshot" sub-collection that behaves similar to other collections.


299

Each virtual machine snapshot is represented with an individual snapshot element that contains thefollowing sub-elements:

Table 30.10. Elements for virtual machine snapshots


vm id= GUID The ID and URI of the virtualmachine to which this snapshotpertains.

link rel="restore"

relationship A link to restore the snapshot of thevirtual machine.

link rel="prev" relationship A link to the previous snapshot ofthis virtual machine.

type string The type of the snapshot. Forexample, active or regular.

date xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which thesnapshot was created.

snapshot_status string The current status of the snapshot.

persist_memorystate

Boolean Defines whether the snapshot alsoincludes the state of the memory ofthe virtual machine at the time thesnapshot was taken.

Note

It is not possible to modify snapshot elements using PUT .

Example 30.37. An XML representat ion 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>

T echnical Guide

300

Use a GET request for a virtual machine snapshot with the All-Content: true header to includeadditional OVF data with the representation of the snapshot.

The Accept header defaults to application/xml if left blank, and the data is represented withHTML entities so as not to interfere with the XML tags. Specifying the Accept: application/jsonheader will return the data in standard XML tagging. This example representation has been formattedfrom its standard block format to improve legibility.

Example 30.38. XML representat ion of addit ional ovf data for a snapshot

GET /api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/snapshots HTTP/1.1All-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>


301

<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>

T echnical Guide

302

<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>


303

<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>

T echnical Guide

304

<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>


305

<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 byusing the POST method:

Example 30.39 . Creat ing a Virtual Machine Snapshot

POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/ HTTP/1.1Accept: application/xmlContent-type: application/xml

<snapshot><description>Snapshot description</description></snapshot>

You can restore a virtual machine snapshot using the rel="restore" action link in the snapshotrepresentation:

Example 30.4 0. Restoring a Virtual Machine Snapshot

POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/00000000-0000-0000-0000-000000000000/restore HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

T echnical Guide

306

30.6 .5 .2 . Clo ne a Virt ual Machine fro m a Snapsho t

API provides a function to create virtual machines from a snapshot of a previous machine. API userscreate 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 astandard representation of a virtual machine, which a user sends in a POST request to the vmscollection.

The snapshots element contains a snapshot id= element to define the specific snapshot to useas a basis for the virtual machine.

Example 30.4 1. Clone Virtual Machine f rom Snapshot


<vm> ... <snapshots> <snapshot id="3f68ee63-0016-4f8c-9b8a-11d9f28f7c9e"/> </snapshots> ...</vm>

30.6.6. Stat ist ics Sub-Collect ion

Each virtual machine resource exposes a statistics sub-collection for virtual machine-specificstatistics. Each statistic contains the following elements:

Table 30.11. Elements for virtual machine stat ist ics





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 stat ist ic types


307

Name Descript ionmemory.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.4 2. An XML representat ion of a virtual machine's stat ist ics sub-collect ion

<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 Informat ion

Submit a GET request for a virtual machine and use the session sub-collection to view the sessioninformation for the user that initiated the SPICE console session and the user logged in to the virtualmachine.

The session information of a virtual machine is listed as a sub-collection:

Example 30.4 3. Displaying the session in format ion of a virtual machine

GET /api/roles/a1a701f1-aa06-4f02-af17-158be31489b3/sessions HTTP/1.1Accept: application/xml


<sessions>

T echnical Guide

308

<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. Act ions

30.7.1. Start Virtual Machine Act ion

The start action launches a stopped, shutdown, or suspended virtual machine.

Example 30.4 4 . Act ion to start a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

The start action allows a vm element to be provided as a parameter. If a vm element is provided, thevirtual 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 windowin 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.4 5. Act ion to start a virtual machine with overridden parameters


309


<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 domain element is used for Windows systems only for overriding parameters on bootwith the start action. The domain element determines the domain that the Windows virtualmachine joins. If the domain does not exist in the domains collection, this element requiresadditional user authentication details, including a user_name and password . If thedomain exists in the domains collection, the action requires no additional userauthentication details.The CD image and floppy disk file must be available in the ISO domain already. If not, usethe ISO uploader tool to upload the files. See The ISO Uploader Tool for more information.

30.7.2. Start Virtual Machine with Cloud-Init Act ion

T echnical Guide

310

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.5/html-single/Administration_Guide/index.html#sect-The_ISO_Uploader_Tool

Cloud-Init is a tool for automating the initial setup of virtual machines. You can use the tool toconfigure the host name, network interfaces, the DNS service, authorized keys, and set user namesand passwords. You can also use the custom_script tag to specify a custom script to run on thevirtual machine when it boots.

Note

The cloud-init element can only be used to start virtual machines with the cloud-initpackage 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.4 6 . Act ion to start a virtual machine using Cloud- In it

This example shows you how to start a virtual machine using the Cloud-Init tool to set the hostname, change the root password, set a static IP for the eth0 interface, configure DNS, and add anSSH key for the root user.


<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>


311

<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 [email protected]</key> </authorized_key> </authorized_keys> </cloud_init> <custom_script><![CDATA[your script]]></custom_script> </initialization> </vm></action>

30.7.3. Stop Virtual Machine Act ion

The stop action forces a virtual machine to power-off.

Example 30.4 7. Act ion to stop a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

30.7.4 . Shutdown Virtual Machine Act ion

The shutdown action sends a shutdown request to a virtual machine.

Example 30.4 8. Act ion to send a shutdown request to a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

30.7.5. Suspend Virtual Machine Act ion

The suspend action saves the virtual machine state to disk and stops it. Start a suspended virtualmachine and restore the virtual machine state with the start action.

T echnical Guide

312

Example 30.4 9 . Act ion to save virtual machine state and suspend the machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

30.7.6. Reboot Virtual Machine Act ion

The reboot action sends a reboot request to a virtual machine.

Example 30.50. Act ion to send a reboot request to a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/reboot HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

30.7.7. Enable user logon to access a virtual machine from an externalconsole

The logon action enables users to access a virtual machine from consoles outside of the Red HatEnterprise Virtualization environment.

This action requires the rhevm-guest-agent-gdm-plugin and the rhevm-guest-agent-pam-modulepackages 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 virtualmachine from an external console.

Example 30.51. Logging onto a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/logon HTTP/1.1Content-Type: application/jsonContent-Length: 2

{}

30.7.8. Detach Virtual Machine from Pool Act ion

The detach action detaches a virtual machine from a pool.

Example 30.52. Act ion to detach a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1Accept: application/xml


313

Content-type: application/xml

<action/>

30.7.9. Migrate Virtual Machine Act ion

The migrate action migrates a virtual machine to another physical host. The destination hostelement is an optional element as Red Hat Enterprise Virtualization Manager automatically selects adefault host for migration. If an API user requires a specific host, the user can specify the host witheither an id or name parameter.

Example 30.53. Act ion to migrate a virtual machine to another host

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/migrate HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/></action>

30.7.10. Cancel Virtual Machine Migrat ion Act ion

The cancel migration action stops any migration of a virtual machine to another physical host.

Example 30.54 . Act ion to cancel migrat ion of a virtual machine to another host

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/cancelmigration HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

30.7.11. Export Virtual Machine Act ion

The export action exports a virtual machine to an export storage domain. A destination storagedomain 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 thedestination domain. Set the exclusive parameter to true to change this behavior and overwriteany 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. Act ion to export a virtual machine to an export storage domain

T echnical Guide

314

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/export HTTP/1.1Accept: application/xmlContent-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 T icket Act ion

The ticket action generates a time-sensitive authentication token for accessing a virtual machine'sdisplay. 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. Inany case, the response specifies the actual ticket value and expiry used.

Example 30.56 . Act ion to generate authent icat ion token for a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <ticket> <expiry>120</expiry> </ticket></action>

200 OKContent-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 Act ion


315

An API user forces the removal of a faulty virtual machine with the force action. This action requiresa DELETE method. The request body contains an action representation with the force parameterset to true. The request also requires an additional Content-type: application/xml headerto process the XML representation in the body.

Example 30.57. Force remove act ion on a virtual machine

DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720 HTTP/1.1Accept: application/xmlContent-type: application/xml


T echnical Guide

316

Chapter 31. Floating Disks

31.1. Float ing Disk Elements

The disks collection provides information about all disks in a Red Hat Enterprise Virtualizationenvironment. A user attaches and detaches disks from any virtual machine and floats them betweenvirtual machines. An API user accesses this information through the rel="disks" link obtainedfrom the entry point URI.

The following table shows specific elements contained in a disks resource representation.

Table 31.1. Elements for f loat ing d isks



relationship A link to the statistics sub-collection for a virtual machine'sdisk statistics.

image_id GUID A reference to the virtual machineimage stored on the defined storagedomain.

storage_domains Complex The storage domains associatedwith this disk. Each storage_domain elementcontains an id attribute with theassociated storage domain's GUID.Update this element with POST toperform live migration of a disk fromone data storage domain toanother.

size integer Size of the disk in bytes.

provisioned_size integer The provisioned size of the disk inbytes.

actual_size integer Actual size of the disk in bytes.

status One of illegal , invalid , locked or ok

The status of the disk device. Thesestates are listed in disk_statesunder capabilities.

interface enumerated The type of interface driver used toconnect to the disk device. A list ofenumerated values is available in capabilities.

format enumerated The underlying storage format. Alist of enumerated values isavailable in capabilities. CopyOn Write (COW) allows snapshots,with a small performance overhead.Raw does not allow snapshots, butoffers improved performance.

sparse Boolean: true or false true if the physical storage for thedisk should not be preallocated.

Chapt er 31 . Float ing Disks

317

bootable Boolean: true or false true if this disk is to be marked asbootable.

shareable Boolean: true or false true to share the disk with multiplevirtual machines.

wipe_after_delete Boolean: true or false true if the underlying physicalstorage for the disk should bezeroed when the disk is deleted.This increases security but is amore intensive operation and mayprolong delete times.

propagate_errors Boolean: true or false true if disk errors should not causevirtual machine to be paused and,instead, disk errors should bepropagated 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 containsiSCSI or FCP device details.

active Boolean Defines if the disk is connected tothe virtual machine.


Important

Search queries for disks based upon name require the alias search parameter instead of name.

31.2. XML Representat ion of a Float ing Disk

Example 31.1. An XML representat ion of a d isk 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>

T echnical Guide

318

<lunStorage> <storage> <logical_unit id="lun1"> ... </logical_unit> <storage> </lunStorage></disk>

31.3. Methods

31.3.1. Creat ing a Float ing Disk

When creating a new floating disk, the API requires the size and storage_domains elements.

Example 31.2. Creat ing a new a f loat ing d isk device

POST /api/disks HTTP/1.1Accept: application/xmlContent-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-Collect ions

31.4 .1. Stat ist ics Sub-Collect ion

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 d isk stat ist ics





Chapt er 31 . Float ing Disks

319

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 stat ist ic types

Name Descript iondata.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 representat ion of a virtual machine's stat ist ics sub-collect ion

<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


T echnical Guide

320

Chapter 32. Templates

32.1. Virtual Machine Template Elements

The templates collection provides information about the virtual machine templates in a Red HatEnterprise 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 resourcerepresentation.

Table 32.1. Virtual machine template elements


link rel="disks" relationship A link to the disks sub-collectionfor virtual machine templateresources.

link rel="nics" relationship A link to the nics sub-collection forvirtual machine template resources.

link rel="cdroms" relationship A link to the cdroms sub-collectionfor virtual machine templateresources.


relationship A link to the permissions sub-collection for virtual machinetemplate permissions.

type enumerated The type of virtual machine thetemplate provides. A list ofenumerated values are available in capabilities.

status One of illegal , locked or ok

The template status. These statesare listed in template_statesunder capabilities.

memory integer The amount of memory allocated tothe guest, in bytes.

cpu complex The CPU topology (i.e. number ofsockets and cores) available tothe guest.

os type= string, e.g. RHEL5 or WindowsXP

The guest operating system type.

os boot dev= enumerated A list of boot devices, described bya dev attribute on a boot element.A list of enumerated values areavailable in capabilities.

os kernel string A path to a kernel image which thetemplate is configured to boot from.

os initrd string A path to an initrd image to be usedwith the kernel above.

os cmdline string A kernel command line parameterstring to be used with the kernelabove.

Chapt er 32 . T emplat es

321

cluster id= GUID A reference to the template's hostcluster.

vm id= GUID A reference to the VM on which thistemplate is based.

domain id= GUID A reference to the template'sdomain.

creation_time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The date and time at which thistemplate was created.

origin One of rhev, ovirt, vmwareor xen

The system from which this templateoriginated.

high_availability complex Set enabled to true if the VMshould be automatically restarted ifthe host crashes. A priorityelement controls the order in whichVMs are re-started.

display complex The display type (either vnc or spice), port, and the number of monitors. The allow_reconnect Boolean valuespecifies if a client can reconnect tothe machine via display.

stateless Boolean: true orfalse

A stateless template contains asnapshot of its disk image taken atboot and deleted at shutdown. Thismeans state changes do not persistafter a reboot.

usb complex Defines the USB policy for a virtualmachine template. Requires an enabled element set to a Booleanvalue and a type element set toeither native or legacy.

placement_policy complex Sets the placement policy for virtualmachine migration. Requires adefault host= and an affinity(one of migratable, user_migratable or pinned ).Leave the host element empty to setno preferred host.

custom_properties complex A set of user-defined environmentvariable passed as parameters tocustom scripts. Each custom_property contains nameand value attributes. A list ofenumerated values are available in capabilities.


T echnical Guide

322

timezone tz databaseformat: Area/Location

The the Sysprep timezone settingfor a Windows virtual machinetemplate.

domain complex The the Sysprep domain setting fora Windows virtual machinetemplate. Requires a name from the domains collection.


32.2. XML Representat ion of a Virtual Machine Template

Example 32.1. An XML representat ion 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"/>;


323

</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. Creat ing a New T emplate

Creation of a new template requires the name and vm elements. Identify the vm with the id attribute or name element.

Example 32.2. Creat ing a template f rom a virtual machine

POST /api/templates HTTP/1.1Accept: application/xmlContent-type: application/xml

T echnical Guide

324

<template> <name>template1</name> <vm id="00000000-0000-0000-0000-000000000000"/></template>

32.3.2. Creat ing a New T emplate Sub Version

Creation of a new template sub version requires the name and vm elements for the new template, andthe base_template and version_name elements for the new template version. The base_template and version_name elements must be specified within a version sectionenclosed in the template section. Identify the vm with the id attribute or name element.

Example 32.3. Creat ing a template sub version f rom a virtual machine

POST /api/templates HTTP/1.1Accept: application/xmlContent-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. Updat ing a T emplate

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 . Updat ing a virtual machine template to contain 1 GB of memory

PUT /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-type: application/xml

<template> <memory>1073741824</memory></template>

32.3.4 . Updat ing a T emplate Sub Version

Only the version_name element can be updated after a template sub version has been created.

Example 32.5. Updat ing a virtual machine template sub version name


325

PUT /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1Accept: application/xmlContent-type: application/xml

<template> <version> <version_name>template1_002</version_name> </version></template>

32.3.5. Removing a T emplate

Removal of a virtual machine template requires a DELETE request.

Example 32.6 . Removing a virtual machine template

DELETE /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1


32.4 . Act ions

32.4 .1. Export T emplate Act ion

The templates collection contains an export action.

The export action exports a template to an Export storage domain. A destination storage domain isspecified with a storage_domain reference.

The export action reports a failed action if a virtual machine template of the same name exists in thedestination domain. Set the exclusive parameter to true to change this behavior and overwriteany existing virtual machine template.

Example 32.7. Act ion to export a template to an export storage domain

POST /api/templates/00000000-0000-0000-0000-000000000000/export HTTP/1.1Accept: application/xmlContent-type: application/xml

<action> <storage_domain id="00000000-0000-0000-0000-000000000000"/> <exclusive>true<exclusive/></action>

T echnical Guide

326

Chapter 33. Virtual Machine Pools

33.1. Virtual Machine Pool Elements

The vmpools collection provides information about the virtual machine pools in a Red HatEnterprise 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 resourcerepresentation.

Table 33.1. Virtual machine pool elements

Element Type Descript ion Propert iesname string A user-supplied, human readable

name for the pool. The name is uniqueacross all pool resources.

description string A user-supplied, human readabledescription of the virtual machinepool.


relationship A link to the permissions sub-collection for virtual machine poolpermissions.

size integer The number of virtual machines in thepool.

cluster id= GUID A reference to the cluster resource inwhich virtual machines in this poolrun.

template id= GUID A reference to the template resourceon which virtual machines in this poolare based.

prestarted_vms integer The number of prestarted virtualmachines in the virtual machine pool.

max_user_vms integer The maximum number of virtualmachines any one user can take fromthe virtual machine pool.

Important

The API as documented in this chapter is experimental and subject to change. It is not coveredby the backwards compatibility statement.

33.2. XML Representat ion of a Virtual Machine Pool

Example 33.1. An XML representat ion of a virtual machine pool

<vmpool href="/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e"> id="2d2d5e26-1b6e-11e1-8cda-001320f76e8e"

Chapt er 33. Virt ual Machine Pools

327

<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. Creat ing 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. Creat ing a virtual machine pool

POST /api/vmpools HTTP/1.1Accept: application/xmlContent-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. Updat ing a Virtual Machine Pool

The name, description, size, prestarted_vms and max_user_vms can be updated after thevirtual machine has been created.

Example 33.3. Updat ing a virtual machine pool

PUT /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1

T echnical Guide

328

Accept: application/xmlContent-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.3.3. Removing a Virtual Machine Pool

Removal of a virtual machine pool requires a DELETE request.

Example 33.4 . Removing a virtual machine

DELETE /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1


33.4 . Act ions

33.4 .1. Allocate Virtual Machine Act ion

The allocate virtual machine action allocates a virtual machine in the virtual machine pool.

Example 33.5. Act ion to allocate a virtual machine f rom a virtual machine pool

POST /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e/allocatevm HTTP/1.1Accept: application/xmlContent-type: application/xml

<action/>

Chapt er 33. Virt ual Machine Pools

329

Chapter 34. Domains

34.1. Domain Elements

The API provides the ability to access user and group information from the organization's directoryservice using the domains collection. Domain information is referenced with the rel="domains"link.

Table 34 .1. Domain elements

Element Type Descript ionname 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 Representat ion of a Domain Resource

Example 34 .1. An XML representat ion 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.1. Domain Users Sub-Collect ion

The users sub-collection contains all users in the directory service. This information is used to add

T echnical Guide

330

new users to the Red Hat Enterprise Virtualization environment.

Table 34 .2. Domain user elements

Element Type Descript ionname 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 representat ion of a user in the users sub-collect ion

<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>[email protected]</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-Collect ion

The groups sub-collection contains all groups in the directory service. A domain group resourcecontains a set of elements.

Table 34 .3. Domain group elements

Element Type Descript ionname string The name of the group.domain id GUID The containing directory service domain.

Example 34 .3. An XML representat ion of a group in the groups sub-collect ion

<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>

Chapt er 34 . Domains

331

T echnical Guide

332

Chapter 35. Groups

35.1. Imported Group Elements

The groups collection contains imported groups from directory services. A group resource containsa set of elements.

Table 35.1. Imported group elements

Element Type Descript ionlink 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 Representat ion of a Group Resource

Example 35.1. An XML representat ion 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 Managerdatabase with a POST request to the groups collection.

Example 35.2. Adding a group f rom a d irectory service

POST /api/group HTTP/1.1Content-Type: application/xmlAccept: application/xml

Chapt er 35. Groups

333

<group> <name>www.example.com/accounts/groups/mygroup</name> <domain> <name>example.com</name> </domain> </group>

T echnical Guide

334

Chapter 36. Roles

36.1. Role Elements

The rel="roles" link obtained from the entry point URI provides access to a static set of systemroles. Each individual role element contains the following:

Table 36 .1. Role elements


link="permits" relationship A link to the permits sub-collection for role permits.

mutable Boolean: true or false Defines the ability to update ordelete the role. Roles with mutableset to false are roles built into theRed Hat Enterprise Virtualizationenvironment.

administrative Boolean: true or false Defines the role as administrative-only.

36.2. XML Representat ion of the Roles Collect ion

Example 36 .1. An XML representat ion of the ro les collect ion

<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"

Chapt er 36 . Roles

335

href="/api/roles/00000000-0000-0000-0001-000000000002/permits"/> <mutable>false</mutable> <administrative>false</administrative> </role></roles>

36.3. Methods

36.3.1. Creat ing a Role

Creation of a role requires values for name, administrative and a list of initial permits.

Example 36 .2. Creat ing a ro le

POST /api/roles HTTP/1.1Accept: application/xmlContent-type: application/xml

<role> <name>Finance Role</name> <administrative>true</administrative> <permits> <permit id="1"/> </permits></role>

36.3.2. Updat ing a Role

The name, description and administrative elements are updatable post-creation.

Example 36 .3. Updat ing a ro le

PUT /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1Accept: application/xmlContent-type: application/xml

<role> <name>Engineering Role</name> <description>Standard users in the Engineering Role</description> <administrative>false</administrative></role>

36.3.3. Removing a Role

Removal of a role requires a DELETE request.

T echnical Guide

336

Example 36 .4 . Removing a ro le

DELETE /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1


36.4 . Roles Permits Sub-Collect ion

36.4 .1. Roles Permits Sub-Collect ion

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. List ing a ro le's permits

GET /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1Accept: 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 idattribute or a name element to specify the permit to assign.

Example 36 .6 . Assign a permit to a ro le

POST /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1Accept: application/xmlContent-Type: application/xml

<permit id="1"/>


Chapt er 36 . Roles

337

<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 .3. Remove a Permit from a Role

Remove a permit from a role with a DELETE request to the permit resource.

Example 36 .7. Remove a permit f rom a ro le

DELETE /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1 HTTP/1.1


T echnical Guide

338

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


user_name string The user principal name (UPN). TheUPN is used as a more convenientidentifier when adding a new user.

link rel="tags" relationship A link to the tags sub-collection foruser resources.

link rel="roles" relationship A link to the roles sub-collectionfor user resources.

name string A free-text name for the user.

domain string The containing directory servicedomain.

groups complex A list of directory service groups forthis user.

37.2. XML representat ion of a User Resource

Example 37.1. An XML representat ion of a user resource

GET /api/users HTTP/1.1Accept: 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>[email protected]</user_name> <groups> <group>Group Policy Creator [email protected]/Users</group> <group>Domain [email protected]/Users</group> <group>Enterprise [email protected]/Users</group>

Chapt er 37 . Users

339

<group>Schema [email protected]/Users</group> <group>[email protected]/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 Managerdatabase with a POST request to the users collection. The client-provided new user representationincludes 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 [email protected]:

Example 37.2. Adding a user f rom directory service and assigning two ro les

POST /api/users HTTP/1.1Content-Type: application/xmlAccept: application/xml

<user> <user_name>[email protected]</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 thedirectory service user principal name (UPN). The user ID format reported from the directory servicedomain might be different to the expected Red Hat Enterprise Virtualization Manager format, such as

in LDIF , the ID has the opposite byte order and is base-64 encoded. Hence it is usually moreconvenient 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 EnterpriseVirtualization Manager database. An API user has the option to query this domain through thedomains 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 ofan individual user. The example below illustrates how the API adds the RHEVMVDIUser role to therole assignments for a particular user.

[6 ]

T echnical Guide

34 0

Note

The embedded user roles list of the user element is only used for the initial creation. Allinteractions post-creation with the user's role assignments go through the roles sub-collection.

Example 37.3. Adding ro les to a user

POST /api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles HTTP/1.1Content-Type: application/xmlAccept: application/xml

<role> <name>RHEVMVDIUser</name></role>

[6 ] The LDAP Data Interchang e Fo rmat is d escrib ed in RFC 28 49 .

Chapt er 37 . Users

34 1


Chapter 38. Tags

38.1. Tag Elements

The tags collection provides information about tags in a Red Hat Enterprise Virtualizationenvironment. An API user accesses this information through the rel="tags" link obtained from theentry point URI.

The following table shows specific elements contained in a tag resource representation.

Table 38.1. Tag elements


host GUID A reference to the host which the tagis attached.

user GUID A reference to the user which the tagis attached.

vm GUID A reference to the VM which the tagis attached.

parent complex A reference to the VM which the tagis attached.

38.2. XML Representat ion of a Tag Resource

Example 38.1. An XML representat ion 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. Associat ing Tags

38.3.1. Associat ing T ags With a Host , User or VM

The collection referenced by link rel="tags" from a host, user or vms represents the set of tagsassociated with the entity.

These tag representations also contain a host id , user id or vm id reference to the entity inquestion.

Associating a tag with an entity is achieved by POST ing a tag reference (identifying the tag either byits id or name) to the collection.

T echnical Guide

34 2

Example 38.2. Associat ing a tag with a virtual machine

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1Accept: application/xmlContent-Type: application/xml

<tag> <name>Finance</name></tag>


<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 T ag

Removing an association is achieved with a DELETE request to the appropriate element in thecollection.

Example 38.3. Removing a tag f rom a virtual machine

DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1


38.3.3. Querying a Collect ion for T agged Resources

To query the set of entities associated with a given tag, the collection/search URI template forthe appropriate collection should be used to search for entities matching tag=MyTag .

Example 38.4 . Querying a collect ion for tagged resources

GET /api/vms?search=tag%3DFinance HTTP/1.1Accept: application/xml


<vms> <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"

Chapt er 38 . T ags

34 3

href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"> ... </vm> ...</vms>

38.4 . Parent Tags

38.4 .1. Parent T ags

An API user assigns a parent element to a tag to create a hierarchical link to a parent tag. The tagsare presented as a flat collection, which descends from the root tag, with tag representationscontaining 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 isspecified. 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>

T echnical Guide

34 4

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. Set t ing a Parent T ag

POST ing 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 . Set t ing an associat ion with a parent tag with the id at t ribute



<tag> <name>Billing</name> <description>Billing Resources</description> <parent> <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/> </parent></tag>

Example 38.7. Set t ing an associat ion with a parent tag with the name element



<tag> <name>Billing</name> <description>Billing Resources</description> <parent> <tag> <name>Finance</name> </tag> </parent></tag>

38.4 .3. Changing a Parent T ag

A tag changes a parent using a PUT request:

Chapt er 38 . T ags

34 5

Example 38.8. Changing the parent tag

PUT /api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd HTTP/1.1Accept: application/xmlContent-Type: application/xml

<tag> <parent> <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/> </parent></tag>

T echnical Guide

34 6

Chapter 39. Events

39.1. Event Elements

The rel="events" link obtained from the entry point URI accesses the events collection and listssystem events from Red Hat Enterprise Virtualization Manager.

Table 39 .1. Event elements

Element Type Descript iondescription string A description of the system eventcode integer The integer event code.severity One of normal ,

warning , erroror alert

The level of severity for the event.

time xsd:dateTimeformat: YYYY-MM-DDThh:mm:ss

The timestamp indicating when the eventhappened.

user id GUID The identification code for the user whotriggered the event.

Note

The events collection is read-only.

39.2. XML Representat ion of the Events Collect ion

Example 39 .1. An XML representat ion of the events collect ion

<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 Representat ion of a Virtual Machine Creat ion Event

In addition to user, an event representation also contains a set of XML element relationships toresources relevant to the event.

Chapt er 39 . Event s

34 7

Example 39 .2. An XML representat ion of a virtual machine creat ion 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 resourceand a storage domain resource.

39.4 . Searching Events

The events collection provides search queries similar to other resource collections. An additionalfeature when searching the events collection is the ability to search from a certain event. Thisqueries 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 f rom an event

GET /api/events;from=1012?search=type%3D30 HTTP/1.1Accept: application/xml

This displays all events with type set to 30 since id="1012"

HTTP/1.1 200 OKContent-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>

T echnical Guide

34 8

<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 specif ic event severity

GET /api/events?search=severity>normal HTTP/1.1Accept: application/xml

This displays all events with severity higher than normal . Severity levels include normal , warning , error and alert.

HTTP/1.1 200 OKContent-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. Paginat ing Events

A virtualization environment generates a large amount of events after a period of time. However, theAPI 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 withthe sortby clause:

sortby time asc page 1

The sortby clause defines the base element to order of the results and whether the results areascending or descending. For search queries of events, set the base element to time and the orderto ascending (asc) so the API displays all events from the creation of your virtualizationenvironment.

Chapt er 39 . Event s

34 9

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:




Example 39 .5. Paginat ing events

This example paginates event resources. The URL-encoded request is:

GET /api/events?search=sortby%20time%20asc%20page%201 HTTP/1.1Accept: application/xml

Increase the page value to view the next page of results.

GET /api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1Accept: 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.1Accept: application/xml

T echnical Guide

350

Part IV. The Python Sofware Development Kit

Part IV. T he Pyt hon Sofware Development Kit

351

Chapter 40. Software Development Kit Overview

40.1. Overview

The Python software development kit is a collection of classes and functions that allows you tointeract with the Red Hat Enterprise Virtualization Manager in Python-based projects. Bydownloading these classes and functions and adding them to your project, you can access a rangeof functionality for high-level automation of administrative tasks.

The Python software development kit uses the rhevm-sdk-python package, which is available tosystems subscribed to a Red Hat Enterprise Virtualization entitlement pool in Red HatSubscription Manager.

40.2. Prerequisit es

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 Workstationvariants 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 thesoftware 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 theversion of your Red Hat Enterprise Virtualization environment. For example, if you are usingRed Hat Enterprise Virtualization 3.5, you must use the version of the software development kitdesigned for 3.5.

40.3. Installing the Python Software Development Kit

Install the Python software development kit.

Procedure 4 0.1. Installing the Python Sof tware Development Kit

1. 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-

T echnical Guide

352

rpms

2. 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 Pythonprojects.

Chapt er 4 0 . Soft ware Development Kit Overview

353

Chapter 41. Python Quick Start Example

41.1. Python Quick Start Int roduct ion

This chapter provides a series of examples demonstrating the steps to create a virtual machine withina basic Red Hat Enterprise Virtualization environment, using the Python SDK.

These examples use the ovirtsdk Python library provided by the rhevm-sdk-python package. Thispackage is available to systems subscribed to a Red Hat Enterprise Virtualizationentitlement pool in Red Hat Subscription Manager. See Section 40.3, “ Installing the Python SoftwareDevelopment 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 HatEnterprise Virtualization environment.

A working understanding of the Python programming language.

Important

All Python examples include placeholders for authentication details (USER for user name, andPASS for password). Ensure all requests performed with Python fulfill the authenticationrequirements of your environment.

Note

Red Hat Enterprise Virtualization Manager generates a globally unique identifier (GUID) for theid attribute for each resource. Identifier codes in these examples might appear different to theidentifier codes in your Red Hat Enterprise Virtualization environment.

Note

These Python examples contain only basic exception and error handling logic. For moreinformation 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 Ent ry Point using Python

T echnical Guide

354

The ovirtsdk Python library provides the API class, which acts as the entry point for the API.

Example 4 1.1. Accessing the API ent ry point using Python

This python example connects to an instance of the REST API provided by the Red Hat EnterpriseVirtualization Manager at rhevm.demo.redhat.com. To connect the example creates aninstance 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 API class in this example are:

The url of the Manager to which to connect.

The username of the user by which to authenticate.

The password of 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 theone for the Manager's Certificate Authority. It can be obtained from https://HOST/ca.crt.

The constructor for the API class supports other parameters. Only mandatory parameters arespecified in this example.

from ovirtsdk.api import APIfrom 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: List ing the Data Center Collect ion using Python

The API class provides access to a data centers collection, named datacenters. This collectioncontains all data centers in the environment.

Example 4 1.2. List ing the Data Center Collect ion using Python

This Python example lists the data centers in the datacenters collection. It also outputs somebasic information about each data center in the collection.

Chapt er 4 1 . Pyt hon Quick St art Example

355



dc_list = api.datacenters.list()

for dc in dc_list: print "%s (%s)" % (dc.get_name(), dc.get_id())

api.disconnect()


In an environment where only the Default data center exists, and it is not activated, the exampleoutputs:

Default (d8b74b20-c6e1-11e1-87a3-00163e77e2ed)

41.4 . Example: List ing the Cluster Collect ion using Python

The API class provides a clusters collection, named clusters. This collection contains all clustersin the environment.

Example 4 1.3. List ing the clusters collect ion using Python

This Python example lists the clusters in the clusters collection. It also outputs some basicinformation about each cluster in the collection.


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()


T echnical Guide

356

In an environment where only the Default cluster exists, the example outputs:

Default (99408929-82cf-4dc7-a532-9d998063fa95)

41.5. Example: List ing the Logical Networks Collect ion using Python

The API class provides access to a logical networks collection, named networks. This collectioncontains all logical networks in the environment.

Example 4 1.4 . List ing the logical networks collect ion using Python

This Python example lists the logical networks in the networks collection. It also outputs somebasic information about each network in the collection.


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: List ing the Host Collect ion using Python

The API class provides access to a hosts collection, named hosts. This collection contains allhosts in the environment.

Example 4 1.5. List ing the host co llect ion using Python

This Python example lists the hosts in the hosts collection.



357


h_list = api.hosts.list()

for h in h_list: print "%s (%s)" % (h.get_name(), h.get_id())

api.disconnect()


In an environment where only one host, named Atlantic, has been attached the example outputs:

Atlantic (5b333c18-f224-11e1-9bdd-00163e77e2ed)

41.7. Example: List ing the ISO Files in an ISO Storage Domain

The API class provides access to a storage domain collection, named storagedomains. Thiscollection in turn contains a files collection that describes the files in a storage domain.

Example 4 1.6 . List ing 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 HatEnterprise Virtualization environment:



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()

T echnical Guide

358

api.disconnect()


41.8. Example: List ing the Size of a Virtual Machine

The API class provides access to a virtual machine collection, named vms. This collection in turncontains a disks collection that describes the details of each disk attached to a virtual machine.

Example 4 1.7. List ing the Siz e of a Virtual Machine

This Python example prints a list of the virtual machines in the Red Hat Enterprise Virtualizationenvironment along with their total disk size in bytes:



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()


41.9. Example: Approving a Host using Python


359

Red Hat Enterprise Virtualization Hypervisor hosts are added to the Red Hat Enterprise VirtualizationManager during their configuration. Once you have added a Hypervisor it requires approval in theManager before it can actually be used in the environment.

Example 4 1.8. Approving a host using Python

This Python example calls the approve method for a host named Atlantic.



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()


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: Creat ing NFS Data Storage using Python

When a Red Hat Enterprise Virtualization environment is first being created it is necessary to define atleast a data storage domain, and an ISO storage domain. The data storage domain will be used tostore virtual machine disk images while the ISO storage domain will be used to store installationmedia for guest operating systems.

The API class provides access to a storage domains collection, named storagedomains. Thiscollection contains all the storage domains in the environment. The storagedomains collectioncan also be used to add and remove storage domains.

T echnical Guide

360

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 EnterpriseVirtualization Administration Guide for more information on preparing NFS shares for use.

Example 4 1.9 . Creat ing NFS data storage using Python

This Python example adds an NFS data domain to the storagedomains collection. Adding anNFS storage domain in Python can be broken down into several steps:

1. Identify the data center to which the storage must be attached, using the get method of the datacenters collection.

dc = api.datacenters.get(name="Default")

2. Identify the host that must be used to attach the storage, using the get method of the hosts collection.


3. Define the Storage parameters for the NFS storage domain. In this example the NFSlocation 192.0.43.10/storage/data is being used.

s = params.Storage(address="192.0.43.10", path="/storage/data", type_="nfs")

4. Request creation of the storage domain, using the add method of the storagedomainscollection. In addition to the Storage parameters it is necessary to pass:

A name for the storage domain.

The data center object that was retrieved from the datacenters collection.

The host object that was retrieved from the hosts collection.

The type of storage domain being added (data, iso , or export).

The storage format to use (v1, v2, or v3).

Once these steps are combined, the completed script is:



dc = api.datacenters.get(name="Default") h = api.hosts.get(name="Atlantic")


361

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()


If the add method call is successful then the script will output:

Storage Domain 'data1' added (bd954c03-d180-4d16-878c-2aedbdede566).

41.11. Example: Creat ing NFS ISO Storage using Python

To create a virtual machine you must be able to provide installation media for the guest operatingsystem. In a Red Hat Enterprise Virtualization environment you store the installation media on an ISOstorage 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 EnterpriseVirtualization Administration Guide for more information on preparing NFS shares for use.

Example 4 1.10. Creat ing NFS ISO storage using Python

This Python example adds an NFS ISO domain to the storagedomains collection. Adding anNFS storage domain in Python can be broken down into several steps:

1. Identify the data center to which the storage must be attached, using the get method of the datacenters collection.

dc = api.datacenters.get( name="Default" )

2. Identify the host that must be used to attach the storage, using the get method of the hosts collection.


3. Define the Storage parameters for the NFS storage domain. In this example the NFSlocation 192.0.43.10/storage/iso is being used.

T echnical Guide

362

s = params.Storage(address="192.0.43.10", path="/storage/iso", type_="nfs")

4. Request creation of the storage domain, using the add method of the storagedomainscollection. In addition to the Storage parameters it is necessary to pass:

A name for the storage domain.

The data center object that was retrieved from the datacenters collection.

The host object that was retrieved from the hosts collection.

The type of storage domain being added (data, iso , or export).

The storage format to use (v1, v2, or v3).

Once these steps are combined, the completed script is:



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()


If the add method call is successful then the script will output:

Storage Domain 'iso1' added (789814a7-7b90-4a39-a1fd-f6a98cc915d8).

41.12. Example: At taching Storage Domains to a Data Center usingPython


363

Once you have added storage domains to Red Hat Enterprise Virtualization you must attach them toa data center and activate them before they will be ready for use.

Example 4 1.11. At taching storage domains to a data center using Python

This Python example attaches a data storage domain named data1, and an ISO storage domainnamed iso1 to the default data center. The attach action is facilitated by the add method of thedata center's storagedomains collection.




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.

T echnical Guide

364

41.13. Example: Act ivat ing Storage Domains using Python

Once you have added storage domains to Red Hat Enterprise Virtualization and attached them to adata center you must activate them before they will be ready for use.

Example 4 1.12. Act ivat ing storage domains using Python

This Python example activates a data storage domain named data1, and an ISO storage domainnamed iso1. Both storage domains are attached to the Default data center. The activate actionis facilitated by the activate method of the storage domain.




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()


If the activate requests are successful then the script will output:


365

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: Creat ing a Virtual Machine using Python

Virtual machine creation is performed in several steps. The first step, covered here, is to create thevirtual machine object itself.

Example 4 1.13. Creat ing a virtual machine using Python

This Python example creates a virtual machine named 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 Default cluster, and therefore the Default data center.

vm_cluster = api.clusters.get(name="Default")

Must be based on the default Blank template.

vm_template = api.templates.get(name="Blank")

Must boot from the virtual hard disk drive.

vm_os = params.OperatingSystem(boot=[params.Boot(dev="hd")])

These options are combined into a virtual machine parameter object, before using the add methodof the vms collection to create the virtual machine itself.



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,

T echnical Guide

366

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()


If the add request is successful then the script will output:

Virtual machine 'vm1' added.

41.15. Example: Creat ing a Virtual Machine NIC using Python

To ensure a newly created virtual machine has network access you must create and attach a virtualNIC.

Example 4 1.14 . Creat ing a virtual machine NIC using Python

This Python example creates an NIC named nic1 and attaches it to the virtual machine named vm1. The NIC in this example:

Must be a virtio network device.

nic_interface = "virtio"

Must be linked to the rhevm management network.

nic_network = api.networks.get(name="rhevm")

These options are combined into an NIC parameter object, before using the add method of thevirtual machine's nics collection to create the NIC.



vm = api.vms.get(name="vm1")


367

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


Network interface 'nic1' added to 'vm1'.

41.16. Example: Creat ing a Virtual Machine Storage Disk using Python

To ensure a newly created virtual machine has access to persistent storage you must create andattach a disk.

Example 4 1.15. Creat ing a virtual machine storage d isk using Python

This Python example creates an 8 GB virtio disk drive and attaches it to the virtual machinenamed 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 system type disk (as opposed to data),

disk_type = "system"

must be virtio storage device,

disk_interface = "virtio"

T echnical Guide

368

must be stored in cow format, and

disk_format = "cow"

must be marked as a usable boot device.

disk_bootable = True

These options are combined into a disk parameter object, before using the add method of thevirtual machine's disks collection to create the disk itself.




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()



Disk 'vm1_Disk1' added to 'vm1'.


369

41.17. Example: At taching an ISO Image to a Virtual Machine usingPython

To begin installing a guest operating system on a newly created virtual machine you must attach anISO file containing the operating system installation media.

Example 4 1.16 . Ident ifying ISO images

ISO images are found in the files collection attached to the ISO storage domain. This examplelists the contents of the files collection on an ISO storage domain.

from ovirtsdk.api import API from ovirtsdk.xml import params


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 ofthe file are shared.

Example 4 1.17. At taching 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 virtualmachine's cdroms collection.


try: api = API(url="https://HOST", username="USER@DOMAIN", password="PASS, ca_file="ca.crt")

T echnical Guide

370

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()



Attached CD to 'vm1'.

Note

This procedure is for attaching an ISO image to virtual machines with a status of Down. Toattach an ISO to a virtual machine with an Up status, amend the second try statement to thefollowing:

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 4 1.18. Eject ing a cdrom f rom a Virtual Machine using Python

Eject an ISO from a virtual machine's cdrom collection.


try: api = API(url="https://HOST", username="USER@DOMAIN", password="PASS, ca_file="ca.crt")

sd = api.storagedomains.get(name="iso1")


371


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()


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 4 1.19 . Detaching a d isk using Python



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()


41.19. Example: Start ing a Virtual Machine using Python

Starting a virtual machine

Example 4 1.20. Start ing a virtual machine using Python

This example starts the virtual machine using the start method.

T echnical Guide

372




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()


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: Start ing a Virtual Machine with Overridden Parametersusing Python

Starting a virtual machine with overridden parameters.

Example 4 1.21. Start ing 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 theRun Once window in the Administration or User Portal to start a virtual machine.


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:


373

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 theISO uploader tool to upload the files. See The ISO Uploader Tool for more information.

41.21. Example: Start ing a Virtual Machine with Cloud-Init using Python

Starting a virtual machine with Cloud-Init using Python.

Example 4 1.22. Start ing a virtual machine with Cloud- In it using Python

This example shows you how to start a virtual machine using the Cloud-Init tool to set a host nameand a static IP for the eth0 interface.


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

T echnical Guide

374

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.5/html-single/Administration_Guide/index.html#sect-The_ISO_Uploader_Tool

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 logsare accessible through the user interface, the system log files, and using the API. The ovirtsdk libraryexposes events using the events collection.

Example 4 1.23. Checking System Events using Python

In this example the events collection is listed. Note that:

The query parameter of the list method is used to ensure that all available pages of resultsare returned. By default the list method will only return the first page of results which defaultsto a maximum of 100 records in length.

The resultant list is reversed to ensure that events are included in the output in the order thatthey occurred.



375


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())


Output from this script will look like this - albeit with different events depending on the state of theenvironment:

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.

T echnical Guide

376

Chapter 42. Using the Software Development Kit

42.1. Connect ing to the API using Python

To connect to the REST API using Python you must create an instance of the API class from theovirtsdk.api module. To be able to do this it is necessary to first import the class at the start of thescript:

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 /api path. This parameter ismandatory.

username

Specifies the user name to connect using, in User Principal Name (UPN) format. Thisparameter is mandatory.

password

Specifies the password for the user name provided by the username parameter. Thisparameter is mandatory.

kerberos

Uses a valid Kerberos ticket to authenticate the connection. Valid values are True and False. This parameter is optional.

key_f ile

Specifies a PEM formatted key file containing the private key associated with the certificatespecified by cert_file. This parameter is optional.

cert_f ile

Specifies a PEM formatted client certificate to be used for establishing the identity of theclient on the server. This parameter is optional.

ca_f ile

Specifies the certificate file of the certificate authority for the server. This parameter ismandatory unless the insecure parameter is set to True.

port

Specifies the port to connect using, where it has not been provided as component of the url parameter. This parameter is optional.

t imeout

Specifies the amount of time in seconds that is allowed to pass before a request is to beconsidered as having timed out. This parameter is optional.

persistent_auth

Chapt er 4 2 . Using t he Soft ware Development Kit

377

Specifies whether persistent authentication is enabled for this connection. Valid values are True and False. This parameter is optional and defaults to False.

insecure

Allows a connection via SSL without certificate authority. Valid values are True and False. If the insecure parameter is set to False - which is the default - then the ca_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.

f i lter

Specifies whether or not user permission based filter is on or off. Valid values are True andFalse. If the filter parameter is set to False - which is the default - then theauthentication credentials provided must be those of an administrative user. If the filterparameter is set to True then any user can be used and the Manager will filter the actionsavailable to the user based on their permissions.

debug

Specifies whether debug mode is enabled for this connection. Valid values are True and False. This parameter is optional.

You can communicate with multiple Red Hat Enterprise Virtualization Managers by creating andmanipulating separate instances of the ovirtsdk.API Python class.

This example script creates an instance of the API class, checks that the connection is workingusing 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.apimodule.

$ pydoc ovirtsdk.api

42.2. Resources and Collect ions

The RESTful nature of the API is evident throughout the Python bindings for both theoretical andpractical reasons. All RESTful APIs have two key concepts that you need to be aware of:

Collect ions

A collection is a set of resources of the same type. The API provides both top-levelcollections and sub-collections. An example of a top-level collection is the hosts collectionwhich contains all virtualization hosts in the environment. An example of a sub-collection is

T echnical Guide

378

the host.nics collection which contains resources for all network interface cardsattached 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 ofattributes that are relevant to the specific type of resource being represented. The interfacefor interacting with resources provides methods for updating (update ) and deleting(delete) resources. Additionally some resources support actions specific to the resourcetype. An example is the approve method of Host resources.

42.3. Ret rieving Resources from a Collect ion

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 onthe name provided as an argument. The get method 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.

l ist

Retrieves any number of resources from the collection. The items to retrieve are determinedbased on the criteria provided. The list method 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 theRed 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(True or False, the default is True).

42.4 . Ret rieving a Specific Resource from a Collect ion

In these examples a specific resource is retrieved from a collection using the get method.

Example 4 2.1. Ret rieving a Specif ic Resource by Name

Retrieving the Default data center from the datacenters collection using the name parameter ofthe get method:

dc = api.datacenters.get("Default")

This syntax is equivalent:



379

42.5. Ret rieving a List of Resources from a Collect ion

In these examples a list of resources is retrieved from a collection using the list method.

Example 4 2.2. Ret rieving a List o f all Resources in a Collect ion

Retrieving a list of all resources in the datacenters collection. The query parameter of the listmethod allows the use of engine based queries. In this way the SDK supports the use of queries inthe same format as those executed in the Administration and User Portals. The query parameter isalso the mechanism for providing pagination arguments while iterating through the collection.

dc_list = []dc_page_index = 1dc_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 storedin the locally defined dc_list list variable.

Warning

The list method of a collection is restricted to returning only as many elements as allowedby 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 paginatethrough the results as illustrated in this example.

Alternatively you may choose to set the max parameter of the list method to the maximumnumber of records that you wish to retrieve.

Example 4 2.3. Ret rieving a List o f Resources in a Collect ion Matching a KeywordBased Filter

Retrieving a list of all resources in the datacenters collection that have a storage type of nfs. Inthis example both the query parameter and **kwargs parameter are supplied. The query isused for pagination in the same way as illustrated in the previous example. The **kwargsparameter is used to filter based on the storage type of the data center.

dc_list = []dc_page_index = 1dc_page_current = api.datacenters.list(query="page %s" % dc_page_index, **{"storage_type": "nfs"})

T echnical Guide

380

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 typeof nfs is ultimately stored in the locally defined dc_list list variable.

42.6. Adding a Resource to a Collect ion

The add method of a collection adds a resource. The resource to be added is created based on theparameters provided. Parameters are provided to the add method using an instance of an objectfrom the ovirtsdk.xml.params module. Which specific class from the module needs to be used variesbased on the type of resource being created.

Example 4 2.4 . Adding a Resource to a Collect ion

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 forcreating 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 add method of the collection passing the parameter object as a parameter.

Some parameter objects also have complex parameters of their own.

Example 4 2.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 thisis used as a parameter when creating an instance of a ovirtsdk.xml.params.DataCenterobject containing parameters of the data center to be created. The resource is then created usingthe 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. Updat ing a Resource in a Collect ion


381

42.7. Updat ing a Resource in a Collect ion

To update a resource you must retrieve it from the collection it resides in, modify the desiredparameters, and then call the update method for the resource to save the changes. Parametermodification is performed by using the set_* methods of the retrieved resource.

Example 4 2.6 . Updat ing 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 Collect ion

To remove a resource you must retrieve it from the collection that contains it and call the deletemethod of the resource.

Example 4 2.7. Removing a Resource f rom a Collect ion

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. TheSoftware Development Kit defines exception types in addition to those defined by the Pythoninterpreter itself. These exceptions are located in the ovirtsdk.infrastructure.errors module:

Connect ionError

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.

NoCert if icatesError

Raised when no CA is provided and --insecure is 'False'.

RequestError

T echnical Guide

382

Raised at any kind of oVirt server error.

UnsecuredConnect ionAt temptError

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 4 2.8. Catching a ConnectionError Except ion


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" % err


383

Chapter 43. Python Reference Documentation

43.1. Python Reference Documentat ion

Documentation generated using pydoc is available for the following modules. The documentation isprovided 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 Manageris installed to view the latest version of these documents:

$ pydoc [MODULE]

T echnical Guide

384

http://docs.python.org/library/pydoc.html

Part V. The Java Software Development Kit

Part V. T he Java Soft ware Development Kit

385

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 RedHat Enterprise Virtualization Manager in Java-based projects. By downloading these classes andadding them to your project, you can access a range of functionality for high-level automation ofadministrative tasks.

The Java software development kit uses the rhevm-sdk-java package, which is available to systemssubscribed to a Red Hat Enterprise Virtualization entitlement pool in Red HatSubscription Manager.

44.2. Installing the Java Software Development Kit

Install the Java software development kit and accompanying documentation.

Procedure 4 4 .1. Installing the Java Sof tware Development Kit

1. 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

2. 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.

T echnical Guide

386

Chapter 45. Using the Software Development Kit

This chapter outlines several examples of how to use the Java Software Development Kit.

45.1. Connect ing to the Red Hat Enterprise Virtualizat ion Manager

The Api class is the main class you use to connect to and manipulate objects in a Red HatEnterprise Virtualization environment. There are a number of overloaded constructors to the Apiclass that allow you to specify different options for connecting to the Red Hat Enterprise Virtualizationenvironment, such as authentication details. This section provides examples of how to use theseconstructors 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, seeSection 45.1.3, “Arguments to Constructors of the Api Class” .

4 5.1.1. Basic Authent icat ion

The following is an example of a simple Java SE program that creates a connection with a Red HatEnterprise Virtualization environment using basic authentication, then gracefully shuts down andcloses the connection:

Example 4 5.1. Basic Authent icat ion

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) {

Chapt er 4 5. Using t he Soft ware Development Kit

387

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 isrecommended that you shut down instances of the Api class in a finally block as per theabove example to ensure the connection with the Red Hat Enterprise Virtualization Manager isclosed gracefully.

4 5.1.2. Session-Based Authent icat ion

The following is an example of a simple Java SE program that creates a connection with a Red HatEnterprise Virtualization environment using a session ID, then gracefully shuts down and closes theconnection:

Example 4 5.2. Session-Based Authent icat ion

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);

T echnical Guide

388

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 isrecommended that you shut down instances of the Api class in a finally block as per theabove example to ensure the connection with the Red Hat Enterprise Virtualization Manager isclosed gracefully.

4 5.1.3. Arguments to Const ructors of the Api Class

The following table outlines the key arguments available to constructors for the Api class.

Table 4 5.1. Arguments to Constructors of the Api Class

Method Argument Type Descript ionurl 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 username 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 connectto the Manager.


389

sessionID String The identifier of a session with which to connectto the Manager. If you have alreadyauthenticated with the Manager and a session isavailable, you can specify this argument insteadof specifying a user name and password. Thevalue must be in the format of JSESSIONID=[SESSION_ID]. SeeSection 17.3, “Authentication Sessions” forinstructions on how to determine the sessionidentifier.

requestTimeout Integer The timeout, in seconds, to wait for responses torequests. If a request takes longer than thisvalue to respond, the request is cancelled, andan exception is thrown. This argument isoptional.

sessionTimeout Integer The timeout, in minutes, after which an activesession is destroyed if no requests are made tothe Manager. This argument is optional.

persistentAuth Boolean Enables or disables persistent authenticationusing cookies. This option is enabled bydefault, so this method is only required todisable this option.

noHostVerification

Boolean Enables or disables verification of the hostname in the SSL certificate presented by theserver where the Manager is hosted. By default,the identity of host names is verified, and theconnection is rejected if the host name is notcorrect, so this method is only required todisable this option.

keyStorePath String Specifies the location of a file containing the CAcertificate used to verify the certificate presentedby the server where the Manager is hosted. Thismethod must be used together with the keyStorePassword method.

keyStorePassword String The password used to access the keystore filespecified in the keyStorePath method.

filter Boolean Enables or disables filtering of objects based onthe permissions of the user making the request.By default, this option is disabled, which allowsany user to see all objects in the environment.This method is only required to restrict theobjects in the environment to those visible to theuser making the request.

debug Boolean Enables or disables debug output. By default,this option is disabled.

Method Argument Type Descript ion

45.2. List ing Ent it ies

The following example outlines how to list entities in the Red Hat Enterprise Virtualization Manager. Inthis example, the entities to be listed are virtual machines, which are listed using the getVMs()method of the Api class.

T echnical Guide

390

Procedure 4 5.1. List ing Ent it ies

Declare a List of the type of entity to be listed and use the corresponding method to get the list ofentities:

List<VM> vms = api.getVMs().list();

45.3. Modifying the At t ributes of Resources

The following example outlines how to modify the attributes of a resource. In this example, theattribute to be modified is the description of the virtual machine with the name 'test' , which is changedto ' java_sdk'.

Procedure 4 5.2. Modifying the At t ributes of a Resource

1. Declare an instance of the resource whose attributes are to be modified:

VM vm = api.getVMs().get("test");

2. Set the new value of the attribute:

vm.setDescription("java_sdk");

3. Update the virtual machine to apply the change:

VM newVM = vm.update();

45.4 . Get t ing 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:


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 VirtualizationManager. 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 beadded. Next, the attributes of that virtual machine set to the preferred values. Finally, the new virtualmachine is added to the Manager.


391

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 isreferenced by declaring an instance of that attribute. Finally, the new virtual machine is added to theManager.

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 Act ions on Resources

The following example outlines how to perform actions on a resource. In this example, a virtualmachine with the name 'test' is started.

Procedure 4 5.3. Performing an Act ion on a Resource

1. Declare an instance of the resource:


2. 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);

3. Perform the action:

Action res = vm.start(actionParam);

T echnical Guide

392

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. List ing 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 4 5.4 . List ing Sub-Resources

1. Declare an instance of the resource whose sub-resources are to be listed:


2. List the sub-resources:

List<VMDisk> disks = vm.getDisks().list();

45.8. Get t ing Sub-Resources

The following example outlines how to reference the sub-resources of a resource. In this example, adisk with the name 'my disk' that belongs to a virtual machine with the name 'test' is referenced.

Procedure 4 5.5. Get t ing the Sub-Resources of a Resource

1. Declare an instance of the resource whose sub-resources are to be referenced:


2. 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 diskwith a size of '1073741824L', interface 'virtio' and format 'cow' are added to a virtual machine with thename 'test' .

Procedure 4 5.6 . Adding a Sub-Resource to a Resource

1. Declare an instance of the resource to which sub-resources are to be added:


393


2. Create parameters to define the attributes of the resource:

Disk diskParam = new Disk();diskParam.setProvisionedSize(1073741824L);diskParam.setInterface("virtio");diskParam.setFormat("cow");

3. 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 withthe name 'test_Disk1' belonging to a virtual machine with the name 'test' is changed to'test_Disk1_updated'.

Procedure 4 5.7. Updat ing a Sub-Resource

1. Declare an instance of the resource whose sub-resource is to be modified:


2. Declare an instance of the sub-resource to be modified:

VMDisk disk = vm.getDisks().get("test_Disk1");

3. Set the new value of the attribute:

disk.setAlias("test_Disk1_updated");

4. Update the sub-resource:

VMDisk updateDisk = disk.update();

45.11. Performing Act ions on Sub-Resources

The following example outlines how to perform actions on sub-resources. In this example, a disk withthe name 'test_Disk1' belonging to a virtual machine with the name 'test' is activated.

Procedure 4 5.8. Performing an Act ion on a Sub-Resource

1. Declare an instance of the resource containing the sub-resource on which the action is to beperformed:


2. Declare an instance of the sub-resource:

T echnical Guide

394

VMDisk disk = vm.getDisks().get("test_Disk1");

3. Declare action parameters to send to the sub-resource:

Action actionParam = new Action();

4. Perform the action:

Action result = disk.activate(actionParam);

45.12. Recommended Pract ices

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 SecureSocket Layer (SSL) and the IETF Transport Layer Security (TLS) protocol using the Java SecureSocket Extension (JSSE). JSSE has been integrated into the Java 2 platform as of version 1.4 andworks with the Java SDK out of the box. On older Java 2 versions, JSSE must be manually installedand configured.

Procedure 4 5.9 . Conf iguring SSL

1. Download the certificate for the Red Hat Enterprise Virtualization Manager:

https://[your manager's address]:[port]/ca.crt

2. Generate a keystore:

keytool -import -alias "server.crt truststore" -file ca.crt -keystore server.truststore

3. Make the Java software development kit aware of the keystore via one of the followingmethods:

Create a keystore lookup path:

$ mkdir ~/.ovirtsdk/$ cp server.truststore ~/.ovirtsdk/ovirtsdk-keystore.truststore


395

Once ovirtsdk-keystore.truststore is copied to the ~/.ovirtsdk directory, it will be usedfor host identity validation upon handshake with the destination host.

Use the following signature to specify a custom truststore when declaring instances of the Api class:

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 forproduction systems due to security reasons, unless it is a conscious decision and you areperfectly aware of the security implications of not validating host identity. To disable hostidentity validation, use the following signature when declaring instances of the Api class:

Api api = new Api(url, user, password, true);

T echnical Guide

396

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 acommand line tool for transferring data across various protocols, including HTTP, and supportsmultiple platforms such as Linux, Windows, Mac and Solaris. Most Linux distributions include cURLas 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 requestrequires 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 HatEnterprise Virtualization Manager host within the API entry point path (/api ).

cURL opt ions

-X COMMAND, - - request COMMAND

The request command to use. In the context of the REST API, use GET , POST , PUT or DELETE.

Example: -X GET

-H LINE, - -header LINE

HTTP header to include with the request. Use multiple header options if more than oneheader 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 attributeacts 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 fileis saved locally on the client machine. Use the -k attribute to bypass SSL.

Appendix A. API Usage wit h cURL

397

http://curl.haxx.se/

Example: --cacert ~/Certificates/rhevm.cer

-d BODY, - -data BODY

The body to send for requests. Use with POST , PUT and DELETE requests. Ensure tospecify the Content-Type: application/xml header 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 requestdoes not contain a body.

GET /api/vms HTTP/1.1Accept: 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 POSTrequest requires a body.


<vm> <name>vm1</name> <cluster> <name>default</name> </cluster> <template> <name>Blank</name> </template> <memory>536870912</memory>

T echnical Guide

398

<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 thefollowing 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 PUTrequest requires a body.

PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1Accept: application/xmlContent-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 . DELET E 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

Appendix A. API Usage wit h cURL

399

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 requestheader is optional due to the empty result of DELETE requests.

A.4 .5. DELET E 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 theoptional body.

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1Accept: application/xmlContent-type: application/xml


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.

T echnical Guide

4 00

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 HatEnterprise 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 Virtualization3.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 B. UI Plugins

4 01

Appendix C. Enumerated Value Translation

C.1. Enumerated Value Translat ion

The API uses Red Hat Enterprise Virtualization Query Language to perform search queries. For moreinformation on the Query Language, read the full specification in Performing Searches in Red HatEnterprise 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 QueryLanguage. The following table provides a translation for these key enumerated values.

Table C.1. Enumerated Value Translat ions

Resource Type API EnumerableType

API EnumerableValue

QueryLanguageProperty

QueryLanguage 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

T echnical Guide

4 02

Appendix D. Event Codes

D.1. Event Codes

This table lists all event codes.

Table D.1. Event codes

Code Name Severity Message0 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.


4 03

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}.

Code Name Severity Message

T echnical Guide

4 04

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}).



4 05

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}).


T echnical Guide

4 06

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}.



4 07

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}).


T echnical Guide

4 08

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}.



4 09

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.


T echnical Guide

4 10

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).



4 11

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}.


T echnical Guide

4 12

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



4 13

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}.


T echnical Guide

4 14

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})



4 15

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}.


T echnical Guide

4 16

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}).



4 17

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}.


T echnical Guide

4 18

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}).



4 19

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}).


T echnical Guide

4 20

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}.



4 21

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}.


T echnical Guide

4 22

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.



4 23

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].


T echnical Guide

4 24

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}.



4 25

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


T echnical Guide

4 26

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.



4 27

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}


T echnical Guide

4 28

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})



4 29

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}.


T echnical Guide

4 30

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})



4 31

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}


T echnical Guide

4 32

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})



4 33

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})


T echnical Guide

4 34

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.



4 35

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).


T echnical Guide

4 36

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})



4 37

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.


T echnical Guide

4 38

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}.



4 39

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})


T echnical Guide

4 4 0

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}.



4 4 1

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.


T echnical Guide

4 4 2

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}



4 4 3

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}.


T echnical Guide

4 4 4

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.



4 4 5

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}.


T echnical Guide

4 4 6

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}).



4 4 7

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}.


T echnical Guide

4 4 8

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}.



4 4 9

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.


T echnical Guide

4 50

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}.



4 51

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}


T echnical Guide

4 52

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}



4 53

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.


T echnical Guide

4 54

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}.



4 55

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.


T echnical Guide

4 56

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"



4 57

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.


T echnical Guide

4 58

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.



4 59

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.


T echnical Guide

4 60

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



4 61

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})


T echnical Guide

4 62

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.



4 63

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}'


T echnical Guide

4 64

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}



4 65

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}


T echnical Guide

4 66

Appendix E. Timezones

E.1. T imezones

The API maps Windows Standard Format timezone names to tz database format when specifying atimezone for a virtual machine or VM template. This means the API only accepts certain tz databasecodes, which the following table lists:

Table E.1. Accepted tz database codes

tz database Format Windows Standard FormatAfrica/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

Appendix E. T imezones

4 67

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

t z database Format Windows Standard Format

T echnical Guide

4 68

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

t z database Format Windows Standard Format

Appendix E. T imezones

4 69

Appendix F. Revision History

Revision 3.5-4 0 Wed 25 May 2016 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1325323 - Updated instructions for configuring SSL and connecting to the Manager.BZ#1317129 - Updated instructions for authenticating via a session identifier.

Revision 3.5-39 Wed 04 May 2016 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1260630 - Updated virtual machine migration limitation details.

Revision 3.5-38 Mon 8 Feb 2016 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1294584 - Updated the Storage Pool Manager selection process.BZ#1124128 - Added NUMA content to the guide.

Revision 3.5-37 Thu 14 Jan 2016 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1281667 - Added severity levels and error messages to the table that lists event codes.

Revision 3.5-36 Fri 20 Nov 2015 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1227607 - Added more rhevm shell network interface examples.BZ#978709 - Added gluster storage domain parameters and example.

Revision 3.5-35 Mon 26 Oct 2015 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1215533 - Updated disks to ensure a storage domain is specified at creation and that VMs canhave disks in multiple storage domains.BZ#1201228 - Removed storage_domain_state element as it does not exist.BZ#1240212 - Updated the Python SDK package name.

Revision 3.5-34 Tue 04 Aug 2015 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1229797 - Added the virtualized CPU support limits for Red Hat Enterprise Linux 7 guests.BZ#1215530 - Added the API equivalent of the Run Once button.BZ#1215520 - Added examples for starting a virtual machine with Cloud-Init.BZ#1219797 - Added domain name to the text for adding a group in the API.

Revision 3.5-33 Wed 03 Jun 2015 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

T echnical Guide

4 70

https://bugzilla.redhat.com/show_bug.cgi?id=1325323















BZ#1213615 - Removed Appendix: Certificates from the guide.BZ#1215534 - Updated reboot virtual machine action.BZ#1221419 - Updated examples for creating a virtual machine, and added a method for listing CPUprofiles.BZ#1215519 - Updated the Disks Sub-Collection section with an example of renaming a virtualmachine disk.BZ#1215539 - Updated the start and suspend virtual machine action for clarity.BZ#1215535 - Updated the floating disk attach and detach section to make the content easier tosearch.BZ#1215536 - Updated the API Disks sub-collection to include a new example, 'Creating a new directLUN disk device on a virtual machine'.BZ#1227527 - Added new REST API host power management options.BZ#1215542 - Updated the API Searching Events section to include 'Searching using a specificevent severity'.

Revision 3.5-32 Tue 12 May 2015 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1214991 - Updated the parameter tables for the 'vm' and 'template' resource types.

Revision 3.5-31 Tue 28 Apr 2015 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1178104 - Updated the Quick Start procedure for the rhevm-shell.BZ#1160689 - Updated the XML representation of a disk device.BZ#1123921 - Added an explanation of network interface custom properties.BZ#1204579 - Updated yum-config-manager commands with subscription-manager commands forconsistency.BZ#1172619 - Fixed errors in the XML representation of a host's power management configuration.BZ#1193556 - Added a RHEVM shell command for confirming that a host has been rebooted.BZ#1200878 - Updated the RHEVM shell command for starting a virtual machine.BZ#1206392 - Changed all instances of 'Red Hat Storage' to 'Red Hat Gluster Storage'.BZ#1204582 - Added an explanation of live snapshot deletion.

Revision 3.5-30 Wed 11 Mar 2015 Red Hat EnterpriseVirtualiz at ionDocumentat ion Team

BZ#1100832 - Updated information for the Wipe After Delete action.BZ#1140288 - Updated the table of event codes.BZ#1122727 - No longer displays two events for event code 524.BZ#1105300 - Added information on section headers in the rhevm-shell config file.BZ#991846 - Added missing content from the rhevm-shell config file.

Revision 3.5-29 Wed 11 Feb 2015 Andrew BurdenBZ#1164505 - Updated the XML Representation and the Virtual Machine Elements table to match 3.5API.

Revision 3.5-28 Tue 10 Feb 2015 Andrew BurdenBZ#1075930 - Added JSON representations for key resources.BZ#1127123 - Added statistic resource for rhevm-shell that includes work flow for using ' list' and'show' commands to gather statistical data for resources.BZ#1076263 - Added two topics for requesting additional OVF data for virtual machines and virtualmachine snapshots using the API.


4 71





























Revision 3.5-27 Tue 18 Nov 2014 Andrew BurdenBZ#1120927 - updated 'vm' in the rhevm-shell chapter to include logon action.

Revision 3.5-26 Fri 14 Nov 2014 Andrew BurdenBZ#1120931 - Users can view the user session information of a VM in the API. Added 'DisplayingVirtual Machine Session Information' subcollection and updated 'Virtual Machine Elements'.BZ#1120927 - Users can now logon to a VM using the API in order to externally access the VMconsole. Added 'Logging onto a virtual machine for external console' and updated 'XMLRepresentation of a Virtual Machine'.

Revision 3.5-25 Thu 6 Nov 2014 Andrew BurdenBZ#1100832 - Added new topic 'Settings to Wipe Virtual Disks After Deletion'.'

Revision 3.5-24 Wed 5 Nov 2014 Andrew BurdenBZ#1100832 - Updated information regarding the 'wipe_after_delete' flag in 'Disks Sub-Collection','disks', and 'Floating Disk Elements'.

Revision 3.5-23 Thu 23 Oct 2014 David RyanBZ#1150793 - Updated switch configuration content to remove unsupported examples.

Revision 3.5-22 Wed 22 Oct 2014 Julie WuBZ#1120956 - Updated the current RHEV version to 3.5.

Revision 3.5-21 Wed 22 Oct 2014 Tahlia RichardsonBZ#976691 - Added a new topic: ovirtmgmt Initialization Procedure.

Revision 3.5-20 Tue 14 Oct 2014 David RyanBZ#1012802 - Updated --os-boot and --vm-os-boot command syntax.

Revision 3.5-19 Tue 14 Oct 2014 Andrew BurdenBZ#1092880 - The 'max' parameter should be used for search queries to avoid returning all values.BZ#1139266 - Updated 'Example: List Data Center Collection', 'Data Center Elements', and theexample 'Creating a New Data Center' topics to include changes as to the elements required to createa data center, and the updated query output.BZ#1132800 - Removed references to now-defunct Hypervisor Deployment Guide.BZ#1129907 - Removed reference to the Power User Portal.BZ#1142384 - Updated '14.11. permission' for rhevm-shell so that the table and example provided areaccurate.BZ#1142372 - Corrected the 'user_name' parameter and the example usage of 'domain-name'.BZ#1142345 - Removed reference to search syntax in the Administration Guide. Included examplecommand for list --help. Added a more complex list query example provided by bug reporter.

Revision 3.5-18 Wed 8 Oct 2014 Andrew DahmsBZ#1151252 - Restructured the section on and outlined how to retrieve the latest list of capabilities.BZ#1150335 - Added entries for locale, language, and keyboard to the description of virtualmachines in the REST API.BZ#1108245 - Added a description of and procedures outlining how to use the backup and restoreAPI.

Revision 3.5-17 Fri 3 Oct 2014 Tahlia Richardson

T echnical Guide

4 72




















BZ#1145074 - Corrected the example for ejecting a CD-ROM temporarily and added an example forejecting a CD-ROM permanently.

Revision 3.5-16 Fri 26 Sep 2014 Andrew BurdenBZ#1071948 - Updated information and xml example for the payloads element in two topics, 'XMLRepresentation of a Virtual Machine' and 'Virtual Machine Elements'.

Revision 3.5-15 Fri 19 Sep 2014 Tahlia RichardsonBZ#1143842 - Removed RHN Classic references and changed "Red Hat Network" to "ContentDelivery Network".BZ#1090226 - Updated maximum guest RAM to 4000 GB.BZ#1122999 - Removed empty properties columns from tables.

Revision 3.5-14 Thu 18 Sep 2014 Andrew BurdenBrewing for 3.5-Beta.

Revision 3.5-13 Sat 13 Sep 2014 Andrew DahmsBZ#1131762 - Added a description of virtual machine initialization attributes in the REST API.

Revision 3.5-12 Wed 10 Sep 2014 Julie WuBuilding for splash page.

Revision 3.5-11 Mon 8 Sep 2014 Julie WuBZ#1127755 - Added missing closing tags and changed ' list of LUNs' to ' list of targets'.

Revision 3.5-10 Fri 5 Sep 2014 Julie WuBZ#1134692 - Removed duplicated strings.

Revision 3.5-9 Tues 2 Sep 2014 Andrew BurdenBZ#977202 - Added topic for updating iSCSI storage connections using API.

Revision 3.5-8 Fri 22 Aug 2014 Julie WuBZ#1097312 - Added an important note for modes that support bridged or bridgeless networks.

Revision 3.5-7 Fri 22 Aug 2014 Andrew DahmsBZ#1113515 - Updated the description of the behavior for deleting a snapshot.

Revision 3.5-6 Wed 20 Aug 2014 Lucy BopfBZ#1105590 - Noted that configuring the .rhevmshellrc file is the first option for connecting to therhevm-shell.

Revision 3.5-5 Thu 14 Aug 2014 Andrew DahmsBZ#1076932 - Added an example of how to import images from a Glance storage domain as atemplate.

Revision 3.5-4 Fri 01 Aug 2014 Andrew DahmsBZ#1125456 - Added two examples to the chapter on the Python SDK.BZ#1075505 - Updated the titles of two examples to more exact.BZ#1066553 - Added an example of how to create a live snapshot using the REST API.

Revision 3.5-3 Tue 01 Jul 2014 Andrew Dahms


4 73

















BZ#1117977 - Updated the name of the collection containing information about logical networks inPython.BZ#1113574 - Updated the methods used to interact with the cdroms sub-collection of a virtualmachine.BZ#1075511 - Updated the command used to provide information on network interfaces.BZ#1075505 - Clarified the targets of actions for adding and removing network labels.BZ#1074692 - Updated the syntax of the example to correctly print error messages.BZ#1067115 - Added an example of how to detach a disk from a virtual machine using Python.

Revision 3.5-2 Mon 30 Jun 2014 Lucy BopfBZ#1101252 - Added an example of expanding disk size using the REST API.

Revision 3.5-1 Thu 5 Jun 2014 Lucy BopfInitial creation for the Red Hat Enterprise Virtualization 3.5 release.

T echnical Guide

4 74








Documents

Red Hat Enterprise Virtualization 3.5 Technical Guide