[PATCH 00/14] docs: Convert some pages to rST and clean up (part 5)
This series corrects some mistakes from previous conversions (local anchor links, ordering of input files) and finishes the conversion of format* documents. Pavel Hrdina (1): docs: Convert 'formatnwfilter' page to rst Peter Krempa (13): docs: meson: Sort list of RST files to build docs: api: Fix local anchor links docs: drivers: Fix local anchor links docs: drvbhve: Fix local anchor links docs: drvesx: Fix local anchor links docs: drvnodedev: Fix local anchor links docs: drvsecret: Fix local anchor links docs: kbase/launch_security_sev: Fix local anchor links docs: kbase/tlscerts: Fix local anchor links docs: pci-hotplug: Fix local anchor links docs: Convert 'formatcaps' page to rst docs: Convert 'formatnetwork' page to rst docs: Convert 'formatnode' page to rst docs/api.rst | 5 +- docs/drivers.rst | 2 +- docs/drvbhyve.rst | 6 +- docs/drvesx.rst | 19 +- docs/drvnodedev.rst | 20 +- docs/firewall.rst | 2 +- docs/formatcaps.html.in | 222 --- docs/formatcaps.rst | 197 +++ docs/formatdomain.rst | 7 +- docs/formatnetwork.html.in | 1479 ----------------- docs/formatnetwork.rst | 1144 +++++++++++++ docs/formatnetworkport.rst | 2 +- docs/formatnode.html.in | 657 -------- docs/formatnode.rst | 556 +++++++ docs/formatnwfilter.html.in | 2471 ---------------------------- docs/formatnwfilter.rst | 1789 ++++++++++++++++++++ docs/formatsecret.rst | 16 +- docs/kbase/launch_security_sev.rst | 2 +- docs/kbase/tlscerts.rst | 7 +- docs/manpages/virsh.rst | 5 +- docs/meson.build | 12 +- docs/pci-hotplug.rst | 5 +- 22 files changed, 3742 insertions(+), 4883 deletions(-) delete mode 100644 docs/formatcaps.html.in create mode 100644 docs/formatcaps.rst delete mode 100644 docs/formatnetwork.html.in create mode 100644 docs/formatnetwork.rst delete mode 100644 docs/formatnode.html.in create mode 100644 docs/formatnode.rst delete mode 100644 docs/formatnwfilter.html.in create mode 100644 docs/formatnwfilter.rst -- 2.35.1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/meson.build b/docs/meson.build index a0e69f3119..a8e360c8a4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -72,13 +72,13 @@ docs_rst_files = [ 'formatbackup', 'formatcheckpoint', 'formatdomain', - 'formatnetworkport', 'formatdomaincaps', + 'formatnetworkport', 'formatsecret', 'formatsnapshot', 'formatstorage', - 'formatstorageencryption', 'formatstoragecaps', + 'formatstorageencryption', 'glib-adoption', 'goals', 'governance', -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/api.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 325b9b840c..08e5a0eed9 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -234,8 +234,9 @@ The libvirt client `applications <apps.html>`__ use a `URI <uri.html>`__ to obtain the ``virConnectPtr``. The ``virConnectPtr`` keeps track of the driver connection plus a variety of other connections (network, interface, storage, etc.). The ``virConnectPtr`` is then used as a -parameter to other virtualization `functions <#Functions>`__. Depending -upon the driver being used, calls will be routed through the remote +parameter to other virtualization functions +(see `Functions and Naming Conventions`_). +Depending upon the driver being used, calls will be routed through the remote driver to the libvirtd daemon. The daemon will reference the connection specific driver in order to retrieve the requested information and then pass back status and/or data through the connection back to the -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drivers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drivers.rst b/docs/drivers.rst index b72266e876..b6a426be6a 100644 --- a/docs/drivers.rst +++ b/docs/drivers.rst @@ -2,7 +2,7 @@ Internal drivers ================ -- `Hypervisor drivers <#hypervisor-drivers>`__ +- `Hypervisor drivers`_ - `Storage drivers <storage.html>`__ - `Node device driver <drvnodedev.html>`__ - `Secret driver <drvsecret.html>`__ -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvbhyve.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/drvbhyve.rst b/docs/drvbhyve.rst index 95ef4e9b49..214bc2e76e 100644 --- a/docs/drvbhyve.rst +++ b/docs/drvbhyve.rst @@ -192,7 +192,8 @@ This is an example to boot into Fedora 25 installation: </devices> </domain> -Please refer to the `UEFI <#uefi>`__ section for a more detailed explanation. +Please refer to the `Using UEFI bootrom, VNC, and USB tablet`_ section for a +more detailed explanation. Guest usage / management ------------------------ @@ -306,7 +307,8 @@ not have spaces or they will be tokenized incorrectly. Using UEFI bootrom, VNC, and USB tablet ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:since:`Since 3.2.0` , in addition to `grub-bhyve <#grubbhyve>`__, non-FreeBSD +:since:`Since 3.2.0` , in addition to +`Using grub2-bhyve or Alternative Bootloaders`_, non-FreeBSD guests could be also booted using an UEFI boot ROM, provided both guest OS and installed ``bhyve(1)`` version support UEFI. To use that, ``loader`` should be specified in the ``os`` section: -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvesx.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/drvesx.rst b/docs/drvesx.rst index a50c689e36..9ef6b74161 100644 --- a/docs/drvesx.rst +++ b/docs/drvesx.rst @@ -119,13 +119,12 @@ The driver understands the extra parameters shown below. | | | the server's SSL | | | | certificate. The default | | | | value is 0. See the | -| | | `Certificates for | -| | | HTTPS <#certificates>`__ | +| | | `Certificates for HTTPS`_ | | | | section for details. | +-----------------+-----------------------------+-----------------------------+ | ``auto_answer`` | ``0`` or ``1`` | If set to 1, the driver | | | | answers all | -| | | `questions <#questions>`__ | +| | | `Questions blocking tasks`_ | | | | with the default answer. If | | | | set to 0, questions are | | | | reported as errors. The | @@ -183,7 +182,7 @@ error like this one: Where are two ways to solve this problem: -- Use the ``no_verify=1`` `extra parameter <#extraparams>`__ to disable server +- Use the ``no_verify=1`` `Extra parameters`_ to disable server certificate verification. - Generate new SSL certificates signed by a CA known to your client computer and replace the original ones on your ESX server. See the section *Replace a @@ -193,13 +192,13 @@ Where are two ways to solve this problem: Connection problems ~~~~~~~~~~~~~~~~~~~ -There are also other causes for connection problems than the `HTTPS -certificate <#certificates>`__ related ones. +There are also other causes for connection problems than those related to +`Certificates for HTTPS`_ . - As stated before the ESX driver doesn't need the `remote transport mechanism <remote.html>`__ provided by the remote driver and libvirtd, nor does the ESX driver support it. Therefore, using an URI including a transport - in the scheme won't work. Only `URIs as described <#uriformat>`__ are + in the scheme won't work. Only URIs as described in `URI Format`_ are supported by the ESX driver. Here's a collection of possible error messages: :: @@ -257,8 +256,8 @@ answer a question, libvirt doesn't have an API for something like this. The VI API provides the ``AnswerVM()`` method to programmatically answer a questions. So the driver has two options how to handle such a situation: either answer the questions with the default answer or report the question as an error -and cancel the blocked task if possible. The `auto_answer <#uriformat>`__ query -parameter controls the answering behavior. +and cancel the blocked task if possible. The ``auto_answer`` query +parameter (see `URI Format`_) controls the answering behavior. Specialities in the domain XML config ------------------------------------- @@ -275,7 +274,7 @@ will complain if this restrictions are violated. - Number of virtual CPU has to be 1 or a multiple of 2. :since:`Since 4.10.0` any number of vCPUs is supported. - Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. :since:`Since - 0.7.6` arbitrary `MAC addresses <#macaddresses>`__ are supported. + 0.7.6` arbitrary `MAC addresses`_ are supported. Datastore references ~~~~~~~~~~~~~~~~~~~~ -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvnodedev.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/drvnodedev.rst b/docs/drvnodedev.rst index cddb36c73b..d333a9dca6 100644 --- a/docs/drvnodedev.rst +++ b/docs/drvnodedev.rst @@ -59,8 +59,7 @@ PCI host devices ``capability`` When used as top level element, the supported values for the ``type`` - attribute are ``pci`` and ``phys_function`` (see `SR-IOV - below <#SRIOVCap>`__). + attribute are ``pci`` and ``phys_function`` (see `SR-IOV capability`_ below). :: @@ -103,9 +102,10 @@ multiple devices called virtual functions (VFs) sharing their configuration with the underlying PF. Despite the SR-IOV specification, the amount of VFs that can be created on a PF varies among manufacturers. -Suppose the NIC `above <#PCI>`__ was also SR-IOV capable, it would also include -a nested ``<capability>`` element enumerating all virtual functions available on -the physical device (physical port) like in the example below. +Suppose the NIC above in `PCI host devices`_ was also SR-IOV capable, it would +also include a nested ``<capability>`` element enumerating all virtual +functions available on the physical device (physical port) like in the example +below. :: @@ -146,8 +146,8 @@ of the XML format for the ``mdev_types`` capability can be found `here <formatnode.html#MDEVTypesCap>`__. The following example shows how we might represent an NVIDIA GPU device that -supports mediated devices. See below for `more information about mediated -devices <#MDEV>`__. +supports mediated devices. See below for more info on +`Mediated devices (MDEVs)`_. :: @@ -281,7 +281,7 @@ covers the following features: Because mediated devices are instantiated from vendor specific templates, simply called 'types', information describing these types is contained within the -parent device's capabilities (see the example in `PCI host devices <#PCI>`__). +parent device's capabilities (see the example in `PCI host devices`_). To list all devices capable of creating mediated devices, the following command can be used. -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsecret.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/formatsecret.rst b/docs/formatsecret.rst index 15b2a221d7..bb2217041a 100644 --- a/docs/formatsecret.rst +++ b/docs/formatsecret.rst @@ -59,8 +59,8 @@ Define the secret and set the passphrase as follows: # virsh secret-define volume-secret.xml Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created -See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the -secret. +See `Setting secret values in virsh`_ on how to set the value of the secret +using ``virsh secret-set-value``. The volume type secret can be supplied either in volume XML during creation of a `storage volume <formatstorage.html#StorageVol>`__ in order to provide the @@ -82,8 +82,8 @@ to decrypt the volume, :since:`since 2.1.0` . An example follows: # virsh secret-define luks-secret.xml Secret f52a81b2-424e-490c-823d-6bd4235bc57 created -See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the -secret. +See `Setting secret values in virsh`_ on how to set the value of the secret +using ``virsh secret-set-value``. The volume type secret can be supplied in domain XML for a luks storage volume `encryption <formatstorageencryption.html>`__ as follows: @@ -128,8 +128,8 @@ secret value in order to define the chosen secret pass phrase. ----------------------------------------------------------- 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example -See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the -secret. +See `Setting secret values in virsh`_ on how to set the value of the secret +using ``virsh secret-set-value``. The ceph secret can then be used by UUID or by the usage name via the ``<auth>`` element in a domain's `<disk> <formatdomain.html#elementsDisks>`__ element as @@ -203,8 +203,8 @@ must match the password used in the iSCSI authentication configuration file. c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi -See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the -secret. +See `Setting secret values in virsh`_ on how to set the value of the secret +using ``virsh secret-set-value``. The iSCSI secret can then be used by UUID or by the usage name via the ``<auth>`` element in a domain's `<disk> <formatdomain.html#elementsDisks>`__ -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/kbase/launch_security_sev.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/kbase/launch_security_sev.rst b/docs/kbase/launch_security_sev.rst index edd819ad5a..06d1f2dad0 100644 --- a/docs/kbase/launch_security_sev.rst +++ b/docs/kbase/launch_security_sev.rst @@ -362,7 +362,7 @@ Checking SEV from within the guest ================================== After making the necessary adjustments discussed in -`Configuration <#Configuration>`__, the VM should now boot successfully +`VM Configuration`_, the VM should now boot successfully with SEV enabled. You can then verify that the guest has SEV enabled by running: -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/kbase/tlscerts.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/kbase/tlscerts.rst b/docs/kbase/tlscerts.rst index c86362974c..c6636770e6 100644 --- a/docs/kbase/tlscerts.rst +++ b/docs/kbase/tlscerts.rst @@ -58,7 +58,7 @@ If you are unsure how to create TLS certificates, skip to the next section. * - ``$HOME/.pki/libvirt/clientcert.pem`` - Installed on the client - Client's certificate signed by the CA - (`more info <#Remote_TLS_client_certificates>`__) + (see `Issuing client certificates`_) - Distinguished Name (DN) can be checked against an access control list (``tls_allowed_dn_list``). @@ -279,9 +279,8 @@ this on a company / organisation policy. For example: C=GB,ST=London,L=London,O=Libvirt Project,CN=name_of_client -The process is the same as for `setting up the server -certificate <#Remote_TLS_server_certificates>`__ so here we just briefly cover -the steps. +The process is the same as for `Issuing server certificates`_ so here we just +briefly cover the steps. #. Make a private key: -- 2.35.1
Original conversion didn't properly convert local links. Fix them by pointing to the section name. In certain cases this requires reformulation of the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/pci-hotplug.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/pci-hotplug.rst b/docs/pci-hotplug.rst index bc7fdbbd86..36798d16a7 100644 --- a/docs/pci-hotplug.rst +++ b/docs/pci-hotplug.rst @@ -137,9 +137,8 @@ aarch64 architecture mach-virt (virt) machine type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This machine type mostly behaves the same as the `q35 machine -type <#q35-machine-type>`__, so you can just refer to that section for -information. +This machine type mostly behaves the same as the `q35 machine type`_, +so you can just refer to that section for information. The only difference worth mentioning is that using legacy PCI for ``mach-virt`` guests is extremely uncommon, so you'll probably never need to add controllers -- 2.35.1
From: Pavel Hrdina <phrdina@redhat.com> Also adjust direct links from other pages. Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/firewall.rst | 2 +- docs/formatdomain.rst | 3 +- docs/formatnwfilter.html.in | 2471 ----------------------------------- docs/formatnwfilter.rst | 1789 +++++++++++++++++++++++++ docs/meson.build | 2 +- 5 files changed, 1793 insertions(+), 2474 deletions(-) delete mode 100644 docs/formatnwfilter.html.in create mode 100644 docs/formatnwfilter.rst diff --git a/docs/firewall.rst b/docs/firewall.rst index adda0ef1f4..eff9de5a89 100644 --- a/docs/firewall.rst +++ b/docs/firewall.rst @@ -250,7 +250,7 @@ source IP address ``!= $IP`` like this: I'm not going to go into details on all the other protocol matches you can do, because it'll take far too much space. You can read about the options -`here <formatnwfilter.html#nwfelemsRulesProto>`__. +`here <formatnwfilter.html#supported-protocols>`__. Out of the box in RHEL6/Fedora rawhide, libvirt ships with a set of default useful rules: diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 24fbfd8670..552b5364f8 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5845,7 +5845,8 @@ complete details. The ``filter`` attribute specifies the name of the nwfilter to use. Optional ``<parameter>`` elements may be specified for passing additional info to the nwfilter via the ``name`` and ``value`` attributes. See the -`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters. +`nwfilter <formatnwfilter.html#usage-of-variables-in-filters>`__ docs for info +on parameters. :anchor:`<a id="elementsInput"/>` diff --git a/docs/formatnwfilter.html.in b/docs/formatnwfilter.html.in deleted file mode 100644 index 04aeda06ec..0000000000 --- a/docs/formatnwfilter.html.in +++ /dev/null @@ -1,2471 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Network Filters</h1> - - <ul id="toc"> - </ul> - - <p> - This page provides an introduction to libvirt's network filters, - their goals, concepts and XML format. - </p> - - <h2><a id="goals">Goals and background</a></h2> - - <p> - The goal of the network filtering XML is to enable administrators - of a virtualized system to configure and enforce network traffic - filtering rules on virtual - machines and manage the parameters of network traffic that - virtual machines - are allowed to send or receive. - The network traffic filtering rules are - applied on the host when a virtual machine is started. Since the - filtering rules - cannot be circumvented from within - the virtual machine, it makes them mandatory from the point of - view of a virtual machine user. - <br/><br/> - The network filter subsystem allows each virtual machine's network - traffic filtering rules to be configured individually on a per - interface basis. The rules are - applied on the host when the virtual machine is started and can be modified - while the virtual machine is running. The latter can be achieved by - modifying the XML description of a network filter. - <br/><br/> - Multiple virtual machines can make use of the same generic network filter. - When such a filter is modified, the network traffic filtering rules - of all running virtual machines that reference this filter are updated. - <br/><br/> - Network filtering support is available <span class="since">since 0.8.1 - (QEMU, KVM)</span> - </p> - - <h2><a id="nwfconcepts">Concepts</a></h2> - <p> - The network traffic filtering subsystem enables configuration - of network traffic filtering rules on individual network - interfaces that are configured for certain types of - network configurations. Supported network types are - </p> - <ul> - <li><code>network</code></li> - <li><code>ethernet</code> -- must be used in bridging mode</li> - <li><code>bridge</code></li> - </ul> - <p> - The interface XML is used to reference a top-level filter. In the - following example, the interface description references - the filter <code>clean-traffic</code>. - </p> -<pre> -... -<devices> - <interface type='bridge'> - <mac address='00:16:3e:5d:c7:9e'/> - <filterref filter='clean-traffic'/> - </interface> -</devices> -...</pre> - - <p> - Network filters are written in XML and may either contain references - to other filters, contain rules for traffic filtering, or - hold a combination of both. The above referenced filter - <code>clean-traffic </code> is a filter that only contains references to - other filters and no actual filtering rules. Since references to - other filters can be used, a <i>tree</i> of filters can be built. - The <code>clean-traffic</code> filter can be viewed using the - command <code>virsh nwfilter-dumpxml clean-traffic</code>. - <br/><br/> - As previously mentioned, a single network filter can be referenced - by multiple virtual machines. Since interfaces will typically - have individual parameters associated with their respective traffic - filtering rules, the rules described in a filter XML can - be parameterized with variables. In this case, the variable name - is used in the filter XML and the name and value are provided at the - place where the filter is referenced. In the - following example, the interface description has been extended with - the parameter <code>IP</code> and a dotted IP address as value. - </p> -<pre> -... -<devices> - <interface type='bridge'> - <mac address='00:16:3e:5d:c7:9e'/> - <filterref filter='clean-traffic'> - <parameter name='IP' value='10.0.0.1'/> - </filterref> - </interface> -</devices> -...</pre> - - <p> - In this particular example, the <code>clean-traffic</code> network - traffic filter will be instantiated with the IP address parameter - 10.0.0.1 and enforce that the traffic from this interface will - always be using 10.0.0.1 as the source IP address, which is - one of the purposes of this particular filter. - <br/><br/> - </p> - - <h3><a id="nwfconceptschains">Filtering chains</a></h3> - <p> - Filtering rules are organized in filter chains. These chains can be - thought of as having a tree structure with packet - filtering rules as entries in individual chains (branches). <br/> - Packets start their filter evaluation in the <code>root</code> chain - and can then continue their evaluation in other chains, return from - those chains back into the <code>root</code> chain or be - dropped or accepted by a filtering rule in one of the traversed chains. - <br/> - Libvirt's network filtering system automatically creates individual - <code>root</code> chains for every virtual machine's network interface - on which the user chooses to activate traffic filtering. - The user may write filtering rules that are either directly instantiated - in the <code>root</code> chain or may create protocol-specific - filtering chains for efficient evaluation of protocol-specific rules. - The following chains exist: - </p> - <ul> - <li>root</li> - <li>mac <span class="since">(since 0.9.8)</span></li> - <li>stp (spanning tree protocol) - <span class="since">(since 0.9.8)</span></li> - <li>vlan (802.1Q) <span class="since">(since 0.9.8)</span></li> - <li>arp, rarp</li> - <li>ipv4</li> - <li>ipv6</li> - </ul> - <p> - <span class="since">Since 0.9.8</span> multiple chains evaluating the - <code>mac</code>, <code>stp</code>, <code>vlan</code>, - <code>arp</code>, <code>rarp</code>, <code>ipv4</code>, or - <code>ipv6</code> protocol can be created using - the protocol name only as a prefix in the chain's name. This for - examples allows chains with names <code>arp-xyz</code> or - <code>arp-test</code> to be specified and have ARP protocol packets - evaluated in those chains. - <br/><br/> - The following filter shows an example of filtering ARP traffic - in the <code>arp</code> chain. - </p> -<pre> -<filter name='no-arp-spoofing' chain='arp' priority='-500'> - <uuid>f88f1932-debf-4aa1-9fbe-f10d3aa4bc95</uuid> - <rule action='drop' direction='out' priority='300'> - <mac match='no' srcmacaddr='$MAC'/> - </rule> - <rule action='drop' direction='out' priority='350'> - <arp match='no' arpsrcmacaddr='$MAC'/> - </rule> - <rule action='drop' direction='out' priority='400'> - <arp match='no' arpsrcipaddr='$IP'/> - </rule> - <rule action='drop' direction='in' priority='450'> - <arp opcode='Reply'/> - <arp match='no' arpdstmacaddr='$MAC'/> - </rule> - <rule action='drop' direction='in' priority='500'> - <arp match='no' arpdstipaddr='$IP'/> - </rule> - <rule action='accept' direction='inout' priority='600'> - <arp opcode='Request'/> - </rule> - <rule action='accept' direction='inout' priority='650'> - <arp opcode='Reply'/> - </rule> - <rule action='drop' direction='inout' priority='1000'/> -</filter> -</pre> - <p> - The consequence of putting ARP-specific rules in the <code>arp</code> - chain, rather than for example in the <code>root</code> chain, is that - packets for any other protocol than ARP do not need to be evaluated by - ARP protocol-specific rules. This improves the efficiency - of the traffic filtering. However, one must then pay attention to only - put filtering rules for the given protocol into the chain since - any other rules will not be evaluated, i.e., an IPv4 rule will not - be evaluated in the ARP chain since no IPv4 protocol packets will - traverse the ARP chain. - <br/><br/> - </p> - <h3><a id="nwfconceptschainpriorities">Filtering chain priorities</a></h3> - <p> - All chains are connected to the <code>root</code> chain. The order in - which those chains are accessed is influenced by the priority of the - chain. The following table shows the chains that can be assigned a - priority and their default priorities. - </p> - <table class="top_table"> - <tr> - <th> Chain (prefix) </th> - <th> Default priority </th> - </tr> - <tr> - <td>stp</td><td>-810</td> - </tr> - <tr> - <td>mac</td><td>-800</td> - </tr> - <tr> - <td>vlan</td><td>-750</td> - </tr> - <tr> - <td>ipv4</td><td>-700</td> - </tr> - <tr> - <td>ipv6</td><td>-600</td> - </tr> - <tr> - <td>arp</td><td>-500</td> - </tr> - <tr> - <td>rarp</td><td>-400</td> - </tr> - </table> - <p> - A chain with a lower priority value is accessed before one with a - higher value. - <br/> - <span class="since">Since 0.9.8</span> the above listed chains - can be assigned custom priorities by writing a value in the - range [-1000, 1000] into the priority (XML) attribute in the filter - node. The above example filter shows the default priority of -500 - for <code>arp</code> chains. - </p> - <h3><a id="nwfconceptsvars">Usage of variables in filters</a></h3> - <p> - - Two variables names have so far been reserved for usage by the - network traffic filtering subsystem: <code>MAC</code> and - <code>IP</code>. - <br/><br/> - <code>MAC</code> is the MAC address of the - network interface. A filtering rule that references this variable - will automatically be instantiated with the MAC address of the - interface. This works without the user having to explicitly provide - the MAC parameter. Even though it is possible to specify the MAC - parameter similar to the IP parameter above, it is discouraged - since libvirt knows what MAC address an interface will be using. - <br/><br/> - The parameter <code>IP</code> represents the IP address - that the operating system inside the virtual machine is expected - to use on the given interface. The <code>IP</code> parameter - is special in so far as the libvirt daemon will try to determine - the IP address (and thus the IP parameter's value) that is being - used on an interface if the parameter - is not explicitly provided but referenced. - For current limitations on IP address detection, consult the - <a href="#nwflimits">section on limitations</a> on how to use this - feature and what to expect when using it. - <br/><br/> - The above-shown network filer <code>no-arp-spoofing</code> - is an example of - a network filter XML referencing the <code>MAC</code> and - <code>IP</code> variables. - <br/><br/> - Note that referenced variables are always prefixed with the - $ (dollar) sign. The format of the value of a variable - must be of the type expected by the filter attribute in the - XML. In the above example, the <code>IP</code> parameter - must hold a dotted IP address in decimal numbers format. - Failure to provide the correct - value type will result in the filter not being instantiatable - and will prevent a virtual machine from starting or the - interface from attaching when hotplugging is used. The types - that are expected for each XML attribute are shown - below. - <br/><br/> - <span class="since">Since 0.9.8</span> variables can contain lists of - elements, e.g., the variable <code>IP</code> can contain multiple IP - addresses that are valid on a particular interface. The notation for - providing multiple elements for the IP variable is: - </p> -<pre> -... -<devices> - <interface type='bridge'> - <mac address='00:16:3e:5d:c7:9e'/> - <filterref filter='clean-traffic'> - <parameter name='IP' value='10.0.0.1'/> - <parameter name='IP' value='10.0.0.2'/> - <parameter name='IP' value='10.0.0.3'/> - </filterref> - </interface> -</devices> -...</pre> - <p> - This then allows filters to enable multiple IP addresses - per interface. Therefore, with the list - of IP address shown above, the following rule will create 3 - individual filtering rules, one for each IP address. - </p> -<pre> -... -<rule action='accept' direction='in' priority='500'> - <tcp srpipaddr='$IP'/> -</rule> -... -</pre> - <p> - <span class="since">Since 0.9.10</span> it is possible to access - individual elements of a variable holding a list of elements. - A filtering rule like the following accesses the 2nd element - of the variable DSTPORTS. - </p> -<pre> -... -<rule action='accept' direction='in' priority='500'> - <udp dstportstart='$DSTPORTS[1]'/> -</rule> -... -</pre> - <p> - <span class="since">Since 0.9.10</span> it is possible to create - filtering rules that instantiate all combinations of rules from - different lists using the notation of - <code>$VARIABLE[@<iterator ID>]</code>. - The following rule allows a virtual machine to - receive traffic on a set of ports, which are specified in DSTPORTS, - from the set of source IP address specified in SRCIPADDRESSES. - The rule generates all combinations of elements of the variable - DSTPORT with those of SRCIPADDRESSES by using two independent - iterators to access their elements. - </p> -<pre> -... -<rule action='accept' direction='in' priority='500'> - <ip srcipaddr='$SRCIPADDRESSES[@1]' dstportstart='$DSTPORTS[@2]'/> -</rule> -... -</pre> - - <p> - In an example we assign concrete values to SRCIPADDRESSES and DSTPORTS - </p> -<pre> -SRCIPADDRESSES = [ 10.0.0.1, 11.1.2.3 ] -DSTPORTS = [ 80, 8080 ] -</pre> - <p> - Accessing the variables using $SRCIPADDRESSES[@1] and $DSTPORTS[@2] would - then result in all combinations of addresses and ports being created: - </p> -<pre> -10.0.0.1, 80 -10.0.0.1, 8080 -11.1.2.3, 80 -11.1.2.3, 8080 -</pre> - <p> - Accessing the same variables using a single iterator, for example by using - the notation $SRCIPADDRESSES[@1] and $DSTPORTS[@1], would result in - parallel access to both lists and result in the following combinations: - </p> -<pre> -10.0.0.1, 80 -11.1.2.3, 8080 -</pre> - <p> - Further, the notation of $VARIABLE is short-hand for $VARIABLE[@0]. The - former notation always assumes the iterator with Id '0'. - </p> - - <h3><a id="nwfelemsRulesAdvIPAddrDetection">Automatic IP address detection</a></h3> - <p> - The detection of IP addresses used on a virtual machine's interface - is automatically activated if the variable <code>IP</code> is referenced - but no value has been assigned to it. - <span class="since">Since 0.9.13</span> - the variable <code>CTRL_IP_LEARNING</code> can be used to specify - the IP address learning method to use. Valid values are <code>any</code>, - <code>dhcp</code>, or <code>none</code>. - <br/><br/> - The value <code>any</code> means that libvirt may use any packet to - determine the address in use by a virtual machine, which is the default - behavior if the variable <code>CTRL_IP_LEARNING</code> is not set. This method - will only detect a single IP address on an interface. - Once a VM's IP address has been detected, its IP network traffic - will be locked to that address, if for example IP address spoofing - is prevented by one of its filters. In that case the user of the VM - will not be able to change the IP address on the interface inside - the VM, which would be considered IP address spoofing. - When a VM is migrated to another host or resumed after a suspend operation, - the first packet sent by the VM will again determine the IP address it can - use on a particular interface. - <br/> - A value of <code>dhcp</code> specifies that libvirt should only honor DHCP - server-assigned addresses with valid leases. This method supports the detection - and usage of multiple IP address per interface. - When a VM is resumed after a suspend operation, still valid IP address leases - are applied to its filters. Otherwise the VM is expected to again use DHCP to obtain new - IP addresses. The migration of a VM to another physical host requires that - the VM again runs the DHCP protocol. - <br/><br/> - Use of <code>CTRL_IP_LEARNING=dhcp</code> (DHCP snooping) provides additional - anti-spoofing security, especially when combined with a filter allowing - only trusted DHCP servers to assign addresses. To enable this, set the - variable <code>DHCPSERVER</code> to the IP address of a valid DHCP server - and provide filters that use this variable to filter incoming DHCP responses. - <br/><br/> - When DHCP snooping is enabled and the DHCP lease expires, - the VM will no longer be able to use the IP address until it acquires a - new, valid lease from a DHCP server. If the VM is migrated, it must get - a new valid DHCP lease to use an IP address (e.g., by - bringing the VM interface down and up again). - <br/><br/> - Note that automatic DHCP detection listens to the DHCP traffic - the VM exchanges with the DHCP server of the infrastructure. To avoid - denial-of-service attacks on libvirt, the evaluation of those packets - is rate-limited, meaning that a VM sending an excessive number of DHCP - packets per second on an interface will not have all of those packets - evaluated and thus filters may not get adapted. Normal DHCP client - behavior is assumed to send a low number of DHCP packets per second. - Further, it is important to setup appropriate filters on all VMs in - the infrastructure to avoid them being able to send DHCP - packets. Therefore VMs must either be prevented from sending UDP and TCP - traffic from port 67 to port 68 or the <code>DHCPSERVER</code> - variable should be used on all VMs to restrict DHCP server messages to - only be allowed to originate from trusted DHCP servers. At the same - time anti-spoofing prevention must be enabled on all VMs in the subnet. - <br/><br/> - If <code>CTRL_IP_LEARNING</code> is set to <code>none</code>, libvirt does not do - IP address learning and referencing <code>IP</code> without assigning it an - explicit value is an error. - <br/><br/> - The following XML provides an example for the activation of IP address learning - using the DHCP snooping method: - </p> -<pre> -<interface type='bridge'> - <source bridge='virbr0'/> - <filterref filter='clean-traffic'> - <parameter name='CTRL_IP_LEARNING' value='dhcp'/> - </filterref> -</interface> -</pre> - - <h3><a id="nwfelemsReservedVars">Reserved Variables</a></h3> - <p> - The following table lists reserved variables in use by libvirt. - </p> - <table class="top_table"> - <tr> - <th> Variable Name </th> - <th> Semantics </th> - </tr> - <tr> - <td> MAC </td> - <td> The MAC address of the interface </td> - </tr> - <tr> - <td> IP </td> - <td> The list of IP addresses in use by an interface </td> - </tr> - <tr> - <td> IPV6 </td> - <td> The list of IPV6 addresses in use by an interface </td> - </tr> - <tr> - <td> DHCPSERVER </td> - <td> The list of IP addresses of trusted DHCP servers</td> - </tr> - <tr> - <td> DHCPSERVERV6 </td> - <td> Not currently implemented: - The list of IPv6 addresses of trusted DHCP servers</td> - </tr> - <tr> - <td> CTRL_IP_LEARNING </td> - <td> The choice of the IP address detection mode </td> - </tr> - </table> - - <h2><a id="nwfelems">Element and attribute overview</a></h2> - - <p> - The root element required for all network filters is - named <code>filter</code> with two possible attributes. The - <code>name</code> attribute provides a unique name of the - given filter. The <code>chain</code> attribute is optional but - allows certain filters to be better organized for more efficient - processing by the firewall subsystem of the underlying host. - Currently the system only supports the chains <code>root, - ipv4, ipv6, arp and rarp</code>. - </p> - - <h3><a id="nwfelemsRefs">References to other filters</a></h3> - <p> - Any filter may hold references to other filters. Individual - filters may be referenced multiple times in a filter tree but - references between filters must not introduce loops (directed - acyclic graph). - <br/><br/> - The following shows the XML of the <code>clean-traffic</code> - network filter referencing several other filters. - </p> -<pre> -<filter name='clean-traffic'> - <uuid>6ef53069-ba34-94a0-d33d-17751b9b8cb1</uuid> - <filterref filter='no-mac-spoofing'/> - <filterref filter='no-ip-spoofing'/> - <filterref filter='allow-incoming-ipv4'/> - <filterref filter='no-arp-spoofing'/> - <filterref filter='no-other-l2-traffic'/> - <filterref filter='qemu-announce-self'/> -</filter> -</pre> - - <p> - To reference another filter, the XML node <code>filterref</code> - needs to be provided inside a <code>filter</code> node. This - node must have the attribute <code>filter</code> whose value contains - the name of the filter to be referenced. - <br/><br/> - New network filters can be defined at any time and - may contain references to network filters that are - not known to libvirt, yet. However, once a virtual machine - is started or a network interface - referencing a filter is to be hotplugged, all network filters - in the filter tree must be available. Otherwise the virtual - machine will not start or the network interface cannot be - attached. - </p> - - <h3><a id="nwfelemsRules">Filter rules</a></h3> - <p> - The following XML shows a simple example of a network - traffic filter implementing a rule to drop traffic if - the IP address (provided through the value of the - variable IP) in an outgoing IP packet is not the expected - one, thus preventing IP address spoofing by the VM. - </p> -<pre> -<filter name='no-ip-spoofing' chain='ipv4'> - <uuid>fce8ae33-e69e-83bf-262e-30786c1f8072</uuid> - <rule action='drop' direction='out' priority='500'> - <ip match='no' srcipaddr='$IP'/> - </rule> -</filter> -</pre> - - <p> - A traffic filtering rule starts with the <code>rule</code> - node. This node may contain up to three attributes - </p> - <ul> - <li> - action -- mandatory; must either be <code>drop</code> - (matching the rule silently discards the packet with no - further analysis), - <code>reject</code> (matching the rule generates an ICMP - reject message with no further analysis) <span class="since">(since - 0.9.0)</span>, <code>accept</code> (matching the rule accepts - the packet with no further analysis), <code>return</code> - (matching the rule passes this filter, but returns control to - the calling filter for further - analysis) <span class="since">(since 0.9.7)</span>, - or <code>continue</code> (matching the rule goes on to the next - rule for further analysis) <span class="since">(since - 0.9.7)</span>. - </li> - <li> - direction -- mandatory; must either be <code>in</code>, <code>out</code> or - <code>inout</code> if the rule is for incoming, - outgoing or incoming-and-outgoing traffic - </li> - <li> - priority -- optional; the priority of the rule controls the order in - which the rule will be instantiated relative to other rules. - Rules with lower value will be instantiated before rules with higher - values. - Valid values are in the range of 0 to 1000. - <span class="since">Since 0.9.8</span> this has been extended to cover - the range of -1000 to 1000. If this attribute is not - provided, priority 500 will automatically be assigned. - <br/> - Note that filtering rules in the <code>root</code> chain are sorted - with filters connected to the <code>root</code> chain following - their priorities. This allows to interleave filtering rules with - access to filter chains. - (See also section on - <a href="#nwfconceptschainpriorities"> - filtering chain priorities - </a>.) - </li> - <li> - statematch -- optional; possible values are '0' or 'false' to - turn the underlying connection state matching off; default is 'true' - <br/> - Also read the section on <a href="#nwfelemsRulesAdv">advanced configuration</a> - topics. - </li> - </ul> - <p> - The above example indicates that the traffic of type <code>ip</code> - will be associated with the chain 'ipv4' and the rule will have - priority 500. If for example another filter is referenced whose - traffic of type <code>ip</code> is also associated with the chain - 'ipv4' then that filter's rules will be ordered relative to the priority - 500 of the shown rule. - <br/><br/> - A rule may contain a single rule for filtering of traffic. The - above example shows that traffic of type <code>ip</code> is to be - filtered. - </p> - - <h4><a id="nwfelemsRulesProto">Supported protocols</a></h4> - <p> - The following sections enumerate the list of protocols that - are supported by the network filtering subsystem. The - type of traffic a rule is supposed to filter on is provided - in the <code>rule</code> node as a nested node. Depending - on the traffic type a rule is filtering, the attributes are - different. The above example showed the single - attribute <code>srcipaddr</code> that is valid inside the - <code>ip</code> traffic filtering node. The following sections - show what attributes are valid and what type of data they are - expecting. The following datatypes are available: - </p> - <ul> - <li>UINT8 : 8 bit integer; range 0-255</li> - <li>UINT16: 16 bit integer; range 0-65535</li> - <li>MAC_ADDR: MAC address in dotted decimal format, i.e., 00:11:22:33:44:55</li> - <li>MAC_MASK: MAC address mask in MAC address format, i.e., FF:FF:FF:FC:00:00</li> - <li>IP_ADDR: IP address in dotted decimal format, i.e., 10.1.2.3</li> - <li>IP_MASK: IP address mask in either dotted decimal format (255.255.248.0) or CIDR mask (0-32)</li> - <li>IPV6_ADDR: IPv6 address in numbers format, i.e., FFFF::1</li> - <li>IPV6_MASK: IPv6 mask in numbers format (FFFF:FFFF:FC00::) or CIDR mask (0-128)</li> - <li>STRING: A string</li> - <li>BOOLEAN: 'true', 'yes', '1' or 'false', 'no', '0'</li> - <li>IPSETFLAGS: The source and destination flags of the ipset described - by up to 6 'src' or 'dst' elements selecting features from either - the source or destination part of the packet header; example: - src,src,dst. The number of 'selectors' to provide here depends - on the type of ipset that is referenced.</li> - </ul> - <p> - <br/><br/> - Every attribute except for those of type IP_MASK or IPV6_MASK can - be negated using the <code>match</code> - attribute with value <code>no</code>. Multiple negated attributes - may be grouped together. The following - XML fragment shows such an example using abstract attributes. - </p> -<pre> -[...] -<rule action='drop' direction='in'> - <protocol match='no' attribute1='value1' attribute2='value2'/> - <protocol attribute3='value3'/> -</rule> -[...] -</pre> - <p> - Rules perform a logical AND evaluation on all values of the given - protocol attributes. Thus, if a single attribute's value does not match - the one given in the rule, the whole rule will be skipped during - evaluation. Therefore, in the above example incoming traffic - will only be dropped if - the protocol property attribute1 does not match value1 AND - the protocol property attribute2 does not match value2 AND - the protocol property attribute3 matches value3. - <br/><br/> - </p> - - - <h5><a id="nwfelemsRulesProtoMAC">MAC (Ethernet)</a></h5> - <p> - Protocol ID: <code>mac</code> - <br/> - Note: Rules of this type should go into the <code>root</code> chain. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>dstmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of destination</td> - </tr> - <tr> - <td>dstmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of destination</td> - </tr> - <tr> - <td>protocolid</td> - <td>UINT16 (0x600-0xffff), STRING</td> - <td>Layer 3 protocol ID</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - </table> - <p> - Valid Strings for <code>protocolid</code> are: arp, rarp, ipv4, ipv6 - </p> -<pre> -[...] -<mac match='no' srcmacaddr='$MAC'/> -[...] -</pre> - - <h5><a id="nwfelemsRulesProtoVLAN">VLAN (802.1Q)</a> - <span class="since">(Since 0.9.8)</span> - </h5> - <p> - Protocol ID: <code>vlan</code> - <br/> - Note: Rules of this type should go either into the <code>root</code> or - <code>vlan</code> chain. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>dstmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of destination</td> - </tr> - <tr> - <td>dstmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of destination</td> - </tr> - <tr> - <td>vlanid</td> - <td>UINT16 (0x0-0xfff, 0 - 4095)</td> - <td>VLAN ID</td> - </tr> - <tr> - <td>encap-protocol</td> - <td>UINT16 (0x03c-0xfff), String</td> - <td>Encapsulated layer 3 protocol ID</td> - </tr> - <tr> - <td>comment </td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - </table> - <p> - Valid Strings for <code>encap-protocol</code> are: arp, ipv4, ipv6 - </p> - - <h5><a id="nwfelemsRulesProtoSTP">STP (Spanning Tree Protocol)</a> - <span class="since">(Since 0.9.8)</span> - </h5> - <p> - Protocol ID: <code>stp</code> - <br/> - Note: Rules of this type should go either into the <code>root</code> or - <code>stp</code> chain. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>type</td> - <td>UINT8</td> - <td>Bridge Protocol Data Unit (BPDU) type</td> - </tr> - <tr> - <td>flags</td> - <td>UINT8</td> - <td>BPDU flag</td> - </tr> - <tr> - <td>root-priority</td> - <td>UINT16</td> - <td>Root priority (range start)</td> - </tr> - <tr> - <td>root-priority-hi</td> - <td>UINT16</td> - <td>Root priority range end</td> - </tr> - <tr> - <td>root-address</td> - <td>MAC_ADDRESS</td> - <td>Root MAC address</td> - </tr> - <tr> - <td>root-address-mask</td> - <td>MAC_MASK</td> - <td>Root MAC address mask</td> - </tr> - <tr> - <td>root-cost</td> - <td>UINT32</td> - <td>Root path cost (range start)</td> - </tr> - <tr> - <td>root-cost-hi</td> - <td>UINT32</td> - <td>Root path cost range end</td> - </tr> - <tr> - <td>sender-priority</td> - <td>UINT16</td> - <td>Sender priority (range start)</td> - </tr> - <tr> - <td>sender-priority-hi</td> - <td>UINT16</td> - <td>Sender priority range end</td> - </tr> - <tr> - <td>sender-address</td> - <td>MAC_ADDRESS</td> - <td>BPDU sender MAC address</td> - </tr> - <tr> - <td>sender-address-mask</td> - <td>MAC_MASK</td> - <td>BPDU sender MAC address mask</td> - </tr> - <tr> - <td>port</td> - <td>UINT16</td> - <td>Port identifier (range start)</td> - </tr> - <tr> - <td>port_hi</td> - <td>UINT16</td> - <td>Port identifier range end</td> - </tr> - <tr> - <td>msg-age</td> - <td>UINT16</td> - <td>Message age timer (range start)</td> - </tr> - <tr> - <td>msg-age-hi</td> - <td>UINT16</td> - <td>Message age timer range end</td> - </tr> - <tr> - <td>max-age</td> - <td>UINT16</td> - <td>Maximum age timer (range start)</td> - </tr> - <tr> - <td>max-age-hi</td> - <td>UINT16</td> - <td>Maximum age timer range end</td> - </tr> - <tr> - <td>hello-time</td> - <td>UINT16</td> - <td>Hello time timer (range start)</td> - </tr> - <tr> - <td>hello-time-hi</td> - <td>UINT16</td> - <td>Hello time timer range end</td> - </tr> - <tr> - <td>forward-delay</td> - <td>UINT16</td> - <td>Forward delay (range start)</td> - </tr> - <tr> - <td>forward-delay-hi</td> - <td>UINT16</td> - <td>Forward delay range end</td> - </tr> - <tr> - <td>comment</td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - </table> - - <h5><a id="nwfelemsRulesProtoARP">ARP/RARP</a></h5> - <p> - Protocol ID: <code>arp</code> or <code>rarp</code> - <br/> - Note: Rules of this type should either go into the - <code>root</code> or <code>arp/rarp</code> chain. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>dstmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of destination</td> - </tr> - <tr> - <td>dstmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of destination</td> - </tr> - <tr> - <td>hwtype</td> - <td>UINT16</td> - <td>Hardware type</td> - </tr> - <tr> - <td>protocoltype</td> - <td>UINT16</td> - <td>Protocol type</td> - </tr> - <tr> - <td>opcode</td> - <td>UINT16, STRING</td> - <td>Opcode</td> - </tr> - <tr> - <td>arpsrcmacaddr</td> - <td>MAC_ADDR</td> - <td>Source MAC address in ARP/RARP packet</td> - </tr> - <tr> - <td>arpdstmacaddr</td> - <td>MAC_ADDR</td> - <td>Destination MAC address in ARP/RARP packet</td> - </tr> - <tr> - <td>arpsrcipaddr</td> - <td>IP_ADDR</td> - <td>Source IP address in ARP/RARP packet</td> - </tr> - <tr> - <td>arpsrcipmask <span class="since">(Since 1.2.3)</span></td> - <td>IP_MASK</td> - <td>Source IP mask</td> - </tr> - <tr> - <td>arpdstipaddr</td> - <td>IP_ADDR</td> - <td>Destination IP address in ARP/RARP packet</td> - </tr> - <tr> - <td>arpdstipmask <span class="since">(Since 1.2.3)</span></td> - <td>IP_MASK</td> - <td>Destination IP mask</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - <tr> - <td>gratuitous <span class="since">(Since 0.9.2)</span></td> - <td>BOOLEAN</td> - <td>boolean indicating whether to check for gratuitous ARP packet</td> - </tr> - </table> - <p> - Valid strings for the <code>Opcode</code> field are: - Request, Reply, Request_Reverse, Reply_Reverse, DRARP_Request, - DRARP_Reply, DRARP_Error, InARP_Request, ARP_NAK - <br/><br/> - </p> - - <h5><a id="nwfelemsRulesProtoIP">IPv4</a></h5> - <p> - Protocol ID: <code>ip</code> - <br/> - Note: Rules of this type should either go into the - <code>root</code> or <code>ipv4</code> chain. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>dstmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of destination</td> - </tr> - <tr> - <td>dstmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of destination</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IP_ADDR</td> - <td>Source IP address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IP_MASK</td> - <td>Mask applied to source IP address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IP_ADDR</td> - <td>Destination IP address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IP_MASK</td> - <td>Mask applied to destination IP address</td> - </tr> - <tr> - <td>protocol</td> - <td>UINT8, STRING</td> - <td>Layer 4 protocol identifier</td> - </tr> - <tr> - <td>srcportstart</td> - <td>UINT16</td> - <td>Start of range of valid source ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>srcportend</td> - <td>UINT16</td> - <td>End of range of valid source ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>dstportstart</td> - <td>UINT16</td> - <td>Start of range of valid destination ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>dstportend</td> - <td>UINT16</td> - <td>End of range of valid destination ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>dscp</td> - <td>UINT8 (0x0-0x3f, 0 - 63)</td> - <td>Differentiated Services Code Point</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - </table> - <p> - Valid strings for <code>protocol</code> are: - tcp, udp, udplite, esp, ah, icmp, igmp, sctp - <br/><br/> - </p> - - - <h5><a id="nwfelemsRulesProtoIPv6">IPv6</a></h5> - <p> - Protocol ID: <code>ipv6</code> - <br/> - Note: Rules of this type should either go into the - <code>root</code> or <code>ipv6</code> chain. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>dstmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of destination</td> - </tr> - <tr> - <td>dstmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of destination</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IPV6_ADDR</td> - <td>Source IPv6 address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to source IPv6 address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IPV6_ADDR</td> - <td>Destination IPv6 address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to destination IPv6 address</td> - </tr> - <tr> - <td>protocol</td> - <td>UINT8</td> - <td>Layer 4 protocol identifier</td> - </tr> - <tr> - <td>srcportstart</td> - <td>UINT16</td> - <td>Start of range of valid source ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>srcportend</td> - <td>UINT16</td> - <td>End of range of valid source ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>dstportstart</td> - <td>UINT16</td> - <td>Start of range of valid destination ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>dstportend</td> - <td>UINT16</td> - <td>End of range of valid destination ports; requires <code>protocol</code></td> - </tr> - <tr> - <td>type<span class="since">(Since 1.2.12)</span></td> - <td>UINT8</td> - <td>ICMPv6 type; requires <code>protocol</code> to be set to <code>icmpv6</code></td> - </tr> - <tr> - <td>typeend<span class="since">(Since 1.2.12)</span></td> - <td>UINT8</td> - <td>ICMPv6 type end of range; requires <code>protocol</code> to be set to <code>icmpv6</code></td> - </tr> - <tr> - <td>code<span class="since">(Since 1.2.12)</span></td> - <td>UINT8</td> - <td>ICMPv6 code; requires <code>protocol</code> to be set to <code>icmpv6</code></td> - </tr> - <tr> - <td>code<span class="since">(Since 1.2.12)</span></td> - <td>UINT8</td> - <td>ICMPv6 code end of range; requires <code>protocol</code> to be set to <code>icmpv6</code></td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - </table> - <p> - Valid strings for <code>protocol</code> are: - tcp, udp, udplite, esp, ah, icmpv6, sctp - <br/><br/> - </p> - - <h5><a id="nwfelemsRulesProtoTCP-ipv4">TCP/UDP/SCTP</a></h5> - <p> - Protocol ID: <code>tcp</code>, <code>udp</code>, <code>sctp</code> - <br/> - Note: The chain parameter is ignored for this type of traffic - and should either be omitted or set to <code>root</code>. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IP_ADDR</td> - <td>Source IP address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IP_MASK</td> - <td>Mask applied to source IP address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IP_ADDR</td> - <td>Destination IP address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IP_MASK</td> - <td>Mask applied to destination IP address</td> - </tr> - - <tr> - <td>srcipfrom</td> - <td>IP_ADDR</td> - <td>Start of range of source IP address</td> - </tr> - <tr> - <td>srcipto</td> - <td>IP_ADDR</td> - <td>End of range of source IP address</td> - </tr> - <tr> - <td>dstipfrom</td> - <td>IP_ADDR</td> - <td>Start of range of destination IP address</td> - </tr> - <tr> - <td>dstipto</td> - <td>IP_ADDR</td> - <td>End of range of destination IP address</td> - </tr> - - <tr> - <td>srcportstart</td> - <td>UINT16</td> - <td>Start of range of valid source ports</td> - </tr> - <tr> - <td>srcportend</td> - <td>UINT16</td> - <td>End of range of valid source ports</td> - </tr> - <tr> - <td>dstportstart</td> - <td>UINT16</td> - <td>Start of range of valid destination ports</td> - </tr> - <tr> - <td>dstportend</td> - <td>UINT16</td> - <td>End of range of valid destination ports</td> - </tr> - <tr> - <td>dscp</td> - <td>UINT8 (0x0-0x3f, 0 - 63)</td> - <td>Differentiated Services Code Point</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - <tr> - <td>state <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE</td> - </tr> - <tr> - <td>flags <span class="since">(Since 0.9.1)</span></td> - <td>STRING</td> - <td>TCP-only: format of mask/flags with mask and flags each being a comma separated list of SYN,ACK,URG,PSH,FIN,RST or NONE or ALL</td> - </tr> - <tr> - <td>ipset <span class="since">(Since 0.9.13)</span></td> - <td>STRING</td> - <td>The name of an IPSet managed outside of libvirt</td> - </tr> - <tr> - <td>ipsetflags <span class="since">(Since 0.9.13)</span></td> - <td>IPSETFLAGS</td> - <td>flags for the IPSet; requires ipset attribute</td> - </tr> - </table> - <p> - <br/><br/> - </p> - - - <h5><a id="nwfelemsRulesProtoICMP">ICMP</a></h5> - <p> - Protocol ID: <code>icmp</code> - <br/> - Note: The chain parameter is ignored for this type of traffic - and should either be omitted or set to <code>root</code>. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>dstmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of destination</td> - </tr> - <tr> - <td>dstmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of destination</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IP_ADDR</td> - <td>Source IP address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IP_MASK</td> - <td>Mask applied to source IP address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IP_ADDR</td> - <td>Destination IP address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IP_MASK</td> - <td>Mask applied to destination IP address</td> - </tr> - - <tr> - <td>srcipfrom</td> - <td>IP_ADDR</td> - <td>Start of range of source IP address</td> - </tr> - <tr> - <td>srcipto</td> - <td>IP_ADDR</td> - <td>End of range of source IP address</td> - </tr> - <tr> - <td>dstipfrom</td> - <td>IP_ADDR</td> - <td>Start of range of destination IP address</td> - </tr> - <tr> - <td>dstipto</td> - <td>IP_ADDR</td> - <td>End of range of destination IP address</td> - </tr> - <tr> - <td>type</td> - <td>UINT16</td> - <td>ICMP type</td> - </tr> - <tr> - <td>code</td> - <td>UINT16</td> - <td>ICMP code</td> - </tr> - <tr> - <td>dscp</td> - <td>UINT8 (0x0-0x3f, 0 - 63)</td> - <td>Differentiated Services Code Point</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - <tr> - <td>state <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE</td> - </tr> - <tr> - <td>ipset <span class="since">(Since 0.9.13)</span></td> - <td>STRING</td> - <td>The name of an IPSet managed outside of libvirt</td> - </tr> - <tr> - <td>ipsetflags <span class="since">(Since 0.9.13)</span></td> - <td>IPSETFLAGS</td> - <td>flags for the IPSet; requires ipset attribute</td> - </tr> - </table> - <p> - <br/><br/> - </p> - - <h5><a id="nwfelemsRulesProtoMisc">IGMP, ESP, AH, UDPLITE, 'ALL'</a></h5> - <p> - Protocol ID: <code>igmp</code>, <code>esp</code>, <code>ah</code>, <code>udplite</code>, <code>all</code> - <br/> - Note: The chain parameter is ignored for this type of traffic - and should either be omitted or set to <code>root</code>. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of sender</td> - </tr> - <tr> - <td>dstmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of destination</td> - </tr> - <tr> - <td>dstmacmask</td> - <td>MAC_MASK</td> - <td>Mask applied to MAC address of destination</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IP_ADDR</td> - <td>Source IP address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IP_MASK</td> - <td>Mask applied to source IP address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IP_ADDR</td> - <td>Destination IP address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IP_MASK</td> - <td>Mask applied to destination IP address</td> - </tr> - - <tr> - <td>srcipfrom</td> - <td>IP_ADDR</td> - <td>Start of range of source IP address</td> - </tr> - <tr> - <td>srcipto</td> - <td>IP_ADDR</td> - <td>End of range of source IP address</td> - </tr> - <tr> - <td>dstipfrom</td> - <td>IP_ADDR</td> - <td>Start of range of destination IP address</td> - </tr> - <tr> - <td>dstipto</td> - <td>IP_ADDR</td> - <td>End of range of destination IP address</td> - </tr> - <tr> - <td>dscp</td> - <td>UINT8 (0x0-0x3f, 0 - 63)</td> - <td>Differentiated Services Code Point</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - <tr> - <td>state <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE</td> - </tr> - <tr> - <td>ipset <span class="since">(Since 0.9.13)</span></td> - <td>STRING</td> - <td>The name of an IPSet managed outside of libvirt</td> - </tr> - <tr> - <td>ipsetflags <span class="since">(Since 0.9.13)</span></td> - <td>IPSETFLAGS</td> - <td>flags for the IPSet; requires ipset attribute</td> - </tr> - </table> - <p> - <br/><br/> - </p> - - - <h5><a id="nwfelemsRulesProtoTCP-ipv6">TCP/UDP/SCTP over IPV6</a></h5> - <p> - Protocol ID: <code>tcp-ipv6</code>, <code>udp-ipv6</code>, <code>sctp-ipv6</code> - <br/> - Note: The chain parameter is ignored for this type of traffic - and should either be omitted or set to <code>root</code>. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IPV6_ADDR</td> - <td>Source IP address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to source IP address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IPV6_ADDR</td> - <td>Destination IP address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to destination IP address</td> - </tr> - - <tr> - <td>srcipfrom</td> - <td>IPV6_ADDR</td> - <td>Start of range of source IP address</td> - </tr> - <tr> - <td>srcipto</td> - <td>IPV6_ADDR</td> - <td>End of range of source IP address</td> - </tr> - <tr> - <td>dstipfrom</td> - <td>IPV6_ADDR</td> - <td>Start of range of destination IP address</td> - </tr> - <tr> - <td>dstipto</td> - <td>IPV6_ADDR</td> - <td>End of range of destination IP address</td> - </tr> - - <tr> - <td>srcportstart</td> - <td>UINT16</td> - <td>Start of range of valid source ports</td> - </tr> - <tr> - <td>srcportend</td> - <td>UINT16</td> - <td>End of range of valid source ports</td> - </tr> - <tr> - <td>dstportstart</td> - <td>UINT16</td> - <td>Start of range of valid destination ports</td> - </tr> - <tr> - <td>dstportend</td> - <td>UINT16</td> - <td>End of range of valid destination ports</td> - </tr> - <tr> - <td>dscp</td> - <td>UINT8 (0x0-0x3f, 0 - 63)</td> - <td>Differentiated Services Code Point</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - <tr> - <td>state <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE</td> - </tr> - <tr> - <td>flags <span class="since">(Since 0.9.1)</span></td> - <td>STRING</td> - <td>TCP-only: format of mask/flags with mask and flags each being a comma separated list of SYN,ACK,URG,PSH,FIN,RST or NONE or ALL</td> - </tr> - <tr> - <td>ipset <span class="since">(Since 0.9.13)</span></td> - <td>STRING</td> - <td>The name of an IPSet managed outside of libvirt</td> - </tr> - <tr> - <td>ipsetflags <span class="since">(Since 0.9.13)</span></td> - <td>IPSETFLAGS</td> - <td>flags for the IPSet; requires ipset attribute</td> - </tr> - </table> - <p> - <br/><br/> - </p> - - - <h5><a id="nwfelemsRulesProtoICMPv6">ICMPv6</a></h5> - <p> - Protocol ID: <code>icmpv6</code> - <br/> - Note: The chain parameter is ignored for this type of traffic - and should either be omitted or set to <code>root</code>. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IPV6_ADDR</td> - <td>Source IPv6 address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to source IPv6 address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IPV6_ADDR</td> - <td>Destination IPv6 address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to destination IPv6 address</td> - </tr> - - <tr> - <td>srcipfrom</td> - <td>IPV6_ADDR</td> - <td>Start of range of source IP address</td> - </tr> - <tr> - <td>srcipto</td> - <td>IPV6_ADDR</td> - <td>End of range of source IP address</td> - </tr> - <tr> - <td>dstipfrom</td> - <td>IPV6_ADDR</td> - <td>Start of range of destination IP address</td> - </tr> - <tr> - <td>dstipto</td> - <td>IPV6_ADDR</td> - <td>End of range of destination IP address</td> - </tr> - - <tr> - <td>type</td> - <td>UINT16</td> - <td>ICMPv6 type</td> - </tr> - <tr> - <td>code</td> - <td>UINT16</td> - <td>ICMPv6 code</td> - </tr> - <tr> - <td>dscp</td> - <td>UINT8 (0x0-0x3f, 0 - 63)</td> - <td>Differentiated Services Code Point</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - <tr> - <td>state <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE</td> - </tr> - <tr> - <td>ipset <span class="since">(Since 0.9.13)</span></td> - <td>STRING</td> - <td>The name of an IPSet managed outside of libvirt</td> - </tr> - <tr> - <td>ipsetflags <span class="since">(Since 0.9.13)</span></td> - <td>IPSETFLAGS</td> - <td>flags for the IPSet; requires ipset attribute</td> - </tr> - </table> - <p> - <br/><br/> - </p> - - <h5><a id="nwfelemsRulesProtoMiscv6">ESP, AH, UDPLITE, 'ALL' over IPv6</a></h5> - <p> - Protocol ID: <code>esp-ipv6</code>, <code>ah-ipv6</code>, <code>udplite-ipv6</code>, <code>all-ipv6</code> - <br/> - Note: The chain parameter is ignored for this type of traffic - and should either be omitted or set to <code>root</code>. - </p> - <table class="top_table"> - <tr> - <th> Attribute </th> - <th> Datatype </th> - <th> Semantics </th> - </tr> - <tr> - <td>srcmacaddr</td> - <td>MAC_ADDR</td> - <td>MAC address of sender</td> - </tr> - <tr> - <td>srcipaddr</td> - <td>IPV6_ADDR</td> - <td>Source IPv6 address</td> - </tr> - <tr> - <td>srcipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to source IPv6 address</td> - </tr> - <tr> - <td>dstipaddr</td> - <td>IPV6_ADDR</td> - <td>Destination IPv6 address</td> - </tr> - <tr> - <td>dstipmask</td> - <td>IPV6_MASK</td> - <td>Mask applied to destination IPv6 address</td> - </tr> - - <tr> - <td>srcipfrom</td> - <td>IPV6_ADDR</td> - <td>Start of range of source IP address</td> - </tr> - <tr> - <td>srcipto</td> - <td>IPV6_ADDR</td> - <td>End of range of source IP address</td> - </tr> - <tr> - <td>dstipfrom</td> - <td>IPV6_ADDR</td> - <td>Start of range of destination IP address</td> - </tr> - <tr> - <td>dstipto</td> - <td>IPV6_ADDR</td> - <td>End of range of destination IP address</td> - </tr> - <tr> - <td>dscp</td> - <td>UINT8 (0x0-0x3f, 0 - 63)</td> - <td>Differentiated Services Code Point</td> - </tr> - <tr> - <td>comment <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>text with max. 256 characters</td> - </tr> - <tr> - <td>state <span class="since">(Since 0.8.5)</span></td> - <td>STRING</td> - <td>comma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE</td> - </tr> - <tr> - <td>ipset <span class="since">(Since 0.9.13)</span></td> - <td>STRING</td> - <td>The name of an IPSet managed outside of libvirt</td> - </tr> - <tr> - <td>ipsetflags <span class="since">(Since 0.9.13)</span></td> - <td>IPSETFLAGS</td> - <td>flags for the IPSet; requires ipset attribute</td> - </tr> - </table> - <p> - <br/><br/> - </p> - - <h3><a id="nwfelemsRulesAdv">Advanced Filter Configuration Topics</a></h3> - <p> - The following sections discuss advanced filter configuration - topics. - </p> - - <h4><a id="nwfelemsRulesAdvTracking">Connection tracking</a></h4> - <p> - The network filtering subsystem (on Linux) makes use of the connection - tracking support of iptables. This helps in enforcing the - directionality of network traffic (state match) as well as - counting and limiting the number of simultaneous connections towards - a VM. As an example, if a VM has TCP port 8080 - open as a server, clients may connect to the VM on port 8080. - Connection tracking and enforcement of directionality then prevents - the VM from initiating a connection from - (TCP client) port 8080 to the host back to a remote host. - More importantly, tracking helps to prevent - remote attackers from establishing a connection back to a VM. For example, - if the user inside the VM established a connection to - port 80 on an attacker site, then the attacker will not be able to - initiate a connection from TCP port 80 back towards the VM. - By default the connection state match that enables connection tracking - and then enforcement of directionality of traffic is turned on. <br/> - The following shows an example XML fragment where this feature has been - turned off for incoming connections to TCP port 12345. - </p> -<pre> -[...] -<rule direction='in' action='accept' statematch='false'> - <tcp dstportstart='12345'/> -</rule> -[...] -</pre> - <p> - This now allows incoming traffic to TCP port 12345, but would also - enable the initiation from (client) TCP port 12345 within the VM, - which may or may not be desirable. - </p> - - <h4><a id="nwfelemsRulesAdvLimiting">Limiting Number of Connections</a></h4> - <p> - To limit the number of connections a VM may establish, a rule must - be provided that sets a limit of connections for a given - type of traffic. If for example a VM - is supposed to be allowed to only ping one other IP address at a time - and is supposed to have only one active incoming ssh connection at a - time, the following XML fragment can be used to achieve this. - </p> -<pre> -[...] -<rule action='drop' direction='in' priority='400'> - <tcp connlimit-above='1'/> -</rule> -<rule action='accept' direction='in' priority='500'> - <tcp dstportstart='22'/> -</rule> -<rule action='drop' direction='out' priority='400'> - <icmp connlimit-above='1'/> -</rule> -<rule action='accept' direction='out' priority='500'> - <icmp/> -</rule> -<rule action='accept' direction='out' priority='500'> - <udp dstportstart='53'/> -</rule> -<rule action='drop' direction='inout' priority='1000'> - <all/> -</rule> -[...] -</pre> - <p> - Note that the rule for the limit has to logically appear - before the rule for accepting the traffic.<br/> - An additional rule for letting DNS traffic to port 22 - go out the VM has been added to avoid ssh sessions not - getting established for reasons related to DNS lookup failures - by the ssh daemon. Leaving this rule out may otherwise lead to - fun-filled debugging joy (symptom: ssh client seems to hang - while trying to connect). - <br/><br/> - Lot of care must be taken with timeouts related - to tracking of traffic. An ICMP ping that - the user may have terminated inside the VM may have a long - timeout in the host's connection tracking system and therefore - not allow another ICMP ping to go through for a while. Therefore, - the timeouts have to be tuned in the host's sysfs, i.e., - </p> - -<pre> -echo 3 > /proc/sys/net/netfilter/nf_conntrack_icmp_timeout -</pre> - <p> - sets the ICMP connection tracking timeout to 3 seconds. The - effect of this is that once one ping is terminated, another - one can start after 3 seconds.<br/> - Further, we want to point out that a client that for whatever - reason has not properly closed a TCP connection may cause a - connection to be held open for a longer period of time, - depending to what timeout the <code>TCP established</code> state - timeout has been set to on the host. Also, idle connections may time - out in the connection tracking system but can be reactivated once - packets are exchanged. However, a newly initiated connection may force - an idle connection into TCP backoff if the number of allowed connections - is set to a too low limit, the new connection is established - and hits (not exceeds) the limit of allowed connections and for - example a key is pressed on the old ssh session, which now has become - unresponsive due to its traffic being dropped. - Therefore, the limit of connections should be rather high so that - fluctuations in new TCP connections don't cause odd - traffic behavior in relation to idle connections. - </p> - - <h2><a id="nwfcli">Command line tools</a></h2> - <p> - The libvirt command line tool <code>virsh</code> has been extended - with life-cycle support for network filters. All commands related - to the network filtering subsystem start with the prefix - <code>nwfilter</code>. The following commands are available: - </p> - <ul> - <li>nwfilter-list : list UUIDs and names of all network filters</li> - <li>nwfilter-define : define a new network filter or update an existing one</li> - <li>nwfilter-undefine : delete a network filter given its name; it must not be currently in use</li> - <li>nwfilter-dumpxml : display a network filter given its name</li> - <li>nwfilter-edit : edit a network filter given its name</li> - </ul> - - <h2><a id="nwfexamples">Pre-existing network filters</a></h2> - <p> - The following is a list of example network filters that are - automatically installed with libvirt.</p> - <table class="top_table"> - <tr> - <th> Name </th> - <th> Description </th> - </tr> - <tr> - <td> no-arp-spoofing </td> - <td> Prevent a VM from spoofing ARP traffic; this filter - only allows ARP request and reply messages and enforces - that those packets contain the MAC and IP addresses - of the VM.</td> - </tr> - <tr> - <td> allow-arp </td> - <td> Allow ARP traffic in both directions</td> - </tr> - <tr> - <td> allow-ipv4 </td> - <td> Allow IPv4 traffic in both directions</td> - </tr> - <tr> - <td> allow-ipv6 </td> - <td> Allow IPv6 traffic in both directions</td> - </tr> - <tr> - <td> allow-incoming-ipv4 </td> - <td> Allow incoming IPv4 traffic</td> - </tr> - <tr> - <td> allow-incoming-ipv6 </td> - <td> Allow incoming IPv6 traffic</td> - </tr> - <tr> - <td> allow-dhcp </td> - <td> Allow a VM to request an IP address via DHCP (from any - DHCP server)</td> - </tr> - <tr> - <td> allow-dhcpv6 </td> - <td> Similar to allow-dhcp, but for DHCPv6 </td> - </tr> - <tr> - <td> allow-dhcp-server </td> - <td> Allow a VM to request an IP address from a specified - DHCP server. The dotted decimal IP address of the DHCP - server must be provided in a reference to this filter. - The name of the variable must be <i>DHCPSERVER</i>.</td> - </tr> - <tr> - <td> allow-dhcpv6-server </td> - <td> Similar to allow-dhcp-server, but for DHCPv6 </td> - </tr> - <tr> - <td> no-ip-spoofing </td> - <td> Prevent a VM from sending of IPv4 packets with - a source IP address different from the one - in the packet. </td> - </tr> - <tr> - <td> no-ipv6-spoofing </td> - <td> Similar to no-ip-spoofing, but for IPv6 </td> - </tr> - <tr> - <td> no-ip-multicast </td> - <td> Prevent a VM from sending IP multicast packets. </td> - </tr> - <tr> - <td> no-ipv6-multicast </td> - <td> Similar to no-ip-multicast, but for IPv6 </td> - </tr> - <tr> - <td> clean-traffic </td> - <td> Prevent MAC, IP and ARP spoofing. This filter references - several other filters as building blocks. </td> - </tr> - </table> - <p> - Note that most of the above filters are only building blocks and - require a combination with other filters to provide useful network - traffic filtering. - The most useful one in the above list is the <i>clean-traffic</i> - filter. This filter itself can for example be combined with the - <i>no-ip-multicast</i> - filter to prevent virtual machines from sending IP multicast traffic - on top of the prevention of packet spoofing. - </p> - - <h2><a id="nwfwrite">Writing your own filters</a></h2> - - <p> - Since libvirt only provides a couple of example networking filters, you - may consider writing your own. When planning on doing so - there are a couple of things - you may need to know regarding the network filtering subsystem and how - it works internally. Certainly you also have to know and understand - the protocols very well that you want to be filtering on so that - no further traffic than what you want can pass and that in fact the - traffic you want to allow does pass. - <br/><br/> - The network filtering subsystem is currently only available on - Linux hosts and only works for QEMU and KVM type of virtual machines. - On Linux - it builds upon the support for <code>ebtables</code>, <code>iptables - </code> and <code>ip6tables</code> and makes use of their features. - From the above list of supported protocols the following ones are - implemented using <code>ebtables</code>: - </p> - <ul> - <li>mac</li> - <li>stp (spanning tree protocol)</li> - <li>vlan (802.1Q)</li> - <li>arp, rarp</li> - <li>ipv4</li> - <li>ipv6</li> - </ul> - - <p> - All other protocols over IPv4 are supported using iptables, those over - IPv6 are implemented using ip6tables. - <br/><br/> - On a Linux host, all traffic filtering instantiated by libvirt's network - filter subsystem first passes through the filtering support implemented - by ebtables and only then through iptables or ip6tables filters. If - a filter tree has rules with the protocols <code>mac</code>, - <code>stp</code>, <code>vlan</code> - <code>arp</code>, <code>rarp</code>, <code>ipv4</code>, - or <code>ipv6</code> ebtables rules will automatically be instantiated. - <br/> - The role of the <code>chain</code> attribute in the network filter - XML is that internally a new user-defined ebtables table is created - that then for example receives all <code>arp</code> traffic coming - from or going to a virtual machine if the chain <code>arp</code> - has been specified. Further, a rule is generated in an interface's - <code>root</code> chain that directs all ipv4 traffic into the - user-defined chain. Therefore, all ARP traffic rules should then be - placed into filters specifying this chain. This type of branching - into user-defined tables is only supported with filtering on the ebtables - layer. - <br/> - <span class="since">Since 0.9.8</span> multiple chains for the same - protocol can be created. For this the name of the chain must have - a prefix of one of the previously enumerated protocols. To create an - additional chain for handling of ARP traffic, a chain with name - <code>arp-test</code> can be specified. - <br/> - As an example, it is - possible to filter on UDP traffic by source and destination ports using - the <code>ip</code> protocol filter and specifying attributes for the - protocol, source and destination IP addresses and ports of UDP packets - that are to be accepted. This allows - early filtering of UDP traffic with ebtables. However, once an IP or IPv6 - packet, such as a UDP packet, - has passed the ebtables layer and there is at least one rule in a filter - tree that instantiates iptables or ip6tables rules, a rule to let - the UDP packet pass will also be necessary to be provided for those - filtering layers. This can be - achieved with a rule containing an appropriate <code>udp</code> or - <code>udp-ipv6</code> traffic filtering node. - </p> - - <h3><a id="nwfwriteexample">Example custom filter</a></h3> - <p> - As an example we want to now build a filter that fulfills the following - list of requirements: - </p> - <ul> - <li>prevents a VM's interface from MAC, IP and ARP spoofing</li> - <li>opens only TCP ports 22 and 80 of a VM's interface</li> - <li>allows the VM to send ping traffic from an interface - but not let the VM be pinged on the interface</li> - <li>allows the VM to do DNS lookups (UDP towards port 53)</li> - </ul> - <p> - The requirement to prevent spoofing is fulfilled by the existing - <code>clean-traffic</code> network filter, thus we will reference this - filter from our custom filter. - <br/> - To enable traffic for TCP ports 22 and 80 we will add 2 rules to - enable this type of traffic. To allow the VM to send ping traffic - we will add a rule for ICMP traffic. For simplicity reasons - we allow general ICMP traffic to be initiated from the VM, not - just ICMP echo request and response messages. To then - disallow all other traffic to reach or be initiated by the - VM we will then need to add a rule that drops all other traffic. - Assuming our VM is called <i>test</i> and - the interface we want to associate our filter with is called <i>eth0</i>, - we name our filter <i>test-eth0</i>. - The result of these considerations is the following network filter XML: - </p> -<pre> -<filter name='test-eth0'> - <!-- reference the clean traffic filter to prevent - MAC, IP and ARP spoofing. By not providing - and IP address parameter, libvirt will detect the - IP address the VM is using. --> - <filterref filter='clean-traffic'/> - - <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable --> - <rule action='accept' direction='in'> - <tcp dstportstart='22'/> - </rule> - - <rule action='accept' direction='in'> - <tcp dstportstart='80'/> - </rule> - - <!-- enable general ICMP traffic to be initiated by the VM; - this includes ping traffic --> - <rule action='accept' direction='out'> - <icmp/> - </rule> - - <!-- enable outgoing DNS lookups using UDP --> - <rule action='accept' direction='out'> - <udp dstportstart='53'/> - </rule> - - <!-- drop all other traffic --> - <rule action='drop' direction='inout'> - <all/> - </rule> - -</filter> -</pre> - <p> - Note that none of the rules in the above XML contain the - IP address of the VM as either source or destination address, yet - the filtering of the traffic works correctly. The reason is that - the evaluation of the rules internally happens on a - per-interface basis and the rules are evaluated based on the knowledge - about which (tap) interface has sent or will receive the packet rather - than what their source or destination IP address may be. - <br/><br/> - An XML fragment for a possible network interface description inside - the domain XML of the <code>test</code> VM could then look like this: - </p> -<pre> -[...] -<interface type='bridge'> - <source bridge='mybridge'/> - <filterref filter='test-eth0'/> -</interface> -[...] -</pre> - - <p> - To more strictly control the ICMP traffic and enforce that only - ICMP echo requests can be sent from the VM - and only ICMP echo responses be received by the VM, the above - <code>ICMP</code> rule can be replaced with the following two rules: - </p> -<pre> -<!-- enable outgoing ICMP echo requests--> -<rule action='accept' direction='out'> - <icmp type='8'/> -</rule> - -<!-- enable incoming ICMP echo replies--> -<rule action='accept' direction='in'> - <icmp type='0'/> -</rule> -</pre> - - <h3><a id="nwfwriteexample2nd">Second example custom filter</a></h3> - <p> - In this example we now want to build a similar filter as in the - example above, but extend the list of requirements with an - ftp server located inside the VM. Further, we will be using features - that have been added in <span class="since">version 0.8.5</span>. - The requirements for this filter are: - </p> - <ul> - <li>prevents a VM's interface from MAC, IP and ARP spoofing</li> - <li>opens only TCP ports 22 and 80 of a VM's interface</li> - <li>allows the VM to send ping traffic from an interface - but not let the VM be pinged on the interface</li> - <li>allows the VM to do DNS lookups (UDP towards port 53)</li> - <li>enable an ftp server (in active mode) to be run inside the VM</li> - </ul> - <p> - The additional requirement of allowing an ftp server to be run inside - the VM maps into the requirement of allowing port 21 to be reachable - for ftp control traffic as well as enabling the VM to establish an - outgoing tcp connection originating from the VM's TCP port 20 back to - the ftp client (ftp active mode). There are several ways of how this - filter can be written and we present 2 solutions. - <br/><br/> - The 1st solution makes use of the <code>state</code> attribute of - the TCP protocol that gives us a hook into the connection tracking - framework of the Linux host. For the VM-initiated ftp data connection - (ftp active mode) we use the <code>RELATED</code> state that allows - us to detect that the VM-initiated ftp data connection is a consequence of - ( or 'has a relationship with' ) an existing ftp control connection, - thus we want to allow it to let packets - pass the firewall. The <code>RELATED</code> state, however, is only - valid for the very first packet of the outgoing TCP connection for the - ftp data path. Afterwards, the state to compare against is - <code>ESTABLISHED</code>, which then applies equally - to the incoming and outgoing direction. All this is related to the ftp - data traffic originating from TCP port 20 of the VM. This then leads to - the following solution - <span class="since">(since 0.8.5 (QEMU, KVM))</span>: - </p> -<pre> -<filter name='test-eth0'> - <!-- reference the clean traffic filter to prevent - MAC, IP and ARP spoofing. By not providing - and IP address parameter, libvirt will detect the - IP address the VM is using. --> - <filterref filter='clean-traffic'/> - - <!-- enable TCP port 21 (ftp-control) to be reachable --> - <rule action='accept' direction='in'> - <tcp dstportstart='21'/> - </rule> - - <!-- enable TCP port 20 for VM-initiated ftp data connection - related to an existing ftp control connection --> - <rule action='accept' direction='out'> - <tcp srcportstart='20' state='RELATED,ESTABLISHED'/> - </rule> - - <!-- accept all packets from client on the ftp data connection --> - <rule action='accept' direction='in'> - <tcp dstportstart='20' state='ESTABLISHED'/> - </rule> - - <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable --> - <rule action='accept' direction='in'> - <tcp dstportstart='22'/> - </rule> - - <rule action='accept' direction='in'> - <tcp dstportstart='80'/> - </rule> - - <!-- enable general ICMP traffic to be initiated by the VM; - this includes ping traffic --> - <rule action='accept' direction='out'> - <icmp/> - </rule> - - <!-- enable outgoing DNS lookups using UDP --> - <rule action='accept' direction='out'> - <udp dstportstart='53'/> - </rule> - - <!-- drop all other traffic --> - <rule action='drop' direction='inout'> - <all/> - </rule> - -</filter> -</pre> - <p> - Before trying out a filter using the <code>RELATED</code> state, - you have to make sure that the appropriate connection tracking module - has been loaded into the host's kernel. Depending on the version of the - kernel, you must run either one of the following two commands before - the ftp connection with the VM is established. - </p> -<pre> -modprobe nf_conntrack_ftp # where available or - -modprobe ip_conntrack_ftp # if above is not available -</pre> - <p> - If other protocols than ftp are to be used in conjunction with the - <code>RELATED</code> state, their corresponding module must be loaded. - Modules exist at least for the protocols ftp, tftp, irc, sip, - sctp, and amanda. - </p> - <p> - The 2nd solution makes uses the state flags of connections more - than the previous solution did. - In this solution we take advantage of the fact that the - <code>NEW</code> state of a connection is valid when the very - first packet of a traffic flow is seen. Subsequently, if the very first - packet of a flow is accepted, the flow becomes a connection and enters - the <code>ESTABLISHED</code> state. This allows us to write a general - rule for allowing packets of <code>ESTABLISHED</code> connections to - reach the VM or be sent by the VM. - We write specific rules for the very first packets identified by the - <code>NEW</code> state and for which ports they are acceptable. All - packets for ports that are not explicitly accepted will be dropped and - therefore the connection will not go into the <code>ESTABLISHED</code> - state and any subsequent packets be dropped. - </p> - -<pre> -<filter name='test-eth0'> - <!-- reference the clean traffic filter to prevent - MAC, IP and ARP spoofing. By not providing - and IP address parameter, libvirt will detect the - IP address the VM is using. --> - <filterref filter='clean-traffic'/> - - <!-- let the packets of all previously accepted connections reach the VM --> - <rule action='accept' direction='in'> - <all state='ESTABLISHED'/> - </rule> - - <!-- let the packets of all previously accepted and related connections be sent from the VM --> - <rule action='accept' direction='out'> - <all state='ESTABLISHED,RELATED'/> - </rule> - - <!-- enable traffic towards port 21 (ftp), 22 (ssh) and 80 (http) --> - <rule action='accept' direction='in'> - <tcp dstportstart='21' dstportend='22' state='NEW'/> - </rule> - - <rule action='accept' direction='in'> - <tcp dstportstart='80' state='NEW'/> - </rule> - - <!-- enable general ICMP traffic to be initiated by the VM; - this includes ping traffic --> - <rule action='accept' direction='out'> - <icmp state='NEW'/> - </rule> - - <!-- enable outgoing DNS lookups using UDP --> - <rule action='accept' direction='out'> - <udp dstportstart='53' state='NEW'/> - </rule> - - <!-- drop all other traffic --> - <rule action='drop' direction='inout'> - <all/> - </rule> - -</filter> - -</pre> - - <h2><a id="nwflimits">Limitations</a></h2> - <p> - The following sections list (current) limitations of the network - filtering subsystem. - </p> - - <h3><a id="nwflimitsmigr">VM Migration</a></h3> - <p> - VM migration is only supported if the whole filter tree - that is referenced by a virtual machine's top level filter - is also available on the target host. The network filter - <i>clean-traffic</i> - for example should be available on all libvirt installations - of version 0.8.1 or later and thus enable migration of VMs that - for example reference this filter. All other - custom filters must be migrated using higher layer software. It is - outside the scope of libvirt to ensure that referenced filters - on the source system are equivalent to those on the target system - and vice versa. - <br/><br/> - Migration must occur between libvirt installations of version - 0.8.1 or later in order not to lose the network traffic filters - associated with an interface. - </p> - <h3><a id="nwflimitsvlan">VLAN filtering on Linux</a></h3> - <p> - VLAN (802.1Q) packets, if sent by a virtual machine, cannot be filtered - with rules for protocol IDs <code>arp</code>, <code>rarp</code>, - <code>ipv4</code> and <code>ipv6</code> but only - with protocol IDs <code>mac</code> and <code>vlan</code>. Therefore, - the example filter <code>clean-traffic</code> will not work as expected. - </p> - </body> -</html> diff --git a/docs/formatnwfilter.rst b/docs/formatnwfilter.rst new file mode 100644 index 0000000000..434da5b1fd --- /dev/null +++ b/docs/formatnwfilter.rst @@ -0,0 +1,1789 @@ +.. role:: since + +=============== +Network Filters +=============== + +.. contents:: + +This page provides an introduction to libvirt's network filters, their goals, +concepts and XML format. + +Goals and background +-------------------- + +The goal of the network filtering XML is to enable administrators of a +virtualized system to configure and enforce network traffic filtering rules on +virtual machines and manage the parameters of network traffic that virtual +machines are allowed to send or receive. The network traffic filtering rules are +applied on the host when a virtual machine is started. Since the filtering rules +cannot be circumvented from within the virtual machine, it makes them mandatory +from the point of view of a virtual machine user. + +The network filter subsystem allows each virtual machine's network traffic +filtering rules to be configured individually on a per interface basis. The +rules are applied on the host when the virtual machine is started and can be +modified while the virtual machine is running. The latter can be achieved by +modifying the XML description of a network filter. + +Multiple virtual machines can make use of the same generic network filter. When +such a filter is modified, the network traffic filtering rules of all running +virtual machines that reference this filter are updated. + +Network filtering support is available :since:`since 0.8.1 (QEMU, KVM)` + +Concepts +-------- + +The network traffic filtering subsystem enables configuration of network traffic +filtering rules on individual network interfaces that are configured for certain +types of network configurations. Supported network types are + +- ``network`` + +- ``ethernet`` -- must be used in bridging mode + +- ``bridge`` + +The interface XML is used to reference a top-level filter. In the following +example, the interface description references the filter ``clean-traffic``. + +:: + + ... + <devices> + <interface type='bridge'> + <mac address='00:16:3e:5d:c7:9e'/> + <filterref filter='clean-traffic'/> + </interface> + </devices> + ... + +Network filters are written in XML and may either contain references to other +filters, contain rules for traffic filtering, or hold a combination of both. The +above referenced filter ``clean-traffic`` is a filter that only contains +references to other filters and no actual filtering rules. Since references to +other filters can be used, a *tree* of filters can be built. The +``clean-traffic`` filter can be viewed using the command +``virsh nwfilter-dumpxml clean-traffic``. + +As previously mentioned, a single network filter can be referenced by multiple +virtual machines. Since interfaces will typically have individual parameters +associated with their respective traffic filtering rules, the rules described in +a filter XML can be parameterized with variables. In this case, the variable +name is used in the filter XML and the name and value are provided at the place +where the filter is referenced. In the following example, the interface +description has been extended with the parameter ``IP`` and a dotted IP address +as value. + +:: + + ... + <devices> + <interface type='bridge'> + <mac address='00:16:3e:5d:c7:9e'/> + <filterref filter='clean-traffic'> + <parameter name='IP' value='10.0.0.1'/> + </filterref> + </interface> + </devices> + ... + +In this particular example, the ``clean-traffic`` network traffic filter will be +instantiated with the IP address parameter 10.0.0.1 and enforce that the traffic +from this interface will always be using 10.0.0.1 as the source IP address, +which is one of the purposes of this particular filter. + +Filtering chains +~~~~~~~~~~~~~~~~ + +Filtering rules are organized in filter chains. These chains can be thought of +as having a tree structure with packet filtering rules as entries in individual +chains (branches). + +Packets start their filter evaluation in the ``root`` chain and can then +continue their evaluation in other chains, return from those chains back into +the ``root`` chain or be dropped or accepted by a filtering rule in one of the +traversed chains. + +Libvirt's network filtering system automatically creates individual ``root`` +chains for every virtual machine's network interface on which the user chooses +to activate traffic filtering. The user may write filtering rules that are +either directly instantiated in the ``root`` chain or may create +protocol-specific filtering chains for efficient evaluation of protocol-specific +rules. The following chains exist: + +- root + +- mac :since:`(since 0.9.8)` + +- stp (spanning tree protocol) :since:`(since 0.9.8)` + +- vlan (802.1Q) :since:`(since 0.9.8)` + +- arp, rarp + +- ipv4 + +- ipv6 + +:since:`Since 0.9.8` multiple chains evaluating the ``mac``, ``stp``, ``vlan``, +``arp``, ``rarp``, ``ipv4``, or ``ipv6`` protocol can be created using the +protocol name only as a prefix in the chain's name. This for examples allows +chains with names ``arp-xyz`` or ``arp-test`` to be specified and have ARP +protocol packets evaluated in those chains. + +The following filter shows an example of filtering ARP traffic in the ``arp`` +chain. + +:: + + <filter name='no-arp-spoofing' chain='arp' priority='-500'> + <uuid>f88f1932-debf-4aa1-9fbe-f10d3aa4bc95</uuid> + <rule action='drop' direction='out' priority='300'> + <mac match='no' srcmacaddr='$MAC'/> + </rule> + <rule action='drop' direction='out' priority='350'> + <arp match='no' arpsrcmacaddr='$MAC'/> + </rule> + <rule action='drop' direction='out' priority='400'> + <arp match='no' arpsrcipaddr='$IP'/> + </rule> + <rule action='drop' direction='in' priority='450'> + <arp opcode='Reply'/> + <arp match='no' arpdstmacaddr='$MAC'/> + </rule> + <rule action='drop' direction='in' priority='500'> + <arp match='no' arpdstipaddr='$IP'/> + </rule> + <rule action='accept' direction='inout' priority='600'> + <arp opcode='Request'/> + </rule> + <rule action='accept' direction='inout' priority='650'> + <arp opcode='Reply'/> + </rule> + <rule action='drop' direction='inout' priority='1000'/> + </filter> + +The consequence of putting ARP-specific rules in the ``arp`` chain, rather than +for example in the ``root`` chain, is that packets for any other protocol than +ARP do not need to be evaluated by ARP protocol-specific rules. This improves +the efficiency of the traffic filtering. However, one must then pay attention to +only put filtering rules for the given protocol into the chain since any other +rules will not be evaluated, i.e., an IPv4 rule will not be evaluated in the ARP +chain since no IPv4 protocol packets will traverse the ARP chain. + +Filtering chain priorities +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All chains are connected to the ``root`` chain. The order in which those chains +are accessed is influenced by the priority of the chain. The following table +shows the chains that can be assigned a priority and their default priorities. + +============== ================ +Chain (prefix) Default priority +============== ================ +stp -810 +mac -800 +vlan -750 +ipv4 -700 +ipv6 -600 +arp -500 +rarp -400 +============== ================ + +A chain with a lower priority value is accessed before one with a higher value. + +:since:`Since 0.9.8` the above listed chains can be assigned custom priorities +by writing a value in the range [-1000, 1000] into the priority (XML) attribute +in the filter node. The above example filter shows the default priority of -500 +for ``arp`` chains. + +Usage of variables in filters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Two variables names have so far been reserved for usage by the network traffic +filtering subsystem: ``MAC`` and ``IP``. + +``MAC`` is the MAC address of the network interface. A filtering rule that +references this variable will automatically be instantiated with the MAC address +of the interface. This works without the user having to explicitly provide the +MAC parameter. Even though it is possible to specify the MAC parameter similar +to the IP parameter above, it is discouraged since libvirt knows what MAC +address an interface will be using. + +The parameter ``IP`` represents the IP address that the operating system inside +the virtual machine is expected to use on the given interface. The ``IP`` +parameter is special in so far as the libvirt daemon will try to determine the +IP address (and thus the IP parameter's value) that is being used on an +interface if the parameter is not explicitly provided but referenced. For +current limitations on IP address detection, consult the section on +`Limitations`_ on how to use this feature and what to expect when using it. + +The above-shown network filer ``no-arp-spoofing`` is an example of a network +filter XML referencing the ``MAC`` and ``IP`` variables. + +Note that referenced variables are always prefixed with the $ (dollar) sign. The +format of the value of a variable must be of the type expected by the filter +attribute in the XML. In the above example, the ``IP`` parameter must hold a +dotted IP address in decimal numbers format. Failure to provide the correct +value type will result in the filter not being instantiatable and will prevent a +virtual machine from starting or the interface from attaching when hotplugging +is used. The types that are expected for each XML attribute are shown below. + +:since:`Since 0.9.8` variables can contain lists of elements, e.g., the variable +``IP`` can contain multiple IP addresses that are valid on a particular +interface. The notation for providing multiple elements for the IP variable is: + +:: + + ... + <devices> + <interface type='bridge'> + <mac address='00:16:3e:5d:c7:9e'/> + <filterref filter='clean-traffic'> + <parameter name='IP' value='10.0.0.1'/> + <parameter name='IP' value='10.0.0.2'/> + <parameter name='IP' value='10.0.0.3'/> + </filterref> + </interface> + </devices> + ... + +This then allows filters to enable multiple IP addresses per interface. +Therefore, with the list of IP address shown above, the following rule will +create 3 individual filtering rules, one for each IP address. + +:: + + ... + <rule action='accept' direction='in' priority='500'> + <tcp srpipaddr='$IP'/> + </rule> + ... + +:since:`Since 0.9.10` it is possible to access individual elements of a variable +holding a list of elements. A filtering rule like the following accesses the 2nd +element of the variable DSTPORTS. + +:: + + ... + <rule action='accept' direction='in' priority='500'> + <udp dstportstart='$DSTPORTS[1]'/> + </rule> + ... + +:since:`Since 0.9.10` it is possible to create filtering rules that instantiate +all combinations of rules from different lists using the notation of +``$VARIABLE[@<iterator ID>]``. The following rule allows a virtual machine to +receive traffic on a set of ports, which are specified in DSTPORTS, from the set +of source IP address specified in SRCIPADDRESSES. The rule generates all +combinations of elements of the variable DSTPORT with those of SRCIPADDRESSES by +using two independent iterators to access their elements. + +:: + + ... + <rule action='accept' direction='in' priority='500'> + <ip srcipaddr='$SRCIPADDRESSES[@1]' dstportstart='$DSTPORTS[@2]'/> + </rule> + ... + +In an example we assign concrete values to SRCIPADDRESSES and DSTPORTS + +:: + + SRCIPADDRESSES = [ 10.0.0.1, 11.1.2.3 ] + DSTPORTS = [ 80, 8080 ] + +Accessing the variables using $SRCIPADDRESSES[@1] and $DSTPORTS[@2] would then +result in all combinations of addresses and ports being created: + +:: + + 10.0.0.1, 80 + 10.0.0.1, 8080 + 11.1.2.3, 80 + 11.1.2.3, 8080 + +Accessing the same variables using a single iterator, for example by using the +notation $SRCIPADDRESSES[@1] and $DSTPORTS[@1], would result in parallel access +to both lists and result in the following combinations: + +:: + + 10.0.0.1, 80 + 11.1.2.3, 8080 + +Further, the notation of $VARIABLE is short-hand for $VARIABLE[@0]. The former +notation always assumes the iterator with Id '0'. + +Automatic IP address detection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The detection of IP addresses used on a virtual machine's interface is +automatically activated if the variable ``IP`` is referenced but no value has +been assigned to it. :since:`Since 0.9.13` the variable ``CTRL_IP_LEARNING`` can +be used to specify the IP address learning method to use. Valid values are +``any``, ``dhcp``, or ``none``. + +The value ``any`` means that libvirt may use any packet to determine the address +in use by a virtual machine, which is the default behavior if the variable +``CTRL_IP_LEARNING`` is not set. This method will only detect a single IP +address on an interface. Once a VM's IP address has been detected, its IP +network traffic will be locked to that address, if for example IP address +spoofing is prevented by one of its filters. In that case the user of the VM +will not be able to change the IP address on the interface inside the VM, which +would be considered IP address spoofing. When a VM is migrated to another host +or resumed after a suspend operation, the first packet sent by the VM will again +determine the IP address it can use on a particular interface. + +A value of ``dhcp`` specifies that libvirt should only honor DHCP +server-assigned addresses with valid leases. This method supports the detection +and usage of multiple IP address per interface. When a VM is resumed after a +suspend operation, still valid IP address leases are applied to its filters. +Otherwise the VM is expected to again use DHCP to obtain new IP addresses. The +migration of a VM to another physical host requires that the VM again runs the +DHCP protocol. + +Use of ``CTRL_IP_LEARNING=dhcp`` (DHCP snooping) provides additional +anti-spoofing security, especially when combined with a filter allowing only +trusted DHCP servers to assign addresses. To enable this, set the variable +``DHCPSERVER`` to the IP address of a valid DHCP server and provide filters that +use this variable to filter incoming DHCP responses. + +When DHCP snooping is enabled and the DHCP lease expires, the VM will no longer +be able to use the IP address until it acquires a new, valid lease from a DHCP +server. If the VM is migrated, it must get a new valid DHCP lease to use an IP +address (e.g., by bringing the VM interface down and up again). + +Note that automatic DHCP detection listens to the DHCP traffic the VM exchanges +with the DHCP server of the infrastructure. To avoid denial-of-service attacks +on libvirt, the evaluation of those packets is rate-limited, meaning that a VM +sending an excessive number of DHCP packets per second on an interface will not +have all of those packets evaluated and thus filters may not get adapted. Normal +DHCP client behavior is assumed to send a low number of DHCP packets per second. +Further, it is important to setup appropriate filters on all VMs in the +infrastructure to avoid them being able to send DHCP packets. Therefore VMs must +either be prevented from sending UDP and TCP traffic from port 67 to port 68 or +the ``DHCPSERVER`` variable should be used on all VMs to restrict DHCP server +messages to only be allowed to originate from trusted DHCP servers. At the same +time anti-spoofing prevention must be enabled on all VMs in the subnet. + +If ``CTRL_IP_LEARNING`` is set to ``none``, libvirt does not do IP address +learning and referencing ``IP`` without assigning it an explicit value is an +error. + +The following XML provides an example for the activation of IP address learning +using the DHCP snooping method: + +:: + + <interface type='bridge'> + <source bridge='virbr0'/> + <filterref filter='clean-traffic'> + <parameter name='CTRL_IP_LEARNING' value='dhcp'/> + </filterref> + </interface> + +Reserved Variables +~~~~~~~~~~~~~~~~~~ + +The following table lists reserved variables in use by libvirt. + ++------------------+----------------------------------------------------------+ +| Variable Name | Semantics | ++==================+==========================================================+ +| MAC | The MAC address of the interface | ++------------------+----------------------------------------------------------+ +| IP | The list of IP addresses in use by an interface | ++------------------+----------------------------------------------------------+ +| IPV6 | The list of IPV6 addresses in use by an interface | ++------------------+----------------------------------------------------------+ +| DHCPSERVER | The list of IP addresses of trusted DHCP servers | ++------------------+----------------------------------------------------------+ +| DHCPSERVERV6 | Not currently implemented: The list of IPv6 addresses of | +| | trusted DHCP servers | ++------------------+----------------------------------------------------------+ +| CTRL_IP_LEARNING | The choice of the IP address detection mode | ++------------------+----------------------------------------------------------+ + +Element and attribute overview +------------------------------ + +The root element required for all network filters is named ``filter`` with two +possible attributes. The ``name`` attribute provides a unique name of the given +filter. The ``chain`` attribute is optional but allows certain filters to be +better organized for more efficient processing by the firewall subsystem of the +underlying host. Currently the system only supports the chains +``root, ipv4, ipv6, arp and rarp``. + +References to other filters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Any filter may hold references to other filters. Individual filters may be +referenced multiple times in a filter tree but references between filters must +not introduce loops (directed acyclic graph). + +The following shows the XML of the ``clean-traffic`` network filter referencing +several other filters. + +:: + + <filter name='clean-traffic'> + <uuid>6ef53069-ba34-94a0-d33d-17751b9b8cb1</uuid> + <filterref filter='no-mac-spoofing'/> + <filterref filter='no-ip-spoofing'/> + <filterref filter='allow-incoming-ipv4'/> + <filterref filter='no-arp-spoofing'/> + <filterref filter='no-other-l2-traffic'/> + <filterref filter='qemu-announce-self'/> + </filter> + +To reference another filter, the XML node ``filterref`` needs to be provided +inside a ``filter`` node. This node must have the attribute ``filter`` whose +value contains the name of the filter to be referenced. + +New network filters can be defined at any time and may contain references to +network filters that are not known to libvirt, yet. However, once a virtual +machine is started or a network interface referencing a filter is to be +hotplugged, all network filters in the filter tree must be available. Otherwise +the virtual machine will not start or the network interface cannot be attached. + +Filter rules +~~~~~~~~~~~~ + +The following XML shows a simple example of a network traffic filter +implementing a rule to drop traffic if the IP address (provided through the +value of the variable IP) in an outgoing IP packet is not the expected one, thus +preventing IP address spoofing by the VM. + +:: + + <filter name='no-ip-spoofing' chain='ipv4'> + <uuid>fce8ae33-e69e-83bf-262e-30786c1f8072</uuid> + <rule action='drop' direction='out' priority='500'> + <ip match='no' srcipaddr='$IP'/> + </rule> + </filter> + +A traffic filtering rule starts with the ``rule`` node. This node may contain up +to three attributes + +- action -- mandatory; must either be ``drop`` (matching the rule silently + discards the packet with no further analysis), ``reject`` (matching the rule + generates an ICMP reject message with no further analysis) :since:`(since + 0.9.0)` , ``accept`` (matching the rule accepts the packet with no further + analysis), ``return`` (matching the rule passes this filter, but returns + control to the calling filter for further analysis) :since:`(since 0.9.7)` , + or ``continue`` (matching the rule goes on to the next rule for further + analysis) :since:`(since 0.9.7)` . + +- direction -- mandatory; must either be ``in``, ``out`` or ``inout`` if the + rule is for incoming, outgoing or incoming-and-outgoing traffic + +- priority -- optional; the priority of the rule controls the order in which + the rule will be instantiated relative to other rules. Rules with lower value + will be instantiated before rules with higher values. Valid values are in the + range of 0 to 1000. :since:`Since 0.9.8` this has been extended to cover the + range of -1000 to 1000. If this attribute is not provided, priority 500 will + automatically be assigned. + + Note that filtering rules in the ``root`` chain are sorted with filters + connected to the ``root`` chain following their priorities. This allows to + interleave filtering rules with access to filter chains. (See also section on + `Filtering chain priorities`_ .) + +- statematch -- optional; possible values are '0' or 'false' to turn the + underlying connection state matching off; default is 'true' + + Also read the section on `Advanced Filter Configuration Topics`_. + +The above example indicates that the traffic of type ``ip`` will be associated +with the chain 'ipv4' and the rule will have priority 500. If for example +another filter is referenced whose traffic of type ``ip`` is also associated +with the chain 'ipv4' then that filter's rules will be ordered relative to the +priority 500 of the shown rule. + +A rule may contain a single rule for filtering of traffic. The above example +shows that traffic of type ``ip`` is to be filtered. + +Supported protocols +^^^^^^^^^^^^^^^^^^^ + +The following sections enumerate the list of protocols that are supported by the +network filtering subsystem. The type of traffic a rule is supposed to filter on +is provided in the ``rule`` node as a nested node. Depending on the traffic type +a rule is filtering, the attributes are different. The above example showed the +single attribute ``srcipaddr`` that is valid inside the ``ip`` traffic filtering +node. The following sections show what attributes are valid and what type of +data they are expecting. The following datatypes are available: + +- UINT8 : 8 bit integer; range 0-255 + +- UINT16: 16 bit integer; range 0-65535 + +- MAC_ADDR: MAC address in dotted decimal format, i.e., 00:11:22:33:44:55 + +- MAC_MASK: MAC address mask in MAC address format, i.e., FF:FF:FF:FC:00:00 + +- IP_ADDR: IP address in dotted decimal format, i.e., 10.1.2.3 + +- IP_MASK: IP address mask in either dotted decimal format (255.255.248.0) or + CIDR mask (0-32) + +- IPV6_ADDR: IPv6 address in numbers format, i.e., FFFF::1 + +- IPV6_MASK: IPv6 mask in numbers format (FFFF:FFFF:FC00::) or CIDR mask + (0-128) + +- STRING: A string + +- BOOLEAN: 'true', 'yes', '1' or 'false', 'no', '0' + +- IPSETFLAGS: The source and destination flags of the ipset described by up to + 6 'src' or 'dst' elements selecting features from either the source or + destination part of the packet header; example: src,src,dst. The number of + 'selectors' to provide here depends on the type of ipset that is referenced. + +Every attribute except for those of type IP_MASK or IPV6_MASK can be negated +using the ``match`` attribute with value ``no``. Multiple negated attributes may +be grouped together. The following XML fragment shows such an example using +abstract attributes. + +:: + + [...] + <rule action='drop' direction='in'> + <protocol match='no' attribute1='value1' attribute2='value2'/> + <protocol attribute3='value3'/> + </rule> + [...] + +Rules perform a logical AND evaluation on all values of the given protocol +attributes. Thus, if a single attribute's value does not match the one given in +the rule, the whole rule will be skipped during evaluation. Therefore, in the +above example incoming traffic will only be dropped if the protocol property +attribute1 does not match value1 AND the protocol property attribute2 does not +match value2 AND the protocol property attribute3 matches value3. + +MAC (Ethernet) +'''''''''''''' + +Protocol ID: ``mac`` + +Note: Rules of this type should go into the ``root`` chain. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcmacmask | MAC_MASK | Mask applied to MAC | +| | | address of sender | ++-------------------------+-------------------------+-------------------------+ +| dstmacaddr | MAC_ADDR | MAC address of | +| | | destination | ++-------------------------+-------------------------+-------------------------+ +| dstmacmask | MAC_MASK | Mask applied to MAC | +| | | address of destination | ++-------------------------+-------------------------+-------------------------+ +| protocolid | UINT16 (0x600-0xffff), | Layer 3 protocol ID | +| | STRING | | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ + +Valid Strings for ``protocolid`` are: arp, rarp, ipv4, ipv6 + +:: + + [...] + <mac match='no' srcmacaddr='$MAC'/> + [...] + +VLAN (802.1Q) :since:`(Since 0.9.8)` +'''''''''''''''''''''''''''''''''''' + +Protocol ID: ``vlan`` + +Note: Rules of this type should go either into the ``root`` or ``vlan`` chain. + ++----------------+-----------------------------+-----------------------------+ +| Attribute | Datatype | Semantics | ++================+=============================+=============================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++----------------+-----------------------------+-----------------------------+ +| srcmacmask | MAC_MASK | Mask applied to MAC address | +| | | of sender | ++----------------+-----------------------------+-----------------------------+ +| dstmacaddr | MAC_ADDR | MAC address of destination | ++----------------+-----------------------------+-----------------------------+ +| dstmacmask | MAC_MASK | Mask applied to MAC address | +| | | of destination | ++----------------+-----------------------------+-----------------------------+ +| vlanid | UINT16 (0x0-0xfff, 0 - | VLAN ID | +| | 4095) | | ++----------------+-----------------------------+-----------------------------+ +| encap-protocol | UINT16 (0x03c-0xfff), | Encapsulated layer 3 | +| | String | protocol ID | ++----------------+-----------------------------+-----------------------------+ +| comment | STRING | text with max. 256 | +| | | characters | ++----------------+-----------------------------+-----------------------------+ + +Valid Strings for ``encap-protocol`` are: arp, ipv4, ipv6 + +STP (Spanning Tree Protocol) (Since 0.9.8) +'''''''''''''''''''''''''''''''''''''''''' + +Protocol ID: ``stp`` + +Note: Rules of this type should go either into the ``root`` or ``stp`` chain. + +=================== =========== ===================================== +Attribute Datatype Semantics +=================== =========== ===================================== +srcmacaddr MAC_ADDR MAC address of sender +srcmacmask MAC_MASK Mask applied to MAC address of sender +type UINT8 Bridge Protocol Data Unit (BPDU) type +flags UINT8 BPDU flag +root-priority UINT16 Root priority (range start) +root-priority-hi UINT16 Root priority range end +root-address MAC_ADDRESS Root MAC address +root-address-mask MAC_MASK Root MAC address mask +root-cost UINT32 Root path cost (range start) +root-cost-hi UINT32 Root path cost range end +sender-priority UINT16 Sender priority (range start) +sender-priority-hi UINT16 Sender priority range end +sender-address MAC_ADDRESS BPDU sender MAC address +sender-address-mask MAC_MASK BPDU sender MAC address mask +port UINT16 Port identifier (range start) +port_hi UINT16 Port identifier range end +msg-age UINT16 Message age timer (range start) +msg-age-hi UINT16 Message age timer range end +max-age UINT16 Maximum age timer (range start) +max-age-hi UINT16 Maximum age timer range end +hello-time UINT16 Hello time timer (range start) +hello-time-hi UINT16 Hello time timer range end +forward-delay UINT16 Forward delay (range start) +forward-delay-hi UINT16 Forward delay range end +comment STRING text with max. 256 characters +=================== =========== ===================================== + +ARP/RARP +'''''''' + +Protocol ID: ``arp`` or ``rarp`` + +Note: Rules of this type should either go into the ``root`` or ``arp/rarp`` +chain. + ++-----------------------------+----------------+-----------------------------+ +| Attribute | Datatype | Semantics | ++=============================+================+=============================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-----------------------------+----------------+-----------------------------+ +| srcmacmask | MAC_MASK | Mask applied to MAC address | +| | | of sender | ++-----------------------------+----------------+-----------------------------+ +| dstmacaddr | MAC_ADDR | MAC address of destination | ++-----------------------------+----------------+-----------------------------+ +| dstmacmask | MAC_MASK | Mask applied to MAC address | +| | | of destination | ++-----------------------------+----------------+-----------------------------+ +| hwtype | UINT16 | Hardware type | ++-----------------------------+----------------+-----------------------------+ +| protocoltype | UINT16 | Protocol type | ++-----------------------------+----------------+-----------------------------+ +| opcode | UINT16, STRING | Opcode | ++-----------------------------+----------------+-----------------------------+ +| arpsrcmacaddr | MAC_ADDR | Source MAC address in | +| | | ARP/RARP packet | ++-----------------------------+----------------+-----------------------------+ +| arpdstmacaddr | MAC_ADDR | Destination MAC address in | +| | | ARP/RARP packet | ++-----------------------------+----------------+-----------------------------+ +| arpsrcipaddr | IP_ADDR | Source IP address in | +| | | ARP/RARP packet | ++-----------------------------+----------------+-----------------------------+ +| arpsrcipmask :since:`(Since | IP_MASK | Source IP mask | +| 1.2.3)` | | | ++-----------------------------+----------------+-----------------------------+ +| arpdstipaddr | IP_ADDR | Destination IP address in | +| | | ARP/RARP packet | ++-----------------------------+----------------+-----------------------------+ +| arpdstipmask :since:`(Since | IP_MASK | Destination IP mask | +| 1.2.3)` | | | ++-----------------------------+----------------+-----------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-----------------------------+----------------+-----------------------------+ +| gratuitous :since:`(Since | BOOLEAN | boolean indicating whether | +| 0.9.2)` | | to check for gratuitous ARP | +| | | packet | ++-----------------------------+----------------+-----------------------------+ + +Valid strings for the ``Opcode`` field are: Request, Reply, Request_Reverse, +Reply_Reverse, DRARP_Request, DRARP_Reply, DRARP_Error, InARP_Request, ARP_NAK + +IPv4 +'''' + +Protocol ID: ``ip`` + +Note: Rules of this type should either go into the ``root`` or ``ipv4`` chain. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcmacmask | MAC_MASK | Mask applied to MAC | +| | | address of sender | ++-------------------------+-------------------------+-------------------------+ +| dstmacaddr | MAC_ADDR | MAC address of | +| | | destination | ++-------------------------+-------------------------+-------------------------+ +| dstmacmask | MAC_MASK | Mask applied to MAC | +| | | address of destination | ++-------------------------+-------------------------+-------------------------+ +| srcipaddr | IP_ADDR | Source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipmask | IP_MASK | Mask applied to source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipaddr | IP_ADDR | Destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipmask | IP_MASK | Mask applied to | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| protocol | UINT8, STRING | Layer 4 protocol | +| | | identifier | ++-------------------------+-------------------------+-------------------------+ +| srcportstart | UINT16 | Start of range of valid | +| | | source ports; requires | +| | | ``protocol`` | ++-------------------------+-------------------------+-------------------------+ +| srcportend | UINT16 | End of range of valid | +| | | source ports; requires | +| | | ``protocol`` | ++-------------------------+-------------------------+-------------------------+ +| dstportstart | UINT16 | Start of range of valid | +| | | destination ports; | +| | | requires ``protocol`` | ++-------------------------+-------------------------+-------------------------+ +| dstportend | UINT16 | End of range of valid | +| | | destination ports; | +| | | requires ``protocol`` | ++-------------------------+-------------------------+-------------------------+ +| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | +| | 63) | Code Point | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ + +Valid strings for ``protocol`` are: tcp, udp, udplite, esp, ah, icmp, igmp, sctp + +IPv6 +'''' + +Protocol ID: ``ipv6`` + +Note: Rules of this type should either go into the ``root`` or ``ipv6`` chain. + ++--------------------------------+-----------+--------------------------------+ +| Attribute | Datatype | Semantics | ++================================+===========+================================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++--------------------------------+-----------+--------------------------------+ +| srcmacmask | MAC_MASK | Mask applied to MAC address of | +| | | sender | ++--------------------------------+-----------+--------------------------------+ +| dstmacaddr | MAC_ADDR | MAC address of destination | ++--------------------------------+-----------+--------------------------------+ +| dstmacmask | MAC_MASK | Mask applied to MAC address of | +| | | destination | ++--------------------------------+-----------+--------------------------------+ +| srcipaddr | IPV6_ADDR | Source IPv6 address | ++--------------------------------+-----------+--------------------------------+ +| srcipmask | IPV6_MASK | Mask applied to source IPv6 | +| | | address | ++--------------------------------+-----------+--------------------------------+ +| dstipaddr | IPV6_ADDR | Destination IPv6 address | ++--------------------------------+-----------+--------------------------------+ +| dstipmask | IPV6_MASK | Mask applied to destination | +| | | IPv6 address | ++--------------------------------+-----------+--------------------------------+ +| protocol | UINT8 | Layer 4 protocol identifier | ++--------------------------------+-----------+--------------------------------+ +| srcportstart | UINT16 | Start of range of valid source | +| | | ports; requires ``protocol`` | ++--------------------------------+-----------+--------------------------------+ +| srcportend | UINT16 | End of range of valid source | +| | | ports; requires ``protocol`` | ++--------------------------------+-----------+--------------------------------+ +| dstportstart | UINT16 | Start of range of valid | +| | | destination ports; requires | +| | | ``protocol`` | ++--------------------------------+-----------+--------------------------------+ +| dstportend | UINT16 | End of range of valid | +| | | destination ports; requires | +| | | ``protocol`` | ++--------------------------------+-----------+--------------------------------+ +| type :since:`(Since 1.2.12)` | UINT8 | ICMPv6 type; requires | +| | | ``protocol`` to be set to | +| | | ``icmpv6`` | ++--------------------------------+-----------+--------------------------------+ +| typeend :since:`(Since | UINT8 | ICMPv6 type end of range; | +| 1.2.12)` | | requires ``protocol`` to be | +| | | set to ``icmpv6`` | ++--------------------------------+-----------+--------------------------------+ +| code :since:`(Since 1.2.12)` | UINT8 | ICMPv6 code; requires | +| | | ``protocol`` to be set to | +| | | ``icmpv6`` | ++--------------------------------+-----------+--------------------------------+ +| code :since:`(Since 1.2.12)` | UINT8 | ICMPv6 code end of range; | +| | | requires ``protocol`` to be | +| | | set to ``icmpv6`` | ++--------------------------------+-----------+--------------------------------+ +| comment :since:`(Since 0.8.5)` | STRING | text with max. 256 characters | ++--------------------------------+-----------+--------------------------------+ + +Valid strings for ``protocol`` are: tcp, udp, udplite, esp, ah, icmpv6, sctp + +TCP/UDP/SCTP +'''''''''''' + +Protocol ID: ``tcp``, ``udp``, ``sctp`` + +Note: The chain parameter is ignored for this type of traffic and should either +be omitted or set to ``root``. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcipaddr | IP_ADDR | Source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipmask | IP_MASK | Mask applied to source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipaddr | IP_ADDR | Destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipmask | IP_MASK | Mask applied to | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipfrom | IP_ADDR | Start of range of | +| | | source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipto | IP_ADDR | End of range of source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipfrom | IP_ADDR | Start of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipto | IP_ADDR | End of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| srcportstart | UINT16 | Start of range of valid | +| | | source ports | ++-------------------------+-------------------------+-------------------------+ +| srcportend | UINT16 | End of range of valid | +| | | source ports | ++-------------------------+-------------------------+-------------------------+ +| dstportstart | UINT16 | Start of range of valid | +| | | destination ports | ++-------------------------+-------------------------+-------------------------+ +| dstportend | UINT16 | End of range of valid | +| | | destination ports | ++-------------------------+-------------------------+-------------------------+ +| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | +| | 63) | Code Point | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ +| state :since:`(Since | STRING | comma separated list of | +| 0.8.5)` | | NEW,ESTA | +| | | BLISHED,RELATED,INVALID | +| | | or NONE | ++-------------------------+-------------------------+-------------------------+ +| flags :since:`(Since | STRING | TCP-only: format of | +| 0.9.1)` | | mask/flags with mask | +| | | and flags each being a | +| | | comma separated list of | +| | | SYN,ACK,URG,PSH,FIN,RST | +| | | or NONE or ALL | ++-------------------------+-------------------------+-------------------------+ +| ipset :since:`(Since | STRING | The name of an IPSet | +| 0.9.13)` | | managed outside of | +| | | libvirt | ++-------------------------+-------------------------+-------------------------+ +| ipsetflags | IPSETFLAGS | flags for the IPSet; | +| :since:`(Since 0.9.13)` | | requires ipset | +| | | attribute | ++-------------------------+-------------------------+-------------------------+ + +ICMP +'''' + +Protocol ID: ``icmp`` + +Note: The chain parameter is ignored for this type of traffic and should either +be omitted or set to ``root``. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcmacmask | MAC_MASK | Mask applied to MAC | +| | | address of sender | ++-------------------------+-------------------------+-------------------------+ +| dstmacaddr | MAC_ADDR | MAC address of | +| | | destination | ++-------------------------+-------------------------+-------------------------+ +| dstmacmask | MAC_MASK | Mask applied to MAC | +| | | address of destination | ++-------------------------+-------------------------+-------------------------+ +| srcipaddr | IP_ADDR | Source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipmask | IP_MASK | Mask applied to source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipaddr | IP_ADDR | Destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipmask | IP_MASK | Mask applied to | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipfrom | IP_ADDR | Start of range of | +| | | source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipto | IP_ADDR | End of range of source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipfrom | IP_ADDR | Start of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipto | IP_ADDR | End of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| type | UINT16 | ICMP type | ++-------------------------+-------------------------+-------------------------+ +| code | UINT16 | ICMP code | ++-------------------------+-------------------------+-------------------------+ +| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | +| | 63) | Code Point | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ +| state :since:`(Since | STRING | comma separated list of | +| 0.8.5)` | | NEW,ESTA | +| | | BLISHED,RELATED,INVALID | +| | | or NONE | ++-------------------------+-------------------------+-------------------------+ +| ipset :since:`(Since | STRING | The name of an IPSet | +| 0.9.13)` | | managed outside of | +| | | libvirt | ++-------------------------+-------------------------+-------------------------+ +| ipsetflags | IPSETFLAGS | flags for the IPSet; | +| :since:`(Since 0.9.13)` | | requires ipset | +| | | attribute | ++-------------------------+-------------------------+-------------------------+ + +IGMP, ESP, AH, UDPLITE, 'ALL' +''''''''''''''''''''''''''''' + +Protocol ID: ``igmp``, ``esp``, ``ah``, ``udplite``, ``all`` + +Note: The chain parameter is ignored for this type of traffic and should either +be omitted or set to ``root``. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcmacmask | MAC_MASK | Mask applied to MAC | +| | | address of sender | ++-------------------------+-------------------------+-------------------------+ +| dstmacaddr | MAC_ADDR | MAC address of | +| | | destination | ++-------------------------+-------------------------+-------------------------+ +| dstmacmask | MAC_MASK | Mask applied to MAC | +| | | address of destination | ++-------------------------+-------------------------+-------------------------+ +| srcipaddr | IP_ADDR | Source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipmask | IP_MASK | Mask applied to source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipaddr | IP_ADDR | Destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipmask | IP_MASK | Mask applied to | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipfrom | IP_ADDR | Start of range of | +| | | source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipto | IP_ADDR | End of range of source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipfrom | IP_ADDR | Start of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipto | IP_ADDR | End of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | +| | 63) | Code Point | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ +| state :since:`(Since | STRING | comma separated list of | +| 0.8.5)` | | NEW,ESTA | +| | | BLISHED,RELATED,INVALID | +| | | or NONE | ++-------------------------+-------------------------+-------------------------+ +| ipset :since:`(Since | STRING | The name of an IPSet | +| 0.9.13)` | | managed outside of | +| | | libvirt | ++-------------------------+-------------------------+-------------------------+ +| ipsetflags | IPSETFLAGS | flags for the IPSet; | +| :since:`(Since 0.9.13)` | | requires ipset | +| | | attribute | ++-------------------------+-------------------------+-------------------------+ + +TCP/UDP/SCTP over IPV6 +'''''''''''''''''''''' + +Protocol ID: ``tcp-ipv6``, ``udp-ipv6``, ``sctp-ipv6`` + +Note: The chain parameter is ignored for this type of traffic and should either +be omitted or set to ``root``. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcipaddr | IPV6_ADDR | Source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipmask | IPV6_MASK | Mask applied to source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipaddr | IPV6_ADDR | Destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipmask | IPV6_MASK | Mask applied to | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipfrom | IPV6_ADDR | Start of range of | +| | | source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipto | IPV6_ADDR | End of range of source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipfrom | IPV6_ADDR | Start of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipto | IPV6_ADDR | End of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| srcportstart | UINT16 | Start of range of valid | +| | | source ports | ++-------------------------+-------------------------+-------------------------+ +| srcportend | UINT16 | End of range of valid | +| | | source ports | ++-------------------------+-------------------------+-------------------------+ +| dstportstart | UINT16 | Start of range of valid | +| | | destination ports | ++-------------------------+-------------------------+-------------------------+ +| dstportend | UINT16 | End of range of valid | +| | | destination ports | ++-------------------------+-------------------------+-------------------------+ +| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | +| | 63) | Code Point | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ +| state :since:`(Since | STRING | comma separated list of | +| 0.8.5)` | | NEW,ESTA | +| | | BLISHED,RELATED,INVALID | +| | | or NONE | ++-------------------------+-------------------------+-------------------------+ +| flags :since:`(Since | STRING | TCP-only: format of | +| 0.9.1)` | | mask/flags with mask | +| | | and flags each being a | +| | | comma separated list of | +| | | SYN,ACK,URG,PSH,FIN,RST | +| | | or NONE or ALL | ++-------------------------+-------------------------+-------------------------+ +| ipset :since:`(Since | STRING | The name of an IPSet | +| 0.9.13)` | | managed outside of | +| | | libvirt | ++-------------------------+-------------------------+-------------------------+ +| ipsetflags | IPSETFLAGS | flags for the IPSet; | +| :since:`(Since 0.9.13)` | | requires ipset | +| | | attribute | ++-------------------------+-------------------------+-------------------------+ + +ICMPv6 +'''''' + +Protocol ID: ``icmpv6`` + +Note: The chain parameter is ignored for this type of traffic and should either +be omitted or set to ``root``. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcipaddr | IPV6_ADDR | Source IPv6 address | ++-------------------------+-------------------------+-------------------------+ +| srcipmask | IPV6_MASK | Mask applied to source | +| | | IPv6 address | ++-------------------------+-------------------------+-------------------------+ +| dstipaddr | IPV6_ADDR | Destination IPv6 | +| | | address | ++-------------------------+-------------------------+-------------------------+ +| dstipmask | IPV6_MASK | Mask applied to | +| | | destination IPv6 | +| | | address | ++-------------------------+-------------------------+-------------------------+ +| srcipfrom | IPV6_ADDR | Start of range of | +| | | source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipto | IPV6_ADDR | End of range of source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipfrom | IPV6_ADDR | Start of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipto | IPV6_ADDR | End of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| type | UINT16 | ICMPv6 type | ++-------------------------+-------------------------+-------------------------+ +| code | UINT16 | ICMPv6 code | ++-------------------------+-------------------------+-------------------------+ +| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | +| | 63) | Code Point | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ +| state :since:`(Since | STRING | comma separated list of | +| 0.8.5)` | | NEW,ESTA | +| | | BLISHED,RELATED,INVALID | +| | | or NONE | ++-------------------------+-------------------------+-------------------------+ +| ipset :since:`(Since | STRING | The name of an IPSet | +| 0.9.13)` | | managed outside of | +| | | libvirt | ++-------------------------+-------------------------+-------------------------+ +| ipsetflags | IPSETFLAGS | flags for the IPSet; | +| :since:`(Since 0.9.13)` | | requires ipset | +| | | attribute | ++-------------------------+-------------------------+-------------------------+ + +ESP, AH, UDPLITE, 'ALL' over IPv6 +''''''''''''''''''''''''''''''''' + +Protocol ID: ``esp-ipv6``, ``ah-ipv6``, ``udplite-ipv6``, ``all-ipv6`` + +Note: The chain parameter is ignored for this type of traffic and should either +be omitted or set to ``root``. + ++-------------------------+-------------------------+-------------------------+ +| Attribute | Datatype | Semantics | ++=========================+=========================+=========================+ +| srcmacaddr | MAC_ADDR | MAC address of sender | ++-------------------------+-------------------------+-------------------------+ +| srcipaddr | IPV6_ADDR | Source IPv6 address | ++-------------------------+-------------------------+-------------------------+ +| srcipmask | IPV6_MASK | Mask applied to source | +| | | IPv6 address | ++-------------------------+-------------------------+-------------------------+ +| dstipaddr | IPV6_ADDR | Destination IPv6 | +| | | address | ++-------------------------+-------------------------+-------------------------+ +| dstipmask | IPV6_MASK | Mask applied to | +| | | destination IPv6 | +| | | address | ++-------------------------+-------------------------+-------------------------+ +| srcipfrom | IPV6_ADDR | Start of range of | +| | | source IP address | ++-------------------------+-------------------------+-------------------------+ +| srcipto | IPV6_ADDR | End of range of source | +| | | IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipfrom | IPV6_ADDR | Start of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dstipto | IPV6_ADDR | End of range of | +| | | destination IP address | ++-------------------------+-------------------------+-------------------------+ +| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | +| | 63) | Code Point | ++-------------------------+-------------------------+-------------------------+ +| comment :since:`(Since | STRING | text with max. 256 | +| 0.8.5)` | | characters | ++-------------------------+-------------------------+-------------------------+ +| state :since:`(Since | STRING | comma separated list of | +| 0.8.5)` | | NEW,ESTA | +| | | BLISHED,RELATED,INVALID | +| | | or NONE | ++-------------------------+-------------------------+-------------------------+ +| ipset :since:`(Since | STRING | The name of an IPSet | +| 0.9.13)` | | managed outside of | +| | | libvirt | ++-------------------------+-------------------------+-------------------------+ +| ipsetflags | IPSETFLAGS | flags for the IPSet; | +| :since:`(Since 0.9.13)` | | requires ipset | +| | | attribute | ++-------------------------+-------------------------+-------------------------+ + +Advanced Filter Configuration Topics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following sections discuss advanced filter configuration topics. + +Connection tracking +^^^^^^^^^^^^^^^^^^^ + +The network filtering subsystem (on Linux) makes use of the connection tracking +support of iptables. This helps in enforcing the directionality of network +traffic (state match) as well as counting and limiting the number of +simultaneous connections towards a VM. As an example, if a VM has TCP port 8080 +open as a server, clients may connect to the VM on port 8080. Connection +tracking and enforcement of directionality then prevents the VM from initiating +a connection from (TCP client) port 8080 to the host back to a remote host. More +importantly, tracking helps to prevent remote attackers from establishing a +connection back to a VM. For example, if the user inside the VM established a +connection to port 80 on an attacker site, then the attacker will not be able to +initiate a connection from TCP port 80 back towards the VM. By default the +connection state match that enables connection tracking and then enforcement of +directionality of traffic is turned on. + +The following shows an example XML fragment where this feature has been turned +off for incoming connections to TCP port 12345. + +:: + + [...] + <rule direction='in' action='accept' statematch='false'> + <tcp dstportstart='12345'/> + </rule> + [...] + +This now allows incoming traffic to TCP port 12345, but would also enable the +initiation from (client) TCP port 12345 within the VM, which may or may not be +desirable. + +Limiting Number of Connections +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To limit the number of connections a VM may establish, a rule must be provided +that sets a limit of connections for a given type of traffic. If for example a +VM is supposed to be allowed to only ping one other IP address at a time and is +supposed to have only one active incoming ssh connection at a time, the +following XML fragment can be used to achieve this. + +:: + + [...] + <rule action='drop' direction='in' priority='400'> + <tcp connlimit-above='1'/> + </rule> + <rule action='accept' direction='in' priority='500'> + <tcp dstportstart='22'/> + </rule> + <rule action='drop' direction='out' priority='400'> + <icmp connlimit-above='1'/> + </rule> + <rule action='accept' direction='out' priority='500'> + <icmp/> + </rule> + <rule action='accept' direction='out' priority='500'> + <udp dstportstart='53'/> + </rule> + <rule action='drop' direction='inout' priority='1000'> + <all/> + </rule> + [...] + +Note that the rule for the limit has to logically appear before the rule for +accepting the traffic. + +An additional rule for letting DNS traffic to port 22 go out the VM has been +added to avoid ssh sessions not getting established for reasons related to DNS +lookup failures by the ssh daemon. Leaving this rule out may otherwise lead to +fun-filled debugging joy (symptom: ssh client seems to hang while trying to +connect). + +Lot of care must be taken with timeouts related to tracking of traffic. An ICMP +ping that the user may have terminated inside the VM may have a long timeout in +the host's connection tracking system and therefore not allow another ICMP ping +to go through for a while. Therefore, the timeouts have to be tuned in the +host's sysfs, i.e., + +:: + + echo 3 > /proc/sys/net/netfilter/nf_conntrack_icmp_timeout + +sets the ICMP connection tracking timeout to 3 seconds. The effect of this is +that once one ping is terminated, another one can start after 3 seconds. + +Further, we want to point out that a client that for whatever reason has not +properly closed a TCP connection may cause a connection to be held open for a +longer period of time, depending to what timeout the ``TCP established`` state +timeout has been set to on the host. Also, idle connections may time out in the +connection tracking system but can be reactivated once packets are exchanged. +However, a newly initiated connection may force an idle connection into TCP +backoff if the number of allowed connections is set to a too low limit, the new +connection is established and hits (not exceeds) the limit of allowed +connections and for example a key is pressed on the old ssh session, which now +has become unresponsive due to its traffic being dropped. Therefore, the limit +of connections should be rather high so that fluctuations in new TCP connections +don't cause odd traffic behavior in relation to idle connections. + +Command line tools +------------------ + +The libvirt command line tool ``virsh`` has been extended with life-cycle +support for network filters. All commands related to the network filtering +subsystem start with the prefix ``nwfilter``. The following commands are +available: + +- nwfilter-list : list UUIDs and names of all network filters + +- nwfilter-define : define a new network filter or update an existing one + +- nwfilter-undefine : delete a network filter given its name; it must not be + currently in use + +- nwfilter-dumpxml : display a network filter given its name + +- nwfilter-edit : edit a network filter given its name + +Pre-existing network filters +---------------------------- + +The following is a list of example network filters that are automatically +installed with libvirt. + ++---------------------+-------------------------------------------------------+ +| Name | Description | ++=====================+=======================================================+ +| no-arp-spoofing | Prevent a VM from spoofing ARP traffic; this filter | +| | only allows ARP request and reply messages and | +| | enforces that those packets contain the MAC and IP | +| | addresses of the VM. | ++---------------------+-------------------------------------------------------+ +| allow-arp | Allow ARP traffic in both directions | ++---------------------+-------------------------------------------------------+ +| allow-ipv4 | Allow IPv4 traffic in both directions | ++---------------------+-------------------------------------------------------+ +| allow-ipv6 | Allow IPv6 traffic in both directions | ++---------------------+-------------------------------------------------------+ +| allow-incoming-ipv4 | Allow incoming IPv4 traffic | ++---------------------+-------------------------------------------------------+ +| allow-incoming-ipv6 | Allow incoming IPv6 traffic | ++---------------------+-------------------------------------------------------+ +| allow-dhcp | Allow a VM to request an IP address via DHCP (from | +| | any DHCP server) | ++---------------------+-------------------------------------------------------+ +| allow-dhcpv6 | Similar to allow-dhcp, but for DHCPv6 | ++---------------------+-------------------------------------------------------+ +| allow-dhcp-server | Allow a VM to request an IP address from a specified | +| | DHCP server. The dotted decimal IP address of the | +| | DHCP server must be provided in a reference to this | +| | filter. The name of the variable must be | +| | *DHCPSERVER*. | ++---------------------+-------------------------------------------------------+ +| allow-dhcpv6-server | Similar to allow-dhcp-server, but for DHCPv6 | ++---------------------+-------------------------------------------------------+ +| no-ip-spoofing | Prevent a VM from sending of IPv4 packets with a | +| | source IP address different from the one in the | +| | packet. | ++---------------------+-------------------------------------------------------+ +| no-ipv6-spoofing | Similar to no-ip-spoofing, but for IPv6 | ++---------------------+-------------------------------------------------------+ +| no-ip-multicast | Prevent a VM from sending IP multicast packets. | ++---------------------+-------------------------------------------------------+ +| no-ipv6-multicast | Similar to no-ip-multicast, but for IPv6 | ++---------------------+-------------------------------------------------------+ +| clean-traffic | Prevent MAC, IP and ARP spoofing. This filter | +| | references several other filters as building blocks. | ++---------------------+-------------------------------------------------------+ + +Note that most of the above filters are only building blocks and require a +combination with other filters to provide useful network traffic filtering. The +most useful one in the above list is the *clean-traffic* filter. This filter +itself can for example be combined with the *no-ip-multicast* filter to prevent +virtual machines from sending IP multicast traffic on top of the prevention of +packet spoofing. + +Writing your own filters +------------------------ + +Since libvirt only provides a couple of example networking filters, you may +consider writing your own. When planning on doing so there are a couple of +things you may need to know regarding the network filtering subsystem and how it +works internally. Certainly you also have to know and understand the protocols +very well that you want to be filtering on so that no further traffic than what +you want can pass and that in fact the traffic you want to allow does pass. + +The network filtering subsystem is currently only available on Linux hosts and +only works for QEMU and KVM type of virtual machines. On Linux it builds upon +the support for ``ebtables``, ``iptables`` and ``ip6tables`` and makes use of +their features. From the above list of supported protocols the following ones +are implemented using ``ebtables``: + +- mac + +- stp (spanning tree protocol) + +- vlan (802.1Q) + +- arp, rarp + +- ipv4 + +- ipv6 + +All other protocols over IPv4 are supported using iptables, those over IPv6 are +implemented using ip6tables. + +On a Linux host, all traffic filtering instantiated by libvirt's network filter +subsystem first passes through the filtering support implemented by ebtables and +only then through iptables or ip6tables filters. If a filter tree has rules with +the protocols ``mac``, ``stp``, ``vlan`` ``arp``, ``rarp``, ``ipv4``, or +``ipv6`` ebtables rules will automatically be instantiated. + +The role of the ``chain`` attribute in the network filter XML is that internally +a new user-defined ebtables table is created that then for example receives all +``arp`` traffic coming from or going to a virtual machine if the chain ``arp`` +has been specified. Further, a rule is generated in an interface's ``root`` +chain that directs all ipv4 traffic into the user-defined chain. Therefore, all +ARP traffic rules should then be placed into filters specifying this chain. This +type of branching into user-defined tables is only supported with filtering on +the ebtables layer. + +:since:`Since 0.9.8` multiple chains for the same protocol can be created. For +this the name of the chain must have a prefix of one of the previously +enumerated protocols. To create an additional chain for handling of ARP traffic, +a chain with name ``arp-test`` can be specified. + +As an example, it is possible to filter on UDP traffic by source and destination +ports using the ``ip`` protocol filter and specifying attributes for the +protocol, source and destination IP addresses and ports of UDP packets that are +to be accepted. This allows early filtering of UDP traffic with ebtables. +However, once an IP or IPv6 packet, such as a UDP packet, has passed the +ebtables layer and there is at least one rule in a filter tree that instantiates +iptables or ip6tables rules, a rule to let the UDP packet pass will also be +necessary to be provided for those filtering layers. This can be achieved with a +rule containing an appropriate ``udp`` or ``udp-ipv6`` traffic filtering node. + +Example custom filter +~~~~~~~~~~~~~~~~~~~~~ + +As an example we want to now build a filter that fulfills the following list of +requirements: + +- prevents a VM's interface from MAC, IP and ARP spoofing + +- opens only TCP ports 22 and 80 of a VM's interface + +- allows the VM to send ping traffic from an interface but not let the VM be + pinged on the interface + +- allows the VM to do DNS lookups (UDP towards port 53) + +The requirement to prevent spoofing is fulfilled by the existing +``clean-traffic`` network filter, thus we will reference this filter from our +custom filter. + +To enable traffic for TCP ports 22 and 80 we will add 2 rules to enable this +type of traffic. To allow the VM to send ping traffic we will add a rule for +ICMP traffic. For simplicity reasons we allow general ICMP traffic to be +initiated from the VM, not just ICMP echo request and response messages. To then +disallow all other traffic to reach or be initiated by the VM we will then need +to add a rule that drops all other traffic. Assuming our VM is called *test* and +the interface we want to associate our filter with is called *eth0*, we name our +filter *test-eth0*. The result of these considerations is the following network +filter XML: + +:: + + <filter name='test-eth0'> + <!-- reference the clean traffic filter to prevent + MAC, IP and ARP spoofing. By not providing + and IP address parameter, libvirt will detect the + IP address the VM is using. --> + <filterref filter='clean-traffic'/> + + <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable --> + <rule action='accept' direction='in'> + <tcp dstportstart='22'/> + </rule> + + <rule action='accept' direction='in'> + <tcp dstportstart='80'/> + </rule> + + <!-- enable general ICMP traffic to be initiated by the VM; + this includes ping traffic --> + <rule action='accept' direction='out'> + <icmp/> + </rule> + + <!-- enable outgoing DNS lookups using UDP --> + <rule action='accept' direction='out'> + <udp dstportstart='53'/> + </rule> + + <!-- drop all other traffic --> + <rule action='drop' direction='inout'> + <all/> + </rule> + + </filter> + +Note that none of the rules in the above XML contain the IP address of the VM as +either source or destination address, yet the filtering of the traffic works +correctly. The reason is that the evaluation of the rules internally happens on +a per-interface basis and the rules are evaluated based on the knowledge about +which (tap) interface has sent or will receive the packet rather than what their +source or destination IP address may be. + +An XML fragment for a possible network interface description inside the domain +XML of the ``test`` VM could then look like this: + +:: + + [...] + <interface type='bridge'> + <source bridge='mybridge'/> + <filterref filter='test-eth0'/> + </interface> + [...] + +To more strictly control the ICMP traffic and enforce that only ICMP echo +requests can be sent from the VM and only ICMP echo responses be received by the +VM, the above ``ICMP`` rule can be replaced with the following two rules: + +:: + + <!-- enable outgoing ICMP echo requests--> + <rule action='accept' direction='out'> + <icmp type='8'/> + </rule> + + <!-- enable incoming ICMP echo replies--> + <rule action='accept' direction='in'> + <icmp type='0'/> + </rule> + +Second example custom filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this example we now want to build a similar filter as in the example above, +but extend the list of requirements with an ftp server located inside the VM. +Further, we will be using features that have been added in :since:`version +0.8.5` . The requirements for this filter are: + +- prevents a VM's interface from MAC, IP and ARP spoofing + +- opens only TCP ports 22 and 80 of a VM's interface + +- allows the VM to send ping traffic from an interface but not let the VM be + pinged on the interface + +- allows the VM to do DNS lookups (UDP towards port 53) + +- enable an ftp server (in active mode) to be run inside the VM + +The additional requirement of allowing an ftp server to be run inside the VM +maps into the requirement of allowing port 21 to be reachable for ftp control +traffic as well as enabling the VM to establish an outgoing tcp connection +originating from the VM's TCP port 20 back to the ftp client (ftp active mode). +There are several ways of how this filter can be written and we present 2 +solutions. + +The 1st solution makes use of the ``state`` attribute of the TCP protocol that +gives us a hook into the connection tracking framework of the Linux host. For +the VM-initiated ftp data connection (ftp active mode) we use the ``RELATED`` +state that allows us to detect that the VM-initiated ftp data connection is a +consequence of ( or 'has a relationship with' ) an existing ftp control +connection, thus we want to allow it to let packets pass the firewall. The +``RELATED`` state, however, is only valid for the very first packet of the +outgoing TCP connection for the ftp data path. Afterwards, the state to compare +against is ``ESTABLISHED``, which then applies equally to the incoming and +outgoing direction. All this is related to the ftp data traffic originating from +TCP port 20 of the VM. This then leads to the following solution :since:`(since +0.8.5 (QEMU, KVM))` : + +:: + + <filter name='test-eth0'> + <!-- reference the clean traffic filter to prevent + MAC, IP and ARP spoofing. By not providing + and IP address parameter, libvirt will detect the + IP address the VM is using. --> + <filterref filter='clean-traffic'/> + + <!-- enable TCP port 21 (ftp-control) to be reachable --> + <rule action='accept' direction='in'> + <tcp dstportstart='21'/> + </rule> + + <!-- enable TCP port 20 for VM-initiated ftp data connection + related to an existing ftp control connection --> + <rule action='accept' direction='out'> + <tcp srcportstart='20' state='RELATED,ESTABLISHED'/> + </rule> + + <!-- accept all packets from client on the ftp data connection --> + <rule action='accept' direction='in'> + <tcp dstportstart='20' state='ESTABLISHED'/> + </rule> + + <!-- enable TCP ports 22 (ssh) and 80 (http) to be reachable --> + <rule action='accept' direction='in'> + <tcp dstportstart='22'/> + </rule> + + <rule action='accept' direction='in'> + <tcp dstportstart='80'/> + </rule> + + <!-- enable general ICMP traffic to be initiated by the VM; + this includes ping traffic --> + <rule action='accept' direction='out'> + <icmp/> + </rule> + + <!-- enable outgoing DNS lookups using UDP --> + <rule action='accept' direction='out'> + <udp dstportstart='53'/> + </rule> + + <!-- drop all other traffic --> + <rule action='drop' direction='inout'> + <all/> + </rule> + + </filter> + +Before trying out a filter using the ``RELATED`` state, you have to make sure +that the appropriate connection tracking module has been loaded into the host's +kernel. Depending on the version of the kernel, you must run either one of the +following two commands before the ftp connection with the VM is established. + +:: + + modprobe nf_conntrack_ftp # where available or + + modprobe ip_conntrack_ftp # if above is not available + +If other protocols than ftp are to be used in conjunction with the ``RELATED`` +state, their corresponding module must be loaded. Modules exist at least for the +protocols ftp, tftp, irc, sip, sctp, and amanda. + +The 2nd solution makes uses the state flags of connections more than the +previous solution did. In this solution we take advantage of the fact that the +``NEW`` state of a connection is valid when the very first packet of a traffic +flow is seen. Subsequently, if the very first packet of a flow is accepted, the +flow becomes a connection and enters the ``ESTABLISHED`` state. This allows us +to write a general rule for allowing packets of ``ESTABLISHED`` connections to +reach the VM or be sent by the VM. We write specific rules for the very first +packets identified by the ``NEW`` state and for which ports they are acceptable. +All packets for ports that are not explicitly accepted will be dropped and +therefore the connection will not go into the ``ESTABLISHED`` state and any +subsequent packets be dropped. + +:: + + <filter name='test-eth0'> + <!-- reference the clean traffic filter to prevent + MAC, IP and ARP spoofing. By not providing + and IP address parameter, libvirt will detect the + IP address the VM is using. --> + <filterref filter='clean-traffic'/> + + <!-- let the packets of all previously accepted connections reach the VM --> + <rule action='accept' direction='in'> + <all state='ESTABLISHED'/> + </rule> + + <!-- let the packets of all previously accepted and related connections be sent from the VM --> + <rule action='accept' direction='out'> + <all state='ESTABLISHED,RELATED'/> + </rule> + + <!-- enable traffic towards port 21 (ftp), 22 (ssh) and 80 (http) --> + <rule action='accept' direction='in'> + <tcp dstportstart='21' dstportend='22' state='NEW'/> + </rule> + + <rule action='accept' direction='in'> + <tcp dstportstart='80' state='NEW'/> + </rule> + + <!-- enable general ICMP traffic to be initiated by the VM; + this includes ping traffic --> + <rule action='accept' direction='out'> + <icmp state='NEW'/> + </rule> + + <!-- enable outgoing DNS lookups using UDP --> + <rule action='accept' direction='out'> + <udp dstportstart='53' state='NEW'/> + </rule> + + <!-- drop all other traffic --> + <rule action='drop' direction='inout'> + <all/> + </rule> + + </filter> + +Limitations +----------- + +The following sections list (current) limitations of the network filtering +subsystem. + +VM Migration +~~~~~~~~~~~~ + +VM migration is only supported if the whole filter tree that is referenced by a +virtual machine's top level filter is also available on the target host. The +network filter *clean-traffic* for example should be available on all libvirt +installations of version 0.8.1 or later and thus enable migration of VMs that +for example reference this filter. All other custom filters must be migrated +using higher layer software. It is outside the scope of libvirt to ensure that +referenced filters on the source system are equivalent to those on the target +system and vice versa. + +Migration must occur between libvirt installations of version 0.8.1 or later in +order not to lose the network traffic filters associated with an interface. + +VLAN filtering on Linux +~~~~~~~~~~~~~~~~~~~~~~~ + +VLAN (802.1Q) packets, if sent by a virtual machine, cannot be filtered with +rules for protocol IDs ``arp``, ``rarp``, ``ipv4`` and ``ipv6`` but only with +protocol IDs ``mac`` and ``vlan``. Therefore, the example filter +``clean-traffic`` will not work as expected. diff --git a/docs/meson.build b/docs/meson.build index a8e360c8a4..0458eea683 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -21,7 +21,6 @@ docs_html_in_files = [ 'formatcaps', 'formatnetwork', 'formatnode', - 'formatnwfilter', 'index', 'remote', 'storage', @@ -74,6 +73,7 @@ docs_rst_files = [ 'formatdomain', 'formatdomaincaps', 'formatnetworkport', + 'formatnwfilter', 'formatsecret', 'formatsnapshot', 'formatstorage', -- 2.35.1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatcaps.html.in | 222 ---------------------------------------- docs/formatcaps.rst | 197 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 198 insertions(+), 223 deletions(-) delete mode 100644 docs/formatcaps.html.in create mode 100644 docs/formatcaps.rst diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in deleted file mode 100644 index a4abad5d20..0000000000 --- a/docs/formatcaps.html.in +++ /dev/null @@ -1,222 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Driver capabilities XML format</h1> - - <ul id="toc"></ul> - - <h2><a id="elements">Element and attribute overview</a></h2> - - <p>As new virtualization engine support gets added to libvirt, and to - handle cases like QEMU supporting a variety of emulations, a query - interface has been added in 0.2.1 allowing to list the set of supported - virtualization capabilities on the host:</p> - - <pre>char * virConnectGetCapabilities (virConnectPtr conn);</pre> - - <p>The value returned is an XML document listing the virtualization - capabilities of the host and virtualization engine to which - <code>@conn</code> is connected. One can test it using <code>virsh</code> - command line tool command '<code>capabilities</code>', it dumps the XML - associated to the current connection. </p> - - <p>As can be seen in the <a href="#elementExamples">example</a>, the - capabilities XML consists of the <code>capabilities</code> element which - have exactly one <code>host</code> child element to report information on - host capabilities, and zero or more <code>guest</code> element to express - the set of architectures the host can run at the moment.</p> - - - <h3><a id="elementHost">Host capabilities</a></h3> - - <p>The <code><host/></code> element consists of the following child - elements:</p> - <dl> - <dt><code>uuid</code></dt> - <dd>The host UUID.</dd> - - <dt><code>cpu</code></dt> - <dd>The host CPU architecture and features.</dd> - - <dt><code>power_management</code></dt> - <dd>whether host is capable of memory suspend, disk hibernation, or - hybrid suspend.</dd> - - <dt><code>migration_features</code></dt> - <dd>This element exposes information on the hypervisor's migration - capabilities, like live migration, supported URI transports, and so - on.</dd> - - <dt><code>topology</code></dt> - <dd>This element embodies the host internal topology. Management - applications may want to learn this information when orchestrating new - guests - e.g. due to reduce inter-NUMA node transfers. Note that the - <code>sockets</code> value reported here is per-NUMA-node; this is in - contrast to the value given in domain definitions, which is interpreted - as a total number of sockets for the domain.</dd> - - <dt><code>secmodel</code></dt> - <dd>To find out default security labels for different security models you - need to parse this element. In contrast with the former elements, this is - repeated for each security model the libvirt daemon currently supports. - </dd> - </dl> - - - <h3><a id="elementGuest">Guest capabilities</a></h3> - - <p>While the <a href="#elementHost">previous section</a> aims at host - capabilities, this one focuses on capabilities available to a guest - using a given hypervisor. The <code><guest/></code> element will - typically wrap up the following elements:</p> - - <dl> - <dt><code>os_type</code></dt> - <dd>This expresses what kind of operating system the hypervisor - is able to run. Possible values are: - <dl> - <dt><code>xen</code></dt> - <dd>for XEN PV</dd> - - <dt><code>linux</code></dt> - <dd>legacy alias for <code>xen</code></dd> - - <dt><code>xenpvh</code></dt> - <dd>for XEN PVH</dd> - - <dt><code>hvm</code></dt> - <dd>Unmodified operating system</dd> - - <dt><code>exe</code></dt> - <dd>Container based virtualization</dd> - </dl> - </dd> - - <dt><code>arch</code></dt> - <dd>This element brings some information on supported guest - architecture. Possible subelements are: - <dl> - <dt><code>wordsize</code></dt><dd>Size of CPU word in bits, for example 64.</dd> - <dt><code>emulator</code></dt><dd>Emulator (device model) path, for - use in <a href="formatdomain.html#elementEmulator">emulator</a> - element of domain XML.</dd> - <dt><code>loader</code></dt><dd>Loader path, for use in - <a href="formatdomain.html#elementLoader">loader</a> element of domain - XML.</dd> - <dt><code>machine</code></dt><dd>Machine type, for use in - <a href="formatdomain.html#attributeOSTypeMachine">machine</a> - attribute of os/type element in domain XML. For example Xen - supports <code>xenfv</code> for HVM, <code>xenpv</code> for - PV, or <code>xenpvh</code> for PVH.</dd> - <dt><code>domain</code></dt><dd>The <code>type</code> attribute of - this element specifies the type of hypervisor required to run the - domain. Use in <a href="formatdomain.html#attributeDomainType">type</a> - attribute of the domain root element.</dd> - </dl> - </dd> - - <dt><code>features</code></dt> - <dd>This optional element encases possible features that can be used - with a guest of described type. Possible subelements are: - <dl> - <dt><code>pae</code></dt><dd>If present, 32-bit guests can use PAE - address space extensions, <span class="since">since - 0.4.1</span></dd> - <dt><code>nonpae</code></dt><dd>If present, 32-bit guests can be run - without requiring PAE, <span class="since">since - 0.4.1</span></dd> - <dt><code>ia64_be</code></dt><dd>If present, IA64 guests can be run in - big-endian mode, <span class="since">since 0.4.1</span></dd> - <dt><code>acpi</code></dt><dd>If this element is present, - the <code>default</code> attribute describes whether the - hypervisor exposes ACPI to the guest by default, and - the <code>toggle</code> attribute describes whether the - user can override this - default. <span class="since">Since 0.4.1</span></dd> - <dt><code>apic</code></dt><dd>If this element is present, - the <code>default</code> attribute describes whether the - hypervisor exposes APIC to the guest by default, and - the <code>toggle</code> attribute describes whether the - user can override this - default. <span class="since">Since 0.4.1</span></dd> - <dt><code>cpuselection</code></dt><dd>If this element is present, the - hypervisor supports the <code><cpu></code> element - within a domain definition for fine-grained control over - the CPU presented to the - guest. <span class="since">Since 0.7.5</span></dd> - <dt><code>deviceboot</code></dt><dd>If this element is present, - the <code><boot order='...'/></code> element can - be used inside devices, rather than the older boot - specification by category. <span class="since">Since - 0.8.8</span></dd> - <dt><code>disksnapshot</code></dt><dd>If this element is present, - the <code>default</code> attribute describes whether - external disk snapshots are supported. If absent, - external snapshots may still be supported, but it - requires attempting the API and checking for an error to - find out for sure. <span class="since">Since - 1.2.3</span></dd> - </dl> - </dd> - </dl> - - <h3><a id="elementExamples">Examples</a></h3> - - <p>For example, in the case of a 64-bit machine with hardware - virtualization capabilities enabled in the chip and - BIOS you will see:</p> - - <pre><capabilities> - <span style="color: #E50000"><host> - <cpu> - <arch>x86_64</arch> - <features> - <vmx/> - </features> - <model>core2duo</model> - <vendor>Intel</vendor> - <topology sockets="1" dies="1" cores="2" threads="1"/> - <feature name="lahf_lm"/> - <feature name='xtpr'/> - ... - </cpu> - <power_management> - <suspend_mem/> - <suspend_disk/> - <suspend_hybrid/> - </power_management> - </host></span> - - <!-- xen-3.0-x86_64 --> - <span style="color: #0000E5"><guest> - <os_type>xen</os_type> - <arch name="x86_64"> - <wordsize>64</wordsize> - <domain type="xen"></domain> - <emulator>/usr/lib64/xen/bin/qemu-dm</emulator> - </arch> - <features> - </features> - </guest></span> - - <!-- hvm-3.0-x86_32 --> - <span style="color: #00B200"><guest> - <os_type>hvm</os_type> - <arch name="i686"> - <wordsize>32</wordsize> - <domain type="xen"></domain> - <emulator>/usr/lib/xen/bin/qemu-dm</emulator> - <machine>pc</machine> - <machine>isapc</machine> - <loader>/usr/lib/xen/boot/hvmloader</loader> - </arch> - <features> - <cpuselection/> - <deviceboot/> - </features> - </guest></span> - ... -</capabilities></pre> - </body> -</html> diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst new file mode 100644 index 0000000000..abd36692e4 --- /dev/null +++ b/docs/formatcaps.rst @@ -0,0 +1,197 @@ +.. role:: since + +============================== +Driver capabilities XML format +============================== + +.. contents:: + +Element and attribute overview +------------------------------ + +As new virtualization engine support gets added to libvirt, and to handle cases +like QEMU supporting a variety of emulations, a query interface has been added +in 0.2.1 allowing to list the set of supported virtualization capabilities on +the host: + +:: + + char * virConnectGetCapabilities (virConnectPtr conn); + +The value returned is an XML document listing the virtualization capabilities of +the host and virtualization engine to which ```conn`` is connected. One can test +it using ``virsh`` command line tool command '``capabilities``', it dumps the +XML associated to the current connection. + +As can be seen in the `Examples`_, the capabilities XML +consists of the ``capabilities`` element which have exactly one ``host`` child +element to report information on host capabilities, and zero or more ``guest`` +element to express the set of architectures the host can run at the moment. + +Host capabilities +~~~~~~~~~~~~~~~~~ + +The ``<host/>`` element consists of the following child elements: + +``uuid`` + The host UUID. +``cpu`` + The host CPU architecture and features. +``power_management`` + whether host is capable of memory suspend, disk hibernation, or hybrid + suspend. +``migration_features`` + This element exposes information on the hypervisor's migration capabilities, + like live migration, supported URI transports, and so on. +``topology`` + This element embodies the host internal topology. Management applications may + want to learn this information when orchestrating new guests - e.g. due to + reduce inter-NUMA node transfers. Note that the ``sockets`` value reported + here is per-NUMA-node; this is in contrast to the value given in domain + definitions, which is interpreted as a total number of sockets for the + domain. +``secmodel`` + To find out default security labels for different security models you need to + parse this element. In contrast with the former elements, this is repeated + for each security model the libvirt daemon currently supports. + +Guest capabilities +~~~~~~~~~~~~~~~~~~ + +While the previous section (`Host capabilities`_) aims at host capabilities, +this one focuses on capabilities available to a guest using a given hypervisor. +The ``<guest/>`` element will typically wrap up the following elements: + +``os_type`` + This expresses what kind of operating system the hypervisor is able to run. + Possible values are: + + ``xen`` + for XEN PV + ``linux`` + legacy alias for ``xen`` + ``xenpvh`` + for XEN PVH + ``hvm`` + Unmodified operating system + ``exe`` + Container based virtualization +``arch`` + This element brings some information on supported guest architecture. + Possible subelements are: + + ``wordsize`` + Size of CPU word in bits, for example 64. + ``emulator`` + Emulator (device model) path, for use in + `emulator <formatdomain.html#elementEmulator>`__ element of domain XML. + ``loader`` + Loader path, for use in `loader <formatdomain.html#elementLoader>`__ + element of domain XML. + ``machine`` + Machine type, for use in + `machine <formatdomain.html#attributeOSTypeMachine>`__ attribute of + os/type element in domain XML. For example Xen supports ``xenfv`` for HVM, + ``xenpv`` for PV, or ``xenpvh`` for PVH. + ``domain`` + The ``type`` attribute of this element specifies the type of hypervisor + required to run the domain. Use in + `type <formatdomain.html#attributeDomainType>`__ attribute of the domain + root element. +``features`` + This optional element encases possible features that can be used with a guest + of described type. Possible subelements are: + + ``pae`` + If present, 32-bit guests can use PAE address space extensions, + :since:`since 0.4.1` + ``nonpae`` + If present, 32-bit guests can be run without requiring PAE, :since:`since + 0.4.1` + ``ia64_be`` + If present, IA64 guests can be run in big-endian mode, :since:`since + 0.4.1` + ``acpi`` + If this element is present, the ``default`` attribute describes whether + the hypervisor exposes ACPI to the guest by default, and the ``toggle`` + attribute describes whether the user can override this default. + :since:`Since 0.4.1` + ``apic`` + If this element is present, the ``default`` attribute describes whether + the hypervisor exposes APIC to the guest by default, and the ``toggle`` + attribute describes whether the user can override this default. + :since:`Since 0.4.1` + ``cpuselection`` + If this element is present, the hypervisor supports the ``<cpu>`` element + within a domain definition for fine-grained control over the CPU presented + to the guest. :since:`Since 0.7.5` + ``deviceboot`` + If this element is present, the ``<boot order='...'/>`` element can be + used inside devices, rather than the older boot specification by category. + :since:`Since 0.8.8` + ``disksnapshot`` + If this element is present, the ``default`` attribute describes whether + external disk snapshots are supported. If absent, external snapshots may + still be supported, but it requires attempting the API and checking for an + error to find out for sure. :since:`Since 1.2.3` + +Examples +~~~~~~~~ + +For example, in the case of a 64-bit machine with hardware virtualization +capabilities enabled in the chip and BIOS you will see: + +:: + + <capabilities> + <host> + <cpu> + <arch>x86_64</arch> + <features> + <vmx/> + </features> + <model>core2duo</model> + <vendor>Intel</vendor> + <topology sockets="1" dies="1" cores="2" threads="1"/> + <feature name="lahf_lm"/> + <feature name='xtpr'/> + ... + </cpu> + <power_management> + <suspend_mem/> + <suspend_disk/> + <suspend_hybrid/> + </power_management> + </host> + + <!-- xen-3.0-x86_64 --> + <guest> + <os_type>xen</os_type> + <arch name="x86_64"> + <wordsize>64</wordsize> + <domain type="xen"></domain> + <emulator>/usr/lib64/xen/bin/qemu-dm</emulator> + </arch> + <features> + </features> + </guest> + + <!-- hvm-3.0-x86_32 --> + <guest> + <os_type>hvm</os_type> + <arch name="i686"> + <wordsize>32</wordsize> + <domain type="xen"></domain> + <emulator>/usr/lib/xen/bin/qemu-dm</emulator> + <machine>pc</machine> + <machine>isapc</machine> + <loader>/usr/lib/xen/boot/hvmloader</loader> + </arch> + <features> + <cpuselection/> + <deviceboot/> + </features> + </guest> + + ... + </capabilities> diff --git a/docs/meson.build b/docs/meson.build index 0458eea683..196f49a1a0 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -18,7 +18,6 @@ docs_assets = [ ] docs_html_in_files = [ - 'formatcaps', 'formatnetwork', 'formatnode', 'index', @@ -69,6 +68,7 @@ docs_rst_files = [ 'firewall', 'format', 'formatbackup', + 'formatcaps', 'formatcheckpoint', 'formatdomain', 'formatdomaincaps', -- 2.35.1
Additionally hyperlinks in other parts of the documentation are updated to match. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 4 +- docs/formatnetwork.html.in | 1479 ------------------------------------ docs/formatnetwork.rst | 1144 ++++++++++++++++++++++++++++ docs/formatnetworkport.rst | 2 +- docs/manpages/virsh.rst | 5 +- docs/meson.build | 2 +- 6 files changed, 1151 insertions(+), 1485 deletions(-) delete mode 100644 docs/formatnetwork.html.in create mode 100644 docs/formatnetwork.rst diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 552b5364f8..6c4096713a 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5542,7 +5542,7 @@ Quality of service This part of interface XML provides setting quality of service. Incoming and outgoing traffic can be shaped independently. The ``bandwidth`` element and its -child elements are described in the `QoS <formatnetwork.html#elementQoS>`__ +child elements are described in the `QoS <formatnetwork.html#quality-of-service>`__ section of the Network XML. :anchor:`<a id="elementVlanTag"/>` @@ -5746,7 +5746,7 @@ address of the other end of a point-to-point network device :since:`(since :since:`Since 1.2.12` route elements can also be added to define IP routes to add in the guest. The attributes of this element are described in the documentation for the ``route`` element in `network -definitions <formatnetwork.html#elementsStaticroute>`__. This is used by the LXC +definitions <formatnetwork.html#static-routes>`__. This is used by the LXC driver. :: diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in deleted file mode 100644 index 56ff32fbf4..0000000000 --- a/docs/formatnetwork.html.in +++ /dev/null @@ -1,1479 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Network XML format</h1> - - <ul id="toc"> - </ul> - - <p> - This page provides an introduction to the network XML format. For - background information on the concepts referred to here, consult the - <a href="https://wiki.libvirt.org/page/Networking">relevant wiki page</a>. - </p> - - <h2><a id="elements">Element and attribute overview</a></h2> - - <p> - The root element required for all virtual networks is - named <code>network</code> and has no configurable attributes - (although <span class="since">since 0.10.0</span> there is one - optional read-only attribute - when examining the live - configuration of a network, the - attribute <code>connections</code>, if present, specifies the - number of guest interfaces currently connected via this - network). The network XML format is - available <span class="since">since 0.3.0</span> - </p> - - <h3><a id="elementsMetadata">General metadata</a></h3> - - <p> - The first elements provide basic metadata about the virtual - network. - </p> - - <pre> -<network ipv6='yes' trustGuestRxFilters='no'> - <name>default</name> - <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid> - <metadata> - <app1:foo xmlns:app1="http://app1.org/app1/">..</app1:foo>; - <app2:bar xmlns:app2="http://app1.org/app2/">..</app2:bar>; - </metadata> - ...</pre> - - <dl> - <dt><code>name</code></dt> - <dd>The content of the <code>name</code> element provides - a short name for the virtual network. This name should - consist only of alphanumeric characters and is required - to be unique within the scope of a single host. It is - used to form the filename for storing the persistent - configuration file. <span class="since">Since 0.3.0</span></dd> - <dt><code>uuid</code></dt> - <dd>The content of the <code>uuid</code> element provides - a globally unique identifier for the virtual network. - The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>. - If omitted when defining/creating a new network, a random - UUID is generated. <span class="since">Since 0.3.0</span></dd> - <dd>The <code>metadata</code> node can be used by applications to - store custom metadata in the form of XML nodes/trees. Applications - must use custom namespaces on their XML nodes/trees, with only - one top-level element per namespace (if the application needs - structure, they should have sub-elements to their namespace - element). <span class="since">Since 2.1.0</span></dd> - <dt><code>ipv6</code></dt> - <dd>When set to <code>yes</code>, the optional parameter - <code>ipv6</code> enables - a network definition with no IPv6 gateway addresses specified - to have guest-to-guest communications. For further information, - see the example below for the example with no gateway addresses. - <span class="since">Since 1.0.1</span></dd> - <dt><code>trustGuestRxFilters</code></dt> - <dd>The optional parameter <code>trustGuestRxFilters</code> can - be used to set that attribute of the same name for each domain - interface connected to this network (<span class="since">since - 1.2.10</span>). See - the <a href="formatdomain.html#elementsNICS">Network - interfaces</a> section of the domain XML documentation for - more details. Note that an explicit setting of this attribute - in a portgroup or the individual domain interface will - override the setting in the network.</dd> - </dl> - - <h3><a id="elementsConnect">Connectivity</a></h3> - - <p> - The next set of elements control how a virtual network is - provided connectivity to the physical LAN (if at all). - </p> - - <pre> -... -<bridge name="virbr0" stp="on" delay="5" macTableManager="libvirt"/> -<mtu size="9000"/> -<domain name="example.com" localOnly="no"/> -<forward mode="nat" dev="eth0"/> -...</pre> - - <dl> - <dt><code>bridge</code></dt> - <dd>The <code>name</code> attribute on the <code>bridge</code> element - defines the name of a bridge device which will be used to construct - the virtual network. The virtual machines will be connected to this - bridge device allowing them to talk to each other. The bridge device - may also be connected to the LAN. When defining - a new network with a <code><forward></code> mode of - - "nat", "route", or "open" (or an isolated network with - no <code><forward></code> element), libvirt will - automatically generate a unique name for the bridge device if - none is given, and this name will be permanently stored in the - network configuration so that that the same name will be used - every time the network is started. For these types of networks - (nat, route, open, and isolated), a bridge name beginning with the - prefix "virbr" is recommended (and that is what is - auto-generated), but not enforced. - Attribute <code>stp</code> specifies if Spanning Tree Protocol - is 'on' or 'off' (default is - 'on'). Attribute <code>delay</code> sets the bridge's forward - delay value in seconds (default is 0). - <span class="since">Since 0.3.0</span> - - <p> - The <code>macTableManager</code> attribute of the bridge - element is used to tell libvirt how the bridge's MAC address - table (used to determine the correct egress port for packets - based on destination MAC address) will be managed. In the - default <code>kernel</code> setting, the kernel - automatically adds and removes entries, typically using - learning, flooding, and promiscuous mode on the bridge's - ports in order to determine the proper egress port for - packets. When <code>macTableManager</code> is set - to <code>libvirt</code>, libvirt disables kernel management - of the MAC table (in the case of the Linux host bridge, this - means enabling vlan_filtering on the bridge, and disabling - learning and unicast_filter for all bridge ports), and - explicitly adds/removes entries to the table according to - the MAC addresses in the domain interface configurations. - Allowing libvirt to manage the MAC table can improve - performance - with a Linux host bridge, for example, turning - off learning and unicast_flood on ports has its own - performance advantage, and can also lead to an additional - boost by permitting the kernel to automatically turn off - promiscuous mode on some ports of the bridge (in particular, - the port attaching the bridge to the physical - network). However, it can also cause some networking setups - to stop working (e.g. vlan tagging, multicast, - guest-initiated changes to MAC address) and is not supported - by older kernels. - <span class="since">Since 1.2.11, requires kernel 3.17 or - newer</span> - </p> - - <p> - The optional <code>zone</code> attribute of - the <code>bridge</code> element is used to specify - the <a href="https://firewalld.org">firewalld</a> - zone for the bridge of a network with <code>forward</code> - mode of "nat", "route", "open", or one with - no <code>forward</code> specified. By default, the bridges - of all virtual networks with these forward modes are placed - in the firewalld zone named "libvirt", which permits - incoming DNS, DHCP, TFTP, and SSH to the host from guests on - the network. This behavior can be changed either by - modifying the libvirt zone (using firewalld management - tools), or by placing the network in a different zone (which - will also be managed using firewalld tools). - <span class="since">Since 5.1.0</span> - </p> - </dd> - - <dt><code>mtu</code></dt> - <dd> - The <code>size</code> attribute of the <code>mtu></code> - element specifies the Maximum Transmission Unit (MTU) for the - network. <span class="since">Since 3.1.0</span>. In the case - of a libvirt-managed network (one with forward mode - of <code>nat</code>, <code>route</code>, <code>open</code>, or - no <code>forward</code> element (i.e. an isolated network), - this will be the MTU assigned to the bridge device when - libvirt creates it, and thereafter also assigned to all tap - devices created to connect guest interfaces. Network types not - specifically mentioned here don't support having an MTU set in - the libvirt network config. If mtu size is unspecified, the - default setting for the type of device being used is assumed - (usually 1500). - </dd> - - <dt><code>domain</code></dt> - <dd> - The <code>name</code> attribute on the <code>domain</code> - element defines the DNS domain of the DHCP server. This - element is optional, and is only used for those networks with - a <code><forward></code> mode of "nat" or "route" (or an - isolated network with no <code><forward></code> - element). <span class="since">Since 0.4.5</span> - - <p> - If the optional <code>localOnly</code> attribute on the - <code>domain</code> element is "yes", then DNS requests under - this domain will only be resolved by the virtual network's own - DNS server - they will not be forwarded to the host's upstream - DNS server. If <code>localOnly</code> is "no", and by - default, unresolved requests <b>will</b> be forwarded. - <span class="since">Since 1.2.12</span> - </p> - </dd> - <dt><code>forward</code></dt> - <dd>Inclusion of the <code>forward</code> element indicates that - the virtual network is to be connected to the physical - LAN.<span class="since">Since 0.3.0.</span> - The <code>mode</code> attribute determines the method of - forwarding. If there is no <code>forward</code> element, the - network will be isolated from any other network (unless a - guest connected to that network is acting as a router, of - course). The following are valid settings - for <code>mode</code> (if there is a <code>forward</code> - element but mode is not specified, <code>mode='nat'</code> is - assumed): - <dl> - <dt><code>nat</code></dt> - <dd> - All traffic between guests connected to this network and - the physical network will be forwarded to the physical - network via the host's IP routing stack, after the guest's - IP address is translated to appear as the host machine's - public IP address (a.k.a. Network Address Translation, or - "NAT"). This allows multiple guests, all having access to - the physical network, on a host that is only allowed a - single public IP address. If a network has any IPv6 - addresses defined, the IPv6 traffic will be forwarded - using plain routing, since IPv6 has no concept of NAT. - Firewall rules will allow outbound connections to any - other network device whether ethernet, wireless, dialup, - or VPN. If the <code>dev</code> attribute is set, the - firewall rules will restrict forwarding to the named - device only. Inbound connections from other networks are - all prohibited; all connections between guests on the same - network, and to/from the host to the guests, are - unrestricted and not NATed.<span class="since">Since - 0.4.2</span> - - <p><span class="since">Since 1.0.3</span> it is possible to - specify a public IPv4 address and port range to be used for - the NAT by using the <code><nat></code> subelement. - Note that all addresses from the range are used, not just those - that are in use on the host. - The address range is set with the <code><address></code> - subelements and <code>start</code> and <code>stop</code> - attributes: - </p> - <pre> -... - <forward mode='nat'> - <nat> - <address start='1.2.3.4' end='1.2.3.10'/> - </nat> - </forward> -...</pre> - <p> - A single IPv4 address can be set by setting - <code>start</code> and <code>end</code> attributes to - the same value. - </p> - <p> - The port range to be used for the <code><nat></code> can - be set via the subelement <code><port></code>: - </p> - <pre> -... - <forward mode='nat'> - <nat> - <port start='500' end='1000'/> - </nat> - </forward> -...</pre> - - <p> - <span class="since">Since 6.5.0</span> it is possible to - enable NAT with IPv6 networking. As noted above, IPv6 - has historically done plain forwarding and thus to avoid - breaking historical compatibility, IPv6 NAT must be - explicitly requested. - </p> - <pre> -... - <forward mode='nat'> - <nat ipv6='yes'/> - </forward> -...</pre> - </dd> - - <dt><code>route</code></dt> - <dd> - Guest network traffic will be forwarded to the physical - network via the host's IP routing stack, but without - having NAT applied. Again, if the <code>dev</code> - attribute is set, firewall rules will restrict forwarding - to the named device only. This presumes that the local LAN - router has suitable routing table entries to return - traffic to this host. All incoming and outgoing sessions - to guest on these networks are unrestricted. (To restrict - incoming traffic to a guest on a routed network, you can - configure <a href="formatnwfilter.html">nwfilter rules</a> - on the guest's interfaces.) - <span class="since">Since 0.4.2</span> - </dd> - - <dt><code>open</code></dt> - <dd> - As with mode='route', guest network traffic will be - forwarded to the physical network via the host's IP - routing stack, but there will be no firewall rules added - to either enable or prevent any of this traffic. When - forward='open' is set, the <code>dev</code> attribute - cannot be set (because the forward dev is enforced with - firewall rules, and the purpose of forward='open' is to - have a forwarding mode where libvirt doesn't add any - firewall rules). This mode presumes that the local LAN - router has suitable routing table entries to return - traffic to this host, and that some other management - system has been used to put in place any necessary - firewall rules. Although no firewall rules will be added - for the network, it is of course still possible to add - restrictions for specific guests using - <a href="formatnwfilter.html">nwfilter rules</a> on the - guests' interfaces.) - <span class="since">Since 2.2.0</span> - </dd> - - <dt><code>bridge</code></dt> - <dd> - This network describes either 1) an existing host bridge - that was configured outside of libvirt (if - a <code><bridge name='xyz'/></code> element has been - specified, <span class="since">Since 0.9.4</span>), 2) an - existing Open vSwitch bridge that was configured outside of - libvirt (if both a <code><bridge name='xyz'/></code> - element <b>and</b> a <code><virtualport - type='openvswitch'/></code> have been - specified <span class="since">Since 0.10.0</span>) 3) an - interface or group of interfaces to be used for a "direct" - connection via macvtap using macvtap's "bridge" mode (if - the forward element has one or - more <code><interface></code> - subelements, <span class="since">Since 0.9.4</span>) - (see <a href="formatdomain.html#elementsNICSDirect">Direct - attachment to physical interface</a> for descriptions of - the various macvtap modes). libvirt doesn't attempt to - manage the bridge interface at all, thus - the <code><bridge></code> element's <code>stp</code> - and <code>delay</code> attributes are not allowed; no - iptables rules, IP addresses, or DHCP/DNS services are - added; at the IP level, the guest interface appears to be - directly connected to the physical - interface.<span class="since">Since 0.9.4</span> - </dd> - <dt><code>private</code></dt> - <dd> - This network uses a macvtap "direct" connection in - "private" mode to connect each guest to the network. The - physical interface to be used will be picked from among - those listed in <code><interface></code> subelements - of the <code><forward></code> element; when using - 802.1Qbh mode (as indicated by - the <code><virtualport></code> type attribute - note - that this requires an 802.1Qbh-capable hardware switch), - each physical interface can only be in use by a single - guest interface at a time; in modes other than 802.1Qbh, - multiple guest interfaces can share each physical - interface (libvirt will attempt to balance usage between - all available interfaces).<span class="since">Since - 0.9.4</span> - </dd> - <dt><code>vepa</code></dt> - <dd> - This network uses a macvtap "direct" connection in "vepa" - mode to connect each guest to the network (this requires - that the physical interfaces used be connected to a - vepa-capable hardware switch. The physical interface to be - used will be picked from among those listed - in <code><interface></code> subelements of - the <code><forward></code> element; multiple guest - interfaces can share each physical interface (libvirt will - attempt to balance usage between all available - interfaces).<span class="since">Since 0.9.4</span> - </dd> - <dt><code>passthrough</code></dt> - <dd> - This network uses a macvtap "direct" connection in - "passthrough" mode to connect each guest to the network - (note that this is <i>not</i> the same thing as "PCI - passthrough"). The physical interface to be used will be - picked from among those listed - in <code><interface></code> subelements of - the <code><forward></code> element. Each physical - interface can only be in use by a single guest interface - at a time, so libvirt will keep track of which interfaces - are currently in use, and only assign unused interfaces - (if there are no available physical interfaces when a - domain interface is being attached, an error will be - logged, and the operation causing the attach will fail - (usually either a domain start, or a hotplug interface - attach to a domain).<span class="since">Since 0.9.4</span> - </dd> - <dt><code>hostdev</code></dt> - <dd> - This network facilitates PCI Passthrough of a network - device. A network device is chosen from the interface - pool and directly assigned to the guest using generic - device passthrough, after first optionally setting the - device's MAC address and vlan tag to the configured value, - and optionally associating the device with an 802.1Qbh - capable switch using a <code><virtualport></code> - element. Note that - due to limitations in standard - single-port PCI ethernet card driver design - only SR-IOV - (Single Root I/O Virtualization) virtual function (VF) - devices can be assigned in this manner; to assign a - standard single-port PCI or PCIe ethernet card to a guest, - use the traditional <code><hostdev></code> device - definition. <span class="since"> Since 0.10.0</span> - - <p> - To force use of a particular type of device assignment, - a <forward type='hostdev'> interface can have an - optional <code>driver</code> sub-element with - a <code>name</code> attribute set to either "vfio" (VFIO - is a new method of device assignment that is compatible - with UEFI Secure Boot) or "kvm" (the legacy device - assignment handled directly by the KVM kernel module) - <span class="since">Since 1.0.5 (QEMU and KVM only, - requires kernel 3.6 or newer)</span>. When specified, - device assignment will fail if the requested method of - device assignment isn't available on the host. When not - specified, the default is "vfio" on systems where the - VFIO driver is available and loaded, and "kvm" on older - systems, or those where the VFIO driver hasn't been - loaded <span class="since">Since 1.1.3</span> (prior to - that the default was always "kvm"). - </p> - - <p>Note that this "intelligent passthrough" of network - devices is very similar to the functionality of a - standard <code><hostdev></code> device, the - difference being that this method allows specifying a MAC - address, vlan tag, and <code><virtualport></code> - for the passed-through device. If these capabilities are - not required, if you have a standard single-port PCI, - PCIe, or USB network card that doesn't support SR-IOV (and - hence would anyway lose the configured MAC address during - reset after being assigned to the guest domain), or if you - are using a version of libvirt older than 0.10.0, you - should use a standard - <code><hostdev></code> device definition in the - domain's configuration to assign the device to the guest - instead of defining an <code><interface - type='network'></code> pointing to a network - with <code><forward mode='hostdev'/></code>. - </p> - </dd> - </dl> - As mentioned above, a <code><forward></code> element can - have multiple <code><interface></code> subelements, each - one giving the name of a physical interface that can be used - for this network <span class="since">Since 0.9.4</span>: - <pre> -... - <forward mode='passthrough'> - <interface dev='eth10'/> - <interface dev='eth11'/> - <interface dev='eth12'/> - <interface dev='eth13'/> - <interface dev='eth14'/> - </forward> -... - </pre> - <p> - <span class="since">since 0.10.0</span>, - <code><interface></code> also has an optional read-only - attribute - when examining the live configuration of a - network, the attribute <code>connections</code>, if present, - specifies the number of guest interfaces currently connected - via this physical interface. - </p> - <p> - Additionally, <span class="since">since 0.9.10</span>, libvirt - allows a shorthand for specifying all virtual interfaces - associated with a single physical function, by using - the <code><pf></code> subelement to call out the - corresponding physical interface associated with multiple - virtual interfaces: - </p> - <pre> -... - <forward mode='passthrough'> - <pf dev='eth0'/> - </forward> -... - </pre> - - <p>When a guest interface is being constructed, libvirt will pick - an interface from this list to use for the connection. In - modes where physical interfaces can be shared by multiple - guest interfaces, libvirt will choose the interface that - currently has the least number of connections. For those modes - that do not allow sharing of the physical device (in - particular, 'passthrough' mode, and 'private' mode when using - 802.1Qbh), libvirt will choose an unused physical interface - or, if it can't find an unused interface, fail the operation.</p> - - <p> - <span class="since">since 0.10.0</span> When using forward - mode 'hostdev', the interface pool is specified with a list - of <code><address></code> elements, each of which has - <code><type></code> (must always be <code>'pci'</code>), - <code><domain></code>, <code><bus></code>, - <code><slot></code>and <code><function></code> - attributes. - </p> - <pre> -... - <forward mode='hostdev' managed='yes'> - <driver name='vfio'/> - <address type='pci' domain='0' bus='4' slot='0' function='1'/> - <address type='pci' domain='0' bus='4' slot='0' function='2'/> - <address type='pci' domain='0' bus='4' slot='0' function='3'/> - </forward> -... - </pre> - - Alternatively the interface pool can also be defined using a - single physical function <code><pf></code> subelement to - call out the corresponding physical interface associated with - multiple virtual interfaces (similar to passthrough mode): - - <pre> -... - <forward mode='hostdev' managed='yes'> - <pf dev='eth0'/> - </forward> -... - </pre> - - </dd> - </dl> - <h5><a id="elementQoS">Quality of service</a></h5> - -<pre> -... - <forward mode='nat' dev='eth0'/> - <b><bandwidth> - <inbound average='1000' peak='5000' burst='5120'/> - <outbound average='128' peak='256' burst='256'/> - </bandwidth></b> -...</pre> - - <p> - The <code><bandwidth></code> element allows setting - quality of service for a particular network - (<span class="since">since 0.9.4</span>). Setting - <code>bandwidth</code> for a network is supported only - for networks with a <code><forward></code> mode - of <code>route</code>, <code>nat</code>, <code>bridge</code>, - or no mode at all (i.e. an "isolated" network). Setting - <code>bandwidth</code> is <b>not</b> supported for forward modes - <code>passthrough</code>, <code>private</code>, - or <code>hostdev</code>. Attempts to do this will lead to - a failure to define the network or to create a transient network. - </p> - <p> - The <code><bandwidth></code> element can only be a - subelement of a domain's <code><interface></code>, a - subelement of a <code><network></code>, or a subelement of - a <code><portgroup></code> in a <code><network></code>. - </p> - <p> - As a subelement of a domain's <code><interface></code>, - the bandwidth only applies to that one interface of the domain. - As a subelement of a <code><network></code>, the bandwidth - is a total aggregate bandwidth to/from all guest interfaces attached - to that network, <b>not</b> to each guest interface individually. - If a domain's <code><interface></code> has - <code><bandwidth></code> element values higher - than the aggregate for the entire network, then the aggregate - bandwidth for the <code><network></code> takes precedence. - This is because the two choke points are independent of each other - where the domain's <code><interface></code> bandwidth control - is applied on the interface's tap device, while the - <code><network></code> bandwidth control is applied on the - interface part of the bridge device created for that network. - </p> - <p> - As a subelement of a - <code><portgroup></code> in a <code><network></code>, - if a domain's <code><interface></code> has a - <code>portgroup</code> attribute in its - <code><source></code> element <b>and</b> if the - <code><interface></code> - itself has no <code><bandwidth></code> element, then the - <code><bandwidth></code> element of the portgroup will be - applied individually to each guest interface defined to be a - member of that portgroup. Any <code><bandwidth></code> - element in the domain's <code><interface></code> definition - will override the setting in the portgroup - (<span class="since">since 1.0.1</span>). - </p> - <p> - Incoming and outgoing traffic can be shaped independently. The - <code>bandwidth</code> element can have at most one - <code>inbound</code> and at most one <code>outbound</code> - child element. Leaving either of these children elements out - results in no QoS applied for that traffic direction. So, - when you want to shape only incoming traffic, use - <code>inbound</code> only, and vice versa. Each of these - elements have one mandatory attribute - <code>average</code> (or - <code>floor</code> as described below). The attributes are as follows, - where accepted values for each attribute is an integer number. - </p> - <dl> - <dt><code>average</code></dt> - <dd> - Specifies the desired average bit rate for the interface - being shaped (in kilobytes/second). - </dd> - <dt><code>peak</code></dt> - <dd> - Optional attribute which specifies the maximum rate at - which the bridge can send data (in kilobytes/second). - Note the limitation of implementation: this attribute in the - <code>outbound</code> element is ignored (as Linux ingress - filters don't know it yet). - </dd> - <dt><code>burst</code></dt> - <dd> - Optional attribute which specifies the amount of kibibytes that - can be transmitted in a single burst at <code>peak</code> speed. - </dd> - <dt><code>floor</code></dt> - <dd> - Optional attribute available only for the <code>inbound</code> - element. This attribute guarantees minimal throughput for - shaped interfaces. This, however, requires that all traffic - goes through one point where QoS decisions can take place, hence - why this attribute works only for virtual networks for now - (that is <code><interface type='network'/></code> with a - forward type of route, nat, open or no forward at all). Moreover, the - virtual network the interface is connected to is required to have - at least inbound QoS set (<code>average</code> at least). If - using the <code>floor</code> attribute users don't need to specify - <code>average</code>. However, <code>peak</code> and - <code>burst</code> attributes still require <code>average</code>. - Currently, the Linux kernel doesn't allow ingress qdiscs to have - any classes therefore <code>floor</code> can be applied only - on <code>inbound</code> and not <code>outbound</code>. - </dd> - </dl> - - <p> - Attributes <code>average</code>, <code>peak</code>, and - <code>burst</code> are available - <span class="since">since 0.9.4</span>, while the - <code>floor</code> attribute is available - <span class="since">since 1.0.1</span>. - </p> - - <h5><a id="elementVlanTag">Setting VLAN tag (on supported network types only)</a></h5> - -<pre> -<network> - <name>ovs-net</name> - <forward mode='bridge'/> - <bridge name='ovsbr0'/> - <virtualport type='openvswitch'> - <parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/> - </virtualport> - <b><vlan trunk='yes'></b> - <b><tag id='42' nativeMode='untagged'/></b> - <b><tag id='47'/></b> - <b></vlan></b> - <portgroup name='dontpanic'> - <b><vlan></b> - <b><tag id='42'/></b> - <b></vlan></b> - </portgroup> -</network> -</pre> - - <p> - If (and only if) the network connection used by the guest - supports VLAN tagging transparent to the guest, an - optional <code><vlan></code> element can specify one or - more VLAN tags to apply to the guest's network - traffic <span class="since">Since 0.10.0</span>. Network - connections that support guest-transparent VLAN tagging include - 1) type='bridge' interfaces connected to an Open vSwitch bridge - <span class="since">Since 0.10.0</span>, 2) SRIOV Virtual - Functions (VF) used via type='hostdev' (direct device - assignment) <span class="since">Since 0.10.0</span>, and 3) - SRIOV VFs used via type='direct' with mode='passthrough' - (macvtap "passthru" mode) <span class="since">Since - 1.3.5</span>. All other connection types, including standard - linux bridges and libvirt's own virtual networks, <b>do not</b> - support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches - provide their own way (outside of libvirt) to tag guest traffic - onto a specific VLAN. Each tag is given in a - separate <code><tag></code> subelement - of <code><vlan></code> (for example: <code><tag - id='42'/></code>). For VLAN trunking of multiple tags (which - is supported only on Open vSwitch connections), - multiple <code><tag></code> subelements can be specified, - which implies that the user wants to do VLAN trunking on the - interface for all the specified tags. In the case that VLAN - trunking of a single tag is desired, the optional - attribute <code>trunk='yes'</code> can be added to the toplevel - <code><vlan></code> element to differentiate trunking of a - single tag from normal tagging. - </p> - <p> - For network connections using Open vSwitch it is also possible - to configure 'native-tagged' and 'native-untagged' VLAN modes - <span class="since">Since 1.1.0.</span> This is done with the - optional <code>nativeMode</code> attribute on - the <code><tag></code> subelement: <code>nativeMode</code> - may be set to 'tagged' or 'untagged'. The <code>id</code> - attribute of the <code><tag></code> subelement - containing <code>nativeMode</code> sets which VLAN is considered - to be the "native" VLAN for this interface, and - the <code>nativeMode</code> attribute determines whether or not - traffic for that VLAN will be tagged. - </p> - <p> - <code><vlan></code> elements can also be specified in - a <code><portgroup></code> element, as well as directly in - a domain's <code><interface></code> element. In the case - that a vlan tag is specified in multiple locations, the setting - in <code><interface></code> takes precedence, followed by - the setting in the <code><portgroup></code> selected by - the interface config. The <code><vlan></code> - in <code><network></code> will be selected only if none is - given in <code><portgroup></code> - or <code><interface></code>. - </p> - - <h5><a id="elementPort">Isolating ports from one another</a></h5> - -<pre> -<network> - <name>isolated-ports</name> - <forward mode='bridge'/> - <bridge name='br0'/> - <port isolated='yes'/> -</network> -</pre> - - <p> - <span class="since">Since 6.1.0.</span> The <code>port</code> - element property <code>isolated</code>, when set - to <code>yes</code> (default setting is <code>no</code>) is used - to isolate the network traffic of each guest on the network from - all other guests connected to the network; it does not have an - effect on communication between the guests and the host, or - between the guests and destinations beyond this network. This - setting is only supported for networks that use a Linux host - bridge to connect guest interfaces via a standard tap device - (i.e. those with a forward mode of nat, route, open, bridge, or - no forward mode). - </p> - - <h5><a id="elementsPortgroup">Portgroups</a></h5> - -<pre> -... - <forward mode='private'/> - <interface dev="eth20"/> - <interface dev="eth21"/> - <interface dev="eth22"/> - <interface dev="eth23"/> - <interface dev="eth24"/> - </forward> - <b><portgroup name='engineering' default='yes'> - <virtualport type='802.1Qbh'> - <parameters profileid='test'/> - </virtualport> - <bandwidth> - <inbound average='1000' peak='5000' burst='5120'/> - <outbound average='1000' peak='5000' burst='5120'/> - </bandwidth> - </portgroup></b> - <b><portgroup name='sales' trustGuestRxFilters='no'> - <virtualport type='802.1Qbh'> - <parameters profileid='salestest'/> - </virtualport> - <bandwidth> - <inbound average='500' peak='2000' burst='2560'/> - <outbound average='128' peak='256' burst='256'/> - </bandwidth> - </portgroup></b> -...</pre> - - <p> - <span class="since">Since 0.9.4</span> - A portgroup provides a method of easily putting guest - connections to the network into different classes, with each - class potentially having a different level/type of service. - <span class="since">Since 0.9.4</span> Each - network can have multiple portgroup elements (and one of those - can optionally be designated as the 'default' portgroup for the - network), and each portgroup has a name, as well as various - attributes and subelements associated with it. The currently supported - subelements are <code><bandwidth></code> - (described <a href="formatnetwork.html#elementQoS">here</a>) - and <code><virtualport></code> - (documented <a href="formatdomain.html#elementsNICSDirect">here</a>). - If a domain interface definition specifies a portgroup (by - adding a <code>portgroup</code> attribute to - the <code><source></code> subelement), that portgroup's - info will be merged into the interface's configuration. If no - portgroup is given in the interface definition, and one of the - network's portgroups has <code>default='yes'</code>, that - default portgroup will be used. If no portgroup is given in the - interface definition, and there is no default portgroup, then - none will be used. Any <code><bandwidth></code> - - specified directly in the domain XML will take precedence over - any setting in the chosen portgroup. if - a <code><virtualport></code> is specified in the portgroup - (and/or directly in the network definition), the multiple - virtualports will be merged, and any parameter that is specified - in more than one virtualport, and is not identical, will be - considered an error, and will prevent the interface from - starting. - </p> - <p> - portgroups also support the optional - parameter <code>trustGuestRxFilters</code> which can be used to - set that attribute of the same name for each domain interface - using this portgroup (<span class="since">since - 1.2.10</span>). See - the <a href="formatdomain.html#elementsNICS">Network - interfaces</a> section of the domain XML documentation for more - details. Note that an explicit setting of this attribute in the - portgroup overrides the network-wide setting, and an explicit - setting in the individual domain interface will override the - setting in the portgroup. - </p> - - <h5><a id="elementsStaticroute">Static Routes</a></h5> - <p> - Static route definitions are used to provide routing information - to the virtualization host for networks which are not directly - reachable from the virtualization host, but *are* reachable from - a guest domain that is itself reachable from the - host <span class="since">since 1.0.6</span>. - </p> - - <p> - As shown in <a href="formatnetwork.html#examplesNoGateway">this - example</a>, it is possible to define a virtual network - interface with no IPv4 or IPv6 addresses. Such networks are - useful to provide host connectivity to networks which are only - reachable via a guest. A guest with connectivity both to the - guest-only network and to another network that is directly - reachable from the host can act as a gateway between the - networks. A static route added to the "host-visible" network - definition provides the routing information so that IP packets - can be sent from the virtualization host to guests on the hidden - network. - </p> - - <p> - Here is a fragment of a definition which shows the static - route specification as well as the IPv4 and IPv6 definitions - for network addresses which are referred to in the - <code>gateway</code> gateway address specifications. Note - that the third static route specification includes the - <code>metric</code> attribute specification with a value of 2. - This particular route would *not* be preferred if there was - another existing rout on the system with the same address and - prefix but with a lower value for the metric. If there is a - route in the host system configuration that should be overridden - by a route in a virtual network whenever the virtual network is - running, the configuration for the system-defined route should - be modified to have a higher metric, and the route on the - virtual network given a lower metric (for example, the default - metric of "1"). - </p> - - <pre> -... - <ip address="192.168.122.1" netmask="255.255.255.0"> - <dhcp> - <range start="192.168.122.128" end="192.168.122.254"/> - </dhcp> - </ip> - <route address="192.168.222.0" prefix="24" gateway="192.168.122.2"/> - <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/> - <route family="ipv6" address="2001:db8:ca2:3::" prefix="64" gateway="2001:db8:ca2:2::2"/> - <route family="ipv6" address="2001:db9:4:1::" prefix="64" gateway="2001:db8:ca2:2::3" metric='2'/> -... - </pre> - - <h3><a id="elementsAddress">Addressing</a></h3> - - <p> - The final set of elements define the addresses (IPv4 and/or - IPv6, as well as MAC) to be assigned to the bridge device - associated with the virtual network, and optionally enable DHCP - services. These elements are only valid for isolated networks - (no <code>forward</code> element specified), and for those with - a forward mode of 'route' or 'nat'. - </p> - - <pre> -... -<mac address='00:16:3E:5D:C7:9E'/> -<domain name="example.com"/> -<dns> - <txt name="example" value="example value"/> - <forwarder addr="8.8.8.8"/> - <forwarder domain='example.com' addr="8.8.4.4"/> - <forwarder domain='www.example.com'/> - <srv service='name' protocol='tcp' domain='test-domain-name' target='.' - port='1024' priority='10' weight='10'/> - <host ip='192.168.122.2'> - <hostname>myhost</hostname> - <hostname>myhostalias</hostname> - </host> -</dns> -<ip address="192.168.122.1" netmask="255.255.255.0" localPtr="yes"> - <dhcp> - <range start="192.168.122.100" end="192.168.122.254"> - <lease expiry='1' unit='hours'/> - </range> - <host mac="00:16:3e:77:e2:ed" name="foo.example.com" ip="192.168.122.10"> - <lease expiry='30' unit='minutes'/> - </host> - <host mac="00:16:3e:3e:a9:1a" name="bar.example.com" ip="192.168.122.11"/> - </dhcp> -</ip> -<ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64" localPtr="yes"/> -<route family="ipv6" address="2001:db9:ca1:1::" prefix="64" gateway="2001:db8:ca2:2::2"/> -</pre> - - <dl> - <dt><code>mac</code></dt> - <dd>The <code>address</code> attribute defines a MAC - (hardware) address formatted as 6 groups of 2-digit - hexadecimal numbers, the groups separated by colons - (eg, <code>"52:54:00:1C:DA:2F"</code>). This MAC address is - assigned to the bridge device when it is created. Generally - it is best to not specify a MAC address when creating a - network - in this case, if a defined MAC address is needed for - proper operation, libvirt will automatically generate a random - MAC address and save it in the config. Allowing libvirt to - generate the MAC address will assure that it is compatible - with the idiosyncrasies of the platform where libvirt is - running. <span class="since">Since 0.8.8</span> - </dd> - <dt><code>dns</code></dt> - <dd> The dns element of a network contains configuration - information for the virtual network's DNS - server <span class="since">Since 0.9.3</span>. - - <p> - The dns element can have an optional <code>enable</code> - attribute <span class="since">Since 2.2.0</span>. - If <code>enable</code> is "no", then no DNS server will be - setup by libvirt for this network (and any other - configuration in <code><dns></code> will be ignored). - If <code>enable</code> is "yes" or unspecified (including - the complete absence of any <code><dns></code> - element) then a DNS server will be setup by libvirt to - listen on all IP addresses specified in the network's - configuration. - </p> - <p> - The dns element - can have an optional <code>forwardPlainNames</code> - attribute <span class="since">Since 1.1.2</span>. - If <code>forwardPlainNames</code> is "no", then DNS resolution - requests for names that are not qualified with a domain - (i.e. names with no "." character) will not be forwarded to - the host's upstream DNS server - they will only be resolved if - they are known locally within the virtual network's own DNS - server. If <code>forwardPlainNames</code> is "yes", - unqualified names <b>will</b> be forwarded to the upstream DNS - server if they can't be resolved by the virtual network's own - DNS server. - </p> - - Currently supported sub-elements of <code><dns></code> are: - <dl> - <dt><code>forwarder</code></dt> - <dd>The dns element can have 0 or - more <code><forwarder></code> elements. Each - forwarder element defines an alternate DNS server to use - for some, or all, DNS requests sent to this network's DNS - server. There are two attributes - <code>domain</code>, - and <code>addr</code>; at least one of these must be - specified in any <code><forwarder></code> - element. If both <code>domain</code> and <code>addr</code> - are specified, then all requests that match the given - domain will be forwarded to the DNS server at addr. If - only <code>domain</code> is specified, then all matching - domains will be resolved locally (or via the host's - standard DNS forwarding if they can't be resolved - locally). If an <code>addr</code> is specified by itself, - then all DNS requests to the network's DNS server will be - forwarded to the DNS server at that address with no - exceptions. <code>addr</code> <span class="since">Since - 1.1.3</span>, <code>domain</code> <span class="since">Since - 2.2.0</span>. - </dd> - <dt><code>txt</code></dt> - <dd>A <code>dns</code> element can have 0 or more <code>txt</code> elements. - Each txt element defines a DNS TXT record and has two attributes, both - required: a name that can be queried via dns, and a value that will be - returned when that name is queried. names cannot contain embedded spaces - or commas. value is a single string that can contain multiple values - separated by commas. <span class="since">Since 0.9.3</span> - </dd> - <dt><code>host</code></dt> - <dd>The <code>host</code> element within <code>dns</code> is the - definition of DNS hosts to be passed to the DNS service. The IP - address is identified by the <code>ip</code> attribute and the names - for that IP address are identified in the <code>hostname</code> - sub-elements of the <code>host</code> element. - <span class="since">Since 0.9.3</span> - </dd> - </dl> - <dl> - <dt><code>srv</code></dt> - <dd>The <code>dns</code> element can have also 0 or more <code>srv</code> - record elements. Each <code>srv</code> record element defines a DNS SRV record - and has 2 mandatory and 5 optional attributes. The mandatory attributes - are <code>service</code> and <code>protocol</code> (tcp, udp) - and the optional attributes are <code>target</code>, - <code>port</code>, <code>priority</code>, <code>weight</code> and - <code>domain</code> as defined in DNS server SRV RFC (RFC 2782). - <span class="since">Since 0.9.9</span> - </dd> - </dl> - </dd> - <dt><code>ip</code></dt> - <dd>The <code>address</code> attribute defines an IPv4 address in - dotted-decimal format, or an IPv6 address in standard colon-separated - hexadecimal format, that will be configured on the bridge device - associated with the virtual network. To the guests this IPv4 address - will be their IPv4 default route. For IPv6, the default route is - established via Router Advertisement. For IPv4 addresses, the - <code>netmask</code> attribute defines the significant bits of the - network address, again specified in dotted-decimal format. For IPv6 - addresses, and as an alternate method for IPv4 addresses, the - significant bits of the network address can be specified with the - <code>prefix</code> attribute, which is an integer (for example, - <code>netmask='255.255.255.0'</code> could also be given as - <code>prefix='24'</code>). The <code>family</code> attribute is used - to specify the type of address - <code>ipv4</code> or - <code>ipv6</code>; if no <code>family</code> is given, - <code>ipv4</code> is assumed. More than one address of each family can - be defined for a network. The optional <code>localPtr</code> attribute - (<span class="since">since 3.0.0</span>) configures the DNS server to - not forward any reverse DNS requests for IP addresses from the network - configured by the <code>address</code> and - <code>netmask</code>/<code>prefix</code> attributes. For some unusual - network prefixes (not divisible by 8 for IPv4 or not divisible by 4 for - IPv6) libvirt may be unable to compute the PTR domain automatically. - The <code>ip</code> element is supported <span class="since">since - 0.3.0</span>. IPv6, multiple addresses on a single network, - <code>family</code>, and <code>prefix</code> are supported - <span class="since">since 0.8.7</span>. The <code>ip</code> element may - contain the following elements: - - <dl> - <dt><code>tftp</code></dt> - <dd>The optional <code>tftp</code> element and its mandatory - <code>root</code> attribute enable TFTP services. The attribute - specifies the path to the root directory served via TFTP. The - <code>tftp</code> element is not supported for IPv6 addresses, - and can only be specified on a single IPv4 address per network. - <span class="since">Since 0.7.1</span> - </dd> - - <dt><code>dhcp</code></dt> - <dd>The presence of this element enables DHCP services on the - virtual network. The <code>dhcp</code> element is supported for - both IPv4 (<span class="since">since 0.3.0</span>) and IPv6 - (<span class="since">since 1.0.1</span>), but only for one IP - address of each type per network. The following sub-elements are - supported: - <dl> - <dt><code>range</code></dt> - <dd>The <code>start</code> and <code>end</code> attributes on the - <code>range</code> element specify the boundaries of a pool of - addresses to be provided to DHCP clients. These two addresses - must lie within the scope of the network defined on the parent - <code>ip</code> element. There may be zero or more - <code>range</code> elements specified. - <span class="since">Since 0.3.0</span> - </dd> - <dt><code>host</code></dt> - <dd>Within the <code>dhcp</code> element there may be zero or - more <code>host</code> elements. These specify hosts which will - be given names and predefined IP addresses by the built-in DHCP - server. Any IPv4 <code>host</code> element must specify the MAC - address of the host to be assigned a given name (via the - <code>mac</code> attribute), the IP to be assigned to that host - (via the <code>ip</code> attribute), and the name itself (the - <code>name</code> attribute). The IPv6 <code>host</code> - element differs slightly from that for IPv4: there is no - <code>mac</code> attribute since a MAC address has no defined - meaning in IPv6. Instead, the <code>name</code> attribute is - used to identify the host to be assigned the IPv6 address. For - DHCPv6, the name is the plain name of the client host sent by the - client to the server. Note that this method of assigning a - specific IP address can also be used for IPv4 instead of the - <code>mac</code> attribute. - <span class="since">Since 0.4.5</span> - </dd> - <dt><code>bootp</code></dt> - <dd>The optional <code>bootp</code> element specifies BOOTP - options to be provided by the DHCP server for IPv4 only. Two - attributes are supported: <code>file</code> is mandatory and - gives the file to be used for the boot image; - <code>server</code> is optional and gives the address of the - TFTP server from which the boot image will be fetched. - <code>server</code> defaults to the same host that runs the - DHCP server, as is the case when the <code>tftp</code> element - is used. The BOOTP options currently have to be the same for - all address ranges and statically assigned addresses. <span - class="since">Since 0.7.1</span> (<code>server</code> - <span class="since">since 0.7.3</span>) - </dd> - </dl> - - <p> - Optionally, <code>range</code> and <code>host</code> elements can - have <code>lease</code> child element which specifies the lease - time through it's attributes <code>expiry</code> and - <code>unit</code> (which accepts <code>seconds</code>, - <code>minutes</code> and <code>hours</code> and defaults to - <code>minutes</code> if omitted). The minimal lease time is 2 - minutes, except when setting an infinite lease time - (<code>expiry='0'</code>). - <span class="since">Since 6.3.0</span> - </p> - - </dd> - </dl> - </dd> - </dl> - - <h3><a id="elementsNamespaces">Network namespaces</a></h3> - - <p> - A special XML namespace is available for passing options - directly to the underlying dnsmasq configuration - file <span class="since">since 5.6.0</span>. Usage of XML - namespaces comes with no support guarantees, so use at your own - risk. - </p> - - <p> - This example XML will pass the option strings <code>foo=bar</code> and - <code>cname=*.foo.example.com,master.example.com</code> directly to the - underlying dnsmasq instance. - <pre> -<network xmlns:dnsmasq='http://libvirt.org/schemas/network/dnsmasq/1.0'>; - ... - <dnsmasq:options> - <dnsmasq:option value="foo=bar"/> - <dnsmasq:option value="cname=*.foo.example.com,master.example.com"/> - </dnsmasq:options> -</network></pre> - </p> - - <h2><a id="examples">Example configuration</a></h2> - - <h3><a id="examplesNAT">NAT based network</a></h3> - - <p> - This example is the so called "default" virtual network. It is - provided and enabled out-of-the-box for all libvirt installations. - This is a configuration that allows guest OS to get outbound - connectivity regardless of whether the host uses ethernet, wireless, - dialup, or VPN networking without requiring any specific admin - configuration. In the absence of host networking, it at least allows - guests to talk directly to each other. - </p> - - <pre> -<network> - <name>default</name> - <bridge name="virbr0"/> - <forward mode="nat"/> - <ip address="192.168.122.1" netmask="255.255.255.0"> - <dhcp> - <range start="192.168.122.2" end="192.168.122.254"/> - </dhcp> - </ip> - <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/> -</network></pre> - - - <p> - Below is a variation of the above example which adds an IPv6 - dhcp range definition. - </p> - - <pre> -<network> - <name>default6</name> - <bridge name="virbr0"/> - <forward mode="nat"/> - <ip address="192.168.122.1" netmask="255.255.255.0"> - <dhcp> - <range start="192.168.122.2" end="192.168.122.254"/> - </dhcp> - </ip> - <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"> - <dhcp> - <range start="2001:db8:ca2:2:1::10" end="2001:db8:ca2:2:1::ff"/> - </dhcp> - </ip> -</network></pre> - - <h3><a id="examplesNATv6">IPv6 NAT based network</a></h3> - - <p> - Below is a variation for also providing IPv6 NAT. This can be - especially useful when using multiple interfaces where some, - such as WiFi cards, can not be bridged (usually on a laptop), - making it difficult to provide end-to-end IPv6 routing. - </p> - - <pre> -<network> - <name>default6</name> - <bridge name="virbr0"/> - <forward mode="nat"> - <nat ipv6='yes'> - <port start='1024' end='65535'/> - </nat> - - <ip address="192.168.122.1" netmask="255.255.255.0"> - <dhcp> - <range start="192.168.122.2" end="192.168.122.254"/> - </dhcp> - </ip> - <ip family="ipv6" address="fdXX:XXXX:XXXX:NNNN:: prefix="64"/> -</network></pre> - - <p>IPv6 NAT addressing has some caveats over the more straight - forward IPv4 case. - <a href="https://tools.ietf.org/html/rfc4193">RFC 4193</a> - defines the address range <tt>fd00::/8</tt> for <tt>/48</tt> IPv6 - private networks. It should be concatenated with a random 40-bit - string (i.e. 10 random hexadecimal digits replacing the <tt>X</tt> - values above, RFC 4193 provides - an <a href="https://tools.ietf.org/html/rfc4193#section-3.2.2">algorithm</a> - if you do not have a source of sufficient randomness). This - leaves <tt>0</tt> through <tt>ffff</tt> for subnets (<tt>N</tt> - above) which you can use at will.</p> - - <p>Many operating systems will not consider these addresses as - preferential to IPv4, due to some practical history of these - addresses being present but unroutable and causing networking - issues. On many Linux distributions, you may need to - override <tt>/etc/gai.conf</tt> with values - from <a href="https://www.ietf.org/rfc/rfc3484.txt">RFC 3484</a> - to have your IPv6 NAT network correctly preferenced over IPv4.</p> - - <h3><a id="examplesRoute">Routed network config</a></h3> - - <p> - This is a variant on the default network which routes traffic - from the virtual network to the LAN without applying any NAT. - It requires that the IP address range be pre-configured in the - routing tables of the router on the host network. This example - further specifies that guest traffic may only go out via the - <code>eth1</code> host network device. - </p> - - <pre> -<network> - <name>local</name> - <bridge name="virbr1"/> - <forward mode="route" dev="eth1"/> - <ip address="192.168.122.1" netmask="255.255.255.0"> - <dhcp> - <range start="192.168.122.2" end="192.168.122.254"/> - </dhcp> - </ip> - <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/> -</network></pre> - - <p> - Below is another IPv6 variation. Instead of a dhcp range being - specified, this example has a couple of IPv6 host definitions. - Note that most of the dhcp host definitions use an "id" (client - id or DUID) since this has proven to be a more reliable way - of specifying the interface and its association with an IPv6 - address. The first is a DUID-LLT, the second a DUID-LL, and - the third a DUID-UUID. <span class="since">Since 1.0.3</span> - </p> - - <pre> -<network> - <name>local6</name> - <bridge name="virbr1"/> - <forward mode="route" dev="eth1"/> - <ip address="192.168.122.1" netmask="255.255.255.0"> - <dhcp> - <range start="192.168.122.2" end="192.168.122.254"/> - </dhcp> - </ip> - <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"> - <dhcp> - <host name="paul" ip="2001:db8:ca2:2:3::1"/> - <host id="0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip="2001:db8:ca2:2:3::2"/> - <host id="0:3:0:1:0:16:3e:11:22:33" name="ralph" ip="2001:db8:ca2:2:3::3"/> - <host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63" - name="badbob" ip="2001:db8:ca2:2:3::4"/> - </dhcp> - </ip> -</network></pre> - - <p> - Below is yet another IPv6 variation. This variation has only - IPv6 defined with DHCPv6 on the primary IPv6 network. A static - link if defined for a second IPv6 network which will not be - directly visible on the bridge interface but there will be a - static route defined for this network via the specified - gateway. Note that the gateway address must be directly - reachable via (on the same subnet as) one of the <ip> - addresses defined for this <network>. - <span class="since">Since 1.0.6</span> - </p> - - <pre> -<network> - <name>net7</name> - <bridge name="virbr7"/> - <forward mode="route"/> - <ip family="ipv6" address="2001:db8:ca2:7::1" prefix="64"> - <dhcp> - <range start="2001:db8:ca2:7::100" end="2001:db8:ca2::1ff"/> - <host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63" - name="lucas" ip="2001:db8:ca2:2:3::4"/> - </dhcp> - </ip> - <route family="ipv6" address="2001:db8:ca2:8::" prefix="64" gateway="2001:db8:ca2:7::4"/> -</network></pre> - - <h3><a id="examplesPrivate">Isolated network config</a></h3> - - <p> - This variant provides a completely isolated private network - for guests. The guests can talk to each other, and the host - OS, but cannot reach any other machines on the LAN, due to - the omission of the <code>forward</code> element in the XML - description. - </p> - - <pre> -<network> - <name>private</name> - <bridge name="virbr2"/> - <ip address="192.168.152.1" netmask="255.255.255.0"> - <dhcp> - <range start="192.168.152.2" end="192.168.152.254"/> - </dhcp> - </ip> - <ip family="ipv6" address="2001:db8:ca2:3::1" prefix="64"/> -</network></pre> - - <h3><a id="examplesPrivate6">Isolated IPv6 network config</a></h3> - - <p> - This variation of an isolated network defines only IPv6. - Note that most of the dhcp host definitions use an "id" (client - id or DUID) since this has proven to be a more reliable way - of specifying the interface and its association with an IPv6 - address. The first is a DUID-LLT, the second a DUID-LL, and - the third a DUID-UUID. <span class="since">Since 1.0.3</span> - </p> - - <pre> -<network> - <name>sixnet</name> - <bridge name="virbr6"/> - <ip family="ipv6" address="2001:db8:ca2:6::1" prefix="64"> - <dhcp> - <host name="peter" ip="2001:db8:ca2:6:6::1"/> - <host id="0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip="2001:db8:ca2:6:6::2"/> - <host id="0:3:0:1:0:16:3e:11:22:33" name="dariusz" ip="2001:db8:ca2:6:6::3"/> - <host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63" - name="anita" ip="2001:db8:ca2:6:6::4"/> - </dhcp> - </ip> -</network></pre> - - <h3><a id="examplesBridge">Using an existing host bridge</a></h3> - - <p> - <span class="since">Since 0.9.4</span> - This shows how to use a pre-existing host bridge "br0". The - guests will effectively be directly connected to the physical - network (i.e. their IP addresses will all be on the subnet of - the physical network, and there will be no restrictions on - inbound or outbound connections). - </p> - - <pre> -<network> - <name>host-bridge</name> - <forward mode="bridge"/> - <bridge name="br0"/> -</network></pre> - - <h3><a id="examplesDirect">Using a macvtap "direct" connection</a></h3> - - <p> - <span class="since">Since 0.9.4, QEMU and KVM only, requires - Linux kernel 2.6.34 or newer</span> - This shows how to use macvtap to connect to the physical network - directly through one of a group of physical devices (without - using a host bridge device). As with the host bridge network, - the guests will effectively be directly connected to the - physical network so their IP addresses will all be on the subnet - of the physical network, and there will be no restrictions on - inbound or outbound connections. Note that, due to a limitation - in the implementation of macvtap, these connections do not allow - communication directly between the host and the guests - if you - require this you will either need the attached physical switch - to be operating in a mirroring mode (so that all traffic coming - to the switch is reflected back to the host's interface), or - provide alternate means for this communication (e.g. a second - interface on each guest that is connected to an isolated - network). The other forward modes that use macvtap (private, - vepa, and passthrough) would be used in a similar fashion. - </p> - - <pre> -<network> - <name>direct-macvtap</name> - <forward mode="bridge"> - <interface dev="eth20"/> - <interface dev="eth21"/> - <interface dev="eth22"/> - <interface dev="eth23"/> - <interface dev="eth24"/> - </forward> -</network></pre> - - <h3><a id="examplesNoGateway">Network config with no gateway addresses</a></h3> - - <p> - A valid network definition can contain no IPv4 or IPv6 addresses. Such a definition - can be used for a "very private" or "very isolated" network since it will not be - possible to communicate with the virtualization host via this network. However, - this virtual network interface can be used for communication between virtual guest - systems. This works for IPv4 and <span class="since">(Since 1.0.1)</span> IPv6. - However, the new ipv6='yes' must be added for guest-to-guest IPv6 - communication. - </p> - - <pre> -<network ipv6='yes'> - <name>nogw</name> - <uuid>7a3b7497-1ec7-8aef-6d5c-38dff9109e93</uuid> - <bridge name="virbr2" stp="on" delay="0"/> - <mac address='00:16:3E:5D:C7:9E'/> -</network></pre> - - </body> -</html> diff --git a/docs/formatnetwork.rst b/docs/formatnetwork.rst new file mode 100644 index 0000000000..d6550f6df9 --- /dev/null +++ b/docs/formatnetwork.rst @@ -0,0 +1,1144 @@ +.. role:: since + +================== +Network XML format +================== + +.. contents:: + +This page provides an introduction to the network XML format. For background +information on the concepts referred to here, consult the `relevant wiki +page <https://wiki.libvirt.org/page/Networking>`__. + +Element and attribute overview +------------------------------ + +The root element required for all virtual networks is named ``network`` and has +no configurable attributes (although :since:`since 0.10.0` there is one optional +read-only attribute - when examining the live configuration of a network, the +attribute ``connections``, if present, specifies the number of guest interfaces +currently connected via this network). The network XML format is available +:since:`since 0.3.0` + +General metadata +~~~~~~~~~~~~~~~~ + +The first elements provide basic metadata about the virtual network. + +:: + + <network ipv6='yes' trustGuestRxFilters='no'> + <name>default</name> + <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid> + <metadata> + <app1:foo xmlns:app1="http://app1.org/app1/">..</app1:foo> + <app2:bar xmlns:app2="http://app1.org/app2/">..</app2:bar> + </metadata> + ... + +``name`` + The content of the ``name`` element provides a short name for the virtual + network. This name should consist only of alphanumeric characters and is + required to be unique within the scope of a single host. It is used to form + the filename for storing the persistent configuration file. :since:`Since + 0.3.0` +``uuid`` + The content of the ``uuid`` element provides a globally unique identifier for + the virtual network. The format must be RFC 4122 compliant, eg + ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating a + new network, a random UUID is generated. :since:`Since 0.3.0` + The ``metadata`` node can be used by applications to store custom metadata in + the form of XML nodes/trees. Applications must use custom namespaces on their + XML nodes/trees, with only one top-level element per namespace (if the + application needs structure, they should have sub-elements to their namespace + element). :since:`Since 2.1.0` +``ipv6`` + When set to ``yes``, the optional parameter ``ipv6`` enables a network + definition with no IPv6 gateway addresses specified to have guest-to-guest + communications. For further information, see the example below for the + example with no gateway addresses. :since:`Since 1.0.1` +``trustGuestRxFilters`` + The optional parameter ``trustGuestRxFilters`` can be used to set that + attribute of the same name for each domain interface connected to this + network ( :since:`since 1.2.10` ). See the `Network + interfaces <formatdomain.html#elementsNICS>`__ section of the domain XML + documentation for more details. Note that an explicit setting of this + attribute in a portgroup or the individual domain interface will override the + setting in the network. + +Connectivity +~~~~~~~~~~~~ + +The next set of elements control how a virtual network is provided connectivity +to the physical LAN (if at all). + +:: + + ... + <bridge name="virbr0" stp="on" delay="5" macTableManager="libvirt"/> + <mtu size="9000"/> + <domain name="example.com" localOnly="no"/> + <forward mode="nat" dev="eth0"/> + ... + +``bridge`` + The ``name`` attribute on the ``bridge`` element defines the name of a bridge + device which will be used to construct the virtual network. The virtual + machines will be connected to this bridge device allowing them to talk to + each other. The bridge device may also be connected to the LAN. When defining + a new network with a ``<forward>`` mode of "nat", "route", or "open" (or an + isolated network with no ``<forward>`` element), libvirt will automatically + generate a unique name for the bridge device if none is given, and this name + will be permanently stored in the network configuration so that that the same + name will be used every time the network is started. For these types of + networks (nat, route, open, and isolated), a bridge name beginning with the + prefix "virbr" is recommended (and that is what is auto-generated), but not + enforced. Attribute ``stp`` specifies if Spanning Tree Protocol is 'on' or + 'off' (default is 'on'). Attribute ``delay`` sets the bridge's forward delay + value in seconds (default is 0). :since:`Since 0.3.0` + + The ``macTableManager`` attribute of the bridge element is used to tell + libvirt how the bridge's MAC address table (used to determine the correct + egress port for packets based on destination MAC address) will be managed. In + the default ``kernel`` setting, the kernel automatically adds and removes + entries, typically using learning, flooding, and promiscuous mode on the + bridge's ports in order to determine the proper egress port for packets. When + ``macTableManager`` is set to ``libvirt``, libvirt disables kernel management + of the MAC table (in the case of the Linux host bridge, this means enabling + vlan_filtering on the bridge, and disabling learning and unicast_filter for + all bridge ports), and explicitly adds/removes entries to the table according + to the MAC addresses in the domain interface configurations. Allowing libvirt + to manage the MAC table can improve performance - with a Linux host bridge, + for example, turning off learning and unicast_flood on ports has its own + performance advantage, and can also lead to an additional boost by permitting + the kernel to automatically turn off promiscuous mode on some ports of the + bridge (in particular, the port attaching the bridge to the physical + network). However, it can also cause some networking setups to stop working + (e.g. vlan tagging, multicast, guest-initiated changes to MAC address) and is + not supported by older kernels. :since:`Since 1.2.11, requires kernel 3.17 or + newer` + + The optional ``zone`` attribute of the ``bridge`` element is used to specify + the `firewalld <https://firewalld.org>`__ zone for the bridge of a network + with ``forward`` mode of "nat", "route", "open", or one with no ``forward`` + specified. By default, the bridges of all virtual networks with these forward + modes are placed in the firewalld zone named "libvirt", which permits + incoming DNS, DHCP, TFTP, and SSH to the host from guests on the network. + This behavior can be changed either by modifying the libvirt zone (using + firewalld management tools), or by placing the network in a different zone + (which will also be managed using firewalld tools). :since:`Since 5.1.0` + +``mtu`` + The ``size`` attribute of the ``mtu>`` element specifies the Maximum + Transmission Unit (MTU) for the network. :since:`Since 3.1.0` . In the case + of a libvirt-managed network (one with forward mode of ``nat``, ``route``, + ``open``, or no ``forward`` element (i.e. an isolated network), this will be + the MTU assigned to the bridge device when libvirt creates it, and thereafter + also assigned to all tap devices created to connect guest interfaces. Network + types not specifically mentioned here don't support having an MTU set in the + libvirt network config. If mtu size is unspecified, the default setting for + the type of device being used is assumed (usually 1500). +``domain`` + The ``name`` attribute on the ``domain`` element defines the DNS domain of + the DHCP server. This element is optional, and is only used for those + networks with a ``<forward>`` mode of "nat" or "route" (or an isolated + network with no ``<forward>`` element). :since:`Since 0.4.5` + + If the optional ``localOnly`` attribute on the ``domain`` element is "yes", + then DNS requests under this domain will only be resolved by the virtual + network's own DNS server - they will not be forwarded to the host's upstream + DNS server. If ``localOnly`` is "no", and by default, unresolved requests + **will** be forwarded. :since:`Since 1.2.12` + +``forward`` + Inclusion of the ``forward`` element indicates that the virtual network is to + be connected to the physical LAN. :since:`Since 0.3.0.` The ``mode`` + attribute determines the method of forwarding. If there is no ``forward`` + element, the network will be isolated from any other network (unless a guest + connected to that network is acting as a router, of course). The following + are valid settings for ``mode`` (if there is a ``forward`` element but mode + is not specified, ``mode='nat'`` is assumed): + + ``nat`` + All traffic between guests connected to this network and the physical + network will be forwarded to the physical network via the host's IP + routing stack, after the guest's IP address is translated to appear as the + host machine's public IP address (a.k.a. Network Address Translation, or + "NAT"). This allows multiple guests, all having access to the physical + network, on a host that is only allowed a single public IP address. If a + network has any IPv6 addresses defined, the IPv6 traffic will be forwarded + using plain routing, since IPv6 has no concept of NAT. Firewall rules will + allow outbound connections to any other network device whether ethernet, + wireless, dialup, or VPN. If the ``dev`` attribute is set, the firewall + rules will restrict forwarding to the named device only. Inbound + connections from other networks are all prohibited; all connections + between guests on the same network, and to/from the host to the guests, + are unrestricted and not NATed. :since:`Since 0.4.2` + + :since:`Since 1.0.3` it is possible to specify a public IPv4 address and + port range to be used for the NAT by using the ``<nat>`` subelement. Note + that all addresses from the range are used, not just those that are in use + on the host. The address range is set with the ``<address>`` subelements + and ``start`` and ``stop`` attributes: + + :: + + ... + <forward mode='nat'> + <nat> + <address start='1.2.3.4' end='1.2.3.10'/> + </nat> + </forward> + ... + + A single IPv4 address can be set by setting ``start`` and ``end`` + attributes to the same value. + + The port range to be used for the ``<nat>`` can be set via the subelement + ``<port>``: + + :: + + ... + <forward mode='nat'> + <nat> + <port start='500' end='1000'/> + </nat> + </forward> + ... + + :since:`Since 6.5.0` it is possible to enable NAT with IPv6 networking. As + noted above, IPv6 has historically done plain forwarding and thus to avoid + breaking historical compatibility, IPv6 NAT must be explicitly requested. + + :: + + ... + <forward mode='nat'> + <nat ipv6='yes'/> + </forward> + ... + + ``route`` + Guest network traffic will be forwarded to the physical network via the + host's IP routing stack, but without having NAT applied. Again, if the + ``dev`` attribute is set, firewall rules will restrict forwarding to the + named device only. This presumes that the local LAN router has suitable + routing table entries to return traffic to this host. All incoming and + outgoing sessions to guest on these networks are unrestricted. (To + restrict incoming traffic to a guest on a routed network, you can + configure `nwfilter rules <formatnwfilter.html>`__ on the guest's + interfaces.) :since:`Since 0.4.2` + ``open`` + As with mode='route', guest network traffic will be forwarded to the + physical network via the host's IP routing stack, but there will be no + firewall rules added to either enable or prevent any of this traffic. When + forward='open' is set, the ``dev`` attribute cannot be set (because the + forward dev is enforced with firewall rules, and the purpose of + forward='open' is to have a forwarding mode where libvirt doesn't add any + firewall rules). This mode presumes that the local LAN router has suitable + routing table entries to return traffic to this host, and that some other + management system has been used to put in place any necessary firewall + rules. Although no firewall rules will be added for the network, it is of + course still possible to add restrictions for specific guests using + `nwfilter rules <formatnwfilter.html>`__ on the guests' interfaces.) + :since:`Since 2.2.0` + ``bridge`` + This network describes either 1) an existing host bridge that was + configured outside of libvirt (if a ``<bridge name='xyz'/>`` element has + been specified, :since:`Since 0.9.4` ), 2) an existing Open vSwitch bridge + that was configured outside of libvirt (if both a ``<bridge name='xyz'/>`` + element **and** a ``<virtualport type='openvswitch'/>`` have + been specified :since:`Since 0.10.0` ) 3) an interface or group of + interfaces to be used for a "direct" connection via macvtap using + macvtap's "bridge" mode (if the forward element has one or more + ``<interface>`` subelements, :since:`Since 0.9.4` ) (see `Direct + attachment to physical interface <formatdomain.html#elementsNICSDirect>`__ + for descriptions of the various macvtap modes). libvirt doesn't attempt to + manage the bridge interface at all, thus the ``<bridge>`` element's + ``stp`` and ``delay`` attributes are not allowed; no iptables rules, IP + addresses, or DHCP/DNS services are added; at the IP level, the guest + interface appears to be directly connected to the physical interface. + :since:`Since 0.9.4` + ``private`` + This network uses a macvtap "direct" connection in "private" mode to + connect each guest to the network. The physical interface to be used will + be picked from among those listed in ``<interface>`` subelements of the + ``<forward>`` element; when using 802.1Qbh mode (as indicated by the + ``<virtualport>`` type attribute - note that this requires an + 802.1Qbh-capable hardware switch), each physical interface can only be in + use by a single guest interface at a time; in modes other than 802.1Qbh, + multiple guest interfaces can share each physical interface (libvirt will + attempt to balance usage between all available interfaces). :since:`Since + 0.9.4` + ``vepa`` + This network uses a macvtap "direct" connection in "vepa" mode to connect + each guest to the network (this requires that the physical interfaces used + be connected to a vepa-capable hardware switch. The physical interface to + be used will be picked from among those listed in ``<interface>`` + subelements of the ``<forward>`` element; multiple guest interfaces can + share each physical interface (libvirt will attempt to balance usage + between all available interfaces). :since:`Since 0.9.4` + ``passthrough`` + This network uses a macvtap "direct" connection in "passthrough" mode to + connect each guest to the network (note that this is *not* the same thing + as "PCI passthrough"). The physical interface to be used will be picked + from among those listed in ``<interface>`` subelements of the + ``<forward>`` element. Each physical interface can only be in use by a + single guest interface at a time, so libvirt will keep track of which + interfaces are currently in use, and only assign unused interfaces (if + there are no available physical interfaces when a domain interface is + being attached, an error will be logged, and the operation causing the + attach will fail (usually either a domain start, or a hotplug interface + attach to a domain). :since:`Since 0.9.4` + ``hostdev`` + This network facilitates PCI Passthrough of a network device. A network + device is chosen from the interface pool and directly assigned to the + guest using generic device passthrough, after first optionally setting the + device's MAC address and vlan tag to the configured value, and optionally + associating the device with an 802.1Qbh capable switch using a + ``<virtualport>`` element. Note that - due to limitations in standard + single-port PCI ethernet card driver design - only SR-IOV (Single Root I/O + Virtualization) virtual function (VF) devices can be assigned in this + manner; to assign a standard single-port PCI or PCIe ethernet card to a + guest, use the traditional ``<hostdev>`` device definition. :since:` Since + 0.10.0` + + To force use of a particular type of device assignment, a <forward + type='hostdev'> interface can have an optional ``driver`` sub-element with + a ``name`` attribute set to either "vfio" (VFIO is a new method of device + assignment that is compatible with UEFI Secure Boot) or "kvm" (the legacy + device assignment handled directly by the KVM kernel module) :since:`Since + 1.0.5 (QEMU and KVM only, requires kernel 3.6 or newer)` . When specified, + device assignment will fail if the requested method of device assignment + isn't available on the host. When not specified, the default is "vfio" on + systems where the VFIO driver is available and loaded, and "kvm" on older + systems, or those where the VFIO driver hasn't been loaded :since:`Since + 1.1.3` (prior to that the default was always "kvm"). + + Note that this "intelligent passthrough" of network devices is very + similar to the functionality of a standard ``<hostdev>`` device, the + difference being that this method allows specifying a MAC address, vlan + tag, and ``<virtualport>`` for the passed-through device. If these + capabilities are not required, if you have a standard single-port PCI, + PCIe, or USB network card that doesn't support SR-IOV (and hence would + anyway lose the configured MAC address during reset after being assigned + to the guest domain), or if you are using a version of libvirt older than + 0.10.0, you should use a standard ``<hostdev>`` device definition in the + domain's configuration to assign the device to the guest instead of + defining an ``<interface type='network'>`` pointing to a + network with ``<forward mode='hostdev'/>``. + + As mentioned above, a ``<forward>`` element can have multiple ``<interface>`` + subelements, each one giving the name of a physical interface that can be + used for this network :since:`Since 0.9.4` : + + :: + + ... + <forward mode='passthrough'> + <interface dev='eth10'/> + <interface dev='eth11'/> + <interface dev='eth12'/> + <interface dev='eth13'/> + <interface dev='eth14'/> + </forward> + ... + + :since:`since 0.10.0` , ``<interface>`` also has an optional read-only + attribute - when examining the live configuration of a network, the attribute + ``connections``, if present, specifies the number of guest interfaces + currently connected via this physical interface. + + Additionally, :since:`since 0.9.10` , libvirt allows a shorthand for + specifying all virtual interfaces associated with a single physical function, + by using the ``<pf>`` subelement to call out the corresponding physical + interface associated with multiple virtual interfaces: + + :: + + ... + <forward mode='passthrough'> + <pf dev='eth0'/> + </forward> + ... + + When a guest interface is being constructed, libvirt will pick an interface + from this list to use for the connection. In modes where physical interfaces + can be shared by multiple guest interfaces, libvirt will choose the interface + that currently has the least number of connections. For those modes that do + not allow sharing of the physical device (in particular, 'passthrough' mode, + and 'private' mode when using 802.1Qbh), libvirt will choose an unused + physical interface or, if it can't find an unused interface, fail the + operation. + + :since:`since 0.10.0` When using forward mode 'hostdev', the interface pool + is specified with a list of ``<address>`` elements, each of which has + ``<type>`` (must always be ``'pci'``), ``<domain>``, ``<bus>``, + ``<slot>``\ and ``<function>`` attributes. + + :: + + ... + <forward mode='hostdev' managed='yes'> + <driver name='vfio'/> + <address type='pci' domain='0' bus='4' slot='0' function='1'/> + <address type='pci' domain='0' bus='4' slot='0' function='2'/> + <address type='pci' domain='0' bus='4' slot='0' function='3'/> + </forward> + ... + + Alternatively the interface pool can also be defined using a single physical + function ``<pf>`` subelement to call out the corresponding physical interface + associated with multiple virtual interfaces (similar to passthrough mode): + + :: + + ... + <forward mode='hostdev' managed='yes'> + <pf dev='eth0'/> + </forward> + ... + +Quality of service +^^^^^^^^^^^^^^^^^^ + +:: + + ... + <forward mode='nat' dev='eth0'/> + <bandwidth> + <inbound average='1000' peak='5000' burst='5120'/> + <outbound average='128' peak='256' burst='256'/> + </bandwidth> + ... + +The ``<bandwidth>`` element allows setting quality of service for a particular +network ( :since:`since 0.9.4` ). Setting ``bandwidth`` for a network is +supported only for networks with a ``<forward>`` mode of ``route``, ``nat``, +``bridge``, or no mode at all (i.e. an "isolated" network). Setting +``bandwidth`` is **not** supported for forward modes ``passthrough``, +``private``, or ``hostdev``. Attempts to do this will lead to a failure to +define the network or to create a transient network. + +The ``<bandwidth>`` element can only be a subelement of a domain's +``<interface>``, a subelement of a ``<network>``, or a subelement of a +``<portgroup>`` in a ``<network>``. + +As a subelement of a domain's ``<interface>``, the bandwidth only applies to +that one interface of the domain. As a subelement of a ``<network>``, the +bandwidth is a total aggregate bandwidth to/from all guest interfaces attached +to that network, **not** to each guest interface individually. If a domain's +``<interface>`` has ``<bandwidth>`` element values higher than the aggregate for +the entire network, then the aggregate bandwidth for the ``<network>`` takes +precedence. This is because the two choke points are independent of each other +where the domain's ``<interface>`` bandwidth control is applied on the +interface's tap device, while the ``<network>`` bandwidth control is applied on +the interface part of the bridge device created for that network. + +As a subelement of a ``<portgroup>`` in a ``<network>``, if a domain's +``<interface>`` has a ``portgroup`` attribute in its ``<source>`` element +**and** if the ``<interface>`` itself has no ``<bandwidth>`` element, then the +``<bandwidth>`` element of the portgroup will be applied individually to each +guest interface defined to be a member of that portgroup. Any ``<bandwidth>`` +element in the domain's ``<interface>`` definition will override the setting in +the portgroup ( :since:`since 1.0.1` ). + +Incoming and outgoing traffic can be shaped independently. The ``bandwidth`` +element can have at most one ``inbound`` and at most one ``outbound`` child +element. Leaving either of these children elements out results in no QoS applied +for that traffic direction. So, when you want to shape only incoming traffic, +use ``inbound`` only, and vice versa. Each of these elements have one mandatory +attribute - ``average`` (or ``floor`` as described below). The attributes are as +follows, where accepted values for each attribute is an integer number. + +``average`` + Specifies the desired average bit rate for the interface being shaped (in + kilobytes/second). +``peak`` + Optional attribute which specifies the maximum rate at which the bridge can + send data (in kilobytes/second). Note the limitation of implementation: this + attribute in the ``outbound`` element is ignored (as Linux ingress filters + don't know it yet). +``burst`` + Optional attribute which specifies the amount of kibibytes that can be + transmitted in a single burst at ``peak`` speed. +``floor`` + Optional attribute available only for the ``inbound`` element. This attribute + guarantees minimal throughput for shaped interfaces. This, however, requires + that all traffic goes through one point where QoS decisions can take place, + hence why this attribute works only for virtual networks for now (that is + ``<interface type='network'/>`` with a forward type of route, nat, open or no + forward at all). Moreover, the virtual network the interface is connected to + is required to have at least inbound QoS set (``average`` at least). If using + the ``floor`` attribute users don't need to specify ``average``. However, + ``peak`` and ``burst`` attributes still require ``average``. Currently, the + Linux kernel doesn't allow ingress qdiscs to have any classes therefore + ``floor`` can be applied only on ``inbound`` and not ``outbound``. + +Attributes ``average``, ``peak``, and ``burst`` are available :since:`since +0.9.4` , while the ``floor`` attribute is available :since:`since 1.0.1` . + +Setting VLAN tag (on supported network types only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + <network> + <name>ovs-net</name> + <forward mode='bridge'/> + <bridge name='ovsbr0'/> + <virtualport type='openvswitch'> + <parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/> + </virtualport> + <vlan trunk='yes'> + <tag id='42' nativeMode='untagged'/> + <tag id='47'/> + </vlan> + <portgroup name='dontpanic'> + <vlan> + <tag id='42'/> + </vlan> + </portgroup> + </network> + +If (and only if) the network connection used by the guest supports VLAN tagging +transparent to the guest, an optional ``<vlan>`` element can specify one or more +VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` . +Network connections that support guest-transparent VLAN tagging include 1) +type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since +0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device +assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with +mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other +connection types, including standard linux bridges and libvirt's own virtual +networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches +provide their own way (outside of libvirt) to tag guest traffic onto a specific +VLAN. Each tag is given in a separate ``<tag>`` subelement of ``<vlan>`` (for +example: ``<tag id='42'/>``). For VLAN trunking of multiple tags (which is +supported only on Open vSwitch connections), multiple ``<tag>`` subelements can +be specified, which implies that the user wants to do VLAN trunking on the +interface for all the specified tags. In the case that VLAN trunking of a single +tag is desired, the optional attribute ``trunk='yes'`` can be added to the +toplevel ``<vlan>`` element to differentiate trunking of a single tag from +normal tagging. + +For network connections using Open vSwitch it is also possible to configure +'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is +done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement: +``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the +``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to +be the "native" VLAN for this interface, and the ``nativeMode`` attribute +determines whether or not traffic for that VLAN will be tagged. + +``<vlan>`` elements can also be specified in a ``<portgroup>`` element, as well +as directly in a domain's ``<interface>`` element. In the case that a vlan tag +is specified in multiple locations, the setting in ``<interface>`` takes +precedence, followed by the setting in the ``<portgroup>`` selected by the +interface config. The ``<vlan>`` in ``<network>`` will be selected only if none +is given in ``<portgroup>`` or ``<interface>``. + +Isolating ports from one another +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + <network> + <name>isolated-ports</name> + <forward mode='bridge'/> + <bridge name='br0'/> + <port isolated='yes'/> + </network> + +:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to +``yes`` (default setting is ``no``) is used to isolate the network traffic of +each guest on the network from all other guests connected to the network; it +does not have an effect on communication between the guests and the host, or +between the guests and destinations beyond this network. This setting is only +supported for networks that use a Linux host bridge to connect guest interfaces +via a standard tap device (i.e. those with a forward mode of nat, route, open, +bridge, or no forward mode). + +Portgroups +^^^^^^^^^^ + +:: + + ... + <forward mode='private'/> + <interface dev="eth20"/> + <interface dev="eth21"/> + <interface dev="eth22"/> + <interface dev="eth23"/> + <interface dev="eth24"/> + </forward> + <portgroup name='engineering' default='yes'> + <virtualport type='802.1Qbh'> + <parameters profileid='test'/> + </virtualport> + <bandwidth> + <inbound average='1000' peak='5000' burst='5120'/> + <outbound average='1000' peak='5000' burst='5120'/> + </bandwidth> + </portgroup> + <portgroup name='sales' trustGuestRxFilters='no'> + <virtualport type='802.1Qbh'> + <parameters profileid='salestest'/> + </virtualport> + <bandwidth> + <inbound average='500' peak='2000' burst='2560'/> + <outbound average='128' peak='256' burst='256'/> + </bandwidth> + </portgroup> + ... + +:since:`Since 0.9.4` A portgroup provides a method of easily putting guest +connections to the network into different classes, with each class potentially +having a different level/type of service. :since:`Since 0.9.4` Each network can +have multiple portgroup elements (and one of those can optionally be designated +as the 'default' portgroup for the network), and each portgroup has a name, as +well as various attributes and subelements associated with it. The currently +supported subelements are ``<bandwidth>`` (described in `Quality of service`_) +and ``<virtualport>`` (documented +`here <formatdomain.html#elementsNICSDirect>`__). If a domain interface +definition specifies a portgroup (by adding a ``portgroup`` attribute to the +``<source>`` subelement), that portgroup's info will be merged into the +interface's configuration. If no portgroup is given in the interface definition, +and one of the network's portgroups has ``default='yes'``, that default +portgroup will be used. If no portgroup is given in the interface definition, +and there is no default portgroup, then none will be used. Any ``<bandwidth>`` +specified directly in the domain XML will take precedence over any setting in +the chosen portgroup. if a ``<virtualport>`` is specified in the portgroup +(and/or directly in the network definition), the multiple virtualports will be +merged, and any parameter that is specified in more than one virtualport, and is +not identical, will be considered an error, and will prevent the interface from +starting. + +portgroups also support the optional parameter ``trustGuestRxFilters`` which can +be used to set that attribute of the same name for each domain interface using +this portgroup ( :since:`since 1.2.10` ). See the `Network +interfaces <formatdomain.html#elementsNICS>`__ section of the domain XML +documentation for more details. Note that an explicit setting of this attribute +in the portgroup overrides the network-wide setting, and an explicit setting in +the individual domain interface will override the setting in the portgroup. + +Static Routes +^^^^^^^^^^^^^ + +Static route definitions are used to provide routing information to the +virtualization host for networks which are not directly reachable from the +virtualization host, but \*are\* reachable from a guest domain that is itself +reachable from the host :since:`since 1.0.6` . + +As shown in `Network config with no gateway addresses`_ example, it is +possible to define a virtual network interface with no IPv4 or IPv6 addresses. +Such networks are useful to provide host connectivity to networks which are only +reachable via a guest. A guest with connectivity both to the guest-only network +and to another network that is directly reachable from the host can act as a +gateway between the networks. A static route added to the "host-visible" network +definition provides the routing information so that IP packets can be sent from +the virtualization host to guests on the hidden network. + +Here is a fragment of a definition which shows the static route specification as +well as the IPv4 and IPv6 definitions for network addresses which are referred +to in the ``gateway`` gateway address specifications. Note that the third static +route specification includes the ``metric`` attribute specification with a value +of 2. This particular route would \*not\* be preferred if there was another +existing rout on the system with the same address and prefix but with a lower +value for the metric. If there is a route in the host system configuration that +should be overridden by a route in a virtual network whenever the virtual +network is running, the configuration for the system-defined route should be +modified to have a higher metric, and the route on the virtual network given a +lower metric (for example, the default metric of "1"). + +:: + + ... + <ip address="192.168.122.1" netmask="255.255.255.0"> + <dhcp> + <range start="192.168.122.128" end="192.168.122.254"/> + </dhcp> + </ip> + <route address="192.168.222.0" prefix="24" gateway="192.168.122.2"/> + <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/> + <route family="ipv6" address="2001:db8:ca2:3::" prefix="64" gateway="2001:db8:ca2:2::2"/> + <route family="ipv6" address="2001:db9:4:1::" prefix="64" gateway="2001:db8:ca2:2::3" metric='2'/> + ... + +Addressing +~~~~~~~~~~ + +The final set of elements define the addresses (IPv4 and/or IPv6, as well as +MAC) to be assigned to the bridge device associated with the virtual network, +and optionally enable DHCP services. These elements are only valid for isolated +networks (no ``forward`` element specified), and for those with a forward mode +of 'route' or 'nat'. + +:: + + ... + <mac address='00:16:3E:5D:C7:9E'/> + <domain name="example.com"/> + <dns> + <txt name="example" value="example value"/> + <forwarder addr="8.8.8.8"/> + <forwarder domain='example.com' addr="8.8.4.4"/> + <forwarder domain='www.example.com'/> + <srv service='name' protocol='tcp' domain='test-domain-name' target='.' + port='1024' priority='10' weight='10'/> + <host ip='192.168.122.2'> + <hostname>myhost</hostname> + <hostname>myhostalias</hostname> + </host> + </dns> + <ip address="192.168.122.1" netmask="255.255.255.0" localPtr="yes"> + <dhcp> + <range start="192.168.122.100" end="192.168.122.254"> + <lease expiry='1' unit='hours'/> + </range> + <host mac="00:16:3e:77:e2:ed" name="foo.example.com" ip="192.168.122.10"> + <lease expiry='30' unit='minutes'/> + </host> + <host mac="00:16:3e:3e:a9:1a" name="bar.example.com" ip="192.168.122.11"/> + </dhcp> + </ip> + <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64" localPtr="yes"/> + <route family="ipv6" address="2001:db9:ca1:1::" prefix="64" gateway="2001:db8:ca2:2::2"/> + +``mac`` + The ``address`` attribute defines a MAC (hardware) address formatted as 6 + groups of 2-digit hexadecimal numbers, the groups separated by colons (eg, + ``"52:54:00:1C:DA:2F"``). This MAC address is assigned to the bridge device + when it is created. Generally it is best to not specify a MAC address when + creating a network - in this case, if a defined MAC address is needed for + proper operation, libvirt will automatically generate a random MAC address + and save it in the config. Allowing libvirt to generate the MAC address will + assure that it is compatible with the idiosyncrasies of the platform where + libvirt is running. :since:`Since 0.8.8` +``dns`` + The dns element of a network contains configuration information for the + virtual network's DNS server :since:`Since 0.9.3` . + + The dns element can have an optional ``enable`` attribute :since:`Since + 2.2.0` . If ``enable`` is "no", then no DNS server will be setup by libvirt + for this network (and any other configuration in ``<dns>`` will be ignored). + If ``enable`` is "yes" or unspecified (including the complete absence of any + ``<dns>`` element) then a DNS server will be setup by libvirt to listen on + all IP addresses specified in the network's configuration. + + The dns element can have an optional ``forwardPlainNames`` attribute + :since:`Since 1.1.2` . If ``forwardPlainNames`` is "no", then DNS resolution + requests for names that are not qualified with a domain (i.e. names with no + "." character) will not be forwarded to the host's upstream DNS server - they + will only be resolved if they are known locally within the virtual network's + own DNS server. If ``forwardPlainNames`` is "yes", unqualified names **will** + be forwarded to the upstream DNS server if they can't be resolved by the + virtual network's own DNS server. + + Currently supported sub-elements of ``<dns>`` are: + + ``forwarder`` + The dns element can have 0 or more ``<forwarder>`` elements. Each + forwarder element defines an alternate DNS server to use for some, or all, + DNS requests sent to this network's DNS server. There are two attributes - + ``domain``, and ``addr``; at least one of these must be specified in any + ``<forwarder>`` element. If both ``domain`` and ``addr`` are specified, + then all requests that match the given domain will be forwarded to the DNS + server at addr. If only ``domain`` is specified, then all matching domains + will be resolved locally (or via the host's standard DNS forwarding if + they can't be resolved locally). If an ``addr`` is specified by itself, + then all DNS requests to the network's DNS server will be forwarded to the + DNS server at that address with no exceptions. ``addr`` :since:`Since + 1.1.3` , ``domain`` :since:`Since 2.2.0` . + ``txt`` + A ``dns`` element can have 0 or more ``txt`` elements. Each txt element + defines a DNS TXT record and has two attributes, both required: a name + that can be queried via dns, and a value that will be returned when that + name is queried. names cannot contain embedded spaces or commas. value is + a single string that can contain multiple values separated by commas. + :since:`Since 0.9.3` + ``host`` + The ``host`` element within ``dns`` is the definition of DNS hosts to be + passed to the DNS service. The IP address is identified by the ``ip`` + attribute and the names for that IP address are identified in the + ``hostname`` sub-elements of the ``host`` element. :since:`Since 0.9.3` + + ``srv`` + The ``dns`` element can have also 0 or more ``srv`` record elements. Each + ``srv`` record element defines a DNS SRV record and has 2 mandatory and 5 + optional attributes. The mandatory attributes are ``service`` and + ``protocol`` (tcp, udp) and the optional attributes are ``target``, + ``port``, ``priority``, ``weight`` and ``domain`` as defined in DNS server + SRV RFC (RFC 2782). :since:`Since 0.9.9` + +``ip`` + The ``address`` attribute defines an IPv4 address in dotted-decimal format, + or an IPv6 address in standard colon-separated hexadecimal format, that will + be configured on the bridge device associated with the virtual network. To + the guests this IPv4 address will be their IPv4 default route. For IPv6, the + default route is established via Router Advertisement. For IPv4 addresses, + the ``netmask`` attribute defines the significant bits of the network + address, again specified in dotted-decimal format. For IPv6 addresses, and as + an alternate method for IPv4 addresses, the significant bits of the network + address can be specified with the ``prefix`` attribute, which is an integer + (for example, ``netmask='255.255.255.0'`` could also be given as + ``prefix='24'``). The ``family`` attribute is used to specify the type of + address - ``ipv4`` or ``ipv6``; if no ``family`` is given, ``ipv4`` is + assumed. More than one address of each family can be defined for a network. + The optional ``localPtr`` attribute ( :since:`since 3.0.0` ) configures the + DNS server to not forward any reverse DNS requests for IP addresses from the + network configured by the ``address`` and ``netmask``/``prefix`` attributes. + For some unusual network prefixes (not divisible by 8 for IPv4 or not + divisible by 4 for IPv6) libvirt may be unable to compute the PTR domain + automatically. The ``ip`` element is supported :since:`since 0.3.0` . IPv6, + multiple addresses on a single network, ``family``, and ``prefix`` are + supported :since:`since 0.8.7` . The ``ip`` element may contain the following + elements: + + ``tftp`` + The optional ``tftp`` element and its mandatory ``root`` attribute enable + TFTP services. The attribute specifies the path to the root directory + served via TFTP. The ``tftp`` element is not supported for IPv6 addresses, + and can only be specified on a single IPv4 address per network. + :since:`Since 0.7.1` + ``dhcp`` + The presence of this element enables DHCP services on the virtual network. + The ``dhcp`` element is supported for both IPv4 ( :since:`since 0.3.0` ) + and IPv6 ( :since:`since 1.0.1` ), but only for one IP address of each + type per network. The following sub-elements are supported: + + ``range`` + The ``start`` and ``end`` attributes on the ``range`` element specify + the boundaries of a pool of addresses to be provided to DHCP clients. + These two addresses must lie within the scope of the network defined on + the parent ``ip`` element. There may be zero or more ``range`` elements + specified. :since:`Since 0.3.0` + ``host`` + Within the ``dhcp`` element there may be zero or more ``host`` + elements. These specify hosts which will be given names and predefined + IP addresses by the built-in DHCP server. Any IPv4 ``host`` element + must specify the MAC address of the host to be assigned a given name + (via the ``mac`` attribute), the IP to be assigned to that host (via + the ``ip`` attribute), and the name itself (the ``name`` attribute). + The IPv6 ``host`` element differs slightly from that for IPv4: there is + no ``mac`` attribute since a MAC address has no defined meaning in + IPv6. Instead, the ``name`` attribute is used to identify the host to + be assigned the IPv6 address. For DHCPv6, the name is the plain name of + the client host sent by the client to the server. Note that this method + of assigning a specific IP address can also be used for IPv4 instead of + the ``mac`` attribute. :since:`Since 0.4.5` + ``bootp`` + The optional ``bootp`` element specifies BOOTP options to be provided + by the DHCP server for IPv4 only. Two attributes are supported: + ``file`` is mandatory and gives the file to be used for the boot image; + ``server`` is optional and gives the address of the TFTP server from + which the boot image will be fetched. ``server`` defaults to the same + host that runs the DHCP server, as is the case when the ``tftp`` + element is used. The BOOTP options currently have to be the same for + all address ranges and statically assigned addresses. :since:`Since + 0.7.1` (``server`` :since:`since 0.7.3` ) + + Optionally, ``range`` and ``host`` elements can have ``lease`` child + element which specifies the lease time through it's attributes ``expiry`` + and ``unit`` (which accepts ``seconds``, ``minutes`` and ``hours`` and + defaults to ``minutes`` if omitted). The minimal lease time is 2 minutes, + except when setting an infinite lease time (``expiry='0'``). :since:`Since + 6.3.0` + +Network namespaces +~~~~~~~~~~~~~~~~~~ + +A special XML namespace is available for passing options directly to the +underlying dnsmasq configuration file :since:`since 5.6.0` . Usage of XML +namespaces comes with no support guarantees, so use at your own risk. + +This example XML will pass the option strings ``foo=bar`` and +``cname=*.foo.example.com,master.example.com`` directly to the underlying +dnsmasq instance. + +:: + + <network xmlns:dnsmasq='http://libvirt.org/schemas/network/dnsmasq/1.0'> + ... + <dnsmasq:options> + <dnsmasq:option value="foo=bar"/> + <dnsmasq:option value="cname=*.foo.example.com,master.example.com"/> + </dnsmasq:options> + </network> + +Example configuration +--------------------- + +NAT based network +~~~~~~~~~~~~~~~~~ + +This example is the so called "default" virtual network. It is provided and +enabled out-of-the-box for all libvirt installations. This is a configuration +that allows guest OS to get outbound connectivity regardless of whether the host +uses ethernet, wireless, dialup, or VPN networking without requiring any +specific admin configuration. In the absence of host networking, it at least +allows guests to talk directly to each other. + +:: + + <network> + <name>default</name> + <bridge name="virbr0"/> + <forward mode="nat"/> + <ip address="192.168.122.1" netmask="255.255.255.0"> + <dhcp> + <range start="192.168.122.2" end="192.168.122.254"/> + </dhcp> + </ip> + <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/> + </network> + +Below is a variation of the above example which adds an IPv6 dhcp range +definition. + +:: + + <network> + <name>default6</name> + <bridge name="virbr0"/> + <forward mode="nat"/> + <ip address="192.168.122.1" netmask="255.255.255.0"> + <dhcp> + <range start="192.168.122.2" end="192.168.122.254"/> + </dhcp> + </ip> + <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"> + <dhcp> + <range start="2001:db8:ca2:2:1::10" end="2001:db8:ca2:2:1::ff"/> + </dhcp> + </ip> + </network> + +IPv6 NAT based network +~~~~~~~~~~~~~~~~~~~~~~ + +Below is a variation for also providing IPv6 NAT. This can be especially useful +when using multiple interfaces where some, such as WiFi cards, can not be +bridged (usually on a laptop), making it difficult to provide end-to-end IPv6 +routing. + +:: + + <network> + <name>default6</name> + <bridge name="virbr0"/> + <forward mode="nat"> + <nat ipv6='yes'> + <port start='1024' end='65535'/> + </nat> + + <ip address="192.168.122.1" netmask="255.255.255.0"> + <dhcp> + <range start="192.168.122.2" end="192.168.122.254"/> + </dhcp> + </ip> + <ip family="ipv6" address="fdXX:XXXX:XXXX:NNNN:: prefix="64"/> + </network> + +IPv6 NAT addressing has some caveats over the more straight forward IPv4 case. +`RFC 4193 <https://tools.ietf.org/html/rfc4193>`__ defines the address range +fd00::/8 for /48 IPv6 private networks. It should be concatenated with a random +40-bit string (i.e. 10 random hexadecimal digits replacing the X values above, +RFC 4193 provides an +`algorithm <https://tools.ietf.org/html/rfc4193#section-3.2.2>`__ if you do not +have a source of sufficient randomness). This leaves 0 through ffff for subnets +(N above) which you can use at will. + +Many operating systems will not consider these addresses as preferential to +IPv4, due to some practical history of these addresses being present but +unroutable and causing networking issues. On many Linux distributions, you may +need to override /etc/gai.conf with values from `RFC +3484 <https://www.ietf.org/rfc/rfc3484.txt>`__ to have your IPv6 NAT network +correctly preferenced over IPv4. + +Routed network config +~~~~~~~~~~~~~~~~~~~~~ + +This is a variant on the default network which routes traffic from the virtual +network to the LAN without applying any NAT. It requires that the IP address +range be pre-configured in the routing tables of the router on the host network. +This example further specifies that guest traffic may only go out via the +``eth1`` host network device. + +:: + + <network> + <name>local</name> + <bridge name="virbr1"/> + <forward mode="route" dev="eth1"/> + <ip address="192.168.122.1" netmask="255.255.255.0"> + <dhcp> + <range start="192.168.122.2" end="192.168.122.254"/> + </dhcp> + </ip> + <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"/> + </network> + +Below is another IPv6 variation. Instead of a dhcp range being specified, this +example has a couple of IPv6 host definitions. Note that most of the dhcp host +definitions use an "id" (client id or DUID) since this has proven to be a more +reliable way of specifying the interface and its association with an IPv6 +address. The first is a DUID-LLT, the second a DUID-LL, and the third a +DUID-UUID. :since:`Since 1.0.3` + +:: + + <network> + <name>local6</name> + <bridge name="virbr1"/> + <forward mode="route" dev="eth1"/> + <ip address="192.168.122.1" netmask="255.255.255.0"> + <dhcp> + <range start="192.168.122.2" end="192.168.122.254"/> + </dhcp> + </ip> + <ip family="ipv6" address="2001:db8:ca2:2::1" prefix="64"> + <dhcp> + <host name="paul" ip="2001:db8:ca2:2:3::1"/> + <host id="0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip="2001:db8:ca2:2:3::2"/> + <host id="0:3:0:1:0:16:3e:11:22:33" name="ralph" ip="2001:db8:ca2:2:3::3"/> + <host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63" + name="badbob" ip="2001:db8:ca2:2:3::4"/> + </dhcp> + </ip> + </network> + +Below is yet another IPv6 variation. This variation has only IPv6 defined with +DHCPv6 on the primary IPv6 network. A static link if defined for a second IPv6 +network which will not be directly visible on the bridge interface but there +will be a static route defined for this network via the specified gateway. Note +that the gateway address must be directly reachable via (on the same subnet as) +one of the <ip> addresses defined for this <network>. :since:`Since 1.0.6` + +:: + + <network> + <name>net7</name> + <bridge name="virbr7"/> + <forward mode="route"/> + <ip family="ipv6" address="2001:db8:ca2:7::1" prefix="64"> + <dhcp> + <range start="2001:db8:ca2:7::100" end="2001:db8:ca2::1ff"/> + <host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63" + name="lucas" ip="2001:db8:ca2:2:3::4"/> + </dhcp> + </ip> + <route family="ipv6" address="2001:db8:ca2:8::" prefix="64" gateway="2001:db8:ca2:7::4"/> + </network> + +Isolated network config +~~~~~~~~~~~~~~~~~~~~~~~ + +This variant provides a completely isolated private network for guests. The +guests can talk to each other, and the host OS, but cannot reach any other +machines on the LAN, due to the omission of the ``forward`` element in the XML +description. + +:: + + <network> + <name>private</name> + <bridge name="virbr2"/> + <ip address="192.168.152.1" netmask="255.255.255.0"> + <dhcp> + <range start="192.168.152.2" end="192.168.152.254"/> + </dhcp> + </ip> + <ip family="ipv6" address="2001:db8:ca2:3::1" prefix="64"/> + </network> + +Isolated IPv6 network config +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This variation of an isolated network defines only IPv6. Note that most of the +dhcp host definitions use an "id" (client id or DUID) since this has proven to +be a more reliable way of specifying the interface and its association with an +IPv6 address. The first is a DUID-LLT, the second a DUID-LL, and the third a +DUID-UUID. :since:`Since 1.0.3` + +:: + + <network> + <name>sixnet</name> + <bridge name="virbr6"/> + <ip family="ipv6" address="2001:db8:ca2:6::1" prefix="64"> + <dhcp> + <host name="peter" ip="2001:db8:ca2:6:6::1"/> + <host id="0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip="2001:db8:ca2:6:6::2"/> + <host id="0:3:0:1:0:16:3e:11:22:33" name="dariusz" ip="2001:db8:ca2:6:6::3"/> + <host id="0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63" + name="anita" ip="2001:db8:ca2:6:6::4"/> + </dhcp> + </ip> + </network> + +Using an existing host bridge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 0.9.4` This shows how to use a pre-existing host bridge "br0". The +guests will effectively be directly connected to the physical network (i.e. +their IP addresses will all be on the subnet of the physical network, and there +will be no restrictions on inbound or outbound connections). + +:: + + <network> + <name>host-bridge</name> + <forward mode="bridge"/> + <bridge name="br0"/> + </network> + +Using a macvtap "direct" connection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 0.9.4, QEMU and KVM only, requires Linux kernel 2.6.34 or newer` +This shows how to use macvtap to connect to the physical network directly +through one of a group of physical devices (without using a host bridge device). +As with the host bridge network, the guests will effectively be directly +connected to the physical network so their IP addresses will all be on the +subnet of the physical network, and there will be no restrictions on inbound or +outbound connections. Note that, due to a limitation in the implementation of +macvtap, these connections do not allow communication directly between the host +and the guests - if you require this you will either need the attached physical +switch to be operating in a mirroring mode (so that all traffic coming to the +switch is reflected back to the host's interface), or provide alternate means +for this communication (e.g. a second interface on each guest that is connected +to an isolated network). The other forward modes that use macvtap (private, +vepa, and passthrough) would be used in a similar fashion. + +:: + + <network> + <name>direct-macvtap</name> + <forward mode="bridge"> + <interface dev="eth20"/> + <interface dev="eth21"/> + <interface dev="eth22"/> + <interface dev="eth23"/> + <interface dev="eth24"/> + </forward> + </network> + +Network config with no gateway addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A valid network definition can contain no IPv4 or IPv6 addresses. Such a +definition can be used for a "very private" or "very isolated" network since it +will not be possible to communicate with the virtualization host via this +network. However, this virtual network interface can be used for communication +between virtual guest systems. This works for IPv4 and :since:`(Since 1.0.1)` +IPv6. However, the new ipv6='yes' must be added for guest-to-guest IPv6 +communication. + +:: + + <network ipv6='yes'> + <name>nogw</name> + <uuid>7a3b7497-1ec7-8aef-6d5c-38dff9109e93</uuid> + <bridge name="virbr2" stp="on" delay="0"/> + <mac address='00:16:3E:5D:C7:9E'/> + </network> diff --git a/docs/formatnetworkport.rst b/docs/formatnetworkport.rst index 86a1bdb60b..6f1a24a52c 100644 --- a/docs/formatnetworkport.rst +++ b/docs/formatnetworkport.rst @@ -78,7 +78,7 @@ The following elements are common to one or more of the plug types listed later This part of the network port XML provides setting quality of service. Incoming and outgoing traffic can be shaped independently. The ``bandwidth`` element and its child elements are described in the - `QoS <formatnetwork.html#elementQoS>`__ section of the Network XML. In + `QoS <formatnetwork.html#quality-of-service>`__ section of the Network XML. In addition the ``classID`` attribute may exist to provide the ID of the traffic shaping class that is active. ``rxfilters`` diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index d7753c4970..e8568559fa 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -2017,7 +2017,8 @@ inbound or outbound bandwidth. *average,peak,burst,floor* is the same as in command *attach-interface*. Values for *average*, *peak* and *floor* are expressed in kilobytes per second, while *burst* is expressed in kilobytes in a single burst at *peak* speed as described in the Network XML -documentation at `https://libvirt.org/formatnetwork.html#elementQoS <https://libvirt.org/formatnetwork.html#elementQoS>`__. +documentation at +`https://libvirt.org/formatnetwork.html#quality-of-service <https://libvirt.org/formatnetwork.html#quality-of-service>`__. To clear inbound or outbound settings, use *--inbound* or *--outbound* respectfully with average value of zero. @@ -4824,7 +4825,7 @@ specified. The other two *peak* and *burst* are optional, so are expressed in kilobytes per second, while *burst* is expressed in kilobytes in a single burst at *peak* speed as described in the Network XML documentation at -`https://libvirt.org/formatnetwork.html#elementQoS <https://libvirt.org/formatnetwork.html#elementQoS>`__. +`https://libvirt.org/formatnetwork.html#quality-of-service <https://libvirt.org/formatnetwork.html#quality-of-service>`__. ``--managed`` is usable only for *hostdev* type and tells libvirt that the interface should be managed, which means detached and reattached diff --git a/docs/meson.build b/docs/meson.build index 196f49a1a0..557cfdb3cf 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -18,7 +18,6 @@ docs_assets = [ ] docs_html_in_files = [ - 'formatnetwork', 'formatnode', 'index', 'remote', @@ -72,6 +71,7 @@ docs_rst_files = [ 'formatcheckpoint', 'formatdomain', 'formatdomaincaps', + 'formatnetwork', 'formatnetworkport', 'formatnwfilter', 'formatsecret', -- 2.35.1
The conversion also included a change to the layout of the document. Specifically the individual 'capabilty' types are now separated under individual headings rather than part of the original definition list. This reduces nesting but also esures that proper anchors are generated automatically. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvnodedev.rst | 4 +- docs/formatnode.html.in | 657 ---------------------------------------- docs/formatnode.rst | 556 ++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 4 files changed, 559 insertions(+), 660 deletions(-) delete mode 100644 docs/formatnode.html.in create mode 100644 docs/formatnode.rst diff --git a/docs/drvnodedev.rst b/docs/drvnodedev.rst index d333a9dca6..115d52ca02 100644 --- a/docs/drvnodedev.rst +++ b/docs/drvnodedev.rst @@ -143,7 +143,7 @@ A device capable of creating mediated devices will include a nested capability ``mdev_types`` which enumerates all supported mdev types on the physical device, along with the type attributes available through sysfs. A detailed description of the XML format for the ``mdev_types`` capability can be found -`here <formatnode.html#MDEVTypesCap>`__. +`here <formatnode.html#mdev-types-capability>`__. The following example shows how we might represent an NVIDIA GPU device that supports mediated devices. See below for more info on @@ -187,7 +187,7 @@ present on Linux-based systems (kernel version v2.6.26 is the first one to expose VPD via sysfs which Libvirt relies on). Reading the VPD contents requires root privileges, therefore, ``virsh nodedev-dumpxml`` must be executed accordingly. A description of the XML format for the ``vpd`` capability can be -found `here <formatnode.html#VPDCap>`__. +found `here <formatnode.html#vpd-capability>`__. The following example shows a VPD representation for a device that exposes the VPD capability with read-only and read-write fields. Among other things, the VPD diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in deleted file mode 100644 index 5a34a356ce..0000000000 --- a/docs/formatnode.html.in +++ /dev/null @@ -1,657 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Node devices XML format</h1> - - <ul id="toc"></ul> - - <h2><a id="NodedevAttributes">Node Device XML</a></h2> - - <p> - There are several libvirt functions, all with the - prefix <code>virNodeDevice</code>, which deal with management of - host devices that can be handed to guests via passthrough as - <hostdev> elements - in <a href="formatdomain.html#elementsHostDev">the domain XML</a>. - These devices are represented as a hierarchy, where a device on - a bus has a parent of the bus controller device; the root of the - hierarchy is the node named "computer". - </p> - - <p> - When represented in XML, a node device uses the - top-level <code>device</code> element, with the following - elements present according to the type of device: - </p> - <dl> - <dt><code>name</code></dt> - <dd>The name for this device. The name will be alphanumeric, - with words separated by underscore. For many devices, the - name is just the bus type and address, as in - "pci_0000_00_02_1" or "usb_1_5_3", but some devices are able - to provide more specific names, such as - "net_eth1_00_27_13_6a_fe_00". This is a read-only field that is - reported by the device driver. If this element is set when defining a - new device, it will be ignored. - - </dd> - <dt><code>path</code></dt> - <dd> - Fully qualified sysfs path to the device. This is a read-only field - that is reported by the device driver. If this element is set when - defining a new device, it will be ignored. - </dd> - <dt><code>parent</code></dt> - <dd> - This element identifies the parent node in the device hierarchy. The - value of the element will correspond with the device parent's - <code>name</code> element or <code>computer</code> if the device does - not have any parent. - </dd> - <dt><code>driver</code></dt> - <dd> - This elements reports the driver in use for this device. The presence - of this element in the output XML depends on whether the underlying - device manager (most likely udev) exposes information about the - driver. - </dd> - <dt><code>devnode</code></dt> - <dd>This node appears for each associated <code>/dev</code> - special file. A mandatory attribute <code>type</code> specify - the kind of file path, which may be either <code>dev</code> for - the main name, or <code>link</code> for additional symlinks. - </dd> - <dt><code>capability</code></dt> - <dd>This node appears for each capability that libvirt - associates with a node. A mandatory - attribute <code>type</code> lists which category the device - belongs to, and controls which further subelements will be - present to describe the node: - <dl> - <dt><code>system</code></dt> - <dd>Describes the overall host. Sub-elements include: - <dl> - <dt><code>product</code></dt> - <dd>If present, a simple text string giving the product - name of the system.</dd> - <dt><code>hardware</code></dt> - <dd>Describes the hardware of the system, including - sub-elements for <code>vendor</code>, <code>version</code>, - <code>serial</code>, and <code>uuid</code>.</dd> - <dt><code>firmware</code></dt> - <dd>Describes the firmware of the system, including - sub-elements for <code>vendor</code>, <code>version</code>, - and <code>release_date</code>.</dd> - </dl> - </dd> - <dt><code>pci</code></dt> - <dd>Describes a device on the host's PCI bus. Sub-elements - include: - <dl> - <dt><code>class</code></dt> - <dd>Optional element for combined class, subclass and - programming interface codes as 6-digit hexadecimal number. - <span class="since">Since 5.2.0</span></dd> - <dt><code>domain</code></dt> - <dd>Which domain the device belongs to.</dd> - <dt><code>bus</code></dt> - <dd>Which bus within the domain.</dd> - <dt><code>slot</code></dt> - <dd>Which slot within the bus.</dd> - <dt><code>function</code></dt> - <dd>Which function within the slot.</dd> - <dt><code>product</code></dt> - <dd>Product details from the device ROM, including an - attribute <code>id</code> with the hexadecimal product - id, and an optional text description of that id.</dd> - <dt><code>vendor</code></dt> - <dd>Vendor details from the device ROM, including an - attribute <code>id</code> with the hexadecimal vendor - id, and an optional text name of that vendor.</dd> - <dt><code>iommuGroup</code></dt> - <dd> - This optional element describes the "IOMMU group" this - device belongs to. If the element exists, it has a - mandatory <code>number</code> attribute which tells - the group number used for management of the group (all - devices in group "n" will be found in - "/sys/kernel/iommu_groups/n"). It will also have a - list of <code>address</code> subelements, each - containing the PCI address of a device in the same - group. The toplevel device will itself be included in - this list. - </dd> - <dt><code>capability</code></dt> - <dd> - This optional element can occur multiple times. If it - exists, it has a mandatory <code>type</code> attribute - which will be set to: - <dl> - <dt><code>phys_function</code></dt> - <dd> - That means there will be a single <code>address</code> - subelement which contains the PCI address of the SRIOV - Physical Function (PF) that is the parent of this device - (and this device is, by implication, an SRIOV Virtual - Function (VF)). - </dd> - <dt><code>virt_functions</code></dt> - <dd> - In this case this device is an SRIOV PF, and the capability - element will have a list of <code>address</code> - subelements, one for each VF on this PF. If the host system - supports reporting it (via the "sriov_totalvfs" file in the - device's sysfs directory) the capability element will also - have an attribute named <code>maxCount</code> which is the - maximum number of SRIOV VFs supported by this device, which - could be higher than the number of VFs that are currently - active <span class="since">since 1.3.0</span>; in this case, - even if there are currently no active VFs the - virtual_functions capabililty will still be shown. - </dd> - <dt><code>pci-bridge</code> or <code>cardbus-bridge</code></dt> - <dd> - This shows merely that the lower 7 bits of PCI header type - have either value of 1 or 2 respectively. Usually this - means such device cannot be used for PCI passthrough. - <span class="since">Since 1.3.3</span> - </dd> - <dt><code><a id="MDEVTypesCapPCI">mdev_types</a></code></dt> - <dd> - This device is capable of creating mediated devices. - The sub-elements are summarized in - <a href="#MDEVTypesCap">mdev_types capability</a>. - </dd> - <dt><code><a id="VPDCapPCI">vpd</a></code></dt> - <dd> - This device exposes a VPD PCI/PCIe capability. - The sub-elements are summarized in - <a href="#VPDCap">vpd capability</a>. - </dd> - </dl> - </dd> - - <dt><code>numa</code></dt> - <dd> - This optional element contains information on the PCI device - with respect to NUMA. For example, the optional - <code>node</code> attribute tells which NUMA node is the PCI - device associated with. - </dd> - <dt><code>pci-express</code></dt> - <dd> - This optional element contains information on PCI Express part of - the device. For example, it can contain a child element - <code>link</code> which addresses the PCI Express device's link. - While a device has its own capabilities - (<code>validity='cap'</code>), the actual run time capabilities - are negotiated on the device initialization - (<code>validity='sta'</code>). The <code>link</code> element then - contains three attributes: <code>port</code> which says in which - port is the device plugged in, <code>speed</code> (in - GigaTransfers per second) and <code>width</code> for the number - of lanes used. Since the port can't be negotiated, it's not - exposed in <code>./pci-express/link/[@validity='sta']</code>. - </dd> - </dl> - </dd> - <dt><code>usb_device</code></dt> - <dd>Describes a device on the host's USB bus, based on its - location within the bus. Sub-elements include: - <dl> - <dt><code>bus</code></dt> - <dd>Which bus the device belongs to.</dd> - <dt><code>device</code></dt> - <dd>Which device within the bus.</dd> - <dt><code>product</code></dt> - <dd>Product details from the device ROM, including an - attribute <code>id</code> with the hexadecimal product - id, and an optional text description of that id.</dd> - <dt><code>vendor</code></dt> - <dd>Vendor details from the device ROM, including an - attribute <code>id</code> with the hexadecimal vendor - id, and an optional text name of that vendor.</dd> - </dl> - </dd> - <dt><code>usb</code></dt> - <dd>Describes a USB device, based on its advertised driver - interface. Sub-elements include: - <dl> - <dt><code>number</code></dt> - <dd>The device number.</dd> - <dt><code>class</code></dt> - <dd>The device class.</dd> - <dt><code>subclass</code></dt> - <dd>The device subclass.</dd> - <dt><code>protocol</code></dt> - <dd>The device protocol.</dd> - <dt><code>description</code></dt> - <dd>If present, a description of the device.</dd> - </dl> - </dd> - <dt><code>net</code></dt> - <dd>Describes a device capable for use as a network - interface. Sub-elements include: - <dl> - <dt><code>interface</code></dt> - <dd>The interface name tied to this device.</dd> - <dt><code>address</code></dt> - <dd>If present, the MAC address of the device.</dd> - <dt><code>link</code></dt> - <dd>Optional to reflect the status of the link. It has - two optional attributes: <code>speed</code> in Mbits per - second and <code>state</code> to tell the state of the - link. So far, the whole element is just for output, - not setting. - </dd> - <dt><code>feature</code></dt> - <dd>If present, the hw offloads supported by this network - interface. Possible features are: - <dl> - <dt><code>rx</code></dt><dd>rx-checksumming</dd> - <dt><code>tx</code></dt><dd>tx-checksumming</dd> - <dt><code>sg</code></dt><dd>scatter-gather</dd> - <dt><code>tso</code></dt><dd>tcp-segmentation-offload</dd> - <dt><code>ufo</code></dt><dd>udp-fragmentation-offload</dd> - <dt><code>gso</code></dt><dd>generic-segmentation-offload</dd> - <dt><code>gro</code></dt><dd>generic-receive-offload</dd> - <dt><code>lro</code></dt><dd>large-receive-offload</dd> - <dt><code>rxvlan</code></dt><dd>rx-vlan-offload</dd> - <dt><code>txvlan</code></dt><dd>tx-vlan-offload</dd> - <dt><code>ntuple</code></dt><dd>ntuple-filters</dd> - <dt><code>rxhash</code></dt><dd>receive-hashing</dd> - <dt><code>rdma</code></dt><dd>remote-direct-memory-access</dd> - <dt><code>txudptnl</code></dt><dd>tx-udp-tunnel-segmentation</dd> - <dt><code>switchdev</code></dt><dd>kernel-forward-plane-offload</dd> - </dl> - </dd> - <dt><code>capability</code></dt> - <dd>A network protocol exposed by the device, where the - attribute <code>type</code> can be "80203" for IEEE - 802.3, or "80211" for various flavors of IEEE 802.11. - </dd> - </dl> - </dd> - <dt><code>scsi_host</code></dt> - <dd>Describes a SCSI host device. Sub-elements include: - <dl> - <dt><code>host</code></dt> - <dd>The SCSI host number.</dd> - <dt><code>unique_id</code></dt> - <dd>On input, this optionally provides the value from the - 'unique_id' file found in the scsi_host's directory. To - view the values of all 'unique_id' files, use <code>find -H - /sys/class/scsi_host/host{0..9}/unique_id | - xargs grep '[0-9]'</code>. On output, if the unique_id - file exists, the value from the file will be displayed. - This can be used in order to help uniquely identify the - scsi_host adapter in a <a href="formatstorage.html"> - Storage Pool</a>. <span class="since">Since 1.2.7</span> - </dd> - <dt><code>capability</code></dt> - <dd>Current capabilities include "vports_ops" (indicates - vport operations are supported) and "fc_host". "vport_ops" - could contain two optional sub-elements: <code>vports</code>, - and <code>max_vports</code>. <code>vports</code> shows the - number of vport in use. <code>max_vports</code> shows the - maximum vports the HBA supports. "fc_host" implies following - sub-elements: <code>wwnn</code>, <code>wwpn</code>, and - optionally <code>fabric_wwn</code>. - </dd> - </dl> - </dd> - <dt><code>scsi</code></dt> - <dd>Describes a SCSI device. Sub-elements include: - <dl> - <dt><code>host</code></dt> - <dd>The SCSI host containing the device.</dd> - <dt><code>bus</code></dt> - <dd>The bus within the host.</dd> - <dt><code>target</code></dt> - <dd>The target within the bus.</dd> - <dt><code>lun</code></dt> - <dd>The lun within the target.</dd> - <dt><code>type</code></dt> - <dd>The type of SCSI device.</dd> - </dl> - </dd> - <dt><code>storage</code></dt> - <dd>Describes a device usable for storage. Sub-elements - include: - <dl> - <dt><code>block</code></dt> - <dd>A block device file name that accesses the storage - present on the device.</dd> - <dt><code>bus</code></dt> - <dd>If present, the name of the bus the device is found - on.</dd> - <dt><code>drive_type</code></dt> - <dd>The type of the drive, such as "disk" or - "cdrom".</dd> - <dt><code>model</code></dt> - <dd>Any model information available from the - device.</dd> - <dt><code>vendor</code></dt> - <dd>Any vendor information available from the - device.</dd> - <dt><code>serial</code></dt> - <dd>Any serial number information available from the - device.</dd> - <dt><code>size</code></dt> - <dd>For fixed-size storage, the amount of storage - available.</dd> - <dt><code>capability</code></dt> - <dd>If present, an additional capability is listed via - the attribute <code>type</code>. Current capabilities - include "hotpluggable" and "removable", with the - latter implying the following - sub-elements: <code>media_available</code> (0 or - 1), <code>media_size</code>, - and <code>media_label</code>.</dd> - </dl> - </dd> - <dt><code>drm</code></dt> - <dd>Describes a Direct Rendering Manager (DRM) device. - Sub-elements include: - <dl> - <dt><code>type</code></dt> - <dd>The type of DRM device. Could be - <code>primary</code>, <code>control</code> or - <code>render</code>.</dd> - </dl> - </dd> - <dt><a id="mdev"><code>mdev</code></a></dt> - <dd>Describes a mediated device. <span class="since">Since - 3.4.0</span> Sub-elements include: - <dl> - <dt><code>type</code></dt> - <dd> - Describes a mediated device type which acts as an abstract - template defining a resource allocation for instances - of this device type. The element has one attribute - <code>id</code> which holds an official vendor-supplied - identifier for the type. - </dd> - <dt><code>iommuGroup</code></dt> - <dd> - This element supports a single attribute <code>number</code> - which holds the IOMMU group number to which the mediated device - belongs. This is a read-only field that is reported by the - device driver. - </dd> - <dt><code>attr</code></dt> - <dd> - This optional element can occur multiple times. It represents a - vendor-specific attribute that is used to configure this - mediated device. It has two required attributes: - <code>name</code> and <code>value</code>. Note that the order - in which attributes are set may be important for some devices. - The order that they appear in the xml definition determines the - order that they will be written to the device. - </dd> - <dt><code>uuid</code></dt> - <dd> - This element represents the UUID of the mediated device. - </dd> - </dl> - </dd> - <dt><code>ccw</code></dt> - <dd>Describes a Command Channel Word (CCW) device commonly found on - the S390 architecture. Sub-elements include: - <dl> - <dt><code>cssid</code></dt> - <dd>The channel subsystem identifier.</dd> - <dt><code>ssid</code></dt> - <dd>The subchannel-set identifier.</dd> - <dt><code>devno</code></dt> - <dd>The device number.</dd> - </dl> - </dd> - <dt><code>css</code></dt> - <dd>Describes a subchannel in the Channel SubSystem (CSS) commonly - found on the S390 architecture. Sub-elements include: - <dl> - <dt><code>cssid</code></dt> - <dd>The channel subsystem identifier.</dd> - <dt><code>ssid</code></dt> - <dd>The subchannel-set identifier.</dd> - <dt><code>devno</code></dt> - <dd>The subchannel number.</dd> - <dt><code>capability</code></dt> - <dd> - This optional element can occur multiple times. If it - exists, it has a mandatory <code>type</code> attribute - which will be set to: - <dl> - <dt><code><a id="MDEVTypesCapCSS">mdev_types</a></code></dt> - <dd> - <span class="since">Since 6.10.0</span> - This device is capable of creating mediated devices. - The sub-elements are summarized in - <a href="#MDevTypesCap">mdev_types capability</a>. - </dd> - </dl> - </dd> - </dl> - </dd> - <dt><code>vdpa</code></dt> - <dd>Describes a virtual datapath acceleration (vDPA) network device. - <span class="since">Since 6.9.0</span>. Sub-elements include: - <dl> - <dt><code>chardev</code></dt> - <dd>The path to the character device that is used to access the - device.</dd> - </dl> - </dd> - <dt><code>ap_card</code></dt> - <dd>Describes the Adjunct Processor (AP) Card device on a S390 host. - Sub-elements include: - <dl> - <dt><code>ap-adapter</code></dt> - <dd>AP Card identifier.</dd> - </dl> - </dd> - <dt><code>ap_queue</code></dt> - <dd>Describes the AP queue on a s390 host. An AP queue is - an AP domain on an AP adapter which is specified by an - adapter identifier and a domain identifier. - Sub-elements include: - <dl> - <dt><code>ap-adapter</code></dt> - <dd>The ap-adapter of an AP queue identifies the AP - card to which this AP queue belongs.</dd> - <dt><code>ap-domain</code></dt> - <dd>The ap-domain of an AP queue identifies the AP - domain to which this AP queue belongs.</dd> - <dd>AP Queue identifier.</dd> - </dl> - </dd> - <dt><code>ap_matrix</code></dt> - <dd>Describes an AP Matrix device on a S390 architecture providing - cryptographic host resources usable for virtualization. - Sub-elements include: - <dl> - <dt><code>capability</code></dt> - <dd> - This optional element can occur multiple times. If it - exists, it has a mandatory <code>type</code> attribute - which will be set to: - <dl> - <dt><code><a id="MDEVTypesCapAP">mdev_types</a></code></dt> - <dd> - <span class="since">Since 6.10.0</span> - This device is capable of creating mediated devices. - The sub-elements are summarized in - <a href="#MDEVTypesCap">mdev_types capability</a>. - </dd> - </dl> - </dd> - </dl> - </dd> - </dl> - </dd> - </dl> - - <h3><a id="MDEVTypesCap">mdev_types capability</a></h3> - - <p> - <a href="#MDEVTypesCapPCI">PCI</a>, <a href="#MDEVTypesCapCSS">CSS</a> - and <a href="#MDEVTypesCapAP">AP Matrix</a> - devices can be capable of creating mediated devices. - If they indeed are capable, then the parent <code>capability</code> - element for <code>mdev_types</code> type will contain a list of - <code>type</code> elements, which list all mdev types supported - on the physical device. <span class="since">Since 3.4.0</span> - Each <code>type</code> element has a single <code>id</code> - attribute that holds an official vendor-supplied identifier - for the type. It supports the following sub-elements: - <dl> - <dt><code>name</code></dt> - <dd> - The <code>name</code> element holds a vendor-supplied - code name for the given mediated device type. This is - an optional element. - </dd> - <dt><code>deviceAPI</code></dt> - <dd> - The value of this element describes how an instance of - the given type will be presented to the guest by the - VFIO framework. - </dd> - <dt><code>availableInstances</code></dt> - <dd> - This element reports the current state of resource - allocation. In other words, how many instances of the - given type can still be successfully created on the - physical device. - </dd> - </dl> - </p> - - <h3><a id="VPDCap">vpd capability</a></h3> - - <p> - <a href="#VPDCapPCI">PCI</a> devices can expose a VPD capability which - is optional per PCI Local Bus 2.2+ and PCIe 4.0+ specifications. If - the VPD capability is present, then the parent <code>capability</code> - element with the <code>vpd</code> type will contain a <code>name</code> - element (containing a manufacturer-provided device name) and optionally - one or two <code>fields</code> elements with an <code>access</code> - attribute set to <code>readonly</code> or <code>readwrite</code>. - </p> - <p> - The read-only <code>fields</code> element may contain the following elements: - <dl> - <dt><code>change_level</code></dt> - <dd>An engineering change level for this add-in card.</dd> - <dt><code>manufacture_id</code></dt> - <dd>An extension to the Vendor ID (or Subsystem Vendor ID) in the - Configuration Space header which allows vendors the flexibility to identify - an additional level of detail pertaining to the sourcing of a PCI device.</dd> - <dt><code>part_number</code></dt> - <dd>An extension to the Device ID (or Subsystem ID) in the Configuration - Space header specifying a part number of an add-in card.</dd> - <dt><code>serial_number</code></dt> - <dd>A unique add-in card Serial Number.</dd> - <dt><code>vendor_field</code></dt> - <dd>Zero or many of those elements with an <code>index</code> attribute - (since-character upper-case ASCII alphanumeric indexes). Contents will vary - depending on a vendor.</dd> - </dl> - All fields are optional and are not guaranteed to be present for a generic PCI device. - </p> - <p> - The read-write <code>fields</code> element may contain the following elements: - <dl> - <dt><code>asset_tag</code></dt> - <dd>A system asset identifier provided by the system owner.</dd> - <dt><code>vendor_field</code></dt> - <dd>Zero or many of those elements with an <code>index</code> attribute - (since-character upper-case ASCII alphanumeric indexes). Contents will vary depending - on a vendor.</dd> - <dt><code>system_field</code></dt> - <dd>Zero or many of those elements with an <code>index</code> attribute (since-character - upper-case ASCII alphanumeric indexes, except for letter 'A'). May store system-specific - data related to a PCI device.</dd> - </dl> - All fields are optional and are not guaranteed to be present for a generic PCI device. - Read-write fields are not possible to alter via Libvirt at the time of writing but their - content is refreshed on each invocation in case this is done by means external to Libvirt. - </p> - <p> - The device name and all fields may contain only the following characters: - <code>[0-9a-zA-F -_,.:;=]</code>. - The device name may be as large as 65535 bytes while fields are limited with 255 bytes. - </p> - - <h2><a id="nodeExample">Examples</a></h2> - - <p>The following are some example node device XML outputs:</p> - <pre> -<device> - <name>computer</name> - <capability type='system'> - <product>2241B36</product> - <hardware> - <vendor>LENOVO</vendor> - <version>ThinkPad T500</version> - <serial>R89055N</serial> - <uuid>c9488981-5049-11cb-9c1c-993d0230b4cd</uuid> - </hardware> - <firmware> - <vendor>LENOVO</vendor> - <version>6FET82WW (3.12 )</version> - <release_date>11/26/2009</release_date> - </firmware> - </capability> -</device> - -<device> - <name>net_eth1_00_27_13_6a_fe_00</name> - <parent>pci_0000_00_19_0</parent> - <capability type='net'> - <interface>eth1</interface> - <address>00:27:13:6a:fe:00</address> - <capability type='80203'/> - </capability> -</device> - -<device> - <name>pci_0000_02_00_0</name> - <path>/sys/devices/pci0000:00/0000:00:04.0/0000:02:00.0</path> - <parent>pci_0000_00_04_0</parent> - <driver> - <name>igb</name> - </driver> - <capability type='pci'> - <class>0x020000</class> - <domain>0</domain> - <bus>2</bus> - <slot>0</slot> - <function>0</function> - <product id='0x10c9'>82576 Gigabit Network Connection</product> - <vendor id='0x8086'>Intel Corporation</vendor> - <capability type='virt_functions'> - <address domain='0x0000' bus='0x02' slot='0x10' function='0x0'/> - <address domain='0x0000' bus='0x02' slot='0x10' function='0x2'/> - <address domain='0x0000' bus='0x02' slot='0x10' function='0x4'/> - <address domain='0x0000' bus='0x02' slot='0x10' function='0x6'/> - <address domain='0x0000' bus='0x02' slot='0x11' function='0x0'/> - <address domain='0x0000' bus='0x02' slot='0x11' function='0x2'/> - <address domain='0x0000' bus='0x02' slot='0x11' function='0x4'/> - </capability> - <iommuGroup number='12'> - <address domain='0x0000' bus='0x02' slot='0x00' function='0x0'/> - <address domain='0x0000' bus='0x02' slot='0x00' function='0x1'/> - </iommuGroup> - <pci-express> - <link validity='cap' port='1' speed='2.5' width='1'/> - <link validity='sta' speed='2.5' width='1'/> - </pci-express> - </capability> -</device> - </pre> - - </body> -</html> diff --git a/docs/formatnode.rst b/docs/formatnode.rst new file mode 100644 index 0000000000..ec3d529fff --- /dev/null +++ b/docs/formatnode.rst @@ -0,0 +1,556 @@ +.. role:: since + +======================= +Node devices XML format +======================= + +.. contents:: + +Node Device XML +--------------- + +There are several libvirt functions, all with the prefix ``virNodeDevice``, +which deal with management of host devices that can be handed to guests via +passthrough as <hostdev> elements in `the domain +XML <formatdomain.html#elementsHostDev>`__. These devices are represented as a +hierarchy, where a device on a bus has a parent of the bus controller device; +the root of the hierarchy is the node named "computer". + +When represented in XML, a node device uses the top-level ``device`` element, +with the following elements present according to the type of device: + +``name`` + The name for this device. The name will be alphanumeric, with words separated + by underscore. For many devices, the name is just the bus type and address, + as in "pci_0000_00_02_1" or "usb_1_5_3", but some devices are able to provide + more specific names, such as "net_eth1_00_27_13_6a_fe_00". This is a + read-only field that is reported by the device driver. If this element is set + when defining a new device, it will be ignored. +``path`` + Fully qualified sysfs path to the device. This is a read-only field that is + reported by the device driver. If this element is set when defining a new + device, it will be ignored. +``parent`` + This element identifies the parent node in the device hierarchy. The value of + the element will correspond with the device parent's ``name`` element or + ``computer`` if the device does not have any parent. +``driver`` + This elements reports the driver in use for this device. The presence of this + element in the output XML depends on whether the underlying device manager + (most likely udev) exposes information about the driver. +``devnode`` + This node appears for each associated ``/dev`` special file. A mandatory + attribute ``type`` specify the kind of file path, which may be either ``dev`` + for the main name, or ``link`` for additional symlinks. +``capability`` + This node appears for each capability that libvirt associates with a node. A + mandatory attribute ``type`` lists which category the device belongs to. + The `capability types`_ section below describes them further. + +``capability`` types +~~~~~~~~~~~~~~~~~~~~ + +Based on the capbility type there are further more specific attributes to a +device described below. + +``system`` +^^^^^^^^^^ + +Describes the overall host. Sub-elements include: + +``product`` + If present, a simple text string giving the product name of the system. +``hardware`` + Describes the hardware of the system, including sub-elements for + ``vendor``, ``version``, ``serial``, and ``uuid``. +``firmware`` + Describes the firmware of the system, including sub-elements for + ``vendor``, ``version``, and ``release_date``. + +``pci`` +^^^^^^^ + +Describes a device on the host's PCI bus. Sub-elements include: + +``class`` + Optional element for combined class, subclass and programming interface + codes as 6-digit hexadecimal number. :since:`Since 5.2.0` +``domain`` + Which domain the device belongs to. +``bus`` + Which bus within the domain. +``slot`` + Which slot within the bus. +``function`` + Which function within the slot. +``product`` + Product details from the device ROM, including an attribute ``id`` with + the hexadecimal product id, and an optional text description of that + id. +``vendor`` + Vendor details from the device ROM, including an attribute ``id`` with + the hexadecimal vendor id, and an optional text name of that vendor. +``iommuGroup`` + This optional element describes the "IOMMU group" this device belongs + to. If the element exists, it has a mandatory ``number`` attribute + which tells the group number used for management of the group (all + devices in group "n" will be found in "/sys/kernel/iommu_groups/n"). It + will also have a list of ``address`` subelements, each containing the + PCI address of a device in the same group. The toplevel device will + itself be included in this list. +``capability`` + This optional element can occur multiple times. If it exists, it has a + mandatory ``type`` attribute which will be set to: + + ``phys_function`` + That means there will be a single ``address`` subelement which + contains the PCI address of the SRIOV Physical Function (PF) that is + the parent of this device (and this device is, by implication, an + SRIOV Virtual Function (VF)). + ``virt_functions`` + In this case this device is an SRIOV PF, and the capability element + will have a list of ``address`` subelements, one for each VF on this + PF. If the host system supports reporting it (via the + "sriov_totalvfs" file in the device's sysfs directory) the + capability element will also have an attribute named ``maxCount`` + which is the maximum number of SRIOV VFs supported by this device, + which could be higher than the number of VFs that are currently + active :since:`since 1.3.0` ; in this case, even if there are + currently no active VFs the virtual_functions capabililty will still + be shown. + ``pci-bridge`` or ``cardbus-bridge`` + This shows merely that the lower 7 bits of PCI header type have + either value of 1 or 2 respectively. Usually this means such device + cannot be used for PCI passthrough. :since:`Since 1.3.3` + ``mdev_types`` + This device is capable of creating mediated devices. The + sub-elements are summarized in `mdev_types capability`_. + ``vpd`` + This device exposes a VPD PCI/PCIe capability. The sub-elements are + summarized in `vpd capability`_. +``numa`` + This optional element contains information on the PCI device with + respect to NUMA. For example, the optional ``node`` attribute tells + which NUMA node is the PCI device associated with. +``pci-express`` + This optional element contains information on PCI Express part of the + device. For example, it can contain a child element ``link`` which + addresses the PCI Express device's link. While a device has its own + capabilities (``validity='cap'``), the actual run time capabilities are + negotiated on the device initialization (``validity='sta'``). The + ``link`` element then contains three attributes: ``port`` which says in + which port is the device plugged in, ``speed`` (in GigaTransfers per + second) and ``width`` for the number of lanes used. Since the port + can't be negotiated, it's not exposed in + ``./pci-express/link/[`validity='sta']``. + +``usb_device`` +^^^^^^^^^^^^^^ + +Describes a device on the host's USB bus, based on its location within the bus. +Sub-elements include: + +``bus`` + Which bus the device belongs to. +``device`` + Which device within the bus. +``product`` + Product details from the device ROM, including an attribute ``id`` with + the hexadecimal product id, and an optional text description of that + id. +``vendor`` + Vendor details from the device ROM, including an attribute ``id`` with + the hexadecimal vendor id, and an optional text name of that vendor. + +``usb`` +^^^^^^^ + +Describes a USB device, based on its advertised driver interface. Sub-elements +include: + +``number`` + The device number. +``class`` + The device class. +``subclass`` + The device subclass. +``protocol`` + The device protocol. +``description`` + If present, a description of the device. + +``net`` +^^^^^^^ + +Describes a device capable for use as a network interface. Sub-elements +include: + +``interface`` + The interface name tied to this device. +``address`` + If present, the MAC address of the device. +``link`` + Optional to reflect the status of the link. It has two optional + attributes: ``speed`` in Mbits per second and ``state`` to tell the + state of the link. So far, the whole element is just for output, not + setting. +``feature`` + If present, the hw offloads supported by this network interface. + Possible features are: + + ``rx`` + rx-checksumming + ``tx`` + tx-checksumming + ``sg`` + scatter-gather + ``tso`` + tcp-segmentation-offload + ``ufo`` + udp-fragmentation-offload + ``gso`` + generic-segmentation-offload + ``gro`` + generic-receive-offload + ``lro`` + large-receive-offload + ``rxvlan`` + rx-vlan-offload + ``txvlan`` + tx-vlan-offload + ``ntuple`` + ntuple-filters + ``rxhash`` + receive-hashing + ``rdma`` + remote-direct-memory-access + ``txudptnl`` + tx-udp-tunnel-segmentation + ``switchdev`` + kernel-forward-plane-offload +``capability`` + A network protocol exposed by the device, where the attribute ``type`` + can be "80203" for IEEE 802.3, or "80211" for various flavors of IEEE + 802.11. + +``scsi_host`` +^^^^^^^^^^^^^ + +Describes a SCSI host device. Sub-elements include: + +``host`` + The SCSI host number. +``unique_id`` + On input, this optionally provides the value from the 'unique_id' file + found in the scsi_host's directory. To view the values of all + 'unique_id' files, use + ``find -H /sys/class/scsi_host/host{0..9}/unique_id | xargs grep '[0-9]'``. + On output, if the unique_id file exists, the value from the file will + be displayed. This can be used in order to help uniquely identify the + scsi_host adapter in a `Storage Pool <formatstorage.html>`__. + :since:`Since 1.2.7` +``capability`` + Current capabilities include "vports_ops" (indicates vport operations + are supported) and "fc_host". "vport_ops" could contain two optional + sub-elements: ``vports``, and ``max_vports``. ``vports`` shows the + number of vport in use. ``max_vports`` shows the maximum vports the HBA + supports. "fc_host" implies following sub-elements: ``wwnn``, ``wwpn``, + and optionally ``fabric_wwn``. + +``scsi`` +^^^^^^^^ + +Describes a SCSI device. Sub-elements include: + +``host`` + The SCSI host containing the device. +``bus`` + The bus within the host. +``target`` + The target within the bus. +``lun`` + The lun within the target. +``type`` + The type of SCSI device. + +``storage`` +^^^^^^^^^^^ + +Describes a device usable for storage. Sub-elements include: + +``block`` + A block device file name that accesses the storage present on the + device. +``bus`` + If present, the name of the bus the device is found on. +``drive_type`` + The type of the drive, such as "disk" or "cdrom". +``model`` + Any model information available from the device. +``vendor`` + Any vendor information available from the device. +``serial`` + Any serial number information available from the device. +``size`` + For fixed-size storage, the amount of storage available. +``capability`` + If present, an additional capability is listed via the attribute + ``type``. Current capabilities include "hotpluggable" and "removable", + with the latter implying the following sub-elements: + ``media_available`` (0 or 1), ``media_size``, and ``media_label``. + +``drm`` +^^^^^^^ + +Describes a Direct Rendering Manager (DRM) device. Sub-elements include: + +``type`` + The type of DRM device. Could be ``primary``, ``control`` or ``render``. + +``mdev`` +^^^^^^^^ + +Describes a mediated device. :since:`Since 3.4.0` Sub-elements include: + +``type`` + Describes a mediated device type which acts as an abstract template + defining a resource allocation for instances of this device type. The + element has one attribute ``id`` which holds an official + vendor-supplied identifier for the type. +``iommuGroup`` + This element supports a single attribute ``number`` which holds the + IOMMU group number to which the mediated device belongs. This is a + read-only field that is reported by the device driver. +``attr`` + This optional element can occur multiple times. It represents a + vendor-specific attribute that is used to configure this mediated + device. It has two required attributes: ``name`` and ``value``. Note + that the order in which attributes are set may be important for some + devices. The order that they appear in the xml definition determines + the order that they will be written to the device. +``uuid`` + This element represents the UUID of the mediated device. + +``ccw`` +^^^^^^^ + +Describes a Command Channel Word (CCW) device commonly found on the S390 +architecture. Sub-elements include: + +``cssid`` + The channel subsystem identifier. +``ssid`` + The subchannel-set identifier. +``devno`` + The device number. + +``css`` +^^^^^^^ + +Describes a subchannel in the Channel SubSystem (CSS) commonly found on the +S390 architecture. Sub-elements include: + +``cssid`` + The channel subsystem identifier. +``ssid`` + The subchannel-set identifier. +``devno`` + The subchannel number. +``capability`` + This optional element can occur multiple times. If it exists, it has a + mandatory ``type`` attribute which will be set to: + + ``mdev_types`` + :since:`Since 6.10.0` This device is capable of creating mediated + devices. The sub-elements are summarized in `mdev_types capability`_. + +``vdpa`` +^^^^^^^^ + +Describes a virtual datapath acceleration (vDPA) network device. :since:`Since +6.9.0` . Sub-elements include: + +``chardev`` + The path to the character device that is used to access the device. + +``ap_card`` +^^^^^^^^^^^ + +Describes the Adjunct Processor (AP) Card device on a S390 host. Sub-elements +include: + +``ap-adapter`` + AP Card identifier. + +``ap_queue`` +^^^^^^^^^^^^ + +Describes the AP queue on a s390 host. An AP queue is an AP domain on an AP +adapter which is specified by an adapter identifier and a domain identifier. +Sub-elements include: + +``ap-adapter`` + The ap-adapter of an AP queue identifies the AP card to which this AP + queue belongs. +``ap-domain`` + The ap-domain of an AP queue identifies the AP domain to which this AP + queue belongs. + AP Queue identifier. + +``ap_matrix`` +^^^^^^^^^^^^^ + +Describes an AP Matrix device on a S390 architecture providing cryptographic +host resources usable for virtualization. Sub-elements include: + +``capability`` + This optional element can occur multiple times. If it exists, it has a + mandatory ``type`` attribute which will be set to: + + ``mdev_types`` + :since:`Since 6.10.0` This device is capable of creating mediated + devices. The sub-elements are summarized in `mdev_types capability`_ + +``mdev_types`` capability +~~~~~~~~~~~~~~~~~~~~~~~~~ + +`pci`_, `css`_ and `ap_matrix`_ devices can be capable of creating mediated +devices. If they indeed are capable, then the parent ``capability`` element for +``mdev_types`` type will contain a list of ``type`` elements, which list all +mdev types supported on the physical device. :since:`Since 3.4.0` Each ``type`` +element has a single ``id`` attribute that holds an official vendor-supplied +identifier for the type. It supports the following sub-elements: + +``name`` + The ``name`` element holds a vendor-supplied code name for the given mediated + device type. This is an optional element. +``deviceAPI`` + The value of this element describes how an instance of the given type will be + presented to the guest by the VFIO framework. +``availableInstances`` + This element reports the current state of resource allocation. In other + words, how many instances of the given type can still be successfully created + on the physical device. + +``vpd`` capability +~~~~~~~~~~~~~~~~~~ + +`pci`_ devices can expose a VPD capability which is optional per +PCI Local Bus 2.2+ and PCIe 4.0+ specifications. If the VPD capability is +present, then the parent ``capability`` element with the ``vpd`` type will +contain a ``name`` element (containing a manufacturer-provided device name) and +optionally one or two ``fields`` elements with an ``access`` attribute set to +``readonly`` or ``readwrite``. + +The read-only ``fields`` element may contain the following elements: + +``change_level`` + An engineering change level for this add-in card. +``manufacture_id`` + An extension to the Vendor ID (or Subsystem Vendor ID) in the Configuration + Space header which allows vendors the flexibility to identify an additional + level of detail pertaining to the sourcing of a PCI device. +``part_number`` + An extension to the Device ID (or Subsystem ID) in the Configuration Space + header specifying a part number of an add-in card. +``serial_number`` + A unique add-in card Serial Number. +``vendor_field`` + Zero or many of those elements with an ``index`` attribute (since-character + upper-case ASCII alphanumeric indexes). Contents will vary depending on a + vendor. + +All fields are optional and are not guaranteed to be present for a generic PCI +device. + +The read-write ``fields`` element may contain the following elements: + +``asset_tag`` + A system asset identifier provided by the system owner. +``vendor_field`` + Zero or many of those elements with an ``index`` attribute (since-character + upper-case ASCII alphanumeric indexes). Contents will vary depending on a + vendor. +``system_field`` + Zero or many of those elements with an ``index`` attribute (since-character + upper-case ASCII alphanumeric indexes, except for letter 'A'). May store + system-specific data related to a PCI device. + +All fields are optional and are not guaranteed to be present for a generic PCI +device. Read-write fields are not possible to alter via Libvirt at the time of +writing but their content is refreshed on each invocation in case this is done +by means external to Libvirt. + +The device name and all fields may contain only the following characters: +``[0-9a-zA-F -_,.:;=]``. The device name may be as large as 65535 bytes while +fields are limited with 255 bytes. + +Examples +-------- + +The following are some example node device XML outputs: + +:: + + <device> + <name>computer</name> + <capability type='system'> + <product>2241B36</product> + <hardware> + <vendor>LENOVO</vendor> + <version>ThinkPad T500</version> + <serial>R89055N</serial> + <uuid>c9488981-5049-11cb-9c1c-993d0230b4cd</uuid> + </hardware> + <firmware> + <vendor>LENOVO</vendor> + <version>6FET82WW (3.12 )</version> + <release_date>11/26/2009</release_date> + </firmware> + </capability> + </device> + + <device> + <name>net_eth1_00_27_13_6a_fe_00</name> + <parent>pci_0000_00_19_0</parent> + <capability type='net'> + <interface>eth1</interface> + <address>00:27:13:6a:fe:00</address> + <capability type='80203'/> + </capability> + </device> + + <device> + <name>pci_0000_02_00_0</name> + <path>/sys/devices/pci0000:00/0000:00:04.0/0000:02:00.0</path> + <parent>pci_0000_00_04_0</parent> + <driver> + <name>igb</name> + </driver> + <capability type='pci'> + <class>0x020000</class> + <domain>0</domain> + <bus>2</bus> + <slot>0</slot> + <function>0</function> + <product id='0x10c9'>82576 Gigabit Network Connection</product> + <vendor id='0x8086'>Intel Corporation</vendor> + <capability type='virt_functions'> + <address domain='0x0000' bus='0x02' slot='0x10' function='0x0'/> + <address domain='0x0000' bus='0x02' slot='0x10' function='0x2'/> + <address domain='0x0000' bus='0x02' slot='0x10' function='0x4'/> + <address domain='0x0000' bus='0x02' slot='0x10' function='0x6'/> + <address domain='0x0000' bus='0x02' slot='0x11' function='0x0'/> + <address domain='0x0000' bus='0x02' slot='0x11' function='0x2'/> + <address domain='0x0000' bus='0x02' slot='0x11' function='0x4'/> + </capability> + <iommuGroup number='12'> + <address domain='0x0000' bus='0x02' slot='0x00' function='0x0'/> + <address domain='0x0000' bus='0x02' slot='0x00' function='0x1'/> + </iommuGroup> + <pci-express> + <link validity='cap' port='1' speed='2.5' width='1'/> + <link validity='sta' speed='2.5' width='1'/> + </pci-express> + </capability> + </device> diff --git a/docs/meson.build b/docs/meson.build index 557cfdb3cf..eff3813cd6 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -18,7 +18,6 @@ docs_assets = [ ] docs_html_in_files = [ - 'formatnode', 'index', 'remote', 'storage', @@ -73,6 +72,7 @@ docs_rst_files = [ 'formatdomaincaps', 'formatnetwork', 'formatnetworkport', + 'formatnode', 'formatnwfilter', 'formatsecret', 'formatsnapshot', -- 2.35.1
On Wed, Apr 13, 2022 at 18:02:01 +0200, Peter Krempa wrote:
This series corrects some mistakes from previous conversions (local anchor links, ordering of input files) and finishes the conversion of format* documents.
Output of the CI pipeline for the converted documents: https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2332431482/artifacts/website/form... https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2332431482/artifacts/website/form... https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2332431482/artifacts/website/form... https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2332431482/artifacts/website/form...
On 4/13/22 18:02, Peter Krempa wrote:
This series corrects some mistakes from previous conversions (local anchor links, ordering of input files) and finishes the conversion of format* documents.
Pavel Hrdina (1): docs: Convert 'formatnwfilter' page to rst
Peter Krempa (13): docs: meson: Sort list of RST files to build docs: api: Fix local anchor links docs: drivers: Fix local anchor links docs: drvbhve: Fix local anchor links docs: drvesx: Fix local anchor links docs: drvnodedev: Fix local anchor links docs: drvsecret: Fix local anchor links docs: kbase/launch_security_sev: Fix local anchor links docs: kbase/tlscerts: Fix local anchor links docs: pci-hotplug: Fix local anchor links docs: Convert 'formatcaps' page to rst docs: Convert 'formatnetwork' page to rst docs: Convert 'formatnode' page to rst
docs/api.rst | 5 +- docs/drivers.rst | 2 +- docs/drvbhyve.rst | 6 +- docs/drvesx.rst | 19 +- docs/drvnodedev.rst | 20 +- docs/firewall.rst | 2 +- docs/formatcaps.html.in | 222 --- docs/formatcaps.rst | 197 +++ docs/formatdomain.rst | 7 +- docs/formatnetwork.html.in | 1479 ----------------- docs/formatnetwork.rst | 1144 +++++++++++++ docs/formatnetworkport.rst | 2 +- docs/formatnode.html.in | 657 -------- docs/formatnode.rst | 556 +++++++ docs/formatnwfilter.html.in | 2471 ---------------------------- docs/formatnwfilter.rst | 1789 ++++++++++++++++++++ docs/formatsecret.rst | 16 +- docs/kbase/launch_security_sev.rst | 2 +- docs/kbase/tlscerts.rst | 7 +- docs/manpages/virsh.rst | 5 +- docs/meson.build | 12 +- docs/pci-hotplug.rst | 5 +- 22 files changed, 3742 insertions(+), 4883 deletions(-) delete mode 100644 docs/formatcaps.html.in create mode 100644 docs/formatcaps.rst delete mode 100644 docs/formatnetwork.html.in create mode 100644 docs/formatnetwork.rst delete mode 100644 docs/formatnode.html.in create mode 100644 docs/formatnode.rst delete mode 100644 docs/formatnwfilter.html.in create mode 100644 docs/formatnwfilter.rst
Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Michal
participants (2)
-
Michal Prívozník -
Peter Krempa