sampledoc

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:
    • 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)[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

Table Of Contents

Previous topic

Ldap

Next topic

Bundler

This Page