From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865774; cv=none; d=zohomail.com; s=zohoarc; b=j7+671wuAX9gYtzW0NjX7hxfvjjE8ugLQY7vvRgNHLcUS6asGaYr2InP+DYgLfaLWD31bNfio/4ajfnKu8kj0XQYNON0PeRp6GeP/WYfOTABnkPHzjnUzXNZ5uN/6NrsG/xVpQc1WyKntyF1TJ/S1Hk1AxCNU6eRes4D3pKLTKE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865774; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=nsUCZotXu8aMrrKtwC/l7YZQiL3Q7KuQK5L9ecI5O4s=; b=FrRI3oO1bHyYraffe9Oz1j+IHW1K9ZvvL9c4iucv3rAqVsKfmLACcYO8RTz5GMfMO2VXOUgSghIkTJh1CfZzOINsbpZrLT/K82/T7UWAccmdugl4+KL1ceBOAu3RMX0fer/GxtpCN4GeUjOyhFq0XsJNN/Uy9DwgYfc8PjU6e+I= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865774254596.159180996295; Wed, 13 Apr 2022 09:02:54 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-554-OFSmWKKtOpSjOtD4WB7g9g-1; Wed, 13 Apr 2022 12:02:43 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 0D5A81C05AB9; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3466E141511C; Wed, 13 Apr 2022 16:02:21 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 391A1193F6E0; Wed, 13 Apr 2022 16:02:19 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 58ED01940340 for ; Wed, 13 Apr 2022 16:02:18 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 4F0441457F13; Wed, 13 Apr 2022 16:02:18 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id CED2F141511C for ; Wed, 13 Apr 2022 16:02:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865773; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=nsUCZotXu8aMrrKtwC/l7YZQiL3Q7KuQK5L9ecI5O4s=; b=jBIv+fImOc6U7EJqWCmJe/NcbkxiLceWQpTZ2TC2gmMnJvdRT6M+k7y83sQSH9oqug3ZWZ jRGDV/KZGX+sSh3W8oWGFXxKxBzEnUFLsuXpPMB9osXCSvh/hqO06ruc7LvXoELfgyNkZ4 4au1rjExi0rswBxQHZbym1KZGw6WmB8= X-MC-Unique: OFSmWKKtOpSjOtD4WB7g9g-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 01/14] docs: meson: Sort list of RST files to build Date: Wed, 13 Apr 2022 18:02:02 +0200 Message-Id: <840e04a493a6674557d30c852f9728805983d529.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865775419100001 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa Reviewed-by: Michal Privoznik --- 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 =3D [ 'formatbackup', 'formatcheckpoint', 'formatdomain', - 'formatnetworkport', 'formatdomaincaps', + 'formatnetworkport', 'formatsecret', 'formatsnapshot', 'formatstorage', - 'formatstorageencryption', 'formatstoragecaps', + 'formatstorageencryption', 'glib-adoption', 'goals', 'governance', --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865781; cv=none; d=zohomail.com; s=zohoarc; b=DmdWMveyceUOt17hYTnNjfA0HGu/9pI9078/58E+N8qua1qXNrPEcdhtPwa6I4RJsPtYU08NKR5nENaWYmGduVpmJeW42MUI2Kfmidz5B/PaVWrsIFPlhJK3yMaHtAbjnwbtSm+RmC1nLJkPxquvw99SepXsj5kHNdjOfC4nPtU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865781; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=TVvaBS6k1GbGAWHM4FJI75etM01prtO1nZhwMsfZFD8=; b=h43XHr/jHui4E3wbThh1e6q3ktll3Qgy+GWFBrghwp3Tv1Wko2sExFCyJXbCktc7lGAdTDepvQbes2F8YUuJh/fgyKYaXwVHwH3h/vE6PI5VnOMDjZEdHYMOUDitDlgmbDVYaB6bbjM+YXwkfGwi7imRXadrPpNpi5B4TNU/KUU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1649865781202905.1671860867906; Wed, 13 Apr 2022 09:03:01 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-81-fbui-8_hN-mbbYPAVlZy0w-1; Wed, 13 Apr 2022 12:02:57 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3E6CA3C23FD4; Wed, 13 Apr 2022 16:02:23 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2008DC44CCA; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id C22A8193F50A; Wed, 13 Apr 2022 16:02:19 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 56212193F6EA for ; Wed, 13 Apr 2022 16:02:19 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 396E61457F13; Wed, 13 Apr 2022 16:02:19 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id A8BB8141511C for ; Wed, 13 Apr 2022 16:02:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865780; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=TVvaBS6k1GbGAWHM4FJI75etM01prtO1nZhwMsfZFD8=; b=hGdxQ7BLpjM7MsrohIrtgCJLtpqW5NQxRSQFqzfW1Kc/DD0Dmq9vFA8NKVucbKGqpC8u+w aYBUaI/WU0R7CbbV8/s8SujS+tBatyhRYg2ro5itz9Ragec6kHmHI9DdiUwoCxI9SuJu7A 3b2/X8rPoxBSBuTPv4KxKxvcb3OH4FA= X-MC-Unique: fbui-8_hN-mbbYPAVlZy0w-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 02/14] docs: api: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:03 +0200 Message-Id: <9219e1d1d94b9d69357e808ee00f09a82b8b9668.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865781410100001 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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 `__ use a `= URI `__ 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 rem= ote 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 --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865784; cv=none; d=zohomail.com; s=zohoarc; b=OXXIAOEKnx1y27eHvbwwT0Wzwa31yVmmzLmydsxxvNSDVjRtn8gyvlonRY5etI1CL0FyNNtp2+51qjpqowABOaIsTKlAm7lLFQc20AyF4YOZFN1BzUnb/6IZCSMayaVnvmnU0xC/UrVw3Rr01rapPqGCtNktbKG5LlC0WrkZ0Ss= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865784; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=dQN3Qu6rOFqvSF2hnYn18ZE7cCfAptsRvXCcNzj9w+E=; b=oJlGdz/bUCwvzIDRIMepX4LULxf4xREenz4qIjLqDcv7cCEAR6yoHG36ieT208VEc/iUrUg7H+tCr8L41IEl286dMO3sUiEZmyJTfNDuZYLJXc4zaX0AiEsKfZBFo4KaU1zVlnGicloJYSd5rWTqBXXfwTrAs4m1NNvuGvqXozg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865784076552.9814982794823; Wed, 13 Apr 2022 09:03:04 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-564-1s7MhyIwPtuBZ9vWwmMBBw-1; Wed, 13 Apr 2022 12:02:54 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 148593841D5C; Wed, 13 Apr 2022 16:02:23 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0075A40CF8EA; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 130AC1940373; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 321D41940373 for ; Wed, 13 Apr 2022 16:02:20 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 201B3145BA5B; Wed, 13 Apr 2022 16:02:20 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9D528145B993 for ; Wed, 13 Apr 2022 16:02:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865783; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=dQN3Qu6rOFqvSF2hnYn18ZE7cCfAptsRvXCcNzj9w+E=; b=DmIwxMonVj4tW/unnURqPEjt5jcRpFF/l9DgSk01xBZdirtF+kxnAjSuFBuSMQTZbUlSPt Lc9jLFpEzIpxS6jvYYzpGBeXfCGGH4S1bUH6V+uzTcvhgiXPIWxyj2xH4hFQwhReY9VyYl TywzIkEskyBVusSGWdLzMpAA/K1Bmy8= X-MC-Unique: 1s7MhyIwPtuBZ9vWwmMBBw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 03/14] docs: drivers: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:04 +0200 Message-Id: <1c7ead21c9cca49ccee2533fe120d2284b1fb1a9.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865785636100001 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -- `Hypervisor drivers <#hypervisor-drivers>`__ +- `Hypervisor drivers`_ - `Storage drivers `__ - `Node device driver `__ - `Secret driver `__ --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865798; cv=none; d=zohomail.com; s=zohoarc; b=KdkpNdnaBETVxQNb6gWqpuenUZ23GU8c/tFoewdD+ZfmPa/+FZpSvbZDb96g3b4ag9zmAHq23WJgGg/tCXKi7xXqzEi2VltfVsHTE8Wm4Dsp4MQOE5ujhgxWojJQMuk0ymlka9hQPLrOM8rUWaLAkU2U/lGg97dwHhEcve6UQ+A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865798; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=muXKeBZ9toqIGib9igqf5U49l7kOdYvwfLIlOaIu5pg=; b=RbIlrcolAP1mxsKHE3CMgqVYjrZ3fGPYH3rrRxRuuZW2DRk1POFlM2ve5BzBPXehfir6uMvQBGWjttaUMURS1Xq8VQ44Vu4vd0+EjUqkgDiNos+PQofgG5FrqHAImtYha/zjdMFoQMzlbvYCBk0MO26iAUVYhm6D6bs1rDIFxuc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865798450691.9528229495826; Wed, 13 Apr 2022 09:03:18 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-632-wQdi1i-kN0STfRc8TiUClg-1; Wed, 13 Apr 2022 12:03:09 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 41E5191D35B; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 28C844082385; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 819BE193F507; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 0D89A1940373 for ; Wed, 13 Apr 2022 16:02:21 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 02F58145BA63; Wed, 13 Apr 2022 16:02:21 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7996B145BA5B for ; Wed, 13 Apr 2022 16:02:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865797; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=muXKeBZ9toqIGib9igqf5U49l7kOdYvwfLIlOaIu5pg=; b=LmOZnWrRwEUDLQnwotACAXU5nqM3aFIBqI1jmeKxO1qNHe9YbogogCpa1YphPiB0gXZ4Bt KpS0cfEasA1Wg/b2pY/V8yWAEusBbtlVNdcfeGAS99j2mToB5SZNGNDif7yC7ugFnxfPCt EKTfXuKPGiW2wETA1WqWXOga5geLbPw= X-MC-Unique: wQdi1i-kN0STfRc8TiUClg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 04/14] docs: drvbhve: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:05 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865799586100001 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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: -Please refer to the `UEFI <#uefi>`__ section for a more detailed explanati= on. +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-Fre= eBSD +: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`` shoul= d be specified in the ``os`` section: --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865780; cv=none; d=zohomail.com; s=zohoarc; b=KwynWaHPubhyhKAX43RrzYIeYqun0h3sH8pzFRAq/ucZr2PbHoe5TgyWnhlpHv3zHwRWookUe42ofv1T0cCk/Etu9asUMV8DZvwdrLIFA0xJng87gryTaSpn3a0jTgvZIlLx3eOtuDj+oB+lnGkhPeRM+8yeGxlKC0+KprDVa/o= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865780; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=eoufHJe1XTxiamd9S3wEOiG58zJA3QGtoH31TOnGMoY=; b=XJ+q/Qn+fxYn90Oln82YAjjpxDb3/VOALhbk3ssJ3bZdq6OunwKq4gLbu2g9ZTAS9Qhv0wFYoAYb4MWTR2CbmMidg4AQylFnWSkdBnV9Eed3X7ZByeGOx+wGrCIoZUBCMwNf60gnYqZYfd6k5wcoBD8KoCG6U8wbLpN/UMOW3gY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865780353869.8641017867769; Wed, 13 Apr 2022 09:03:00 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-448-jIpH3BOyMu2bdb66nVEzfA-1; Wed, 13 Apr 2022 12:02:43 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id E91B3806604; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id D46D0145BA5B; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id C771C194E014; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 005441940340 for ; Wed, 13 Apr 2022 16:02:21 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id D7547145BA60; Wed, 13 Apr 2022 16:02:21 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 5EED2145BA5B for ; Wed, 13 Apr 2022 16:02:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865779; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=eoufHJe1XTxiamd9S3wEOiG58zJA3QGtoH31TOnGMoY=; b=S4Gk5cuVYuskfmdP7WDuJP75+COJ3pAjcGNy4TVtjRWWfREWaQFB8KlisSmtU/nlVOU3Ob PGtz2oeKsBqE3FRRW/005pG2dJi6lgpE10kIqCckRSo38k0IQfG/0VdndfPkhGP8Dhf1sN B1hNE2C1r+TohVLGRSCc7GhIvBpspSE= X-MC-Unique: jIpH3BOyMu2bdb66nVEzfA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 05/14] docs: drvesx: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:06 +0200 Message-Id: <4c15e1a4ec241d490a79b51187566ec0eec1030b.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865781433100002 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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 bel= ow. | | | 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 task= s`_ | | | | 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=3D1`` `extra parameter <#extraparams>`__ to disable= server +- Use the ``no_verify=3D1`` `Extra parameters`_ to disable server certificate verification. - Generate new SSL certificates signed by a CA known to your client compu= ter and replace the original ones on your ESX server. See the section *Repl= ace 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 `__ provided by the remote driver and libvirtd, = nor does the ESX driver support it. Therefore, using an URI including a tra= nsport - 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 mess= ages: :: @@ -257,8 +256,8 @@ answer a question, libvirt doesn't have an API for some= thing 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: e= ither 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.1= 0.0` any number of vCPUs is supported. - Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. :since:`S= ince - 0.7.6` arbitrary `MAC addresses <#macaddresses>`__ are supported. + 0.7.6` arbitrary `MAC addresses`_ are supported. Datastore references ~~~~~~~~~~~~~~~~~~~~ --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865843; cv=none; d=zohomail.com; s=zohoarc; b=NF9Ng1t6SRlUhn++6mEBS4PVoMQxn1Q5yj+GOo5vZYsyTpZirDHah6T5sgbOhE4FIU86myZKjMz06DL+C1yNMEnSE2IPJXVXTpnAflndj596G44EtktFAXu7PmRkEpJsDh3Yd1mKqwjz+O1kioaMtt3vL03N7puEWeWdJTF9CU0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865843; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=EUKXUnyZAa0zQOQhTEjsYcpgJSmucbNsktQyuCq7WQg=; b=YJqOnXFt6kM714WiU9Ie2BcF/vvZmxxIy9+7rwmsnrLGFQpGRX41I0auP3iU2V0EAdsgI6+aEj2vb92rkzmCnsMUv5Aw48PgNu1Rt6CSYS61h+2ixezNTLown10bOGFzZ05kwff9NERMgiXnYgx4Iq3703eMDipiSo/Kz/ChSO8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1649865843198466.34537250906317; Wed, 13 Apr 2022 09:04:03 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-209-uVJaCh4cNqK8723sLytgqQ-1; Wed, 13 Apr 2022 12:03:11 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id AF0B118E52A6; Wed, 13 Apr 2022 16:02:25 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9B004C27E92; Wed, 13 Apr 2022 16:02:25 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 203C41940345; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id CF9FB194E015 for ; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id C487A145BA60; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3D4C9145BA5B for ; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865842; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=EUKXUnyZAa0zQOQhTEjsYcpgJSmucbNsktQyuCq7WQg=; b=LHSFRiytTelXTU1TGBueL7JDwZio7wxGviKohrnkyTtFZYddNWWHqXcig0UlPii88uMqlJ mAMxN7kAnfuTeB8EtIv0/tYebsvc9TbKc4kpLA8ga78uUigutykEjAdQb8w5uwhoPRnCLu ZjKx3fjzlvDyzC6UnLghVHu3eAUBOQE= X-MC-Unique: uVJaCh4cNqK8723sLytgqQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 06/14] docs: drvnodedev: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:07 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865843883100001 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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`_ b= elow). :: @@ -103,9 +102,10 @@ multiple devices called virtual functions (VFs) sharin= g their configuration with the underlying PF. Despite the SR-IOV specification, the amount of VFs tha= t can be created on a PF varies among manufacturers. -Suppose the NIC `above <#PCI>`__ was also SR-IOV capable, it would also in= clude -a nested ```` element enumerating all virtual functions availa= ble 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 w= ould +also include a nested ```` element enumerating all virtual +functions available on the physical device (physical port) like in the exa= mple +below. :: @@ -146,8 +146,8 @@ of the XML format for the ``mdev_types`` capability can= be found `here `__. The following example shows how we might represent an NVIDIA GPU device th= at -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 co= mmand can be used. --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865786; cv=none; d=zohomail.com; s=zohoarc; b=JPi1y/7eUvc3ZvCSRDhARLbJvSbIWqifUGO14cgqLkjcs43HYlBZxFUS8dkr/rmaWweDqofM7vKo0Xa0ROzWwXt6MdFgxax4bFwanHbPY9aBslFv03UNObu7AtEmtGrgsmWGm9sEAMtMWzs0lsWqIVvlX6C+HMBMeBeiY9lcnsw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865786; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=shEUNNQepTLByoE6a02XVHibp1XFY7qh/rt8uIbgJ5Y=; b=B24w4GAtKKjK7qnodNcFnYFEwn3a7xMNHURWbEI+Cm3GQfV46VkeiyhHRbzPPjHmYjReW5GHezO589aI/rAjWgtzPoQP/khXEKB9DmPNT4VpsmnawsKwiRQG+R6scLVEjEOdCEJQzb2TY4mNzlgL7nd+UYhggYDxn3u22GqA5HU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1649865786201259.9697144153175; Wed, 13 Apr 2022 09:03:06 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-569-QTa-Nx8nOWaQOimqLokoVA-1; Wed, 13 Apr 2022 12:02:52 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4D2E128EA6F9; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3667BC44CFB; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 66484193F50E; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id DC0861940340 for ; Wed, 13 Apr 2022 16:02:23 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id C95A6145B97E; Wed, 13 Apr 2022 16:02:23 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2797D145BA5B for ; Wed, 13 Apr 2022 16:02:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865784; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=shEUNNQepTLByoE6a02XVHibp1XFY7qh/rt8uIbgJ5Y=; b=ZweZSwNBuVOs/U4d2wu7VFjUsVAlSht30ncPdWeNcNSCqlufW9KfCBmRJL8PKfbH4PXHfE 0px9F05bK1TxujaAUGNJOnQtE8hwcc6yCJYvZ+4NHPl0Bzq3MF5P9tV+RWWuPro25uDv75 cZ0yTMbJ/ysiGW5Pvb/aCxDZfEQIwA4= X-MC-Unique: QTa-Nx8nOWaQOimqLokoVA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 07/14] docs: drvsecret: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:08 +0200 Message-Id: <238e977f5ce24a9cea0f392ccbdef3628cbf8811.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865787501100003 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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 o= f 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 creatio= n of a `storage volume `__ 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 o= f 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 vo= lume `encryption `__ 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 o= f 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 ```` element in a domain's ` `__ element= as @@ -203,8 +203,8 @@ must match the password used in the iSCSI authenticatio= n configuration file. c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi -See `virsh secret-set-value <#settingSecrets>`__ on how to set the value o= f 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 ```` element in a domain's ` = `__ --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865793; cv=none; d=zohomail.com; s=zohoarc; b=Ihq6BowBHSvcc+uGpe2atWe/KjF1BZEOVIw4M7yodk/TOqABpGECJ189w9YBPBvXOc1pGragC1Vym30xUnJR57rMzV2nqvt8PT/fqlLPGGdYignKroPFVEf6EA2mWSynfDjeciFr0KaAAj5xUsBoE4Ezo86OhB6Z0ZGcw4o0N5E= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865793; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=s6PhX2pojhJkKAJfUP6OgoqE75BzKrEAFc3qWA7AAeM=; b=MrE+NkRE1NET4HH3xeV+gZUY5wV+MZvHzQsOSZ80405s3d53gxWlk+uXsBh1G+8/mNA0j26rNJBo4mnsLO5mQI4nG0ujqfPfiXoT08uN/nbxlvPGeiogag8y8ucKT2RR33ZEDKTdN/Z2XW9Rk/uaIxHWcOYleP+fH8lcszdWr5w= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1649865793886103.77941108925847; Wed, 13 Apr 2022 09:03:13 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-263-zuLlmpKXNJiJhq7V3W8_wg-1; Wed, 13 Apr 2022 12:03:06 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id E84D110A5CD3; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id CA894145BA5D; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 64CAF1940345; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id E2A51193F6E8 for ; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id C6CE1145BA5F; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2445A145BA5B for ; Wed, 13 Apr 2022 16:02:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865792; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=s6PhX2pojhJkKAJfUP6OgoqE75BzKrEAFc3qWA7AAeM=; b=cAPtBMih2OIBUu0f/kWlNTrzKW56T0Ue2JZ2Gk6fHPwSWQYaf4hgmwLRaenXl15hgv72ke /c2bvoAfaYiaVBL8ibQiJzrhaR7FgIqLZAnM+g4wn+GXXSiui7rAbOkgpziYvfnuuqD6Pd HeLeF5X3FJO4DMN1ZvV3LCe0d3vDmo8= X-MC-Unique: zuLlmpKXNJiJhq7V3W8_wg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 08/14] docs: kbase/launch_security_sev: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:09 +0200 Message-Id: <1203e2c6ca03f9b013307fe75454cc823f9f3f9a.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865795544100001 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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_securit= y_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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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: --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865789; cv=none; d=zohomail.com; s=zohoarc; b=KIe0tNQL6vHbrcARMZZc2OkDDyJKjzWa9H5DOovV9Hz8NIIGMono/jYFppJYlMZkqXDIj0yUKTZuf76aOVmmwt/SdX8ZF5IQm+T+Zl6Ili2q8MJ61WPtHPTiem58CkpP1FWvighXglfoTpvmgxKQpTKK2RC9g/xevZ3vHJiw7go= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865789; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Bn8wgeLjOEHbA3lW+ZDSPdyheex8mLTHU9F6cyd9IyE=; b=mXxqE1PIRzw9sbgRQ46NMR7AxxFEgdIESK8kN6TtlOesJbs9Mhx2yrSs9Z8itsqQsVo5XL7c3omDzZnjH3NiYwZIe7f1G/9IWUpGdIR6BzhwiYJ84f3dbYaqvVqRtur2sskKGX0/fx6a3I2O7NJfNkP/ll4eGAk62n8qe299NBE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865789400363.91001878214706; Wed, 13 Apr 2022 09:03:09 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-172-BAH9QY9NMfW09q70vvWpsg-1; Wed, 13 Apr 2022 12:03:04 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 8396F10AF627; Wed, 13 Apr 2022 16:02:27 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6DFBCC4C7A0; Wed, 13 Apr 2022 16:02:27 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id BB842193F507; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id CDC211940340 for ; Wed, 13 Apr 2022 16:02:25 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id C3FED145BA5D; Wed, 13 Apr 2022 16:02:25 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 36859145BA5B for ; Wed, 13 Apr 2022 16:02:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865788; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Bn8wgeLjOEHbA3lW+ZDSPdyheex8mLTHU9F6cyd9IyE=; b=AHDchJdvd3c3Re4DueO6S6RGw4n5ivl4neL1bdOKMJfqlSs2Gm152V4yhHTy9wGdvbjlq6 OxlT7N3J+SDDWYPwLxGIO5dUNRjjxzBiJjqyprZHH/O0oA+GT17dr8BG2kuVuEhyKfO7iI 4M2jrBFwtPZtMkXw6ydDx4fftAKn5I8= X-MC-Unique: BAH9QY9NMfW09q70vvWpsg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 09/14] docs: kbase/tlscerts: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:10 +0200 Message-Id: <9ef4c904a6e47b40779292456ddf30932e49a025.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865791527100013 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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 li= st (``tls_allowed_dn_list``). @@ -279,9 +279,8 @@ this on a company / organisation policy. For example: C=3DGB,ST=3DLondon,L=3DLondon,O=3DLibvirt Project,CN=3Dname_of_client -The process is the same as for `setting up the server -certificate <#Remote_TLS_server_certificates>`__ so here we just briefly c= over -the steps. +The process is the same as for `Issuing server certificates`_ so here we j= ust +briefly cover the steps. #. Make a private key: --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865788; cv=none; d=zohomail.com; s=zohoarc; b=nsK4E8MgG3m0bD8yPzoBJ6WJYF3S+HJqCeVAZ5J8i06j+LhNEvBYXKn183lYYNO/X6cahVF6FY6ex969ANQVuUdJ5Z/B1Znbzvg5XLFNsT+Bn6chM2oaJs/Afx6VRVTzdUmu3H1H31uRMVb8m4v5SqbvukjBenDjxa1OCcNO44U= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865788; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Rm4UqXhI7PMKtiapYD0IUpD1Blm5Snhqq1h+jajtfog=; b=a/IZ+ix0ubPiiZd86A4YDZp6G/9/aI1vah7A9vTywRWkmPIGrD9g/tjpECOnS4QyDnhkdlZXV1GN20YOKddv05e+kTNOwO+T7CpuRtCZ6ZGJlXbCgPT4LfdLC/Km4rTOJGOVexTKhqlg9A+m/qCEykAdcokd6nn6ACtOMIA/Z8U= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1649865788873459.382764542136; Wed, 13 Apr 2022 09:03:08 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-303-tKEazP19NWC5BG_vApnrvA-1; Wed, 13 Apr 2022 12:03:05 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 019F83C02B94; Wed, 13 Apr 2022 16:02:28 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id D82E940D016C; Wed, 13 Apr 2022 16:02:27 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 14C16193F513; Wed, 13 Apr 2022 16:02:27 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id BFFA3193F509 for ; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id A0180145BA5D; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 240AB145BA5B for ; Wed, 13 Apr 2022 16:02:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865787; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Rm4UqXhI7PMKtiapYD0IUpD1Blm5Snhqq1h+jajtfog=; b=ZUp4v6dddCIPrvtPdktyeUmpFUzKl8iuVCroqExWqLylsNmCrwd/QCK4ZtoSdQ+tce7Txr N0c+HMhfN8IDMbzvvk6v1C0/9rzgUcL1I5sIPiKzNkam68sOeJl9j7v9uomJOAivdv3QzP OCfsYSawhkdJgUFjlcLOASx2XNhco64= X-MC-Unique: tKEazP19NWC5BG_vApnrvA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 10/14] docs: pci-hotplug: Fix local anchor links Date: Wed, 13 Apr 2022 18:02:11 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865789530100009 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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-v= irt`` guests is extremely uncommon, so you'll probably never need to add control= lers --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865786; cv=none; d=zohomail.com; s=zohoarc; b=SPWhyP1xDCsG1eOVzNBJnLh/3ALjCdaV7csFlkCWtQ7XuZNf4kCOZenpses3itKOt/1lnu6344bg3yfUuc56QR5fZJIoB+DhTsxzTzJ9VVgeB14UwmYzqZ/+UveTTdxypeYrkbNpatNiCKviMZ4YbbGI6TdDaigqgmDinjqNUG8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865786; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=U6OFtUAtmmhleHqPZZFBl+5Cc5vunBP5SrXbVrNdM9c=; b=be8Ht4dQQ7eWck9rAIhkUV/CPM1YZuFEmhAzC8MjBeOuKhjkPnxDYHz3sVTxi3X/OjT2SrmNL49k1ZOm0zX06GLC3nowmVszv/qJPpTmE6rYNf+a9oAQP6bYZ1PH7Jj8RFNe+SAH3R1zRFTYTylhSPzV6QbpGlxIBUpsq46/gw4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865786933154.59329065407906; Wed, 13 Apr 2022 09:03:06 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-524-DtJPOQUTNjKgCZ9Gsexlzg-1; Wed, 13 Apr 2022 12:03:01 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 309BA19711CD; Wed, 13 Apr 2022 16:02:30 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1797A141511F; Wed, 13 Apr 2022 16:02:30 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id C959C193F6E0; Wed, 13 Apr 2022 16:02:29 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id EB5181940345 for ; Wed, 13 Apr 2022 16:02:28 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id CC6E6145BA5D; Wed, 13 Apr 2022 16:02:28 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0D88C145BA5B for ; Wed, 13 Apr 2022 16:02:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865785; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=U6OFtUAtmmhleHqPZZFBl+5Cc5vunBP5SrXbVrNdM9c=; b=E3NPQOoEoE4cB4HJajSBh7A/aig/zpSghyGP613+LxMsKtjwRkvrTC20VUPJmLPiZ5FdJm eeS4JcZUWV/u3PZ/OdyzMRqbROK3rlLHYPJ3LOIc6kWKNQ2HAufFR6T1uV4wg+pc4p5JXf 7DIvGN4K1NncSQ8V1YM9Cp3upt3hiEI= X-MC-Unique: DtJPOQUTNjKgCZ9Gsexlzg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 11/14] docs: Convert 'formatnwfilter' page to rst Date: Wed, 13 Apr 2022 18:02:12 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: application/octet-stream; x-default=true X-Zoho-Virus-Status: 1 X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865787542100005 From: Pavel Hrdina Also adjust direct links from other pages. Signed-off-by: Pavel Hrdina Signed-off-by: Peter Krempa --- 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 `__. +`here `__. 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 ```` elements may be specified for passing additional info to the nwfilter via the ``name`` and ``value`` attributes. See the -`nwfilter `__ docs for info on parameters. +`nwfilter `__ docs for info +on parameters. :anchor:`` 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 @@ - - - - -

Network Filters

- -
    -
- -

- 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 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 0.9.8)
    • -
  • stp (spanning tree protocol) - (since 0.9.8)
    • -
  • vlan (802.1Q) (since 0.9.8)
    • -
  • arp, rarp
    • -
  • ipv4
    • -
  • ipv6
    • -
-

- 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 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 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 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 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 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 - 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 0.9.7), - or continue (matching the rule goes on to the next - rule for further analysis) (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 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 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
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
dstmacaddrMAC_ADDRMAC address of destination
dstmacmaskMAC_MASKMask applied to MAC address of destination
protocolidUINT16 (0x600-0xffff), STRINGLayer 3 protocol ID
comment (Since 0.8.5)STRINGtext with max. 256 characters
-

- Valid Strings for protocolid are: arp, rarp, ipv4, ipv6 -

-
-[...]
-<mac match='no' srcmacaddr='$MAC'/>
-[...]
-
- -
VLAN (802.1Q) - (Since 0.9.8) -
-

- Protocol ID: vlan -
- Note: Rules of this type should go either into the root or - vlan chain. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Attribute Datatype Semantics
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
dstmacaddrMAC_ADDRMAC address of destination
dstmacmaskMAC_MASKMask applied to MAC address of destination
vlanidUINT16 (0x0-0xfff, 0 - 4095)VLAN ID
encap-protocolUINT16 (0x03c-0xfff), StringEncapsulated layer 3 protocol ID
comment STRINGtext 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
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
typeUINT8Bridge Protocol Data Unit (BPDU) type
flagsUINT8BPDU flag
root-priorityUINT16Root priority (range start)
root-priority-hiUINT16Root priority range end
root-addressMAC_ADDRESSRoot MAC address
root-address-maskMAC_MASKRoot MAC address mask
root-costUINT32Root path cost (range start)
root-cost-hiUINT32Root path cost range end
sender-priorityUINT16Sender priority (range start)
sender-priority-hiUINT16Sender priority range end
sender-addressMAC_ADDRESSBPDU sender MAC address
sender-address-maskMAC_MASKBPDU sender MAC address mask
portUINT16Port identifier (range start)
port_hiUINT16Port identifier range end
msg-ageUINT16Message age timer (range start)
msg-age-hiUINT16Message age timer range end
max-ageUINT16Maximum age timer (range start)
max-age-hiUINT16Maximum age timer range end
hello-timeUINT16Hello time timer (range start)
hello-time-hiUINT16Hello time timer range end
forward-delayUINT16Forward delay (range start)
forward-delay-hiUINT16Forward delay range end
commentSTRINGtext 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
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
dstmacaddrMAC_ADDRMAC address of destination
dstmacmaskMAC_MASKMask applied to MAC address of destination
hwtypeUINT16Hardware type
protocoltypeUINT16Protocol type
opcodeUINT16, STRINGOpcode
arpsrcmacaddrMAC_ADDRSource MAC address in ARP/RARP packet
arpdstmacaddrMAC_ADDRDestination MAC address in ARP/RARP packet
arpsrcipaddrIP_ADDRSource IP address in ARP/RARP packet
arpsrcipmask (Since 1.2.3)IP_MASKSource IP mask
arpdstipaddrIP_ADDRDestination IP address in ARP/RARP packet
arpdstipmask (Since 1.2.3)IP_MASKDestination IP mask
comment (Since 0.8.5)STRINGtext with max. 256 characters
gratuitous (Since 0.9.2)BOOLEANboolean indicating whether 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
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
dstmacaddrMAC_ADDRMAC address of destination
dstmacmaskMAC_MASKMask applied to MAC address of destination
srcipaddrIP_ADDRSource IP address
srcipmaskIP_MASKMask applied to source IP address
dstipaddrIP_ADDRDestination IP address
dstipmaskIP_MASKMask applied to destination IP address
protocolUINT8, STRINGLayer 4 protocol identifier
srcportstartUINT16Start of range of valid source ports; requires protocol
srcportendUINT16End of range of valid source ports; requires protocol
dstportstartUINT16Start of range of valid destination ports; requires protocol
dstportendUINT16End of range of valid destination ports; requires protocol
dscpUINT8 (0x0-0x3f, 0 - 63)Differentiated Services Code Point
comment (Since 0.8.5)STRINGtext with max. 256 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
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
dstmacaddrMAC_ADDRMAC address of destination
dstmacmaskMAC_MASKMask applied to MAC address of destination
srcipaddrIPV6_ADDRSource IPv6 address
srcipmaskIPV6_MASKMask applied to source IPv6 address
dstipaddrIPV6_ADDRDestination IPv6 address
dstipmaskIPV6_MASKMask applied to destination IPv6 address
protocolUINT8Layer 4 protocol identifier
srcportstartUINT16Start of range of valid source ports; requires protocol
srcportendUINT16End of range of valid source ports; requires protocol
dstportstartUINT16Start of range of valid destination ports; requires protocol
dstportendUINT16End of range of valid destination ports; requires protocol
type(Since 1.2.12)UINT8ICMPv6 type; requires protocol to be set to icmpv6
typeend(Since 1.2.12)UINT8ICMPv6 type end of range; requires protocol to be set to icmpv6
code(Since 1.2.12)UINT8ICMPv6 code; requires protocol to be set to icmpv6
code(Since 1.2.12)UINT8ICMPv6 code end of range; requires protocol to be set to icmpv6
comment (Since 0.8.5)STRINGtext 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
srcmacaddrMAC_ADDRMAC address of sender
srcipaddrIP_ADDRSource IP address
srcipmaskIP_MASKMask applied to source IP address
dstipaddrIP_ADDRDestination IP address
dstipmaskIP_MASKMask applied to destination IP address
srcipfromIP_ADDRStart of range of source IP address
srciptoIP_ADDREnd of range of source IP address
dstipfromIP_ADDRStart of range of destination IP address
dstiptoIP_ADDREnd of range of destination IP address
srcportstartUINT16Start of range of valid source ports
srcportendUINT16End of range of valid source ports
dstportstartUINT16Start of range of valid destination ports
dstportendUINT16End of range of valid destination ports
dscpUINT8 (0x0-0x3f, 0 - 63)Differentiated Services Code Point
comment (Since 0.8.5)STRINGtext with max. 256 characters
state (Since 0.8.5)STRINGcomma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE
flags (Since 0.9.1)STRINGTCP-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
ipset (Since 0.9.13)STRINGThe name of an IPSet managed outside of libvirt
ipsetflags (Since 0.9.13)IPSETFLAGSflags for the IPSet; 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
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
dstmacaddrMAC_ADDRMAC address of destination
dstmacmaskMAC_MASKMask applied to MAC address of destination
srcipaddrIP_ADDRSource IP address
srcipmaskIP_MASKMask applied to source IP address
dstipaddrIP_ADDRDestination IP address
dstipmaskIP_MASKMask applied to destination IP address
srcipfromIP_ADDRStart of range of source IP address
srciptoIP_ADDREnd of range of source IP address
dstipfromIP_ADDRStart of range of destination IP address
dstiptoIP_ADDREnd of range of destination IP address
typeUINT16ICMP type
codeUINT16ICMP code
dscpUINT8 (0x0-0x3f, 0 - 63)Differentiated Services Code Point
comment (Since 0.8.5)STRINGtext with max. 256 characters
state (Since 0.8.5)STRINGcomma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE
ipset (Since 0.9.13)STRINGThe name of an IPSet managed outside of libvirt
ipsetflags (Since 0.9.13)IPSETFLAGSflags for the IPSet; 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
srcmacaddrMAC_ADDRMAC address of sender
srcmacmaskMAC_MASKMask applied to MAC address of sender
dstmacaddrMAC_ADDRMAC address of destination
dstmacmaskMAC_MASKMask applied to MAC address of destination
srcipaddrIP_ADDRSource IP address
srcipmaskIP_MASKMask applied to source IP address
dstipaddrIP_ADDRDestination IP address
dstipmaskIP_MASKMask applied to destination IP address
srcipfromIP_ADDRStart of range of source IP address
srciptoIP_ADDREnd of range of source IP address
dstipfromIP_ADDRStart of range of destination IP address
dstiptoIP_ADDREnd of range of destination IP address
dscpUINT8 (0x0-0x3f, 0 - 63)Differentiated Services Code Point
comment (Since 0.8.5)STRINGtext with max. 256 characters
state (Since 0.8.5)STRINGcomma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE
ipset (Since 0.9.13)STRINGThe name of an IPSet managed outside of libvirt
ipsetflags (Since 0.9.13)IPSETFLAGSflags for the IPSet; 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
srcmacaddrMAC_ADDRMAC address of sender
srcipaddrIPV6_ADDRSource IP address
srcipmaskIPV6_MASKMask applied to source IP address
dstipaddrIPV6_ADDRDestination IP address
dstipmaskIPV6_MASKMask applied to destination IP address
srcipfromIPV6_ADDRStart of range of source IP address
srciptoIPV6_ADDREnd of range of source IP address
dstipfromIPV6_ADDRStart of range of destination IP address
dstiptoIPV6_ADDREnd of range of destination IP address
srcportstartUINT16Start of range of valid source ports
srcportendUINT16End of range of valid source ports
dstportstartUINT16Start of range of valid destination ports
dstportendUINT16End of range of valid destination ports
dscpUINT8 (0x0-0x3f, 0 - 63)Differentiated Services Code Point
comment (Since 0.8.5)STRINGtext with max. 256 characters
state (Since 0.8.5)STRINGcomma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE
flags (Since 0.9.1)STRINGTCP-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
ipset (Since 0.9.13)STRINGThe name of an IPSet managed outside of libvirt
ipsetflags (Since 0.9.13)IPSETFLAGSflags for the IPSet; 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
srcmacaddrMAC_ADDRMAC address of sender
srcipaddrIPV6_ADDRSource IPv6 address
srcipmaskIPV6_MASKMask applied to source IPv6 address
dstipaddrIPV6_ADDRDestination IPv6 address
dstipmaskIPV6_MASKMask applied to destination IPv6 address
srcipfromIPV6_ADDRStart of range of source IP address
srciptoIPV6_ADDREnd of range of source IP address
dstipfromIPV6_ADDRStart of range of destination IP address
dstiptoIPV6_ADDREnd of range of destination IP address
typeUINT16ICMPv6 type
codeUINT16ICMPv6 code
dscpUINT8 (0x0-0x3f, 0 - 63)Differentiated Services Code Point
comment (Since 0.8.5)STRINGtext with max. 256 characters
state (Since 0.8.5)STRINGcomma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE
ipset (Since 0.9.13)STRINGThe name of an IPSet managed outside of libvirt
ipsetflags (Since 0.9.13)IPSETFLAGSflags for the IPSet; 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
srcmacaddrMAC_ADDRMAC address of sender
srcipaddrIPV6_ADDRSource IPv6 address
srcipmaskIPV6_MASKMask applied to source IPv6 address
dstipaddrIPV6_ADDRDestination IPv6 address
dstipmaskIPV6_MASKMask applied to destination IPv6 address
srcipfromIPV6_ADDRStart of range of source IP address
srciptoIPV6_ADDREnd of range of source IP address
dstipfromIPV6_ADDRStart of range of destination IP address
dstiptoIPV6_ADDREnd of range of destination IP address
dscpUINT8 (0x0-0x3f, 0 - 63)Differentiated Services Code Point
comment (Since 0.8.5)STRINGtext with max. 256 characters
state (Since 0.8.5)STRINGcomma separated list of NEW,ESTABLISHED,RELATED,INVALID or NONE
ipset (Since 0.9.13)STRINGThe name of an IPSet managed outside of libvirt
ipsetflags (Since 0.9.13)IPSETFLAGSflags for the IPSet; 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 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 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 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/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``. + +:: + + ... + + + + + + + ... + +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. + +:: + + ... + + + + + + + + + ... + +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. + +:: + + + f88f1932-debf-4aa1-9fbe-f10d3aa4bc95 + + + + + + + + + + + + + + + + + + + + + + + + + +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: + +:: + + ... + + + + + + + + + + + ... + +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. + +:: + + ... + + + + ... + +: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. + +:: + + ... + + + + ... + +: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[@]``. 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. + +:: + + ... + + + + ... + +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: + +:: + + + + + + + + +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. + +:: + + + 6ef53069-ba34-94a0-d33d-17751b9b8cb1 + + + + + + + + +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. + +:: + + + fce8ae33-e69e-83bf-262e-30786c1f8072 + + + + + +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. + +:: + + [...] + + + + + [...] + +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 + +:: + + [...] + + [...] + +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. + +:: + + [...] + + + + [...] + +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. + +:: + + [...] + + + + + + + + + + + + + + + + + + + [...] + +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: + +:: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +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: + +:: + + [...] + + + + + [...] + +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: + +:: + + + + + + + + + + + +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))` : + +:: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +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. + +:: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +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 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865788; cv=none; d=zohomail.com; s=zohoarc; b=mlJA1jhXm4NomBTpcQVY8rAzFsBOnkGIYqLpW9t3ryw8YM74MxBoE8igAjOENtsyMf89f5fbVahA06GB1SeW+WxJh/LSvozSbwpvVFI+DN2OzABsWPY4ZnFkxunnm6M9+AIEqaWZ4lBexZYhWk3IFkqKITshfKdPo/QIkMMONik= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865788; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=wqKdy3nhd2OrIBlSpDTwWhDT9s6lcRQvnl0LlxdMA5k=; b=bZSZQwe7zLMAOYk64sqWTnROBcxMOfgwxDiJW8B1zJQOwvp9xQKLDSxCAALN3W0CJPIUaR/EtJQWvvznAVlHv/8fKa91Hba/ZtlVDn4Lxg3SwC0CG3JzZK547QbVuSlEXQlvb4gaNYIqGxn1j5sbldA1cpgOKfz94cJIRMJNJB8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1649865788725122.10973665386166; Wed, 13 Apr 2022 09:03:08 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-645-c5Wjs-hdN3Sbn7XreWUoVg-1; Wed, 13 Apr 2022 12:03:03 -0400 Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 91F2A1C00BB4; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 730C0492D55; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 2E3B91940353; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id BA5DB194037E for ; Wed, 13 Apr 2022 16:02:29 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id AFA8F145BA5B; Wed, 13 Apr 2022 16:02:29 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 35258145BA5F for ; Wed, 13 Apr 2022 16:02:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865787; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=wqKdy3nhd2OrIBlSpDTwWhDT9s6lcRQvnl0LlxdMA5k=; b=d/nqF+SSd2Ben0TaGq8AWQiqVtV2xXxb3u2Ov3Z0v4A25Z2BJMKTWZL8FixjwgkrIJFTnM GNAOvVJ442D8z0j6LuvfLgQ/XX7K8HiU9rrzaEmPswGuxb+lBdOSF51ejk8RrRH6RgzGXx 2G8tXELCo/xP7rTMP/KnKuW+6JyEDNM= X-MC-Unique: c5Wjs-hdN3Sbn7XreWUoVg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 12/14] docs: Convert 'formatcaps' page to rst Date: Wed, 13 Apr 2022 18:02:13 +0200 Message-Id: <19ad6ab6a6cacee6fcb400fd642edb65a9dc8315.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.9 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: application/octet-stream; x-default=true X-Zoho-Virus-Status: 1 X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865789532100010 Signed-off-by: Peter Krempa --- 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 @@ - - - - -

Driver capabilities XML format

- -
    - -

    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 example, 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 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 - element of domain XML.
    -
    loader
    Loader path, for use in - loader element of domain - XML.
    -
    machine
    Machine type, for use in - machine - 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 - 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 - 0.4.1
    -
    nonpae
    If present, 32-bit guests can be run - without requiring PAE, since - 0.4.1
    -
    ia64_be
    If present, IA64 guests can be run in - big-endian mode, 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 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 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 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 - 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 - 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/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 ```` 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 ```` 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 `__ element of domain XML. + ``loader`` + Loader path, for use in `loader `__ + element of domain XML. + ``machine`` + Machine type, for use in + `machine `__ 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 `__ 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 ```` 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 ```` 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: + +:: + + + + + x86_64 + + + + core2duo + Intel + + + + ... + + + + + + + + + + + xen + + 64 + + /usr/lib64/xen/bin/qemu-dm + + + + + + + + hvm + + 32 + + /usr/lib/xen/bin/qemu-dm + pc + isapc + /usr/lib/xen/boot/hvmloader + + + + + + + + ... + 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 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865794; cv=none; d=zohomail.com; s=zohoarc; b=io2ZGQMGJeBamf+uPqcrdnKOhwRC6zo1Q+3bmKfLUAWTmOvEy/BmPcItm0kmlKrGhxooTlsuYHcpmSZds/Qhwkc3gBqqFljY5kAZIKV74Fjrbt2/M4WiGUhKjn/gYIyJvD//gr24h09pI6FRoXXCZe24mL+x5wrHuxnnbd//0AU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865794; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=IrTjkX6CWJ9QCdu58HmEnB9n4iDjSNAj8zIzm0zjiRo=; b=TsEP1A586oXNGg1+nWjhf6JnLtNui0rIbYNhfQPcfxidhyiVui+Gg5elo/vW3/8GAtnY3Tq0QSLrCvMY9Sw/DVQ53TXCu+Ow7rKHiECJt3ZxrQJSgrMTeubUpWrPiD5Fz5Z6iK+gickAvh19TGnDn0NPEyEJa1f3K5/GwBpZ1bQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865794266870.9638103823384; Wed, 13 Apr 2022 09:03:14 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-124-XwdsOGj3MAKPCMECrbpgxA-1; Wed, 13 Apr 2022 12:03:09 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id D0CC638008CB; Wed, 13 Apr 2022 16:02:32 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id AFFD740D0160; Wed, 13 Apr 2022 16:02:32 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 858161940373; Wed, 13 Apr 2022 16:02:32 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 25E701940340 for ; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 1BD22145BA5B; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0D657141511C for ; Wed, 13 Apr 2022 16:02:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865792; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=IrTjkX6CWJ9QCdu58HmEnB9n4iDjSNAj8zIzm0zjiRo=; b=XBFnmrPzDxxnAxevVlRFvmyuV7edkiL5UoUU92HUaWstyfDa4MSGsbxtXZd3WDLWzbwbQt lYRaqEzGoCSDk6czIaudVCIiszMK1gIm4OADzSGacpsI21SbDmqe2ka0vAhUy5ra0iNdaj Z4U3v+Lg3geqltu067MNfeGlfMUnO60= X-MC-Unique: XwdsOGj3MAKPCMECrbpgxA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 13/14] docs: Convert 'formatnetwork' page to rst Date: Wed, 13 Apr 2022 18:02:14 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865795768100005 Content-Type: text/plain; charset="utf-8"; x-default="true" Additionally hyperlinks in other parts of the documentation are updated to match. Signed-off-by: Peter Krempa Reviewed-by: Michal Privoznik --- 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 a= nd outgoing traffic can be shaped independently. The ``bandwidth`` element an= d its -child elements are described in the `QoS `__ +child elements are described in the `QoS `__ section of the Network XML. :anchor:`` @@ -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 `__. This is used by t= he LXC +definitions `__. 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 @@ - - - - -

    Network XML format

    - -
      -
    - -

    - This page provides an introduction to the network XML format. For - background information on the concepts referred to here, consult the - relevant wiki p= age. -

    - -

    Element and attribute overview

    - -

    - The root element required for all virtual networks is - named network and has no configurable attributes - (although 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 0.3.0 -

    - -

    General metadata

    - -

    - The first elements provide basic metadata about the virtual - network. -

    - - 
    -<network ipv6=3D'yes' trustGuestRxFilters=3D'no'>
-  <name>default</name>
-  <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
-  <metadata>
-    <app1:foo xmlns:app1=3D"http://app1.org/app1/">..</app1:foo&g=
t;
-    <app2:bar xmlns:app2=3D"http://app1.org/app2/">..</app2:bar&g=
t;
-  </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 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 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 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 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 - 1.2.10). See - the Network - interfaces 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=3D"virbr0" stp=3D"on" delay=3D"5" macTableManager=3D"libvi=
rt"/>
-<mtu size=3D"9000"/>
-<domain name=3D"example.com" localOnly=3D"no"/>
-<forward mode=3D"nat" dev=3D"eth0"/>
-...
    - -
    -
    bridge
    -
    The name attribute on the bridge eleme= nt - 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 devi= ce - 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 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 1.2.11, requires kernel 3.17 or - newer -

    - -

    - The optional zone attribute of - the bridge element is used to specify - the firewalld - 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 5.1.0 -

    -
    - -
    mtu
    -
    - The size attribute of the mtu> - element specifies the Maximum Transmission Unit (MTU) for the - network. 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 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 1.2.12 -

    -
    -
    forward
    -
    Inclusion of the forward element indicates that - the virtual network is to be connected to the physical - LAN.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=3D'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 - 0.4.2 - -

    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=3D'nat'>
-    <nat>
-      <address start=3D'1.2.3.4' end=3D'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=3D'nat'>
-    <nat>
-      <port start=3D'500' end=3D'1000'/>
-    </nat>
-  </forward>
-...
    - -

    - 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=3D'nat'>
-    <nat ipv6=3D'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 - on the guest's interfaces.) - Since 0.4.2 -
    - -
    open
    -
    - As with mode=3D'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=3D'open' is set, the dev attribute - cannot be set (because the forward dev is enforced with - firewall rules, and the purpose of forward=3D'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 on the - guests' interfaces.) - Since 2.2.0 -
    - -
    bridge
    -
    - This network describes either 1) an existing host bridge - that was configured outside of libvirt (if - a <bridge name=3D'xyz'/> element has been - specified, Since 0.9.4), 2) an - existing Open vSwitch bridge that was configured outside of - libvirt (if both a <bridge name=3D'xyz'/> - element and a <virtualport - type=3D'openvswitch'/> have been - specified 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 0.9.4) - (see Direct - attachment to physical interface 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 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 - 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 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 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 0.10.0 - -

    - To force use of a particular type of device assignment, - a <forward type=3D'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 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 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=3D'network'> pointing to a network - with <forward mode=3D'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 0.9.4: - 
    -...
-  <forward mode=3D'passthrough'>
-    <interface dev=3D'eth10'/>
-    <interface dev=3D'eth11'/>
-    <interface dev=3D'eth12'/>
-    <interface dev=3D'eth13'/>
-    <interface dev=3D'eth14'/>
-  </forward>
-...
-
    -

    - 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 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=3D'passthrough'>
-    <pf dev=3D'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 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=3D'hostdev' managed=3D'yes'>
-    <driver name=3D'vfio'/>
-    <address type=3D'pci' domain=3D'0' bus=3D'4' slot=3D'0' function=3D=
'1'/>
-    <address type=3D'pci' domain=3D'0' bus=3D'4' slot=3D'0' function=3D=
'2'/>
-    <address type=3D'pci' domain=3D'0' bus=3D'4' slot=3D'0' function=3D=
'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=3D'hostdev' managed=3D'yes'>
-    <pf dev=3D'eth0'/>
-  </forward>
-...
-
    - -
    -
    -
    Quality of service
    - -
    -...
-  <forward mode=3D'nat' dev=3D'eth0'/>
-  <bandwidth>
-    <inbound average=3D'1000' peak=3D'5000' burst=3D'5120'/>
-    <outbound average=3D'128' peak=3D'256' burst=3D'256'/>
-  </bandwidth>
-...
    - -

    - The <bandwidth> element allows setting - quality of service for a particular network - (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 attach= ed - 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 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 foll= ows, - 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=3D'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 speci= fy - 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 0.9.4, while the - floor attribute is available - since 1.0.1. -

    - -
    Setting VLAN tag (on supported network ty= pes only)
    - -
    -<network>
-  <name>ovs-net</name>
-  <forward mode=3D'bridge'/>
-  <bridge name=3D'ovsbr0'/>
-  <virtualport type=3D'openvswitch'>
-    <parameters interfaceid=3D'09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&g=
t;
-  </virtualport>
-  <vlan trunk=3D'yes'>
-    <tag id=3D'42' nativeMode=3D'untagged'/>
-    <tag id=3D'47'/>
-  </vlan>
-  <portgroup name=3D'dontpanic'>
-    <vlan>
-      <tag id=3D'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 0.10.0. Network - connections that support guest-transparent VLAN tagging include - 1) type=3D'bridge' interfaces connected to an Open vSwitch bridge - Since 0.10.0, 2) SRIOV Virtual - Functions (VF) used via type=3D'hostdev' (direct device - assignment) Since 0.10.0, and 3) - SRIOV VFs used via type=3D'direct' with mode=3D'passthrough' - (macvtap "passthru" mode) 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=3D'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=3D'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 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=3D'bridge'/>
-  <bridge name=3D'br0'/>
-  <port isolated=3D'yes'/>
-</network>
-
    - -

    - 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=3D'private'/>
-    <interface dev=3D"eth20"/>
-    <interface dev=3D"eth21"/>
-    <interface dev=3D"eth22"/>
-    <interface dev=3D"eth23"/>
-    <interface dev=3D"eth24"/>
-  </forward>
-  <portgroup name=3D'engineering' default=3D'yes'>
-    <virtualport type=3D'802.1Qbh'>
-      <parameters profileid=3D'test'/>
-    </virtualport>
-    <bandwidth>
-      <inbound average=3D'1000' peak=3D'5000' burst=3D'5120'/>
-      <outbound average=3D'1000' peak=3D'5000' burst=3D'5120'/>
-    </bandwidth>
-  </portgroup>
-  <portgroup name=3D'sales' trustGuestRxFilters=3D'no'>
-    <virtualport type=3D'802.1Qbh'>
-      <parameters profileid=3D'salestest'/>
-    </virtualport>
-    <bandwidth>
-      <inbound average=3D'500' peak=3D'2000' burst=3D'2560'/>
-      <outbound average=3D'128' peak=3D'256' burst=3D'256'/>
-    </bandwidth>
-  </portgroup>
-...
    - -

    - 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 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 support= ed - subelements are <bandwidth> - (described here) - and <virtualport> - (documented here). - 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=3D'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 - 1.2.10). See - the Network - interfaces 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 1.0.6. -

    - -

    - As shown in this - 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=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.128" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <route address=3D"192.168.222.0" prefix=3D"24" gateway=3D"192.168.122=
.2"/>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64"/>
-  <route family=3D"ipv6" address=3D"2001:db8:ca2:3::" prefix=3D"64" gat=
eway=3D"2001:db8:ca2:2::2"/>
-  <route family=3D"ipv6" address=3D"2001:db9:4:1::" prefix=3D"64" gatew=
ay=3D"2001:db8:ca2:2::3" metric=3D'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=3D'00:16:3E:5D:C7:9E'/>
-<domain name=3D"example.com"/>
-<dns>
-  <txt name=3D"example" value=3D"example value"/>
-  <forwarder addr=3D"8.8.8.8"/>
-  <forwarder domain=3D'example.com' addr=3D"8.8.4.4"/>
-  <forwarder domain=3D'www.example.com'/>
-  <srv service=3D'name' protocol=3D'tcp' domain=3D'test-domain-name' ta=
rget=3D'.'
-    port=3D'1024' priority=3D'10' weight=3D'10'/>
-  <host ip=3D'192.168.122.2'>
-    <hostname>myhost</hostname>
-    <hostname>myhostalias</hostname>
-  </host>
-</dns>
-<ip address=3D"192.168.122.1" netmask=3D"255.255.255.0" localPtr=3D"yes=
">
-  <dhcp>
-    <range start=3D"192.168.122.100" end=3D"192.168.122.254">
-      <lease expiry=3D'1' unit=3D'hours'/>
-    </range>
-    <host mac=3D"00:16:3e:77:e2:ed" name=3D"foo.example.com" ip=3D"192.=
168.122.10">
-      <lease expiry=3D'30' unit=3D'minutes'/>
-    </host>
-    <host mac=3D"00:16:3e:3e:a9:1a" name=3D"bar.example.com" ip=3D"192.=
168.122.11"/>
-  </dhcp>
-</ip>
-<ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64" localPt=
r=3D"yes"/>
-<route family=3D"ipv6" address=3D"2001:db9:ca1:1::" prefix=3D"64" gatew=
ay=3D"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 0.8.8 -
    -
    dns
    -
    The dns element of a network contains configuration - information for the virtual network's DNS - server Since 0.9.3. - -

    - The dns element can have an optional enable - attribute 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 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 - 1.1.3, domain 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 attribut= es, 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 embed= ded spaces - or commas. value is a single string that can contain multiple = values - separated by commas. 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 0.9.3 -
    -
    -
    -
    srv
    -
    The dns element can have also 0 or more s= rv - record elements. Each srv record element defines = a DNS SRV record - and has 2 mandatory and 5 optional attributes. The mandatory a= ttributes - 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 0.9.9 -
    -
    -
    -
    ip
    -
    The address attribute defines an IPv4 address in - dotted-decimal format, or an IPv6 address in standard colon-separa= ted - hexadecimal format, that will be configured on the bridge device - associated with the virtual network. To the guests this IPv4 addre= ss - 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=3D'255.255.255.0' could also be given as - prefix=3D'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 attri= bute - (since 3.0.0) configures the DNS serv= er to - not forward any reverse DNS requests for IP addresses from the net= work - configured by the address and - netmask/prefix attributes. For some unus= ual - network prefixes (not divisible by 8 for IPv4 or not divisible by = 4 for - IPv6) libvirt may be unable to compute the PTR domain automaticall= y. - The ip element is supported sin= ce - 0.3.0. IPv6, multiple addresses on a single network, - family, and prefix are supported - since 0.8.7. The ip elem= ent 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 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 0.3.0) and IPv6 - (since 1.0.1), but only for one IP - address of each type per network. The following sub-elements a= re - supported: -
    -
    range
    -
    The start and end attributes o= n the - range element specify the boundaries of a poo= l of - addresses to be provided to DHCP clients. These two addres= ses - must lie within the scope of the network defined on the pa= rent - ip element. There may be zero or more - range elements specified. - 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 th= e 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 defi= ned - 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 t= he - mac attribute. - Since 0.4.5 -
    -
    bootp
    -
    The optional bootp element specifies BOOTP - options to be provided by the DHCP server for IPv4 only. T= wo - attributes are supported: file is mandatory a= nd - gives the file to be used for the boot image; - server is optional and gives the address of t= he - 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 ele= ment - is used. The BOOTP options currently have to be the same f= or - all address ranges and statically assigned addresses. Since 0.7.1 (server - since 0.7.3) -
    -
    - -

    - Optionally, range and host element= s can - have lease child element which specifies the le= ase - 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=3D'0'). - Since 6.3.0 -

    - -
    -
    -
    -
    - -

    Network namespaces

    - -

    - A special XML namespace is available for passing options - directly to the underlying dnsmasq configuration - file 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=3Dbar= and - cname=3D*.foo.example.com,master.example.com directly t= o the - underlying dnsmasq instance. - 

    -<network xmlns:dnsmasq=3D'http://libvirt.org/schemas/network/dnsmasq/1.=
0'>
-  ...
-  <dnsmasq:options>
-    <dnsmasq:option value=3D"foo=3Dbar"/>
-    <dnsmasq:option value=3D"cname=3D*.foo.example.com,master.example.c=
om"/>
-  </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=3D"virbr0"/>
-  <forward mode=3D"nat"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64"/>
-</network>
    - - -

    - Below is a variation of the above example which adds an IPv6 - dhcp range definition. -

    - - 
    -<network>
-  <name>default6</name>
-  <bridge name=3D"virbr0"/>
-  <forward mode=3D"nat"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64">
-    <dhcp>
-      <range start=3D"2001:db8:ca2:2:1::10" end=3D"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=3D"virbr0"/>
-  <forward mode=3D"nat">
-    <nat ipv6=3D'yes'>
-      <port start=3D'1024' end=3D'65535'/>
-    </nat>
-
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"fdXX:XXXX:XXXX:NNNN:: prefix=3D"64"/&g=
t;
-</network>
    - -

    IPv6 NAT addressing has some caveats over the more straight - forward IPv4 case. - RFC 4193 - 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 algor= ithm - 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 - 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=3D"virbr1"/>
-  <forward mode=3D"route" dev=3D"eth1"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"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 1.0.3 -

    - - 
    -<network>
-  <name>local6</name>
-  <bridge name=3D"virbr1"/>
-  <forward mode=3D"route" dev=3D"eth1"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64">
-    <dhcp>
-      <host name=3D"paul" ip=3D"2001:db8:ca2:2:3::1"/>
-      <host id=3D"0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip=3D"2001:db8:=
ca2:2:3::2"/>
-      <host id=3D"0:3:0:1:0:16:3e:11:22:33" name=3D"ralph" ip=3D"2001:d=
b8:ca2:2:3::3"/>
-      <host id=3D"0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
-        name=3D"badbob" ip=3D"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 1.0.6 -

    - - 
    -<network>
-  <name>net7</name>
-  <bridge name=3D"virbr7"/>
-  <forward mode=3D"route"/>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:7::1" prefix=3D"64">
-    <dhcp>
-      <range start=3D"2001:db8:ca2:7::100" end=3D"2001:db8:ca2::1ff"/&g=
t;
-      <host id=3D"0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
-        name=3D"lucas" ip=3D"2001:db8:ca2:2:3::4"/>
-    </dhcp>
-  </ip>
-  <route family=3D"ipv6" address=3D"2001:db8:ca2:8::" prefix=3D"64" gat=
eway=3D"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=3D"virbr2"/>
-  <ip address=3D"192.168.152.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.152.2" end=3D"192.168.152.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:3::1" prefix=3D"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 1.0.3 -

    - - 
    -<network>
-  <name>sixnet</name>
-  <bridge name=3D"virbr6"/>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:6::1" prefix=3D"64">
-    <dhcp>
-      <host name=3D"peter" ip=3D"2001:db8:ca2:6:6::1"/>
-      <host id=3D"0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip=3D"2001:db8:=
ca2:6:6::2"/>
-      <host id=3D"0:3:0:1:0:16:3e:11:22:33" name=3D"dariusz" ip=3D"2001=
:db8:ca2:6:6::3"/>
-      <host id=3D"0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
-        name=3D"anita" ip=3D"2001:db8:ca2:6:6::4"/>
-    </dhcp>
-  </ip>
-</network>
    - -

    Using an existing host bridge

    - -

    - 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=3D"bridge"/>
-  <bridge name=3D"br0"/>
-</network>
    - -

    Using a macvtap "direct" connection - -

    - 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=3D"bridge">
-    <interface dev=3D"eth20"/>
-    <interface dev=3D"eth21"/>
-    <interface dev=3D"eth22"/>
-    <interface dev=3D"eth23"/>
-    <interface dev=3D"eth24"/>
-  </forward>
-</network>
    - -

    Network config with no gateway address= es

    - -

    - A valid network definition can contain no IPv4 or IPv6 addresses. Suc= h a definition - can be used for a "very private" or "very isolated" network since it w= ill not be - possible to communicate with the virtualization host via this network.= However, - this virtual network interface can be used for communication between v= irtual guest - systems. This works for IPv4 and (Since 1.0.1)<= /span> IPv6. - However, the new ipv6=3D'yes' must be added for guest-to-guest IPv6 - communication. -

    - - 
    -<network ipv6=3D'yes'>
-  <name>nogw</name>
-  <uuid>7a3b7497-1ec7-8aef-6d5c-38dff9109e93</uuid>
-  <bridge name=3D"virbr2" stp=3D"on" delay=3D"0"/>
-  <mac address=3D'00:16:3E:5D:C7:9E'/>
-</network>
    - - - 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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Network XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +This page provides an introduction to the network XML format. For backgrou= nd +information on the concepts referred to here, consult the `relevant wiki +page `__. + +Element and attribute overview +------------------------------ + +The root element required for all virtual networks is named ``network`` an= d has +no configurable attributes (although :since:`since 0.10.0` there is one op= tional +read-only attribute - when examining the live configuration of a network, = the +attribute ``connections``, if present, specifies the number of guest inter= faces +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. + +:: + + + default + 3e3fce45-4f53-4fa7-bb32-11f34168b82b + + .. + .. + + ... + +``name`` + The content of the ``name`` element provides a short name for the virtu= al + 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:`Sin= ce + 0.3.0` +``uuid`` + The content of the ``uuid`` element provides a globally unique identifi= er for + the virtual network. The format must be RFC 4122 compliant, eg + ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/crea= ting a + new network, a random UUID is generated. :since:`Since 0.3.0` + The ``metadata`` node can be used by applications to store custom metad= ata 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 nam= espace + 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-gu= est + 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 `__ 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 overri= de the + setting in the network. + +Connectivity +~~~~~~~~~~~~ + +The next set of elements control how a virtual network is provided connect= ivity +to the physical LAN (if at all). + +:: + + ... + + + + + ... + +``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 de= fining + a new network with a ```` mode of "nat", "route", or "open" (o= r an + isolated network with no ```` element), libvirt will automatic= ally + 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 th= e 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 corre= ct + egress port for packets based on destination MAC address) will be manag= ed. In + the default ``kernel`` setting, the kernel automatically adds and remov= es + 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 mana= gement + of the MAC table (in the case of the Linux host bridge, this means enab= ling + vlan_filtering on the bridge, and disabling learning and unicast_filter= for + all bridge ports), and explicitly adds/removes entries to the table acc= ording + to the MAC addresses in the domain interface configurations. Allowing l= ibvirt + to manage the MAC table can improve performance - with a Linux host bri= dge, + for example, turning off learning and unicast_flood on ports has its own + performance advantage, and can also lead to an additional boost by perm= itting + 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 wor= king + (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 sp= ecify + the `firewalld `__ zone for the bridge of a netw= ork + with ``forward`` mode of "nat", "route", "open", or one with no ``forwa= rd`` + specified. By default, the bridges of all virtual networks with these f= orward + modes are placed in the firewalld zone named "libvirt", which permits + incoming DNS, DHCP, TFTP, and SSH to the host from guests on the networ= k. + This behavior can be changed either by modifying the libvirt zone (using + firewalld management tools), or by placing the network in a different z= one + (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 wi= ll be + the MTU assigned to the bridge device when libvirt creates it, and ther= eafter + also assigned to all tap devices created to connect guest interfaces. N= etwork + types not specifically mentioned here don't support having an MTU set i= n 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 ```` mode of "nat" or "route" (or an isolated + network with no ```` element). :since:`Since 0.4.5` + + If the optional ``localOnly`` attribute on the ``domain`` element is "y= es", + 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 ups= tream + DNS server. If ``localOnly`` is "no", and by default, unresolved reques= ts + **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 follow= ing + are valid settings for ``mode`` (if there is a ``forward`` element but = mode + is not specified, ``mode=3D'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 physic= al + 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 for= warded + using plain routing, since IPv6 has no concept of NAT. Firewall rule= s will + allow outbound connections to any other network device whether ether= net, + wireless, dialup, or VPN. If the ``dev`` attribute is set, the firew= all + 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 gues= ts, + 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 ```` 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 ``
    `` subelem= ents + and ``start`` and ``stop`` attributes: + + :: + + ... + + +
    + + + ... + + 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 ```` can be set via the subel= ement + ````: + + :: + + ... + + + + + + ... + + :since:`Since 6.5.0` it is possible to enable NAT with IPv6 networki= ng. As + noted above, IPv6 has historically done plain forwarding and thus to= avoid + breaking historical compatibility, IPv6 NAT must be explicitly reque= sted. + + :: + + ... + + + + ... + + ``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 t= he + ``dev`` attribute is set, firewall rules will restrict forwarding to= the + named device only. This presumes that the local LAN router has suita= ble + routing table entries to return traffic to this host. All incoming a= nd + 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 `__ on the guest's + interfaces.) :since:`Since 0.4.2` + ``open`` + As with mode=3D'route', guest network traffic will be forwarded to t= he + 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=3D'open' is set, the ``dev`` attribute cannot be set (becaus= e the + forward dev is enforced with firewall rules, and the purpose of + forward=3D'open' is to have a forwarding mode where libvirt doesn't = add any + firewall rules). This mode presumes that the local LAN router has su= itable + routing table entries to return traffic to this host, and that some = other + management system has been used to put in place any necessary firewa= ll + 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 `__ 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 ```` eleme= nt has + been specified, :since:`Since 0.9.4` ), 2) an existing Open vSwitch = bridge + that was configured outside of libvirt (if both a ```` + element **and** a ```= ` 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 + ```` subelements, :since:`Since 0.9.4` ) (see `Direct + attachment to physical interface `__ + for descriptions of the various macvtap modes). libvirt doesn't atte= mpt to + manage the bridge interface at all, thus the ```` 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 ```` subelements of = the + ```` element; when using 802.1Qbh mode (as indicated by the + ```` 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.1= Qbh, + 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 co= nnect + each guest to the network (this requires that the physical interface= s used + be connected to a vepa-capable hardware switch. The physical interfa= ce to + be used will be picked from among those listed in ```` + subelements of the ```` 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" mod= e 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 pic= ked + from among those listed in ```` subelements of the + ```` 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 t= he + attach will fail (usually either a domain start, or a hotplug interf= ace + attach to a domain). :since:`Since 0.9.4` + ``hostdev`` + This network facilitates PCI Passthrough of a network device. A netw= ork + device is chosen from the interface pool and directly assigned to the + guest using generic device passthrough, after first optionally setti= ng the + device's MAC address and vlan tag to the configured value, and optio= nally + associating the device with an 802.1Qbh capable switch using a + ```` element. Note that - due to limitations in standard + single-port PCI ethernet card driver design - only SR-IOV (Single Ro= ot I/O + Virtualization) virtual function (VF) devices can be assigned in this + manner; to assign a standard single-port PCI or PCIe ethernet card t= o a + guest, use the traditional ```` device definition. :since:`= Since + 0.10.0` + + To force use of a particular type of device assignment, a interface can have an optional ``driver`` sub-elem= ent with + a ``name`` attribute set to either "vfio" (VFIO is a new method of d= evice + assignment that is compatible with UEFI Secure Boot) or "kvm" (the l= egacy + 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 spec= ified, + device assignment will fail if the requested method of device assign= ment + isn't available on the host. When not specified, the default is "vfi= o" 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:`S= ince + 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 ```` device, the + difference being that this method allows specifying a MAC address, v= lan + tag, and ```` for the passed-through device. If these + capabilities are not required, if you have a standard single-port PC= I, + PCIe, or USB network card that doesn't support SR-IOV (and hence wou= ld + anyway lose the configured MAC address during reset after being assi= gned + to the guest domain), or if you are using a version of libvirt older= than + 0.10.0, you should use a standard ```` device definition in= the + domain's configuration to assign the device to the guest instead of + defining an ```` pointing to= a + network with ````. + + As mentioned above, a ```` element can have multiple ```` + subelements, each one giving the name of a physical interface that can = be + used for this network :since:`Since 0.9.4` : + + :: + + ... + + + + + + + + ... + + :since:`since 0.10.0` , ```` also has an optional read-only + attribute - when examining the live configuration of a network, the att= ribute + ``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 fun= ction, + by using the ```` subelement to call out the corresponding physical + interface associated with multiple virtual interfaces: + + :: + + ... + + + + ... + + When a guest interface is being constructed, libvirt will pick an inter= face + from this list to use for the connection. In modes where physical inter= faces + can be shared by multiple guest interfaces, libvirt will choose the int= erface + that currently has the least number of connections. For those modes tha= t 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 ``
    `` elements, each of which has + ```` (must always be ``'pci'``), ````, ````, + ````\ and ```` attributes. + + :: + + ... + + +
    +
    +
    + + ... + + Alternatively the interface pool can also be defined using a single phy= sical + function ```` subelement to call out the corresponding physical int= erface + associated with multiple virtual interfaces (similar to passthrough mod= e): + + :: + + ... + + + + ... + +Quality of service +^^^^^^^^^^^^^^^^^^ + +:: + + ... + + + + + + ... + +The ```` element allows setting quality of service for a partic= ular +network ( :since:`since 0.9.4` ). Setting ``bandwidth`` for a network is +supported only for networks with a ```` 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 ```` element can only be a subelement of a domain's +````, a subelement of a ````, or a subelement of a +```` in a ````. + +As a subelement of a domain's ````, the bandwidth only applies = to +that one interface of the domain. As a subelement of a ````, the +bandwidth is a total aggregate bandwidth to/from all guest interfaces atta= ched +to that network, **not** to each guest interface individually. If a domain= 's +```` has ```` element values higher than the aggrega= te for +the entire network, then the aggregate bandwidth for the ```` tak= es +precedence. This is because the two choke points are independent of each o= ther +where the domain's ```` bandwidth control is applied on the +interface's tap device, while the ```` bandwidth control is appli= ed on +the interface part of the bridge device created for that network. + +As a subelement of a ```` in a ````, if a domain's +```` has a ``portgroup`` attribute in its ```` element +**and** if the ```` itself has no ```` element, then= the +```` element of the portgroup will be applied individually to e= ach +guest interface defined to be a member of that portgroup. Any ```` +element in the domain's ```` definition will override the setti= ng 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 a= pplied +for that traffic direction. So, when you want to shape only incoming traff= ic, +use ``inbound`` only, and vice versa. Each of these elements have one mand= atory +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 filt= ers + 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 att= ribute + guarantees minimal throughput for shaped interfaces. This, however, req= uires + that all traffic goes through one point where QoS decisions can take pl= ace, + hence why this attribute works only for virtual networks for now (that = is + ```` with a forward type of route, nat, op= en or no + forward at all). Moreover, the virtual network the interface is connect= ed 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``. Howeve= r, + ``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) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + + ovs-net + + + + + + + + + + + + + + + + +If (and only if) the network connection used by the guest supports VLAN ta= gging +transparent to the guest, an optional ```` element can specify one o= r 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=3D'bridge' interfaces connected to an Open vSwitch bridge :since:`Sin= ce +0.10.0` , 2) SRIOV Virtual Functions (VF) used via type=3D'hostdev' (direc= t device +assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type=3D'dire= ct' with +mode=3D'passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All = other +connection types, including standard linux bridges and libvirt's own virtu= al +networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) sw= itches +provide their own way (outside of libvirt) to tag guest traffic onto a spe= cific +VLAN. Each tag is given in a separate ```` subelement of ```` (= for +example: ````). For VLAN trunking of multiple tags (= which is +supported only on Open vSwitch connections), multiple ```` subelement= s 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=3D'yes'`` can be added to t= he +toplevel ```` 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.` Thi= s is +done with the optional ``nativeMode`` attribute on the ```` subelemen= t: +``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute = of the +```` subelement containing ``nativeMode`` sets which VLAN is consider= ed to +be the "native" VLAN for this interface, and the ``nativeMode`` attribute +determines whether or not traffic for that VLAN will be tagged. + +```` elements can also be specified in a ```` element, as= well +as directly in a domain's ```` element. In the case that a vlan= tag +is specified in multiple locations, the setting in ```` takes +precedence, followed by the setting in the ```` selected by the +interface config. The ```` in ```` will be selected only if= none +is given in ```` or ````. + +Isolating ports from one another +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + + isolated-ports + + + + + +: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 o= nly +supported for networks that use a Linux host bridge to connect guest inter= faces +via a standard tap device (i.e. those with a forward mode of nat, route, o= pen, +bridge, or no forward mode). + +Portgroups +^^^^^^^^^^ + +:: + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + ... + +:since:`Since 0.9.4` A portgroup provides a method of easily putting guest +connections to the network into different classes, with each class potenti= ally +having a different level/type of service. :since:`Since 0.9.4` Each networ= k can +have multiple portgroup elements (and one of those can optionally be desig= nated +as the 'default' portgroup for the network), and each portgroup has a name= , as +well as various attributes and subelements associated with it. The current= ly +supported subelements are ```` (described in `Quality of servic= e`_) +and ```` (documented +`here `__). If a domain interface +definition specifies a portgroup (by adding a ``portgroup`` attribute to t= he +```` subelement), that portgroup's info will be merged into the +interface's configuration. If no portgroup is given in the interface defin= ition, +and one of the network's portgroups has ``default=3D'yes'``, that default +portgroup will be used. If no portgroup is given in the interface definiti= on, +and there is no default portgroup, then none will be used. Any ```` +specified directly in the domain XML will take precedence over any setting= in +the chosen portgroup. if a ```` is specified in the portgroup +(and/or directly in the network definition), the multiple virtualports wil= l 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`` whi= ch can +be used to set that attribute of the same name for each domain interface u= sing +this portgroup ( :since:`since 1.2.10` ). See the `Network +interfaces `__ section of the domain XML +documentation for more details. Note that an explicit setting of this attr= ibute +in the portgroup overrides the network-wide setting, and an explicit setti= ng 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 its= elf +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 addres= ses. +Such networks are useful to provide host connectivity to networks which ar= e only +reachable via a guest. A guest with connectivity both to the guest-only ne= twork +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" n= etwork +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 specificat= ion as +well as the IPv4 and IPv6 definitions for network addresses which are refe= rred +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 lo= wer +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 giv= en a +lower metric (for example, the default metric of "1"). + +:: + + ... + + + + + + + + + + ... + +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 netwo= rk, +and optionally enable DHCP services. These elements are only valid for iso= lated +networks (no ``forward`` element specified), and for those with a forward = mode +of 'route' or 'nat'. + +:: + + ... + + + + + + + + + + myhost + myhostalias + + + + + + + + + + + + + + + + +``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 de= vice + when it is created. Generally it is best to not specify a MAC address w= hen + creating a network - in this case, if a defined MAC address is needed f= or + proper operation, libvirt will automatically generate a random MAC addr= ess + 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 wh= ere + 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 lib= virt + for this network (and any other configuration in ```` will be igno= red). + If ``enable`` is "yes" or unspecified (including the complete absence o= f any + ```` 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 resol= ution + requests for names that are not qualified with a domain (i.e. names wit= h 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 netw= ork'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 ```` are: + + ``forwarder`` + The dns element can have 0 or more ```` elements. Each + forwarder element defines an alternate DNS server to use for some, o= r all, + DNS requests sent to this network's DNS server. There are two attrib= utes - + ``domain``, and ``addr``; at least one of these must be specified in= any + ```` element. If both ``domain`` and ``addr`` are specifi= ed, + then all requests that match the given domain will be forwarded to t= he DNS + server at addr. If only ``domain`` is specified, then all matching d= omains + 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 itse= lf, + 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 elem= ent + defines a DNS TXT record and has two attributes, both required: a na= me + 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. val= ue 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 t= o 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 for= mat, + 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 address= es, + 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 net= work + address can be specified with the ``prefix`` attribute, which is an int= eger + (for example, ``netmask=3D'255.255.255.0'`` could also be given as + ``prefix=3D'24'``). The ``family`` attribute is used to specify the typ= e 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 netw= ork. + The optional ``localPtr`` attribute ( :since:`since 3.0.0` ) configures= the + DNS server to not forward any reverse DNS requests for IP addresses fro= m the + network configured by the ``address`` and ``netmask``/``prefix`` attrib= utes. + 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` . I= Pv6, + multiple addresses on a single network, ``family``, and ``prefix`` are + supported :since:`since 0.8.7` . The ``ip`` element may contain the fol= lowing + elements: + + ``tftp`` + The optional ``tftp`` element and its mandatory ``root`` attribute e= nable + TFTP services. The attribute specifies the path to the root directory + served via TFTP. The ``tftp`` element is not supported for IPv6 addr= esses, + 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 ne= twork. + 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 ea= ch + type per network. The following sub-elements are supported: + + ``range`` + The ``start`` and ``end`` attributes on the ``range`` element spe= cify + the boundaries of a pool of addresses to be provided to DHCP clie= nts. + These two addresses must lie within the scope of the network defi= ned on + the parent ``ip`` element. There may be zero or more ``range`` el= ements + 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 prede= fined + IP addresses by the built-in DHCP server. Any IPv4 ``host`` eleme= nt + must specify the MAC address of the host to be assigned a given n= ame + (via the ``mac`` attribute), the IP to be assigned to that host (= via + the ``ip`` attribute), and the name itself (the ``name`` attribut= e). + The IPv6 ``host`` element differs slightly from that for IPv4: th= ere is + no ``mac`` attribute since a MAC address has no defined meaning in + IPv6. Instead, the ``name`` attribute is used to identify the hos= t to + be assigned the IPv6 address. For DHCPv6, the name is the plain n= ame 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 inst= ead of + the ``mac`` attribute. :since:`Since 0.4.5` + ``bootp`` + The optional ``bootp`` element specifies BOOTP options to be prov= ided + 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 f= rom + 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:`Sin= ce + 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 ``exp= iry`` + and ``unit`` (which accepts ``seconds``, ``minutes`` and ``hours`` a= nd + defaults to ``minutes`` if omitted). The minimal lease time is 2 min= utes, + except when setting an infinite lease time (``expiry=3D'0'``). :sinc= e:`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=3Dbar`` and +``cname=3D*.foo.example.com,master.example.com`` directly to the underlying +dnsmasq instance. + +:: + + + ... + + + + + + +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 configurat= ion +that allows guest OS to get outbound connectivity regardless of whether th= e host +uses ethernet, wireless, dialup, or VPN networking without requiring any +specific admin configuration. In the absence of host networking, it at lea= st +allows guests to talk directly to each other. + +:: + + + default + + + + + + + + + + +Below is a variation of the above example which adds an IPv6 dhcp range +definition. + +:: + + + default6 + + + + + + + + + + + + + + +IPv6 NAT based network +~~~~~~~~~~~~~~~~~~~~~~ + +Below is a variation for also providing IPv6 NAT. This can be especially u= seful +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 I= Pv6 +routing. + +:: + + + default6 + + + + + + + + + + + + + + +IPv6 NAT addressing has some caveats over the more straight forward IPv4 c= ase. +`RFC 4193 `__ defines the address ran= ge +fd00::/8 for /48 IPv6 private networks. It should be concatenated with a r= andom +40-bit string (i.e. 10 random hexadecimal digits replacing the X values ab= ove, +RFC 4193 provides an +`algorithm `__ if you d= o not +have a source of sufficient randomness). This leaves 0 through ffff for su= bnets +(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 `__ to have your IPv6 NAT netwo= rk +correctly preferenced over IPv4. + +Routed network config +~~~~~~~~~~~~~~~~~~~~~ + +This is a variant on the default network which routes traffic from the vir= tual +network to the LAN without applying any NAT. It requires that the IP addre= ss +range be pre-configured in the routing tables of the router on the host ne= twork. +This example further specifies that guest traffic may only go out via the +``eth1`` host network device. + +:: + + + local + + + + + + + + + + +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` + +:: + + + local6 + + + + + + + + + + + + + + + + + +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 the= re +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 subne= t as) +one of the addresses defined for this . :since:`Since 1.0.6` + +:: + + + net7 + + + + + + + + + + + +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. + +:: + + + private + + + + + + + + + +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 prove= n to +be a more reliable way of specifying the interface and its association wit= h 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` + +:: + + + sixnet + + + + + + + + + + + +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). + +:: + + + host-bridge + + + + +Using a macvtap "direct" connection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 0.9.4, QEMU and KVM only, requires Linux kernel 2.6.34 or ne= wer` +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 de= vice). +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 inbou= nd 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 phy= sical +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 me= ans +for this communication (e.g. a second interface on each guest that is conn= ected +to an isolated network). The other forward modes that use macvtap (private, +vepa, and passthrough) would be used in a similar fashion. + +:: + + + direct-macvtap + + + + + + + + + +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 sin= ce it +will not be possible to communicate with the virtualization host via this +network. However, this virtual network interface can be used for communica= tion +between virtual guest systems. This works for IPv4 and :since:`(Since 1.0.= 1)` +IPv6. However, the new ipv6=3D'yes' must be added for guest-to-guest IPv6 +communication. + +:: + + + nogw + 7a3b7497-1ec7-8aef-6d5c-38dff9109e93 + + + 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 p= lug types listed later This part of the network port XML provides setting quality of service. Incoming and outgoing traffic can be shaped independently. The ``bandwi= dth`` element and its child elements are described in the - `QoS `__ section of the Network XML. In + `QoS `__ section of the Network = XML. In addition the ``classID`` attribute may exist to provide the ID of the t= raffic 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,fl= oor* 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 kilob= ytes in a single burst at *peak* speed as described in the Network XML -documentation at `https://libvirt.org/formatnetwork.html#elementQoS `__. +documentation at +`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 opti= onal, 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#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 =3D [ ] docs_html_in_files =3D [ - 'formatnetwork', 'formatnode', 'index', 'remote', @@ -72,6 +71,7 @@ docs_rst_files =3D [ 'formatcheckpoint', 'formatdomain', 'formatdomaincaps', + 'formatnetwork', 'formatnetworkport', 'formatnwfilter', 'formatsecret', --=20 2.35.1 From nobody Sat May 11 06:14:09 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1649865793; cv=none; d=zohomail.com; s=zohoarc; b=LsCglS4Oj8cf2oFUxMfTTfP0yAmMbOoqpPW/dgcbOJNKFPgk9yMYUlbL7LopU8I9o8IbOYT9SIGHCPqpxvMEEY7oaNkLk00Mhf0PmXjXiTavkhNVdxwnGcFolIqXArIdGmIELylpNet0EPKiUgI+lPc2vYc+flESy2KQZ15k/D8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865793; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=116nBy3gyR6YbGz5z4tR3E3L1BDCeHXuFZaGbyWi930=; b=lWLkiQpZMVueOawUI8d1nlOFGeoBFAhrdnZzt6zyb+igbY6KNUro42NndddwWAitmvsr8wRLTGizlurAW3KXkOmVj4pQ3pulk2R4JEbzvQJ1LCEkcuR5XkpRjT4jwqoYgPaR9RUuuOrADg+HJjQx631TC+oypnZkH244I2meWks= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1649865793922281.3866382083502; Wed, 13 Apr 2022 09:03:13 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-167-T43JDHfBPsq9XAW-q0Mf5A-1; Wed, 13 Apr 2022 12:03:06 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3C0F58E91EA; Wed, 13 Apr 2022 16:02:34 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2505F145B96C; Wed, 13 Apr 2022 16:02:34 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id F0CA81940345; Wed, 13 Apr 2022 16:02:33 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 18E13194037E for ; Wed, 13 Apr 2022 16:02:33 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 0449A141511C; Wed, 13 Apr 2022 16:02:33 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 273A7145BA5D for ; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865792; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=116nBy3gyR6YbGz5z4tR3E3L1BDCeHXuFZaGbyWi930=; b=HPQRjUTXm1MnDsDbPaKHOR+b6iEzkpOB6XEBfC0jymk74Wvf80Q5afx1UhhOoEkyrWLUv8 qCKAVMSiODBFqw6uDLOQVc9s3VSOU+mNkPFjV37bZh9WH/LuI0GVdjvaCBt3R/WSXwIv1s dq0Mp75V7rMd4KLKbFzFON/isUzkNlY= X-MC-Unique: T43JDHfBPsq9XAW-q0Mf5A-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 14/14] docs: Convert 'formatnode' page to rst Date: Wed, 13 Apr 2022 18:02:15 +0200 Message-Id: <580e7a196ed194129fbfb6835cf9a5362493737e.1649865545.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649865795622100002 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Michal Privoznik --- 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 incl= ude a nested capability ``mdev_types`` which enumerates all supported mdev types on the physical d= evice, along with the type attributes available through sysfs. A detailed descrip= tion of the XML format for the ``mdev_types`` capability can be found -`here `__. +`here `__. The following example shows how we might represent an NVIDIA GPU device th= at 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 re= quires root privileges, therefore, ``virsh nodedev-dumpxml`` must be executed accordingly. A description of the XML format for the ``vpd`` capability ca= n be -found `here `__. +found `here `__. 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, t= he 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 @@ - - - - -

    Node devices XML format

    - -
      - -

      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. - 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 definin= g 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. T= he - value of the element will correspond with the device parent's - name element or computer if the device d= oes - not have any parent. -
      -
      driver
      -
      - This elements reports the driver in use for this device. The prese= nce - 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, and controls which further subelements will be - present to describe the node: -
      -
      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 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 devi= ce - (and this device is, by implication, an SRIOV Virtual - Function (VF)). -
      -
      virt_functions
      -
      - In this case this device is an SRIOV PF, and the capab= ility - element will have a list of address - subelements, one for each VF on this PF. If the host s= ystem - supports reporting it (via the "sriov_totalvfs" file i= n 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 curren= tly - active since 1.3.0; in th= is 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 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 devi= ce - with respect to NUMA. For example, the optional - node attribute tells which NUMA node is the P= CI - device associated with. -
      -
      pci-express
      -
      - This optional element contains information on PCI Express pa= rt of - the device. For example, it can contain a child element - link which addresses the PCI Express device's l= ink. - While a device has its own capabilities - (validity=3D'cap'), the actual run time capabil= ities - are negotiated on the device initialization - (validity=3D'sta'). The link eleme= nt then - contains three attributes: port which says in w= hich - port is the device plugged in, speed (in - GigaTransfers per second) and width for the num= ber - of lanes used. Since the port can't be negotiated, it's not - exposed in ./pci-express/link/[@validity=3D'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<= /dd> -
      ufo
      udp-fragmentation-offload=
      -
      gso
      generic-segmentation-offl= oad
      -
      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-acc= ess
      -
      txudptnl
      tx-udp-tunnel-segmen= tation
      -
      switchdev
      kernel-forward-plan= e-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. 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 followi= ng - 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 - 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 d= evice - belongs. This is a read-only field that is reported by the - device driver. -
      -
      attr
      -
      - This optional element can occur multiple times. It represe= nts a - vendor-specific attribute that is used to configure this - mediated device. It has two required attributes: - name and value. Note that the or= der - in which attributes are set may be important for some devi= ces. - The order that they appear in the xml definition determine= s 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) common= ly - 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 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 dev= ice. - 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 h= ost. - 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 providi= ng - 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 6.10.0 - This device is capable of creating mediated devices. - The sub-elements are summarized in - mdev_types capability. -
      -
      -
      -
      -
      -
      -
      -
      - -

      mdev_types capability

      - -

      - PCI, C= SS - 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 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 w= hich - 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 optiona= lly - 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 PC= I device.
      -
      part_number
      -
      An extension to the Device ID (or Subsystem ID) in the Configu= ration - 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 attr= ibute - (since-character upper-case ASCII alphanumeric indexes). Content= s will vary - depending on a vendor.
      -
      - All fields are optional and are not guaranteed to be present for a g= eneric 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 attr= ibute - (since-character upper-case ASCII alphanumeric indexes). Content= s will vary depending - on a vendor.
      -
      system_field
      -
      Zero or many of those elements with an index attr= ibute (since-character - upper-case ASCII alphanumeric indexes, except for letter 'A'). M= ay store system-specific - data related to a PCI device.
      -
      - All fields are optional and are not guaranteed to be present for a g= eneric 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 mean= s external to Libvirt. -

      -

      - The device name and all fields may contain only the following charac= ters: - [0-9a-zA-F -_,.:;=3D]. - The device name may be as large as 65535 bytes while fields are limi= ted with 255 bytes. -

      - -

      Examples

      - -

      The following are some example node device XML outputs:

      - 
      -<device>
-  <name>computer</name>
-  <capability type=3D'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=3D'net'>
-    <interface>eth1</interface>
-    <address>00:27:13:6a:fe:00</address>
-    <capability type=3D'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&g=
t;
-  <parent>pci_0000_00_04_0</parent>
-  <driver>
-    <name>igb</name>
-  </driver>
-  <capability type=3D'pci'>
-    <class>0x020000</class>
-    <domain>0</domain>
-    <bus>2</bus>
-    <slot>0</slot>
-    <function>0</function>
-    <product id=3D'0x10c9'>82576 Gigabit Network Connection</prod=
uct>
-    <vendor id=3D'0x8086'>Intel Corporation</vendor>
-    <capability type=3D'virt_functions'>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x10' function=3D=
'0x0'/>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x10' function=3D=
'0x2'/>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x10' function=3D=
'0x4'/>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x10' function=3D=
'0x6'/>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x11' function=3D=
'0x0'/>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x11' function=3D=
'0x2'/>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x11' function=3D=
'0x4'/>
-    </capability>
-    <iommuGroup number=3D'12'>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x00' function=3D=
'0x0'/>
-      <address domain=3D'0x0000' bus=3D'0x02' slot=3D'0x00' function=3D=
'0x1'/>
-    </iommuGroup>
-    <pci-express>
-      <link validity=3D'cap' port=3D'1' speed=3D'2.5' width=3D'1'/>
-      <link validity=3D'sta' speed=3D'2.5' width=3D'1'/>
-    </pci-express>
-  </capability>
-</device>
-
      - - - 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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Node devices XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 elements in `the domain +XML `__. These devices are represented = as a +hierarchy, where a device on a bus has a parent of the bus controller devi= ce; +the root of the hierarchy is the node named "computer". + +When represented in XML, a node device uses the top-level ``device`` eleme= nt, +with the following elements present according to the type of device: + +``name`` + The name for this device. The name will be alphanumeric, with words sep= arated + by underscore. For many devices, the name is just the bus type and addr= ess, + as in "pci_0000_00_02_1" or "usb_1_5_3", but some devices are able to p= rovide + 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 tha= t is + reported by the device driver. If this element is set when defining a n= ew + device, it will be ignored. +``parent`` + This element identifies the parent node in the device hierarchy. The va= lue 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 o= f this + element in the output XML depends on whether the underlying device mana= ger + (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 no= de. 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=3D'cap'``), the actual run time capabilities a= re + negotiated on the device initialization (``validity=3D'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=3D'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-ele= ments +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 `__. + :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-elem= ents +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 identifie= r. +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 cryptograph= ic +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`` elemen= t for +``mdev_types`` type will contain a list of ``type`` elements, which list a= ll +mdev types supported on the physical device. :since:`Since 3.4.0` Each ``t= ype`` +element has a single ``id`` attribute that holds an official vendor-suppli= ed +identifier for the type. It supports the following sub-elements: + +``name`` + The ``name`` element holds a vendor-supplied code name for the given me= diated + device type. This is an optional element. +``deviceAPI`` + The value of this element describes how an instance of the given type w= ill 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 c= reated + 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 Configura= tion + Space header which allows vendors the flexibility to identify an additi= onal + 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 Sp= ace + 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-chara= cter + 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-chara= cter + 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-chara= cter + 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 tim= e 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 -_,.:;=3D]``. 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: + +:: + + + computer + + 2241B36 + + LENOVO + ThinkPad T500 + R89055N + c9488981-5049-11cb-9c1c-993d0230b4cd + + + LENOVO + 6FET82WW (3.12 ) + 11/26/2009 + + + + + + net_eth1_00_27_13_6a_fe_00 + pci_0000_00_19_0 + + eth1 +
      00:27:13:6a:fe:00
      + + +       + + + pci_0000_02_00_0 + /sys/devices/pci0000:00/0000:00:04.0/0000:02:00.0 + pci_0000_00_04_0 + + igb + + + 0x020000 + 0 + 2 + 0 + 0 + 82576 Gigabit Network Connection + Intel Corporation + +
      +
      +
      +
      +
      +
      +
      + + +
      +
      + + + + + + + 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 =3D [ ] docs_html_in_files =3D [ - 'formatnode', 'index', 'remote', 'storage', @@ -73,6 +72,7 @@ docs_rst_files =3D [ 'formatdomaincaps', 'formatnetwork', 'formatnetworkport', + 'formatnode', 'formatnwfilter', 'formatsecret', 'formatsnapshot', --=20 2.35.1