diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/_templates/indexsidebar.html | 1 | ||||
-rw-r--r-- | doc/development/documentation.txt | 27 | ||||
-rw-r--r-- | doc/reports/dynamic.txt | 64 | ||||
-rw-r--r-- | doc/server/plugins/connectors/grouplogic.txt | 122 | ||||
-rw-r--r-- | doc/server/plugins/generators/packages.txt | 40 | ||||
-rw-r--r-- | doc/server/plugins/generators/rules.txt | 9 | ||||
-rw-r--r-- | doc/server/plugins/generators/sslca.txt | 2 | ||||
-rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 17 | ||||
-rw-r--r-- | doc/server/selinux.txt | 10 |
9 files changed, 213 insertions, 79 deletions
diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 39916315d..2133cdcc5 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -7,5 +7,6 @@ <ul> <li><a href="http://docs.bcfg2.org/1.1/">Bcfg2 1.1 (stable)</a></li> <li><a href="http://docs.bcfg2.org/1.2/">Bcfg2 1.2 (stable)</a></li> + <li><a href="http://docs.bcfg2.org/1.3/">Bcfg2 1.3 (stable)</a></li> <li><a href="http://docs.bcfg2.org/dev/">Bcfg2 development documentation</a></li> </ul> diff --git a/doc/development/documentation.txt b/doc/development/documentation.txt index 2a3cf46d1..4d8a7c9f8 100644 --- a/doc/development/documentation.txt +++ b/doc/development/documentation.txt @@ -8,13 +8,14 @@ There are two parts of documentation in the Bcfg2 project: -* The wiki -* The manual +* The Wiki_ +* The Manual_ The wiki ======== .. _Wiki: http://bcfg2.org +.. _Manual: http://docs.bcfg2.org .. _Trac: http://trac.edgewall.org/ .. _OpenID: https://openid.org/ .. _MCS: http://www.mcs.anl.gov/ @@ -31,9 +32,9 @@ The manual ========== .. _rst: http://en.wikipedia.org/wiki/ReStructuredText .. _Sphinx: http://sphinx.pocoo.org -.. _Docutils: +.. _Docutils: http://docutils.sourceforge.net -The source for the manual is located in the ``doc/`` directory in the +The source for the Manual_ is located in the ``doc/`` directory in the git repository or in the source tarball. All files are written in rst_ (ReStructuredText) format. Sphinx_ is used to build the documentation from the restructured text sources. @@ -49,11 +50,20 @@ Building the Manual apt-get -t lenny-backports install python-sphinx - * The needed tools for Fedora based systems are in the `Fedora + * The tools for Fedora based systems are in the `Fedora Package Collection <https://admin.fedoraproject.org/pkgdb>`_; installation can be done easily with Yum:: yum -y install python-sphinx python-docutils + + * The tools for RHEL6-based systems are in the base distribution; you can install them with Yum:: + + yum -y install python-sphinx python-docutils + + * The tools for RHEL5-based systems are in the `Extra Packages for Enterprise Linux(EPEL) <https://fedoraproject.org/wiki/EPEL>`_ repository; if your system is configured for EPEL, you can install them with Yum:: + + yum -y install python-sphinx python-docutils + * Additionally, to build the PDF version: @@ -80,14 +90,14 @@ Documentation Style Guide for Bcfg2 =================================== This is a style guide to use when creating documentation for Bcfg2. It -is meant to be helpful, not a hinderence. +is meant to be helpful, not a hindrance. Basics ------ **Bcfg2** - When referring to project, Bcfg2 is the preferred use of cases. + When referring to project, Bcfg2 is the preferred use of case. **Monospace fonts** @@ -97,8 +107,7 @@ Basics **Repository** When used alone this refers to a Bcfg2 :term:`repository`. When there - is a chance for confusion, for instance in documents also talking - about :term:`VCS`, be sure to use the longer Bcfg2 :term:`repository`. + is a chance for confusion, for instance in documents that also discuss :term:`VCS`, be sure to use the longer phrase "Bcfg2 :term:`repository`". Sections -------- diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index b3028e9e1..9de3f868f 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -53,40 +53,41 @@ Prerequisites Install ------- -Be sure to include the specified fields included in the example -``bcfg2.conf`` file. These can be specified in either ``/etc/bcfg2.conf``, -if it is readable by the webserver user, or ``/etc/bcfg2-web.conf``. Any -database supported by `Django <http://www.djangoproject.com>`_ can be used. -As of version 1.3, `South <http://south.aeracode.org>`_ is used to control -schema changes. If your database is not supported by South, any updates -will need to be applied manually. Sqlite is configured by default. -Please see the :ref:`reporting-databases` section to configure alternative -databases. -.. warning:: +1. Be sure to include the specified fields included in the example + ``bcfg2.conf`` file. These can be specified in either + ``/etc/bcfg2.conf``, if it is readable by the webserver user, + or ``/etc/bcfg2-web.conf``. Any database supported by `Django + <http://www.djangoproject.com>`_ can be used. As of version 1.3, + `South <http://south.aeracode.org>`_ is used to control schema changes. + If your database is not supported by South, any updates will need to + be applied manually. Sqlite is configured by default. Please see the + :ref:`reporting-databases` section to configure alternative databases. - If you are using an sqlite database, the directory containing the - database file will need to be writable by the web server. The reason - for this is that sqlite will create another file for its journal - when it tries to update the database file. + .. warning:: -.. note:: + If you are using an sqlite database, the directory containing the + database file will need to be writable by the web server. The reason + for this is that sqlite will create another file for its journal + when it tries to update the database file. + + .. note:: - Distributed environments can share a single remote database for - reporting. + Distributed environments can share a single remote database for + reporting. -After configuring your database be sure to run `bcfg2-admin reports init` -to create the schema. +2. After configuring your database be sure to run ``bcfg2-admin reports + init`` to create the schema. -To enable statistics collection in the bcfg2-server, add -:ref:`server-plugins-statistics-reporting` to the **plugins** -line in your ``bcfg2.conf`` and restart the bcfg2-server. A report collecting -daemon should be run to import the collected statistics into the backend. -Please see the section :ref:`Report Collector <report_collector>` for more -information. +3. To enable statistics collection in the bcfg2-server, add + :ref:`server-plugins-statistics-reporting` to the **plugins** + line in your ``bcfg2.conf`` and restart the bcfg2-server. A report + collecting daemon should be run to import the collected statistics + into the backend. Please see the section :ref:`Report Collector + <report_collector>` for more information. -Detailed installation instructions can be found :ref:`here -<appendix-guides-web-reports-install>`. + Detailed installation instructions can be found :ref:`here + <appendix-guides-web-reports-install>`. .. _dynamic-http-install: @@ -175,7 +176,7 @@ Upgrading .. note:: After the database is upgraded all of the old tables are left - intact. To remove them any table starting with reports_ can + intact. To remove them any table starting with **reports\_** can be dropped. 4. `(Optional)` Run the :ref:`Report Collector <report_collector>` @@ -199,11 +200,6 @@ An example using the defaults is listed below:: host = port = - [statistics] - config = /etc/bcfg2-web.conf - time_zone = - web_debug = False - [reporting] transport = DirectStore web_prefix = @@ -241,6 +237,8 @@ section: statistics ^^^^^^^^^^ +.. deprecated: 1.3.0 + * config: The config file to be read for additional reporting data. This is used to restrict what can be read by the web server. diff --git a/doc/server/plugins/connectors/grouplogic.txt b/doc/server/plugins/connectors/grouplogic.txt new file mode 100644 index 000000000..b9a5b00d6 --- /dev/null +++ b/doc/server/plugins/connectors/grouplogic.txt @@ -0,0 +1,122 @@ +.. -*- mode: rst -*- + +.. _server-plugins-connectors-grouplogic: + +========== +GroupLogic +========== + +.. versionadded:: 1.3.2 + +GroupLogic is a connector plugin that lets you use an XML Genshi +template to dynamically set additional groups for clients. + +Usage +===== + +To use the GroupLogic plugin, first do ``mkdir +/var/lib/bcfg2/GroupLogic``. Add ``GroupLogic`` to your ``plugins`` +line in ``/etc/bcfg2.conf``. Next, create +``/var/lib/bcfg2/GroupLogic/groups.xml``: + +.. code-block:: xml + + <GroupLogic xmlns:py="http://genshi.edgewall.org/"> + </GroupLogic> + +``groups.xml`` is structured very similarly to the +:ref:`server-plugins-grouping-metadata` ``groups.xml``. A Group tag +that contains no children is a declaration of membership; a Group or +Client tag that does contain children is a conditional. + +Unlike ``Metadata/groups.xml``, GroupLogic supports genshi templating, +so you can dynamically create groups. ``GroupLogic/groups.xml`` is +rendered for each client, and the groups set in it are added to the +client metadata. + +.. note:: + + Also unlike ``Metadata/groups.xml``, GroupLogic can not be used to + associate bundles with clients directly, or to negate groups. But + you can use GroupLogic to assign a group that is associated with a + bundle in Metadata. + +Consider the case where you have four environments -- dev, test, +staging, and production -- and four components to a web application -- +the frontend, the API, the database server, and the caching proxy. In +order to make files specific to the component *and* to the +environment, you need groups to describe each combination: +webapp-frontend-dev, webapp-frontend-test, and so on. You *could* do +this in ``Metadata/groups.xml``: + +.. code-block:: xml + + <Groups> + <Group name="webapp-frontend"> + <Group name="dev"> + <Group name="webapp-frontend-dev"/> + </Group> + <Group name="test"> + <Group name="webapp-frontend-test"/> + </Group> + ... + </Group> + <Group name="webapp-api"> + ... + </Group> + ... + </Groups> + +Creating the sixteen groups this way is incredibly tedious, and this +is a quite *small* site. GroupLogic can automate this process. + +Assume that we've declared the groups thusly in +``Metadata/groups.xml``: + +.. code-block:: xml + + <Groups> + <Group name="webapp-frontend" category="webapp-component"/> + <Group name="webapp-api" category="webapp-component"/> + <Group name="webapp-db" category="webapp-component"/> + <Group name="webapp-proxy" category="webapp-component"/> + <Group name="dev" category="environment"/> + <Group name="test" category="environment"/> + <Group name="staging" category="environment"/> + <Group name="prod" category="environment"/> + </Groups> + +One way to automate the creation of the groups would be to simply +generate the tedious config: + +.. code-block:: xml + + <GroupLogic xmlns:py="http://genshi.edgewall.org/"> + <py:for each="component in metadata.query.all_groups_in_category("webapp-component")> + <Group name="${component}"> + <py:for each="env in metadata.query.all_groups_in_category("environment")> + <Group name="${env}"> + <Group name="${component}-${env}"/> + </Group> + </py:for> + </Group> + </py:for> + </GroupLogic> + +But, since ``GroupLogic/groups.xml`` is rendered for each client +individually, there's a more elegant way to accomplish the same thing: + +.. code-block:: xml + + <GroupLogic xmlns:py="http://genshi.edgewall.org/"> + <?python +component = metadata.group_in_category("webapp-component") +env = metadata.group_in_category("environment") + ?> + <py:if test="component and env"> + <Group name="${component}-${env}"/> + </py:if> + </GroupLogic> + +This gets only the component and environment for the current client, +and, if both are set, sets the single appropriate group. diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 73145fd6b..606e1e128 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -434,7 +434,7 @@ configs. Simply add entries like these to the appropriate bundles: .. code-block:: xml <Path name="/etc/yum.repos.d/bcfg2.repo"/> - <Path name="/etc/apt/sources.d/bcfg2"/> + <Path name="/etc/apt/sources.list.d/bcfg2-packages-generated-sources.list"/> If you want to change the path to either of those files, you can set ``yum_config`` or ``apt_config`` in ``bcfg2.conf`` to the path to the @@ -702,25 +702,25 @@ It understands the following directives: [packages] section ------------------ -+-------------+------------------------------------------------------+----------+-----------------------------+ -| Name | Description | Values | Default | -+=============+======================================================+==========+=============================+ -| resolver | Enable dependency resolution | Boolean | True | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| metadata | Enable metadata processing. Disabling ``metadata`` | Boolean | True | -| | implies disabling ``resolver`` as well. | | | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| yum_config | The path at which to generate Yum configs. | String | /etc/yum.repos.d/bcfg2.repo | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| apt_config | The path at which to generate APT configs. | String | /etc/apt/sources.d/bcfg2 | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| gpg_keypath | The path on the client RPM GPG keys will be copied | String | /etc/pki/rpm-gpg | -| | to before they are imported on the client. | | | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| version | Set the version attribute used when binding Packages | any|auto | auto | -+-------------+------------------------------------------------------+----------+-----------------------------+ -| cache | Path where Packages will store its cache | String | <repo>/Packages/cache | -+-------------+------------------------------------------------------+----------+-----------------------------+ ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| Name | Description | Values | Default | ++=============+======================================================+==========+===================================================================+ +| resolver | Enable dependency resolution | Boolean | True | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| metadata | Enable metadata processing. Disabling ``metadata`` | Boolean | True | +| | implies disabling ``resolver`` as well. | | | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| yum_config | The path at which to generate Yum configs. | String | /etc/yum.repos.d/bcfg2.repo | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| apt_config | The path at which to generate APT configs. | String | /etc/apt/sources.list.d/bcfg2-packages-generated-sources.list | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| gpg_keypath | The path on the client RPM GPG keys will be copied | String | /etc/pki/rpm-gpg | +| | to before they are imported on the client. | | | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| version | Set the version attribute used when binding Packages | any|auto | auto | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ +| cache | Path where Packages will store its cache | String | <repo>/Packages/cache | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ [packages:yum] section diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 2789411e7..845006115 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -117,8 +117,13 @@ describe the attributes available for various Path types. Note that ``secontext`` below expects a full context, not just the type. For instance, "``system_u:object_r:etc_t:s0``", not just ``etc_t``. You can also specify "``__default__``", which will restore -the context of the file to the default set by policy. See -:ref:`server-selinux` for more information. +the context of the file to the default set by policy. If a file has +no default context rule, and you don't wish to set one, you can +specify ``secontext=''`` (i.e., an empty ``secontext``), in which case +the client will not try to manage the SELinux context of the file at +all. + +See :ref:`server-selinux` for more information. Attributes common to all Path tags: diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index cab7eb233..7ef358a31 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -156,7 +156,7 @@ Example .. code-block:: xml <CertInfo> - <SubjectAltName>test.example.com</SubjectAltName> + <subjectAltName>test.example.com</subjectAltName> <Group name="apache"> <Cert key="/etc/pki/tls/private/foo.key" days="730"/> </Group> diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index fe0d2683e..32834b458 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -119,20 +119,19 @@ a simple ``groups.xml`` file: <Group name='oracle-server'> <Group name='selinux-enabled' negate='true'/> </Group> - <Client name='foo.eample.com'> + <Client name='foo.example.com'> <Group name='oracle-server'/> <Group name='apache-server'/> </Client> </Groups> -A Group or Client 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.) +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 diff --git a/doc/server/selinux.txt b/doc/server/selinux.txt index 9f54b0d68..79384970a 100644 --- a/doc/server/selinux.txt +++ b/doc/server/selinux.txt @@ -142,13 +142,13 @@ necessary. Duplicate Entries ----------------- -It may be necessary to use `BoundSELinux` tags if a single fcontext +It may be necessary to use `BoundSEFcontext` tags if a single fcontext needs two different SELinux types depending on whether it's a symlink or a plain file. For instance: .. code-block:: xml - <BoundSELinux type="fcontext" filetype="symlink" - name="/etc/localtime" selinuxtype="etc_t"/> - <BoundSELinux type="fcontext" filetype="regular" - name="/etc/localtime" selinuxtype="locale_t"/> + <BoundSEFcontext filetype="symlink" + name="/etc/localtime" selinuxtype="etc_t"/> + <BoundSEFcontext filetype="regular" + name="/etc/localtime" selinuxtype="locale_t"/> |