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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
|
.. -*- mode: rst -*-
.. _server-plugins-grouping-metadata:
========
Metadata
========
The metadata mechanism has two types of information, client metadata and
group metadata. The client metadata describes which top level group a
client is associated with.The group metadata describes groups in terms
of what bundles and other groups they include. Each aspect grouping
and clients' memberships are reflected in the ``Metadata/groups.xml`` and
``Metadata/clients.xml`` files, respectively.
Usage of Groups in Metadata
===========================
Clients are assigned membership of groups in the Metadata descriptions.
Clients can be directly assigned to *'profile'* or *'public'* groups.
Client membership of all other groups is by those groups being
associated with the profile or public groups. This file can be indirectly
modified from clients through use of the ``-p`` flag to ``bcfg2``.
Clients are associated with profile groups in ``Metadata/clients.xml`` as
shown below.
.. _server-plugins-grouping-metadata-clients-xml:
Metadata/clients.xml
====================
The ``Metadata/clients.xml`` file contains the mappings of Profile Groups
to clients. The file is just a series of *<Client />* tags, each of which
describe one host. A sample file is below:
.. code-block:: xml
<Clients version="3.0">
<Client profile="backup-server" pingable="Y" pingtime="0" name="backup.example.com"/>
<Client profile="console-server" pingable="Y" pingtime="0" name="con.example.com"/>
<Client profile="kerberos-master" pingable="Y" pingtime="0" name="kdc.example.com"/>
<Client profile="mail-server" pingable="Y" pingtime="0" name="mail.example.com"/>
<Client name='foo' address='10.0.0.1' pingable='N' pingtime='-1'>
<Alias name='foo-mgmt' address='10.1.0.1'/>
</Client>
</Clients>
Clients Tag
-----------
The Clients tag has the following possible attributes:
+---------+-----------------------+--------+
| Name | Description | Values |
+=========+=======================+========+
| version | Client schema version | String |
+---------+-----------------------+--------+
Client Tag
----------
Each entry in ``clients.xml`` **must** have the following properties:
+---------+---------------------------------------+--------+
| Name | Description | Values |
+=========+=======================================+========+
| name | Host name of client. This needs to be | String |
| | the name (possibly a FQDN) returned | |
| | by a reverse lookup on the connecting | |
| | IP address. | |
+---------+---------------------------------------+--------+
| profile | Profile group name to associate this | String |
| | client with. | |
+---------+---------------------------------------+--------+
Additionally, the following properties can be specified:
+----------+----------------------------------------+----------------+
| Name | Description | Values |
+==========+========================================+================+
| Alias | Alternative name and address for the | XML Element |
| | client. | |
+----------+----------------------------------------+----------------+
| address | Establishes an extra IP address that | ip address |
| | resolves to this client. | |
+----------+----------------------------------------+----------------+
| location | Requires requests to come from an IP | fixed|floating |
| | address that matches the client | |
| | record. | |
+----------+----------------------------------------+----------------+
| password | Establishes a per-node password that | String |
| | can be used instead of the global | |
| | password. | |
+----------+----------------------------------------+----------------+
| pingable | If the client is pingable (deprecated; | Y|N |
| | for old reporting system) | |
+----------+----------------------------------------+----------------+
| pingtime | Last time the client was pingable | String |
| | (deprecated; for old reporting system) | |
+----------+----------------------------------------+----------------+
| secure | Requires the use of the per-client | true|false |
| | password for this client. | |
+----------+----------------------------------------+----------------+
| uuid | Establishes a per-node name that can | String |
| | be used to bypass dns-based client | |
| | resolution. | |
+----------+----------------------------------------+----------------+
For detailed information on client authentication see
:ref:`appendix-guides-authentication`
Metadata/groups.xml
===================
The ``Metadata/groups.xml`` file contains Group and Profile
definitions. Here's a simple ``Metadata/groups.xml`` file:
.. code-block:: xml
<Groups version='3.0'>
<Group name='mail-server' profile='true'
public='false'
comment='Top level mail server group' >
<Bundle name='mail-server'/>
<Bundle name='mailman-server'/>
<Group name='apache-server'/>
<Group name='rhel-as-5-x86'/>
<Group name='nfs-client'/>
<Group name='server'/>
</Group>
<Group name='rhel-as-5-x86'>
<Group name='rhel'/>
</Group>
<Group name='apache-server'/>
<Group name='nfs-client'/>
<Group name='server'/>
<Group name='rhel'/>
</Groups>
Nested/chained groups definitions are conjunctive (logical and). For
instance, in the above example, a client associated with the Profile
Group ``mail-server`` is also a member of the ``apache-server``,
``rhel-as-5-x86``, ``nfs-client``, ``server``, and ``rhel`` groups.
Groups describe clients in terms for abstract, disjoint aspects. Groups
can be combined to form complex descriptions of clients that use
configuration commonality and inheritance. Groups have several attributes,
described below:
Metadata Groups Tag
-------------------
The Groups tag has the following possible attributes:
+----------+---------------------------------+--------+
| Name | Description | Values |
+==========+=================================+========+
| version | Group schema version | String |
+----------+---------------------------------+--------+
| origin | URL of master version | String |
| | (for common repository) | |
+----------+---------------------------------+--------+
| revision | Master version control revision | String |
+----------+---------------------------------+--------+
Metadata Group Tag
------------------
The Group Tag has the following possible attributes:
+----------+------------------------------------------+--------------+
| Name | Description | Values |
+==========+==========================================+==============+
| name | Name of the group | String |
+----------+------------------------------------------+--------------+
| profile | If a client can be directly associated | True|False |
| | with this group | |
+----------+------------------------------------------+--------------+
| public | If a client can freely associate itself | True|False |
| | with this group. For use with the | |
| | *bcfg2 -p* option on the client. | |
+----------+------------------------------------------+--------------+
| category | A group can only contain one instance of | String |
| | a group in any one category. This | |
| | provides the basis for representing | |
| | groups which are conjugates of one | |
| | another in a rigorous way. It also | |
| | provides the basis for negation. | |
+----------+------------------------------------------+--------------+
| default | Set as the profile to use for clients | True|False |
| | that are not associated with a profile | |
| | in ``clients.xml`` | |
+----------+------------------------------------------+--------------+
| comment | English text description of group | String |
+----------+------------------------------------------+--------------+
Groups can also contain other groups and bundles.
Use of XInclude
===============
`XInclude <http://www.w3.org/TR/xinclude/>`_ is a W3C specification
for the inclusion of external XML documents into XML source
files. Much like the use of ``#include`` in C, this allows complex
definitions to be split into smaller, more manageable pieces. As of
bcfg2-0.9.0pre1, the `Metadata`_ plugin supports the use of XInclude
specifications to split the ``clients.xml`` and ``groups.xml``
files. This mechanism allows the following specification to produce
useful results:
.. code-block:: xml
<Groups version='3.0' xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="my-groups.xml" />
<xi:include href="their-groups.xml" />
</Groups>
Each of the included groups files has the same format. These files are
properly validated by ``bcfg2-lint``. This mechanism is useful for
composing group definitions from multiple sources, or setting
different permissions in an svn repository.
Probes
======
The metadata plugin includes client-side probing functionality. This
is fully documented :ref:`here <server-plugins-probes-index>`.
.. _server-plugins-grouping-metadata-clientmetadata:
ClientMetadata
==============
A special client metadata class is available to the
:ref:`TGenshi <server-plugins-generators-tgenshi-index>` and
:ref:`TCheetah <server-plugins-generators-tcheetah>` plugins.
+----------------------+------------------------------------------------+-------------------+
| Attribute | Description | Value |
+======================+================================================+===================+
| hostname | Client hostname | String |
+----------------------+------------------------------------------------+-------------------+
| profile | Client profile | String |
+----------------------+------------------------------------------------+-------------------+
| aliases | Client aliases | List |
+----------------------+------------------------------------------------+-------------------+
| addresses | Adresses this client is known by | List |
+----------------------+------------------------------------------------+-------------------+
| groups | Groups this client is a member of | List |
+----------------------+------------------------------------------------+-------------------+
| categories | Categories of this clients groups | List |
+----------------------+------------------------------------------------+-------------------+
| uuid | uuid identifier for this client | String |
+----------------------+------------------------------------------------+-------------------+
| password | bcfg password for this client | String |
+----------------------+------------------------------------------------+-------------------+
| connectors | connector plugins known to this client | List |
+----------------------+------------------------------------------------+-------------------+
| query | MetadataQuery object | MetadataQuery |
+----------------------+------------------------------------------------+-------------------+
|
+------------------------------+------------------------------------------------+-------------------+
| Method | Description | Value |
+==============================+================================================+===================+
| inGroup(group) | True if this client is a memnber of 'group' | Boolean |
+------------------------------+------------------------------------------------+-------------------+
| group_in_category(category) | Returns the group in 'category' if the client | String |
| | is a member of 'category', otherwise '' | |
+------------------------------+------------------------------------------------+-------------------+
MetadataQuery
-------------
This class provides query methods for the metadata of all clients
known to the Bcfg2 server. Note that ``*by_groups()`` and
``*by_profiles()`` behave differently; for a client to be included in
the return value of a ``by_groups()`` method, it must be a member of
*all* groups listed in the argument; for a client to be included in
the return value of a ``by_profiles()`` method, it must have any group
listed as its profile group.
+------------------------------+------------------------------------------------+-------------------+
| Method | Description | Value |
+==============================+================================================+===================+
| by_name(client) | Get ClientMetadata object for 'client' | ClientMetadata |
+------------------------------+------------------------------------------------+-------------------+
| by_groups(groups) | Get ClientMetadata object for clients in all | List of |
| | listed groups | ClientMetadata |
+------------------------------+------------------------------------------------+-------------------+
| by_profiles(client) | Get ClientMetadata objects for clients whose | List of |
| | profile matches any listed profile group | ClientMetadata |
+------------------------------+------------------------------------------------+-------------------+
| names_by_groups(groups) | Get the names of all clients in all listed | List of strings |
| | groups | |
+------------------------------+------------------------------------------------+-------------------+
| names_by_profiles(profiles) | Get the names of clients whose profile matches | List of strings |
| | any listed profile group | |
+------------------------------+------------------------------------------------+-------------------+
| all_clients() | All known client hostnames | List of strings |
+------------------------------+------------------------------------------------+-------------------+
| all_groups() | All known group names | List of strings |
+------------------------------+------------------------------------------------+-------------------+
| all_groups_in_category(cat) | The names of all groups in category 'cat' | List of strings |
+------------------------------+------------------------------------------------+-------------------+
| all() | Get ClientMetadata for all clients | List of |
| | | ClientMetadata |
+------------------------------+------------------------------------------------+-------------------+
|
