path: root/doc/server/configuration.txt

.. -*- 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.

Many of the steps below may have already been performed by your OS
packages.

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 ``mode="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 0755 /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 three different server backends: a builtin server based
on the Python SimpleXMLRPCServer object; a server that uses CherryPy
(http://www.cherrypy.org); and a version of the builtin server that
uses the Python :mod:`multiprocessing` module.  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 multiprocessing server:

* Leverages most of the stability and maturity of the builtin server,
  but does have some new bits;
* Introduces concurrent processing to Bcfg2, which may break in
  various edge cases;
* Supports certificate authentication;
* Requires Python 2.6;
* Is faster with large numbers of concurrent runs.

The CherryPy server:

* Is very new and potentially buggy;
* Does not support certificate authentication yet, only password
  authentication;
* Requires CherryPy 3.3, 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.  The CherryPy server is purely
experimental at this point.

To select which backend to use, set the ``backend`` option in the
``[server]`` section of ``/etc/bcfg2.conf``.  Options are:

* ``cherrypy``
* ``builtin``
* ``multiprocessing``
* ``best`` (the default; currently the same as ``builtin``)

``best`` may change in future releases.

Multiprocessing core configuration
----------------------------------

If you use the multiprocessing core, there are other bits you may wish
to twiddle.

By default, the server spawns as many children as the host has CPUs.
(This is determined by ``multiprocessing.cpu_count()``.)  To change
this, set:

.. code-block:: conf

    [server]
    children = 4

The optimal number of children may vary depending on your workload.
For instance, if you are using :ref:`native yum
library support <native-yum-libraries>`, then a separate process is
spawned for each client to resolve its package dependencies, so
keeping the children at or below the CPU count is likely a good idea.
If you're not using native yum library support, though, you may wish
to oversubscribe the core slightly.  It's recommended that you test
various configurations and use what works best for your workload.

Secondly, if ``tmpwatch`` is enabled, you must either disable it or
exclude the pattern ``/tmp/pymp-\*``.  For instance, on RHEL or CentOS
you may have a line like the following in
``/etc/cron.daily/tmpwatch``:

.. code-block:: bash

    /usr/sbin/tmpwatch -x /tmp/.X11-unix -x /tmp/.XIM-unix -x /tmp/.font-unix \
        -x /tmp/.ICE-unix -x /tmp/.Test-unix 240 /tmp

You would need to add ``-X /tmp/pymp-\*`` to it, like so:

.. code-block:: bash

    /usr/sbin/tmpwatch -x /tmp/.X11-unix -x /tmp/.XIM-unix -x /tmp/.font-unix \
        -x /tmp/.ICE-unix -x /tmp/.Test-unix -X /tmp/pymp-\* 240 /tmp

See https://bugzilla.redhat.com/show_bug.cgi?id=1058310 for more information.