diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/client/tools/posixusers.txt | 51 | ||||
-rw-r--r-- | doc/development/compat.txt | 6 | ||||
-rw-r--r-- | doc/development/documentation.txt | 4 | ||||
-rw-r--r-- | doc/server/plugins/generators/cfg.txt | 30 | ||||
-rw-r--r-- | doc/server/plugins/generators/rules.txt | 188 | ||||
-rw-r--r-- | doc/server/plugins/generators/sslca.txt | 63 | ||||
-rw-r--r-- | doc/server/selinux.txt | 39 |
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 |