added docs for privilege dropping

4 files changed, 211 insertions, 48 deletions

diff --git a/doc/server/backends.txt b/doc/server/backends.txt
deleted file mode 100644
index 71ecac10b..000000000
--- a/doc/server/backends.txt
+++ /dev/null
@@ -1,44 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _server-backends:
-
-===============
-Server Backends
-===============
-
-.. versionadded:: 1.3.0
-
-Bcfg2 supports two different server backends: a builtin server
-based on the Python SimpleXMLRPCServer object, and a server that uses
-CherryPy (http://www.cherrypy.org).  Each one has advantages and
-disadvantages.
-
-The builtin server:
-
-* Is very stable and mature;
-* Supports certificate authentication;
-* Works on Python 2.4;
-* Is slow with larger numbers of clients.
-
-The CherryPy server:
-
-* Is very new and potentially buggy;
-* Does not support certificate authentication, only password
-  authentication;
-* Requires CherryPy 3.2, which requires Python 2.5;
-* Is faster with large numbers of clients.
-
-Basically, the builtin server should be used unless you have a
-particular need for performance, and can sacrifice certificate
-authentication.
-
-To select which backend to use, set the ``backend`` option in the
-``[server]`` section of ``/etc/bcfg2.conf``.  Options are:
-
-* ``cherrypy``
-* ``builtin``
-* ``best`` (the default; currently the same as ``builtin``)
-
-If the certificate authentication issues (a limitation in CherryPy
-itself) can be resolved and the CherryPy server proves to be stable,
-it will likely become the default (and ``best``) in a future release.
diff --git a/doc/server/configuration.txt b/doc/server/configuration.txt
new file mode 100644
index 000000000..6cf082cd8
--- /dev/null
+++ b/doc/server/configuration.txt
@@ -0,0 +1,207 @@
+.. -*- mode: rst -*-
+
+.. _server-configuration:
+
+======================
+ Server Configuration
+======================
+
+This page documents various aspects of server configuration.
+
+.. _server-dropping-privs:
+
+Running as a non-root user
+==========================
+
+Although the Bcfg2 server runs as root by default, it is possible (and
+probably encouraged) to run it as an unprivileged user.  This may
+become the default in the future.  This can be done in all versions of
+Bcfg2, although it has become easier in 1.3.0.  The steps to do so are
+described in three sections below:  Common steps for all versions;
+steps for older versions only; and steps for 1.3.0.
+
+Common Steps
+------------
+
+We will assume for the sake of these steps that we are running the
+Bcfg2 server as the ``bcfg2`` user, who is a member of the ``bcfg2``
+group.  To create that user and group, you can run:
+
+.. code-block:: bash
+
+    groupadd bcfg2
+    useradd -g bcfg2 -M -r -s /sbin/nologin -d /var/lib/bcfg2 \
+        -c "Bcfg2 server user" bcfg2
+
+``useradd`` arguments can vary wildly on different OSes, so please
+read ``useradd`` and run a command appropriate for your platform.
+
+The Bcfg2 server has to be able to read and write its data, so we need
+to set ownership on several things.  The config file and specification
+data, of course:
+
+.. code-block:: bash
+
+    chown bcfg2:bcfg2 /etc/bcfg2.conf
+    chmod 0600 /etc/bcfg2.conf
+    chown -R bcfg2:bcfg2 /var/lib/bcfg2/*
+    chmod -R 0700 /var/lib/bcfg2/*
+
+Note that this does not change the permissions of ``/var/lib/bcfg2``
+itself, which would prevent the ``bcfg2`` user from enabling a new
+plugin.  If you depend on this capability (e.g., if your specification
+is stored in a VCS and checked out onto the Bcfg2 server by a script
+running as the ``bcfg2`` user), then you would want to ``chown`` and
+``chmod`` ``/var/lib/bcfg2`` rather than ``/var/lib/bcfg2/*``.  Note
+also that the recursive ``chmod`` will change permissions on any files
+that are using ``perms="inherit"`` in :ref:`server-info`.
+
+The Bcfg2 server also needs to be able to read its SSL certificate,
+key and the SSL CA certificate:
+
+.. code-block:: bash
+
+    chown bcfg2:bcfg2 /etc/pki/tls/private/bcfg2.key \
+        /etc/pki/tls/certs/bcfg2.crt
+    chmod 0600 /etc/pki/tls/private/bcfg2.key
+    chmod 0644 /etc/pki/tls/certs/bcfg2.crt
+
+The paths to your SSL key and cert may be quite different,
+particularly on older versions of Bcfg2.
+
+.. note::
+
+    This step can be skipped if you are using the CherryPy
+    :ref:`backend <server-backends>`.  CherryPy reads in the
+    certificate data before dropping privileges, so you can (and
+    should) keep the keypair owned by root to prevent a compromised
+    Bcfg2 server process from modifying that data.
+
+Most of these steps can (and should) be done via Bcfg2 itself.
+
+Steps on older versions
+-----------------------
+
+On older versions of Bcfg2, you must change the location of the PID
+file.  This change has been made the default in newer versions.
+
+This can be accomplished in one of two ways.
+
+* On systems where ``/var/run`` is world-writable with the sticky bit set,
+  no change needs to be made.
+* On systems where ``/var/run`` is only writable by root, create a
+  subdirectory for the PID file and configure the Bcfg2 server to
+  write its PID file there:
+
+.. code-block:: bash
+
+    mkdir /var/run/bcfg2-server
+    chown bcfg2:bcfg2 /var/run/bcfg2-server
+    chmod 0644 /var/run/bcfg2-server
+
+To change the PID file:
+
+* On Debian and derivatives, add ``export
+  PIDFILE=/var/run/bcfg2-server/bcfg2-server.pid`` to
+  ``/etc/default/bcfg2-server``
+* On Red Hat Enterprise Linux and derivatives, add ``export
+  PIDFILE=/var/run/bcfg2-server/bcfg2-server.pid`` to
+  ``/etc/sysconfig/bcfg2-server``.  This includes recent versions that
+  are using systemd.
+* On other platforms, take the appropriate steps to change the PID
+  file, which is given to the ``bcfg2-server`` process with the ``-D``
+  option, in your init system.
+
+On older versions of Bcfg2, you must also manually change the init script
+or process to drop privileges to the ``bcfg2`` user before the daemon
+is even invoked.
+
+* On RHEL and derivatives that are not using systemd, modify the
+  ``bcfg2-server`` init script to run ``daemon --user=bcfg2 $DAEMON
+  ...`` in the ``start()`` function.
+* On Debian and derivatives, modify the ``bcfg2-server`` init script
+  to run ``start_daemon --user=bcfg2 ${DAEMON} ...`` in the
+  ``start()`` function.
+* On systems that use systemd as their init system, add ``User=bcfg``
+  to the ``[Service]`` section of
+  ``/etc/systemd/system/bcfg2-server.service``
+* On other platforms, take the appropriate steps to change to the
+  ``bcfg2`` user when spawning the ``bcfg2-server`` daemon.
+
+Restart ``bcfg2-server`` and you should see it running as non-root in
+``ps`` output::
+
+    % ps -ef | grep '[b]cfg2-server'   
+    1000     11581     1  0 07:55 ?        00:00:15 python usr/sbin/bcfg2-server -C /etc/bcfg2.conf -D /var/run/bcfg2-server/bcfg2-server.pid
+
+Steps on Bcfg2 1.3.0
+--------------------
+
+.. versionadded:: 1.3.0
+
+On Bcfg2 1.3, the default PID file location has been changed, but it
+is still owned by root since no ``bcfg2`` user is created by default.
+Consequently, you simply have to run:
+
+.. code-block:: bash
+
+    chown bcfg2:bcfg2 /var/run/bcfg2-server
+    chmod 0644 /var/run/bcfg2-server
+
+Additionally, the server daemon itself supports dropping privileges
+natively in 1.3.  Simply add the following lines to ``bcfg2.conf``::
+
+    [server]
+    ...
+    user = bcfg2
+    group = bcfg2
+
+Restart ``bcfg2-server`` and you should see it running as non-root in
+``ps`` output::
+
+    % ps -ef | grep '[b]cfg2-server'   
+    1000     11581     1  0 07:55 ?        00:00:15 python usr/sbin/bcfg2-server -C /etc/bcfg2.conf -D /var/run/bcfg2-server/bcfg2-server.pid
+
+.. _server-backends:
+
+Server Backends
+===============
+
+.. versionadded:: 1.3.0
+
+Bcfg2 supports two different server backends: a builtin server
+based on the Python SimpleXMLRPCServer object, and a server that uses
+CherryPy (http://www.cherrypy.org).  Each one has advantages and
+disadvantages.
+
+The builtin server:
+
+* Is very stable and mature;
+* Supports certificate authentication;
+* Works on Python 2.4;
+* Is slow with larger numbers of clients.
+
+The CherryPy server:
+
+* Is very new and potentially buggy;
+* Does not support certificate authentication yet, only password
+  authentication;
+* Requires CherryPy 3.2, which requires Python 2.5;
+* Is smarter about daemonization, particularly if you are
+  :ref:`server-dropping-privs`;
+* Is faster with large numbers of clients.
+
+Basically, the builtin server should be used unless you have a
+particular need for performance, and can sacrifice certificate
+authentication.
+
+To select which backend to use, set the ``backend`` option in the
+``[server]`` section of ``/etc/bcfg2.conf``.  Options are:
+
+* ``cherrypy``
+* ``builtin``
+* ``best`` (the default; currently the same as ``builtin``)
+
+If the certificate authentication issues (a limitation in CherryPy
+itself) can be resolved and the CherryPy server proves to be stable,
+it will likely become the default (and ``best``) in a future release.
diff --git a/doc/server/index.txt b/doc/server/index.txt
index 505fc8004..b02b5def8 100644
--- a/doc/server/index.txt
+++ b/doc/server/index.txt
@@ -29,7 +29,7 @@ clients.
    snapshots/index
    bcfg2-info
    selinux
-   backends
+   configuration
    database
    caching
    encryption
diff --git a/doc/server/info.txt b/doc/server/info.txt
index 69f926aad..34b5fcd7d 100644
--- a/doc/server/info.txt
+++ b/doc/server/info.txt
@@ -2,9 +2,9 @@
 
 .. _server-info:
 
-====
-Info
-====
+========
+info.xml
+========
 
 Various file properties for entries served by most generator plugins,
 including :ref:`server-plugins-generators-cfg`,