Server Configuration

This page documents various aspects of server configuration.

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:

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:

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

The Bcfg2 server also needs to be able to read its SSL certificate, key and the SSL CA certificate:

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 backend. 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:
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

New in version 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:

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

New in version 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 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 Running as a non-root user;
  • 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:

[server]
children = 4

The optimal number of children may vary depending on your workload. For instance, if you are using native yum library support, 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:

/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:

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