[systemd-devel] [PATCH 1/2] libcgroup: Added README_systemd file.

[Jan Safranek]

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

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

 README_systemd |   68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 68 insertions(+), 0 deletions(-)
 create mode 100644 README_systemd

diff --git a/README_systemd b/README_systemd
new file mode 100644
index 0000000..3bb2f6b
--- /dev/null
+++ b/README_systemd
@@ -0,0 +1,68 @@
+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 tries to describe how to configure systemd
+and libcgroup so they can safely live together and mutually benefit from 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 usefult document describing systemd expectations on applications
+(incl. libcgroup tools).
+
+
+Compilation
+===========
+As stated in [2], libcgroup should not touch "name=systemd" hierarchy. Compile
+libcgroup with --enable-opaque-hierarchy configure option to do so:
+
+./configure --enable-opaque-hierarchy=name=systemd
+
+Libcgroup and all its tools won't then see the "name=systemd" hierarchy at all.
+For example, lsgcroup won't show it's content and cgclear won't remove it.
+
+
+Startup 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 "cpu,cpuacct:/system/$service_name"
+control group. System admin has full control on parameters of each group and
+also which controllers are used. Consult systemd documentation, mainly
+systemd.conf(5) and systemd.exec(5), for details.
+
+In vast majority of use cases, this should be enough and libcgroup does not need
+to be used.
+
+For specific use cases, e.g. when 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 systemd does not
+create control groups for services automatically.
+
+2. Prepare /etc/cgconfig.conf and enable cgconfig service. The service will
+parse /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 tasks file as recommended in [2].
+
+3. For each service that should start in specific control group, add following
+lines into it's unit file:
+	After=cgconfig.service
+	ControlGroup=<name of the control group(s)>
+
+This ensures the service is started only after cgconfig creates necessary
+hierarchy for it and also tells systemd into which control group should be the
+service started.
+