[libvirt] [PATCH v3 1/9] lib: add virDomainGetGuestInfo()

[Jonathon Jongsma]

On Wed, 2019-08-28 at 16:37 +0100, Daniel P. Berrangé wrote:
> On Fri, Aug 23, 2019 at 11:31:15AM -0500, Jonathon Jongsma wrote:
> > This API is intended to aggregate several guest agent information
> > queries and is ispired by stats API virDomainListGetStats(). It is
> > anticipated that this information will be provided by a guest agent
> > running within the domain.
> > 
> > Signed-off-by: Jonathon Jongsma <jjongsma at redhat.com>
> > ---
> >  include/libvirt/libvirt-domain.h |  14 ++++
> >  src/driver-hypervisor.h          |   8 +++
> >  src/libvirt-domain.c             | 117
> > +++++++++++++++++++++++++++++++
> >  src/libvirt_public.syms          |   1 +
> >  4 files changed, 140 insertions(+)
> > 
> > +/**
> > + * virDomainGetGuestInfo:
> > + * @domain: pointer to domain object
> > + * @types: types of information to return, binary-OR of
> > virDomainGuestInfoTypes
> > + * @params: location to store the guest info parameters
> > + * @nparams: number of items in @params
> > + * @flags: currently unused, set to 0
> > + *
> > + * Queries the guest agent for the various information about the
> > guest system.
> > + * The reported data depends on the guest agent implementation.
> > the information
> > + * is returned as an array of typed parameters containing the
> > individual
> > + * parameters. The parameter name for each information field
> > consists of a
> > + * dot-separated strign containing the name of the requested group
> > followed by
> > + * a group-specific description of the statistic value.
> > + *
> > + * The information groups are enabled using the @types parameter
> > which is a
> > + * binary-OR of enum virDomainGuestInfoTypes. The following groups
> > are available
> > + * (although not necessarily implemented for each hypervisor):
> > + *
> > + * VIR_DOMAIN_GUEST_INFO_USERS:
> > + *  returns information about users that are currently logged in
> > within the
> > + *  guest domain. The typed parameter keys are in this format:
> > + *
> > + *      "user.count" - the number of active users on this domain
> > as an
> > + *                     unsigned int
> > + *      "user.<num>.name - username of the user as a string
> > + *      "user.<num>.domain - domain of the user as a string (may
> > only be
> > + *                           present on certain guest types)
> > + *      "user.<num>.login-time - the login time of a user in
> > milliseconds
> > + *                               since the epoch as unsigned long
> > long
> > + *
> > + * VIR_DOMAIN_GUEST_INFO_OS:
> > + *  Return information about the operating system running within
> > the guest. The
> > + *  typed parameter keys are in this format:
> > + *
> > + *      "os.id" - a string identifying the operating system
> > + *      "os.name" - the name of the operating system, suitable for
> > presentation
> > + *                  to a user, as a string
> > + *      "os.pretty-name" - a pretty name for the operating system,
> > suitable for
> > + *                         presentation to a user, as a string
> > + *      "os.version" - the version of the operating system
> > suitable for
> > + *                     presentation to a user, as a string
> > + *      "os.version-id" - the version id of the operating system
> > suitable for
> > + *                        processing by scripts, as a string
> > + *      "os.kernel-release" - the release of the operating system
> > kernel, as a
> > + *                            string
> > + *      "os.kernel-version" - the version of the operating system
> > kernel, as a
> > + *                            string
> > + *      "os.machine" - the machine hardware name as a string
> > + *      "os.variant" - a specific variant or edition of the
> > operating system
> > + *                     suitable for presentation to a user, as a
> > string
> > + *      "os.variant-id" - the id for a specific variant or edition
> > of the
> > + *                        operating system, as a string
> > + *
> > + * VIR_DOMAIN_GUEST_INFO_TIMEZONE:
> > + *  Returns information about the timezone within the domain. The
> > typed
> > + *  parameter keys are in this format:
> > + *
> > + *      "timezone.name" - the name of the timezone as a string
> > + *      "timezone.offset" - the offset to UTC in seconds as an int
> > + *
> > + * VIR_DOMAIN_GUEST_INFO_FILESYSTEM:
> > + *  Returns inforamtion about the filesystems within the
> > domain.  The typed
> > + *  parameter keys are in this format:
> > + *      "fs.count" - the number of filesystems defined on this
> > domain
> > + *                   as an unsigned int
> > + *      "fs.<num>.mountpoint" - the path to the mount point for
> > the filesystem
> > + *      "fs.<num>.name" - device name in the guest (e.g. "sda1")
> > + *      "fs.<num>.fstype" - the type of filesystem
> > + *      "fs.<num>.total-bytes" - the total size of the filesystem
> > + *      "fs.<num>.used-bytes" - the number of bytes used in the
> > filesystem
> > + *      "fs.<num>.disk.count" - the number of disks targeted by
> > this filesystem
> > + *      "fs.<num>.disk.<num>.alias" - the device alias of the disk
> > (e.g. sda)
> > + *      "fs.<num>.disk.<num>.serial" - the serial number of the
> > disk
> > + *      "fs.<num>.disk.<num>.device" - the device node of the disk
> 
> This hasn't documented VIR_DOMAIN_GUEST_INFO_HOSTNAME at all


Unfortunately Michal merged the patch before this was caught, but I did
send out a follow-up yesterday after I noticed it.

Jonathon