Merge remote branch 'upstream/master' into jasons-hacking

7 files changed, 256 insertions, 125 deletions

diff --git a/doc/client/tools/posixusers.txt b/doc/client/tools/posixusers.txt
new file mode 100644
index 000000000..884edc2b7
--- /dev/null
+++ b/doc/client/tools/posixusers.txt
@@ -0,0 +1,51 @@
+.. -*- mode: rst -*-
+
+.. _client-tools-posixusers:
+
+==========
+POSIXUsers
+==========
+
+The POSIXUsers tool handles the creation of users and groups as
+defined by ``POSIXUser`` and ``POSIXGroup`` entries.  For a full
+description of those tags, see :ref:`server-plugins-generators-rules`.
+
+The POSIXUsers tool relies on the ``useradd``, ``usermod``,
+``userdel``, ``groupadd``, ``groupmod``, and ``groupdel`` tools, since
+there is no Python library to manage users and groups.  It expects
+those tools to be in ``/usr/sbin``.
+
+Primary group creation
+======================
+
+Each user must have a primary group, which can be specified with the
+``group`` attribute of the ``POSIXUser`` tag.  (If the ``group``
+attribute is not specified, then a group with the same name as the
+user will be used.)  If that group does not exist, the POSIXUsers tool
+will create it automatically.  It does this by adding a ``POSIXGroup``
+entry on the fly; this has a few repercussions:
+
+* When run in interactive mode (``-I``), Bcfg2 will prompt for
+  installation of the group separately from the user.
+* The ``POSIXGroup`` entry is added to the same bundle as the
+  ``POSIXUser`` entry, so if the group is created, the bundle is
+  considered to have been modified and consequently Actions will be
+  run and Services will be restarted.  This should never be a concern,
+  since the group can only be created, not modified (it has no
+  attributes other than its name), and if the group is being created
+  then the user will certainly be created or modified as well.
+* The group is created with no specified GID number.  If you need to
+  specify a particular GID number, you must explicitly define a
+  ``POSIXGroup`` entry for the group.
+
+Creating a baseline configuration
+=================================
+
+The majority of users on many systems are created by the packages that
+are installed, but currently Bcfg2 cannot query the package database
+to determine these users.  (In some cases, this is a limitation of the
+packaging system.)  The often-tedious task of creating a baseline that
+defines all users and groups can be simplified by use of the
+``tools/posixusers_baseline.py`` script, which outputs a bundle
+containing all users and groups on the machine it's run on.
+
diff --git a/doc/development/compat.txt b/doc/development/compat.txt
index d3e77b4a3..b7bf87bec 100644
--- a/doc/development/compat.txt
+++ b/doc/development/compat.txt
@@ -197,3 +197,9 @@ unicode
 In Py3k, the :func:`unicode` class is not defined, because all
 strings are unicode.  ``Bcfg2.Compat`` defines ``unicode`` as
 equivalent to :func:`str` in Python 3.
+
+oct_mode
+~~~~~~~~
+
+.. autofunction:: Bcfg2.Compat.oct_mode
+
diff --git a/doc/development/documentation.txt b/doc/development/documentation.txt
index 1e7667cc5..2a3cf46d1 100644
--- a/doc/development/documentation.txt
+++ b/doc/development/documentation.txt
@@ -103,5 +103,5 @@ Basics
 Sections
 --------
 
-Unless necessary, all the documentation follows the sections header
-rules available at http://docs.python.org/documenting/rest.html#sections.
+Unless necessary, all the documentation follows the sections header rules
+available at http://docs.python.org/devguide/documenting.html#sections
diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt
index 7d0e0acff..94394f98f 100644
--- a/doc/server/plugins/generators/cfg.txt
+++ b/doc/server/plugins/generators/cfg.txt
@@ -136,33 +136,33 @@ by running the template manually. To do this, run ``bcfg2-info
 debug``, and, once in the Python interpreter, run::
 
     metadata = self.build_metadata("<hostname>")
-    path = "<relative path to template (see note below)>"
-
-``path`` should be set to the path to the template file with a leading
-slash, relative to the Bcfg2 specification root. See `Inside Genshi
-Templates`_ for examples.
+    source_path = "<full path to template>"
+    name = source_path[len(self.setup['repo']):]
 
 Then, run::
 
-    import os, Bcfg2.Options
+    import os
     from genshi.template import TemplateLoader, NewTextTemplate
-    name = os.path.dirname(path[path.find('/', 1):])
-    setup = Bcfg2.Options.OptionParser({'repo':
-                                        Bcfg2.Options.SERVER_REPOSITORY})
-    setup.parse('--')
-    template = TemplateLoader().load(setup['repo'] + path, cls=NewTextTemplate)
-    print template.generate(metadata=metadata, path=path, name=name).render()
+    template = TemplateLoader().load(source_path, cls=NewTextTemplate)
+    data = dict(metadata=metadata,
+                source_path=source_path,
+                path=source_path,
+                name=name,
+                repo=self.setup['repo'])
+    print(template.generate(**data).render())
 
 This gives you more fine-grained control over how your template is
-rendered.
+rendered.  E.g., you can tweak the values of the variables passed to
+the template, or evaluate the template manually, line-by-line, and so
+on.
 
 You can also use this approach to render templates that depend on
 :ref:`altsrc <server-plugins-structures-altsrc>` tags by setting
-``path`` to the path to the template, and setting ``name`` to the path
+``source_path`` to the path to the template, and setting ``name`` to the path
 to the file to be generated, e.g.::
 
     metadata = self.build_metadata("foo.example.com")
-    path = "/Cfg/etc/sysconfig/network-scripts/ifcfg-template/ifcfg-template.genshi"
+    source_path = "/Cfg/etc/sysconfig/network-scripts/ifcfg-template/ifcfg-template.genshi"
     name = "/etc/sysconfig/network-scripts/ifcfg-bond0"
 
 Error handling
diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt
index 542b38f01..cdde65960 100644
--- a/doc/server/plugins/generators/rules.txt
+++ b/doc/server/plugins/generators/rules.txt
@@ -62,10 +62,10 @@ The Rules Tag may have the following attributes:
 |          | Rules list.The higher value wins.   |        |
 +----------+-------------------------------------+--------+
 
-Rules Group Tag
----------------
+Group Tag
+---------
 
-The Rules Group Tag may have the following attributes:
+The Group Tag may have the following attributes:
 
 +--------+-------------------------+--------------+
 | Name   | Description             | Values       |
@@ -76,6 +76,27 @@ The Rules Group Tag may have the following attributes:
 |        | (is not a member of)    |              |
 +--------+-------------------------+--------------+
 
+Client Tag
+----------
+
+The Client Tag is used in Rules for selecting the package entries to
+include in the clients literal configuration.  Its function is similar
+to the Group tag in this context.  It can be thought of as::
+
+    if client is name then
+        assign to literal config
+
+The Client Tag may have the following attributes:
+
++--------+-------------------------+--------------+
+| Name   | Description             | Values       |
++========+=========================+==============+
+| name   | Client Name             | String       |
++--------+-------------------------+--------------+
+| negate | Negate client selection | (true|false) |
+|        | (if not client name)    |              |
++--------+-------------------------+--------------+
+
 Package Tag
 -----------
 
@@ -84,8 +105,7 @@ The Package Tag may have the following attributes:
 +------------+----------------------------------------------+----------+
 | Name       | Description                                  | Values   |
 +============+==============================================+==========+
-| name       | Package name or regular expression           | String   |
-|            |                                              | or regex |
+| name       | Package name                                 | String   |
 +------------+----------------------------------------------+----------+
 | version    | Package Version or version='noverify' to     | String   |
 |            | not do version checking in the Yum driver    |          |
@@ -131,8 +151,7 @@ Service Tag
 |            | service (new in 1.3; replaces |                                                         |
 |            | "mode" attribute)             |                                                         |
 +------------+-------------------------------+---------------------------------------------------------+
-| name       | Service name or regular       | String or regex                                         |
-|            | expression                    |                                                         |
+| name       | Service name                  | String                                                  |
 +------------+-------------------------------+---------------------------------------------------------+
 | status     | Should the service be on or   | (on | off | ignore)                                     |
 |            | off (default: off).           |                                                         |
@@ -193,27 +212,6 @@ Service status descriptions
 
   * Don't perform service status checks.
 
-Client Tag
-----------
-
-The Client Tag is used in Rules for selecting the package entries to
-include in the clients literal configuration.  Its function is similar
-to the Group tag in this context.  It can be thought of as::
-
-    if client is name then
-        assign to literal config
-
-The Client Tag may have the following attributes:
-
-+--------+-------------------------+--------------+
-| Name   | Description             | Values       |
-+========+=========================+==============+
-| name   | Client Name             | String       |
-+--------+-------------------------+--------------+
-| negate | Negate client selection | (true|false) |
-|        | (if not client name)    |              |
-+--------+-------------------------+--------------+
-
 Path Tag
 --------
 
@@ -229,11 +227,11 @@ the context of the file to the default set by policy.  See
 
 Attributes common to all Path tags:
 
-+----------+---------------------------------------------------+-----------------+
-| Name     | Description                                       | Values          |
-+==========+===================================================+=================+
-| name     | Full path or regular expression matching the path | String or regex |
-+----------+---------------------------------------------------+-----------------+
++----------+-------------+--------+
+| Name     | Description | Values |
++==========+=============+========+
+| name     | Full path   | String |
++----------+-------------+--------+
 
 
 device
@@ -394,14 +392,12 @@ the permissions to ``0674``.  When this happens, Bcfg2 will change the
 permissions and set the ACLs on every run and the entry will be
 eternally marked as bad.
 
-SELinux Tag
------------
+SELinux Entries
+---------------
 
-The SELinux tag has different values depending on the *type* attribute
-of the SELinux entry specified in your configuration. Below is a set
-of tables which describe the attributes available for various SELinux
-types.  The types (except for ``module``) correspond to ``semanage``
-subcommands.
+Below is a set of tables which describe the attributes available
+for various SELinux types.  The entry types (except for ``module``)
+correspond to ``semanage`` subcommands.
 
 Note that the ``selinuxtype`` attribute takes only an SELinux type,
 not a full context; e.g., "``etc_t``", not
@@ -411,18 +407,10 @@ As it can be very tedious to create a baseline of all existing SELinux
 entries, you can use ``selinux_baseline.py`` located in the ``tools/``
 directory to do that for you.
 
-In certain cases, it may be necessary to create multiple SELinux
-entries with the same name.  For instance, "root" is both an SELinux
-user and an SELinux login record; or a given fcontext may need two
-different SELinux types depending on whether it's a symlink or a plain
-file.  In these (few) cases, it is necessary to create BoundSELinux
-entries directly in Bundler rather than using abstract SELinux entries
-in Bundler and binding them with Rules.
-
 See :ref:`server-selinux` for more information.
 
-boolean
-^^^^^^^
+SEBoolean Tag
+^^^^^^^^^^^^^
 
 +-------+----------------------+---------+----------+
 | Name  | Description          | Values  | Required |
@@ -432,8 +420,8 @@ boolean
 | value | Value of the boolean | on|off  | Yes      |
 +-------+----------------------+---------+----------+
 
-port
-^^^^
+SEPort Tag
+^^^^^^^^^^
 
 +-------------+------------------------+---------------------------+----------+
 | Name        | Description            | Values                    | Required |
@@ -445,8 +433,8 @@ port
 |             | to this port           |                           |          |
 +-------------+------------------------+---------------------------+----------+
 
-fcontext
-^^^^^^^^
+SEFcontext Tag
+^^^^^^^^^^^^^^
 
 +-------------+-------------------------+---------------------+----------+
 | Name        | Description             | Values              | Required |
@@ -462,8 +450,8 @@ fcontext
 |             |                         |  socket|block|char) |          |
 +-------------+-------------------------+---------------------+----------+
 
-node
-^^^^
+SENode Tag
+^^^^^^^^^^
 
 +-------------+------------------------------------+------------------+----------+
 | Name        | Description                        | Values           | Required |
@@ -477,8 +465,8 @@ node
 | proto       | Protocol                           | (ipv4|ipv6)      | Yes      |
 +-------------+------------------------------------+------------------+----------+
 
-login
-^^^^^
+SELogin Tag
+^^^^^^^^^^^
 
 +-------------+-------------------------------+-----------+----------+
 | Name        | Description                   | Values    | Required |
@@ -488,8 +476,8 @@ login
 | selinuxuser | SELinux username              | String    | Yes      |
 +-------------+-------------------------------+-----------+----------+
 
-user
-^^^^
+SEUser Tag
+^^^^^^^^^^
 
 +-------------+-------------------------------+-----------+----------+
 | Name        | Description                   | Values    | Required |
@@ -501,8 +489,8 @@ user
 | prefix      | Home directory context prefix | String    | Yes      |
 +-------------+-------------------------------+-----------+----------+
 
-interface
-^^^^^^^^^
+SEInterface Tag
+^^^^^^^^^^^^^^^
 
 +-------------+-------------------------+-------------+----------+
 | Name        | Description             | Values      | Required |
@@ -513,8 +501,8 @@ interface
 |             | to this interface       |             |          |
 +-------------+-------------------------+-------------+----------+
 
-permissive
-^^^^^^^^^^
+SEPermissive Tag
+^^^^^^^^^^^^^^^^
 
 +-------------+------------------------------------+-------------+----------+
 | Name        | Description                        | Values      | Required |
@@ -522,11 +510,79 @@ permissive
 | name        | SELinux type to make permissive    | String      | Yes      |
 +-------------+------------------------------------+-------------+----------+
 
-module
-^^^^^^
+SEModule Tag
+^^^^^^^^^^^^
 
 See :ref:`server-plugins-generators-semodules`
 
+POSIXUser Tag
+-------------
+
+The POSIXUser tag allows you to create users on client machines.  It
+takes the following attributes:
+
++-------+-----------------------+---------+-------------------------------+
+| Name  | Description           | Values  | Default                       |
++=======+=======================+=========+===============================+
+| name  | Username              | String  | None                          |
++-------+-----------------------+---------+-------------------------------+
+| uid   | User ID number        | Integer | The client sets the uid       |
++-------+-----------------------+---------+-------------------------------+
+| group | Name of the user's    | String  | The username                  |
+|       | primary group         |         |                               |
++-------+-----------------------+---------+-------------------------------+
+| gecos | Human-readable user   | String  | The username                  |
+|       | name or comment       |         |                               |
++-------+-----------------------+---------+-------------------------------+
+| home  | User's home directory | String  | /root (for "root");           |
+|       |                       |         | /home/<username> otherwise    |
++-------+-----------------------+---------+-------------------------------+
+| shell | User's shell          | String  | /bin/bash                     |
++-------+-----------------------+---------+-------------------------------+
+
+The group specified will automatically be created if it does not
+exist, even if there is no `POSIXGroup Tag`_ for it.  If you need to
+specify a particular GID for the group, you must specify that in a
+``POSIXGroup`` tag.
+
+If you with to change the default shell, you can do so with :ref:`the
+Defaults plugin <server-plugins-structures-defaults>`.
+
+Additionally, a user may be a member of supplementary groups.  These
+can be specified with the ``MemberOf`` child tag of the ``POSIXUser``
+tag.
+
+For example:
+
+.. code-block:: xml
+
+    <POSIXUser name="daemon" home="/sbin" shell="/sbin/nologin"
+               gecos="daemon" uid="2" group="daemon">
+      <MemberOf>lp</MemberOf>
+      <MemberOf>adm</MemberOf>
+      <MemberOf>bin</MemberOf>
+    </BoundPOSIXUser>
+
+See :ref:`client-tools-posixusers` for more information on managing
+users and groups.
+
+POSIXGroup Tag
+--------------
+
+The POSIXGroup tag allows you to create groups on client machines.  It
+takes the following attributes:
+
++-------+-------------------+---------+-------------------------+
+| Name  | Description       | Values  | Default                 |
++=======+===================+=========+=========================+
+| name  | Name of the group | String  | None                    |
++-------+-------------------+---------+-------------------------+
+| gid   | Group ID number   | Integer | The client sets the gid |
++-------+-------------------+---------+-------------------------+
+
+See :ref:`client-tools-posixusers` for more information on managing
+users and groups.
+
 Rules Directory
 ===============
 
diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt
index 2b07f91fe..cabb4d730 100644
--- a/doc/server/plugins/generators/sslca.txt
+++ b/doc/server/plugins/generators/sslca.txt
@@ -146,9 +146,15 @@ cert.xml
 
 ``cert.xml`` is an XML document describing an SSL certificate
 generated from an SSL key that has also been generated by SSLCA.  It
-contains a top-level ``CertInfo`` tag that contains a single ``Cert``
-tag.  (``Group`` and ``Client`` tags are not currently supported in
-``cert.xml``.)  The ``Cert`` tag may take the following attributes:
+honors ``Group`` and ``Client`` tags much like Bundler.  It must have
+a top-level ``CertInfo`` tag and can contain two types of tags:
+
+Cert
+^^^^
+
+The ``Cert`` tag explains how the certificate should be generated.
+There should be at least one ``Cert`` tag, and at most one ``Cert``
+tag should apply to any given client.
 
 +--------------+------------------------------------------+---------+---------+
 | Attribute    | Description                              | Values  | Default |
@@ -188,13 +194,42 @@ tag.  (``Group`` and ``Client`` tags are not currently supported in
 |              | the format required by Nginx)            |         |         |
 +--------------+------------------------------------------+---------+---------+
 
+SubjectAltName
+^^^^^^^^^^^^^^
+
+The ``SubjectAltName`` tag contains text giving a subject alternative
+name for the certificate.  Any number of ``SubjectAltName`` tags may
+be used.
+
+Example
+^^^^^^^
+
+.. code-block: xml
+
+    <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>
+
 key.xml
 -------
 
-``key.xml`` is an XML document describing an SSL key.  It contains a
-top-level ``KeyInfo`` tag that contains a single ``Key`` tag.
-(``Group`` and ``Client`` tags are not currently supported in
-``key.xml``.)  The ``Key`` tag may take the following attributes:
+``key.xml`` is an XML document describing an SSL key.  It also honors
+``Group`` and ``Client`` tags.  It contains a top-level ``KeyInfo``
+tag that contains at least one ``Key`` tag.
+
+Key
+^^^
+
+The ``Cert`` tag explains how the certificate should be generated.
+There should be at least one ``Cert`` tag, and at most one ``Cert``
+tag should apply to any given client.
 
 +--------------+------------------------------------------+---------+---------+
 | Attribute    | Description                              | Values  | Default |
@@ -204,6 +239,20 @@ top-level ``KeyInfo`` tag that contains a single ``Key`` tag.
 | bits         | The key length                           | Integer | 2048    |
 +--------------+------------------------------------------+---------+---------+
 
+Example
+^^^^^^^
+
+.. code-block: xml
+
+    <KeyInfo>
+      <Group name="fast">
+        <Key type="rsa" bits="1024"/>
+      </Group>
+      <Group name="secure">
+        <Key type="rsa" bits="4096"/>
+      </Group>
+    </KeyInfo>
+
 Automated Bcfg2 SSL Authentication
 ==================================
 
diff --git a/doc/server/selinux.txt b/doc/server/selinux.txt
index e61a09002..9f54b0d68 100644
--- a/doc/server/selinux.txt
+++ b/doc/server/selinux.txt
@@ -135,47 +135,16 @@ will be considered extra, making ``selinux_baseline.py`` quite
 necessary.
 
 ``selinux_baseline.py`` writes a bundle to stdout that contains
-``BoundSELinux`` entries for the appropriate SELinux entities.  It
-does this rather than separate Bundle/Rules files because of the
-:ref:`server-selinux-duplicate-entries` problem.
+``BoundSELinux`` entries for the appropriate SELinux entities.
 
 .. _server-selinux-duplicate-entries:
 
 Duplicate Entries
 -----------------
 
-In certain cases, it may be necessary to create multiple SELinux
-entries with the same name.  For instance, "root" is both an SELinux
-user and an SELinux login record, so to manage both, you would have
-the following in Bundler:
-
-.. code-block:: xml
-
-    <SELinux name="root"/>
-    <SELinux name="root"/>
-
-And in Rules:
-
-.. code-block:: xml
-
-    <SELinux type="login" selinuxuser="root" name="root"/>
-    <SELinux type="user" prefix="user" name="root"
-             roles="system_r sysadm_r user_r"/>
-
-But Rules has no way to tell which "root" is which, and you will get
-errors.  In these cases, it is necessary to use ``BoundSELinux`` tags
-directly in Bundler.  (See :ref:`boundentries` for more details on
-bound entries.)  For instance:
-
-.. code-block:: xml
-
-    <BoundSELinux type="login" selinuxuser="root" name="root"/>
-    <BoundSELinux type="user" prefix="user" name="root"
-                  roles="system_r sysadm_r user_r"/>
-
-It may also be necessary to use ``BoundSELinux`` tags if a single
-fcontext needs two different SELinux types depending on whether it's a
-symlink or a plain file.  For instance:
+It may be necessary to use `BoundSELinux` 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