Sys::Virt::Network(3pm)

1Sys::Virt::Network(3pm)User Contributed Perl DocumentatioSnys::Virt::Network(3pm)
2
3
4

NAME

6       Sys::Virt::Network - Represent & manage a libvirt virtual network
7

DESCRIPTION

9       The "Sys::Virt::Network" module represents a virtual network managed by
10       the virtual machine monitor.
11

METHODS

13       my $uuid = $net->get_uuid()
14           Returns a 16 byte long string containing the raw globally unique
15           identifier (UUID) for the network.
16
17       my $uuid = $net->get_uuid_string()
18           Returns a printable string representation of the raw UUID, in the
19           format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'.
20
21       my $name = $net->get_name()
22           Returns a string with a locally unique name of the network
23
24       $net->is_active()
25           Returns a true value if the network is currently running
26
27       $net->is_persistent()
28           Returns a true value if the network has a persistent configuration
29           file defined
30
31       my $xml = $net->get_xml_description()
32           Returns an XML document containing a complete description of the
33           network's configuration
34
35       $net->create()
36           Start a network whose configuration was previously defined using
37           the "define_network" method in Sys::Virt.
38
39       $net->undefine()
40           Remove the configuration associated with a network previously
41           defined with the "define_network" method in Sys::Virt. If the
42           network is running, you probably want to use the "shutdown" or
43           "destroy" methods instead.
44
45       $net->destroy()
46           Immediately terminate the machine, and remove it from the virtual
47           machine monitor. The $net handle is invalid after this call
48           completes and should not be used again.
49
50       $net->update($command, $section, $parentIndex, $xml, $flags=0)
51           Update the network configuration with $xml. The $section parameter,
52           which must be one of the XML SECTION CONSTANTS listed later,
53           indicates what schema is used in $xml. The $command parameter
54           determines what action is taken. Finally, the $flags parameter can
55           be use to control which config is affected.
56
57       $net->get_bridge_name()
58           Return the name of the bridge device associated with the virtual
59           network
60
61       $flag = $net->get_autostart();
62           Return a true value if the virtual network is configured to
63           automatically start upon boot. Return false, otherwise
64
65       $net->set_autostart($flag)
66           Set the state of the autostart flag, which determines whether the
67           virtual network will automatically start upon boot of the host OS.
68
69       @leases = $net->get_dhcp_leases($mac=undef, $flags=0)
70           Get a list of all active DHCP leases. If $mac is undefined than
71           leases for all VMs are returned, otherwise only leases for the
72           matching MAC address are returned. The $flags parameter is
73           currently unused and defaults to zero.
74
75           The elements in the returned array are hash references with the
76           following fields
77
78           "iface"
79               Network interface name
80
81           "expirytime"
82               Seconds since the epoch until the lease expires
83
84           "type"
85               One of the Sys::Virt IP address type constants
86
87           "mac"
88               The MAC address of the lease
89
90           "iaid"
91               The IAID of the client
92
93           "ipaddr"
94               The IP address of the lease
95
96           "prefix"
97               The IP address prefix
98
99           "hostname"
100               The optional hostname associated with the lease
101
102           "clientid"
103               The client ID or DUID
104
105       @port = $net->list_all_ports($flags=0)
106           List all ports associated with the network. The return array
107           elements are instances of the "Sys::Virt::NetworkPort" class.
108
109       $port = $net->create_port($xml, $flags=0)
110           Create a new network port from the given $xml description. The
111           $flags parameter can optionally taken one or more of the network
112           port creation constants. The returned $port object is an instance
113           of the "Sys::Virt::NetworkPort" class.
114
115       $port = $net->get_port_by_uuid($uuid);
116           Lookup a network port from a raw or printable UUID.  The returned
117           $port object is an instance of the "Sys::Virt::NetworkPort" class.
118
119       my $str = $net->get_metadata($type, $uri, $flags =0)
120           Returns the metadata element of type $type associated with the
121           network. If $type is "Sys::Virt::Network::METADATA_ELEMENT" then
122           the $uri parameter specifies the XML namespace to retrieve,
123           otherwise $uri should be "undef". The optional $flags parameter
124           takes one of the XML UPDATE FLAGS values, and defaults to zero.
125
126       $net->set_metadata($type, $val, $key, $uri, $flags=0)
127           Sets the metadata element of type $type to hold the value $val. If
128           $type is  "Sys::Virt::Network::METADATA_ELEMENT" then the $key and
129           $uri elements specify an XML namespace to use, otherwise they
130           should both be "undef". The optional $flags parameter takes one of
131           the XML UPDATE FLAGS values, and defaults to zero.
132

CONSTANTS

134       This section documents constants that are used with various APIs
135       described above
136
137   NETWORK CREATION CONSTANTS
138       When creating networks zero or more of the following constants may be
139       used
140
141       Sys::Virt::Network::CREATE_VALIDATE
142           Validate the XML document against the XML schema
143
144   LIST FILTERING
145       The following constants are used to filter object lists
146
147       Sys::Virt::Network::LIST_ACTIVE
148           Include networks which are active
149
150       Sys::Virt::Network::LIST_INACTIVE
151           Include networks which are not active
152
153       Sys::Virt::Network::LIST_AUTOSTART
154           Include networks which are set to autostart
155
156       Sys::Virt::Network::LIST_NO_AUTOSTART
157           Include networks which are not set to autostart
158
159       Sys::Virt::Network::LIST_PERSISTENT
160           Include networks which are persistent
161
162       Sys::Virt::Network::LIST_TRANSIENT
163           Include networks which are transient
164
165   NETWORK DEFINE
166       The following constants can be used to control the behaviour of network
167       define operations
168
169       Sys::Virt::Network::DEFINE_VALIDATE
170           Validate the XML document against the XML schema
171
172   XML CONSTANTS
173       The following constants are used when querying XML
174
175       Sys::Virt::Network::XML_INACTIVE
176           Request the inactive XML, instead of the current possibly live
177           config.
178

XML SECTION CONSTANTS

180       The following constants are used to refer to sections of the XML
181       document
182
183       Sys::Virt::Network::SECTION_BRIDGE
184           The bridge device element
185
186       Sys::Virt::Network::SECTION_DNS_HOST
187           The DNS host record section
188
189       Sys::Virt::Network::SECTION_DNS_SRV
190           The DNS SRV record section
191
192       Sys::Virt::Network::SECTION_DNS_TXT
193           The DNS TXT record section
194
195       Sys::Virt::Network::SECTION_DOMAIN
196           The domain name section
197
198       Sys::Virt::Network::SECTION_FORWARD
199           The forward device section
200
201       Sys::Virt::Network::SECTION_FORWARD_INTERFACE
202           The forward interface section
203
204       Sys::Virt::Network::SECTION_FORWARD_PF
205           The forward physical function section
206
207       Sys::Virt::Network::SECTION_IP
208           The IP address section
209
210       Sys::Virt::Network::SECTION_IP_DHCP_HOST
211           The IP address DHCP host section
212
213       Sys::Virt::Network::SECTION_IP_DHCP_RANGE
214           The IP address DHCP range section
215
216       Sys::Virt::Network::SECTION_PORTGROUP
217           The port group section
218
219       Sys::Virt::Network::SECTION_NONE
220           The top level domain element
221
222   XML UPDATE FLAGS
223       Sys::Virt::Network::UPDATE_AFFECT_CURRENT
224           Affect whatever the current object state is
225
226       Sys::Virt::Network::UPDATE_AFFECT_CONFIG
227           Always update the config file
228
229       Sys::Virt::Network::UPDATE_AFFECT_LIVE
230           Always update the live config
231
232   XML UPDATE COMMANDS
233       Sys::Virt::Network::UPDATE_COMMAND_NONE
234           No update
235
236       Sys::Virt::Network::UPDATE_COMMAND_DELETE
237           Remove the matching entry
238
239       Sys::Virt::Network::UPDATE_COMMAND_MODIFY
240           Modify the matching entry
241
242       Sys::Virt::Network::UPDATE_COMMAND_ADD_FIRST
243           Insert the matching entry at the start
244
245       Sys::Virt::Network::UPDATE_COMMAND_ADD_LAST
246           Insert the matching entry at the end
247
248   EVENT ID CONSTANTS
249       Sys::Virt::Network::EVENT_ID_LIFECYCLE
250           Network lifecycle events
251
252   LIFECYCLE CHANGE EVENTS
253       The following constants allow network lifecycle change events to be
254       interpreted. The events contain both a state change, and a reason
255       though the reason is currently unused.
256
257       Sys::Virt::Network::EVENT_DEFINED
258           Indicates that a persistent configuration has been defined for the
259           network.
260
261       Sys::Virt::Network::EVENT_STARTED
262           The network has started running
263
264       Sys::Virt::Network::EVENT_STOPPED
265           The network has stopped running
266
267       Sys::Virt::Network::EVENT_UNDEFINED
268           The persistent configuration has gone away
269
270   METADATA TYPE CONSTANTS
271       The following constants control the type of metadata being accessed
272
273       Sys::Virt::Network::METADATA_TITLE
274           The short human friendly title of the network
275
276       Sys::Virt::Network::METADATA_DESCRIPTION
277           The long free text description of the network
278
279       Sys::Virt::Network::METADATA_ELEMENT
280           The structured metadata elements for the network
281

AUTHORS

283       Daniel P. Berrange <berrange@redhat.com>
284

COPYRIGHT

286       Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
287

LICENSE

289       This program is free software; you can redistribute it and/or modify it
290       under the terms of either the GNU General Public License as published
291       by the Free Software Foundation (either version 2 of the License, or at
292       your option any later version), or, the Artistic License, as specified
293       in the Perl README file.
294