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>

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.

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)

inGroup(group)[source]

Test to see if client is a member of group.

Returns:bool
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