.. -*- mode: rst -*-

.. _server-info:

========
info.xml
========

Various file properties for entries served by most generator plugins,
including :ref:`server-plugins-generators-cfg`,
:ref:`server-plugins-generators-sslca`, and
:ref:`server-plugins-generators-sshbase`, are controlled through the
use of ``info.xml`` files.

By default, these plugins are set to write files to the filesystem
with owner **root**, group **root**, and mode **644** (read and write
for owner, read only for group and other). These options, and a few
others, can be overridden through use of ``info.xml`` files. Each
config file directory can have a ``info.xml`` file if needed.

An ``info.xml`` file consists of a ``<FileInfo>`` tag containing an
``<Info>`` tag; the following attributes are allowed on the ``<Info>`` tag:

+------------+-------------------+----------------------------------+---------+
| Field      | Possible values   | Description                      | Default |
+============+===================+==================================+=========+
| encoding   | ascii | base64    | Encoding of the file. Use        | ascii   |
|            |                   | base64 for binary files          |         |
+------------+-------------------+----------------------------------+---------+
| owner      | Any valid user    | Sets owner of the file           | root    |
+------------+-------------------+----------------------------------+---------+
| group      | Any valid group   | Sets group of the file           | root    |
+------------+-------------------+----------------------------------+---------+
| perms      | Numeric file mode | Sets the permissions of the file | 0644    |
|            | | 'inherit'       | (or inherits from the files on   |         |
|            |                   | disk if set to 'inherit')        |         |
+------------+-------------------+----------------------------------+---------+
| secontext  | A valid SELinux   | Sets the SELinux context of the  | default |
|            | context string or | file, or sets to the default     |         |
|            | '__default__'     | context set by policy if set to  |         |
|            |                   | '__default__'                    |         |
+------------+-------------------+----------------------------------+---------+
| important  | true | false      | Important entries are            | false   |
|            |                   | installed first during client    |         |
|            |                   | execution                        |         |
+------------+-------------------+----------------------------------+---------+
| paranoid   | true | false      | Backup file before replacement?  | true    |
+------------+-------------------+----------------------------------+---------+
| sensitive  | true | false      | The contents of sensitive        | false   |
|            |                   | entries aren't included in       |         |
|            |                   | reports                          |         |
+------------+-------------------+----------------------------------+---------+

A sample info file for CGI script on a web server might look like:

.. code-block:: xml

    <FileInfo>
      <Info owner="www" group="www" perms="0755"/>
    </FileInfo>

Back to the fstab example again, our final ``Cfg/etc/fstab/`` directory
might look like::

    info.xml
    fstab
    fstab.G50_server
    fstab.G99_fileserver
    fstab.H_host.example.com

See :ref:`server-selinux` for more information on the ``secontext``
attribute and managing SELinux in general.

``info.xml`` files also have the ability to specify different sets of
file metadata on a group by group or host by host basis, or by path
(for files using :ref:`altsrc
<server-plugins-structures-altsrc>`). These files are XML, and work
similarly to those used by :ref:`Rules
<server-plugins-generators-rules>` or :ref:`Bundler
<server-plugins-structures-bundler-index>`.

The following specifies a different global set of permissions
(root/sys/0651) than on clients in group webserver or named
"foo.example.com" (root/root/0652)::

    <FileInfo>
      <Client name='foo.example.com'>
        <Info owner='root' group='root' perms='0652'/>
      </Client>
      <Group name='webserver'>
        <Info owner='root' group='root' perms='0652'/>
      </Group>
      <Info owner='root' group='sys' perms='0651'/>
    </FileInfo>

.. versionadded:: 1.2.0

You can also use the ``<Path>`` directive to specify a different set
of permissions depending on the path of the file::

    <FileInfo>
      <Path name="/etc/bcfg2-web.conf">
        <Info owner="root" group="apache" perms="0640"/>
      </Path>
      <Path name="/etc/bcfg2-web.conf" negate="true">
        <Info owner="root" group="root" perms="0600"/>
      </Path>
    </FileInfo>

.. versionadded:: 1.3.0

You can also specify ACLs as children of ``<Info>`` tags in
``info.xml``.  See :ref:`server-plugins-generators-rules-acls` for
more information on the formatting of ACL tags.

:info and info files
====================

Historically, Bcfg2 also accepted the use of ``:info`` and ``info``
files, which function the same as ``info.xml``, but are not XML.  They
lack the ability to specify different permissions based on client,
group, or path, and cannot be used to specify ACLs, either.

.. note::

    ``:info`` and ``info`` files are deprecated and will be removed in
    a future release.

An example ``:info`` or ``info`` file would look like::

    owner: www
    group: www
    perms: 0755

All attributes allowed on the ``<Info>`` tag of an ``info.xml`` file
can be used in an ``:info`` or ``info`` file.

You should not use more than one ``:info``, ``info``, or ``info.xml``
file for a single entry.