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
|
.. -*- 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. Group data and
clients' memberships are reflected in the `groups.xml`_ and
`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 `clients.xml`_
as shown below.
.. _server-plugins-grouping-metadata-clients-xml:
clients.xml
===========
The ``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" name="backup.example.com"/>
<Client profile="console-server" name="con.example.com"/>
<Client profile="kerberos-master" name="kdc.example.com"/>
<Client profile="mail-server" name="mail.example.com"/>
<Client name='foo' address='10.0.0.1'>
<Alias name='foo-mgmt' address='10.1.0.1'/>
</Client>
</Clients>
.. xml:schema:: clients.xsd
For detailed information on client authentication see
:ref:`appendix-guides-authentication`
.. _server-plugins-grouping-metadata-clients-database:
Clients Database
----------------
.. versionadded:: 1.3.0
It is also possible to store client records in a database rather than
writing back to `clients.xml`_. This provides several advantages:
* `clients.xml`_ will never be written by the server, removing an
area of contention between the user and server.
* `clients.xml`_ can be removed entirely for many sites.
* The Bcfg2 client list can be queried by other machines without
obtaining and parsing `clients.xml`_.
* A single client list can be shared amongst multiple Bcfg2 servers.
In general, storing clients in the database works almost the same as
`clients.xml`_. `groups.xml`_ is parsed identically. If
`clients.xml`_ is present, it is parsed, but ``<Client>`` tags in
`clients.xml`_ *do not* assert client existence; they are only used
to set client options *if* the client exists (in the database). That
is, the two purposes of `clients.xml`_ -- to track which clients
exist, and to set client options -- have been separated.
With the improvements in `groups.xml`_ parsing in 1.3, client groups
can now be set directly in `groups.xml`_ with ``<Client>`` tags. (See
:xml:type:`clientType` for more details.) As a result, `clients.xml`_
is only necessary if you need to set options (e.g., aliases, floating
clients, per-client passwords, etc.) on clients.
To use the database backend instead of `clients.xml`_, set
``use_database`` in the ``[metadata]`` section of ``bcfg2.conf`` to
``true``. You will also need to configure the :ref:`Global Server
Database Settings <server-database>`.
The `clients.xml`_-based model remains the default.
.. _server-plugins-grouping-metadata-groups-xml:
groups.xml
==========
The ``groups.xml`` file contains Group and Profile definitions. Here's
a simple ``groups.xml`` file:
.. code-block:: xml
<Groups>
<Group name='mail-server' profile='true'
comment='Top level mail server group' >
<Bundle name='mail-server'/>
<Bundle name='mailman-server'/>
<Group name='apache-server'/>
<Group name='nfs-client'/>
<Group name='server'/>
<Group name='rhel5'>
<Group name='sendmail-server'/>
</Group>
<Group name='rhel6'>
<Group name='postfix-server'/>
</Group>
</Group>
<Group name='rhel'>
<Group name='selinux-enabled'/>
</Group>
<Group name='oracle-server'>
<Group name='selinux-enabled' negate='true'/>
</Group>
<Client name='foo.example.com'>
<Group name='oracle-server'/>
<Group name='apache-server'/>
</Client>
</Groups>
A Group tag that does not contain any child tags is a declaration of
membership; a Group or Client tag that does contain children is a
conditional. So the example above does not assign either the
``rhel5`` or ``rhel6`` groups to machines in the ``mail-server``
group, but conditionally assigns the ``sendmail-server`` or
``postfix-server`` groups depending on the OS of the client.
(Presumably in this example the OS groups are set by a probe.)
Consequently, a client that is RHEL 5 and a member of the
``mail-server`` profile group would also be a member of the
``apache-server``, ``nfs-client``, ``server``, and ``sendmail-server``
groups; a RHEL 6 client that is a member of the ``mail-server``
profile group would be a member of the ``apache-server``,
``nfs-client``, ``server``, and ``postfix-server`` groups.
Client tags in `groups.xml`_ allow you to supplement the profile
group declarations in `clients.xml`_ and/or client group assignments
with the :ref:`server-plugins-grouping-grouppatterns` plugin. They
should be used sparingly. (They are more useful when you are using
the database backend for client records.)
You can also declare that a group should be negated; this allows you
to set defaults and override them efficiently. Negation is applied
after other group memberships are calculated, so it doesn't matter how
many times a client is assigned to a group or how many times it is
negated; a single group negation is sufficient to remove a client from
that group. For instance, in the following example,
``foo.example.com`` is **not** a member of ``selinux-enabled``, even
though it is a member of the ``foo-server`` and ``every-server``
groups:
.. code-block:: xml
<Groups>
<Group name="foo-server">
<Group name="apache-server"/>
<Group name="selinux-enabled"/>
</Group>
<Group name="apache-server">
<Group name="selinux-enabled"/>
</Group>
<Group name="every-server">
<Group name="selinux-enabled"/>
</Group>
<Client name="foo.example.com">
<Group name="selinux-enabled" negate="true"/>
</Client>
.. note::
Nested Group conditionals, Client tags, and negated Group tags are
all new in 1.3.0.
.. xml:schema:: metadata.xsd
Metadata Caching
================
.. versionadded:: 1.3.0
Client metadata can be cached in order to improve performance. This
is particularly important if you have lots of templates that use
metadata from other clients (e.g., with the `MetadataQuery`_ interface
described below. See :ref:`server-caching` for a full description of
the caching features available.
.. _server-plugins-grouping-metadata-clientmetadata:
ClientMetadata
==============
A special client metadata class is available to
:ref:`server-plugins-generators-cfg-genshi` and
:ref:`server-plugins-generators-cfg-cheetah`.
.. autoclass:: Bcfg2.Server.Plugins.Metadata.ClientMetadata
MetadataQuery
-------------
.. autoclass:: Bcfg2.Server.Plugins.Metadata.MetadataQuery
|
