Module libvirt-interface from libvirt

Provides APIs for the management of interfaces

Table of Contents

Types

typedef enum virConnectListAllInterfacesFlags
typedef struct _virInterface virInterface
typedef enum virInterfaceDefineFlags
typedef virInterface * virInterfacePtr
typedef enum virInterfaceXMLFlags

Functions

int	virConnectListAllInterfaces	(virConnectPtr conn, 
virInterfacePtr ** ifaces,
unsigned int flags) int virConnectListDefinedInterfaces (virConnectPtr conn,
char ** const names,
int maxnames) int virConnectListInterfaces (virConnectPtr conn,
char ** const names,
int maxnames) int virConnectNumOfDefinedInterfaces (virConnectPtr conn) int virConnectNumOfInterfaces (virConnectPtr conn) int virInterfaceChangeBegin (virConnectPtr conn,
unsigned int flags) int virInterfaceChangeCommit (virConnectPtr conn,
unsigned int flags) int virInterfaceChangeRollback (virConnectPtr conn,
unsigned int flags) int virInterfaceCreate (virInterfacePtr iface,
unsigned int flags) virInterfacePtr virInterfaceDefineXML (virConnectPtr conn,
const char * xml,
unsigned int flags) int virInterfaceDestroy (virInterfacePtr iface,
unsigned int flags) int virInterfaceFree (virInterfacePtr iface) virConnectPtr virInterfaceGetConnect (virInterfacePtr iface) const char * virInterfaceGetMACString (virInterfacePtr iface) const char * virInterfaceGetName (virInterfacePtr iface) char * virInterfaceGetXMLDesc (virInterfacePtr iface,
unsigned int flags) int virInterfaceIsActive (virInterfacePtr iface) virInterfacePtr virInterfaceLookupByMACString (virConnectPtr conn,
const char * macstr) virInterfacePtr virInterfaceLookupByName (virConnectPtr conn,
const char * name) int virInterfaceRef (virInterfacePtr iface) int virInterfaceUndefine (virInterfacePtr iface)

Description

Types

virConnectListAllInterfacesFlags

Flags used to filter the returned interfaces.

enum virConnectListAllInterfacesFlags {
VIR_CONNECT_LIST_INTERFACES_INACTIVE = 1 (0x1; 1 << 0)
VIR_CONNECT_LIST_INTERFACES_ACTIVE = 2 (0x2; 1 << 1)
}

virInterface

struct virInterface {
The content of this structure is not made public by the API
}

virInterfaceDefineFlags

enum virInterfaceDefineFlags {
VIR_INTERFACE_DEFINE_VALIDATE = 1 (0x1; 1 << 0)
Validate the XML document against schema
}

virInterfacePtr

typedef virInterface * virInterfacePtr;

a virInterfacePtr is pointer to a virInterface private structure, this is the type used to reference a virtual interface in the API.

virInterfaceXMLFlags

enum virInterfaceXMLFlags {
VIR_INTERFACE_XML_INACTIVE = 1 (0x1; 1 << 0)
dump inactive interface information
}

Functions

virConnectListAllInterfaces

int	virConnectListAllInterfaces	(virConnectPtr conn,
					 virInterfacePtr ** ifaces,
					 unsigned int flags)

Collect the list of interfaces, and allocate an array to store those objects. This API solves the race inherent between virConnectListInterfaces and virConnectListDefinedInterfaces.

Normally, all interfaces are returned; however, flags can be used to filter the results for a smaller list of targeted interfaces. The valid flags are divided into groups, where each group contains bits that describe mutually exclusive attributes of a interface, and where all bits within a group describe all possible interfaces.

The only group of flags is VIR_CONNECT_LIST_INTERFACES_ACTIVE (up) and VIR_CONNECT_LIST_INTERFACES_INACTIVE (down) to filter the interfaces by state.

conn
Pointer to the hypervisor connection.
ifaces
Pointer to a variable to store the array containing the interface objects or NULL if the list is not required (just returns number of interfaces).
flags
bitwise-OR of virConnectListAllInterfacesFlags.
Returns
the number of interfaces found or -1 and sets ifaces to NULL in case of error. On success, the array stored into ifaces is guaranteed to have an extra allocated element set to NULL but not included in the return count, to make iteration easier. The caller is responsible for calling virStorageInterfaceFree() on each array element, then calling free() on ifaces.
Access control parameter checks
ObjectPermissionCondition
connectsearch-interfaces-
Access control return value filters
ObjectPermission
interfacegetattr

virConnectListDefinedInterfaces

int	virConnectListDefinedInterfaces	(virConnectPtr conn,
					 char ** const names,
					 int maxnames)

Collect the list of defined (inactive) physical host interfaces, and store their names in names.

The use of this function is discouraged. Instead, use virConnectListAllInterfaces().

conn
pointer to the hypervisor connection
names
array to collect the list of names of interfaces
maxnames
size of names
Returns
the number of names provided in the array or -1 in case of error. Note that this command is inherently racy; a interface can be defined between a call to virConnectNumOfDefinedInterfaces() and this call; you are only guaranteed that all currently defined interfaces were listed if the return is less than maxnames. The client must call free() on each returned name.
Access control parameter checks
ObjectPermissionCondition
connectsearch-interfaces-
Access control return value filters
ObjectPermission
interfacegetattr

virConnectListInterfaces

int	virConnectListInterfaces	(virConnectPtr conn,
					 char ** const names,
					 int maxnames)

Collect the list of active physical host interfaces, and store their names in names

The use of this function is discouraged. Instead, use virConnectListAllInterfaces().

conn
pointer to the hypervisor connection
names
array to collect the list of names of interfaces
maxnames
size of names
Returns
the number of interfaces found or -1 in case of error. Note that this command is inherently racy; a interface can be started between a call to virConnectNumOfInterfaces() and this call; you are only guaranteed that all currently active interfaces were listed if the return is less than maxnames. The client must call free() on each returned name.
Access control parameter checks
ObjectPermissionCondition
connectsearch-interfaces-
Access control return value filters
ObjectPermission
interfacegetattr

virConnectNumOfDefinedInterfaces

int	virConnectNumOfDefinedInterfaces	(virConnectPtr conn)

Provides the number of defined (inactive) interfaces on the physical host.

conn
pointer to the hypervisor connection
Returns
the number of defined interface found or -1 in case of error
Access control parameter checks
ObjectPermissionCondition
connectsearch-interfaces-
Access control return value filters
ObjectPermission
interfacegetattr

virConnectNumOfInterfaces

int	virConnectNumOfInterfaces	(virConnectPtr conn)

Provides the number of active interfaces on the physical host.

conn
pointer to the hypervisor connection
Returns
the number of active interfaces found or -1 in case of error
Access control parameter checks
ObjectPermissionCondition
connectsearch-interfaces-
Access control return value filters
ObjectPermission
interfacegetattr

virInterfaceChangeBegin

int	virInterfaceChangeBegin		(virConnectPtr conn,
					 unsigned int flags)

This function creates a restore point to which one can return later by calling virInterfaceChangeRollback(). This function should be called before any transaction with interface configuration. Once it is known that a new configuration works, it can be committed via virInterfaceChangeCommit(), which frees the restore point.

If virInterfaceChangeBegin() is called when a transaction is already opened, this function will fail, and a VIR_ERR_INVALID_OPERATION will be logged.

conn
pointer to hypervisor connection
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 in case of success and -1 in case of failure.
Access control parameter checks
ObjectPermissionCondition
connectinterface-transaction-

virInterfaceChangeCommit

int	virInterfaceChangeCommit	(virConnectPtr conn,
					 unsigned int flags)

This commits the changes made to interfaces and frees the restore point created by virInterfaceChangeBegin().

If virInterfaceChangeCommit() is called when a transaction is not opened, this function will fail, and a VIR_ERR_INVALID_OPERATION will be logged.

conn
pointer to hypervisor connection
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 in case of success and -1 in case of failure.
Access control parameter checks
ObjectPermissionCondition
connectinterface-transaction-

virInterfaceChangeRollback

int	virInterfaceChangeRollback	(virConnectPtr conn,
					 unsigned int flags)

This cancels changes made to interfaces settings by restoring previous state created by virInterfaceChangeBegin().

If virInterfaceChangeRollback() is called when a transaction is not opened, this function will fail, and a VIR_ERR_INVALID_OPERATION will be logged.

conn
pointer to hypervisor connection
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 in case of success and -1 in case of failure.
Access control parameter checks
ObjectPermissionCondition
connectinterface-transaction-

virInterfaceCreate

int	virInterfaceCreate		(virInterfacePtr iface,
					 unsigned int flags)

Activate an interface (i.e. call "ifup").

If there was an open network config transaction at the time this interface was defined (that is, if virInterfaceChangeBegin() had been called), the interface will be brought back down (and then undefined) if virInterfaceChangeRollback() is called.

iface
pointer to a defined interface
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 in case of success, -1 in case of error
Access control parameter checks
ObjectPermissionCondition
interfacestart-

virInterfaceDefineXML

virInterfacePtr	virInterfaceDefineXML	(virConnectPtr conn,
					 const char * xml,
					 unsigned int flags)

Define an inactive persistent physical host interface or modify an existing persistent one from the XML description.

Normally this change in the interface configuration is immediately permanent/persistent, but if virInterfaceChangeBegin() has been previously called (i.e. if an interface config transaction is open), the new interface definition will only become permanent if virInterfaceChangeCommit() is called prior to the next reboot of the system running libvirtd. Prior to that time, it can be explicitly removed using virInterfaceChangeRollback(), or will be automatically removed during the next reboot of the system running libvirtd.

virInterfaceFree should be used to free the resources after the interface object is no longer needed.

conn
pointer to the hypervisor connection
xml
the XML description for the interface, preferably in UTF-8
flags
bitwise-OR of virInterfaceDefineFlags
Returns
NULL in case of error, a pointer to the interface otherwise
Access control parameter checks
ObjectPermissionCondition
interfacewrite-
interfacesave-

virInterfaceDestroy

int	virInterfaceDestroy		(virInterfacePtr iface,
					 unsigned int flags)

deactivate an interface (ie call "ifdown") This does not remove the interface from the config, and does not free the associated virInterfacePtr object.

If there is an open network config transaction at the time this interface is destroyed (that is, if virInterfaceChangeBegin() had been called), and if the interface is later undefined and then virInterfaceChangeRollback() is called, the restoral of the interface definition will also bring the interface back up.

iface
an interface object
flags
extra flags; not used yet, so callers should always pass 0
Returns
0 in case of success and -1 in case of failure.
Access control parameter checks
ObjectPermissionCondition
interfacestop-

virInterfaceFree

int	virInterfaceFree		(virInterfacePtr iface)

Free the interface object. The interface itself is unaltered. The data structure is freed and should not be used thereafter.

iface
an interface object
Returns
0 in case of success and -1 in case of failure.

virInterfaceGetConnect

virConnectPtr	virInterfaceGetConnect	(virInterfacePtr iface)

Provides the connection pointer associated with an interface. The reference counter on the connection is not increased by this call.

iface
pointer to an interface
Returns
the virConnectPtr or NULL in case of failure.

virInterfaceGetMACString

const char *	virInterfaceGetMACString	(virInterfacePtr iface)

Get the MAC for an interface as string. For more information about MAC see RFC4122.

iface
an interface object
Returns
a pointer to the MAC address (in null-terminated ASCII format) or NULL, the string need not be deallocated its lifetime will be the same as the interface object.

virInterfaceGetName

const char *	virInterfaceGetName	(virInterfacePtr iface)

Get the public name for that interface

iface
an interface object
Returns
a pointer to the name or NULL, the string need not be deallocated its lifetime will be the same as the interface object.

virInterfaceGetXMLDesc

char *	virInterfaceGetXMLDesc		(virInterfacePtr iface,
					 unsigned int flags)

VIR_INTERFACE_XML_INACTIVE - return the static configuration, suitable for use redefining the interface via virInterfaceDefineXML()

Provide an XML description of the interface. If VIR_INTERFACE_XML_INACTIVE is set, the description may be reused later to redefine the interface with virInterfaceDefineXML(). If it is not set, the ip address and netmask will be the current live setting of the interface, not the settings from the config files.

iface
an interface object
flags
bitwise-OR of extraction flags. Current valid bits:
Returns
a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. The caller must free() the returned value.
Access control parameter checks
ObjectPermissionCondition
interfaceread-

virInterfaceIsActive

int	virInterfaceIsActive		(virInterfacePtr iface)

Determine if the interface is currently running

iface
pointer to the interface object
Returns
1 if running, 0 if inactive, -1 on error
Access control parameter checks
ObjectPermissionCondition
interfaceread-

virInterfaceLookupByMACString

virInterfacePtr	virInterfaceLookupByMACString	(virConnectPtr conn,
						 const char * macstr)

Try to lookup an interface on the given hypervisor based on its MAC.

virInterfaceFree should be used to free the resources after the interface object is no longer needed.

conn
pointer to the hypervisor connection
macstr
the MAC for the interface (null-terminated ASCII format)
Returns
a new interface object or NULL in case of failure. If the interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
Access control parameter checks
ObjectPermissionCondition
interfacegetattr-

virInterfaceLookupByName

virInterfacePtr	virInterfaceLookupByName	(virConnectPtr conn,
						 const char * name)

Try to lookup an interface on the given hypervisor based on its name.

virInterfaceFree should be used to free the resources after the interface object is no longer needed.

conn
pointer to the hypervisor connection
name
name for the interface
Returns
a new interface object or NULL in case of failure. If the interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
Access control parameter checks
ObjectPermissionCondition
interfacegetattr-

virInterfaceRef

int	virInterfaceRef			(virInterfacePtr iface)

Increment the reference count on the interface. For each additional call to this method, there shall be a corresponding call to virInterfaceFree to release the reference count, once the caller no longer needs the reference to this object.

This method is typically useful for applications where multiple threads are using a connection, and it is required that the connection remain open until all threads have finished using it. ie, each new thread using an interface would increment the reference count.

iface
the interface to hold a reference on
Returns
0 in case of success, -1 in case of failure.

virInterfaceUndefine

int	virInterfaceUndefine		(virInterfacePtr iface)

Undefine an interface, ie remove it from the config. This does not free the associated virInterfacePtr object.

Normally this change in the interface configuration is permanent/persistent, but if virInterfaceChangeBegin() has been previously called (i.e. if an interface config transaction is open), the removal of the interface definition will only become permanent if virInterfaceChangeCommit() is called prior to the next reboot of the system running libvirtd. Prior to that time, the definition can be explicitly restored using virInterfaceChangeRollback(), or will be automatically restored during the next reboot of the system running libvirtd.

iface
pointer to a defined interface
Returns
0 in case of success, -1 in case of error
Access control parameter checks
ObjectPermissionCondition
interfacedelete-