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.
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:
<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>
- schema clients.xsd¶
- Bcfg2 client list schema
- element Clients¶
-
- Attributes:
Name Description Values Required Default version
Client schema versionstring
No None - Child elements:
- element Client¶
-
- Attributes:
Name Description Values Required Default name
Hostname of client. This needs to be the name (probably FQDN) returned by a reverse lookup on the connecting IP address.string
Yes None profile
Profile group name to associate this client with.string
Yes None address
Establishes an extra IP address that resolves to this client.string
No None auth
Authentication mode for the client. See Authentication for details on the values available.cert+password
|bootstrap
|cert
No cert+password
floating
Allows requests to come from any IP address, rather than requiring requests to come from an IP associated with this client. Note that, since this forces the Bcfg2 server to trust any connection that claims to be from this hostname, it can introduce security issues.true
|false
No false
location
Deprecated. Usefloating
instead.string
No None password
Establishes a per-client password that can be used instead of the global password.string
No None pingable
Deprecated.string
No None pingtime
Deprecated.string
No None secure
Requires the use ofpassword
for this client.true
|false
No false
uuid
Establishes a name for this cilent that can be used to bypass dns-based client resolution.string
No None version
The version of the Bcfg2 client running on this machine. You should not have to set this manually, but can let the Bcfg2 server set it automatically.token
No None - Child elements:
- element Alias¶
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
Clients Database¶
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:
- 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
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.
groups.xml¶
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.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 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>
Negated groups can also be used to declare other Group assignments, but not to declare Bundle assignments.
Note
Nested Group conditionals, Client tags, and negated Group tags are all new in 1.3.0.
- schema metadata.xsd¶
- Bcfg2 schema for declaring groups and associating groups with bundles.
- element Groups¶
-
- Attributes:
Name Description Values Required Default origin
URI of master version (for common repository)anyURI
No None revision
Master version control revisionstring
No None version
Group schema versionstring
No None - Child elements:
- element Group¶
-
- Attributes:
Name Description Values Required Default name
Name of the groupstring
Yes None category
Assign the group to the given category. A client can only be a member of one group in a given category.string
No None default
Set as the profile to use for clients that are not associated with any profile explicitly in clients.xml. Settingdefault
totrue
requires settingprofile
totrue
as well.true
|false
No false
negate
When the Group tag is used as a conditional, only apply the child elements if the named group does not match. When the Group tag is used as a declaration, do not apply the named group to matching clients.true
|false
No false
profile
Mark the group as a profile, which allows a client to be directly associated with this group in clients.xml.true
|false
No false
public
Mark the group as public, which allows any client to assert membership in the group withbcfg2 -p
.true
|false
No false
- Child elements:
xi:include
Metadata Caching¶
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.
ClientMetadata¶
A special client metadata class is available to Genshi Templates and Cheetah Templates.
-
class
Bcfg2.Server.Plugins.Metadata.
ClientMetadata
(client, profile, groups, bundles, aliases, addresses, categories, uuid, password, version, query)[source]¶ Bases:
object
This object contains client metadata.
-
addresses
= None¶ A list of all addresses this client is known by
-
aliases
= None¶ A list of all client aliases
-
bundles
= None¶ The set of all bundles this client gets
-
categories
= None¶ A dict of categories of this client’s groups. Keys are category names, values are corresponding group names.
-
connectors
= None¶ Connector plugins known to this client
-
group_in_category
(category)[source]¶ Return the group in the given category that the client is a member of, or an empty string.
Returns: string
-
groups
= None¶ A list of groups this client is a member of
-
hostname
= None¶ The client hostname (as a string)
-
password
= None¶ The Bcfg2 password for this client
-
profile
= None¶ The client profile (as a string)
-
query
= None¶ A
Bcfg2.Server.Plugins.Metadata.MetadataQuery
object for this client.
-
uuid
= None¶ The UUID identifier for this client
-
version
= None¶ The version of the Bcfg2 client this client is running, as a string
-
version_info
= None¶ The version of the Bcfg2 client this client is running, as a
Bcfg2.version.Bcfg2VersionInfo
object.
-
MetadataQuery¶
-
class
Bcfg2.Server.Plugins.Metadata.
MetadataQuery
(by_name, get_clients, by_groups, by_profiles, all_groups, all_groups_in_category)[source]¶ Bases:
object
This class provides query methods for the metadata of all clients known to the Bcfg2 server, without being able to modify that data.
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.-
all
()[source]¶ Get a list of all
Bcfg2.Server.Plugins.Metadata.ClientMetadata
objects.Returns: list of Bcfg2.Server.Plugins.Metadata.ClientMetadata
-
all_clients
= None¶ Get all known client hostnames.
Returns: list of strings
-
all_groups
= None¶ Get all known group names.
Returns: list of strings
-
all_groups_in_category
= None¶ Get the names of all groups in the given category.
Parameters: category (string) – The category to query for groups that belong to it. Returns: list of strings
-
by_groups
(groups)[source]¶ Get a list of
Bcfg2.Server.Plugins.Metadata.ClientMetadata
objects that are in all given groups.Parameters: groups (list) – The groups to check clients for membership in. Returns: list of Bcfg2.Server.Plugins.Metadata.ClientMetadata objects
-
by_name
= None¶ Get
Bcfg2.Server.Plugins.Metadata.ClientMetadata
object for the given hostname.Returns: Bcfg2.Server.Plugins.Metadata.ClientMetadata
-
by_profiles
(profiles)[source]¶ Get a list of
Bcfg2.Server.Plugins.Metadata.ClientMetadata
objects that have any of the given groups as their profile.Parameters: profiles (list) – The profiles to check clients for membership in. Returns: list of Bcfg2.Server.Plugins.Metadata.ClientMetadata objects
-
names_by_groups
= None¶ Get a list of hostnames of clients that are in all given groups.
Parameters: groups (list) – The groups to check clients for membership in Returns: list of strings
-
names_by_profiles
= None¶ Get a list of hostnames of clients whose profile matches any given profile group.
Parameters: profiles (list) – The profiles to check clients for membership in. Returns: list of strings
-