[libvirt_application_development_guide_using_python] Network Interface chapter - added examples 1-4 - some reformatting done
3:22 p.m.
commit eea89d005b8c0be5a404b6cf107cfe026d4d768b
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Tue Aug 4 10:29:37 2015 -0500
Network Interface chapter
- added examples 1-4
- some reformatting done
en-US/Network_Interfaces.xml | 856 +++++++++++++--------------
en-US/extras/NetworkInterface-Example-1.xml | 7 +
en-US/extras/NetworkInterface-Example-2.xml | 8 +
en-US/extras/NetworkInterface-Example-3.xml | 13 +
en-US/extras/NetworkInterface-Example-4.xml | 9 +
5 files changed, 441 insertions(+), 452 deletions(-)
---
diff --git a/en-US/Network_Interfaces.xml b/en-US/Network_Interfaces.xml
index 6dca97e..c4cb929 100644
--- a/en-US/Network_Interfaces.xml
+++ b/en-US/Network_Interfaces.xml
@@ -4,509 +4,461 @@
%BOOK_ENTITIES;
]>
<chapter
id="libvirt_application_development_guide_using_python-Network_Interfaces">
- <title>Network Interfaces</title>
- <para>
- This section covers the management of physical network interfaces
- using the libvirt API.
- </para>
-
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Overview">
- <title>Overview</title>
+ <title>Network Interfaces</title>
<para>
- The configuration of network interfaces on physical hosts can be
- examined and modified with functions in the
<literal>virInterface</literal> API. This is
- useful for setting up the host to share one physical interface bewteen
- multiple guest domains you want connected directly to the network
- (briefly - enslave a physical interface to the bridge, then create a
- tap device for each VM you want to share the interface), as well as
- for general host network interface management. In addition to physical
- hardware, this API can also be used to configure bridges, bonded
- interfaces, and vlan interfaces.
+ This section covers the management of physical network interfaces
+ using the libvirt <literal>virInterface</literal> class.
</para>
- <para>
- The <literal>virInterface</literal> API is
<emphasis>not</emphasis> used to configure virtual networks (used
- to conceal the guest domain's interface behind a NAT); virtual networks are
- instead configured using the <literal>virNetwork</literal> API
described in <xref
linkend="libvirt_application_development_guide_using_python-Virtual_Networks"
/>.
- </para>
- <para>
- Each host interface is represented in the API by a
<literal>virInterfacePtr</literal> - a
- pointer to an "interface object" - and each of these has a single
- unique identifier:
- </para>
- <para>
- <literal>name</literal>: a string unique among all interfaces (active
or inactive) on a
- host. This is the same string used by the operating system to identify
- the interface (eg: "eth0" or "br1").
- </para>
- <para>
- Each interface object also has a second, non-unique index that can be
- duplicated in other interfaces on the same host:
- </para>
- <para>
- <literal>mac</literal>: an ASCII string representation of the MAC
address of this
- interface. Since multiple interfaces can share the same MAC address
- (for example, in the case of VLANs), this is <emphasis>not</emphasis> a
unique
- identifier. However, it can still be used to search for an interface.
- </para>
- <para>
- All interfaces configured with libvirt should be considered as
- persistent, since libvirt is actually changing the host's own
- persistent configuration data (usually contained in files somewhere
- under <filename>/etc</filename>), and not the interface itself.
However, there are API
- functions to start and stop interfaces, and those actions cause the
- new configuration to be applied to the interface immediately.
- </para>
- <para>
- When a new interface is defined (with
<literal>virInterfaceDefineXML</literal>), or the
- configuration of an existing interface is changed (again, with
- <literal>virInterfaceDefineXML</literal>), this configuration will be
stored on the host.
- The live configuration of the interface itself will not be changed
- until either the interface is started (with
<literal>virInterfaceCreate</literal>), or
- the host is rebooted.
- </para>
- </section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-XML_Format">
- <title>XML Interface Description Format</title>
- <para>
- The current Relax NG definition of the XML that is produced and accepted
- by <literal>virInterfaceDefineXML</literal> and
<literal>virInterfaceGetXMLDesc</literal> can be found in the
- file <filename>data/xml/interface.rng</filename> of the
<package>netcf</package> package, available at
- <ulink
url="http://git.fedorahosted.org/git/netcf.git?p=netcf.git;a=tree&qu...;.
Below are some examples of common interface configurations.
- </para>
- <example>
- <title>XML definition of an ethernet interface using DHCP</title>
- <programlisting>
-<![CDATA[<interface type='ethernet' name='eth0'>
- <start mode='onboot'/>
- <mac address='aa:bb:cc:dd:ee:ff'/>
- <protocol family='ipv4'>
- <dhcp/>
- </protocol>
-</interface>]]>
- </programlisting>
- </example>
-
- <example>
- <title>XML definition of an ethernet interface with static IP</title>
- <programlisting>
-<![CDATA[<interface type='ethernet' name='eth0'>
- <start mode='onboot'/>
- <mac address='aa:bb:cc:dd:ee:ff'/>
- <protocol family='ipv4'>
- <ip address="192.168.0.5" prefix="24"/>
- <route gateway="192.168.0.1"/>
- </protocol>
-</interface>]]>
- </programlisting>
- </example>
-
- <example>
- <title>XML definition of a bridge device with eth0 and eth1
attached</title>
- <programlisting>
-<![CDATA[<interface type="bridge" name="br0">
- <start mode="onboot"/>
- <mtu size="1500"/>
- <protocol family="ipv4">
- <dhcp/>
- </protocol>
- <bridge stp="off" delay="0.01">
- <interface type="ethernet" name="eth0">
- <mac address="ab:bb:cc:dd:ee:ff"/>
- </interface>
- <interface type="ethernet" name="eth1"/>
- </bridge>
-</interface>]]>
- </programlisting>
- </example>
-
- <example>
- <title>XML definition of a vlan interface associated with eth0</title>
- <programlisting>
-<![CDATA[<interface type="vlan" name="eth0.42">
- <start mode="onboot"/>
- <protocol family="ipv4">
- <dhcp peerdns="no"/>
- </protocol>
- <vlan tag="42">
- <interface name="eth0"/>
- </vlan>
-</interface>]]>
- </programlisting>
- </example>
- </section>
-
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information">
- <title>Retrieving Information About Interfaces</title>
-
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-Listing">
- <title>Enumerating Interfaces</title>
- <para>
- Once you have a connection to a host, represented by a
<literal>virConnectPtr</literal>, you can determine
- the number of interfaces on the host with
<literal>virConnectNumOfInterfaces</literal>
- and <literal>virConnectNumOfDefinedInterfaces</literal>. A list of
those interfaces'
- names can be obtained with
<literal>virConnectListInterfaces</literal> and
- <literal>virConnectListDefinedInterfaces</literal>
("defined" interfaces are those that
- have been defined, but are currently inactive). Each of these
- functions takes a connection object as its first argument; the list
- functions also take an argument pointing to a char* array for the
- result, and another giving the maximum number of entries to put in
- that array. All four functions return the number of interfaces found, or
- -1 if an error is encountered.
- </para>
-
- <example>
- <title>Getting a list of active ("up") interfaces on a
host</title>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Overview">
+ <title>Overview</title>
<para>
- Note: error handling omitted for clarity
+ The configuration of network interfaces on physical hosts can be
+ examined and modified with methods in the
<literal>virInterface</literal> class. This is
+ useful for setting up the host to share one physical interface bewteen
+ multiple guest domains you want connected directly to the network
+ (briefly - enslave a physical interface to the bridge, then create a
+ tap device for each VM you want to share the interface), as well as
+ for general host network interface management. In addition to physical
+ hardware, this API can also be used to configure bridges, bonded
+ interfaces, and vlan interfaces.
+ </para>
+ <para>
+ The <literal>virInterface</literal> class is
<emphasis>not</emphasis> used to configure virtual networks (used
+ to conceal the guest domain's interface behind a NAT); virtual networks
are
+ instead configured using the <literal>virNetwork</literal> class
described in <xref
linkend="libvirt_application_development_guide_using_python-Virtual_Networks"
/>.
+ </para>
+ <para>
+ Each host interface is represented by an instance of the
<literal>virInterfacePtr</literal> class
+ and each of these has a single unique identifier:
+ </para>
+ <para>
+ The <literal>name</literal> method returms a string unique among
all interfaces (active or inactive) on a
+ host. This is the same string used by the operating system to identify
+ the interface (eg: "eth0" or "br1").
+ </para>
+ <para>
+ Each interface object also has a second, non-unique index that can be
+ duplicated in other interfaces on the same host:
+ </para>
+ <para>
+ The <literal>MACString</literal> method returns an ASCII string
representation of the MAC address of this
+ interface. Since multiple interfaces can share the same MAC address
+ (for example, in the case of VLANs), this is
<emphasis>not</emphasis> a unique
+ identifier. However, it can still be used to search for an interface.
+ </para>
+ <para>
+ All interfaces configured with libvirt should be considered as
+ persistent, since libvirt is actually changing the host's own
+ persistent configuration data (usually contained in files somewhere
+ under <filename>/etc</filename>), and not the interface itself.
+ </para>
+ <para>
+ When a new interface is defined (using the
<literal>interfaceDefineXML</literal> method), or the
+ configuration of an existing interface is changed (again, with
+ <literal>interfaceDefineXML</literal> method), this configuration
will be stored on the host.
+ The live configuration of the interface itself will not be changed
+ until the interface is restarted manually or the host is rebooted.
</para>
- <programlisting>
-<![CDATA[int numIfaces, i;
-char *ifaceNames;
-
-numIfaces = virConnectNumOfInterfaces(conn);
-ifaceNames = malloc(numIfaces * sizeof(char*));
-numIfaces = virConnectListInterfaces(conn, names, ct);
-
-printf("Active host interfaces:\n");
-for (i = 0; i < numIfaces; i++) {
- printf(" %s\n", ifaceNames[i]);
- free(ifaceNames[i]);
-}
-free(ifaceNames);]]>
- </programlisting>
- </example>
-
- <example>
- <title>Getting a list of inactive ("down") interfaces on a
host</title>
- <programlisting>
-<![CDATA[int numIfaces, i;
-char *ifaceNames;
-
-numIfaces = virConnectNumOfDefinedInterfaces(conn);
-ifaceNames = malloc(numIfaces * sizeof(char*));
-numIfaces = virConnectListDefinedInterfaces(conn, names, ct);
-
-printf("Inactive host interfaces:\n");
-for (i = 0; i < numIfaces; i++) {
- printf(" %s\n", ifaceNames[i]);
- free(ifaceNames[i]);
-}
-free(ifaceNames);]]>
- </programlisting>
- </example>
</section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-AltListing">
- <title>Alternative method of enumerating interfaces</title>
- <para>
- It is also possible to get a list of interfaces from the
<literal>virNodeDevice</literal>
- function. Calling <literal>virNodeListDevices</literal> with the
<parameter>cap</parameter> argument (capabilities)
- set to <literal>net</literal>. This will return a list of device
names (each starting
- with "net_"), and those device names can, in turn, be sent through
- <literal>virNodeDeviceLookupByName</literal>, then
<literal>virNodeDeviceGetXMLDesc</literal> to get an XML
- string containing the interfaces' names, MAC addresses, and 802.11
- vs. 802.03 status (wired vs wireless). See <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config"
/> for more
- information and examples of using <literal>virNodeDevice</literal>
functions for this
- purpose.
- </para>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-XML_Format">
+ <title>XML Interface Description Format</title>
+ <para>
+ The current Relax NG definition of the XML that is produced and accepted
+ by <literal>virInterfaceDefineXML</literal> and
<literal>virInterfaceGetXMLDesc</literal> can be found in the
+ file <filename>data/xml/interface.rng</filename> of the
<package>netcf</package> package, available at
+ <ulink
url="http://git.fedorahosted.org/git/netcf.git?p=netcf.git;a=tree&qu...;.
Below are some examples of common interface configurations.
+ </para>
+ <example>
+ <title>XML definition of an ethernet interface using
DHCP</title>
+ <programlisting language="XML"><xi:include
href="extras/NetworkInterface-Example-1.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+
+ <example>
+ <title>XML definition of an ethernet interface with static
IP</title>
+ <programlisting language="XML"><xi:include
href="extras/NetworkInterface-Example-2.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+
+ <example>
+ <title>XML definition of a bridge device with eth0 and eth1
attached</title>
+ <programlisting language="XML"><xi:include
href="extras/NetworkInterface-Example-3.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+
+ <example>
+ <title>XML definition of a vlan interface associated with
eth0</title>
+ <programlisting language="XML"><xi:include
href="extras/NetworkInterface-Example-4.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-Fetching">
- <title>Obtaining a virInterfacePtr for an Interface</title>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information">
+ <title>Retrieving Information About Interfaces</title>
+
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-Listing">
+ <title>Enumerating Interfaces</title>
+ <para>
+ Once you have a connection to a host you can determine
+ the number of interfaces on the host with
<literal>virConnectNumOfInterfaces</literal>
+ and <literal>numOfDefinedInterfaces</literal> method. A list of
those interfaces'
+ names can be obtained with <literal>listInterfaces</literal>
method and
+ <literal>listDefinedInterfaces</literal> method
("defined" interfaces are those that
+ have been defined, but are currently inactive).
+ The list methods return a Python <literal>list</literal>.
+ All four functions return <literal>None</literal> if an error
is encountered.
+ </para>
+
+ <example>
+ <title>Getting a list of active ("up") interfaces on a
host</title>
+ <para>
+ Note: error handling omitted for clarity
+ </para>
+ <programlisting>
+ <![CDATA[int numIfaces, i;
+ char *ifaceNames;
+
+ numIfaces = virConnectNumOfInterfaces(conn);
+ ifaceNames = malloc(numIfaces * sizeof(char*));
+ numIfaces = virConnectListInterfaces(conn, names, ct);
+
+ printf("Active host interfaces:\n");
+ for (i = 0; i < numIfaces; i++) {
+ printf(" %s\n", ifaceNames[i]);
+ free(ifaceNames[i]);
+ }
+ free(ifaceNames);]]>
+ </programlisting>
+ </example>
+
+ <example>
+ <title>Getting a list of inactive ("down") interfaces on a
host</title>
+ <programlisting>
+ <![CDATA[int numIfaces, i;
+ char *ifaceNames;
+
+ numIfaces = virConnectNumOfDefinedInterfaces(conn);
+ ifaceNames = malloc(numIfaces * sizeof(char*));
+ numIfaces = virConnectListDefinedInterfaces(conn, names, ct);
+
+ printf("Inactive host interfaces:\n");
+ for (i = 0; i < numIfaces; i++) {
+ printf(" %s\n", ifaceNames[i]);
+ free(ifaceNames[i]);
+ }
+ free(ifaceNames);]]>
+ </programlisting>
+ </example>
+ </section>
- <para>
- Many operations require that you have a
<literal>virInterfacePtr</literal>, but you may
- only have the name or MAC address of the interface. You can use
- <literal>virInterfaceLookupByName</literal> and
<literal>virInterfaceLookupByMACString</literal> to get the
- <literal>virInterfacePtr</literal> in these cases.
- </para>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-AltListing">
+ <title>Alternative method of enumerating interfaces</title>
+ <para>
+ It is also possible to get a list of interfaces from the
<literal>virNodeDevice</literal>
+ function. Calling <literal>virNodeListDevices</literal> with the
<parameter>cap</parameter> argument (capabilities)
+ set to <literal>net</literal>. This will return a list of device
names (each starting
+ with "net_"), and those device names can, in turn, be sent through
+ <literal>virNodeDeviceLookupByName</literal>, then
<literal>virNodeDeviceGetXMLDesc</literal> to get an XML
+ string containing the interfaces' names, MAC addresses, and 802.11
+ vs. 802.03 status (wired vs wireless). See <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config"
/> for more
+ information and examples of using <literal>virNodeDevice</literal>
functions for this
+ purpose.
+ </para>
+ </section>
- <example>
- <title>Fetching the virInterfacePtr for a given interface
name</title>
- <programlisting>
-<![CDATA[virInterfacePtr iface;
-const char *name = "eth0";
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-Fetching">
+ <title>Obtaining a virInterfacePtr for an Interface</title>
-iface = virInterfaceLookupByName(name);
+ <para>
+ Many operations require that you have a
<literal>virInterfacePtr</literal>, but you may
+ only have the name or MAC address of the interface. You can use
+ <literal>virInterfaceLookupByName</literal> and
<literal>virInterfaceLookupByMACString</literal> to get the
+ <literal>virInterfacePtr</literal> in these cases.
+ </para>
-if (iface) {
+ <example>
+ <title>Fetching the virInterfacePtr for a given interface
name</title>
+ <programlisting>
+ <![CDATA[virInterfacePtr iface;
+ const char *name = "eth0";
- /* use the virInterfacePtr ... */
+ iface = virInterfaceLookupByName(name);
- virInterfaceFree(iface);
-} else {
- printf("Interface '%s' not found.\n", name);
-}]]>
- </programlisting>
- </example>
+ if (iface) {
- <example>
- <title>Fetching the virInterfacePtr for a given interface MAC
Address</title>
- <programlisting>
-<![CDATA[virInterfacePtr iface;
-const char *mac = "00:01:02:03:04:05";
+ /* use the virInterfacePtr ... */
-iface = virInterfaceLookupByMACString(mac);
+ virInterfaceFree(iface);
+ } else {
+ printf("Interface '%s' not found.\n", name);
+ }]]>
+ </programlisting>
+ </example>
-if (iface) {
+ <example>
+ <title>Fetching the virInterfacePtr for a given interface MAC
Address</title>
+ <programlisting>
+ <![CDATA[virInterfacePtr iface;
+ const char *mac = "00:01:02:03:04:05";
- /* use the virInterfacePtr ... */
+ iface = virInterfaceLookupByMACString(mac);
- virInterfaceFree(iface);
-} else {
- printf("No interface found with MAC address '%s'.\n", mac);
-}]]>
- </programlisting>
- </example>
+ if (iface) {
- <para>
- Note that, as shown in the examples, after you are finished using the
- <literal>virInterfacePtr</literal>, you must call
<literal>virInterfaceFree</literal> to free up its
- resources, even if you undefined or destroyed the interface in the
- meantime. Also note that performing a lookup for a MAC address
- that has multiple matches will result in a NULL return and a
- VIR_ERR_MULTIPLE_INTERFACES error being raised. This limitation will
- be addressed in the near future with a new API function.
- </para>
- </section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-Detail">
- <title>Retrieving Detailed Interface Information</title>
+ /* use the virInterfacePtr ... */
- <para>
- You may also find yourself with a <literal>virInterfacePtr</literal>,
and need the name
- or MAC address of the interface, or want to examine the full interface
- configuration. The <literal>virInterfaceGetName</literal>,
<literal>virInterfaceGetMACString</literal>, and
- <literal>virInterfaceGetXMLDesc</literal> functions provide this
capability.
- </para>
+ virInterfaceFree(iface);
+ } else {
+ printf("No interface found with MAC address '%s'.\n", mac);
+ }]]>
+ </programlisting>
+ </example>
- <example>
- <title>Fetching the name and mac address from an interface
object</title>
- <programlisting>
-<![CDATA[const char *name;
-const char *mac;
+ <para>
+ Note that, as shown in the examples, after you are finished using the
+ <literal>virInterfacePtr</literal>, you must call
<literal>virInterfaceFree</literal> to free up its
+ resources, even if you undefined or destroyed the interface in the
+ meantime. Also note that performing a lookup for a MAC address
+ that has multiple matches will result in a NULL return and a
+ VIR_ERR_MULTIPLE_INTERFACES error being raised. This limitation will
+ be addressed in the near future with a new API function.
+ </para>
+ </section>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Information-Detail">
+ <title>Retrieving Detailed Interface Information</title>
-name = virInterfaceGetName(iface);
-mac = virInterfaceGetMACString(iface);
+ <para>
+ You may also find yourself with a
<literal>virInterfacePtr</literal>, and need the name
+ or MAC address of the interface, or want to examine the full interface
+ configuration. The <literal>virInterfaceGetName</literal>,
<literal>virInterfaceGetMACString</literal>, and
+ <literal>virInterfaceGetXMLDesc</literal> functions provide this
capability.
+ </para>
-printf("Interface %s has MAC address %s", name, mac);]]>
- </programlisting>
- </example>
+ <example>
+ <title>Fetching the name and mac address from an interface
object</title>
+ <programlisting>
+ <![CDATA[const char *name;
+ const char *mac;
- <para>
- Note that the strings returned by
<literal>virInterfaceGetName</literal> and
- <literal>virInterfaceGetMACString</literal> do not need to be freed
by the application;
- their lifetime will be the same as the interface object.
- </para>
- <para>
- The string returned by <literal>virInterfaceGetXMLDesc</literal>, on
the other hand, is
- created especially for the caller, and the caller must free it when
- finished. <literal>virInterfacegetXMLDesc</literal> also has a flags
argument, intended
- for future expansion. For forward compatibility, you should always set
- it to 0. The returned string is UTF-8 encoded. The same string may
- later be given to <literal>virInterfaceDefineXML</literal> to
recreate the interface
- configuration.
- </para>
+ name = virInterfaceGetName(iface);
+ mac = virInterfaceGetMACString(iface);
- <example>
- <title>Fetching the XML configuration string from an interface
object</title>
- <programlisting>
-<![CDATA[const char *xml;
+ printf("Interface %s has MAC address %s", name, mac);]]>
+ </programlisting>
+ </example>
-name = virInterfaceGetXMLDesc(iface, 0);
-printf("Interface configuration:\n%s\n", xml);
-free(xml);]]>
- </programlisting>
- </example>
- </section>
- </section>
+ <para>
+ Note that the strings returned by
<literal>virInterfaceGetName</literal> and
+ <literal>virInterfaceGetMACString</literal> do not need to be freed
by the application;
+ their lifetime will be the same as the interface object.
+ </para>
+ <para>
+ The string returned by <literal>virInterfaceGetXMLDesc</literal>,
on the other hand, is
+ created especially for the caller, and the caller must free it when
+ finished. <literal>virInterfacegetXMLDesc</literal> also has a
flags argument, intended
+ for future expansion. For forward compatibility, you should always set
+ it to 0. The returned string is UTF-8 encoded. The same string may
+ later be given to <literal>virInterfaceDefineXML</literal> to
recreate the interface
+ configuration.
+ </para>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Configs">
- <title>Managing interface configuration files</title>
- <para>
- In libvirt, "defining" an interface means creating or changing the
- configuration, and "undefining" means deleting that configuration from
- the system. Newcomers may sometimes confuse these two operations with
- Create/Delete (which actually are used to activate and deactivate an
- existing interface - see <xref
linkend="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle"
/>).
- </para>
+ <example>
+ <title>Fetching the XML configuration string from an interface
object</title>
+ <programlisting>
+ <![CDATA[const char *xml;
+
+ name = virInterfaceGetXMLDesc(iface, 0);
+ printf("Interface configuration:\n%s\n", xml);
+ free(xml);]]>
+ </programlisting>
+ </example>
+ </section>
+ </section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Configs-Define">
- <title>Defining an interface configuration</title>
- <para>
- The <literal>virInterfaceDefineXML</literal> function is used for
both adding new interface configurations
- and modifying existing configurations. It either adds a new interface
- (with all information, including the interface name, given in the XML
- data) or modifies the configuration of an existing interface. The
- newly defined interface will be inactive until separate action is
- taken to make the new configuration take effect (for example,
- rebooting the host, or calling <literal>virInterfaceCreate</literal>,
described in
- <xref
linkend="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle"
/>)
- </para>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Configs">
+ <title>Managing interface configuration files</title>
<para>
- If the interface is successfully added/modified in the host's
- configuration, <literal>virInterfaceDefineXML</literal> returns a
<literal>virInterfacePtr</literal>. This
- can be used as a handle to perform further actions on the new interface,
- for example making it active with
<literal>virInterfaceCreate</literal>.
- </para>
- <para>
- When you are finished using the returned
<literal>virInterfacePtr</literal>, you must
- free it with <literal>virInterfaceFree</literal>. This does not
remove the interface
- itself, just the internal object used by libvirt.
+ In libvirt, "defining" an interface means creating or changing the
+ configuration, and "undefining" means deleting that configuration from
+ the system. Newcomers may sometimes confuse these two operations with
+ Create/Delete (which actually are used to activate and deactivate an
+ existing interface - see <xref
linkend="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle"
/>).
</para>
- <example id="Example-Defining_a_new_interface">
- <title>Defining a new interface</title>
- <programlisting>
-<![CDATA[/* xml is a char* containing the description, per section 7.2 */
-virInterfacePtr iface;
-
-iface = virInterfaceDefineXML(xml, 0);
-if (!iface) {
- fprintf(stderr, "Failed to define interface.\n");
- /* other error handling */
- goto cleanup;
-}
-if (virInterfaceCreate(iface) != 0) {
- fprintf(stderr, "Failed to create (activate) interface\n");
- /* other error handling */
- goto cleanup;
-}
-virInterfaceFree(iface);
-
-cleanup:
- /* ... */
-]]>
- </programlisting>
- </example>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Configs-Define">
+ <title>Defining an interface configuration</title>
+ <para>
+ The <literal>virInterfaceDefineXML</literal> function is used for
both adding new interface configurations
+ and modifying existing configurations. It either adds a new interface
+ (with all information, including the interface name, given in the XML
+ data) or modifies the configuration of an existing interface. The
+ newly defined interface will be inactive until separate action is
+ taken to make the new configuration take effect (for example,
+ rebooting the host, or calling
<literal>virInterfaceCreate</literal>, described in
+ <xref
linkend="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle"
/>)
+ </para>
+ <para>
+ If the interface is successfully added/modified in the host's
+ configuration, <literal>virInterfaceDefineXML</literal> returns a
<literal>virInterfacePtr</literal>. This
+ can be used as a handle to perform further actions on the new interface,
+ for example making it active with
<literal>virInterfaceCreate</literal>.
+ </para>
+ <para>
+ When you are finished using the returned
<literal>virInterfacePtr</literal>, you must
+ free it with <literal>virInterfaceFree</literal>. This does not
remove the interface
+ itself, just the internal object used by libvirt.
+ </para>
+
+ <example id="Example-Defining_a_new_interface">
+ <title>Defining a new interface</title>
+ <programlisting>
+ <![CDATA[/* xml is a char* containing the description, per section 7.2 */
+ virInterfacePtr iface;
+
+ iface = virInterfaceDefineXML(xml, 0);
+ if (!iface) {
+ fprintf(stderr, "Failed to define interface.\n");
+ /* other error handling */
+ goto cleanup;
+ }
+ if (virInterfaceCreate(iface) != 0) {
+ fprintf(stderr, "Failed to create (activate) interface\n");
+ /* other error handling */
+ goto cleanup;
+ }
+ virInterfaceFree(iface);
+
+ cleanup:
+ /* ... */
+ ]]>
+ </programlisting>
+ </example>
+ </section>
+
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Configs-Undefine">
+ <title>Undefining an interface configuration</title>
+ <para>
+ The <literal>virInterfaceUndefine</literal> function completely and
permanently removes the
+ configuration for the given interface from the host's configuration
+ files. If you want to recreate this configuration again in the
+ future, you should call <literal>virInterfacegetXMLDesc</literal>
and save the string
+ prior to the undefine.
+ </para>
+ <para>
+ <literal>virInterfaceUndefine</literal> does not free the
<literal>virInterfacePtr</literal> itself, it only
+ removes the configuration from the host. You must still free the
+ <literal>virInterfacePtr</literal> with
<literal>virInterfaceFree</literal>.
+ </para>
+ <example>
+ <title>Undefining br0 interface after saving its XML data</title>
+ <programlisting>
+ <![CDATA[virInterfacePtr iface;
+ char *xml = NULL;;
+
+ iface = virInterfaceLookupByName("br0");
+ if (!iface) {
+ printf ("Interface br0 not found.\n");
+ } else {
+ xml = virInterfaceGetXMLDesc(iface, 0);
+ virInterfaceUndefine(iface);
+ virInterfaceFree(iface);
+ }
+ /* you must also free the buffer at xml when you're finished with it */]]>
+ --------------
+ </programlisting>
+ </example>
+ </section>
</section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Configs-Undefine">
- <title>Undefining an interface configuration</title>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle">
+ <title>Interface lifecycle management</title>
<para>
- The <literal>virInterfaceUndefine</literal> function completely and
permanently removes the
- configuration for the given interface from the host's configuration
- files. If you want to recreate this configuration again in the
- future, you should call <literal>virInterfacegetXMLDesc</literal> and
save the string
- prior to the undefine.
+ In libvirt parlance, "creating" an interface means making it active,
+ or "bringing it up", and "deleting" an interface means making
it
+ inactive, or "bringing it down". On hosts using the
<package>netcf</package> backend for
+ interface configuration, such as Fedora and Red Hat Enterprise Linux, this is the
same as calling
+ the system shell scripts <command>ifup</command> and
<command>ifdown</command> for the interface.
</para>
- <para>
- <literal>virInterfaceUndefine</literal> does not free the
<literal>virInterfacePtr</literal> itself, it only
- removes the configuration from the host. You must still free the
- <literal>virInterfacePtr</literal> with
<literal>virInterfaceFree</literal>.
- </para>
- <example>
- <title>Undefining br0 interface after saving its XML data</title>
- <programlisting>
-<![CDATA[virInterfacePtr iface;
-char *xml = NULL;;
-
-iface = virInterfaceLookupByName("br0");
-if (!iface) {
- printf ("Interface br0 not found.\n");
-} else {
- xml = virInterfaceGetXMLDesc(iface, 0);
- virInterfaceUndefine(iface);
- virInterfaceFree(iface);
-}
-/* you must also free the buffer at xml when you're finished with it */]]>
---------------
- </programlisting>
- </example>
- </section>
- </section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle">
- <title>Interface lifecycle management</title>
- <para>
- In libvirt parlance, "creating" an interface means making it active,
- or "bringing it up", and "deleting" an interface means making
it
- inactive, or "bringing it down". On hosts using the
<package>netcf</package> backend for
- interface configuration, such as Fedora and Red Hat Enterprise Linux, this is the
same as calling
- the system shell scripts <command>ifup</command> and
<command>ifdown</command> for the interface.
- </para>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle-Activate">
+ <title>Activating an interface</title>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle-Activate">
- <title>Activating an interface</title>
+ <para>
+ <literal>virInterfaceCreate</literal> makes the given inactive
interface active
+ ("up"). On success, it returns 0. If there is any problem making the
+ interface active, -1 is returned. <xref
linkend="Example-Defining_a_new_interface" /> shows typical usage of this
function.
+ </para>
+ </section>
- <para>
- <literal>virInterfaceCreate</literal> makes the given inactive
interface active
- ("up"). On success, it returns 0. If there is any problem making the
- interface active, -1 is returned. <xref
linkend="Example-Defining_a_new_interface" /> shows typical usage of this
function.
- </para>
- </section>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle-Deactivate">
+ <title>Deactivating an interface</title>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-Lifecycle-Deactivate">
- <title>Deactivating an interface</title>
+ <para>
+ <literal>virInterfaceDestroy</literal> makes the given interface
inactive ("down"). On
+ success, it returns 0. If there is any problem making the interface
+ active, -1 is returned.
+ </para>
+ <example>
+ <title>Temporarily bring down eth2, then bring it back up</title>
+ <programlisting>
+ <![CDATA[virInterfacePtr iface;
+
+ iface = virInterfaceLookupByName("eth2");
+ if (!iface) {
+ printf("Interface eth2 not found.\n");
+ } else {
+ if (virInterfaceDestroy(iface) != 0) {
+ fprintf(stderr, "failed to destroy (deactivate) interface eth2.\n");
+ } else
+ /* do whatever you wanted to do with interface down */
+ if (virInterfaceCreate(iface) != 0) {
+ fprintf(stderr, "failed to create (activate) interface eth2.\n");
+ }
+ }
+ free(iface);
+ }]]>
+ </programlisting>
+ </example>
+ </section>
+ </section>
+ <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-MemManager">
+ <title>Interface object memory management</title>
+ <para>
+ Any time an application calls a function that returns a
+ <literal>virInterfacePtr</literal>, it is implied that a reference
counter has been
+ incremented for that particular interface object. To decrement the
+ reference counter (eventually resulting in the interface object's
+ resources being freed), call <literal>virInterfaceFree</literal>.
This reference counting
+ assures that the interface object will not be freed while an
+ application is still using it.
+ </para>
<para>
- <literal>virInterfaceDestroy</literal> makes the given interface
inactive ("down"). On
- success, it returns 0. If there is any problem making the interface
- active, -1 is returned.
+ For cases where an application makes a copy of a
<literal>virInterfacePtr</literal> and
+ stores it away somewhere which may require a lifetime longer than that
+ of the original <literal>virInterfacePtr</literal>,
<literal>virInterfaceRef</literal> should be called to
+ manually increment the reference count.
<literal>virInterfaceFree</literal> should then
+ be called an extra time, when that copy of the
<literal>virInterfacePtr</literal> is no
+ longer being used.
</para>
<example>
- <title>Temporarily bring down eth2, then bring it back up</title>
+ <title>Reference counting an interface object</title>
<programlisting>
-<![CDATA[virInterfacePtr iface;
-
-iface = virInterfaceLookupByName("eth2");
-if (!iface) {
- printf("Interface eth2 not found.\n");
-} else {
- if (virInterfaceDestroy(iface) != 0) {
- fprintf(stderr, "failed to destroy (deactivate) interface eth2.\n");
- } else
- /* do whatever you wanted to do with interface down */
- if (virInterfaceCreate(iface) != 0) {
- fprintf(stderr, "failed to create (activate) interface eth2.\n");
- }
- }
- free(iface);
-}]]>
- </programlisting>
- </example>
- </section>
- </section>
- <section
id="libvirt_application_development_guide_using_python-Network_Interfaces-MemManager">
- <title>Interface object memory management</title>
- <para>
- Any time an application calls a function that returns a
- <literal>virInterfacePtr</literal>, it is implied that a reference
counter has been
- incremented for that particular interface object. To decrement the
- reference counter (eventually resulting in the interface object's
- resources being freed), call <literal>virInterfaceFree</literal>. This
reference counting
- assures that the interface object will not be freed while an
- application is still using it.
- </para>
- <para>
- For cases where an application makes a copy of a
<literal>virInterfacePtr</literal> and
- stores it away somewhere which may require a lifetime longer than that
- of the original <literal>virInterfacePtr</literal>,
<literal>virInterfaceRef</literal> should be called to
- manually increment the reference count.
<literal>virInterfaceFree</literal> should then
- be called an extra time, when that copy of the
<literal>virInterfacePtr</literal> is no
- longer being used.
- </para>
+ <![CDATA[virInterfacePtr iface;
- <example>
- <title>Reference counting an interface object</title>
- <programlisting>
-<![CDATA[virInterfacePtr iface;
+ iface = virInterfaceLookupByName("eth0");
-iface = virInterfaceLookupByName("eth0");
+ mydata.iface = iface;
+ virInterfaceRef(mydata.iface);
+ /* now we're done with iface */
+ virInterfaceFree(iface);
-mydata.iface = iface;
-virInterfaceRef(mydata.iface);
-/* now we're done with iface */
-virInterfaceFree(iface);
+ ...
-...
-
-/* now we're done with mydata.iface */
-virInterfaceFree(mydata.iface);]]>
- </programlisting>
- </example>
- </section>
+ /* now we're done with mydata.iface */
+ virInterfaceFree(mydata.iface);]]>
+ </programlisting>
+ </example>
+ </section>
</chapter>
diff --git a/en-US/extras/NetworkInterface-Example-1.xml
b/en-US/extras/NetworkInterface-Example-1.xml
new file mode 100644
index 0000000..9d56e15
--- /dev/null
+++ b/en-US/extras/NetworkInterface-Example-1.xml
@@ -0,0 +1,7 @@
+<interface type='ethernet' name='eth0'>
+ <start mode='onboot'/>
+ <mac address='aa:bb:cc:dd:ee:ff'/>
+ <protocol family='ipv4'>
+ <dhcp/>
+ </protocol>
+</interface>
diff --git a/en-US/extras/NetworkInterface-Example-2.xml
b/en-US/extras/NetworkInterface-Example-2.xml
new file mode 100644
index 0000000..6719b03
--- /dev/null
+++ b/en-US/extras/NetworkInterface-Example-2.xml
@@ -0,0 +1,8 @@
+<interface type='ethernet' name='eth0'>
+ <start mode='onboot'/>
+ <mac address='aa:bb:cc:dd:ee:ff'/>
+ <protocol family='ipv4'>
+ <ip address="192.168.0.5" prefix="24"/>
+ <route gateway="192.168.0.1"/>
+ </protocol>
+</interface>
diff --git a/en-US/extras/NetworkInterface-Example-3.xml
b/en-US/extras/NetworkInterface-Example-3.xml
new file mode 100644
index 0000000..bf084d4
--- /dev/null
+++ b/en-US/extras/NetworkInterface-Example-3.xml
@@ -0,0 +1,13 @@
+<interface type="bridge" name="br0">
+ <start mode="onboot"/>
+ <mtu size="1500"/>
+ <protocol family="ipv4">
+ <dhcp/>
+ </protocol>
+ <bridge stp="off" delay="0.01">
+ <interface type="ethernet" name="eth0">
+ <mac address="ab:bb:cc:dd:ee:ff"/>
+ </interface>
+ <interface type="ethernet" name="eth1"/>
+ </bridge>
+</interface>
diff --git a/en-US/extras/NetworkInterface-Example-4.xml
b/en-US/extras/NetworkInterface-Example-4.xml
new file mode 100644
index 0000000..4ff73d6
--- /dev/null
+++ b/en-US/extras/NetworkInterface-Example-4.xml
@@ -0,0 +1,9 @@
+<interface type="vlan" name="eth0.42">
+ <start mode="onboot"/>
+ <protocol family="ipv4">
+ <dhcp peerdns="no"/>
+ </protocol>
+ <vlan tag="42">
+ <interface name="eth0"/>
+ </vlan>
+</interface>
3232
days inactive
3232
days old
docs-commits@lists.fedoraproject.org
0 comments
1 participants
participants (1)
-
David Ashley