docs/cgroups.html.in | 424 -------------- docs/cgroups.rst | 364 ++++++++++++ docs/drvbhyve.html.in | 583 ------------------- docs/drvbhyve.rst | 582 +++++++++++++++++++ docs/drvesx.html.in | 838 --------------------------- docs/drvesx.rst | 681 ++++++++++++++++++++++ docs/drvhyperv.html.in | 150 ----- docs/drvhyperv.rst | 121 ++++ docs/drvlxc.html.in | 822 -------------------------- docs/drvlxc.rst | 670 +++++++++++++++++++++ docs/drvnodedev.html.in | 383 ------------ docs/drvnodedev.rst | 348 +++++++++++ docs/drvopenvz.html.in | 123 ---- docs/drvopenvz.rst | 97 ++++ docs/drvremote.html.in | 7 - docs/drvsecret.html.in | 82 --- docs/drvsecret.rst | 65 +++ docs/drvtest.html.in | 27 - docs/drvtest.rst | 21 + docs/drvvbox.html.in | 172 ------ docs/drvvbox.rst | 161 +++++ docs/drvvirtuozzo.html.in | 70 --- docs/drvvirtuozzo.rst | 60 ++ docs/drvvmware.html.in | 89 --- docs/drvvmware.rst | 72 +++ docs/drvxen.html.in | 358 ------------ docs/drvxen.rst | 338 +++++++++++ docs/firewall.html.in | 523 ----------------- docs/firewall.rst | 506 ++++++++++++++++ docs/format.html.in | 48 -- docs/format.rst | 35 ++ docs/formatcaps.html.in | 219 ------- docs/formatcaps.rst | 196 +++++++ docs/formatdomain.rst | 25 +- docs/formatdomaincaps.html.in | 693 ---------------------- docs/formatdomaincaps.rst | 602 +++++++++++++++++++ docs/formatnetworkport.html.in | 223 ------- docs/formatnetworkport.rst | 175 ++++++ docs/formatstoragecaps.html.in | 95 --- docs/formatstoragecaps.rst | 81 +++ docs/formatstorageencryption.html.in | 181 ------ docs/formatstorageencryption.rst | 139 +++++ docs/hooks.html.in | 406 ------------- docs/hooks.rst | 518 +++++++++++++++++ docs/java.html.in | 121 ---- docs/java.rst | 128 ++++ docs/kbase/backing_chains.rst | 2 +- docs/logging.html.in | 243 -------- docs/logging.rst | 215 +++++++ docs/meson.build | 49 +- docs/php.html.in | 28 - docs/php.rst | 23 + 52 files changed, 6236 insertions(+), 6946 deletions(-) delete mode 100644 docs/cgroups.html.in create mode 100644 docs/cgroups.rst delete mode 100644 docs/drvbhyve.html.in create mode 100644 docs/drvbhyve.rst delete mode 100644 docs/drvesx.html.in create mode 100644 docs/drvesx.rst delete mode 100644 docs/drvhyperv.html.in create mode 100644 docs/drvhyperv.rst delete mode 100644 docs/drvlxc.html.in create mode 100644 docs/drvlxc.rst delete mode 100644 docs/drvnodedev.html.in create mode 100644 docs/drvnodedev.rst delete mode 100644 docs/drvopenvz.html.in create mode 100644 docs/drvopenvz.rst delete mode 100644 docs/drvremote.html.in delete mode 100644 docs/drvsecret.html.in create mode 100644 docs/drvsecret.rst delete mode 100644 docs/drvtest.html.in create mode 100644 docs/drvtest.rst delete mode 100644 docs/drvvbox.html.in create mode 100644 docs/drvvbox.rst delete mode 100644 docs/drvvirtuozzo.html.in create mode 100644 docs/drvvirtuozzo.rst delete mode 100644 docs/drvvmware.html.in create mode 100644 docs/drvvmware.rst delete mode 100644 docs/drvxen.html.in create mode 100644 docs/drvxen.rst delete mode 100644 docs/firewall.html.in create mode 100644 docs/firewall.rst delete mode 100644 docs/format.html.in create mode 100644 docs/format.rst delete mode 100644 docs/formatcaps.html.in create mode 100644 docs/formatcaps.rst delete mode 100644 docs/formatdomaincaps.html.in create mode 100644 docs/formatdomaincaps.rst delete mode 100644 docs/formatnetworkport.html.in create mode 100644 docs/formatnetworkport.rst delete mode 100644 docs/formatstoragecaps.html.in create mode 100644 docs/formatstoragecaps.rst delete mode 100644 docs/formatstorageencryption.html.in create mode 100644 docs/formatstorageencryption.rst delete mode 100644 docs/hooks.html.in create mode 100644 docs/hooks.rst delete mode 100644 docs/java.html.in create mode 100644 docs/java.rst delete mode 100644 docs/logging.html.in create mode 100644 docs/logging.rst delete mode 100644 docs/php.html.in create mode 100644 docs/php.rst
Peter Krempa (29): docs: Remove empty unreferenced 'drvremote' page docs: Convert 'cgroups' page to rST docs: Convert 'drvbhyve' page to rST docs: Convert 'drvesx' page to rST docs: Convert 'drvhyperv' page to rST docs: Convert 'drvlxc' page to rST docs: Convert 'drvnodedev' page to rST docs: Convert 'drvopenvz' page to rST docs: Convert 'drvsecret' page to rST docs: Convert 'drvtest' page to rST docs: Convert 'drvvbox' page to rST docs: Convert 'drvvirtuozzo' page to rST docs: Convert 'drvvmware' page to rST docs: Convert 'drvxen' page to rST docs: Convert 'firewall' page to rST docs: Convert 'format' page to rST docs: Convert 'formatcaps' page to rST docs: Convert 'formatdomaincaps' to rST docs: Convert 'formatnetworkport' to rST docs: Fix heading of 'formatnetworkport' page docs: Convert 'formatstoragecaps' page to rST docs: Convert 'formatstorageencryption' page to rST docs: formatstorageencryption: Drop empty 'default' paragraph docs: formatstorageencryption: Re-style encryption type headers docs: Convert 'hooks' page to rST docs: Convert 'java' page to rST docs: Convert 'logging' page to rST docs: logging: Replace example by link to kbase/debuglogs.html docs: Convert 'php' page to rST docs/cgroups.html.in | 424 -------------- docs/cgroups.rst | 364 ++++++++++++ docs/drvbhyve.html.in | 583 ------------------- docs/drvbhyve.rst | 582 +++++++++++++++++++ docs/drvesx.html.in | 838 --------------------------- docs/drvesx.rst | 681 ++++++++++++++++++++++ docs/drvhyperv.html.in | 150 ----- docs/drvhyperv.rst | 121 ++++ docs/drvlxc.html.in | 822 -------------------------- docs/drvlxc.rst | 670 +++++++++++++++++++++ docs/drvnodedev.html.in | 383 ------------ docs/drvnodedev.rst | 348 +++++++++++ docs/drvopenvz.html.in | 123 ---- docs/drvopenvz.rst | 97 ++++ docs/drvremote.html.in | 7 - docs/drvsecret.html.in | 82 --- docs/drvsecret.rst | 65 +++ docs/drvtest.html.in | 27 - docs/drvtest.rst | 21 + docs/drvvbox.html.in | 172 ------ docs/drvvbox.rst | 161 +++++ docs/drvvirtuozzo.html.in | 70 --- docs/drvvirtuozzo.rst | 60 ++ docs/drvvmware.html.in | 89 --- docs/drvvmware.rst | 72 +++ docs/drvxen.html.in | 358 ------------ docs/drvxen.rst | 338 +++++++++++ docs/firewall.html.in | 523 ----------------- docs/firewall.rst | 506 ++++++++++++++++ docs/format.html.in | 48 -- docs/format.rst | 35 ++ docs/formatcaps.html.in | 219 ------- docs/formatcaps.rst | 196 +++++++ docs/formatdomain.rst | 25 +- docs/formatdomaincaps.html.in | 693 ---------------------- docs/formatdomaincaps.rst | 602 +++++++++++++++++++ docs/formatnetworkport.html.in | 223 ------- docs/formatnetworkport.rst | 175 ++++++ docs/formatstoragecaps.html.in | 95 --- docs/formatstoragecaps.rst | 81 +++ docs/formatstorageencryption.html.in | 181 ------ docs/formatstorageencryption.rst | 139 +++++ docs/hooks.html.in | 406 ------------- docs/hooks.rst | 518 +++++++++++++++++ docs/java.html.in | 121 ---- docs/java.rst | 128 ++++ docs/kbase/backing_chains.rst | 2 +- docs/logging.html.in | 243 -------- docs/logging.rst | 215 +++++++ docs/meson.build | 49 +- docs/php.html.in | 28 - docs/php.rst | 23 + 52 files changed, 6236 insertions(+), 6946 deletions(-) delete mode 100644 docs/cgroups.html.in create mode 100644 docs/cgroups.rst delete mode 100644 docs/drvbhyve.html.in create mode 100644 docs/drvbhyve.rst delete mode 100644 docs/drvesx.html.in create mode 100644 docs/drvesx.rst delete mode 100644 docs/drvhyperv.html.in create mode 100644 docs/drvhyperv.rst delete mode 100644 docs/drvlxc.html.in create mode 100644 docs/drvlxc.rst delete mode 100644 docs/drvnodedev.html.in create mode 100644 docs/drvnodedev.rst delete mode 100644 docs/drvopenvz.html.in create mode 100644 docs/drvopenvz.rst delete mode 100644 docs/drvremote.html.in delete mode 100644 docs/drvsecret.html.in create mode 100644 docs/drvsecret.rst delete mode 100644 docs/drvtest.html.in create mode 100644 docs/drvtest.rst delete mode 100644 docs/drvvbox.html.in create mode 100644 docs/drvvbox.rst delete mode 100644 docs/drvvirtuozzo.html.in create mode 100644 docs/drvvirtuozzo.rst delete mode 100644 docs/drvvmware.html.in create mode 100644 docs/drvvmware.rst delete mode 100644 docs/drvxen.html.in create mode 100644 docs/drvxen.rst delete mode 100644 docs/firewall.html.in create mode 100644 docs/firewall.rst delete mode 100644 docs/format.html.in create mode 100644 docs/format.rst delete mode 100644 docs/formatcaps.html.in create mode 100644 docs/formatcaps.rst delete mode 100644 docs/formatdomaincaps.html.in create mode 100644 docs/formatdomaincaps.rst delete mode 100644 docs/formatnetworkport.html.in create mode 100644 docs/formatnetworkport.rst delete mode 100644 docs/formatstoragecaps.html.in create mode 100644 docs/formatstoragecaps.rst delete mode 100644 docs/formatstorageencryption.html.in create mode 100644 docs/formatstorageencryption.rst delete mode 100644 docs/hooks.html.in create mode 100644 docs/hooks.rst delete mode 100644 docs/java.html.in create mode 100644 docs/java.rst delete mode 100644 docs/logging.html.in create mode 100644 docs/logging.rst delete mode 100644 docs/php.html.in create mode 100644 docs/php.rst -- 2.35.1
Can you please rebase? The series doesn't apply cleanly anymore. Isn't this a part 3 actually? Based on [1]... :P [1] https://listman.redhat.com/archives/libvir-list/2022-March/229208.html Erik
On Fri, Apr 01, 2022 at 09:23:54 +0200, Erik Skultety wrote: > Can you please rebase? The series doesn't apply cleanly anymore. I've noted that patch 17 doesn't apply cleanly. I planned to drop it (and solve the trivial conflict in docs/meson.build in patch 18). Then I'll re-convert it in the next pass. It doesn't make too much sense for me to try to chase and re-apply what has changed to the converted docs. > > Isn't this a part 3 actually? Based on [1]... :P > > [1] https://listman.redhat.com/archives/libvir-list/2022-March/229208.html It is, but that series is pushed for some time now. The problem was that there was a docs change in one of the files converted in this series. I can re-send with the conflict solved if you'd like me to.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvremote.html.in | 7 ------- docs/meson.build | 1 - 2 files changed, 8 deletions(-) delete mode 100644 docs/drvremote.html.in diff --git a/docs/drvremote.html.in b/docs/drvremote.html.in deleted file mode 100644 index 224f1bfb17..0000000000 --- a/docs/drvremote.html.in +++ /dev/null @@ -1,7 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Remote management driver</h1> - </body> -</html> diff --git a/docs/meson.build b/docs/meson.build index b097866208..5f26d40082 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -29,7 +29,6 @@ docs_html_in_files = [ 'drvlxc', 'drvnodedev', 'drvopenvz', - 'drvremote', 'drvsecret', 'drvtest', 'drvvbox', -- 2.35.1
On Mon, Mar 28, 2022 at 02:10:16PM +0200, Peter Krempa wrote: > Signed-off-by: Peter Krempa <pkrempa@redhat.com> > --- Reviewed-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
docs/cgroups.html.in | 424 -------------------------------------------
docs/cgroups.rst | 364 +++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 365 insertions(+), 425 deletions(-)
delete mode 100644 docs/cgroups.html.in
create mode 100644 docs/cgroups.rst
diff --git a/docs/cgroups.html.in b/docs/cgroups.html.in
deleted file mode 100644
index 412a9360ff..0000000000
--- a/docs/cgroups.html.in
+++ /dev/null
@@ -1,424 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Control Groups Resource Management</h1>
-
- <ul id="toc"></ul>
-
- <p>
- The QEMU and LXC drivers make use of the Linux "Control Groups" facility
- for applying resource management to their virtual machines and containers.
- </p>
-
- <h2><a id="requiredControllers">Required controllers</a></h2>
-
- <p>
- The control groups filesystem supports multiple "controllers". By default
- the init system (such as systemd) should mount all controllers compiled
- into the kernel at <code>/sys/fs/cgroup/$CONTROLLER-NAME</code>. Libvirt
- will never attempt to mount any controllers itself, merely detect where
- they are mounted.
- </p>
-
- <p>
- The QEMU driver is capable of using the <code>cpuset</code>,
- <code>cpu</code>, <code>cpuacct</code>, <code>memory</code>,
- <code>blkio</code> and <code>devices</code> controllers.
- None of them are compulsory. If any controller is not mounted,
- the resource management APIs which use it will cease to operate.
- It is possible to explicitly turn off use of a controller,
- even when mounted, via the <code>/etc/libvirt/qemu.conf</code>
- configuration file.
- </p>
-
- <p>
- The LXC driver is capable of using the <code>cpuset</code>,
- <code>cpu</code>, <code>cpuacct</code>, <code>freezer</code>,
- <code>memory</code>, <code>blkio</code> and <code>devices</code>
- controllers. The <code>cpuacct</code>, <code>devices</code>
- and <code>memory</code> controllers are compulsory. Without
- them mounted, no containers can be started. If any of the
- other controllers are not mounted, the resource management APIs
- which use them will cease to operate.
- </p>
-
- <h2><a id="currentLayout">Current cgroups layout</a></h2>
-
- <p>
- As of libvirt 1.0.5 or later, the cgroups layout created by libvirt has been
- simplified, in order to facilitate the setup of resource control policies by
- administrators / management applications. The new layout is based on the concepts
- of "partitions" and "consumers". A "consumer" is a cgroup which holds the
- processes for a single virtual machine or container. A "partition" is a cgroup
- which does not contain any processes, but can have resource controls applied.
- A "partition" will have zero or more child directories which may be either
- "consumer" or "partition".
- </p>
-
- <p>
- As of libvirt 1.1.1 or later, the cgroups layout will have some slight
- differences when running on a host with systemd 205 or later. The overall
- tree structure is the same, but there are some differences in the naming
- conventions for the cgroup directories. Thus the following docs split
- in two, one describing systemd hosts and the other non-systemd hosts.
- </p>
-
- <h3><a id="currentLayoutSystemd">Systemd cgroups integration</a></h3>
-
- <p>
- On hosts which use systemd, each consumer maps to a systemd scope unit,
- while partitions map to a system slice unit.
- </p>
-
- <h4><a id="systemdScope">Systemd scope naming</a></h4>
-
- <p>
- The systemd convention is for the scope name of virtual machines / containers
- to be of the general format <code>machine-$NAME.scope</code>. Libvirt forms the
- <code>$NAME</code> part of this by concatenating the driver type with the id
- and truncated name of the guest, and then escaping any systemd reserved
- characters.
- So for a guest <code>demo</code> running under the <code>lxc</code> driver,
- we get a <code>$NAME</code> of <code>lxc-12345-demo</code> which when escaped
- is <code>lxc\x2d12345\x2ddemo</code>. So the complete scope name is
- <code>machine-lxc\x2d12345\x2ddemo.scope</code>.
- The scope names map directly to the cgroup directory names.
- </p>
-
- <h4><a id="systemdSlice">Systemd slice naming</a></h4>
-
- <p>
- The systemd convention for slice naming is that a slice should include the
- name of all of its parents prepended on its own name. So for a libvirt
- partition <code>/machine/engineering/testing</code>, the slice name will
- be <code>machine-engineering-testing.slice</code>. Again the slice names
- map directly to the cgroup directory names. Systemd creates three top level
- slices by default, <code>system.slice</code> <code>user.slice</code> and
- <code>machine.slice</code>. All virtual machines or containers created
- by libvirt will be associated with <code>machine.slice</code> by default.
- </p>
-
- <h4><a id="systemdLayout">Systemd cgroup layout</a></h4>
-
- <p>
- Given this, a possible systemd cgroups layout involving 3 qemu guests,
- 3 lxc containers and 3 custom child slices, would be:
- </p>
-
- <pre>
-$ROOT
- |
- +- system.slice
- | |
- | +- libvirtd.service
- |
- +- machine.slice
- |
- +- machine-qemu\x2d1\x2dvm1.scope
- | |
- | +- libvirt
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- machine-qemu\x2d2\x2dvm2.scope
- | |
- | +- libvirt
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- machine-qemu\x2d3\x2dvm3.scope
- | |
- | +- libvirt
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- machine-engineering.slice
- | |
- | +- machine-engineering-testing.slice
- | | |
- | | +- machine-lxc\x2d11111\x2dcontainer1.scope
- | |
- | +- machine-engineering-production.slice
- | |
- | +- machine-lxc\x2d22222\x2dcontainer2.scope
- |
- +- machine-marketing.slice
- |
- +- machine-lxc\x2d33333\x2dcontainer3.scope
- </pre>
-
- <p>
- Prior libvirt 7.1.0 the topology doesn't have extra
- <code>libvirt</code> directory.
- </p>
-
- <h3><a id="currentLayoutGeneric">Non-systemd cgroups layout</a></h3>
-
- <p>
- On hosts which do not use systemd, each consumer has a corresponding cgroup
- named <code>$VMNAME.libvirt-{qemu,lxc}</code>. Each consumer is associated
- with exactly one partition, which also have a corresponding cgroup usually
- named <code>$PARTNAME.partition</code>. The exceptions to this naming rule
- is the top level default partition for virtual machines and containers
- <code>/machine</code>.
- </p>
-
- <p>
- Given this, a possible non-systemd cgroups layout involving 3 qemu guests,
- 3 lxc containers and 2 custom child slices, would be:
- </p>
-
- <pre>
-$ROOT
- |
- +- machine
- |
- +- qemu-1-vm1.libvirt-qemu
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- qeme-2-vm2.libvirt-qemu
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- qemu-3-vm3.libvirt-qemu
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- engineering.partition
- | |
- | +- testing.partition
- | | |
- | | +- lxc-11111-container1.libvirt-lxc
- | |
- | +- production.partition
- | |
- | +- lxc-22222-container2.libvirt-lxc
- |
- +- marketing.partition
- |
- +- lxc-33333-container3.libvirt-lxc
- </pre>
-
- <h2><a id="customPartiton">Using custom partitions</a></h2>
-
- <p>
- If there is a need to apply resource constraints to groups of
- virtual machines or containers, then the single default
- partition <code>/machine</code> may not be sufficiently
- flexible. The administrator may wish to sub-divide the
- default partition, for example into "testing" and "production"
- partitions, and then assign each guest to a specific
- sub-partition. This is achieved via a small element addition
- to the guest domain XML config, just below the main <code>domain</code>
- element
- </p>
-
- <pre>
-...
-<resource>
- <partition>/machine/production</partition>
-</resource>
-...
- </pre>
-
- <p>
- Note that the partition names in the guest XML are using a
- generic naming format, not the low level naming convention
- required by the underlying host OS. That is, you should not include
- any of the <code>.partition</code> or <code>.slice</code>
- suffixes in the XML config. Given a partition name
- <code>/machine/production</code>, libvirt will automatically
- apply the platform specific translation required to get
- <code>/machine/production.partition</code> (non-systemd)
- or <code>/machine.slice/machine-production.slice</code>
- (systemd) as the underlying cgroup name
- </p>
-
- <p>
- Libvirt will not auto-create the cgroups directory to back
- this partition. In the future, libvirt / virsh will provide
- APIs / commands to create custom partitions, but currently
- this is left as an exercise for the administrator.
- </p>
-
- <p>
- <strong>Note:</strong> the ability to place guests in custom
- partitions is only available with libvirt >= 1.0.5, using
- the new cgroup layout. The legacy cgroups layout described
- later in this document did not support customization per guest.
- </p>
-
- <h3><a id="createSystemd">Creating custom partitions (systemd)</a></h3>
-
- <p>
- Given the XML config above, the admin on a systemd based host would
- need to create a unit file <code>/etc/systemd/system/machine-production.slice</code>
- </p>
-
- <pre>
-# cat > /etc/systemd/system/machine-testing.slice <<EOF
-[Unit]
-Description=VM testing slice
-Before=slices.target
-Wants=machine.slice
-EOF
-# systemctl start machine-testing.slice
- </pre>
-
- <h3><a id="createNonSystemd">Creating custom partitions (non-systemd)</a></h3>
-
- <p>
- Given the XML config above, the admin on a non-systemd based host
- would need to create a cgroup named '/machine/production.partition'
- </p>
-
- <pre>
-# cd /sys/fs/cgroup
-# for i in blkio cpu,cpuacct cpuset devices freezer memory net_cls perf_event
- do
- mkdir $i/machine/production.partition
- done
-# for i in cpuset.cpus cpuset.mems
- do
- cat cpuset/machine/$i > cpuset/machine/production.partition/$i
- done
-</pre>
-
- <h2><a id="resourceAPIs">Resource management APIs/commands</a></h2>
-
- <p>
- Since libvirt aims to provide an API which is portable across
- hypervisors, the concept of cgroups is not exposed directly
- in the API or XML configuration. It is considered to be an
- internal implementation detail. Instead libvirt provides a
- set of APIs for applying resource controls, which are then
- mapped to corresponding cgroup tunables
- </p>
-
- <h3>Scheduler tuning</h3>
-
- <p>
- Parameters from the "cpu" controller are exposed via the
- <code>schedinfo</code> command in virsh.
- </p>
-
- <pre>
-# virsh schedinfo demo
-Scheduler : posix
-cpu_shares : 1024
-vcpu_period : 100000
-vcpu_quota : -1
-emulator_period: 100000
-emulator_quota : -1</pre>
-
-
- <h3>Block I/O tuning</h3>
-
- <p>
- Parameters from the "blkio" controller are exposed via the
- <code>bkliotune</code> command in virsh.
- </p>
-
-
- <pre>
-# virsh blkiotune demo
-weight : 500
-device_weight : </pre>
-
- <h3>Memory tuning</h3>
-
- <p>
- Parameters from the "memory" controller are exposed via the
- <code>memtune</code> command in virsh.
- </p>
-
- <pre>
-# virsh memtune demo
-hard_limit : 580192
-soft_limit : unlimited
-swap_hard_limit: unlimited
- </pre>
-
- <h3>Network tuning</h3>
-
- <p>
- The <code>net_cls</code> is not currently used. Instead traffic
- filter policies are set directly against individual virtual
- network interfaces.
- </p>
-
- <h2><a id="legacyLayout">Legacy cgroups layout</a></h2>
-
- <p>
- Prior to libvirt 1.0.5, the cgroups layout created by libvirt was different
- from that described above, and did not allow for administrator customization.
- Libvirt used a fixed, 3-level hierarchy <code>libvirt/{qemu,lxc}/$VMNAME</code>
- which was rooted at the point in the hierarchy where libvirtd itself was
- located. So if libvirtd was placed at <code>/system/libvirtd.service</code>
- by systemd, the groups for each virtual machine / container would be located
- at <code>/system/libvirtd.service/libvirt/{qemu,lxc}/$VMNAME</code>. In addition
- to this, the QEMU drivers further child groups for each vCPU thread and the
- emulator thread(s). This leads to a hierarchy that looked like
- </p>
-
-
- <pre>
-$ROOT
- |
- +- system
- |
- +- libvirtd.service
- |
- +- libvirt
- |
- +- qemu
- | |
- | +- vm1
- | | |
- | | +- emulator
- | | +- vcpu0
- | | +- vcpu1
- | |
- | +- vm2
- | | |
- | | +- emulator
- | | +- vcpu0
- | | +- vcpu1
- | |
- | +- vm3
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- lxc
- |
- +- container1
- |
- +- container2
- |
- +- container3
- </pre>
-
- <p>
- Although current releases are much improved, historically the use of deep
- hierarchies has had a significant negative impact on the kernel scalability.
- The legacy libvirt cgroups layout highlighted these problems, to the detriment
- of the performance of virtual machines and containers.
- </p>
- </body>
-</html>
diff --git a/docs/cgroups.rst b/docs/cgroups.rst
new file mode 100644
index 0000000000..eb66a14f0d
--- /dev/null
+++ b/docs/cgroups.rst
@@ -0,0 +1,364 @@
+==================================
+Control Groups Resource Management
+==================================
+
+.. contents::
+
+The QEMU and LXC drivers make use of the Linux "Control Groups" facility for
+applying resource management to their virtual machines and containers.
+
+Required controllers
+--------------------
+
+The control groups filesystem supports multiple "controllers". By default the
+init system (such as systemd) should mount all controllers compiled into the
+kernel at ``/sys/fs/cgroup/$CONTROLLER-NAME``. Libvirt will never attempt to
+mount any controllers itself, merely detect where they are mounted.
+
+The QEMU driver is capable of using the ``cpuset``, ``cpu``, ``cpuacct``,
+``memory``, ``blkio`` and ``devices`` controllers. None of them are compulsory.
+If any controller is not mounted, the resource management APIs which use it will
+cease to operate. It is possible to explicitly turn off use of a controller,
+even when mounted, via the ``/etc/libvirt/qemu.conf`` configuration file.
+
+The LXC driver is capable of using the ``cpuset``, ``cpu``, ``cpuacct``,
+``freezer``, ``memory``, ``blkio`` and ``devices`` controllers. The ``cpuacct``,
+``devices`` and ``memory`` controllers are compulsory. Without them mounted, no
+containers can be started. If any of the other controllers are not mounted, the
+resource management APIs which use them will cease to operate.
+
+Current cgroups layout
+----------------------
+
+As of libvirt 1.0.5 or later, the cgroups layout created by libvirt has been
+simplified, in order to facilitate the setup of resource control policies by
+administrators / management applications. The new layout is based on the
+concepts of "partitions" and "consumers". A "consumer" is a cgroup which holds
+the processes for a single virtual machine or container. A "partition" is a
+cgroup which does not contain any processes, but can have resource controls
+applied. A "partition" will have zero or more child directories which may be
+either "consumer" or "partition".
+
+As of libvirt 1.1.1 or later, the cgroups layout will have some slight
+differences when running on a host with systemd 205 or later. The overall tree
+structure is the same, but there are some differences in the naming conventions
+for the cgroup directories. Thus the following docs split in two, one describing
+systemd hosts and the other non-systemd hosts.
+
+Systemd cgroups integration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On hosts which use systemd, each consumer maps to a systemd scope unit, while
+partitions map to a system slice unit.
+
+Systemd scope naming
+^^^^^^^^^^^^^^^^^^^^
+
+The systemd convention is for the scope name of virtual machines / containers to
+be of the general format ``machine-$NAME.scope``. Libvirt forms the ``$NAME``
+part of this by concatenating the driver type with the id and truncated name of
+the guest, and then escaping any systemd reserved characters. So for a guest
+``demo`` running under the ``lxc`` driver, we get a ``$NAME`` of
+``lxc-12345-demo`` which when escaped is ``lxc\x2d12345\x2ddemo``. So the
+complete scope name is ``machine-lxc\x2d12345\x2ddemo.scope``. The scope names
+map directly to the cgroup directory names.
+
+Systemd slice naming
+^^^^^^^^^^^^^^^^^^^^
+
+The systemd convention for slice naming is that a slice should include the name
+of all of its parents prepended on its own name. So for a libvirt partition
+``/machine/engineering/testing``, the slice name will be
+``machine-engineering-testing.slice``. Again the slice names map directly to the
+cgroup directory names. Systemd creates three top level slices by default,
+``system.slice`` ``user.slice`` and ``machine.slice``. All virtual machines or
+containers created by libvirt will be associated with ``machine.slice`` by
+default.
+
+Systemd cgroup layout
+^^^^^^^^^^^^^^^^^^^^^
+
+Given this, a possible systemd cgroups layout involving 3 qemu guests, 3 lxc
+containers and 3 custom child slices, would be:
+
+::
+
+ $ROOT
+ |
+ +- system.slice
+ | |
+ | +- libvirtd.service
+ |
+ +- machine.slice
+ |
+ +- machine-qemu\x2d1\x2dvm1.scope
+ | |
+ | +- libvirt
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- machine-qemu\x2d2\x2dvm2.scope
+ | |
+ | +- libvirt
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- machine-qemu\x2d3\x2dvm3.scope
+ | |
+ | +- libvirt
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- machine-engineering.slice
+ | |
+ | +- machine-engineering-testing.slice
+ | | |
+ | | +- machine-lxc\x2d11111\x2dcontainer1.scope
+ | |
+ | +- machine-engineering-production.slice
+ | |
+ | +- machine-lxc\x2d22222\x2dcontainer2.scope
+ |
+ +- machine-marketing.slice
+ |
+ +- machine-lxc\x2d33333\x2dcontainer3.scope
+
+Prior libvirt 7.1.0 the topology doesn't have extra ``libvirt`` directory.
+
+Non-systemd cgroups layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On hosts which do not use systemd, each consumer has a corresponding cgroup
+named ``$VMNAME.libvirt-{qemu,lxc}``. Each consumer is associated with exactly
+one partition, which also have a corresponding cgroup usually named
+``$PARTNAME.partition``. The exceptions to this naming rule is the top level
+default partition for virtual machines and containers ``/machine``.
+
+Given this, a possible non-systemd cgroups layout involving 3 qemu guests, 3 lxc
+containers and 2 custom child slices, would be:
+
+::
+
+ $ROOT
+ |
+ +- machine
+ |
+ +- qemu-1-vm1.libvirt-qemu
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- qeme-2-vm2.libvirt-qemu
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- qemu-3-vm3.libvirt-qemu
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- engineering.partition
+ | |
+ | +- testing.partition
+ | | |
+ | | +- lxc-11111-container1.libvirt-lxc
+ | |
+ | +- production.partition
+ | |
+ | +- lxc-22222-container2.libvirt-lxc
+ |
+ +- marketing.partition
+ |
+ +- lxc-33333-container3.libvirt-lxc
+
+Using custom partitions
+-----------------------
+
+If there is a need to apply resource constraints to groups of virtual machines
+or containers, then the single default partition ``/machine`` may not be
+sufficiently flexible. The administrator may wish to sub-divide the default
+partition, for example into "testing" and "production" partitions, and then
+assign each guest to a specific sub-partition. This is achieved via a small
+element addition to the guest domain XML config, just below the main ``domain``
+element
+
+::
+
+ ...
+ <resource>
+ <partition>/machine/production</partition>
+ </resource>
+ ...
+
+Note that the partition names in the guest XML are using a generic naming
+format, not the low level naming convention required by the underlying host OS.
+That is, you should not include any of the ``.partition`` or ``.slice`` suffixes
+in the XML config. Given a partition name ``/machine/production``, libvirt will
+automatically apply the platform specific translation required to get
+``/machine/production.partition`` (non-systemd) or
+``/machine.slice/machine-production.slice`` (systemd) as the underlying cgroup
+name
+
+Libvirt will not auto-create the cgroups directory to back this partition. In
+the future, libvirt / virsh will provide APIs / commands to create custom
+partitions, but currently this is left as an exercise for the administrator.
+
+**Note:** the ability to place guests in custom partitions is only available
+with libvirt >= 1.0.5, using the new cgroup layout. The legacy cgroups layout
+described later in this document did not support customization per guest.
+
+Creating custom partitions (systemd)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given the XML config above, the admin on a systemd based host would need to
+create a unit file ``/etc/systemd/system/machine-production.slice``
+
+::
+
+ # cat > /etc/systemd/system/machine-testing.slice <<EOF
+ [Unit]
+ Description=VM testing slice
+ Before=slices.target
+ Wants=machine.slice
+ EOF
+ # systemctl start machine-testing.slice
+
+Creating custom partitions (non-systemd)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given the XML config above, the admin on a non-systemd based host would need to
+create a cgroup named '/machine/production.partition'
+
+::
+
+ # cd /sys/fs/cgroup
+ # for i in blkio cpu,cpuacct cpuset devices freezer memory net_cls perf_event
+ do
+ mkdir $i/machine/production.partition
+ done
+ # for i in cpuset.cpus cpuset.mems
+ do
+ cat cpuset/machine/$i > cpuset/machine/production.partition/$i
+ done
+
+Resource management APIs/commands
+---------------------------------
+
+Since libvirt aims to provide an API which is portable across hypervisors, the
+concept of cgroups is not exposed directly in the API or XML configuration. It
+is considered to be an internal implementation detail. Instead libvirt provides
+a set of APIs for applying resource controls, which are then mapped to
+corresponding cgroup tunables
+
+Scheduler tuning
+~~~~~~~~~~~~~~~~
+
+Parameters from the "cpu" controller are exposed via the ``schedinfo`` command
+in virsh.
+
+::
+
+ # virsh schedinfo demo
+ Scheduler : posix
+ cpu_shares : 1024
+ vcpu_period : 100000
+ vcpu_quota : -1
+ emulator_period: 100000
+ emulator_quota : -1
+
+Block I/O tuning
+~~~~~~~~~~~~~~~~
+
+Parameters from the "blkio" controller are exposed via the ``bkliotune`` command
+in virsh.
+
+::
+
+ # virsh blkiotune demo
+ weight : 500
+ device_weight :
+
+Memory tuning
+~~~~~~~~~~~~~
+
+Parameters from the "memory" controller are exposed via the ``memtune`` command
+in virsh.
+
+::
+
+ # virsh memtune demo
+ hard_limit : 580192
+ soft_limit : unlimited
+ swap_hard_limit: unlimited
+
+Network tuning
+~~~~~~~~~~~~~~
+
+The ``net_cls`` is not currently used. Instead traffic filter policies are set
+directly against individual virtual network interfaces.
+
+Legacy cgroups layout
+---------------------
+
+Prior to libvirt 1.0.5, the cgroups layout created by libvirt was different from
+that described above, and did not allow for administrator customization. Libvirt
+used a fixed, 3-level hierarchy ``libvirt/{qemu,lxc}/$VMNAME`` which was rooted
+at the point in the hierarchy where libvirtd itself was located. So if libvirtd
+was placed at ``/system/libvirtd.service`` by systemd, the groups for each
+virtual machine / container would be located at
+``/system/libvirtd.service/libvirt/{qemu,lxc}/$VMNAME``. In addition to this,
+the QEMU drivers further child groups for each vCPU thread and the emulator
+thread(s). This leads to a hierarchy that looked like
+
+::
+
+ $ROOT
+ |
+ +- system
+ |
+ +- libvirtd.service
+ |
+ +- libvirt
+ |
+ +- qemu
+ | |
+ | +- vm1
+ | | |
+ | | +- emulator
+ | | +- vcpu0
+ | | +- vcpu1
+ | |
+ | +- vm2
+ | | |
+ | | +- emulator
+ | | +- vcpu0
+ | | +- vcpu1
+ | |
+ | +- vm3
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- lxc
+ |
+ +- container1
+ |
+ +- container2
+ |
+ +- container3
+
+Although current releases are much improved, historically the use of deep
+hierarchies has had a significant negative impact on the kernel scalability. The
+legacy libvirt cgroups layout highlighted these problems, to the detriment of
+the performance of virtual machines and containers.
diff --git a/docs/meson.build b/docs/meson.build
index 5f26d40082..bb7e27e031 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -19,7 +19,6 @@ docs_assets = [
docs_html_in_files = [
'404',
- 'cgroups',
'csharp',
'dbus',
'docs',
@@ -70,6 +69,7 @@ docs_rst_files = [
'best-practices',
'bindings',
'bugs',
+ 'cgroups',
'ci',
'coding-style',
'committer-guidelines',
--
2.35.1
On Mon, Mar 28, 2022 at 02:10:17PM +0200, Peter Krempa wrote: > Signed-off-by: Peter Krempa <pkrempa@redhat.com> > --- Reviewed-by: Erik Skultety <eskultet@redhat.com>
The first sentence was moved up a paragraph to stop treating the first sub-heading as a page subtitle. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvtest.html.in | 27 --------------------------- docs/drvtest.rst | 21 +++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 22 insertions(+), 28 deletions(-) delete mode 100644 docs/drvtest.html.in create mode 100644 docs/drvtest.rst diff --git a/docs/drvtest.html.in b/docs/drvtest.html.in deleted file mode 100644 index 6884184e6f..0000000000 --- a/docs/drvtest.html.in +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Test "mock" driver</h1> - - <h2>Connections to Test driver</h2> - - <p> - The libvirt Test driver is a per-process fake hypervisor driver, - with a driver name of 'test'. The driver maintains all its state - in memory. It can start with a pre-configured default config, or - be given a path to an alternate config. Some example connection URIs - for the libvirt driver are: - </p> - -<pre> -test:///default (local access, default config) -test:///path/to/driver/config.xml (local access, custom config) -test+unix:///default (local access, default config, via daemon) -test://example.com/default (remote access, TLS/x509) -test+tcp://example.com/default (remote access, SASl/Kerberos) -test+ssh://root@example.com/default (remote access, SSH tunnelled) -</pre> - - </body> -</html> diff --git a/docs/drvtest.rst b/docs/drvtest.rst new file mode 100644 index 0000000000..99578a47ba --- /dev/null +++ b/docs/drvtest.rst @@ -0,0 +1,21 @@ +================== +Test "mock" driver +================== + +The libvirt ``test`` driver is a per-process fake hypervisor driver. + +Connections to Test driver +-------------------------- + +The driver maintains all its state in memory. It can start with +a pre-configured default config, or be given a path to an alternate config. Some +example connection URIs for the libvirt driver are: + +:: + + test:///default (local access, default config) + test:///path/to/driver/config.xml (local access, custom config) + test+unix:///default (local access, default config, via daemon) + test://example.com/default (remote access, TLS/x509) + test+tcp://example.com/default (remote access, SASl/Kerberos) + test+ssh://root@example.com/default (remote access, SSH tunnelled) diff --git a/docs/meson.build b/docs/meson.build index 8499b3d595..5995b2ec91 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -22,7 +22,6 @@ docs_html_in_files = [ 'csharp', 'dbus', 'docs', - 'drvtest', 'drvvbox', 'drvvirtuozzo', 'drvvmware', @@ -81,6 +80,7 @@ docs_rst_files = [ 'drvopenvz', 'drvqemu', 'drvsecret', + 'drvtest', 'errors', 'formatbackup', 'formatcheckpoint', -- 2.35.1
On Mon, Mar 28, 2022 at 02:10:25PM +0200, Peter Krempa wrote: > The first sentence was moved up a paragraph to stop treating the first > sub-heading as a page subtitle. > > Signed-off-by: Peter Krempa <pkrempa@redhat.com> > --- Reviewed-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvvirtuozzo.html.in | 70 --------------------------------------- docs/drvvirtuozzo.rst | 60 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 61 insertions(+), 71 deletions(-) delete mode 100644 docs/drvvirtuozzo.html.in create mode 100644 docs/drvvirtuozzo.rst diff --git a/docs/drvvirtuozzo.html.in b/docs/drvvirtuozzo.html.in deleted file mode 100644 index e47f72bad1..0000000000 --- a/docs/drvvirtuozzo.html.in +++ /dev/null @@ -1,70 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Virtuozzo driver</h1> - <ul id="toc"></ul> - <p> - The libvirt vz driver can manage Virtuozzo starting from version 6.0. - </p> - - - <h2><a id="project">Project Links</a></h2> - <ul> - <li> - The <a href="https://www.virtuozzo.com/">Virtuozzo</a> Solution. - </li> - </ul> - - - <h2><a id="uri">Connections to the Virtuozzo driver</a></h2> - <p> - The libvirt Virtuozzo driver is a single-instance privileged driver, with a driver name of 'virtuozzo'. Some example connection URIs for the libvirt driver are: - </p> -<pre> -vz:///system (local access) -vz+unix:///system (local access) -vz://example.com/system (remote access, TLS/x509) -vz+tcp://example.com/system (remote access, SASl/Kerberos) -vz+ssh://root@example.com/system (remote access, SSH tunnelled) -</pre> - - <h2><a id="example">Example guest domain XML configuration</a></h2> - - <p> - Virtuozzo driver require at least one hard disk for new domains - at this time. It is used for defining directory, where VM should - be created. - </p> - -<pre> -<domain type='vz'> - <name>demo</name> - <uuid>54cdecad-4492-4e31-a209-33cc21d64057</uuid> - <description>some description</description> - <memory unit='KiB'>1048576</memory> - <currentMemory unit='KiB'>1048576</currentMemory> - <vcpu placement='static'>2</vcpu> - <os> - <type arch='x86_64'>hvm</type> - </os> - <clock offset='utc'/> - <on_poweroff>destroy</on_poweroff> - <on_reboot>destroy</on_reboot> - <on_crash>destroy</on_crash> - <devices> - <disk type='file' device='disk'> - <source file='/storage/vol1'/> - <target dev='hda'/> - </disk> - <video> - <model type='vga' vram='33554432' heads='1'> - <acceleration accel3d='no' accel2d='no'/> - </model> - </video> - </devices> -</domain> - -</pre> - -</body></html> diff --git a/docs/drvvirtuozzo.rst b/docs/drvvirtuozzo.rst new file mode 100644 index 0000000000..fbb6ab0e71 --- /dev/null +++ b/docs/drvvirtuozzo.rst @@ -0,0 +1,60 @@ +================ +Virtuozzo driver +================ + +The libvirt vz driver can manage Virtuozzo starting from version 6.0. + +Project Links +------------- + +- The `Virtuozzo <https://www.virtuozzo.com/>`__ Solution. + +Connections to the Virtuozzo driver +----------------------------------- + +The libvirt Virtuozzo driver is a single-instance privileged driver, with a +driver name of 'virtuozzo'. Some example connection URIs for the libvirt driver +are: + +:: + + vz:///system (local access) + vz+unix:///system (local access) + vz://example.com/system (remote access, TLS/x509) + vz+tcp://example.com/system (remote access, SASl/Kerberos) + vz+ssh://root@example.com/system (remote access, SSH tunnelled) + +Example guest domain XML configuration +-------------------------------------- + +Virtuozzo driver require at least one hard disk for new domains at this time. It +is used for defining directory, where VM should be created. + +:: + + <domain type='vz'> + <name>demo</name> + <uuid>54cdecad-4492-4e31-a209-33cc21d64057</uuid> + <description>some description</description> + <memory unit='KiB'>1048576</memory> + <currentMemory unit='KiB'>1048576</currentMemory> + <vcpu placement='static'>2</vcpu> + <os> + <type arch='x86_64'>hvm</type> + </os> + <clock offset='utc'/> + <on_poweroff>destroy</on_poweroff> + <on_reboot>destroy</on_reboot> + <on_crash>destroy</on_crash> + <devices> + <disk type='file' device='disk'> + <source file='/storage/vol1'/> + <target dev='hda'/> + </disk> + <video> + <model type='vga' vram='33554432' heads='1'> + <acceleration accel3d='no' accel2d='no'/> + </model> + </video> + </devices> + </domain> diff --git a/docs/meson.build b/docs/meson.build index 954c4e4b96..99732f57ba 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -22,7 +22,6 @@ docs_html_in_files = [ 'csharp', 'dbus', 'docs', - 'drvvirtuozzo', 'drvvmware', 'drvxen', 'firewall', @@ -81,6 +80,7 @@ docs_rst_files = [ 'drvsecret', 'drvtest', 'drvvbox', + 'drvvirtuozzo', 'errors', 'formatbackup', 'formatcheckpoint', -- 2.35.1
On Mon, Mar 28, 2022 at 02:10:27PM +0200, Peter Krempa wrote: > Signed-off-by: Peter Krempa <pkrempa@redhat.com> > --- Reviewed-by: Erik Skultety <eskultet@redhat.com>
Note that if we want to preserve the link from the code block hilighting 'virConnectGetStoragePoolCapabilities' we'd need to re-stylize it as rST doesn't support nesting of links into preformatted code blocks. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatstoragecaps.html.in | 95 ---------------------------------- docs/formatstoragecaps.rst | 81 +++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 82 insertions(+), 96 deletions(-) delete mode 100644 docs/formatstoragecaps.html.in create mode 100644 docs/formatstoragecaps.rst diff --git a/docs/formatstoragecaps.html.in b/docs/formatstoragecaps.html.in deleted file mode 100644 index a9ecc371fa..0000000000 --- a/docs/formatstoragecaps.html.in +++ /dev/null @@ -1,95 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Storage Pool Capabilities XML format</h1> - - <ul id="toc"></ul> - - <h2><a id="Overview">Overview</a></h2> - - <p>The Storage Pool Capabilities XML will provide the information - to determine what types of Storage Pools exist, whether the pool is - supported, and if relevant the source format types, the required - source elements, and the target volume format types. </p> - - <h2><a id="elements">Element and attribute overview</a></h2> - - <p>A query interface was added to the virConnect API's to retrieve the - XML listing of the set of Storage Pool Capabilities - (<span class="since">Since 5.2.0</span>):</p> - -<pre> -<a href="/html/libvirt-libvirt-storage.html#virConnectGetStoragePoolCapabilities">virConnectGetStoragePoolCapabilities</a> -</pre> - - <p>The root element that emulator capability XML document starts with is - named <code>storagepoolCapabilities</code>. There will be any number of - <code>pool</code> child elements with two attributes <code>type</code> - and <code>supported</code>. Each <code>pool</code> element may have - a <code>poolOptions</code> or <code>volOptions</code> subelements to - describe the available features. Sample XML output is:</p> - -<pre> -<storagepoolCapabilities> - <pool type='dir' supported='yes'> - <volOptions> - <defaultFormat type='raw'</> - <enum name='targetFormatType'> - <value>none</value> - <value>raw</value> - ... - </enum> - </volOptions> - </pool> - <pool type='fs' supported='yes'> - <poolOptions> - <defaultFormat type='auto'</> - <enum name='sourceFormatType'> - <value>auto</value> - <value>ext2</value> - ... - </enum> - </poolOptions> - <volOptions> - <defaultFormat type='raw'</> - <enum name='targetFormatType'> - <value>none</value> - <value>raw</value> - ... - </enum> - </volOptions> - </pool> - ... -</storagepoolCapabilities> -</pre> - - <p>The following section describes subelements of the - <code>poolOptions</code> and <code>volOptions</code> subelements </p>: - - <dl> - <dt><code>defaultFormat</code></dt> - <dd>For the <code>poolOptions</code>, the <code>type</code> attribute - describes the default format name used for the pool source. For the - <code>volOptions</code>, the <code>type</code> attribute describes - the default volume name used for each volume. - </dd> - <dl> - <dt><code>enum</code></dt> - <dd>Each enum uses a name from the list below with any number of - <code>value</code> value subelements describing the valid values. - <dl> - <dt><code>sourceFormatType</code></dt> - <dd>Lists all the possible <code>poolOptions</code> source - pool format types. - </dd> - <dt><code>targetFormatType</code></dt> - <dd>Lists all the possible <code>volOptions</code> target volume - format types. - </dd> - </dl> - </dd> - </dl> - </dl> - </body> -</html> diff --git a/docs/formatstoragecaps.rst b/docs/formatstoragecaps.rst new file mode 100644 index 0000000000..32cd392931 --- /dev/null +++ b/docs/formatstoragecaps.rst @@ -0,0 +1,81 @@ +.. role:: since + +==================================== +Storage Pool Capabilities XML format +==================================== + +.. contents:: + +Overview +-------- + +The Storage Pool Capabilities XML will provide the information to determine what +types of Storage Pools exist, whether the pool is supported, and if relevant the +source format types, the required source elements, and the target volume format +types. + +Element and attribute overview +------------------------------ + +A query interface was added to the virConnect API's to retrieve the XML listing +of the set of Storage Pool Capabilities ( :since:`Since 5.2.0` ): + +:: + + virConnectGetStoragePoolCapabilities + +The root element that emulator capability XML document starts with is named +``storagepoolCapabilities``. There will be any number of ``pool`` child elements +with two attributes ``type`` and ``supported``. Each ``pool`` element may have a +``poolOptions`` or ``volOptions`` subelements to describe the available +features. Sample XML output is: + +:: + + <storagepoolCapabilities> + <pool type='dir' supported='yes'> + <volOptions> + <defaultFormat type='raw'</> + <enum name='targetFormatType'> + <value>none</value> + <value>raw</value> + ... + </enum> + </volOptions> + </pool> + <pool type='fs' supported='yes'> + <poolOptions> + <defaultFormat type='auto'</> + <enum name='sourceFormatType'> + <value>auto</value> + <value>ext2</value> + ... + </enum> + </poolOptions> + <volOptions> + <defaultFormat type='raw'</> + <enum name='targetFormatType'> + <value>none</value> + <value>raw</value> + ... + </enum> + </volOptions> + </pool> + ... + </storagepoolCapabilities> + +The following section describes subelements of the ``poolOptions`` and +``volOptions`` subelements + +``defaultFormat`` + For the ``poolOptions``, the ``type`` attribute describes the default format + name used for the pool source. For the ``volOptions``, the ``type`` attribute + describes the default volume name used for each volume. +``enum`` + Each enum uses a name from the list below with any number of ``value`` value + subelements describing the valid values. + + ``sourceFormatType`` + Lists all the possible ``poolOptions`` source pool format types. + ``targetFormatType`` + Lists all the possible ``volOptions`` target volume format types. diff --git a/docs/meson.build b/docs/meson.build index bb1359aacd..b911292480 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -25,7 +25,6 @@ docs_html_in_files = [ 'formatnetwork', 'formatnode', 'formatnwfilter', - 'formatstoragecaps', 'formatstorageencryption', 'hooks', 'index', @@ -88,6 +87,7 @@ docs_rst_files = [ 'formatsecret', 'formatsnapshot', 'formatstorage', + 'formatstoragecaps', 'glib-adoption', 'goals', 'governance', -- 2.35.1
On Mon, Mar 28, 2022 at 02:10:36PM +0200, Peter Krempa wrote: > Note that if we want to preserve the link from the code block hilighting > 'virConnectGetStoragePoolCapabilities' we'd need to re-stylize it as rST > doesn't support nesting of links into preformatted code blocks. > > Signed-off-by: Peter Krempa <pkrempa@redhat.com> > --- ... > +A query interface was added to the virConnect API's to retrieve the XML listing > +of the set of Storage Pool Capabilities ( :since:`Since 5.2.0` ): > + > +:: > + > + virConnectGetStoragePoolCapabilities Here too it should IMO be a ref instead of verbatim. Reviewed-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
docs/logging.html.in | 243 -------------------------------------------
docs/logging.rst | 243 +++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 244 insertions(+), 244 deletions(-)
delete mode 100644 docs/logging.html.in
create mode 100644 docs/logging.rst
diff --git a/docs/logging.html.in b/docs/logging.html.in
deleted file mode 100644
index 1052b763a0..0000000000
--- a/docs/logging.html.in
+++ /dev/null
@@ -1,243 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1 >Logging in the library and the daemon</h1>
-
- <p>Libvirt includes logging facilities starting from version 0.6.0,
- this complements the <a href="errors.html">error handling</a>
- mechanism and APIs to allow tracing through the execution of the
- library as well as in the libvirtd daemon.</p>
-
- <ul id="toc"/>
-
- <h2>
- <a id="log_library">Logging in the library</a>
- </h2>
- <p>The logging functionalities in libvirt are based on 3 key concepts,
- similar to the one present in other generic logging facilities like
- log4j:</p>
- <ul>
- <li><b>log messages</b>: they are information generated at runtime by
- the libvirt code. Each message includes a priority level (DEBUG = 1,
- INFO = 2, WARNING = 3, ERROR = 4), a category, function name and
- line number, indicating where it originated from, and finally
- a formatted message. In addition the library adds a timestamp
- at the beginning of the message</li>
- <li><b>log filters</b>: a set of patterns and priorities to accept
- or reject a log message. If the message category matches a filter,
- the message priority is compared to the filter priority, if lower
- the message is discarded, if higher the message is output. If
- no filter matches, then a general priority level is applied to
- all remaining messages. This allows, for example, capturing all
- debug messages for the QEMU driver, but otherwise only allowing
- errors to show up from other parts.</li>
- <li><b>log outputs</b>: once a message has gone through filtering a set of
- output defines where to send the message, they can also filter
- based on the priority, for example it may be useful to output
- all messages to a debugging file but only allow errors to be
- logged through syslog.</li>
- </ul>
-
- <h2>
- <a id="log_config">Configuring logging in the library</a>
- </h2>
- <p>The library configuration of logging is through 3 environment variables
- allowing to control the logging behaviour:</p>
- <ul>
- <li>LIBVIRT_DEBUG: it can take the four following values:
- <ul>
- <li>1 or "debug": asking the library to log every message emitted,
- though the filters can be used to avoid filling up the output</li>
- <li>2 or "info": log all non-debugging information</li>
- <li>3 or "warn": log warnings and errors, that's the default value</li>
- <li>4 or "error": log only error messages</li>
- </ul></li>
- <li>LIBVIRT_LOG_FILTERS: defines logging filters</li>
- <li>LIBVIRT_LOG_OUTPUTS: defines logging outputs</li>
- </ul>
- <p>Note that, for example, setting LIBVIRT_DEBUG= is the same as unset. If
- you specify an invalid value, it will be ignored with a warning. If you
- have an error in a filter or output string, some of the settings may be
- applied up to the point at which libvirt encountered the error.</p>
- <h2>
- <a id="log_daemon">Logging in the daemon</a>
- </h2>
- <p>Similarly the daemon logging behaviour can be tuned using 3 config
- variables, stored in the configuration file:</p>
- <ul>
- <li>log_level: accepts the following values:
- <ul>
- <li>4: only errors</li>
- <li>3: warnings and errors</li>
- <li>2: information, warnings and errors</li>
- <li>1: debug and everything</li>
- </ul></li>
- <li>log_filters: defines logging filters</li>
- <li>log_outputs: defines logging outputs</li>
- </ul>
- <p>When starting the libvirt daemon, any logging environment variable
- settings will override settings in the config file. Command line options
- take precedence over all. If no outputs are defined for libvirtd, it
- will try to use</p>
- <ul>
- <li>0.10.0 or later: systemd journal, if <code>/run/systemd/journal/socket</code> exists</li>
- <li>0.9.0 or later: file <code>/var/log/libvirt/libvirtd.log</code> if running as a daemon</li>
- <li>before 0.9.0: syslog if running as a daemon</li>
- <li>all versions: to stderr stream if running in the foreground</li>
- </ul>
- <p>Libvirtd does not reload its logging configuration when issued a SIGHUP.
- If you want to reload the configuration, you must do a <code>service
- libvirtd restart</code> or manually stop and restart the daemon
- yourself.</p>
- <p>Starting from 0.9.0, the daemon can save all the content of the debug
- buffer to the defined error channels (or /var/log/libvirt/libvirtd.log
- by default) in case of crash, this can also be activated explicitly
- for debugging purposes by sending the daemon a USR2 signal:</p>
- <pre>killall -USR2 libvirtd</pre>
- <h2>
- <a id="log_syntax">Syntax for filters and output values</a>
- </h2>
- <p>The syntax for filters and outputs is the same for both types of
- variables.</p>
- <p>The format for a filter is:</p>
- <pre>
-x:name</pre>
- <p>where <code>name</code> is a string which is matched against
- the category given in the VIR_LOG_INIT() at the top of each
- libvirt source file, e.g., <code>remote</code>, <code>qemu</code>,
- or <code>util.json</code> (the name in the filter can be a
- substring of the full category name, in order to match multiple
- similar categories), and <code>x</code> is the minimal
- level where matching messages should be logged:</p>
- <ul>
- <li>1: DEBUG</li>
- <li>2: INFO</li>
- <li>3: WARNING</li>
- <li>4: ERROR</li>
- </ul>
- <p>Multiple filters can be defined in a single string, they just need to be
- separated by spaces, e.g: <code>"3:remote 4:event"</code> to only get
- warning or errors from the remote layer and only errors from the event
- layer.</p>
- <p>If you specify a log priority in a filter that is below the default log
- priority level, messages that match that filter will still be logged,
- while others will not. In order to see those messages, you must also have
- an output defined that includes the priority level of your filter.</p>
- <p>The format for an output can be one of the following forms:</p>
- <ul>
- <li><code>x:stderr</code> output goes to stderr</li>
- <li><code>x:syslog:name</code> use syslog for the output and use the
- given <code>name</code> as the ident</li>
- <li><code>x:file:file_path</code> output to a file, with the given
- filepath</li>
- <li><code>x:journald</code> output goes to systemd journal</li>
- </ul>
- <p>In all cases the x prefix is the minimal level, acting as a filter:</p>
- <ul>
- <li>1: DEBUG</li>
- <li>2: INFO</li>
- <li>3: WARNING</li>
- <li>4: ERROR</li>
- </ul>
- <p>Multiple output can be defined, they just need to be separated by
- spaces, e.g.: <code>"3:syslog:libvirtd 1:file:/tmp/libvirt.log"</code>
- will log all warnings and errors to syslog under the libvirtd ident
- but also log all debug and information included in the
- file <code>/tmp/libvirt.log</code></p>
-
- <h2><a id="journald">Systemd journal fields</a></h2>
-
- <p>
- When logging to the systemd journal, the following fields
- are defined, in addition to any automatically recorded
- <a href="https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html">standard fields</a>:
- </p>
-
- <dl>
- <dt><code>MESSAGE</code></dt>
- <dd>The log message string</dd>
- <dt><code>PRIORITY</code></dt>
- <dd>The log priority value</dd>
- <dt><code>LIBVIRT_SOURCE</code></dt>
- <dd>The source type, one of "file", "error", "audit", "trace", "library"</dd>
- <dt><code>CODE_FILE</code></dt>
- <dd>The name of the file emitting the log record</dd>
- <dt><code>CODE_LINE</code></dt>
- <dd>The line number of the file emitting the log record</dd>
- <dt><code>CODE_FUNC</code></dt>
- <dd>The name of the function emitting the log record</dd>
- <dt><code>LIBVIRT_DOMAIN</code></dt>
- <dd>The libvirt error domain (values from virErrorDomain enum), if LIBVIRT_SOURCE="error"</dd>
- <dt><code>LIBVIRT_CODE</code></dt>
- <dd>The libvirt error code (values from virErrorCode enum), if LIBVIRT_SOURCE="error"</dd>
- </dl>
-
- <h3><a id="journaldids">Well known message ID values</a></h3>
-
- <p>
- Certain areas of the code will emit log records tagged with well known
- unique id values, which are guaranteed never to change in the future.
- This allows applications to identify critical log events without doing
- string matching on the <code>MESSAGE</code> field.
- </p>
-
- <dl>
- <dt><code>MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361</code></dt>
- <dd>Generated by the QEMU driver when it identifies a QEMU system
- emulator binary, but is unable to extract information about its
- capabilities. This is usually an indicator of a broken QEMU
- build or installation. When this is emitted, the <code>LIBVIRT_QEMU_BINARY</code>
- message field will provide the full path of the QEMU binary that failed.
- </dd>
- </dl>
-
- <p>
- The <code>journalctl</code> command can be used to search the journal
- matching on specific message ID values
- </p>
-
- <pre>
-$ journalctl MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361 --output=json
-{ ...snip...
- "LIBVIRT_SOURCE" : "file",
- "PRIORITY" : "3",
- "CODE_FILE" : "qemu/qemu_capabilities.c",
- "CODE_LINE" : "2770",
- "CODE_FUNC" : "virQEMUCapsLogProbeFailure",
- "MESSAGE_ID" : "8ae2f3fb-2dbe-498e-8fbd-012d40afa361",
- "LIBVIRT_QEMU_BINARY" : "/bin/qemu-system-xtensa",
- "MESSAGE" : "Failed to probe capabilities for /bin/qemu-system-xtensa:" \
- "internal error: Child process (LC_ALL=C LD_LIBRARY_PATH=/home/berrange" \
- "/src/virt/libvirt/src/.libs PATH=/usr/lib64/ccache:/usr/local/sbin:" \
- "/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/root/bin HOME=/root " \
- "USER=root LOGNAME=root /bin/qemu-system-xtensa -help) unexpected " \
- "exit status 127: /bin/qemu-system-xtensa: error while loading shared " \
- "libraries: libglapi.so.0: cannot open shared object file: No such " \
- "file or directory\n" }
- </pre>
-
- <h2>
- <a id="log_examples">Examples</a>
- </h2>
- <p>For example setting up the following:</p>
- <pre>export LIBVIRT_DEBUG=1
-export LIBVIRT_LOG_OUTPUTS="1:file:virsh.log"</pre>
- <p>and then running virsh will accumulate the logs in the
- <code>virsh.log</code> file in a way similar to:</p>
- <pre>14:29:04.771: debug : virInitialize:278 : register drivers
-14:29:04.771: debug : virRegisterDriver:618 : registering Test as driver 0</pre>
- <p>the messages are timestamped, there is also the level recorded,
- if debug the name of the function is also printed and then the formatted
- message. This should be sufficient to at least get a precise idea of
- what is happening and where things are going wrong, allowing to then
- put the correct breakpoints when running under a debugger.</p>
- <p>To activate full debug of the libvirt entry points, utility
- functions and the QEMU/KVM driver, set:</p>
- <pre>log_filters="1:libvirt 1:util 1:qemu"
-log_outputs="1:file:/var/log/libvirt/libvirtd.log"</pre>
- <p>in libvirtd.conf and restart the daemon will allow to
- gather a copious amount of debugging traces for the operations done
- in those areas.</p>
- </body>
-</html>
diff --git a/docs/logging.rst b/docs/logging.rst
new file mode 100644
index 0000000000..204176c6f5
--- /dev/null
+++ b/docs/logging.rst
@@ -0,0 +1,243 @@
+=====================================
+Logging in the library and the daemon
+=====================================
+
+.. contents::
+
+Libvirt includes logging facilities starting from version 0.6.0, this
+complements the `error handling <errors.html>`__ mechanism and APIs to allow
+tracing through the execution of the library as well as in the libvirtd daemon.
+
+Logging in the library
+----------------------
+
+The logging functionalities in libvirt are based on 3 key concepts, similar to
+the one present in other generic logging facilities like log4j:
+
+- **log messages**: they are information generated at runtime by the libvirt
+ code. Each message includes a priority level (DEBUG = 1, INFO = 2, WARNING =
+ 3, ERROR = 4), a category, function name and line number, indicating where it
+ originated from, and finally a formatted message. In addition the library
+ adds a timestamp at the beginning of the message
+- **log filters**: a set of patterns and priorities to accept or reject a log
+ message. If the message category matches a filter, the message priority is
+ compared to the filter priority, if lower the message is discarded, if higher
+ the message is output. If no filter matches, then a general priority level is
+ applied to all remaining messages. This allows, for example, capturing all
+ debug messages for the QEMU driver, but otherwise only allowing errors to
+ show up from other parts.
+- **log outputs**: once a message has gone through filtering a set of output
+ defines where to send the message, they can also filter based on the
+ priority, for example it may be useful to output all messages to a debugging
+ file but only allow errors to be logged through syslog.
+
+Configuring logging in the library
+----------------------------------
+
+The library configuration of logging is through 3 environment variables allowing
+to control the logging behaviour:
+
+- LIBVIRT_DEBUG: it can take the four following values:
+
+ - 1 or "debug": asking the library to log every message emitted, though the
+ filters can be used to avoid filling up the output
+ - 2 or "info": log all non-debugging information
+ - 3 or "warn": log warnings and errors, that's the default value
+ - 4 or "error": log only error messages
+
+- LIBVIRT_LOG_FILTERS: defines logging filters
+- LIBVIRT_LOG_OUTPUTS: defines logging outputs
+
+Note that, for example, setting LIBVIRT_DEBUG= is the same as unset. If you
+specify an invalid value, it will be ignored with a warning. If you have an
+error in a filter or output string, some of the settings may be applied up to
+the point at which libvirt encountered the error.
+
+Logging in the daemon
+---------------------
+
+Similarly the daemon logging behaviour can be tuned using 3 config variables,
+stored in the configuration file:
+
+- log_level: accepts the following values:
+
+ - 4: only errors
+ - 3: warnings and errors
+ - 2: information, warnings and errors
+ - 1: debug and everything
+
+- log_filters: defines logging filters
+- log_outputs: defines logging outputs
+
+When starting the libvirt daemon, any logging environment variable settings will
+override settings in the config file. Command line options take precedence over
+all. If no outputs are defined for libvirtd, it will try to use
+
+- 0.10.0 or later: systemd journal, if ``/run/systemd/journal/socket`` exists
+- 0.9.0 or later: file ``/var/log/libvirt/libvirtd.log`` if running as a daemon
+- before 0.9.0: syslog if running as a daemon
+- all versions: to stderr stream if running in the foreground
+
+Libvirtd does not reload its logging configuration when issued a SIGHUP. If you
+want to reload the configuration, you must do a
+``service libvirtd restart`` or manually stop and restart the daemon
+yourself.
+
+Starting from 0.9.0, the daemon can save all the content of the debug buffer to
+the defined error channels (or /var/log/libvirt/libvirtd.log by default) in case
+of crash, this can also be activated explicitly for debugging purposes by
+sending the daemon a USR2 signal:
+
+::
+
+ killall -USR2 libvirtd
+
+Syntax for filters and output values
+------------------------------------
+
+The syntax for filters and outputs is the same for both types of variables.
+
+The format for a filter is:
+
+::
+
+ x:name
+
+where ``name`` is a string which is matched against the category given in the
+VIR_LOG_INIT() at the top of each libvirt source file, e.g., ``remote``,
+``qemu``, or ``util.json`` (the name in the filter can be a substring of the
+full category name, in order to match multiple similar categories), and ``x`` is
+the minimal level where matching messages should be logged:
+
+- 1: DEBUG
+- 2: INFO
+- 3: WARNING
+- 4: ERROR
+
+Multiple filters can be defined in a single string, they just need to be
+separated by spaces, e.g: ``"3:remote 4:event"`` to only get warning or errors
+from the remote layer and only errors from the event layer.
+
+If you specify a log priority in a filter that is below the default log priority
+level, messages that match that filter will still be logged, while others will
+not. In order to see those messages, you must also have an output defined that
+includes the priority level of your filter.
+
+The format for an output can be one of the following forms:
+
+- ``x:stderr`` output goes to stderr
+- ``x:syslog:name`` use syslog for the output and use the given ``name`` as the
+ ident
+- ``x:file:file_path`` output to a file, with the given filepath
+- ``x:journald`` output goes to systemd journal
+
+In all cases the x prefix is the minimal level, acting as a filter:
+
+- 1: DEBUG
+- 2: INFO
+- 3: WARNING
+- 4: ERROR
+
+Multiple output can be defined, they just need to be separated by spaces, e.g.:
+``"3:syslog:libvirtd 1:file:/tmp/libvirt.log"`` will log all warnings and errors
+to syslog under the libvirtd ident but also log all debug and information
+included in the file ``/tmp/libvirt.log``
+
+Systemd journal fields
+----------------------
+
+When logging to the systemd journal, the following fields are defined, in
+addition to any automatically recorded `standard
+fields <https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html>`__:
+
+``MESSAGE``
+ The log message string
+``PRIORITY``
+ The log priority value
+``LIBVIRT_SOURCE``
+ The source type, one of "file", "error", "audit", "trace", "library"
+``CODE_FILE``
+ The name of the file emitting the log record
+``CODE_LINE``
+ The line number of the file emitting the log record
+``CODE_FUNC``
+ The name of the function emitting the log record
+``LIBVIRT_DOMAIN``
+ The libvirt error domain (values from virErrorDomain enum), if
+ LIBVIRT_SOURCE="error"
+``LIBVIRT_CODE``
+ The libvirt error code (values from virErrorCode enum), if
+ LIBVIRT_SOURCE="error"
+
+Well known message ID values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Certain areas of the code will emit log records tagged with well known unique id
+values, which are guaranteed never to change in the future. This allows
+applications to identify critical log events without doing string matching on
+the ``MESSAGE`` field.
+
+``MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361``
+ Generated by the QEMU driver when it identifies a QEMU system emulator
+ binary, but is unable to extract information about its capabilities. This is
+ usually an indicator of a broken QEMU build or installation. When this is
+ emitted, the ``LIBVIRT_QEMU_BINARY`` message field will provide the full path
+ of the QEMU binary that failed.
+
+The ``journalctl`` command can be used to search the journal matching on
+specific message ID values
+
+::
+
+ $ journalctl MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361 --output=json
+ { ...snip...
+ "LIBVIRT_SOURCE" : "file",
+ "PRIORITY" : "3",
+ "CODE_FILE" : "qemu/qemu_capabilities.c",
+ "CODE_LINE" : "2770",
+ "CODE_FUNC" : "virQEMUCapsLogProbeFailure",
+ "MESSAGE_ID" : "8ae2f3fb-2dbe-498e-8fbd-012d40afa361",
+ "LIBVIRT_QEMU_BINARY" : "/bin/qemu-system-xtensa",
+ "MESSAGE" : "Failed to probe capabilities for /bin/qemu-system-xtensa:" \
+ "internal error: Child process (LC_ALL=C LD_LIBRARY_PATH=/home/berrange" \
+ "/src/virt/libvirt/src/.libs PATH=/usr/lib64/ccache:/usr/local/sbin:" \
+ "/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/root/bin HOME=/root " \
+ "USER=root LOGNAME=root /bin/qemu-system-xtensa -help) unexpected " \
+ "exit status 127: /bin/qemu-system-xtensa: error while loading shared " \
+ "libraries: libglapi.so.0: cannot open shared object file: No such " \
+ "file or directory\n" }
+
+Examples
+--------
+
+For example setting up the following:
+
+::
+
+ export LIBVIRT_DEBUG=1
+ export LIBVIRT_LOG_OUTPUTS="1:file:virsh.log"
+
+and then running virsh will accumulate the logs in the ``virsh.log`` file in a
+way similar to:
+
+::
+
+ 14:29:04.771: debug : virInitialize:278 : register drivers
+ 14:29:04.771: debug : virRegisterDriver:618 : registering Test as driver 0
+
+the messages are timestamped, there is also the level recorded, if debug the
+name of the function is also printed and then the formatted message. This should
+be sufficient to at least get a precise idea of what is happening and where
+things are going wrong, allowing to then put the correct breakpoints when
+running under a debugger.
+
+To activate full debug of the libvirt entry points, utility functions and the
+QEMU/KVM driver, set:
+
+::
+
+ log_filters="1:libvirt 1:util 1:qemu"
+ log_outputs="1:file:/var/log/libvirt/libvirtd.log"
+
+in libvirtd.conf and restart the daemon will allow to gather a copious amount of
+debugging traces for the operations done in those areas.
diff --git a/docs/meson.build b/docs/meson.build
index e1b618438c..f6e51353f0 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -27,7 +27,6 @@ docs_html_in_files = [
'formatnwfilter',
'index',
'internals',
- 'logging',
'php',
'python',
'remote',
@@ -94,6 +93,7 @@ docs_rst_files = [
'java',
'libvirt-go',
'libvirt-go-xml',
+ 'logging',
'macos',
'migration',
'newreposetup',
--
2.35.1
On Mon, Mar 28, 2022 at 02:10:42PM +0200, Peter Krempa wrote: > Signed-off-by: Peter Krempa <pkrempa@redhat.com> > --- Reviewed-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/php.html.in | 28 ---------------------------- docs/php.rst | 23 +++++++++++++++++++++++ 3 files changed, 24 insertions(+), 29 deletions(-) delete mode 100644 docs/php.html.in create mode 100644 docs/php.rst diff --git a/docs/meson.build b/docs/meson.build index f6e51353f0..c1def26655 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -27,7 +27,6 @@ docs_html_in_files = [ 'formatnwfilter', 'index', 'internals', - 'php', 'python', 'remote', 'storage', @@ -100,6 +99,7 @@ docs_rst_files = [ 'nss', 'pci-addresses', 'pci-hotplug', + 'php', 'platforms', 'programming-languages', 'securityprocess', diff --git a/docs/php.html.in b/docs/php.html.in deleted file mode 100644 index 9340c81eec..0000000000 --- a/docs/php.html.in +++ /dev/null @@ -1,28 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>PHP API bindings</h1> - -<h2>Presentation</h2> - <p>The libvirt-php, originally called php-libvirt, is the PHP API bindings for - the libvirt virtualization toolkit originally developed by Radek Hladik.</p> - -<h2>Getting the source</h2> -<p> The PHP bindings code source is now maintained in a <a -href="https://git-scm.com/">git</a> repository available on -<a href="https://gitlab.com/libvirt/libvirt-php">gitlab.com</a>: -</p> -<pre> -git clone https://gitlab.com/libvirt/libvirt-php.git -</pre> - -<p></p> -<h2>Project pages</h2> -<p>Since February 2011 the project has its own pages hosted at libvirt.org. For more information on the project - please refer to <a href="https://libvirt.org/php">https://libvirt.org/php</a>. - -</p> - - </body> -</html> diff --git a/docs/php.rst b/docs/php.rst new file mode 100644 index 0000000000..36f7c44bed --- /dev/null +++ b/docs/php.rst @@ -0,0 +1,23 @@ +================ +PHP API bindings +================ + +The libvirt-php, originally called php-libvirt, is the PHP API bindings for the +libvirt virtualization toolkit originally developed by Radek Hladik. + +Getting the source +------------------ + +The PHP bindings code source is now maintained in a +`git <https://git-scm.com/>`__ repository available on +`gitlab.com <https://gitlab.com/libvirt/libvirt-php>`__: + +:: + + git clone https://gitlab.com/libvirt/libvirt-php.git + +Project pages +------------- + +Since February 2011 the project has its own pages hosted at libvirt.org. For +more information on the project please refer to https://libvirt.org/php. -- 2.35.1
© 2016 - 2024 Red Hat, Inc.