[libvirt PATCH v2 0/3] docs: Convert html.in to rst (volume 1)
since v1: - fixed a broken heading reference from a kbase article caused by RST convers= ion - dropped architecture.html.in along with images v1: https://listman.redhat.com/archives/libvir-list/2021-March/msg00584.html Erik Skultety (3): docs: html.in: Drop the architecture page docs: html.in: Convert auth to rst docs: kbase: Fix a broken formatdomain reference in locking-sanlock docs/architecture.gif | Bin 5571 -> 0 bytes docs/architecture.html.in | 82 -------- docs/architecture.svg | 239 --------------------- docs/auth.html.in | 368 --------------------------------- docs/auth.rst | 343 ++++++++++++++++++++++++++++++ docs/kbase/locking-sanlock.rst | 4 +- docs/meson.build | 4 +- 7 files changed, 346 insertions(+), 694 deletions(-) delete mode 100644 docs/architecture.gif delete mode 100644 docs/architecture.html.in delete mode 100644 docs/architecture.svg delete mode 100644 docs/auth.html.in create mode 100644 docs/auth.rst --=20 2.29.2
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 <eskultet@redhat.com> --- 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..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5571 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 R`lpZjsjvD=fC2>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 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1 >libvirt architecture</h1> - - <p> - Currently libvirt supports 2 kind of virtualization, and its - internal structure is based on a driver model which simplifies - adding new - engines: - </p> - - <ul id="toc"></ul> - - <h2><a id="Xen">Xen support</a></h2> - - <p>When running in a Xen environment, programs using libvirt have to execute -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 the -hypervisor, the backend drivers, any running domains, and libxl (aka libxenlight). -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 hypervisor, -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:</p> - <img src="architecture.gif" alt="The Xen architecture" /> - <p>The library will interact with libxl for all management operations -on a Xen system.</p> - <p>Note that the libvirt libxl driver only supports root access.</p> - - <h2><a id="QEMU">QEMU and KVM support</a></h2> - - <p>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 differs -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 the -QEMU or KVM process. That program called libvirt_qemud talks though a specific -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.</p> - <p>The code controlling the QEMU process is available in the -<code>qemud/</code> directory.</p> - - <h2><a id="drivers">Driver based architecture</a></h2> - - <p>As the previous section explains, libvirt can communicate using different -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:</p> - <ul> - <li>xend_internal: implements the driver functions though the Xen - Daemon</li> - <li>xs_internal: implements the subset of the driver available though the - Xen Store</li> - <li>xen_internal: provide the implementation of the functions possible via - direct hypervisor access</li> - <li>proxy_internal: provide read-only Xen access via a proxy, the proxy code - is in the <code>proxy/</code> directory.</li> - <li>xm_internal: provide support for Xen defined but not running - domains.</li> - <li>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.</li> - <li>test: this is a test driver useful for regression tests of the - front-end part of libvirt.</li> - </ul> - <p>Note that a given driver may only implement a subset of those functions, -(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.</p> - <p></p> - </body> -</html> 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 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Creator: fig2dev Version 3.2.7b-dev --> -<!-- CreationDate: 2020-07-10 10:23:50 --> -<!-- Magnification: 1 --> -<svg xmlns="http://www.w3.org/2000/svg" - xmlns:xlink="http://www.w3.org/1999/xlink" - width="519pt" height="362pt" - viewBox="888 3963 8649 6024"> -<g fill="none"> -<!-- Line --> -<rect x="1050" y="7500" width="8325" height="1200" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<rect x="1050" y="4125" width="2475" height="3150" rx="105" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<polyline points=" 1050,6540 3540,6525" - stroke="#000000" stroke-width="15px" stroke-dasharray="60 60"/> -<!-- Line --> -<rect x="1140" y="6645" width="450" height="255" rx="105" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<rect x="1140" y="6930" width="450" height="255" rx="105" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<defs> -<clipPath id="cp0"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 8353,7665 8353,7785 8651,7751 8651,7700z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 1875,7725 8625,7725" clip-path="url(#cp0)" - stroke="#000000" stroke-width="45px"/> -<!-- Forward arrow to point 8625,7725 --> -<polygon points=" 8353,7785 8593,7725 8353,7665 8353,7785" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Backward arrow to point 1875,7725 --> -<polygon points=" 2147,7665 1907,7725 2147,7785 2147,7665" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<rect x="1650" y="5625" width="1350" height="750" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<defs> -<clipPath id="cp1"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 2790,6647 2910,6647 2876,6350 2825,6350z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 2850,7725 2850,6375" clip-path="url(#cp1)" - stroke="#000000" stroke-width="45px"/> -<!-- Forward arrow to point 2850,6375 --> -<polygon points=" 2910,6647 2850,6407 2790,6647 2910,6647" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<rect x="3975" y="4125" width="2475" height="3150" rx="105" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<rect x="6825" y="4125" width="2475" height="3150" rx="105" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<polyline points=" 3975,6540 6465,6525" - stroke="#000000" stroke-width="15px" stroke-dasharray="60 60"/> -<!-- Line --> -<polyline points=" 6825,6540 9315,6525" - stroke="#000000" stroke-width="15px" stroke-dasharray="60 60"/> -<!-- Line --> -<defs> -<clipPath id="cp2"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 5340,7322 5460,7322 5426,7025 5375,7025z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 5400,7725 5400,7050" clip-path="url(#cp2)" - stroke="#000000" stroke-width="45px"/> -<!-- Forward arrow to point 5400,7050 --> -<polygon points=" 5460,7322 5400,7082 5340,7322 5460,7322" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp3"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 7965,7322 8085,7322 8051,7025 8000,7025z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 8025,7725 8025,7050" clip-path="url(#cp3)" - stroke="#000000" stroke-width="45px"/> -<!-- Forward arrow to point 8025,7050 --> -<polygon points=" 8085,7322 8025,7082 7965,7322 8085,7322" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<rect x="1050" y="8925" width="8325" height="975" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<rect x="2100" y="4575" width="1350" height="750" - stroke="#000000" stroke-width="8px"/> -<!-- Line --> -<defs> -<clipPath id="cp4"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 3285,8053 3165,8053 3207,8343 3243,8343z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 3225,5325 3225,8325" clip-path="url(#cp4)" - stroke="#000000" stroke-width="30px" stroke-dasharray="20 20"/> -<!-- Forward arrow to point 3225,8325 --> -<polygon points=" 3165,8053 3225,8293 3285,8053 3165,8053" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp5"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 6285,7978 6165,7978 6207,8268 6243,8268z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 6225,6900 6225,8250" clip-path="url(#cp5)" - stroke="#000000" stroke-width="30px" stroke-dasharray="20 20"/> -<!-- Forward arrow to point 6225,8250 --> -<polygon points=" 6165,7978 6225,8218 6285,7978 6165,7978" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp6"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 8985,7978 8865,7978 8907,8268 8943,8268z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 8925,6900 8925,8250" clip-path="url(#cp6)" - stroke="#000000" stroke-width="30px" stroke-dasharray="20 20"/> -<!-- Forward arrow to point 8925,8250 --> -<polygon points=" 8865,7978 8925,8218 8985,7978 8865,7978" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp7"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 1785,8053 1665,8053 1707,8343 1743,8343z - M 2147,7785 2147,7665 1850,7700 1850,7751z"/> -</clipPath> -</defs> -<polyline points=" 1725,7125 1725,8325" clip-path="url(#cp7)" - stroke="#000000" stroke-width="30px" stroke-dasharray="20 20"/> -<!-- Forward arrow to point 1725,8325 --> -<polygon points=" 1665,8053 1725,8293 1785,8053 1665,8053" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp8"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 2790,5297 2910,5297 2876,5000 2825,5000z - M 2910,5578 2790,5578 2825,5876 2876,5876z"/> -</clipPath> -</defs> -<polyline points=" 2850,5850 2850,5025" clip-path="url(#cp8)" - stroke="#000000" stroke-width="45px"/> -<!-- Forward arrow to point 2850,5025 --> -<polygon points=" 2910,5297 2850,5057 2790,5297 2910,5297" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Backward arrow to point 2850,5850 --> -<polygon points=" 2790,5578 2850,5818 2910,5578 2790,5578" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp9"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 5235,9103 5115,9103 5157,9393 5193,9393z - M 2910,5578 2790,5578 2825,5876 2876,5876z"/> -</clipPath> -</defs> -<polyline points=" 5175,8475 5175,9375" clip-path="url(#cp9)" - stroke="#000000" stroke-width="30px" stroke-dasharray="20 20"/> -<!-- Forward arrow to point 5175,9375 --> -<polygon points=" 5115,9103 5175,9343 5235,9103 5115,9103" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp10"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 1410,9178 1290,9178 1332,9468 1368,9468z - M 2910,5578 2790,5578 2825,5876 2876,5876z"/> -</clipPath> -</defs> -<polyline points=" 1350,7125 1350,9450" clip-path="url(#cp10)" - stroke="#000000" stroke-width="30px" stroke-dasharray="20 20"/> -<!-- Forward arrow to point 1350,9450 --> -<polygon points=" 1290,9178 1350,9418 1410,9178 1290,9178" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<defs> -<clipPath id="cp11"> - <path clip-rule="evenodd" d="M 888,3963 H 9537 V 9987 H 888 z - M 2265,7472 2385,7472 2351,7175 2300,7175z - M 2910,5578 2790,5578 2825,5876 2876,5876z"/> -</clipPath> -</defs> -<polyline points=" 2325,7725 2325,7200" clip-path="url(#cp11)" - stroke="#000000" stroke-width="45px"/> -<!-- Forward arrow to point 2325,7200 --> -<polygon points=" 2385,7472 2325,7232 2265,7472 2385,7472" - stroke="#000000" stroke-width="15px" stroke-miterlimit="8" fill="#000000"/> -<!-- Line --> -<polyline points=" 900,3975" - stroke="#000000" stroke-width="8px" stroke-dasharray="40 40"/> -<!-- Line --> -<polyline points=" 9525,9975" - stroke="#000000" stroke-width="8px" stroke-dasharray="40 40"/> -<!-- Text --> -<text xml:space="preserve" x="4350" y="7980" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">XenBus</text> -<!-- Text --> -<text xml:space="preserve" x="1680" y="6870" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">drivers</text> -<!-- Text --> -<text xml:space="preserve" x="1800" y="6075" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">XenStore</text> -<!-- Text --> -<text xml:space="preserve" x="1875" y="7125" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">Kernel0</text> -<!-- Text --> -<text xml:space="preserve" x="4875" y="6975" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">KernelU</text> -<!-- Text --> -<text xml:space="preserve" x="7650" y="6975" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">KernelU</text> -<!-- Text --> -<text xml:space="preserve" x="4050" y="8400" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">Xen Hypervisor</text> -<!-- Text --> -<text xml:space="preserve" x="2325" y="4950" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">Xend</text> -<!-- Text --> -<text xml:space="preserve" x="1200" y="4725" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">Dom0</text> -<!-- Text --> -<text xml:space="preserve" x="4875" y="5325" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">DomU</text> -<!-- Text --> -<text xml:space="preserve" x="7650" y="5325" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">DomU</text> -<!-- Text --> -<text xml:space="preserve" x="3750" y="9450" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="216" text-anchor="start">Hardware</text> -</g> -</svg> 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 = [ '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 = [ docs_html_in_files = [ '404', - 'architecture', 'auth', 'bugs', 'cgroups', -- 2.29.2
There was one external reference to this page's section which was fixed manually. Signed-off-by: Erik Skultety <eskultet@redhat.com> --- 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 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Connection authentication</h1> - <p> - 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 <a href="acl.html">access control</a> to the operations - performed by a client. - </p> - - <ul id="toc"></ul> - - <h2><a id="Auth_client_config">Client configuration</a></h2> - - <p> - 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: - </p> - <ol> - <li>The file path specified by the $LIBVIRT_AUTH_FILE environment - variable.</li> - <li>The file path specified by the "authfile=/some/file" URI - query parameter</li> - <li>The file $XDG_CONFIG_HOME/libvirt/auth.conf</li> - <li>The file /etc/libvirt/auth.conf</li> - </ol> - - <p> - The auth configuration file uses the traditional <code>".ini"</code> - style syntax. There are two types of groups that can be present in - the config. First there are one or more <strong>credential</strong> - sets, which provide the actual authentication credentials. The keys - within the group may be: - </p> - - <ul> - <li><code>username</code>: 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.</li> - <li><code>authname</code>: the name to authorize as. This is - what is commonly required for libvirtd with SASL.</li> - <li><code>password</code>: the secret password</li> - <li><code>realm</code>: the domain realm for SASL, mostly - unused</li> - </ul> - - <p> - Each set of credentials has a name, which is part of the group - entry name. Overall the syntax is - </p> - - <pre> -[credentials-$NAME] -credname1=value1 -credname2=value2</pre> - - <p> - For example, to define two sets of credentials used for production - and test machines, using libvirtd, and a further ESX server for dev: - </p> -<pre> -[credentials-test] -authname=fred -password=123456 - -[credentials-prod] -authname=bar -password=letmein - -[credentials-dev] -username=joe -password=hello - -[credentials-defgrp] -username=defuser -password=defpw</pre> - - <p> - The second set of groups provide mappings of credentials to - specific machine services. The config file group names compromise - the service type and host: - </p> - - <pre> -[auth-$SERVICE-$HOSTNAME] -credentials=$CREDENTIALS</pre> - - <p> - For example, following the previous example, here is how to - map some machines. For convenience libvirt supports a default - mapping of credentials to machines: - </p> - - <pre> -[auth-libvirt-test1.example.com] -credentials=test - -[auth-libvirt-test2.example.com] -credentials=test - -[auth-libvirt-demo3.example.com] -credentials=test - -[auth-libvirt-prod1.example.com] -credentials=prod - -[auth-libvirt-default] -credentials=defgrp - -[auth-esx-dev1.example.com] -credentials=dev - -[auth-esx-default] -credentials=defgrp</pre> - - - <p> - The following service types are known to libvirt: - </p> - - <ul> - <li><code>esx</code> - used for connections to an ESX or - VirtualCenter server</li> - <li><code>hyperv</code> - used for connections to an HyperV - server</li> - <li><code>libvirt</code> - used for connections to a libvirtd - server, which is configured with SASL auth</li> - <li><code>ssh</code> - used for connections to a remote QEMU driver - over SSH</li> - </ul> - - <p> - 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 - </p> - - <h2><a id="ACL_server_config">Server configuration</a></h2> - <p> -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 -<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can -have its authentication mechanism configured independently. There is -currently a choice of <code>none</code>, <code>polkit</code>, and <code>sasl</code>. -The SASL scheme can be further configured to choose between a large -number of different mechanisms. -</p> - <h2><a id="ACL_server_unix_perms">UNIX socket permissions/group</a></h2> - <p> -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 <code>root</code> user to connect. The read-only socket will -be open access (mode 0777) to allow any user to connect. -</p> - <p> -To allow non-root users greater access, the <code>libvirtd.conf</code> file -can be edited to change the permissions via the <code>unix_sock_rw_perms</code>, -config parameter and to set a user group via the <code>unix_sock_group</code> -parameter. For example, setting the former to mode <code>0770</code> and the -latter <code>wheel</code> would let any user in the wheel group connect to -the libvirt daemon. -</p> - <h2><a id="ACL_server_polkit">UNIX socket PolicyKit auth</a></h2> - <p> -If libvirt contains support for PolicyKit, then access control options are -more advanced. The <code>auth_unix_rw</code> parameter will default to -<code>polkit</code>, and the file permissions will default to <code>0777</code> -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 <code>sudo</code> -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. -</p> - <p> -The default policy can be overridden by creating a new policy file in the -<code>/etc/polkit-1/rules.d</code> directory. Information on the options -available can be found by reading the <code>polkit(8)</code> man page. The -two libvirt actions are named <code>org.libvirt.unix.manage</code> for full -management access, and <code>org.libvirt.unix.monitor</code> for read-only -access. -</p> - <p> -As an example, creating <code>/etc/polkit-1/rules.d/80-libvirt-manage.rules</code> -with the following gives the user <code>fred</code> full management access -when accessing from an active local session: - </p> -<pre>polkit.addRule(function(action, subject) { - if (action.id == "org.libvirt.unix.manage" && - subject.local && subject.active && subject.user == "fred") { - return polkit.Result.YES; - } -});</pre> - <p> -Older versions of PolicyKit used policy files ending with .pkla in the -local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>. -Compatibility with this older format is provided by <a -href="https://pagure.io/polkit-pkla-compat">polkit-pkla-compat</a>. As an -example, this gives the user <code>fred</code> full management access: - </p> -<pre>[Allow fred libvirt management permissions] -Identity=unix-user:fred -Action=org.libvirt.unix.manage -ResultAny=yes -ResultInactive=yes -ResultActive=yes</pre> - <h2><a id="ACL_server_sasl">SASL pluggable authentication</a></h2> - - <p> -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: - </p> - - <dl> - <dt>GSSAPI</dt> - <dd><strong>This is the current default mechanism to use with libvirtd</strong>. - 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.</dd> - - <dt>DIGEST-MD5</dt> - <dd>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. - <a href="https://tools.ietf.org/html/rfc6331">RFC 6331</a>, however, - documents a number of serious security flaws with DIGEST-MD5 and as a - result marks it as <code>OBSOLETE</code>. 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. - </dd> - - <dt>PASSDSS-3DES-1</dt> - <dd>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.</dd> - - <dt>KERBEROS_V4</dt> - <dd>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.</dd> - </dl> - - <p> - Other SASL mechanisms, not listed above, can only be used when the libvirtd - TLS or UNIX socket listeners. - </p> - - <h3><a id="ACL_server_username">Username/password auth</a></h3> - <p> -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 <code>auth_unix_ro</code>, <code>auth_unix_rw</code>, -<code>auth_tls</code> config params in <code>libvirt.conf</code> can be used -to turn on SASL auth in these listeners. - </p> - <p> -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 <code>/etc/sasl2/libvirt.conf</code> to set the <code>mech_list</code> -parameter to <code>scram-sha-1</code>. - </p> - <p> -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 <code>saslpasswd2</code> -command. When running this command it is important to tell it that the appname is <code>libvirt</code>. -As an example, to add a user <code>fred</code>, run -</p> - <pre> -# saslpasswd2 -a libvirt fred -Password: xxxxxx -Again (for verification): xxxxxx -</pre> - <p> -To see a list of all accounts the <code>sasldblistusers2</code> command can be used. -This command expects to be given the path to the libvirt user database, which is kept -in <code>/etc/libvirt/passwd.db</code> -</p> - <pre> -# sasldblistusers2 -f /etc/libvirt/passwd.db -fred@t60wlan.home.berrange.com: userPassword -</pre> - <p> -Finally, to disable a user's access, the <code>saslpasswd2</code> command can be used -again: -</p> - <pre> -# saslpasswd2 -a libvirt -d fred -</pre> - <h3><a id="ACL_server_kerberos">GSSAPI/Kerberos auth</a></h3> - <p> -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 -</p> - <p> -Some operating systems do not install the SASL kerberos plugin by default. It -may be necessary to install a sub-package such as <code>cyrus-sasl-gssapi</code>. -To check whether the Kerberos plugin is installed run the <code>pluginviewer</code> -program and verify that <code>gssapi</code> is listed, e.g.: -</p> - <pre> -# pluginviewer -...snip... -Plugin "gssapiv2" [loaded], API version: 4 - SASL mechanism: GSSAPI, best SSF: 56 - security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH - features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN -</pre> - <p> -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 <code>libvirt/full.hostname@KERBEROS.REALM</code>. This is -typically done by running the <code>kadmin.local</code> 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 <code>/etc/libvirt/krb5.tab</code> -</p> - <pre> -# 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, encryption 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, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab. -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab. -Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-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 -</pre> - <p> -Any client application wishing to connect to a Kerberos enabled libvirt server -merely needs to run <code>kinit</code> 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. -</p> - </body> -</html> 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 @@ +========================= +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 <acl.html>`__ 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=/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=value1 + credname2=value2 + +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=fred + password=123456 + + [credentials-prod] + authname=bar + password=letmein + + [credentials-dev] + username=joe + password=hello + + [credentials-defgrp] + username=defuser + password=defpw + +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=$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=test + + [auth-libvirt-test2.example.com] + credentials=test + + [auth-libvirt-demo3.example.com] + credentials=test + + [auth-libvirt-prod1.example.com] + credentials=prod + + [auth-libvirt-default] + credentials=defgrp + + [auth-esx-dev1.example.com] + credentials=dev + + [auth-esx-default] + credentials=defgrp + +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 == "org.libvirt.unix.manage" && + subject.local && subject.active && subject.user == "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 <https://pagure.io/polkit-pkla-compat>`__. As an +example, this gives the user ``fred`` full management access: + +:: + + [Allow fred libvirt management permissions] + Identity=unix-user:fred + Action=org.libvirt.unix.manage + ResultAny=yes + ResultInactive=yes + ResultActive=yes + +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 <https://tools.ietf.org/html/rfc6331>`__, 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_CREDENTIALS|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, encryption 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, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-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 +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 <auth.html#Auth_client_config>`__ needs to contain something like +file <../auth.html#client-configuration>`__ needs to contain something like the following: :: 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 = [ docs_html_in_files = [ '404', - 'auth', 'bugs', 'cgroups', 'contact', @@ -103,6 +102,7 @@ docs_rst_files = [ 'api', 'apps', 'auditlog', + 'auth', 'bindings', 'best-practices', 'ci', -- 2.29.2
On Mon, Mar 15, 2021 at 06:39:45PM +0100, Erik Skultety wrote:
There was one external reference to this page's section which was fixed manually.
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- ...
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 <auth.html#Auth_client_config>`__ needs to contain something like +file <../auth.html#client-configuration>`__ needs to contain something like
Since the conversion of auth.html.in to RST has already been pushed in an unrelated patch series, this patch is redundant, except for ^this single hunk which I'll squash to patch 3. Erik
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- 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 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 <formatdomain.html#elementsEvents>`__ 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 -- 2.29.2
On Mon, Mar 15, 2021 at 06:39:43PM +0100, Erik Skultety wrote:
since v1: - fixed a broken heading reference from a kbase article caused by RST convers= ion - dropped architecture.html.in along with images
v1: https://listman.redhat.com/archives/libvir-list/2021-March/msg00584.html
Erik Skultety (3): docs: html.in: Drop the architecture page docs: html.in: Convert auth to rst docs: kbase: Fix a broken formatdomain reference in locking-sanlock
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
participants (2)
-
Erik Skultety -
Pavel Hrdina