# 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

Object | Permission | Condition
--- | --- | ---
connect | search-interfaces | -

##### Access control return value filters

Object | Permission
--- | ---
interface | getattr

### `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

Object | Permission | Condition
--- | --- | ---
connect | search-interfaces | -

##### Access control return value filters

Object | Permission
--- | ---
interface | getattr

### `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

Object | Permission | Condition
--- | --- | ---
connect | search-interfaces | -

##### Access control return value filters

Object | Permission
--- | ---
interface | getattr

### `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

Object | Permission | Condition
--- | --- | ---
connect | search-interfaces | -

##### Access control return value filters

Object | Permission
--- | ---
interface | getattr

### `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

Object | Permission | Condition
--- | --- | ---
connect | search-interfaces | -

##### Access control return value filters

Object | Permission
--- | ---
interface | getattr

### `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

Object | Permission | Condition
--- | --- | ---
connect | interface-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

Object | Permission | Condition
--- | --- | ---
connect | interface-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

Object | Permission | Condition
--- | --- | ---
connect | interface-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

Object | Permission | Condition
--- | --- | ---
interface | start | -

### `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

Object | Permission | Condition
--- | --- | ---
interface | write | -
interface | save | -

### `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

Object | Permission | Condition
--- | --- | ---
interface | stop | -

### `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

Object | Permission | Condition
--- | --- | ---
interface | read | -

### `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

Object | Permission | Condition
--- | --- | ---
interface | read | -

### `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

Object | Permission | Condition
--- | --- | ---
interface | getattr | -

### `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

Object | Permission | Condition
--- | --- | ---
interface | getattr | -

### `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

Object | Permission | Condition
--- | --- | ---
interface | delete | -