libcgroup: Added README_systemd file.

New documentation file is added. It should describe how systemd and
libcgroup should work together and how to configure a system to have
control groups created by libcgroup's cgconfig service.

I'm going to install this README into /usr/share/doc/libcgroup-*/.

I know I am not Shakespeare and also English is not my mother language, feel
free to comment also the style and grammar. Missing/wrong articles is my
speciality :).

Changelog:
  - updated with review remarks from Martin Prpic and Kevin Constantine

Signed-off-by: Jan Safranek <jsafrane@redhat.com>

diff --git a/README_systemd b/README_systemd
new file mode 100644 (file)
index 0000000..6733c2c
--- /dev/null
+++ b/README_systemd
@@ -0,0 +1,69 @@
+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.