1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
.. -*- mode: rst -*-
.. _client-metadata:
===============
Client Metadata
===============
This page describes ClientMetadata objects. These are used to describe
clients in terms of a variety of parameters, group memberships, and
so forth.
Construction
============
ClientMetadata instances are constructed whenever the server needs
to recognize a client. This occurs in every aspect of client server
interaction:
* Probing
* Configuration Generation
* Statistics Upload
This construction process spans several server plugins. The
:ref:`server-plugins-grouping-metadata` is responsible for initial
instance creation, including the client hostname, profile, and basic
group memberships. After this initial creation, Connector plugins (such as
:ref:`server-plugins-probes-index` or :ref:`server-plugins-properties`)
can add additional group memberships for clients. These memberships
are merged into the instance; that is, the new group memberships are
treated as if they were included in groups.xml. If any of these groups
are defined in groups.xml, then groups included there are included in
the ClientMetadata instance group list. At the end of this process, the
ClientMetadata instance has its complete set of group memberships. At this
point, each connector plugin has the opportunity to return an additional
object which will be placed in an attribute corresponding to the Connector
name. For example, the Probes plugin returns a dictionary of probe name
to probe result mappings for the client. This dictionary is available as
the "Probes" attribute. With this, ClientMetadata resolution is complete,
and the ClientMetadata instance can be used by the rest of the system.
Contents
========
ClientMetadata instances contain all of the information needed to
differentiate clients from one another. This data includes:
* hostname
* groups
* profile group
* address information (if specified)
ClientMetadata instances also contain a query object. This can be used
to query the metadata of other clients. Currently, several methods are
supported. In this table, we refer to the instance as meta. Each of
these is a function that must be called.
+------------------------------------------+-------------------+----------------+
| Name | Description | Return Type |
+==========================================+===================+================+
| meta.query.names_by_groups([group list]) | Returns names of | List of |
| | clients which are | client names |
| | members of all | |
| | groups | |
+------------------------------------------+-------------------+----------------+
| meta.query.names_by_profile(profile) | Returns names of | List of |
| | clients which use | client names |
| | profile group | |
+------------------------------------------+-------------------+----------------+
| meta.query.all_clients() | Returns names of | List of |
| | all clients | client names |
+------------------------------------------+-------------------+----------------+
| meta.query.all_groups() | Returns names of | List of |
| | all groups | group names |
+------------------------------------------+-------------------+----------------+
| meta.query.all() | Returns metadata | List of |
| | for all clients | ClientMetadata |
| | | instances |
+------------------------------------------+-------------------+----------------+
| meta.query.by_name(name) | Returns metadata | ClientMetadata |
| | for named client | instance |
+------------------------------------------+-------------------+----------------+
| meta.query.by_groups([group list]) | Returns metadata | List of |
| | for all members | ClientMetadata |
| | of all groups | instances |
+------------------------------------------+-------------------+----------------+
| meta.query.by_profile(profile) | Returns metadata | List of |
| | for all profile | ClientMetadata |
| | havers | instances |
+------------------------------------------+-------------------+----------------+
In general, there is no substantial benefit to using name returning
versions of the query functions; metadata resolution is (in general) fast.
|
