From nobody Sun May 5 22:07:47 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=1615830011; cv=none; d=zohomail.com; s=zohoarc; b=eIFplq2XeZRM5eeUWzrSG9KG7VvLVM5u1NstaDfx4+oGUrpEpySiF0+wO4NX1D06jE+7OZkRFVY9hiUGBnAPkPX76NAxW8g6HL+dZk5oTuSXggYqqw6EMxApuDaPWkz4+ECGHy6uPuYYg/RKZvlI8T4Na1TjclMs5uPPjfLs/5s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615830011; h=Content-Type:Content-Transfer-Encoding:Cc: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=pWG7lmORIG9mByA7sY4rrlWRjkK9Wr3w4WP/Trv+glo=; b=O+ypn/K6/oIFI/W0RGRvzj61v58kKsUbmPhfox1fgTIfAcl9PlJiRA0Ci8xAsUexAILfyRG2WpalZM8wJem095PbGhw1pl/SAr4sbDBR1jVOCXegBevf2snwMOmvWIrI+JAa0g2X80+Y1OPpShprFXH941PsMaJSvWLctdS6KOI= 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) header.from= 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 161583001172255.05750221748235; Mon, 15 Mar 2021 10:40:11 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-28-2ijczaU0M9qnBpY5XClKEQ-1; Mon, 15 Mar 2021 13:40:07 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id F017C84B9A4; Mon, 15 Mar 2021 17:40:01 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 9436061F5C; Mon, 15 Mar 2021 17:40:01 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 0779D57DC1; Mon, 15 Mar 2021 17:40:01 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12FHdtjR003438 for ; Mon, 15 Mar 2021 13:39:55 -0400 Received: by smtp.corp.redhat.com (Postfix) id 4C2EA2B9FA; Mon, 15 Mar 2021 17:39:55 +0000 (UTC) Received: from nautilus.local (unknown [10.40.192.76]) by smtp.corp.redhat.com (Postfix) with ESMTP id 73B57620DE; Mon, 15 Mar 2021 17:39:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615830010; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=pWG7lmORIG9mByA7sY4rrlWRjkK9Wr3w4WP/Trv+glo=; b=NTC8RPfTBX3KSpk6ePCkeRbt/lf6DrKEdm05Xa3DfPSdkV5TeMvylcbuFdOwMFa5MlGVDh 43XROJY7KKycMwB3BMSJufX8krIAdXo3+uibSkIawJ+/z2v4MYuORmivcv79NzPNTEo0rM Rqx4TzIP8Ziz9n8wdTXznRdediXrfb0= X-MC-Unique: 2ijczaU0M9qnBpY5XClKEQ-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH v2 1/3] docs: html.in: Drop the architecture page Date: Mon, 15 Mar 2021 18:39:44 +0100 Message-Id: <061dfc25ed08fa0d62b96c2d615e1b96ff0b9055.1615829966.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 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) Content-Type: text/plain; charset="utf-8" The page isn't linked from anywhere and the contents is dated. Images related to the page are also dropped. Signed-off-by: Erik Skultety --- docs/architecture.gif | Bin 5571 -> 0 bytes docs/architecture.html.in | 82 ------------- docs/architecture.svg | 239 -------------------------------------- docs/meson.build | 2 - 4 files changed, 323 deletions(-) delete mode 100644 docs/architecture.gif delete mode 100644 docs/architecture.html.in delete mode 100644 docs/architecture.svg diff --git a/docs/architecture.gif b/docs/architecture.gif deleted file mode 100644 index 9b820eef1878da18981e133d23c645a88df35dd6..000000000000000000000000000= 0000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5571 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 R`lpZjsjvD=3DfC2>o06Q2Wc~SrX diff --git a/docs/architecture.html.in b/docs/architecture.html.in deleted file mode 100644 index 7a5cf2dca8..0000000000 --- a/docs/architecture.html.in +++ /dev/null @@ -1,82 +0,0 @@ - - - - -

libvirt architecture

- -

- Currently libvirt supports 2 kind of virtualization, and its - internal structure is based on a driver model which simplifies - adding new - engines: -

- -
    - -

    Xen support

    - -

    When running in a Xen environment, programs using libvirt have to e= xecute -in "Domain 0", which is the primary Linux OS loaded on the machine. That OS -kernel provides most if not all of the actual drivers used by the set of -domains. It also runs the Xen Store, a database of information shared by t= he -hypervisor, the backend drivers, any running domains, and libxl (aka libxe= nlight). -libxl provides a set of APIs for creating and managing domains, which can = be used -by applications such as the xl tool provided by Xen or libvirt. The hyperv= isor, -drivers, kernels and daemons communicate though a shared system bus -implemented in the hypervisor. The figure below tries to provide a view of -this environment:

    - 3D"The -

    The library will interact with libxl for all management operations -on a Xen system.

    -

    Note that the libvirt libxl driver only supports root access.

    - -

    QEMU and KVM support

    - -

    The model for QEMU and KVM is completely similar, basically KVM is = based -on QEMU for the process controlling a new domain, only small details diffe= rs -between the two. In both case the libvirt API is provided by a controlling -process forked by libvirt in the background and which launch and control t= he -QEMU or KVM process. That program called libvirt_qemud talks though a spec= ific -protocol to the library, and connects to the console of the QEMU process in -order to control and report on its status. Libvirt tries to expose all the -emulations models of QEMU, the selection is done when creating the new -domain, by specifying the architecture and machine type targeted.

    -

    The code controlling the QEMU process is available in the -qemud/ directory.

    - -

    Driver based architecture

    - -

    As the previous section explains, libvirt can communicate using dif= ferent -channels with the current hypervisor, and should also be able to use -different kind of hypervisor. To simplify the internal design, code, ease -maintenance and simplify the support of other virtualization engine the -internals have been structured as one core component, the libvirt.c module -acting as a front-end for the library API and a set of hypervisor drivers -defining a common set of routines. That way the Xen Daemon access, the Xen -Store one, the Hypervisor hypercall are all isolated in separate C modules -implementing at least a subset of the common operations defined by the -drivers present in driver.h:

    -
      -
    • xend_internal: implements the driver functions though the Xen - Daemon
      • -
    • xs_internal: implements the subset of the driver available thoug= h the - Xen Store
      • -
    • xen_internal: provide the implementation of the functions possib= le via - direct hypervisor access
      • -
    • proxy_internal: provide read-only Xen access via a proxy, the pr= oxy code - is in the proxy/ directory.
      • -
    • xm_internal: provide support for Xen defined but not running - domains.
      • -
    • qemu_internal: implement the driver functions for QEMU and - KVM virtualization engines. It also uses a qemud/ specific daemon - which interacts with the QEMU process to implement libvirt API.
      • -
    • test: this is a test driver useful for regression tests of the - front-end part of libvirt.
      • -
    -

    Note that a given driver may only implement a subset of those funct= ions, -(for example saving a Xen domain state to disk and restoring it is only -possible though the Xen Daemon), in that case the driver entry points for -unsupported functions are initialized to NULL.

    -

    - - diff --git a/docs/architecture.svg b/docs/architecture.svg deleted file mode 100644 index 1e1555156b..0000000000 --- a/docs/architecture.svg +++ /dev/null @@ -1,239 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -XenBus - -drivers - -XenStore - -Kernel0 - -KernelU - -KernelU - -Xen Hypervisor - -Xend - -Dom0 - -DomU - -DomU - -Hardware - - diff --git a/docs/meson.build b/docs/meson.build index 36cf679929..fdaf369271 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -7,7 +7,6 @@ docs_assets =3D [ 'android-chrome-192x192.png', 'android-chrome-256x256.png', 'apple-touch-icon.png', - 'architecture.gif', 'browserconfig.xml', 'favicon.ico', 'favicon-16x16.png', @@ -32,7 +31,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'architecture', 'auth', 'bugs', 'cgroups', --=20 2.29.2 From nobody Sun May 5 22:07:47 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.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 63.128.21.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=1615830069; cv=none; d=zohomail.com; s=zohoarc; b=JQ+kKmlejrVuTu04KqtMG+vV6eEoI9TbNmhRlgMea6GNLsME9YOe7EANhaJtW6mSl5N3zWLQl6rGfOpB5fDTSK0n6aRg0F91cEjFYNwYAeaNT/CDguEmwGuDV5JGfsC542t3j2Fzrqi/R0OCzAdo4x3Pr/sqznWzUZtFky3STYQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615830069; h=Content-Type:Content-Transfer-Encoding:Cc: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=MtTbCcLQSuRubQqoKJtC4cDbJVxynOt51K9tcLEoZrc=; b=dfZcLqnlmosfdkPYhPMqj7PUQ1M/7wtWhpzFj1ysPPoLgJN9A87u5NreTfesnNfJonwigR8ZTjUp7m0ty16ukVxWcvr6mks+tFplloKGoxchndA73g2nmF9BfZQmUkMC6tc64ZkFOX5kj/habqANO5Aru3yIXOnU6uwKghMWyl0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1615830069599464.22166903759523; Mon, 15 Mar 2021 10:41:09 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-196-0nrCL-HSOM-76EelrgM4bQ-1; Mon, 15 Mar 2021 13:40:10 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 1B00684B9A8; Mon, 15 Mar 2021 17:40:03 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E43A0100F49F; Mon, 15 Mar 2021 17:40:02 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 91FAE1800B99; Mon, 15 Mar 2021 17:40:02 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12FHduSQ003448 for ; Mon, 15 Mar 2021 13:39:56 -0400 Received: by smtp.corp.redhat.com (Postfix) id 74A32620DE; Mon, 15 Mar 2021 17:39:56 +0000 (UTC) Received: from nautilus.local (unknown [10.40.192.76]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9CC3D19EF2; Mon, 15 Mar 2021 17:39:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615830068; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=MtTbCcLQSuRubQqoKJtC4cDbJVxynOt51K9tcLEoZrc=; b=iNHDqP5IXHMCmlywkNW6V+O2dO0hEMpdE/UqTQCc2usMFWaOKI90r1LLGhiQyBuNMVGARv eKy1CiXqN+dmuvnqcm9uEgjX/C19xG03L8DRR9jvXB3hHRmXTSQpipr5uPjqOTEeu4EpAZ 8A2CT5QLzTmn9j7HQWyrnVzDapmtOd4= X-MC-Unique: 0nrCL-HSOM-76EelrgM4bQ-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH v2 2/3] docs: html.in: Convert auth to rst Date: Mon, 15 Mar 2021 18:39:45 +0100 Message-Id: <3fd45b094e93e9baf1ad5c9e9b76b3a7611b92c2.1615829966.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 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) Content-Type: text/plain; charset="utf-8" There was one external reference to this page's section which was fixed manually. Signed-off-by: Erik Skultety --- docs/auth.html.in | 368 --------------------------------- docs/auth.rst | 343 ++++++++++++++++++++++++++++++ docs/kbase/locking-sanlock.rst | 2 +- docs/meson.build | 2 +- 4 files changed, 345 insertions(+), 370 deletions(-) delete mode 100644 docs/auth.html.in create mode 100644 docs/auth.rst diff --git a/docs/auth.html.in b/docs/auth.html.in deleted file mode 100644 index 9b940a8598..0000000000 --- a/docs/auth.html.in +++ /dev/null @@ -1,368 +0,0 @@ - - - - -

    Connection authentication

    -

    - When connecting to libvirt, some connections may require client - authentication before allowing use of the APIs. The set of possible - authentication mechanisms is administrator controlled, independent - of applications using libvirt. Once authenticated, libvirt can apply - fine grained access control to the operatio= ns - performed by a client. -

    - -
      - -

      Client configuration

      - -

      - When connecting to a remote hypervisor which requires authentication, -most libvirt applications will prompt the user for the credentials. It is -also possible to provide a client configuration file containing all the -authentication credentials, avoiding any interaction. Libvirt will look -for the authentication file using the following sequence: -

      -
        -
      1. The file path specified by the $LIBVIRT_AUTH_FILE environment - variable.
        2. -
      2. The file path specified by the "authfile=3D/some/file" URI - query parameter
        3. -
      3. The file $XDG_CONFIG_HOME/libvirt/auth.conf
        4. -
      4. The file /etc/libvirt/auth.conf
        5. -
      - -

      - The auth configuration file uses the traditional ".ini" - style syntax. There are two types of groups that can be present in - the config. First there are one or more credential - sets, which provide the actual authentication credentials. The keys - within the group may be: -

      - -
        -
      • username: the user login name to act as. This - is relevant for ESX, Xen, HyperV and SSH, but probably not - the one you want to libvirtd with SASL.
        • -
      • authname: the name to authorize as. This is - what is commonly required for libvirtd with SASL.
        • -
      • password: the secret password
        • -
      • realm: the domain realm for SASL, mostly - unused
        • -
      - -

      - Each set of credentials has a name, which is part of the group - entry name. Overall the syntax is -

      - - 
      -[credentials-$NAME]
-credname1=3Dvalue1
-credname2=3Dvalue2
      - -

      - For example, to define two sets of credentials used for production - and test machines, using libvirtd, and a further ESX server for dev: -

      -
      -[credentials-test]
-authname=3Dfred
-password=3D123456
-
-[credentials-prod]
-authname=3Dbar
-password=3Dletmein
-
-[credentials-dev]
-username=3Djoe
-password=3Dhello
-
-[credentials-defgrp]
-username=3Ddefuser
-password=3Ddefpw
      - -

      - The second set of groups provide mappings of credentials to - specific machine services. The config file group names compromise - the service type and host: -

      - - 
      -[auth-$SERVICE-$HOSTNAME]
-credentials=3D$CREDENTIALS
      - -

      - For example, following the previous example, here is how to - map some machines. For convenience libvirt supports a default - mapping of credentials to machines: -

      - - 
      -[auth-libvirt-test1.example.com]
-credentials=3Dtest
-
-[auth-libvirt-test2.example.com]
-credentials=3Dtest
-
-[auth-libvirt-demo3.example.com]
-credentials=3Dtest
-
-[auth-libvirt-prod1.example.com]
-credentials=3Dprod
-
-[auth-libvirt-default]
-credentials=3Ddefgrp
-
-[auth-esx-dev1.example.com]
-credentials=3Ddev
-
-[auth-esx-default]
-credentials=3Ddefgrp
      - - -

      - The following service types are known to libvirt: -

      - -
        -
      • esx - used for connections to an ESX or - VirtualCenter server
        • -
      • hyperv - used for connections to an HyperV - server
        • -
      • libvirt - used for connections to a libvirtd - server, which is configured with SASL auth
        • -
      • ssh - used for connections to a remote QEMU driver - over SSH
        • -
      - -

      - Applications using libvirt are free to use this same configuration - file for storing other credentials. For example, it can be used - to storage VNC or SPICE login credentials -

      - -

      Server configuration

      -

      -The libvirt daemon allows the administrator to choose the authentication -mechanisms used for client connections on each network socket independentl= y. -This is primarily controlled via the libvirt daemon master config file in -/etc/libvirt/libvirtd.conf. Each of the libvirt sockets can -have its authentication mechanism configured independently. There is -currently a choice of none, polkit, and sa= sl. -The SASL scheme can be further configured to choose between a large -number of different mechanisms. -

      -

      UNIX socket permissions/group<= /h2> -

      -If libvirt does not contain support for PolicyKit, then access control for -the UNIX domain socket is done using traditional file user/group ownership -and permissions. There are 2 sockets, one for full read-write access, the -other for read-only access. The RW socket will be restricted (mode 0700) to -only allow the root user to connect. The read-only socket will -be open access (mode 0777) to allow any user to connect. -

      -

      -To allow non-root users greater access, the libvirtd.conf file -can be edited to change the permissions via the unix_sock_rw_perms, -config parameter and to set a user group via the unix_sock_group -parameter. For example, setting the former to mode 0770 and t= he -latter wheel would let any user in the wheel group connect to -the libvirt daemon. -

      -

      UNIX socket PolicyKit auth

      -

      -If libvirt contains support for PolicyKit, then access control options are -more advanced. The auth_unix_rw parameter will default to -polkit, and the file permissions will default to 0777 -even on the RW socket. Upon connecting to the socket, the client applicati= on -will be required to identify itself with PolicyKit. The default policy for= the -RW daemon socket will require any application running in the current deskt= op -session to authenticate using the user's password. This is akin to s= udo -auth, but does not require that the client application ultimately run as r= oot. -Default policy will still allow any application to connect to the RO socke= t. -

      -

      -The default policy can be overridden by creating a new policy file in the -/etc/polkit-1/rules.d directory. Information on the options -available can be found by reading the polkit(8) man page. The -two libvirt actions are named org.libvirt.unix.manage for full -management access, and org.libvirt.unix.monitor for read-only -access. -

      -

      -As an example, creating /etc/polkit-1/rules.d/80-libvirt-manage.rule= s -with the following gives the user fred full management access -when accessing from an active local session: -

      -
      polkit.addRule(function(action, subject) {
-  if (action.id =3D=3D "org.libvirt.unix.manage" &&
-      subject.local && subject.active && subject.user =3D=
=3D "fred") {
-      return polkit.Result.YES;
-  }
-});
      -

      -Older versions of PolicyKit used policy files ending with .pkla in the -local override directory /etc/polkit-1/localauthority/50-local.d/. -Compatibility with this older format is provided by polkit-pkla-compat. As an -example, this gives the user fred full management access: -

      -
      [Allow fred libvirt management permissions]
-Identity=3Dunix-user:fred
-Action=3Dorg.libvirt.unix.manage
-ResultAny=3Dyes
-ResultInactive=3Dyes
-ResultActive=3Dyes
      -

      SASL pluggable authentication

      - -

      -Libvirt integrates with the cyrus-sasl library to provide a pluggable auth= entication -system using the SASL protocol. SASL can be used in combination with libvi= rtd's TLS -or TCP socket listeners. When used with the TCP listener, the SASL mechani= sm is -rqeuired to provide session encryption in addition to authentication. Only= a very -few SASL mechanisms are able to do this, and of those that can do it, only= the -GSSAPI plugin is considered acceptably secure by modern standards: -

      - -
      -
      GSSAPI
      -
      This is the current default mechanism to use with libvir= td. - It uses the Kerberos v5 authentication protocol underneath, and as= suming - the Kerberos client/server are configured with modern ciphers (AES= ), - it provides strong session encryption capabilities.
      - -
      DIGEST-MD5
      -
      This was previously set as the default mechanism to use with lib= virtd. - It provides a simple username/password based authentication mechan= ism - that includes session encryption. - RFC 6331, howe= ver, - documents a number of serious security flaws with DIGEST-MD5 and a= s a - result marks it as OBSOLETE. Specific concerns are th= at - it is vulnerable to MITM attacks and the MD5 hash can be brute-for= ced - to reveal the password. A replacement is provided via the SCRAM me= chanism, - however, note that this does not provide encryption, so the SCRAM - mechanism can only be used on the libvirtd TLS listener. -
      - -
      PASSDSS-3DES-1
      -
      This provides a simple username/password based authentication - mechanism that includes session encryption. The current cyrus-sasl - implementation does not provide a way to validate the server's - public key identity, thus it is susceptible to a MITM attacker - impersonating the server. It is also not enabled in many OS - distros when building SASL libraries.
      - -
      KERBEROS_V4
      -
      This uses the obsolete Kerberos v4 protocol to provide both auth= entication - and session encryption. Kerberos v4 protocol has been obsolete sin= ce the - early 1990's and has known security vulnerabilities so this will n= ever be - used in practice.
      -
      - -

      - Other SASL mechanisms, not listed above, can only be used when the l= ibvirtd - TLS or UNIX socket listeners. -

      - -

      Username/password auth

      -

      -As noted above, the DIGEST-MD5 mechanism is considered obsolete and should -not be used anymore. To provide a simple username/password auth scheme on -the libvirt UNIX socket or TLS listeners, however, it is possible to use -the SCRAM mechanism. The auth_unix_ro, auth_unix_rw, -auth_tls config params in libvirt.conf can be us= ed -to turn on SASL auth in these listeners. -

      -

      -Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), a -config change is required to enable plain password auth. This is done by -editing /etc/sasl2/libvirt.conf to set the mech_list -parameter to scram-sha-1. -

      -

      -Out of the box, no user accounts are defined, so no clients will be able t= o authenticate -on the TCP socket. Adding users and setting their passwords is done with t= he saslpasswd2 -command. When running this command it is important to tell it that the app= name is libvirt. -As an example, to add a user fred, run -

      - 
      -# saslpasswd2 -a libvirt fred
-Password: xxxxxx
-Again (for verification): xxxxxx
-
      -

      -To see a list of all accounts the sasldblistusers2 command ca= n be used. -This command expects to be given the path to the libvirt user database, wh= ich is kept -in /etc/libvirt/passwd.db -

      - 
      -# sasldblistusers2 -f /etc/libvirt/passwd.db
-fred@t60wlan.home.berrange.com: userPassword
-
      -

      -Finally, to disable a user's access, the saslpasswd2 command = can be used -again: -

      - 
      -# saslpasswd2 -a libvirt -d fred
-
      -

      GSSAPI/Kerberos auth

      -

      -The plain TCP listener of the libvirt daemon defaults to using SASL for au= thentication. -The libvirt SASL config also defaults to GSSAPI, so there is no need to ed= it the -SASL config when using GSSAPI. If the libvirtd TLS or UNIX listeners are u= sed, -then the Kerberos session encryption will be disabled since it is not requ= ired -in these scenarios - only the plain TCP listener needs encryption -

      -

      -Some operating systems do not install the SASL kerberos plugin by default.= It -may be necessary to install a sub-package such as cyrus-sasl-gssapi<= /code>. -To check whether the Kerberos plugin is installed run the pluginview= er -program and verify that gssapi is listed, e.g.: -

      - 
      -# pluginviewer
-...snip...
-Plugin "gssapiv2" [loaded],     API version: 4
-        SASL mechanism: GSSAPI, best SSF: 56
-        security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIA=
LS|MUTUAL_AUTH
-        features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
-
      -

      -Next it is necessary for the administrator of the Kerberos realm to -issue a principal for the libvirt server. There needs to be one -principal per host running the libvirt daemon. The principal should be -named libvirt/full.hostname@KERBEROS.REALM. This is -typically done by running the kadmin.local command on the -Kerberos server, though some Kerberos servers have alternate ways of -setting up service principals. Once created, the principal should be -exported to a keytab, copied to the host running the libvirt daemon -and placed in /etc/libvirt/krb5.tab -

      - 
      -# kadmin.local
-kadmin.local: add_principal libvirt/foo.example.com
-Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
-Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
-Principal "libvirt/foo.example.com@EXAMPLE.COM" created.
-
-kadmin.local:  ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.=
com@EXAMPLE.COM
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/=
libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-e=
xample.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-exam=
ple.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-f=
oo-example.tab.
-
-kadmin.local: quit
-
-# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5=
.tab
-# rm /root/libvirt-foo-example.tab
-
      -

      -Any client application wishing to connect to a Kerberos enabled libvirt se= rver -merely needs to run kinit to gain a user principal. This may = well -be done automatically when a user logs into a desktop session, if PAM is s= et up -to authenticate against Kerberos. -

      - - diff --git a/docs/auth.rst b/docs/auth.rst new file mode 100644 index 0000000000..26fa6c950c --- /dev/null +++ b/docs/auth.rst @@ -0,0 +1,343 @@ +=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 +Connection authentication +=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 + +When connecting to libvirt, some connections may require client +authentication before allowing use of the APIs. The set of possible +authentication mechanisms is administrator controlled, independent of +applications using libvirt. Once authenticated, libvirt can apply fine +grained `access control `__ to the operations performed by a +client. + +.. contents:: + +Client configuration +-------------------- + +When connecting to a remote hypervisor which requires authentication, +most libvirt applications will prompt the user for the credentials. It +is also possible to provide a client configuration file containing all +the authentication credentials, avoiding any interaction. Libvirt will +look for the authentication file using the following sequence: + +#. The file path specified by the $LIBVIRT_AUTH_FILE environment + variable. +#. The file path specified by the "authfile=3D/some/file" URI query + parameter +#. The file $XDG_CONFIG_HOME/libvirt/auth.conf +#. The file /etc/libvirt/auth.conf + +The auth configuration file uses the traditional ``".ini"`` style +syntax. There are two types of groups that can be present in the config. +First there are one or more **credential** sets, which provide the +actual authentication credentials. The keys within the group may be: + +- ``username``: the user login name to act as. This is relevant for + ESX, Xen, HyperV and SSH, but probably not the one you want to + libvirtd with SASL. +- ``authname``: the name to authorize as. This is what is commonly + required for libvirtd with SASL. +- ``password``: the secret password +- ``realm``: the domain realm for SASL, mostly unused + +Each set of credentials has a name, which is part of the group entry +name. Overall the syntax is + +:: + + [credentials-$NAME] + credname1=3Dvalue1 + credname2=3Dvalue2 + +For example, to define two sets of credentials used for production and +test machines, using libvirtd, and a further ESX server for dev: + +:: + + [credentials-test] + authname=3Dfred + password=3D123456 + + [credentials-prod] + authname=3Dbar + password=3Dletmein + + [credentials-dev] + username=3Djoe + password=3Dhello + + [credentials-defgrp] + username=3Ddefuser + password=3Ddefpw + +The second set of groups provide mappings of credentials to specific +machine services. The config file group names compromise the service +type and host: + +:: + + [auth-$SERVICE-$HOSTNAME] + credentials=3D$CREDENTIALS + +For example, following the previous example, here is how to map some +machines. For convenience libvirt supports a default mapping of +credentials to machines: + +:: + + [auth-libvirt-test1.example.com] + credentials=3Dtest + + [auth-libvirt-test2.example.com] + credentials=3Dtest + + [auth-libvirt-demo3.example.com] + credentials=3Dtest + + [auth-libvirt-prod1.example.com] + credentials=3Dprod + + [auth-libvirt-default] + credentials=3Ddefgrp + + [auth-esx-dev1.example.com] + credentials=3Ddev + + [auth-esx-default] + credentials=3Ddefgrp + +The following service types are known to libvirt: + +- ``esx`` - used for connections to an ESX or VirtualCenter server +- ``hyperv`` - used for connections to an HyperV server +- ``libvirt`` - used for connections to a libvirtd server, which is + configured with SASL auth +- ``ssh`` - used for connections to a remote QEMU driver over SSH + +Applications using libvirt are free to use this same configuration file +for storing other credentials. For example, it can be used to storage +VNC or SPICE login credentials + +Server configuration +-------------------- + +The libvirt daemon allows the administrator to choose the authentication +mechanisms used for client connections on each network socket +independently. This is primarily controlled via the libvirt daemon +master config file in ``/etc/libvirt/libvirtd.conf``. Each of the +libvirt sockets can have its authentication mechanism configured +independently. There is currently a choice of ``none``, ``polkit``, and +``sasl``. The SASL scheme can be further configured to choose between a +large number of different mechanisms. + +UNIX socket permissions/group +----------------------------- + +If libvirt does not contain support for PolicyKit, then access control +for the UNIX domain socket is done using traditional file user/group +ownership and permissions. There are 2 sockets, one for full read-write +access, the other for read-only access. The RW socket will be restricted +(mode 0700) to only allow the ``root`` user to connect. The read-only +socket will be open access (mode 0777) to allow any user to connect. + +To allow non-root users greater access, the ``libvirtd.conf`` file can +be edited to change the permissions via the ``unix_sock_rw_perms``, +config parameter and to set a user group via the ``unix_sock_group`` +parameter. For example, setting the former to mode ``0770`` and the +latter ``wheel`` would let any user in the wheel group connect to the +libvirt daemon. + +UNIX socket PolicyKit auth +-------------------------- + +If libvirt contains support for PolicyKit, then access control options +are more advanced. The ``auth_unix_rw`` parameter will default to +``polkit``, and the file permissions will default to ``0777`` even on +the RW socket. Upon connecting to the socket, the client application +will be required to identify itself with PolicyKit. The default policy +for the RW daemon socket will require any application running in the +current desktop session to authenticate using the user's password. This +is akin to ``sudo`` auth, but does not require that the client +application ultimately run as root. Default policy will still allow any +application to connect to the RO socket. + +The default policy can be overridden by creating a new policy file in +the ``/etc/polkit-1/rules.d`` directory. Information on the options +available can be found by reading the ``polkit(8)`` man page. The two +libvirt actions are named ``org.libvirt.unix.manage`` for full +management access, and ``org.libvirt.unix.monitor`` for read-only +access. + +As an example, creating +``/etc/polkit-1/rules.d/80-libvirt-manage.rules`` with the following +gives the user ``fred`` full management access when accessing from an +active local session: + +:: + + polkit.addRule(function(action, subject) { + if (action.id =3D=3D "org.libvirt.unix.manage" && + subject.local && subject.active && subject.user =3D=3D "fred") { + return polkit.Result.YES; + } + }); + +Older versions of PolicyKit used policy files ending with .pkla in the +local override directory ``/etc/polkit-1/localauthority/50-local.d/``. +Compatibility with this older format is provided by +`polkit-pkla-compat `__. As an +example, this gives the user ``fred`` full management access: + +:: + + [Allow fred libvirt management permissions] + Identity=3Dunix-user:fred + Action=3Dorg.libvirt.unix.manage + ResultAny=3Dyes + ResultInactive=3Dyes + ResultActive=3Dyes + +SASL pluggable authentication +----------------------------- + +Libvirt integrates with the cyrus-sasl library to provide a pluggable +authentication system using the SASL protocol. SASL can be used in +combination with libvirtd's TLS or TCP socket listeners. When used with +the TCP listener, the SASL mechanism is rqeuired to provide session +encryption in addition to authentication. Only a very few SASL +mechanisms are able to do this, and of those that can do it, only the +GSSAPI plugin is considered acceptably secure by modern standards: + +GSSAPI + **This is the current default mechanism to use with libvirtd**. It + uses the Kerberos v5 authentication protocol underneath, and assuming + the Kerberos client/server are configured with modern ciphers (AES), + it provides strong session encryption capabilities. +DIGEST-MD5 + This was previously set as the default mechanism to use with + libvirtd. It provides a simple username/password based authentication + mechanism that includes session encryption. `RFC + 6331 `__, however, documents a + number of serious security flaws with DIGEST-MD5 and as a result + marks it as ``OBSOLETE``. Specific concerns are that it is vulnerable + to MITM attacks and the MD5 hash can be brute-forced to reveal the + password. A replacement is provided via the SCRAM mechanism, however, + note that this does not provide encryption, so the SCRAM mechanism + can only be used on the libvirtd TLS listener. +PASSDSS-3DES-1 + This provides a simple username/password based authentication + mechanism that includes session encryption. The current cyrus-sasl + implementation does not provide a way to validate the server's public + key identity, thus it is susceptible to a MITM attacker impersonating + the server. It is also not enabled in many OS distros when building + SASL libraries. +KERBEROS_V4 + This uses the obsolete Kerberos v4 protocol to provide both + authentication and session encryption. Kerberos v4 protocol has been + obsolete since the early 1990's and has known security + vulnerabilities so this will never be used in practice. + +Other SASL mechanisms, not listed above, can only be used when the +libvirtd TLS or UNIX socket listeners. + +Username/password auth +~~~~~~~~~~~~~~~~~~~~~~ + +As noted above, the DIGEST-MD5 mechanism is considered obsolete and +should not be used anymore. To provide a simple username/password auth +scheme on the libvirt UNIX socket or TLS listeners, however, it is +possible to use the SCRAM mechanism. The ``auth_unix_ro``, +``auth_unix_rw``, ``auth_tls`` config params in ``libvirt.conf`` can be +used to turn on SASL auth in these listeners. + +Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), +a config change is required to enable plain password auth. This is done +by editing ``/etc/sasl2/libvirt.conf`` to set the ``mech_list`` +parameter to ``scram-sha-1``. + +Out of the box, no user accounts are defined, so no clients will be able +to authenticate on the TCP socket. Adding users and setting their +passwords is done with the ``saslpasswd2`` command. When running this +command it is important to tell it that the appname is ``libvirt``. As +an example, to add a user ``fred``, run + +:: + + # saslpasswd2 -a libvirt fred + Password: xxxxxx + Again (for verification): xxxxxx + +To see a list of all accounts the ``sasldblistusers2`` command can be +used. This command expects to be given the path to the libvirt user +database, which is kept in ``/etc/libvirt/passwd.db`` + +:: + + # sasldblistusers2 -f /etc/libvirt/passwd.db + fred@t60wlan.home.berrange.com: userPassword + +Finally, to disable a user's access, the ``saslpasswd2`` command can be +used again: + +:: + + # saslpasswd2 -a libvirt -d fred + +GSSAPI/Kerberos auth +~~~~~~~~~~~~~~~~~~~~ + +The plain TCP listener of the libvirt daemon defaults to using SASL for +authentication. The libvirt SASL config also defaults to GSSAPI, so +there is no need to edit the SASL config when using GSSAPI. If the +libvirtd TLS or UNIX listeners are used, then the Kerberos session +encryption will be disabled since it is not required in these scenarios +- only the plain TCP listener needs encryption + +Some operating systems do not install the SASL kerberos plugin by +default. It may be necessary to install a sub-package such as +``cyrus-sasl-gssapi``. To check whether the Kerberos plugin is installed +run the ``pluginviewer`` program and verify that ``gssapi`` is listed, +e.g.: + +:: + + # pluginviewer + ...snip... + Plugin "gssapiv2" [loaded], API version: 4 + SASL mechanism: GSSAPI, best SSF: 56 + security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDEN= TIALS|MUTUAL_AUTH + features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQ= DN + +Next it is necessary for the administrator of the Kerberos realm to +issue a principal for the libvirt server. There needs to be one +principal per host running the libvirt daemon. The principal should be +named ``libvirt/full.hostname@KERBEROS.REALM``. This is typically done +by running the ``kadmin.local`` command on the Kerberos server, though +some Kerberos servers have alternate ways of setting up service +principals. Once created, the principal should be exported to a keytab, +copied to the host running the libvirt daemon and placed in +``/etc/libvirt/krb5.tab`` + +:: + + # kadmin.local + kadmin.local: add_principal libvirt/foo.example.com + Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Principal "libvirt/foo.example.com@EXAMPLE.COM" created. + + kadmin.local: ktadd -k /root/libvirt-foo-example.tab libvirt/foo.examp= le.com@EXAMPLE.COM + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/ro= ot/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-fo= o-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-e= xample.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvir= t-foo-example.tab. + + kadmin.local: quit + + # scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/k= rb5.tab + # rm /root/libvirt-foo-example.tab + +Any client application wishing to connect to a Kerberos enabled libvirt +server merely needs to run ``kinit`` to gain a user principal. This may +well be done automatically when a user logs into a desktop session, if +PAM is set up to authenticate against Kerberos. diff --git a/docs/kbase/locking-sanlock.rst b/docs/kbase/locking-sanlock.rst index fece9df80e..bd85c2e36e 100644 --- a/docs/kbase/locking-sanlock.rst +++ b/docs/kbase/locking-sanlock.rst @@ -180,7 +180,7 @@ helper binary will connect to libvirtd and thus it may = need to authenticate if libvirtd was configured to require that on the read-write UNIX socket. To provide the appropriate credentials to sanlock_helper, a `client authentication -file `__ needs to contain something like +file <../auth.html#client-configuration>`__ needs to contain something like the following: =20 :: diff --git a/docs/meson.build b/docs/meson.build index fdaf369271..ab0932ceb4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -31,7 +31,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'auth', 'bugs', 'cgroups', 'contact', @@ -103,6 +102,7 @@ docs_rst_files =3D [ 'api', 'apps', 'auditlog', + 'auth', 'bindings', 'best-practices', 'ci', --=20 2.29.2 From nobody Sun May 5 22:07:47 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.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 216.205.24.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=1615830069; cv=none; d=zohomail.com; s=zohoarc; b=c6G3nCooLa0RMx3wUnKURHhtkHpMZvk1NwZ0TPdI+sAoKQqX5ia5QEV+BSq44t+yHY+7JdYpK7bzJHH4oRj3K+bNMw2eL9np4bcuYccI2XoC6t0sngbkZt5fq/kmPIx3/FbaC3r2nxP8AzR79wpS+IBKbpg4ZJXqMqr8hPSE/mM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615830069; h=Content-Type:Content-Transfer-Encoding:Cc: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=fVw9WzSiGQYQYwg1ZvfFp+dWl48+McXiZFJu37fZOzo=; b=Y1lIZEMqM4fiBWDqGyodLJgw7aEld8XywBW8SGLhwAdYk0WC7qR7GffbJ6gdZUNGVO/h252J3ZLOIikD1aVeUBSw0+Yfg/4YOkiYFzWbOcjh1PD4NPx+M3EAd2KdXIweqCvpeEvj+Z6grFhNmqKE5eL5qG/NNZwQwemq320A40k= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1615830069723323.3787605304128; Mon, 15 Mar 2021 10:41:09 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-78-Z5ROL_OfN3aES-uBfgqhrA-1; Mon, 15 Mar 2021 13:40:13 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A7D8780006E; Mon, 15 Mar 2021 17:40:06 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 81FB262692; Mon, 15 Mar 2021 17:40:06 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 0E00457DC1; Mon, 15 Mar 2021 17:40:06 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12FHdvwD003457 for ; Mon, 15 Mar 2021 13:39:57 -0400 Received: by smtp.corp.redhat.com (Postfix) id 73B4D2B9FA; Mon, 15 Mar 2021 17:39:57 +0000 (UTC) Received: from nautilus.local (unknown [10.40.192.76]) by smtp.corp.redhat.com (Postfix) with ESMTP id C43B0620DE; Mon, 15 Mar 2021 17:39:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615830068; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=fVw9WzSiGQYQYwg1ZvfFp+dWl48+McXiZFJu37fZOzo=; b=G5c2hBx87Zy8uJpBchp7t2ES/RPXKgeQZB17TejbFIK7HAwZVAzlXqkNqISebgt4Lb24q0 LbHQqljY5igbLZ5aQz+t0b7IfUW/c9aSD9gQehLoz7hcWZrZcsa+TLqg5ZtBnyCa8f5zUt bB/Os9WJuaUo6OhMAhJgfDVnwjQFWIA= X-MC-Unique: Z5ROL_OfN3aES-uBfgqhrA-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH v2 3/3] docs: kbase: Fix a broken formatdomain reference in locking-sanlock Date: Mon, 15 Mar 2021 18:39:46 +0100 Message-Id: <1ac65e9fe8116c53749eeaebc7054637a516b085.1615829966.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety --- docs/kbase/locking-sanlock.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/kbase/locking-sanlock.rst b/docs/kbase/locking-sanlock.rst index bd85c2e36e..24895b42f4 100644 --- a/docs/kbase/locking-sanlock.rst +++ b/docs/kbase/locking-sanlock.rst @@ -173,7 +173,7 @@ Domain configuration =20 In case sanlock loses access to disk locks for some reason, it will kill all domains that lost their locks. This default behavior may be changed -using `on_lockfailure element `__ in +using `on_lockfailure element <../formatdomain.html#elementsEvents>`__ in domain XML. When this element is present, sanlock will call ``sanlock_helper`` (provided by libvirt) with the specified action. This helper binary will connect to libvirtd and thus it may need to --=20 2.29.2