4/30/2016 libvirt:ThelibvirtAPIconcepts

Search

Home ThelibvirtAPIconcepts
News ThispagedescribesthemainprinciplesandarchitecturechoicesbehindthedefinitionofthelibvirtAPI:

Applications ObjectsExposed
FunctionsandNamingConventions
Downloads ThelibvirtDrivers
Documentation DaemonandRemoteAccess

Compiling ObjectsExposed
Deployment Asdefinedinthegoalssection,thelibvirtAPIisdesignedtoexposealltheresourcesneededtomanagethevirtualization
supportofrecentoperatingsystems.ThefirstobjectmanipulatedthroughtheAPIisthevirConnectPtr,whichrepresents
Architecture
theconnectiontoahypervisor.AnyapplicationusinglibvirtislikelytostartusingtheAPIbycallingoneofthe
Goals virConnectOpenfunctions.YouwillnotethatthosefunctionstakeanameargumentwhichisactuallyaconnectionURIto
selecttherighthypervisortoopen.AURIisneededtoallowremoteconnectionsandalsoselectbetweendifferentpossible
APIconcepts hypervisors.Forexample,onaLinuxsystemitmaybepossibletousebothKVMandLinuxContainersonthesamenode.
ANULLnamewilldefaulttoapreselectedhypervisor,butit'sprobablynotawisethingtodoinmostcases.Seethe
Domains
connectionURIpageforafulldescriptionsofthevaluesallowed.
Network
OnDevicetheapplicationobtainsavirConnectPtrconnectiontothehypervisoritcanthenuseittomanagethehypervisor's
Storage availabledomainsandrelatedvirtualizationresources,suchasstorageandnetworking.Allthoseareexposedasfirst
classobjectsandconnectedtothehypervisorconnection(andthenodeorclusterwhereitisavailable).
NodeDevices

Secureusage

XMLformat

Drivers

APIreference

Languagebindings

Internals

DevelopmentGuide

VirshCommands

Governance

Wiki

FAQ

Bugreports

Contact

Testsuites

RelatedLinks

Sitemap

ThefigureaboveshowsthefivemainobjectsexportedbytheAPI:

virConnectPtr

Representstheconnectiontoahypervisor.UseoneofthevirConnectOpenfunctionstoobtainconnectiontothe
hypervisorwhichisthenusedasaparametertootherconnectionAPI's.

http://libvirt.org/api.html 1/5
4/30/2016 libvirt:ThelibvirtAPIconcepts
virDomainPtr

Representsonedomaineitheractiveordefined(i.e.existingaspermanentconfigfileandstoragebutnotcurrently
runningonthatnode).ThefunctionvirConnectListAllDomainslistsallthedomainsforthehypervisor.

virNetworkPtr

Representsonenetworkeitheractiveordefined(i.e.existingaspermanentconfigfileandstoragebutnotcurrently
activated).ThefunctionvirConnectListAllNetworkslistsallthevirtualizationnetworksforthehypervisor.

virStorageVolPtr

Representsonestoragevolumegenerallyusedasablockdeviceavailabletooneofthedomains.Thefunction
virStorageVolLookupByPathfindsthestoragevolumeobjectbasedonitspathonthenode.

virStoragePoolPtr

Representsastoragepool,whichisalogicalareausedtoallocateandstorestoragevolumes.Thefunction
virConnectListAllStoragePoolslistsallofthevirtualizationstoragepoolsonthehypervisor.Thefunction
virStoragePoolLookupByVolumefindsthestoragepoolcontainingagivenstoragevolume.

MostobjectsmanipulatedbythelibrarycanalsoberepresentedusingXMLdescriptions.Thisisusedprimarilytocreate
thoseobject,butisalsohelpfultomodifyorsavetheirdescriptionback.

Domains,networks,andstoragepoolscanbeeitheractivei.e.eitherrunningoravailableforimmediateuse,ordefinedin
whichcasetheyareinactivebutthereisapermanentdefinitionavailableinthesystemforthem.Basedonthistheycanbe
activateddynamicallyinordertobeused.

Mostobjectscanalsobenamedinvariousways:

name

Auserfriendlyidentifierbutwhoseuniquenesscannotbeguaranteedbetweentwonodes.

ID

Aruntimeuniqueidentifierprovidedbythehypervisorforonegivenactivationoftheobjecthowever,itbecomes
invalidoncetheresourceisdeactivated.

UUID

A16byteuniqueidentifierasdefinedinRFC4122,whichisguaranteedtobeuniqueforlongtermusageandacross
asetofnodes.

FunctionsandNamingConventions
Thenamingofthefunctionspresentinthelibraryisusuallycomposedbyaprefixdescribingtheobjectassociatedtothe
functionandaverbdescribingtheactiononthatobject.

ForeachfirstclassobjectyouwillfindAPIsforthefollowingactions:

Lookup[...LookupBy...]

Usedtoperformlookupsonobjectsbysometypeofidentifier,suchas:

virDomainLookupByID
virDomainLookupByName
virDomainLookupByUUID
virDomainLookupByUUIDString
Enumeration[virConnectList...,virConnectNumOf...]

Usedtoenumerateasetofobjectavailabletoangivenhypervisorconnectionsuchas:

virConnectListDomains
virConnectNumOfDomains
virConnectListNetworks
virConnectListStoragePools
Description[...GetInfo]

Genericaccessorprovidingasetofgenericinformationaboutanobject,suchas:

http://libvirt.org/api.html 2/5
4/30/2016 libvirt:ThelibvirtAPIconcepts
virNodeGetInfo
virDomainGetInfo
virStoragePoolGetInfo
virStorageVolGetInfo
Accessors[...Get...,...Set...]

Specificaccessorsusedtoqueryormodifydataforthegivenobject,suchas:

virConnectGetType
virDomainGetMaxMemory
virDomainSetMemory
virDomainGetVcpus
virStoragePoolSetAutostart
virNetworkGetBridgeName
Creation[...Create,...CreateXML]

Usedtocreateandstartobjects.The...CreateXMLAPIswillcreatetheobjectbasedonanXMLdescription,whilethe
...CreateAPIswillcreatetheobjectbasedonexistingobjectpointer,suchas:

virDomainCreate
virDomainCreateXML
virNetworkCreate
virNetworkCreateXML
Destruction[...Destroy]

Usedtoshutdownordeactivateanddestroyobjects,suchas:

virDomainDestroy
virNetworkDestroy
virStoragePoolDestroy

Note:functionsreturningvir*Ptr(likethevirDomainLookupfunctions)allocatememorywhichneedstobefreedbythe
callerbythecorrespondingvir*Freefunction(e.g.virDomainFreeforavirDomainPtrobject).

FormoreindepthdetailsofthestoragerelatedAPIsseethestoragemanagementpage.

ThelibvirtDrivers
Driversarethebasicbuildingblockforlibvirtfunctionalitytosupportthecapabilitytohandlespecifichypervisordrivercalls.
DriversarediscoveredandregisteredduringconnectionprocessingaspartofthevirInitializeAPI.Eachdriverhasa
registrationAPIwhichloadsupthedriverspecificfunctionreferencesforthelibvirtAPIstocall.Thefollowingisasimplistic
viewofthehypervisordrivermechanism.Considerthestackedlistofdriversasaseriesofmodulesthatcanbeplugged
intothearchitecturedependingonhowlibvirtisconfiguredtobebuilt.

http://libvirt.org/api.html 3/5
4/30/2016 libvirt:ThelibvirtAPIconcepts

Thedriverarchitectureisalsousedtosupportothervirtualizationcomponentssuchasstorage,storagepools,hostdevice,
networking,networkinterfaces,andnetworkfilters.

Seethelibvirtdriverspageformoreinformationonhypervisorandstoragespecificdrivers.

Notalldriverssupporteveryvirtualizationfunctionpossible.ThelibvirtAPIsupportmatrixliststhevariousfunctionsand
supportfoundineachdriverbytheversionsupportwasaddedintolibvirt.

DaemonandRemoteAccess
AccesstolibvirtdriversisprimarilyhandledbythelibvirtddaemonthroughtheremotedriverviaanRPC.Some
hypervisorsdosupportclientsideconnectionsandresponses,suchasTest,OpenVZ,VMware,PowerVM(phyp),
VirtualBox(vbox),ESX,HyperV,Xen,andVirtuozzo.Thelibvirtddaemonserviceisstartedonthehostatsystemboot
timeandcanalsoberestartedatanytimebyaproperlyprivilegeduser,suchasroot.Thelibvirtddaemonusesthesame
libvirtAPIvirInitializesequenceasapplicationsforclientsidedriverregistrations,butthenextendstheregistereddriver
listtoencompassallknowndriverssupportedforalldrivertypessupportedonthehost.

ThelibvirtclientapplicationsuseaURItoobtainthevirConnectPtr.ThevirConnectPtrkeepstrackofthedriverconnection
plusavarietyofotherconnections(network,interface,storage,etc.).ThevirConnectPtristhenusedasaparameterto
othervirtualizationfunctions.Dependinguponthedriverbeingused,callswillberoutedthroughtheremotedrivertothe
libvirtddaemon.Thedaemonwillreferencetheconnectionspecificdriverinordertoretrievetherequestedinformation
andthenpassbackstatusand/ordatathroughtheconnectionbacktotheapplication.Theapplicationcanthendecide
whattodowiththatdata,suchasdisplay,writelogdata,etc.Migrationisanexampleofmanyfacetsofthearchitecturein
use.

http://libvirt.org/api.html 4/5
4/30/2016 libvirt:ThelibvirtAPIconcepts

Thekeytakeawayfromtheabovediagramisthatthereisaremotedriverwhichhandlestransactionsforamajorityofthe
drivers.Thelibvirtddaemonrunningonthehostwillreceivetransactionrequestsfromtheremotedriverandwillthen
querythehypervisordriverasspecifiedinthevirConnectPtrinordertofetchthedata.Thedatawillthenbereturned
throughtheremotedrivertotheclientapplicationforprocessing.

Ifyouareinterestedincontributingtolibvirt,readtheFAQandhackingguidelinestogainanunderstandingofbasicrules
andguidelines.InordertoaddnewAPIfunctionalityfollowtheinstructionsregardingimplementinganewAPIinlibvirt.

http://libvirt.org/api.html 5/5