Ubuntu Server Guide

Merge lp:~serge-hallyn/serverguide/cgroups into lp:serverguide/trunk

  1. cgroups
  2. Merge into trunk
Proposed by Serge Hallyn
Status: Merged
Approved by: Doug Smythies
Approved revision: 193
Merge reported by: Doug Smythies
Merged at revision: not available
Proposed branch: lp:~serge-hallyn/serverguide/cgroups
Merge into: lp:serverguide/trunk
Diff against target: 258 lines (+243/-0)
2 files modified
serverguide/C/cgroups.xml (+242/-0)
serverguide/C/serverguide.xml (+1/-0)
To merge this branch: bzr merge lp:~serge-hallyn/serverguide/cgroups
Reviewer Review Type Date Requested Status
Doug Smythies Approve
Review via email: mp+210029@code.launchpad.net

Description of the change

This is a first draft for a new section on control groups, written mainly to document the cgmanager.

To post a comment you must log in.
Revision history for this message
Doug Smythies (dsmythies) wrote :

Hi Serge,
Thanks for another chunk for really great stuff.
I am not a subject matter expert on this, and defer to you on that part of it.

In lines 37, 38, and 39 in the below diff, the word "Section" needs to be deleted. Why? Because the PDF compile automatically puts it in so it then reads as "Section Section 1, “Cgroups overview” [p. 345] will describe cgroups" (for example). In my opinion, the HTML reads fine without the word "Section", as the HTML doesn't really have that concept anyhow (at least under the "new" theme). I can make this change if you are busy.

For the Resources item 5: Do we really want to refer to kernel V3.14- rc2? Is there not some more generic way to make the link?

Peter M: This addition will juggle the wiki page numbering. I'll fix it, but perhaps not right away.

review: Needs Fixing
Revision history for this message
Doug Smythies (dsmythies) wrote :

For the link, I think this is more generic:

https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/cgroups

lp:~serge-hallyn/serverguide/cgroups updated
193. By Serge Hallyn

use more general link for the kernel cgroup doc page

Revision history for this message
Serge Hallyn (serge-hallyn) wrote :

Quoting Doug Smythies (<email address hidden>):
> For the link, I think this is more generic:
>
> https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/cgroups

Good point! updated that, thanks. (haven't addressed the rest of the
feedback yet)

Revision history for this message
Doug Smythies (dsmythies) wrote :

Serge, Thanks.
I'll make the other change.

review: Approve
Revision history for this message
Doug Smythies (dsmythies) wrote :

Oh Crap: I forgot that for consistency throughout the Serverguide, we don't name sections within chapters with the chapter name. I'm saying that, for example, the title for Chapter 21 Section 1 should be "Overview" instead of "Cgroups Overview". I'll fix it.

Revision history for this message
Serge Hallyn (serge-hallyn) wrote :

Quoting Doug Smythies (<email address hidden>):
> Oh Crap: I forgot that for consistency throughout the Serverguide, we don't name sections within chapters with the chapter name. I'm saying that, for example, the title for Chapter 21 Section 1 should be "Overview" instead of "Cgroups Overview". I'll fix it.

Oh, thanks! Sorry I had every intention of making the other changes on
Monday.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== added file 'serverguide/C/cgroups.xml'
2--- serverguide/C/cgroups.xml 1970-01-01 00:00:00 +0000
3+++ serverguide/C/cgroups.xml 2014-03-07 23:59:35 +0000
4@@ -0,0 +1,242 @@
5+<?xml version="1.0" encoding="UTF-8"?>
6+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
7+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
8+<!ENTITY % globalent SYSTEM "../../libs/global.ent">
9+%globalent;
10+<!ENTITY % xinclude SYSTEM "../../libs/xinclude.mod">
11+%xinclude;
12+<!ENTITY language "&EnglishAmerican;">
13+]>
14+<chapter id="cgroups" status="review">
15+ <title>Control Groups</title>
16+
17+ <para>
18+Control groups (cgroups) are a kernel mechanism for grouping, tracking,
19+and limiting the resource usage of tasks. The kernel-provided administration
20+interface is through a virtual filesystem. Higher level cgroup
21+administration tools have been developed, including libcgroup and
22+lmctfy. Additionally, there is guidance at freedesktop.org
23+for how applications can best cooperate using the cgroup filesystem
24+interface (see Resources).
25+ </para>
26+
27+ <para>
28+As of Ubuntu 14.04, the cgroup manager (cgmanager) is available as
29+another cgroup administion interface. It's goal is to respond to dbus
30+requests from any user, allowing him to administer only those cgroups
31+which have been delegated to him.
32+ </para>
33+
34+ <para>
35+Section <xref linkend="cgroups-overview"/> will describe cgroups in more detail.
36+Section <xref linkend="cgroups-fs"/> will describe the long-standing cgroups filesystem
37+interface. Section <xref linkend="cgroups-manager"/> will describe the cgroup
38+manager.
39+ </para>
40+
41+ <sect1 id="cgroups-overview" status="review">
42+ <title>Cgroups overview</title>
43+
44+ <para>
45+Cgroups are the generalized feature for grouping tasks. The actual
46+resource tracking and limits are implemented by subsystems. A
47+hierarchy is a set of subsystems mounted together. For instance,
48+if the memory and devices subsystems are mounted together under
49+/sys/fs/cgroups/set1, then any task which is in "/child1" will
50+be subject to the corresponding limits of both subsystems.
51+ </para>
52+
53+ <para>
54+Each set of mounted subsystems consittutes a 'hierarchy'. With
55+exceptions, cgroups which are children of "/child1" will be
56+subject to all limits placed on "/child1", and their resource
57+usage will be accounted to "/child1".
58+ </para>
59+
60+ <para>
61+The existing subsystems include:
62+ </para>
63+
64+ <itemizedlist>
65+<listitem><para><emphasis>cpusets</emphasis>: fascilitate assigning a set of
66+CPUS and memory nodes to cgroups.
67+ Tasks in a cpuset cgroup may only be scheduled on CPUS assigned to that
68+ cpuset.</para></listitem>
69+<listitem><para><emphasis> blkio </emphasis>: limits per-cgroup block io.</para></listitem>
70+<listitem><para><emphasis> cpuacct </emphasis>: provides per-cgroup cpu usage accounting.</para></listitem>
71+<listitem><para><emphasis> devices </emphasis>: controls the ability of tasks to create or use devices nodes
72+ using either a blacklist or whitelist.</para></listitem>
73+<listitem><para><emphasis> freezer </emphasis>: provides a way to 'freeze' and 'thaw' whole cgroups. Tasks
74+ in the cgroup will not be scheduled while they are frozen.</para></listitem>
75+<listitem><para><emphasis> hugetlb </emphasis>: fascilitates limiting hugetlb usage per cgroup.</para></listitem>
76+<listitem><para><emphasis> memory </emphasis>: allows memory, kernel memory, and swap usage to be tracked
77+ and limited.</para></listitem>
78+<listitem><para><emphasis> net_cls </emphasis>: provides an interface for tagging packets based on the
79+ sender cgroup. These tags can then be used by tc (traffic controller)
80+ to assign priorities.</para></listitem>
81+<listitem><para><emphasis> net_prio </emphasis>: allows setting network traffic priority on a per-cgroup
82+ basis.</para></listitem>
83+<listitem><para><emphasis> cpu </emphasis>: enables setting of scheduling preferences on per-cgroup basis.</para></listitem>
84+<listitem><para><emphasis> perf_event </emphasis>: enables per-cpu mode to monitor only threads in certain
85+ cgroups.</para></listitem>
86+ </itemizedlist>
87+
88+ <para>
89+In addition, named cgroups can be created with no bound
90+subsystems for the sake of process tracking. As an example,
91+systemd does this to track services and user sessions.
92+ </para>
93+
94+ </sect1>
95+
96+ <sect1 id="cgroups-fs" status="review">
97+ <title>Cgroup filesystem</title>
98+
99+ <para>
100+A hierarchy is created by mounting an instance of the cgroup filesystem
101+with each of the desired subsystems listed as a mount option. For instance,
102+ </para>
103+
104+<screen><command>
105+mount -t cgroup -o devices,memory,freezer cgroup /cgroup1
106+</command></screen>
107+
108+ <para>
109+would instantiate a hierarchy with the devices and memory cgroups comounted.
110+A child cgroup "child1" can be created using 'mkdir'
111+ </para>
112+
113+<screen><command>
114+mkdir /cgroup1/child1
115+</command></screen>
116+
117+ <para>
118+and tasks can be moved into the new child cgroup by writing their process
119+ids into the 'tasks' or 'cgroup.procs' file:
120+ </para>
121+
122+<screen><command>
123+sleep 100
124+echo $! > /cgroup1/child1/cgroup.procs
125+</command></screen>
126+
127+ <para>
128+Other administration is done through files in the cgroup directories. For
129+instance, to freeze all tasks in child1,
130+ </para>
131+
132+<screen><command>
133+echo FROZEN > /cgroup1/child1/freezer.state
134+</command></screen>
135+
136+ <para>
137+A great deal of information about cgroups and its subsystems can be found
138+under the cgroups documentation directory in the kernel source tree (see
139+Resources).
140+ </para>
141+
142+ </sect1>
143+
144+ <sect1 id="cgroups-delegation" status="review">
145+ <title>Cgroups Delegation</title>
146+
147+ <para>
148+Cgroup files and directories can be owned by non-root users, enabling
149+delegation of cgroup administration. In general, the kernel enforces
150+the hierarchical constraints on limits, so that for instance if
151+devices cgroup <filename>/child1</filename> cannot access a disk drive, then
152+<filename>/child1/child2</filename> cannot give itself those rights.
153+ </para>
154+
155+ <para>
156+As of Ubuntu 14.04, users are automatically placed in a set of cgroups
157+which they own, safely allowing them to contrain their own jobs using child
158+cgroups. This feature is relied upon, for instance, for unprivileged
159+container creation in lxc.
160+ </para>
161+
162+ </sect1>
163+
164+ <sect1 id="cgroups-manager" status="review">
165+ <title>Cgroup Manager</title>
166+
167+ <para>
168+The cgroup manager (cgmanager) provides a D-Bus service allowing
169+programs and users to administer cgroups without needing direct
170+knowledge of or access to the cgroup filesystem. For requests
171+from tasks in the same namespaces as the manager, the manager can
172+directly perform the needed security checks to ensure that requests
173+are legitimate. For other requests - such as those from a task in
174+a container - enhanced D-Bus requests must be made, where process-,
175+user- and group-ids are passed as SCM_CREDENTIALS, so that the kernel
176+maps the identifiers to their global host values.
177+ </para>
178+
179+ <para>
180+To fascilitate the use of simple D-Bus calls from all users, a
181+'cgroup manager proxy' (cgproxy) is automatically started when in
182+a container. The proxy accepts standard D-Bus requests from tasks
183+in the same namespaces as itself, and converts them to
184+SCM-enhanced D-Bus requests which it passes on to the cgmanager.
185+ </para>
186+
187+ <para>
188+A simple example of creating a new cgroup in which to run a
189+cpu-intensive compile would look like:
190+ </para>
191+
192+<screen><command>
193+dbus-send --print-reply --address=unix:path=/sys/fs/cgroup/cgmanager/sock \
194+ --type=method_call /org/linuxcontainers/cgmanager \
195+ org.linuxcontainers.cgmanager0_0.Create string:'cpuset' string:"build1"
196+dbus-send --print-reply --address=unix:path=/sys/fs/cgroup/cgmanager/sock \
197+ --type=method_call /org/linuxcontainers/cgmanager \
198+ org.linuxcontainers.cgmanager0_0.MovePid string:'cpuset' \
199+ string:"build1" int32:$$
200+dbus-send --print-reply --address=unix:path=/sys/fs/cgroup/cgmanager/sock \
201+ --type=method_call /org/linuxcontainers/cgmanager \
202+ org.linuxcontainers.cgmanager0_0.SetValue string:'cpuset' \
203+ string:"build1" string:"cpuset.cpus" string:"1"
204+make
205+</command></screen>
206+
207+ <para>
208+The above can also be done much more simply by using lmctfy or
209+cgroup-bin, once they are converted to use the cgmanager.
210+ </para>
211+
212+ </sect1>
213+
214+ <sect1 id="cgroups-resources" status="review">
215+ <title>Resources</title>
216+
217+ <itemizedlist>
218+ <listitem>
219+ <para>Manual pages referenced above can be found at:</para>
220+ <screen>
221+<ulink url="http://manpages.ubuntu.com/manpages/en/man5/cgconfig.conf.5.html">cgconfig.conf</ulink>
222+<ulink url="http://manpages.ubuntu.com/manpages/en/man8/cgmanager.8.html">cgmanager</ulink>
223+<ulink url="http://manpages.ubuntu.com/manpages/en/man8/cgproxy.8.html">cgproxy</ulink>
224+</screen>
225+ </listitem>
226+
227+ <listitem>
228+ <para>The upstream cgmanager project is hosted at <ulink
229+ url="http://cgmanager.linuxcontainers.org">linuxcontainers.org</ulink>.</para>
230+ </listitem>
231+
232+ <listitem>
233+ <para>The upstream kernel documentation page on cgroups can be seen <ulink
234+ url="https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/cgroups">here
235+ </ulink>.</para>
236+ </listitem>
237+
238+ <listitem>
239+ <para>The freedesktop.org control group usage guidelines can be seen <ulink
240+ url="http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups/">here</ulink>.</para>
241+ </listitem>
242+
243+ </itemizedlist>
244+ </sect1>
245+
246+</chapter>
247
248=== modified file 'serverguide/C/serverguide.xml'
249--- serverguide/C/serverguide.xml 2013-02-09 00:40:31 +0000
250+++ serverguide/C/serverguide.xml 2014-03-07 23:59:35 +0000
251@@ -41,6 +41,7 @@
252 <xi:include href="samba.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
253 <xi:include href="backups.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
254 <xi:include href="virtualization.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
255+ <xi:include href="cgroups.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
256 <xi:include href="clustering.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
257 <xi:include href="vpn.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
258 <xi:include href="other-apps.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

Subscribers

People subscribed via source and target branches