Cfg ¶

complexType PassphraseType¶

Specify the private key passphrase.

Attributes:

Name	Description	Values	Required	Default
`encrypted`	The name of the passphrase to use to encrypt this private key on the filesystem (in Bcfg2).	`string`	No	None

Attribute groups:

py:genshiAttrs

Text content:

string

complexType PrivateKeyParamsType¶

Specify parameters for creating the private key

Attributes:

Name	Description	Values	Required	Default
`bits`	Number of bits in the key. See ssh-keygen(1) for defaults.	`positiveInteger`	No	None
`type`	Key type to create.	`rsa` \| `dsa`	No	`rsa`

Attribute groups:

py:genshiAttrs

complexType PrivateKeyGroupType¶

A PrivateKeyGroupType is a tag used to provide logic. Child entries of a PrivateKeyGroupType tag only apply to machines that match the condition specified – either membership in a group, or a matching client name. negate can be set to negate the sense of the match.

Attributes:

Name	Description	Values	Required	Default
`name`	The name of the client or group to match on. Child entries will only apply to this client or group (unless `negate` is set).	`string`	No	None
`negate`	Negate the sense of the match, so that child entries only apply to a client if it is not a member of the given group or does not have the given name.	`true` \| `false`	No	None

Attribute groups:

py:genshiAttrs

Child elements:

Element groups:

group py:genshiElements¶

Most Genshi templating directives can be used either as standalone elements or as attributes on existing elements. This element group defines the standalone tags.

Elements:

element py:with¶

Type: py:withType

element py:replace¶

element py:choose¶

element py:for¶

Type: py:forType

element py:if¶

Type: py:ifType

element py:match¶

element py:def¶

Type: py:defType

complexType py:withType¶

with directive

Attributes:

Name	Description	Values	Required	Default
`py:vars`	A semicolon-delimited list of variables to define and their values.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:replaceType¶

replace directive

Attributes:

Name	Description	Values	Required	Default
`py:value`	The value to replace the contents with.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:chooseType¶

choose directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	If `test` is set, the child `py:when` directives are tested for equality to the value of the expression.	`string`	No	None

Child elements:

element py:when¶

The when directive is used inside py:chooseType or choose to handle a single specific condition.

Type: py:ifType
element py:otherwise¶

Type: py:otherwiseType

Text content:

Any

complexType py:forType¶

for directive

Attributes:

Name	Description	Values	Required	Default
`py:each`	The loop iterator	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:ifType¶

if directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	The statement giving the value to test	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:matchType¶

match directive

Attributes:

Name	Description	Values	Required	Default
`py:path`	XPath expression to search for in the template.	`string`	Yes	None
`py:buffer`	Whether the matched content should be buffered in memory. Buffering can improve performance a bit at the cost of needing more memory during rendering. Buffering is required for match templates that contain more than one invocation of the `select()` function. If there is only one call, and the matched content can potentially be very long, consider disabling buffering to avoid excessive memory use.	`true` \| `false`	No	`true`
`py:once`	Whether the engine should stop looking for more matching elements after the first match. Use this on match templates that match elements that can only occur once in the stream, such as the <head> or <body> elements in an HTML template, or elements with a specific ID.	`true` \| `false`	No	`false`
`py:recursive`	Whether the match template should be applied to its own output. Note that once implies non-recursive behavior, so this attribute only needs to be set for match templates that don’t also have once set.	`true` \| `false`	No	`true`

Any arbitrary child elements allowed

Text content:

Any

complexType py:defType¶

def directive

Attributes:

Name	Description	Values	Required	Default
`py:function`	The function prototype	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:otherwiseType¶

The otherwise directive is used inside py:chooseType or choose to handle all conditions not handled by a py:when.

Text content:: Any

See Bcfg2 Data Encryption for more details on encryption in Bcfg2 in general.

`pubkey.xml`¶

pubkey.xml only ever contains a single line:

<PublicKey/>

element PublicKey¶

Top-level tag for flagging a generated SSH public key.

It acts only as a flag to Bcfg2 that a key pair should be generated, if none exists, using the associated privkey.xml file. The path to privkey.xml is determined by removing .pub from the directory containing pubkey.xml. I.e., if you create /var/lib/bcfg2/Cfg/home/foo/.ssh/id_rsa.pub/pubkey.xml, then Bcfg2 will use /var/lib/bcfg2/Cfg/home/foo/.ssh/id_rsa/privkey.xml to create the key pair.

Use of pubkey.xml is optional, but is recommended. If you do not use pubkey.xml files, you may encounter two problems:

On the first Bcfg2 client run on a given client, the private keys may be present but the public keys may not be. This will be fixed by running bcfg2 again.
If you are including an automatically created public key in authorized_keys, it will not be created until the client the key is for requests the key pair.

As an example of this latter scenario, suppose that your authorized_keys.xml allows access to foo.example.com from /root/.ssh/id_rsa.pub for bar.example.com. If bar.example.com has not run the Bcfg2 client, then no key pair will have been generated, and generating the foo.example.com authorized_keys file will create a warning. But if you create Cfg/root/.ssh/id_rsa.pub/pubkey.xml, then building authorized_keys for foo.example.com will create root’s keypair for bar.example.com.

Note

In order to use pubkey.xml, there must be a corresponding privkey.xml. You cannot, for instance, populate a directory with manually-generated private SSH keys, drop pubkey.xml in the related public key directory, and expect Bcfg2 to generate the public keys. It will not.

Examples¶

privkey.xml can, at its simplest, be very simple indeed:

<PrivateKey/>

This will create a private key with all defaults. Or it can be more complex:

<PrivateKey category="environment">
  <Params bits="1024" type="dsa"/>
  <Group name="secure">
    <Passphrase encrypted="secure">U2FsdGVkX19xACol83uyPELP94s4CmngD12oU6PLLuE=</Passphrase>
  </Group>
</PrivateKey>

This creates a 1024-bit DSA key for each group in the environment category, and keys for clients in the secure group will be protected with the given (encrypted) passphrase.

To complete the example, assume that this file was saved at /var/lib/bcfg2/Cfg/home/foo/.ssh/id_rsa/privkey.xml. If a client in the development group, which is a group in the environment category, requests the private key, then the following files would be created:

/var/lib/bcfg2/Cfg/home/foo/.ssh/id_rsa/id_rsa.G50_development
/var/lib/bcfg2/Cfg/home/foo/.ssh/id_rsa.pub/id_rsa.pub.G50_development

/var/lib/bcfg2/Cfg/home/foo/.ssh/id_rsa.pub would be created if it did not exist.

Subsequent clients that were also members of the development environment would get the keys that have already been generated.

pubkey.xml always contains a single empty tag:

<PublicKey/>

Generating `authorized_keys`¶

authorized_keys can be automatically generated from public SSH keys that exist in the Cfg tree. The keys in question can be generated from privkey.xml, or they can be manually created.

If a key doesn’t exist when authorized_keys is generated, the key will only be created if pubkey.xml exists. If that is not the case, a warning will be produced.

To generate authorized_keys, create authorized_keys.xml, e.g.: /var/lib/bcfg2/Cfg/root/.ssh/authorized_keys/authorized_keys.xml.

`authorized_keys.xml`¶

authorized_keys.xml is structured as follows:

element AuthorizedKeys¶

Type: AuthorizedKeysType

complexType AuthorizedKeysType¶

Top-level tag for describing a generated SSH key pair.

Attributes:

Name	Description	Values	Required	Default
`lax_decryption`	Override the global lax_decryption setting in `bcfg2.conf`.	`true` \| `false`	No	None

Attribute groups:

py:genshiAttrs

Child elements:

element Allow¶

Type: AllowType
element Group¶

Type: AuthorizedKeysGroupType
element Client¶

Type: AuthorizedKeysGroupType
AuthorizedKeys

Element groups:

complexType AllowType¶

Allow access from a public key, given either as text content, or described by the attributes.

Attributes:

Name	Description	Values	Required	Default
`category`	Use a public key specific to the group in the given category, instead of the category specified in `bcfg2.conf`.	`string`	No	None
`from`	The path of the public key to allow.	`string`	No	None
`group`	Use a public key specific to the given group, instead of the public key specific to the appropriate category group of the current client.	`string`	No	None
`host`	Use a public key specific to the given host.	`string`	No	None

Attribute groups:

py:genshiAttrs

Child elements:

Group
Client
element Option¶

Type: AuthorizedKeysOptionType

Element groups:

Text content:

Any

complexType AuthorizedKeysGroupType¶

An AuthorizedKeysGroupType is a tag used to provide logic. Child entries of an AuthorizedKeysGroupType tag only apply to machines that match the condition specified – either membership in a group, or a matching client name. negate can be set to negate the sense of the match.

Attributes:

Name	Description	Values	Required	Default
`name`	The name of the client or group to match on. Child entries will only apply to this client or group (unless `negate` is set).	`string`	No	None
`negate`	Negate the sense of the match, so that child entries only apply to a client if it is not a member of the given group or does not have the given name.	`true` \| `false`	No	None

Attribute groups:

py:genshiAttrs

Child elements:

Allow
Group
Client
AuthorizedKeys

Element groups:

group py:genshiElements¶

Most Genshi templating directives can be used either as standalone elements or as attributes on existing elements. This element group defines the standalone tags.

Elements:

element py:with¶

Type: py:withType

element py:replace¶

element py:choose¶

element py:for¶

Type: py:forType

element py:if¶

Type: py:ifType

element py:match¶

element py:def¶

Type: py:defType

complexType AuthorizedKeysOptionType¶

Specify options for public key authentication and connection. See sshd(8) for details on allowable options.

Attributes:

Name	Description	Values	Required	Default
`name`	The name of the sshd option.	`string`	Yes	None
`value`	The value of the sshd option. This can be omitted for options that take no value.	`string`	No	None

complexType py:withType¶

with directive

Attributes:

Name	Description	Values	Required	Default
`py:vars`	A semicolon-delimited list of variables to define and their values.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:replaceType¶

replace directive

Attributes:

Name	Description	Values	Required	Default
`py:value`	The value to replace the contents with.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:chooseType¶

choose directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	If `test` is set, the child `py:when` directives are tested for equality to the value of the expression.	`string`	No	None

Child elements:

element py:when¶

The when directive is used inside py:chooseType or choose to handle a single specific condition.

Type: py:ifType
element py:otherwise¶

Type: py:otherwiseType

Text content:

Any

complexType py:forType¶

for directive

Attributes:

Name	Description	Values	Required	Default
`py:each`	The loop iterator	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:ifType¶

if directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	The statement giving the value to test	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:matchType¶

match directive

Attributes:

Name	Description	Values	Required	Default
`py:path`	XPath expression to search for in the template.	`string`	Yes	None
`py:buffer`	Whether the matched content should be buffered in memory. Buffering can improve performance a bit at the cost of needing more memory during rendering. Buffering is required for match templates that contain more than one invocation of the `select()` function. If there is only one call, and the matched content can potentially be very long, consider disabling buffering to avoid excessive memory use.	`true` \| `false`	No	`true`
`py:once`	Whether the engine should stop looking for more matching elements after the first match. Use this on match templates that match elements that can only occur once in the stream, such as the <head> or <body> elements in an HTML template, or elements with a specific ID.	`true` \| `false`	No	`false`
`py:recursive`	Whether the match template should be applied to its own output. Note that once implies non-recursive behavior, so this attribute only needs to be set for match templates that don’t also have once set.	`true` \| `false`	No	`true`

Any arbitrary child elements allowed

Text content:

Any

complexType py:defType¶

def directive

Attributes:

Name	Description	Values	Required	Default
`py:function`	The function prototype	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:otherwiseType¶

The otherwise directive is used inside py:chooseType or choose to handle all conditions not handled by a py:when.

Text content:: Any

Example¶

<AuthorizedKeys>
  <Group name="some_group">
    <Allow from="/root/.ssh/id_rsa.pub"/>
    <Allow from="/root/.ssh/id_rsa.pub" group="test"/>
  </Group>
  <Allow from="/root/.ssh/id_rsa.pub" host="foo.example.com"/>
  <Allow from="/home/foo_user/.ssh/id_rsa.pub">
    <Option name="command" value="/home/foo_user/.ssh/ssh_command_filter"/>
    <Option name="no-X11-forwarding"/>
  </Allow>
  <Allow>
    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDw/rgKQeARRAHK5bQQhAAe1b+gzdtqBXWrZIQ6cIaLgxqj76TwZ3DY4A6aW9RgC4zzd0p4a9MfsScUIB4+UeZsx9GopUj4U6H8Vz7S3pXxrr4E9logVLuSfOLFbI/wMWNRuOANqquLYQ+JYWKeP4kagkVp0aAWp7mH5IOI0rp0A6qE2you4ep9N/nKvHDrtypwhYBWprsgTUXXMHnAWGmyuHGYWxNYBV9AARPdAvZfb8ggtuwibcOULlyK4DdVNbDTAN1/BDBE1ve6WZDcrc386KhqUGj/yoRyPjNZ46uZiOjRr3cdY6yUZoCwzzxvm5vle6mEbLjHgjGEMQMArzM9 vendor@example.com
  </Allow>
</AuthorizedKeys>

Note

authorized_keys.xml allows you to specify the group whose public key should be allowed. This retrieves the public key specific to that group (if it exists), not the public key for all hosts in that group. This is due to the performance penalties that would be imposed by that approach.

Similarly, it is not possible to allow access from all keys for a given user (i.e., at a given path).

Hopefully, the performance concerns can be resolved in a future release and these features can be added.

SSL Keys and Certificates¶

Cfg can also create SSL keys and certs on the fly, and store the generated data in the repo so that subsequent requests do not result in repeated key/cert recreation. In the event that a new key or cert is needed, the old file can simply be removed from the repository, and the next time that host checks in, a new file will be created. If that file happens to be the key, any dependent certificates will also be regenerated.

See also Automated Bcfg2 SSL Authentication for a detailed example that uses the SSL key management feature to automate Bcfg2 certificate authentication.

Getting started¶

In order to use the SSL certificate generation feature, you must first have at least one CA configured on your system. For details on setting up your own OpenSSL based CA, please see http://www.openssl.org/docs/apps/ca.html for details of the suggested directory layout and configuration directives.

For SSL cert generation to work, the openssl.cnf (or other configuration file) for that CA must contain full (not relative) paths.

Add a section to your /etc/bcfg2.conf called sslca_foo, replacing foo with the name you wish to give your CA so you can reference it in certificate definitions. (If you only have one CA, you can name it sslca_default, and it will be the default CA for all other operations.)
Under that section, add a config option that gives the location of the openssl.cnf file for your CA.
If necessary, add a passphrase option containing the passphrase for the CA’s private key. If no passphrase is entry exists, it is assumed that the private key is stored unencrypted.
Optionally, add a chaincert option that points to the location of your ssl chaining certificate. This is used when preexisting certificate hostfiles are found, so that they can be validated and only regenerated if they no longer meet the specification. If you’re using a self signing CA this would be the CA cert that you generated. If the chain cert is a root CA cert (e.g., if it is a self-signing CA), also add an entry root_ca = true. If chaincert is omitted, certificate verification will not be performed.

Once all this is done, you should have a section in your /etc/bcfg2.conf that looks similar to the following:

[sslca_default]
config = /etc/pki/CA/openssl.cnf
passphrase = youReallyThinkIdShareThis?
chaincert = /etc/pki/CA/chaincert.crt
root_ca = true

You are now ready to create key and certificate definitions. For this example we’ll assume you’ve added Path entries for the key, /etc/pki/tls/private/localhost.key, and the certificate, /etc/pki/tls/certs/localhost.crt to a bundle.
Within the Cfg/etc/pki/tls/private/localhost.key directory, create a sslkey.xml file containing the following:
```
<KeyInfo/>
```
This will cause the generation of an SSL key when a client requests that Path. (By default, it will be a 2048-bit RSA key; see sslkey.xml for details on how to change the key type and size.)
Similarly, create sslcert.xml in Cfg/etc/pki/tls/certs/localhost.cfg/, containing the following:
```
<CertInfo>
  <Cert key="/etc/pki/tls/private/localhost.key" ca="foo"/>
</CertInfo>
```
When a client requests the cert path, a certificate will be generated using the key hostfile at the specified key location, using the CA matching the ca attribute. ie. ca="foo" will match [sslca_default] in your /etc/bcfg2.conf

The Bcfg2 bundle example contains entries to automate the process of setting up a CA.

Configuration¶

`bcfg2.conf`¶

In bcfg2.conf, you must declare your CA(s) in [sslca_<name>] sections. At least one is required. Valid options are detailed below, in Cfg Configuration.

Only the config option is required; i.e., the simplest possible CA section is:

[sslca_default]
config = /etc/pki/CA/openssl.cnf

`sslcert.xml`¶

schema sslca-cert.xsd¶

Schema for SSL Keys and Certificates sslcert.xml

element CertInfo¶

Type: CertInfoType

complexType CertInfoType¶

Top-level tag for describing an SSLCA generated certificate.

Attributes:

Name	Description	Values	Required	Default
`lax_decryption`	Override the global lax_decryption setting in `bcfg2.conf`.	`true` \| `false`	No	None

Child elements:

element Cert¶

Attributes:

Name	Description	Values	Required	Default
`key`	The full path to the key entry to use for this certificate. This is the client path; e.g., for a key defined at `/var/lib/bcfg2/SSLCA/etc/pki/tls/private/foo.key/sslkey.xml`, key should be `/etc/pki/tls/private/foo.key`.	`string`	Yes	None
`append_chain`	Append the CA chain certificate to the generated certificate (e.g., to produce a certificate in the format required by Nginx.)	`true` \| `false`	No	`false`
`c`	Override the country set in the CA config	`string`	No	None
`ca`	The name of the CA (from bcfg2.conf) to use to generate this certificate.	`string`	No	`default`
`days`	Time (in days) the certificate will be valid for.	`integer`	No	`365`
`emailaddress`	Override the email address set in the CA config	`string`	No	None
`format`	The certificate format to produce.	`pem`	No	`pem`
`l`	Override the location set in the CA config	`string`	No	None
`o`	Override the organization set in the CA config	`string`	No	None
`ou`	Override the organizational unit set in the CA config	`string`	No	None
`st`	Override the state set in the CA config	`string`	No	None

Attribute groups:

py:genshiAttrs

element Group¶

Type: SSLCACertGroupType
element Client¶

Type: SSLCACertGroupType
element subjectAltName¶

subjectAltName takes only text content, which may be the following values: string
CertInfo

Element groups:

complexType SSLCACertGroupType¶

An SSLCACertGroupType is a tag used to provide logic. Child entries of an SSLCACertGroupType tag only apply to machines that match the condition specified – either membership in a group, or a matching client name. negate can be set to negate the sense of the match.

Attributes:

Name	Description	Values	Required	Default
`name`	The name of the client or group to match on. Child entries will only apply to this client or group (unless `negate` is set).	`string`	No	None
`negate`	Negate the sense of the match, so that child entries only apply to a client if it is not a member of the given group or does not have the given name.	`true` \| `false`	No	None

Attribute groups:

py:genshiAttrs

Child elements:

Cert
Group
Client
subjectAltName
CertInfo

Element groups:

group py:genshiElements¶

Most Genshi templating directives can be used either as standalone elements or as attributes on existing elements. This element group defines the standalone tags.

Elements:

element py:with¶

Type: py:withType

element py:replace¶

element py:choose¶

element py:for¶

Type: py:forType

element py:if¶

Type: py:ifType

element py:match¶

element py:def¶

Type: py:defType

complexType py:withType¶

with directive

Attributes:

Name	Description	Values	Required	Default
`py:vars`	A semicolon-delimited list of variables to define and their values.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:replaceType¶

replace directive

Attributes:

Name	Description	Values	Required	Default
`py:value`	The value to replace the contents with.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:chooseType¶

choose directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	If `test` is set, the child `py:when` directives are tested for equality to the value of the expression.	`string`	No	None

Child elements:

element py:when¶

The when directive is used inside py:chooseType or choose to handle a single specific condition.

Type: py:ifType
element py:otherwise¶

Type: py:otherwiseType

Text content:

Any

complexType py:forType¶

for directive

Attributes:

Name	Description	Values	Required	Default
`py:each`	The loop iterator	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:ifType¶

if directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	The statement giving the value to test	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:matchType¶

match directive

Attributes:

Name	Description	Values	Required	Default
`py:path`	XPath expression to search for in the template.	`string`	Yes	None
`py:buffer`	Whether the matched content should be buffered in memory. Buffering can improve performance a bit at the cost of needing more memory during rendering. Buffering is required for match templates that contain more than one invocation of the `select()` function. If there is only one call, and the matched content can potentially be very long, consider disabling buffering to avoid excessive memory use.	`true` \| `false`	No	`true`
`py:once`	Whether the engine should stop looking for more matching elements after the first match. Use this on match templates that match elements that can only occur once in the stream, such as the <head> or <body> elements in an HTML template, or elements with a specific ID.	`true` \| `false`	No	`false`
`py:recursive`	Whether the match template should be applied to its own output. Note that once implies non-recursive behavior, so this attribute only needs to be set for match templates that don’t also have once set.	`true` \| `false`	No	`true`

Any arbitrary child elements allowed

Text content:

Any

complexType py:defType¶

def directive

Attributes:

Name	Description	Values	Required	Default
`py:function`	The function prototype	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:otherwiseType¶

The otherwise directive is used inside py:chooseType or choose to handle all conditions not handled by a py:when.

Text content:: Any

Example¶

<CertInfo>
  <subjectAltName>test.example.com</subjectAltName>
  <Group name="apache">
    <Cert key="/etc/pki/tls/private/foo.key" days="730"/>
  </Group>
  <Group name="nginx">
    <Cert key="/etc/pki/tls/private/foo.key" days="730"
          append_chain="true"/>
  </Group>
</CertInfo>

`sslkey.xml`¶

schema sslca-key.xsd¶

Schema for SSL Keys and Certificates sslkey.xml

element KeyInfo¶

Type: KeyInfoType

complexType KeyInfoType¶

Top-level tag for describing an SSLCA generated key.

Attributes:

Name	Description	Values	Required	Default
`category`	Create keys specific to the given category, instead of specific to the category given in `bcfg2.conf`.	`string`	No	None
`perhost`	Create keys on a per-host basis (rather than on a per-group basis).	`true` \| `false`	No	None
`priority`	Create group-specific keys with the given priority.	`positiveInteger`	No	`50`

Child elements:

element Key¶
Attributes:

Name

Description

Values

Required

Default

bits

The key length

nonNegativeInteger

No
2048

type

The key type

string

No
rsa

Attribute groups:
py:genshiAttrs
element Group¶

Type: SSLCAKeyGroupType
element Client¶

Type: SSLCAKeyGroupType
KeyInfo

Element groups:

complexType SSLCAKeyGroupType¶

An SSLCAKeyGroupType is a tag used to provide logic. Child entries of an SSLCAKeyGroupType tag only apply to machines that match the condition specified – either membership in a group, or a matching client name. negate can be set to negate the sense of the match.

Attributes:

Name	Description	Values	Required	Default
`name`	The name of the client or group to match on. Child entries will only apply to this client or group (unless `negate` is set).	`string`	No	None
`negate`	Negate the sense of the match, so that child entries only apply to a client if it is not a member of the given group or does not have the given name.	`true` \| `false`	No	None

Attribute groups:

py:genshiAttrs

Child elements:

Element groups:

group py:genshiElements¶

Most Genshi templating directives can be used either as standalone elements or as attributes on existing elements. This element group defines the standalone tags.

Elements:

element py:with¶

Type: py:withType

element py:replace¶

element py:choose¶

element py:for¶

Type: py:forType

element py:if¶

Type: py:ifType

element py:match¶

element py:def¶

Type: py:defType

complexType py:withType¶

with directive

Attributes:

Name	Description	Values	Required	Default
`py:vars`	A semicolon-delimited list of variables to define and their values.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:replaceType¶

replace directive

Attributes:

Name	Description	Values	Required	Default
`py:value`	The value to replace the contents with.	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:chooseType¶

choose directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	If `test` is set, the child `py:when` directives are tested for equality to the value of the expression.	`string`	No	None

Child elements:

element py:when¶

The when directive is used inside py:chooseType or choose to handle a single specific condition.

Type: py:ifType
element py:otherwise¶

Type: py:otherwiseType

Text content:

Any

complexType py:forType¶

for directive

Attributes:

Name	Description	Values	Required	Default
`py:each`	The loop iterator	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:ifType¶

if directive

Attributes:

Name	Description	Values	Required	Default
`py:test`	The statement giving the value to test	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any

complexType py:matchType¶

match directive

Attributes:

Name	Description	Values	Required	Default
`py:path`	XPath expression to search for in the template.	`string`	Yes	None
`py:buffer`	Whether the matched content should be buffered in memory. Buffering can improve performance a bit at the cost of needing more memory during rendering. Buffering is required for match templates that contain more than one invocation of the `select()` function. If there is only one call, and the matched content can potentially be very long, consider disabling buffering to avoid excessive memory use.	`true` \| `false`	No	`true`
`py:once`	Whether the engine should stop looking for more matching elements after the first match. Use this on match templates that match elements that can only occur once in the stream, such as the <head> or <body> elements in an HTML template, or elements with a specific ID.	`true` \| `false`	No	`false`
`py:recursive`	Whether the match template should be applied to its own output. Note that once implies non-recursive behavior, so this attribute only needs to be set for match templates that don’t also have once set.	`true` \| `false`	No	`true`

Any arbitrary child elements allowed

Text content:

Any

complexType py:defType¶

def directive

Attributes:

Name	Description	Values	Required	Default
`py:function`	The function prototype	`string`	Yes	None

Any arbitrary child elements allowed

Text content:

Any