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.
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.
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:
<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>
Bcfg2 client list schema
Name | Description | Values | Required | Default |
---|---|---|---|---|
version |
|
string | No | None |
Name |
Description |
Values |
Required |
Default |
---|---|---|---|---|
name |
|
Yes |
None |
|
profile |
|
Yes |
None |
|
address |
|
No |
None |
|
auth |
|
cert+password | bootstrap | cert |
No |
cert+password |
floating |
|
true | false |
No |
false |
location |
|
No |
None |
|
password |
|
No |
None |
|
pingable |
|
No |
None |
|
pingtime |
|
No |
None |
|
secure |
|
true | false |
No |
false |
uuid |
|
No |
None |
|
version |
|
No |
None |
Alias allows you to set alternative hostname and IP address pairs that also resolve to this client.
For detailed information on client authentication see Authentication
New in version 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:
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 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 Global Server Database Settings.
The clients.xml-based model remains the default.
The groups.xml file contains Group and Profile definitions. Here’s a simple groups.xml file:
<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.eample.com'>
<Group name='oracle-server'/>
<Group name='apache-server'/>
</Client>
</Groups>
A Group or Client 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 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:
<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.
Bcfg2 schema for declaring groups and associating groups with bundles.
Name | Description | Values | Required | Default |
---|---|---|---|---|
origin |
|
anyURI | No | None |
revision |
|
string | No | None |
version |
|
string | No | None |
Name |
Description |
Values |
Required |
Default |
---|---|---|---|---|
name |
|
Yes |
None |
|
category |
|
No |
None |
|
default |
|
true | false |
No |
false |
negate |
|
true | false |
No |
false |
profile |
|
true | false |
No |
false |
public |
|
true | false |
No |
false |
xi:include
New in version 0.9.0.
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. 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:
<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.
The metadata plugin includes client-side probing functionality. This is fully documented here.
New in version 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 Server-side Caching for a full description of the caching features available.
A special client metadata class is available to Genshi Templates and Cheetah Templates.
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 is a member of ‘category’, otherwise ‘’ | String |
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 listed groups | List of ClientMetadata |
by_profiles(client) | Get ClientMetadata objects for clients whose profile matches any listed profile group | List of ClientMetadata |
names_by_groups(groups) | Get the names of all clients in all listed groups | List of strings |
names_by_profiles(profiles) | Get the names of clients whose profile matches any listed profile group | List of strings |
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 |