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
|
.. -*- mode: rst -*-
.. _server-plugins-generators-cfg:
===
Cfg
===
The Cfg plugin provides a repository to describe configuration file
contents for clients. In its simplest form, the Cfg repository is just a
directory tree modeled off of the directory tree on your client machines.
The Cfg Repository
==================
The Cfg plugin is enabled by including **Cfg** on the **plugins** line of
the **[server]** section of your Bcfg2 server config file. The repository
itself lives in ``/var/lib/bcfg2/Cfg``, assuming you are using the default
repository location of ``/var/lib/bcfg2``. The contents of this directory
are a series of directories corresponding to the real-life locations of
the files on your clients, starting at the root level. For example::
lueningh@tg-prez:~/bcfg2/repository> ls Cfg
bin/ boot/ etc/ opt/ root/ usr/ var/
Specific config files go in like-named directories in this
heirarchy. For example the password file, ``/etc/passwd``, goes in
``Cfg/etc/passwd/passwd``, while the ssh pam module config file,
``/etc/pam.d/sshd``, goes in ``Cfg/etc/pam.d/sshd/sshd``. The reason
for the like-name directory is to allow multiple versions of each file
to exist, as described below. Note that these files are exact copies of
what will appear on the client machine - no templates, XML wrappers, etc.
Group-Specific Files
====================
It is often that you want one version of a config file for all of your
machines except those in a particular group. For example, ``/etc/fstab``
should look alike on all of your desktop machines, but should be
different on your file servers. Bcfg2 can handle this case through use
of group-specific files.
As mentioned above, all Cfg entries live in like-named directories
at the end of their directory tree. In the case of fstab, the file at
``Cfg/etc/fstab/fstab`` will be handed out by default to any client that
asks for a copy of ``/etc/fstab``. Group-specific files are located in
the same directory and are named with the syntax::
/path/to/filename/filename.GNN_groupname
in which **NN** is a priority number where **00** is lowest and
**99** is highest, and **groupname** is the name of a group defined in
``Metadata/groups.xml``. Back to our fstab example, we might have a
``Cfg/etc/fstab/`` directory that looks like::
fstab
fstab.G50_server
fstab.G99_fileserver
By default, clients will receive the plain fstab file when they request
``/etc/fstab``. Any machine that is in the **server** group, however, will
instead receive the ``fstab.G50_server`` file. Finally, any machine that
is in the **fileserver** group will receive the ``fstab.G99_fileserver``
file, even if they are also in the **server** group.
Host-Specific Files
===================
Similar to the case with group-specific files, there are cases where
a specific machine should have a different version of a file than all
others. This can be accomplished with host-specific files. The format
of a host-specific file name is::
/path/to/filename/filename.H_host.example.com
Host-specific files have a higher priority than group specific
files. Again, the fstab example::
fstab
fstab.G50_server
fstab.G99_fileserver
fstab.H_host.example.com
In this case, *host.example.com* will always get the host-specific
version, even if it is part of the **server** or **fileserver** (or both)
classes.
.. note::
If you have the ability to choose between using a group-specific and a
host-specific file, it is almost always best to use a group-specific
one. That way if a hostname changes or an extra copy of a particular
client is built, it will get the same changes as the original.
Deltas
======
Bcfg2 has finer grained control over how to deliver configuration
files to a host. Let's say we have a Group named file-server. Members
of this group need the exact same ``/etc/motd`` as all other hosts except
they need one line added. We could copy motd to ``motd.G01_file-server``,
add the one line to the Group specific version and be done with it,
but we're duplicating data in both files. What happens if we need to
update the motd? We'll need to remember to update both files then. Here's
where deltas come in. A delta is a small change to the base file. There
are two types of deltas: cats and diffs. The cat delta simply adds or
removes lines from the base file. The diff delta is more powerful since
it can take a unified diff and apply it to the base configuration file
to create the specialized file. Diff deltas should be used very sparingly.
Cat Files
---------
Continuing our example for cat files, we would first create a file named
``motd.G01_file-server.cat``. The .cat suffix designates that the file is
a diff. We would then edit that file and add the following line::
+This is a file server
The **+** at the begining of the file tells Bcfg2 that the line should be
appended to end of the file. You can also start a line with **-** to tell
Bcfg2 to remove that exact line wherever it might be in the file. How do
we know what base file Bcfg2 will choose to use to apply a delta? The
same rules apply as before: Bcfg2 will choose the highest priority,
most specific file as the base and then apply deltas in the order of
most specific and then increasing in priority. What does this mean in
real life. Let's say our machine is a web server, mail server, and file
server and we have the following configuration files::
motd
motd.G01_web-server
motd.G01_mail-server.cat
motd.G02_file-server.cat
motd.H_foo.example.cat
If our machine isn't *foo.example.com* then here's what would happen:
Bcfg2 would choose ``motd.G01_web-server`` as the base file. It is
the most specific base file for this host. Bcfg2 would apply the
``motd.G01_mail-server.cat`` delta to the ``motd.G01_web-server``
base file. It is the least specific delta. Bcfg2 would then apply the
``motd.G02_file-server.cat`` delta to the result of the delta before
it. If our machine is foo.example.com then here's what would happen:
Bcfg2 would choose ``motd.G01_web-server`` as the base file. It
is the most specific base file for this host. Bcfg2 would apply the
``motd.H_foo.example.com.cat`` delta to the ``motd.G01_web-server`` base
file. The reason the other deltas aren't applied to *foo.example.com*
is because a **.H_** delta is more specific than a **.G##_** delta. Bcfg2
applies all the deltas at the most specific level.
Info files
==========
By default, Cfg writes files to the filesystem with owner *root*, group
*root*, and mode *644* (read and write for owner, read only for group
and other). These options, and a few others, can be overridden through
use of ``:info`` or ``info`` files. Each config file directory can have
a ``:info`` or ``info`` file if needed. The possible fields in an info
file are:
+-----------+-------------------+------------------------------------------------------+---------+
| Field | Possible values | Description | Default |
+===========+===================+======================================================+=========+
| owner: | Any valid user | Sets owner of the file | root |
+-----------+-------------------+------------------------------------------------------+---------+
| group: | Any valid group | Sets group of the file | root |
+-----------+-------------------+------------------------------------------------------+---------+
| perms: | Numeric file mode | Sets the permissions of the file | 0644 |
+-----------+-------------------+------------------------------------------------------+---------+
| encoding: | ascii | base64 | Encoding of the file. Use base64 for non-ASCII files | ascii |
+-----------+-------------------+------------------------------------------------------+---------+
| paranoid: | yes | no | Backup file before replacement? | no |
+-----------+-------------------+------------------------------------------------------+---------+
A sample info file for CGI script on a web server might look like::
owner: www
group: www
perms: 0755
Back to the fstab example again, our final ``Cfg/etc/fstab/`` directory
might look like::
:info
fstab
fstab.G50_server
fstab.G99_fileserver
fstab.H_host.example.com
info.xml files
==============
info.xml files add the ability to specify different sets of file metadata
on a group by group basis. These files are XML, and work similarly
to those used by :ref:`Rules <server-plugins-generators-rules>` or
:ref:`Pkgmgr <server-plugins-generators-pkgmgr>`.
The following specifies a different global set of permissions
(root/sys/0651) than on clients in group webserver (root/root/0652)
.. code-block:: xml
<FileInfo>
<Group name='webserver'>
<Info owner='root' group='root' perms='0652'/>
</Group>
<Info owner='root' group='sys' perms='0651'/>
</FileInfo>
|
