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 version	string	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. Use floating 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 of password 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.

    Attributes:

    Name	Description	Values	Required	Default
    name	Hostname of the alternative client name-address pair.	string	Yes	None
    address	IP address of the alternative client name-address pair.	string	No	None

• 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>

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 revision	string	No	None
version	Group schema version	string	No	None

Child elements:

• element Group

  Attributes:

  Name	Description	Values	Required	Default
  name	Name of the group	string	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. Setting default to true requires setting profile to true 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 with bcfg2 -p.	true | false	No	false

  Child elements:

  • element Bundle

    Attributes:

    Name	Description	Values	Required	Default
    name	The bundle name	string	Yes	None

  • Group

  • element Client

    Attributes:

    Name	Description	Values	Required	Default
    name	The name of the client.	string	Yes	None
    negate	Only apply the child tags if the named client does not match.	true | false	No	false

    Child elements:

    • Bundle
    • Group
    • Client
    • Groups

  • Groups

• Client

• Groups

• xi:include

XInclude

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 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.

You can also optionally include a file that may or may not exist with the fallback tag:

<Groups xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="my-groups.xml"/>
  <xi:include href="their-groups.xml"><xi:fallback/></xi:include>
</Groups>

In this case, if their-groups.xml does not exist, no error will be raised and everything will work fine. (You can also use fallback to include a different file, or explicit content in the case that the parent include does not exist.)

Wildcard XInclude

New in version 1.3.1.

Bcfg2 supports an extension to XInclude that allows you to use shell globbing in the hrefs. (Stock XInclude doesn’t support this, since the href is supposed to be a URL.)

For instance:

<Groups xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="groups/*.xml"/>
</Groups>

This would include all *.xml files in the groups subdirectory.

Note that if a glob finds no files, that is treated the same as if a single included file does not exist. You should use the fallback tag, described above, if a glob may potentially find no files.

Probes

The metadata plugin includes client-side probing functionality. This is fully documented here.

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)

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)

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)

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)

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()

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)

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)

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