--- name: "Sys::Virt::Network" section: "3pm" platform: "linux" package: "perl-sys-virt" version: "12.7.0-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Sys::Virt::Network" --- # Sys::Virt::Network(3pm) Represent & manage a libvirt virtual network ## NAME Sys::Virt::Network - Represent & manage a libvirt virtual network ## DESCRIPTION The `"Sys::Virt::Network"` module represents a virtual network managed by the virtual machine monitor. ## METHODS - my $uuid = $net-\>**get\_uuid()** Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the network. - my $uuid = $net-\>**get\_uuid\_string()** Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. - my $name = $net-\>**get\_name()** Returns a string with a locally unique name of the network - $net-\>**is\_active()** Returns a true value if the network is currently running - $net-\>**is\_persistent()** Returns a true value if the network has a persistent configuration file defined - my $xml = $net-\>**get\_xml\_description()** Returns an XML document containing a complete description of the network's configuration - $net-\>**create()** Start a network whose configuration was previously defined using the `"define_network"` method in Sys::Virt. - $net-\>**undefine()** Remove the configuration associated with a network previously defined with the `"define_network"` method in Sys::Virt. If the network is running, you probably want to use the `"shutdown"` or `"destroy"` methods instead. - $net-\>**destroy()** Immediately terminate the machine, and remove it from the virtual machine monitor. The `$net` handle is invalid after this call completes and should not be used again. - $net-\>update($command, $section, $parentIndex, $xml, $flags=0) Update the network configuration with `$xml`. The `$section` parameter, which must be one of the XML SECTION CONSTANTS listed later, indicates what schema is used in `$xml`. The `$command` parameter determines what action is taken. Finally, the `$flags` parameter can be use to control which config is affected. - $net-\>**get\_bridge\_name()** Return the name of the bridge device associated with the virtual network - $flag = $net-\>**get\_autostart()**; Return a true value if the virtual network is configured to automatically start upon boot. Return false, otherwise - $net-\>set\_autostart($flag) Set the state of the autostart flag, which determines whether the virtual network will automatically start upon boot of the host OS. - @leases = $net-\>get\_dhcp\_leases($mac=undef, $flags=0) Get a list of all active DHCP leases. If `$mac` is undefined than leases for all VMs are returned, otherwise only leases for the matching MAC address are returned. The `$flags` parameter is currently unused and defaults to zero. The elements in the returned array are hash references with the following fields - "iface" Network interface name - "expirytime" Seconds since the epoch until the lease expires - "type" One of the Sys::Virt IP address type constants - "mac" The MAC address of the lease - "iaid" The IAID of the client - "ipaddr" The IP address of the lease - "prefix" The IP address prefix - "hostname" The optional hostname associated with the lease - "clientid" The client ID or DUID - @port = $net-\>list\_all\_ports($flags=0) List all ports associated with the network. The return array elements are instances of the `"Sys::Virt::NetworkPort"` class. - $port = $net-\>create\_port($xml, $flags=0) Create a new network port from the given `$xml` description. The `$flags` parameter can optionally taken one or more of the network port creation constants. The returned `$port` object is an instance of the `"Sys::Virt::NetworkPort"` class. - $port = $net-\>get\_port\_by\_uuid($uuid); Lookup a network port from a raw or printable UUID. The returned `$port` object is an instance of the `"Sys::Virt::NetworkPort"` class. - my $str = $net-\>get\_metadata($type, $uri, $flags =0) Returns the metadata element of type `$type` associated with the network. If `$type` is `"Sys::Virt::Network::METADATA_ELEMENT"` then the `$uri` parameter specifies the XML namespace to retrieve, otherwise `$uri` should be `"undef"`. The optional `$flags` parameter takes one of the XML UPDATE FLAGS values, and defaults to zero. - $net-\>set\_metadata($type, $val, $key, $uri, $flags=0) Sets the metadata element of type `$type` to hold the value `$val`. If `$type` is `"Sys::Virt::Network::METADATA_ELEMENT"` then the `$key` and `$uri` elements specify an XML namespace to use, otherwise they should both be `"undef"`. The optional `$flags` parameter takes one of the XML UPDATE FLAGS values, and defaults to zero. ## CONSTANTS This section documents constants that are used with various APIs described above ### NETWORK CREATION CONSTANTS When creating networks zero or more of the following constants may be used - Sys::Virt::Network::CREATE\_VALIDATE Validate the XML document against the XML schema ### LIST FILTERING The following constants are used to filter object lists - Sys::Virt::Network::LIST\_ACTIVE Include networks which are active - Sys::Virt::Network::LIST\_INACTIVE Include networks which are not active - Sys::Virt::Network::LIST\_AUTOSTART Include networks which are set to autostart - Sys::Virt::Network::LIST\_NO\_AUTOSTART Include networks which are not set to autostart - Sys::Virt::Network::LIST\_PERSISTENT Include networks which are persistent - Sys::Virt::Network::LIST\_TRANSIENT Include networks which are transient ### NETWORK DEFINE The following constants can be used to control the behaviour of network define operations - Sys::Virt::Network::DEFINE\_VALIDATE Validate the XML document against the XML schema ### XML CONSTANTS The following constants are used when querying XML - Sys::Virt::Network::XML\_INACTIVE Request the inactive XML, instead of the current possibly live config. ## XML SECTION CONSTANTS The following constants are used to refer to sections of the XML document - Sys::Virt::Network::SECTION\_BRIDGE The bridge device element - Sys::Virt::Network::SECTION\_DNS\_HOST The DNS host record section - Sys::Virt::Network::SECTION\_DNS\_SRV The DNS SRV record section - Sys::Virt::Network::SECTION\_DNS\_TXT The DNS TXT record section - Sys::Virt::Network::SECTION\_DOMAIN The domain name section - Sys::Virt::Network::SECTION\_FORWARD The forward device section - Sys::Virt::Network::SECTION\_FORWARD\_INTERFACE The forward interface section - Sys::Virt::Network::SECTION\_FORWARD\_PF The forward physical function section - Sys::Virt::Network::SECTION\_IP The IP address section - Sys::Virt::Network::SECTION\_IP\_DHCP\_HOST The IP address DHCP host section - Sys::Virt::Network::SECTION\_IP\_DHCP\_RANGE The IP address DHCP range section - Sys::Virt::Network::SECTION\_PORTGROUP The port group section - Sys::Virt::Network::SECTION\_NONE The top level domain element ### XML UPDATE FLAGS - Sys::Virt::Network::UPDATE\_AFFECT\_CURRENT Affect whatever the current object state is - Sys::Virt::Network::UPDATE\_AFFECT\_CONFIG Always update the config file - Sys::Virt::Network::UPDATE\_AFFECT\_LIVE Always update the live config ### XML UPDATE COMMANDS - Sys::Virt::Network::UPDATE\_COMMAND\_NONE No update - Sys::Virt::Network::UPDATE\_COMMAND\_DELETE Remove the matching entry - Sys::Virt::Network::UPDATE\_COMMAND\_MODIFY Modify the matching entry - Sys::Virt::Network::UPDATE\_COMMAND\_ADD\_FIRST Insert the matching entry at the start - Sys::Virt::Network::UPDATE\_COMMAND\_ADD\_LAST Insert the matching entry at the end ### EVENT ID CONSTANTS - Sys::Virt::Network::EVENT\_ID\_LIFECYCLE Network lifecycle events - Sys::Virt::Network::EVENT\_ID\_METADATA\_CHANGE The network metadata has changed ### LIFECYCLE CHANGE EVENTS The following constants allow network lifecycle change events to be interpreted. The events contain both a state change, and a reason though the reason is currently unused. - Sys::Virt::Network::EVENT\_DEFINED Indicates that a persistent configuration has been defined for the network. - Sys::Virt::Network::EVENT\_STARTED The network has started running - Sys::Virt::Network::EVENT\_STOPPED The network has stopped running - Sys::Virt::Network::EVENT\_UNDEFINED The persistent configuration has gone away ### METADATA TYPE CONSTANTS The following constants control the type of metadata being accessed - Sys::Virt::Network::METADATA\_TITLE The short human friendly title of the network - Sys::Virt::Network::METADATA\_DESCRIPTION The long free text description of the network - Sys::Virt::Network::METADATA\_ELEMENT The structured metadata elements for the network ## AUTHORS Daniel P. Berrange \ ## COPYRIGHT Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange ## LICENSE This program is free software; you can redistribute it and/or modify it under the terms of either the GNU General Public License as published by the Free Software Foundation (either version 2 of the License, or at your option any later version), or, the Artistic License, as specified in the Perl README file. ## SEE ALSO Sys::Virt, Sys::Virt::Error, `"http://libvirt.org"`