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
|
.. -*- 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 (except when using genshi templating --
see below).
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.
Genshi Templates
================
Genshi templates maybe used for entries as well. Any file ending in .genshi
will be processed using the new template style (like .newtxt in the TGenshi
plugin). Templates can be host and group specific as well. Deltas will not
be processed for any genshi base file.
.. note::
If you are using genshi templating in combination with host-specific
or group-specific files, you will need to ensure that the ``.genshi``
extensions is at the **end** of the filename. Using the examples
from above for *host.example.com* and group *server* you would have
the following::
Cfg/etc/fstab/fstab.H_host.example.com.genshi
Cfg/etc/fstab/fstab.G50_server.genshi
File permissions
================
File permissions for entries handled by Cfg are controlled via the use
of :ref:`server-info` files. Note that you **cannot** use both a
Permissions entry and a Path entry to handle the same file.
|
