[libvirt] [PATCH 6/6] docs: add page describing the libvirt daemons

[Daniel P. Berrangé]

On Mon, Nov 11, 2019 at 03:24:28PM +0100, Ján Tomko wrote:
> On Fri, Nov 08, 2019 at 11:21:12AM +0000, Daniel P. Berrangé wrote:
> > Now that we have more than just the libvirtd daemon, we should be
> > explaining to users what they are all for & important aspects of their
> > configuration.
> > 
> > Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
> > ---
> > docs/Makefile.am  |   7 +-
> > docs/daemons.rst  | 209 ++++++++++++++++++++++++++++++++++++++++++++++
> > docs/docs.html.in |   3 +
> > 3 files changed, 218 insertions(+), 1 deletion(-)
> > create mode 100644 docs/daemons.rst
> > 
> > diff --git a/docs/daemons.rst b/docs/daemons.rst
> > new file mode 100644
> > index 0000000000..51d4153b99
> > --- /dev/null
> > +++ b/docs/daemons.rst
> 
> [...]
> 
> > +Sockets
> > +-------
> > +
> > +When running in system mode, `libvirtd` exposes three UNIX domain sockets, and
> > +optionally, one or two TCP sockets
> > +
> > +* `/var/run/libvirt/libvirt-sock` - the primary socket for accessing libvirt
> 
> All the stuff in backticks are rendered in italics for me. A fixed-width
> font would look better.
> 
> > +  APIs, with full read-write privileges. A connection to this socket gives the
> > +  client privileges that are equivalent to having a root shell. This is the
> > +  socket that most management applications connect to by default.
> > +
> > +* `/var/run/libvirt/libvirt-sock-ro` - the secondary socket for accessing
> > +  libvirt APIs, with limited read-only privileges. A connection to this socket
> > +  gives the ability to query the existance of objects and monitor some aspects
> > +  of their operation. This is the socket that most management applications
> > +  connect to when requesting read only mode. Typically this is what a
> > +  monitoring app would use.
> > +
> > +* `/var/run/libvirt/libvirt-sock-admin` - the administrative socket for
> > +  controlling operation of the daemon itself (as opposed to drivers it is
> > +  running). This can be used to dynamically reconfigure some aspects of the
> > +  daemon and monitor/control connected clients.
> > +
> 
> [...]
> 
> > +Logging daemon
> > +--------------
> > +
> > +The `virtlogd` daemon provides a service for managing log files associated with
> > +QEMU virtual machines. The QEMU process is given one or more pipes, the other
> > +end of which are owned by the `virtlogd` daemon. It will then write data on
> > +those pipes to log files, while enforcing a maximum file size and performing
> > +log rollover at the size limit.
> > +
> > +Since the daemon holds open anoymous pipe file descriptors, it must never be
> > +stopped while any QEMU virtual machines are running. To enable software updates
> > +to be applied, the daemon is capable of re-executing itself while keeping all
> > +file descriptors open. This can be triggered by sending the daemon `SIGUSR1`
> > +
> > +Systemd integration
> > +~~~~~~~~~~~~~~~~~~~
> 
> Empty sections.

Sorry, I didn't mean to send patch 6 yet - it is obviously incomplete :-)

> Also, the '¶' character with a tooltip of 'Permalink to this headline'
> is no longer rendered here.

I'll think about how to handle this...

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|