Integration with systemd
========================

systemd is a system and service manager for Linux, compatible with SysV
and LSB init scripts. systemd heavily uses control groups to manage and control
services.

Most of the libcgroup tools and APIs can be safely used on systems with systemd
without any problems. This document attempts to describe the configuration of
systemd and libcgroup so they can safely co-exist and mutually benefit each
other.

References
==========
[1] http://www.freedesktop.org/wiki/Software/systemd
Systemd home page.

[2] http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups
This is the most useful document describing systemd expectations on applications
(incl. libcgroup tools).


Compilation
===========
As stated in [2], libcgroup should not interact with the 'name=systemd'
hierarchy. Compile libcgroup with the --enable-opaque-hierarchy configure option
to do so:

./configure --enable-opaque-hierarchy=name=systemd

Consequently, the 'name=systemd' hierarchy will not be visible to libcgroup and
all of its tools. For example, the lscgroup command will not list systemd
cgroups and the cgclear command will not remove them.

Start-up and services
====================

Systemd automatically mounts all available controllers on system boot ('cpu' and
'cpuacct' together in one hierarchy by default) and can automatically put
service processes into control groups with configured parameters — by default,
each service is automatically put into the 'cpu,cpuacct:/system/$service_name'
control group. The System Administrator has full control of parameters in each
control group and of which controllers are used. Consult systemd
documentation, mainly systemd.conf(5) and systemd.exec(5) man pages, for
details.

In the vast majority of use cases, this behavior is sufficient and libcgroup
does not need to be used.

For specific use cases, e.g. when a different tree of control groups is needed,
libcgroup provides cgconfig service. This service can create arbitrary control
group hierarchies. In this case, follow these steps:

1. Set 'DefaultControllers=' in /etc/systemd/system.conf so that systemd does
not create control groups for services automatically.

2. Prepare /etc/cgconfig.conf and enable the cgconfig service. The service will
parse the /etc/cgconfig.conf file during machine boot and create all control
groups which are defined in it. The service automatically sets '+t' ("sticky")
bit on the tasks files as recommended in [2].

3. For each service that should start in a specific control group, add the
following lines into its unit file:
	After=cgconfig.service
	ControlGroup=<name of the control group(s)>

This ensures the service is started only after cgconfig creates the necessary
hierarchy for it. It also tells systemd which control group it should use to
start the service.