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
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
|
.. -*- mode: rst -*-
.. _xml-features:
=====================
Common XML Features
=====================
Most of the XML files in Bcfg2 have a common set of features that are
supported. These are described in some detail below, and a precise
rundown of which features are supported by which files is provided.
.. _xml-group-client-tags:
Group and Client tags
=====================
These allow the portions of an XML document inside a Client or Group
tag to only apply to the given client group. That is, they can be
thought of as conditionals, where the following are roughly equivalent:
.. code-block:: xml
<Group name="group1">
<Path name="/etc/foo.conf"/>
</Group>
And::
If client is a member of group1 then
Manage the abstract path "/etc/foo.conf"
Nested Group and Client tags are conjunctive (logical ``AND``). For
instance, the following are roughly equivalent:
.. code-block:: xml
<Group name="group1">
<Client name="foo.example.com">
<Package name="bar"/>
</Client>
<Package name="baz"/>
</Group>
And::
If client is a member of group1 and has hostname "foo.example.com" then
Manage the abstract package "bar"
If client is a member of group1 then
Manage the abstract package "baz"
There is no convenient ``else``; you must specify all conditions
explicitly. To do this, Group and Client tags may be negated, as in:
.. code-block:: xml
<Group name="group1">
<Service name="foo"/>
</Group>
<Group name="group1" negate="true">
<Service name="bar"/>
</Group>
This is roughly equivalent to::
If client is a member of group1 then
Manage the abstract service "foo"
If client is not a member of group 1 then
Manage the abstract service "bar"
Or, more compactly:
If client is a member of group1 then
Manage the abstract service "foo"
Else
Manage the abstract service "bar"
As an example, consider the following :ref:`bundle
<server-plugins-structures-bundler-index>`:
.. code-block:: xml
<Bundle>
<Path name='/etc/ssh/ssh_host_dsa_key'/>
<Path name='/etc/ssh/ssh_host_rsa_key'/>
<Path name='/etc/ssh/ssh_host_dsa_key.pub'/>
<Path name='/etc/ssh/ssh_host_rsa_key.pub'/>
<Path name='/etc/ssh/ssh_host_key'/>
<Path name='/etc/ssh/ssh_host_key.pub'/>
<Path name='/etc/ssh/sshd_config'/>
<Path name='/etc/ssh/ssh_config'/>
<Path name='/etc/ssh/ssh_known_hosts'/>
<Group name='rpm'>
<Package name='openssh'/>
<Package name='openssh-askpass'/>
<Service name='sshd'/>
<Group name='fedora' >
<Group name='fedora14' negate='true'>
<Package name='openssh-clients'/>
</Group>
<Package name='openssh-server'/>
</Group>
</Group>
<Group name='deb'>
<Package name='ssh'/>
<Service name='ssh'/>
</Group>
<Client name='trust.example.com'>
<Path name='/etc/ssh/shosts.equiv'/>
</Client>
</Bundle>
In this bundle, most of the entries are common to all systems. Clients
in group ``deb`` get one extra package and service, while clients in
group ``rpm`` get two extra packages and an extra service. In
addition, clients in group ``fedora`` *and* group ``rpm`` get one
extra package entries, unless they are not in the ``fedora14`` group,
in which case, they get an extra package. The client
``trust.example.com`` gets one extra file that is not distributed to
any other clients.
+------------------------+-----------------------------------+
| Group/Hostname | Entry |
+========================+===================================+
| all | ``/etc/ssh/ssh_host_dsa_key`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_rsa_key`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_dsa_key.pub`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_rsa_key.pub`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_key`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_key.pub`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/sshd_config`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_config`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_known_hosts`` |
+------------------------+-----------------------------------+
| ``rpm`` | Package ``openssh`` |
+------------------------+-----------------------------------+
| ``rpm`` | Package ``openssh-askpass`` |
+------------------------+-----------------------------------+
| ``rpm`` | Service ``sshd`` |
+------------------------+-----------------------------------+
| ``rpm`` AND ``fedora`` | Package ``openssh-server`` |
+------------------------+-----------------------------------+
| ``rpm`` AND ``fedora`` | Package ``openssh-clients`` |
| AND NOT ``fedora14`` | |
+------------------------+-----------------------------------+
| ``deb`` | Package ``ssh`` |
+------------------------+-----------------------------------+
| ``deb`` | Service ``ssh`` |
+------------------------+-----------------------------------+
| ``trust.example.com`` | ``/etc/ssh/shosts.equiv`` |
+------------------------+-----------------------------------+
.. _xml-genshi-templating:
Genshi templating
=================
Genshi XML templates allow you to use the `Genshi
<http://genshi.edgewall.org>`_ templating system to dynamically
generate XML file content for a given client. Genshi templating can
be enabled on a file by adding the Genshi namespace to the top-level
tag, e.g.:
.. code-block:: xml
<Bundle xmlns:py="http://genshi.edgewall.org/">
Several variables are pre-defined inside Genshi XML templates:
+-------------+--------------------------------------------------------+
| Name | Description |
+=============+========================================================+
| metadata | :ref:`Client metadata |
| | <server-plugins-grouping-metadata-clientmetadata>` |
+-------------+--------------------------------------------------------+
| repo | The path to the Bcfg2 repository on the filesystem |
+-------------+--------------------------------------------------------+
.. note::
``<Group>`` and ``<Client>`` tags can be used inside templates as
of Bcfg2 1.2, but they do not behave the same as using a Genshi
conditional, e.g.::
<py:if test="'groupname' in metadata.groups">
</py:if>
The conditional is evaluated when the template is rendered, so
code inside the conditional is not executed if the conditional
fails. A ``<Group>`` tag is evaluated *after* the template is
rendered, so code inside the tag is always executed. This is an
important distinction: if you have code that will fail on some
groups, you *must* use a Genshi conditional, not a ``<Group>``
tag. The same caveats apply to ``<Client>`` tags.
.. _xml-genshi-reference:
Genshi XML Template Reference
-----------------------------
The Genshi XML templating language is described in depth at `Genshi
<http://genshi.edgewall.org>`_. The XML schema reference follows.
Genshi Tags
~~~~~~~~~~~
.. xml:group:: genshiElements
:namespace: py
Genshi Attributes
~~~~~~~~~~~~~~~~~
.. xml:attributegroup:: genshiAttrs
:namespace: py
.. _xml-encryption:
Encryption
==========
You can encrypt data in XML files to protect that data from other
people who need access to the repository. The data is decrypted
transparently on-the-fly by the server.
.. note::
This feature is *not* intended to secure the files against a
malicious attacker who has gained access to your Bcfg2 server, as
the encryption passphrases are held in plaintext in
``bcfg2.conf``. This is only intended to make it easier to use a
single Bcfg2 repository with multiple admins who should not
necessarily have access to each other's sensitive data.
XML files are encrypted on a per-element basis; that is, rather than
encrypting the whole file, only the character content of individual
elements is encrypted. This makes it easier to track changes to the
file in a VCS, and also lets unprivileged users work with the other
data in the file. Only character content of an element can be
encrypted; attribute content and XML elements themselves cannot be
encrypted.
By default, decryption is *strict*; that is, if any element cannot be
decrypted, parsing of the file is aborted. See
:ref:`server-encryption-lax-strict` for information on changing this
on a global or per-file basis.
To encrypt or decrypt a file, use :ref:`bcfg2-crypt`.
See :ref:`server-encryption` for more details on encryption in Bcfg2
in general.
XInclude
========
.. versionadded:: 0.9.0
`XInclude <http://www.w3.org/TR/xinclude/>`_ is a W3C specification
for the inclusion of external XML documents into XML source files,
allowing complex definitions to be split into smaller, more manageable
pieces. For instance, in the :ref:`server-plugins-grouping-metadata`
``groups.xml`` file, you might do:
.. code-block:: xml
<Groups xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="my-groups.xml" />
<xi:include href="their-groups.xml" />
</Groups>
To enable XInclude on a file, you need only add the XInclude namespace
to the top-level tag.
XInclude can only include complete, well-formed XML files. In some
cases, it may not be entirely obvious or intuitive how to structure
such an included file to conform to the schema, although in general
the included files should be structure exactly like the parent file.
Feature Matrix
==============
+-------------------------------------------------+--------------+--------+------------+------------+
| File | Group/Client | Genshi | Encryption | XInclude |
+=================================================+==============+========+============+============+
| :ref:`ACL ip.xml <server-plugins-misc-acl>' | No | No | No | Yes |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`ACL metadata.xml | Yes | Yes | Yes | Yes |
| <server-plugins-misc-acl>' | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Bundler | Yes | Yes | Yes | Yes |
| <server-plugins-structures-bundler-index>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`info.xml <server-info>` | Yes [#f1]_ | Yes | Yes | Yes |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`privkey.xml and pubkey.xml | Yes | Yes | Yes | Yes [#f2]_ |
| <server-plugins-generators-cfg-sshkeys>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`authorizedkeys.xml | Yes | Yes | Yes | Yes |
| <server-plugins-generators-cfg-sshkeys>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Decisions | Yes | Yes | Yes | Yes |
| <server-plugins-generators-decisions>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Defaults | Yes | Yes | Yes | Yes |
| <server-plugins-structures-defaults>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`FileProbes | Yes | Yes | Yes | Yes |
| <server-plugins-probes-fileprobes>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`GroupPatterns | No | No | No | Yes |
| <server-plugins-grouping-grouppatterns>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Metadata clients.xml | No | No | No | Yes |
| <server-plugins-grouping-metadata-clients-xml>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Metadata groups.xml | Yes [#f3]_ | No | No | Yes |
| <server-plugins-grouping-metadata-groups-xml>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`NagiosGen | Yes | Yes | Yes | Yes |
| <server-plugins-generators-nagiosgen>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Packages | Yes | Yes | Yes | Yes |
| <server-plugins-generators-packages>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Pkgmgr | Yes | No | No | No |
| <server-plugins-generators-pkgmgr>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Properties | Yes [#f4]_ | Yes | Yes | Yes |
| <server-plugins-connectors-properties>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Rules <server-plugins-generators-rules>` | Yes | Yes | Yes | Yes |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`SSLCA cert.xml and key.xml | Yes | Yes | Yes | Yes |
| <server-plugins-generators-sslca>` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
.. rubric:: Footnotes
.. [#f1] ``info.xml`` also supports conditional Path tags; see
:ref:`server-info` for more.
.. [#f2] XInclude is supported, but the schema has not been modified
to allow including files that are structured exactly like the
parent. You may need to read the schema to understand how to
use XInclude properly.
.. [#f3] The semantics of Group tags in ``groups.xml`` is slightly
different; see
:ref:`server-plugins-grouping-metadata-groups-xml` for
details.
.. [#f4] Group and Client tags in XML Properties are not automatic by
default; they can be resolved by use of either the
``Match()`` or ``XMLMatch()`` methods, or by use of the
:ref:`server-plugins-connectors-properties-automatch`
feature. See :ref:`server-plugins-connectors-properties-xml`
for details.
|
