From 10f815f1af1935bd76b7f75c5577c6f6197d706e Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Thu, 29 Nov 2012 18:13:42 -0600 Subject: doc: Fix broken target name Signed-off-by: Sol Jerome --- doc/server/plugins/generators/cfg.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 7d0e0acff..28d783781 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -139,8 +139,8 @@ debug``, and, once in the Python interpreter, run:: path = "" ``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. +slash, relative to the Bcfg2 specification root. See `Inside Templates`_ +for examples. Then, run:: -- cgit v1.2.3-1-g7c22 From 41d1d29b8b545e0f636ebf26795eecd1a46bc9fb Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 3 Dec 2012 08:45:48 -0600 Subject: SELinux: Split up selinux entries This commit splits up the all-in-one SELinux tag into various entries (formerly done using a type attribute). This helps prevent ambiguation when entries of different SELinux types have the same name. Note that there is still some ambiguation for File Context entries since there can be duplicates involved. Signed-off-by: Sol Jerome --- doc/server/plugins/generators/rules.txt | 56 ++++++++++++++------------------- doc/server/selinux.txt | 39 +++-------------------- 2 files changed, 27 insertions(+), 68 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 542b38f01..65eb0c5d9 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -394,14 +394,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 +409,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 +422,8 @@ boolean | value | Value of the boolean | on|off | Yes | +-------+----------------------+---------+----------+ -port -^^^^ +SEPort Tag +^^^^^^^^^^ +-------------+------------------------+---------------------------+----------+ | Name | Description | Values | Required | @@ -445,8 +435,8 @@ port | | to this port | | | +-------------+------------------------+---------------------------+----------+ -fcontext -^^^^^^^^ +SEFcontext Tag +^^^^^^^^^^^^^^ +-------------+-------------------------+---------------------+----------+ | Name | Description | Values | Required | @@ -462,8 +452,8 @@ fcontext | | | socket|block|char) | | +-------------+-------------------------+---------------------+----------+ -node -^^^^ +SENode Tag +^^^^^^^^^^ +-------------+------------------------------------+------------------+----------+ | Name | Description | Values | Required | @@ -477,8 +467,8 @@ node | proto | Protocol | (ipv4|ipv6) | Yes | +-------------+------------------------------------+------------------+----------+ -login -^^^^^ +SELogin Tag +^^^^^^^^^^^ +-------------+-------------------------------+-----------+----------+ | Name | Description | Values | Required | @@ -488,8 +478,8 @@ login | selinuxuser | SELinux username | String | Yes | +-------------+-------------------------------+-----------+----------+ -user -^^^^ +SEUser Tag +^^^^^^^^^^ +-------------+-------------------------------+-----------+----------+ | Name | Description | Values | Required | @@ -501,8 +491,8 @@ user | prefix | Home directory context prefix | String | Yes | +-------------+-------------------------------+-----------+----------+ -interface -^^^^^^^^^ +SEInterface Tag +^^^^^^^^^^^^^^^ +-------------+-------------------------+-------------+----------+ | Name | Description | Values | Required | @@ -513,8 +503,8 @@ interface | | to this interface | | | +-------------+-------------------------+-------------+----------+ -permissive -^^^^^^^^^^ +SEPermissive Tag +^^^^^^^^^^^^^^^^ +-------------+------------------------------------+-------------+----------+ | Name | Description | Values | Required | @@ -522,8 +512,8 @@ permissive | name | SELinux type to make permissive | String | Yes | +-------------+------------------------------------+-------------+----------+ -module -^^^^^^ +SEModule Tag +^^^^^^^^^^^^ See :ref:`server-plugins-generators-semodules` 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 - - - - -And in Rules: - -.. code-block:: xml - - - - -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 - - - - -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 -- cgit v1.2.3-1-g7c22 From 1d4b0118ced1b198587fd75c549e2b394ff71531 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Fri, 30 Nov 2012 08:18:12 -0500 Subject: doc: fixed in-depth genshi debugging instructions --- doc/server/plugins/generators/cfg.txt | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 28d783781..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("") - path = "" - -``path`` should be set to the path to the template file with a leading -slash, relative to the Bcfg2 specification root. See `Inside Templates`_ -for examples. + source_path = "" + 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 ` 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 -- cgit v1.2.3-1-g7c22 From 33234d5dae565e6520bbdb65d67fbaed03df4d43 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Mon, 3 Dec 2012 10:51:34 -0600 Subject: added builtin support for creating users and groups --- doc/client/tools/posixusers.txt | 51 ++++++++++++ doc/server/plugins/generators/rules.txt | 132 ++++++++++++++++++++++++-------- 2 files changed, 150 insertions(+), 33 deletions(-) create mode 100644 doc/client/tools/posixusers.txt (limited to 'doc') 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/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 65eb0c5d9..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 @@ -517,6 +515,74 @@ 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/ 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 `. + +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 + + + lp + adm + bin + + +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 =============== -- cgit v1.2.3-1-g7c22 From 5336c981b167858c3bb08b1ac4d94a700fd407a9 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Mon, 3 Dec 2012 17:08:02 -0600 Subject: SSLCA improvements: Added support for Group/Client tags in cert.xml/key.xml Added support for explicit subjectAltNames in cert.xml Reorganized code to make generally more like other GroupSpool plugins --- doc/server/plugins/generators/sslca.txt | 63 +++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index 2b07f91fe..85659982e 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 + + + test.example.com + + + + + + + + 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 + + + + + + + + + + Automated Bcfg2 SSL Authentication ================================== -- cgit v1.2.3-1-g7c22 From 27e78da340bc259a723ceda74cd96b0d49117566 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 3 Dec 2012 20:27:51 -0600 Subject: doc: Fix broken link Signed-off-by: Sol Jerome --- doc/development/documentation.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') 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 -- cgit v1.2.3-1-g7c22 From d052c66c5d5e561f2b5de4ebebd60dba7b78b1cc Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 3 Dec 2012 20:29:08 -0600 Subject: doc: Fix indentation errors Signed-off-by: Sol Jerome --- doc/server/plugins/generators/sslca.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/sslca.txt b/doc/server/plugins/generators/sslca.txt index 85659982e..cabb4d730 100644 --- a/doc/server/plugins/generators/sslca.txt +++ b/doc/server/plugins/generators/sslca.txt @@ -150,7 +150,7 @@ 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`` @@ -195,14 +195,14 @@ tag should apply to any given client. +--------------+------------------------------------------+---------+---------+ 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 @@ -225,7 +225,7 @@ key.xml 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`` @@ -240,7 +240,7 @@ tag should apply to any given client. +--------------+------------------------------------------+---------+---------+ Example -~~~~~~~ +^^^^^^^ .. code-block: xml -- cgit v1.2.3-1-g7c22 From f35c38e87eafffb497338b9273fe84f284a41dcf Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 4 Dec 2012 06:57:50 -0600 Subject: fixed conversion to octal in py3k --- doc/development/compat.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc') 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 + -- cgit v1.2.3-1-g7c22