Debian Codegraph @

doc/lxc.sgml.in

raw
1 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
2
3 <!DOCTYPE refentry PUBLIC @docdtd@ [
4
5 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
6 ]>
7
8 <refentry>
9
10 <docinfo>
11 <date>@LXC_GENERATE_DATE@</date>
12 </docinfo>
13
14
15 <refmeta>
16 <refentrytitle>lxc</refentrytitle>
17 <manvolnum>7</manvolnum>
18 <refmiscinfo>
19 Version @PACKAGE_VERSION@
20 </refmiscinfo>
21 </refmeta>
22
23 <refnamediv>
24 <refname>lxc</refname>
25
26 <refpurpose>
27 linux containers
28 </refpurpose>
29 </refnamediv>
30
31 <refsect1>
32 <title>Overview</title>
33 <para>
34 The container technology is actively being pushed into the mainstream
35 Linux kernel. It provides resource management through control groups and
36 resource isolation via namespaces.
37 </para>
38
39 <para>
40 <command>lxc</command>, aims to use these new functionalities to provide a
41 userspace container object which provides full resource isolation and
42 resource control for an applications or a full system.
43 </para>
44
45 <para>
46 <command>lxc</command> is small enough to easily manage a container with
47 simple command lines and complete enough to be used for other purposes.
48 </para>
49 </refsect1>
50
51 <refsect1>
52 <title>Requirements</title>
53 <para>
54 The kernel version >= 3.10 shipped with the distros, will work with
55 <command>lxc</command>, this one will have less functionalities but enough
56 to be interesting.
57 </para>
58
59 <para>
60 <command>lxc</command> relies on a set of functionalities provided by the
61 kernel. The helper script <command>lxc-checkconfig</command> will give
62 you information about your kernel configuration, required, and missing
63 features.
64 </para>
65 </refsect1>
66
67 <refsect1>
68 <title>Functional specification</title>
69 <para>
70 A container is an object isolating some resources of the host, for the
71 application or system running in it.
72 </para>
73 <para>
74 The application / system will be launched inside a container specified by
75 a configuration that is either initially created or passed as a parameter
76 of the commands.
77 </para>
78
79 <para>How to run an application in a container</para>
80 <para>
81 Before running an application, you should know what are the resources you
82 want to isolate. The default configuration is to isolate PIDs, the sysv
83 IPC and mount points. If you want to run a simple shell inside a
84 container, a basic configuration is needed, especially if you want to
85 share the rootfs. If you want to run an application like
86 <command>sshd</command>, you should provide a new network stack and a new
87 hostname. If you want to avoid conflicts with some files eg.
88 <filename>/var/run/httpd.pid</filename>, you should remount
89 <filename>/var/run</filename> with an empty directory. If you want to
90 avoid the conflicts in all the cases, you can specify a rootfs for the
91 container. The rootfs can be a directory tree, previously bind mounted
92 with the initial rootfs, so you can still use your distro but with your
93 own <filename>/etc</filename> and <filename>/home</filename>
94 </para>
95 <para>
96 Here is an example of directory tree
97 for <command>sshd</command>:
98 <programlisting>
99 [root@lxc sshd]$ tree -d rootfs
100
101 rootfs
102 |-- bin
103 |-- dev
104 | |-- pts
105 | `-- shm
106 | `-- network
107 |-- etc
108 | `-- ssh
109 |-- lib
110 |-- proc
111 |-- root
112 |-- sbin
113 |-- sys
114 |-- usr
115 `-- var
116 |-- empty
117 | `-- sshd
118 |-- lib
119 | `-- empty
120 | `-- sshd
121 `-- run
122 `-- sshd
123 </programlisting>
124
125 and the mount points file associated with it:
126 <programlisting>
127 [root@lxc sshd]$ cat fstab
128
129 /lib /home/root/sshd/rootfs/lib none ro,bind 0 0
130 /bin /home/root/sshd/rootfs/bin none ro,bind 0 0
131 /usr /home/root/sshd/rootfs/usr none ro,bind 0 0
132 /sbin /home/root/sshd/rootfs/sbin none ro,bind 0 0
133 </programlisting>
134 </para>
135
136 <para>How to run a system in a container</para>
137
138 <para>
139 Running a system inside a container is paradoxically easier
140 than running an application. Why? Because you don't have to care
141 about the resources to be isolated, everything needs to be
142 isolated, the other resources are specified as being isolated but
143 without configuration because the container will set them
144 up. eg. the ipv4 address will be setup by the system container
145 init scripts. Here is an example of the mount points file:
146 </para>
147
148 <programlisting>
149 [root@lxc debian]$ cat fstab
150
151 /dev /home/root/debian/rootfs/dev none bind 0 0
152 /dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0
153 </programlisting>
154
155 <refsect2>
156 <title>Container life cycle</title>
157 <para>
158 When the container is created, it contains the configuration
159 information. When a process is launched, the container will be starting
160 and running. When the last process running inside the container exits,
161 the container is stopped.
162 </para>
163 <para>
164 In case of failure when the container is initialized, it will pass
165 through the aborting state.
166 </para>
167
168 <programlisting>
169 <![CDATA[
170 ---------
171 | STOPPED |<---------------
172 --------- |
173 | |
174 start |
175 | |
176 V |
177 ---------- |
178 | STARTING |--error- |
179 ---------- | |
180 | | |
181 V V |
182 --------- ---------- |
183 | RUNNING | | ABORTING | |
184 --------- ---------- |
185 | | |
186 no process | |
187 | | |
188 V | |
189 ---------- | |
190 | STOPPING |<------- |
191 ---------- |
192 | |
193 ---------------------
194 ]]>
195 </programlisting>
196 </refsect2>
197
198 <refsect2>
199 <title>Configuration</title>
200 <para>The container is configured through a configuration
201 file, the format of the configuration file is described in
202 <citerefentry>
203 <refentrytitle><filename>lxc.conf</filename></refentrytitle>
204 <manvolnum>5</manvolnum>
205 </citerefentry>
206 </para>
207 </refsect2>
208
209 <refsect2>
210 <title>Unprivileged containers</title>
211 <para>
212 Unprivileged LXC containers run without root host-level privileges in a
213 user namespace, mapping container UID 0 to a non-root host ID, which
214 strictly limits the accessible devices and filesystems of the
215 container. In order to mount a rootfs in an unprivileged container, the
216 mapped host user must have execute permissions for all directories
217 along the path to and including the rootfs. Additionally, all files and
218 directories under the rootfs must be owned by the correct user ID and
219 group ID. The correct user ID and group ID are the host IDs mapped to
220 the container root(UID 0) in lxc.idmap.
221 </para>
222 </refsect2>
223
224 <refsect2>
225 <title>Creating / Destroying containers</title>
226 <para>
227 A persistent container object can be created via the
228 <command>lxc-create</command> command. It takes a container name as
229 parameter and optional configuration file and template. The name is
230 used by the different commands to refer to this container. The
231 <command>lxc-destroy</command> command will destroy the container
232 object.
233 <programlisting>
234 lxc-create -n foo
235 lxc-destroy -n foo
236 </programlisting>
237 </para>
238 </refsect2>
239
240 <refsect2>
241 <title>Volatile container</title>
242 <para>
243 It is not mandatory to create a container object before starting it.
244 The container can be directly started with a configuration file as
245 parameter.
246 </para>
247 </refsect2>
248
249 <refsect2>
250 <title>Starting / Stopping container</title>
251 <para>
252 When the container has been created, it is ready to run an application /
253 system. This is the purpose of the <command>lxc-execute</command> and
254 <command>lxc-start</command> commands. If the container was not created
255 before starting the application, the container will use the
256 configuration file passed as parameter to the command, and if there is
257 no such parameter either, then it will use a default isolation. If the
258 application ended, the container will be stopped, but if needed the
259 <command>lxc-stop</command> command can be used to stop the container.
260 </para>
261
262 <para>
263 Running an application inside a container is not exactly the same thing
264 as running a system. For this reason, there are two different commands
265 to run an application into a container:
266 <programlisting>
267 lxc-execute -n foo [-f config] /bin/bash
268 lxc-start -n foo [-f config] [/bin/bash]
269 </programlisting>
270 </para>
271
272 <para>
273 The <command>lxc-execute</command> command will run the specified command
274 into a container via an intermediate process,
275 <command>lxc-init</command>.
276 This lxc-init after launching the specified command, will wait for its
277 end and all other reparented processes. (to support daemons in the
278 container). In other words, in the container,
279 <command>lxc-init</command> has PID 1 and the first process of the
280 application has PID 2.
281 </para>
282
283 <para>
284 The <command>lxc-start</command> command will directly run the specified
285 command in the container. The PID of the first process is 1. If no
286 command is specified <command>lxc-start</command> will run the command
287 defined in lxc.init.cmd or if not set, <filename>/sbin/init</filename> .
288 </para>
289
290 <para>
291 To summarize, <command>lxc-execute</command> is for running an
292 application and <command>lxc-start</command> is better suited for
293 running a system.
294 </para>
295
296 <para>
297 If the application is no longer responding, is inaccessible or is not
298 able to finish by itself, a wild <command>lxc-stop</command> command
299 will kill all the processes in the container without pity.
300 <programlisting>
301 lxc-stop -n foo -k
302 </programlisting>
303 </para>
304 </refsect2>
305
306 <refsect2>
307 <title>Connect to an available tty</title>
308 <para>
309 If the container is configured with ttys, it is possible to access it
310 through them. It is up to the container to provide a set of available
311 ttys to be used by the following command. When the tty is lost, it is
312 possible to reconnect to it without login again.
313 <programlisting>
314 lxc-console -n foo -t 3
315 </programlisting>
316 </para>
317 </refsect2>
318
319 <refsect2>
320 <title>Freeze / Unfreeze container</title>
321 <para>
322 Sometime, it is useful to stop all the processes belonging to
323 a container, eg. for job scheduling. The commands:
324 <programlisting>
325 lxc-freeze -n foo
326 </programlisting>
327
328 will put all the processes in an uninteruptible state and
329
330 <programlisting>
331 lxc-unfreeze -n foo
332 </programlisting>
333
334 will resume them.
335 </para>
336
337 <para>
338 This feature is enabled if the freezer cgroup v1 controller is enabled
339 in the kernel.
340 </para>
341 </refsect2>
342
343 <refsect2>
344 <title>Getting information about container</title>
345 <para>
346 When there are a lot of containers, it is hard to follow what has been
347 created or destroyed, what is running or what are the PIDs running in a
348 specific container. For this reason, the following commands may be useful:
349 <programlisting>
350 lxc-ls -f
351 lxc-info -n foo
352 </programlisting>
353 </para>
354 <para>
355 <command>lxc-ls</command> lists containers.
356 </para>
357
358 <para>
359 <command>lxc-info</command> gives information for a specific container.
360 </para>
361
362 <para>
363 Here is an example on how the combination of these commands
364 allows one to list all the containers and retrieve their state.
365 <programlisting>
366 for i in $(lxc-ls -1); do
367 lxc-info -n $i
368 done
369 </programlisting>
370 </para>
371 </refsect2>
372
373 <refsect2>
374 <title>Monitoring container</title>
375 <para>
376 It is sometime useful to track the states of a container, for example to
377 monitor it or just to wait for a specific state in a script.
378 </para>
379
380 <para>
381 <command>lxc-monitor</command> command will monitor one or several
382 containers. The parameter of this command accepts a regular expression
383 for example:
384 <programlisting>
385 lxc-monitor -n "foo|bar"
386 </programlisting>
387 will monitor the states of containers named 'foo' and 'bar', and:
388 <programlisting>
389 lxc-monitor -n ".*"
390 </programlisting>
391 will monitor all the containers.
392 </para>
393 <para>
394 For a container 'foo' starting, doing some work and exiting,
395 the output will be in the form:
396 <programlisting>
397 'foo' changed state to [STARTING]
398 'foo' changed state to [RUNNING]
399 'foo' changed state to [STOPPING]
400 'foo' changed state to [STOPPED]
401 </programlisting>
402 </para>
403 <para>
404 <command>lxc-wait</command> command will wait for a specific
405 state change and exit. This is useful for scripting to
406 synchronize the launch of a container or the end. The
407 parameter is an ORed combination of different states. The
408 following example shows how to wait for a container if it successfully
409 started as a daemon.
410
411 <programlisting>
412 <![CDATA[
413 # launch lxc-wait in background
414 lxc-wait -n foo -s STOPPED &
415 LXC_WAIT_PID=$!
416
417 # this command goes in background
418 lxc-execute -n foo mydaemon &
419
420 # block until the lxc-wait exits
421 # and lxc-wait exits when the container
422 # is STOPPED
423 wait $LXC_WAIT_PID
424 echo "'foo' is finished"
425 ]]>
426 </programlisting>
427 </para>
428 </refsect2>
429
430 <refsect2>
431 <title>cgroup settings for containers</title>
432 <para>
433 The container is tied with the control groups, when a container is
434 started a control group is created and associated with it. The control
435 group properties can be read and modified when the container is running
436 by using the lxc-cgroup command.
437 </para>
438 <para>
439 <command>lxc-cgroup</command> command is used to set or get a
440 control group subsystem which is associated with a
441 container. The subsystem name is handled by the user, the
442 command won't do any syntax checking on the subsystem name, if
443 the subsystem name does not exists, the command will fail.
444 </para>
445 <para>
446 <programlisting>
447 lxc-cgroup -n foo cpuset.cpus
448 </programlisting>
449 will display the content of this subsystem.
450 <programlisting>
451 lxc-cgroup -n foo cpu.shares 512
452 </programlisting>
453 will set the subsystem to the specified value.
454 </para>
455 </refsect2>
456 </refsect1>
457
458 &seealso;
459
460 </refentry>
461
462 <!-- Keep this comment at the end of the file Local variables: mode:
463 sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil
464 sgml-always-quote-attributes:t sgml-indent-step:2 sgml-indent-data:t
465 sgml-parent-document:nil sgml-default-dtd-file:nil
466 sgml-exposed-tags:nil sgml-local-catalogs:nil
467 sgml-local-ecat-files:nil End: -->