Merge lp:~serge-hallyn/serverguide/serverguide-lxc into lp:~ubuntu-core-doc/serverguide/precise
- serverguide-lxc
- Merge into precise
Status: | Merged |
---|---|
Merged at revision: | 46 |
Proposed branch: | lp:~serge-hallyn/serverguide/serverguide-lxc |
Merge into: | lp:~ubuntu-core-doc/serverguide/precise |
Diff against target: |
1772 lines (+1764/-0) 1 file modified
serverguide/C/virtualization.xml (+1764/-0) |
To merge this branch: | bzr merge lp:~serge-hallyn/serverguide/serverguide-lxc |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Peter Matulis | Approve | ||
Serge Hallyn (community) | Needs Resubmitting | ||
Review via email: mp+97238@code.launchpad.net |
Commit message
Description of the change
This merge introduces a new LXC section. Some subsections are yet to be written, because they are contingent on work still going into precise.
Serge Hallyn (serge-hallyn) wrote : | # |
On 03/16/2012 02:52 PM, Peter Matulis wrote:
> Review: Needs Fixing
>
> This is a very significant contribution to the guide. Thank you!
>
> Technical:
>
> All tests performed using default settings and with a simple ubuntu-based container. I did not check all commands.
>
> 1. I tried to start a container (cn1) on a KVM guest. I was able to log in but shutting down threw warnings/errors. Normal?
Yes, the errors are normal. Should that be explained somewhere?
> -------
> $ sudo poweroff
> [sudo] password for ubuntu:
> $
> Broadcast message from ubuntu@cn1
> (/dev/lxc/console) at 18:17 ...
>
> The system is going down for power off NOW!
> * Asking all remaining processes to terminate...
> ...done.
> * All processes ended within 1 seconds....
> ...done.
> * Deconfiguring network interfaces...
> ...done.
> * Deactivating swap...
> ...fail!
> umount: /run/lock: not mounted
> umount: /dev/shm: not mounted
> mount: / is busy
> * Will now halt
> -------
>
>
> 2. This command output doesn't look right. Normal?:
>
> -------
> $ sudo lxc-start -n cn1 -d
> $ lxc-ls
> cn1
> cn1
>
> $ lxc-list
> RUNNING
>
> STOPPED
> -------
The lxc-list output doesn't look right - cn1 should show up in both
lists. The lxc-ls output shouldn't have the third (empty) line but
otherwise looks fine. I can't reproduce this.
I will address the rest in a merge proposal update. Thanks for the
comments!
- 50. By Serge Hallyn
-
Address a number of pmatulis' comments.
- 51. By Serge Hallyn
-
sudo
- 52. By Serge Hallyn
-
standardize use of LXC
- 53. By Serge Hallyn
-
remove <pre>
- 54. By Serge Hallyn
-
fix parse errors
- 55. By Serge Hallyn
-
namespac
- 56. By Serge Hallyn
-
write security section
- 57. By Serge Hallyn
-
remove udev comment
- 58. By Serge Hallyn
-
comment out virt-install libvirt-lxc section (it never worked for me)
Serge Hallyn (serge-hallyn) wrote : | # |
I believe the comments are now addressed, thanks.
Peter Matulis (petermatulis) wrote : | # |
All good. Very nice!
Preview Diff
1 | === modified file 'serverguide/C/virtualization.xml' | |||
2 | --- serverguide/C/virtualization.xml 2012-03-11 16:42:45 +0000 | |||
3 | +++ serverguide/C/virtualization.xml 2012-03-18 23:46:47 +0000 | |||
4 | @@ -2215,4 +2215,1768 @@ | |||
5 | 2215 | 2215 | ||
6 | 2216 | </sect2> | 2216 | </sect2> |
7 | 2217 | </sect1> | 2217 | </sect1> |
8 | 2218 | <sect1 id='lxc' status='review'> | ||
9 | 2219 | <title>LXC</title> | ||
10 | 2220 | <para> | ||
11 | 2221 | Containers are a lightweight virtualization technology. They are | ||
12 | 2222 | more akin to an enhanced chroot than to full virtualization like | ||
13 | 2223 | Qemu or VMware, both because they do not emulate hardware and | ||
14 | 2224 | because containers share the same operating system as the host. | ||
15 | 2225 | Therefore containers are better compared to Solaris zones or BSD | ||
16 | 2226 | jails. Linux-vserver and OpenVZ are two pre-existing, independently | ||
17 | 2227 | developed implementations of containers-like functionality for | ||
18 | 2228 | Linux. In fact, containers came about as a result of the work to | ||
19 | 2229 | upstream the vserver and OpenVZ functionality. Some vserver and | ||
20 | 2230 | OpenVZ functionality is still missing in containers, however | ||
21 | 2231 | containers can <emphasis>boot</emphasis> many Linux distributions and have the | ||
22 | 2232 | advantage that they can be used with an un-modified upstream kernel. | ||
23 | 2233 | </para> | ||
24 | 2234 | |||
25 | 2235 | <para> | ||
26 | 2236 | There are two user-space implementations of containers, each | ||
27 | 2237 | exploiting the same kernel features. Libvirt allows the use of | ||
28 | 2238 | containers through the LXC driver by connecting to 'lxc:///'. This | ||
29 | 2239 | can be very convenient as it supports the same usage as its other | ||
30 | 2240 | drivers. The other implementation, called simply 'LXC', is not | ||
31 | 2241 | compatible with libvirt, but is more flexible with more userspace | ||
32 | 2242 | tools. It is possible to switch between the two, though there are | ||
33 | 2243 | peculiarities which can cause confusion. | ||
34 | 2244 | </para> | ||
35 | 2245 | |||
36 | 2246 | <para> | ||
37 | 2247 | In this document we will mainly describe the <application>lxc</application> package. Toward | ||
38 | 2248 | the end, we will describe how to use the libvirt LXC driver. | ||
39 | 2249 | </para> | ||
40 | 2250 | |||
41 | 2251 | <para> | ||
42 | 2252 | In this document, a container name will be shown as CN, C1, or C2. | ||
43 | 2253 | </para> | ||
44 | 2254 | |||
45 | 2255 | <sect2 id="lxc-installation" status="review"> | ||
46 | 2256 | <title>Installation</title> | ||
47 | 2257 | <para> | ||
48 | 2258 | The <application>lxc</application> package can be installed using | ||
49 | 2259 | </para> | ||
50 | 2260 | |||
51 | 2261 | <screen> | ||
52 | 2262 | <command> | ||
53 | 2263 | sudo apt-get install lxc | ||
54 | 2264 | </command> | ||
55 | 2265 | </screen> | ||
56 | 2266 | |||
57 | 2267 | <para> | ||
58 | 2268 | This will pull in the required and recommended dependencies, including | ||
59 | 2269 | cgroup-lite, lvm2, and debootstrap. To use libvirt-lxc, install libvirt-bin. | ||
60 | 2270 | LXC and libvirt-lxc can be installed and used at the same time. | ||
61 | 2271 | </para> | ||
62 | 2272 | </sect2> | ||
63 | 2273 | |||
64 | 2274 | <sect2 id="lxc-hostsetup" status="review"> | ||
65 | 2275 | <title>Host Setup</title> | ||
66 | 2276 | <sect3 id="lxc-layout" status="review"> | ||
67 | 2277 | <title>Basic layout of LXC files</title> | ||
68 | 2278 | <para> | ||
69 | 2279 | Following is a description of the files and directories which | ||
70 | 2280 | are installed and used by LXC. | ||
71 | 2281 | </para> | ||
72 | 2282 | |||
73 | 2283 | <itemizedlist> | ||
74 | 2284 | <listitem> | ||
75 | 2285 | <para>There are two upstart jobs:</para> | ||
76 | 2286 | |||
77 | 2287 | <itemizedlist> <!-- nested list --> | ||
78 | 2288 | <listitem> | ||
79 | 2289 | <para> | ||
80 | 2290 | <filename>/etc/init/lxc-net.conf:</filename> is an optional job which | ||
81 | 2291 | only runs if <filename> /etc/default/lxc</filename> specifies | ||
82 | 2292 | USE_LXC_BRIDGE (true by default). It sets up a NATed bridge for | ||
83 | 2293 | containers to use. | ||
84 | 2294 | </para> | ||
85 | 2295 | </listitem> | ||
86 | 2296 | |||
87 | 2297 | <listitem> | ||
88 | 2298 | <para> | ||
89 | 2299 | <filename>/etc/init/lxc.conf:</filename> runs if LXC_AUTO (true by | ||
90 | 2300 | default) is set to | ||
91 | 2301 | true in <filename>/etc/default/lxc</filename>. It looks for entries | ||
92 | 2302 | under <filename>/etc/lxc/auto/</filename> which are symbolic links to | ||
93 | 2303 | configuration files for the containers which should be started at boot. | ||
94 | 2304 | </para> | ||
95 | 2305 | </listitem> | ||
96 | 2306 | </itemizedlist> | ||
97 | 2307 | |||
98 | 2308 | </listitem> | ||
99 | 2309 | <listitem> | ||
100 | 2310 | <para> | ||
101 | 2311 | <filename>/etc/lxc/lxc.conf:</filename> | ||
102 | 2312 | There is a default container creation configuration file, | ||
103 | 2313 | <filename>/etc/lxc/lxc.conf</filename>, which directs containers to use | ||
104 | 2314 | the LXC bridge created by the lxc-net upstart job. If no configuration | ||
105 | 2315 | file is specified when creating a container, then this one will be used. | ||
106 | 2316 | </para> | ||
107 | 2317 | </listitem> | ||
108 | 2318 | |||
109 | 2319 | <listitem> | ||
110 | 2320 | <para> | ||
111 | 2321 | Examples of other container creation configuration files are | ||
112 | 2322 | found under <filename>/usr/share/doc/lxc/examples</filename>. These show how to | ||
113 | 2323 | create containers without a private network, or using macvlan, | ||
114 | 2324 | vlan, or other network layouts. | ||
115 | 2325 | </para> | ||
116 | 2326 | </listitem> | ||
117 | 2327 | |||
118 | 2328 | <listitem> | ||
119 | 2329 | <para> | ||
120 | 2330 | The various container administration tools are found under | ||
121 | 2331 | <filename>/usr/bin</filename>. | ||
122 | 2332 | </para> | ||
123 | 2333 | </listitem> | ||
124 | 2334 | |||
125 | 2335 | <listitem> | ||
126 | 2336 | <para> | ||
127 | 2337 | <filename>/usr/lib/lxc/lxc-init</filename> is a very minimal and lightweight init | ||
128 | 2338 | binary which is used by lxc-execute. Rather than `booting' a | ||
129 | 2339 | full container, it manually mounts a few filesystems, especially | ||
130 | 2340 | <filename>/proc</filename>, and executes its arguments. You are not likely to need to | ||
131 | 2341 | manually refer to this file. | ||
132 | 2342 | </para> | ||
133 | 2343 | </listitem> | ||
134 | 2344 | |||
135 | 2345 | <listitem> | ||
136 | 2346 | <para> | ||
137 | 2347 | <filename>/usr/lib/lxc/templates/</filename> contains the `templates' which can be | ||
138 | 2348 | used to create new containers of various distributions and | ||
139 | 2349 | flavors. Not all templates are currently supported. | ||
140 | 2350 | </para> | ||
141 | 2351 | </listitem> | ||
142 | 2352 | |||
143 | 2353 | <listitem> | ||
144 | 2354 | <para> | ||
145 | 2355 | <filename>/etc/apparmor.d/usr.bin.lxc-start</filename> contains the (active by default) | ||
146 | 2356 | apparmor MAC policy which works to protect the host from containers. | ||
147 | 2357 | Please see the <xref linkend="lxc-security">Security</xref> section for more information. | ||
148 | 2358 | </para> | ||
149 | 2359 | </listitem> | ||
150 | 2360 | |||
151 | 2361 | <listitem> | ||
152 | 2362 | <para> | ||
153 | 2363 | There are various man pages for the LXC administration tools as well | ||
154 | 2364 | as the <filename>lxc.conf</filename> container configuration file. | ||
155 | 2365 | </para> | ||
156 | 2366 | </listitem> | ||
157 | 2367 | |||
158 | 2368 | <listitem> | ||
159 | 2369 | <para> | ||
160 | 2370 | <filename>/var/lib/lxc</filename> is where containers and their configuration information | ||
161 | 2371 | are stored. | ||
162 | 2372 | </para> | ||
163 | 2373 | </listitem> | ||
164 | 2374 | |||
165 | 2375 | <listitem> | ||
166 | 2376 | <para> | ||
167 | 2377 | <filename>/var/cache/lxc</filename> is where caches of distribution data are stored to | ||
168 | 2378 | speed up multiple container creations. | ||
169 | 2379 | </para> | ||
170 | 2380 | </listitem> | ||
171 | 2381 | </itemizedlist> | ||
172 | 2382 | </sect3> | ||
173 | 2383 | |||
174 | 2384 | <sect3 id="lxcbr0" status="review"> | ||
175 | 2385 | <title>lxcbr0</title> | ||
176 | 2386 | <para> | ||
177 | 2387 | When USE_LXC_BRIDGE is set to true in /etc/default/lxc (as it is by | ||
178 | 2388 | default), a bridge called lxcbr0 is created at startup. This bridge is | ||
179 | 2389 | given the private address 10.0.3.1, and containers using this bridge will | ||
180 | 2390 | have a 10.0.3.0/24 address. A dnsmasq instance is run listening on that | ||
181 | 2391 | bridge, so if another dnsmasq has bound all interfaces before the lxc-net | ||
182 | 2392 | upstart job runs, lxc-net will fail to start and lxcbr0 will not exist. | ||
183 | 2393 | </para> | ||
184 | 2394 | |||
185 | 2395 | <para> | ||
186 | 2396 | If you have another bridge - libvirt's default virbr0, or a br0 | ||
187 | 2397 | bridge for your default NIC - you can use that bridge in place of | ||
188 | 2398 | lxcbr0 for your containers. | ||
189 | 2399 | </para> | ||
190 | 2400 | </sect3> | ||
191 | 2401 | |||
192 | 2402 | <sect3 id="lxc-partitions" status="review"> | ||
193 | 2403 | <title>Using a separate filesystem for the container store</title> | ||
194 | 2404 | <para> | ||
195 | 2405 | LXC stores container information and (with the default backing store) root | ||
196 | 2406 | filesystems under <filename>/var/lib/lxc</filename>. Container creation | ||
197 | 2407 | templates also tend to store cached distribution information under | ||
198 | 2408 | <filename>/var/cache/lxc</filename>. | ||
199 | 2409 | </para> | ||
200 | 2410 | |||
201 | 2411 | <para> | ||
202 | 2412 | If you wish to use another filesystem than | ||
203 | 2413 | <filename>/var</filename>, you can mount a filesystem which has more space into those | ||
204 | 2414 | locations. If you have a disk dedicated for this, you can simply | ||
205 | 2415 | mount it at <filename>/var/lib/lxc</filename>. If you'd like to use another location, like | ||
206 | 2416 | <filename>/srv</filename>, you can bind mount it or use a symbolic link. For instance, if | ||
207 | 2417 | <filename>/srv</filename> is a large mounted filesystem, create and symlink two directories: | ||
208 | 2418 | </para> | ||
209 | 2419 | |||
210 | 2420 | <screen> | ||
211 | 2421 | <command> | ||
212 | 2422 | sudo mkdir /srv/lxclib /srv/lxccache | ||
213 | 2423 | sudo rm -rf /var/lib/lxc /var/cache/lxc | ||
214 | 2424 | sudo ln -s /srv/lxclib /var/lib/lxc | ||
215 | 2425 | sudo ln -s /srv/lxccache /var/cache/lxc | ||
216 | 2426 | </command> | ||
217 | 2427 | </screen> | ||
218 | 2428 | |||
219 | 2429 | <para> | ||
220 | 2430 | or, using bind mounts: | ||
221 | 2431 | </para> | ||
222 | 2432 | |||
223 | 2433 | <screen> | ||
224 | 2434 | <command> | ||
225 | 2435 | sudo mkdir /srv/lxclib /srv/lxccache | ||
226 | 2436 | sudo sed -i '$a \ | ||
227 | 2437 | /srv/lxclib /var/lib/lxc none defaults,bind 0 0 \ | ||
228 | 2438 | /srv/lxccache /var/cache/lxc none defaults,bind 0 0' /etc/fstab | ||
229 | 2439 | sudo mount -a | ||
230 | 2440 | </command> | ||
231 | 2441 | </screen> | ||
232 | 2442 | |||
233 | 2443 | </sect3> | ||
234 | 2444 | |||
235 | 2445 | <sect3 id="lxc-lvm" status="review"> | ||
236 | 2446 | <title>Containers backed by lvm</title> | ||
237 | 2447 | |||
238 | 2448 | <para> | ||
239 | 2449 | It is possible to use LVM partitions as the backing stores for | ||
240 | 2450 | containers. Advantages of this include flexibility in storage | ||
241 | 2451 | management and fast container cloning. The tools | ||
242 | 2452 | default to using a VG (volume group) named <emphasis>lxc</emphasis>, but another | ||
243 | 2453 | VG can be used through command line options. When a LV is used | ||
244 | 2454 | as a container backing store, the container's configuration file | ||
245 | 2455 | is still <filename>/var/lib/lxc/CN/config</filename>, but the root fs | ||
246 | 2456 | entry in that file (<emphasis>lxc.rootfs</emphasis>) will point to the lV block | ||
247 | 2457 | device name, i.e. <filename>/dev/lxc/CN</filename>. | ||
248 | 2458 | </para> | ||
249 | 2459 | |||
250 | 2460 | <para> | ||
251 | 2461 | Containers with directory tree and LVM backing stores can | ||
252 | 2462 | co-exist. | ||
253 | 2463 | </para> | ||
254 | 2464 | </sect3> | ||
255 | 2465 | |||
256 | 2466 | <sect3 id="lxc-btrfs" status="review"> | ||
257 | 2467 | <title>Btrfs</title> | ||
258 | 2468 | <para> | ||
259 | 2469 | If your host has a btrfs <filename>/var</filename>, the LXC administration | ||
260 | 2470 | tools will detect this and automatically exploit it by | ||
261 | 2471 | cloning containers using btrfs snapshots. | ||
262 | 2472 | </para> | ||
263 | 2473 | </sect3> | ||
264 | 2474 | |||
265 | 2475 | <sect3 id="lxc-apparmor" status="review"> | ||
266 | 2476 | <title>Apparmor</title> | ||
267 | 2477 | <para> | ||
268 | 2478 | LXC ships with an apparmor profile intended to protect the host | ||
269 | 2479 | from accidental misuses of privilege inside the container. For | ||
270 | 2480 | instance, the container will not be able to write to | ||
271 | 2481 | <filename>/proc/sysrq-trigger</filename> or to most <filename>/sys</filename> files. | ||
272 | 2482 | </para> | ||
273 | 2483 | </sect3> | ||
274 | 2484 | |||
275 | 2485 | <sect3 id="lxc-cgroups" status="review"> | ||
276 | 2486 | <title>Control Groups</title> | ||
277 | 2487 | <para> | ||
278 | 2488 | Control groups (cgroups) are a kernel feature providing hierarchical | ||
279 | 2489 | task grouping and per-cgroup resource accounting and limits. They are | ||
280 | 2490 | used in containers to limit block and character device access and to | ||
281 | 2491 | freeze (suspend) containers. They can be further used to limit memory | ||
282 | 2492 | use and block i/o, guarantee minimum cpu shares, and to lock containers | ||
283 | 2493 | to specific cpus. By default, LXC depends on the cgroup-lite package to be installed, which | ||
284 | 2494 | provides the proper cgroup initialization at boot. The cgroup-lite | ||
285 | 2495 | package mounts each cgroup subsystem separately under | ||
286 | 2496 | <filename>/sys/fs/cgroup/SS</filename>, where SS is the subsystem name. For instance | ||
287 | 2497 | the freezer subsystem is mounted under <filename>/sys/fs/cgroup/freezer</filename>. | ||
288 | 2498 | LXC cgroup are kept under <filename>/sys/fs/cgroup/SS/INIT/lxc</filename>, where | ||
289 | 2499 | INIT is the init task's cgroup. This is <filename>/</filename> by default, so | ||
290 | 2500 | in the end the freezer cgroup for container CN would be | ||
291 | 2501 | <filename>/sys/fs/cgroup/freezer/lxc/CN</filename>. | ||
292 | 2502 | </para> | ||
293 | 2503 | </sect3> | ||
294 | 2504 | |||
295 | 2505 | <sect3 id="lxc-privs" status="review"> | ||
296 | 2506 | <title>Privilege</title> | ||
297 | 2507 | <para> | ||
298 | 2508 | The container administration tools must be run with root user | ||
299 | 2509 | privilege. A utility called <filename>lxc-setup</filename> was written with the | ||
300 | 2510 | intention of providing the tools with the needed file capabilities to | ||
301 | 2511 | allow non-root users to run the tools with sufficient privilege. | ||
302 | 2512 | However, as root in a container cannot yet be reliably contained, this | ||
303 | 2513 | is not worthwhile. It is therefore recommended to not use | ||
304 | 2514 | <filename>lxc-setup</filename>, and to provide the LXC administrators the needed | ||
305 | 2515 | sudo privilege. | ||
306 | 2516 | </para> | ||
307 | 2517 | |||
308 | 2518 | <para> | ||
309 | 2519 | The user namespace, which is expected to be available in the next Long Term | ||
310 | 2520 | Support (LTS) release, will allow containment of the container root user, as | ||
311 | 2521 | well as reduce the amount of privilege required for creating and administering | ||
312 | 2522 | containers. | ||
313 | 2523 | </para> | ||
314 | 2524 | </sect3> | ||
315 | 2525 | |||
316 | 2526 | <sect3 id="lxc-upstart" status="review"> | ||
317 | 2527 | <title>LXC Upstart Jobs</title> | ||
318 | 2528 | <para> | ||
319 | 2529 | As listed above, the <application>lxc</application> package includes two upstart jobs. The | ||
320 | 2530 | first, <filename>lxc-net</filename>, is always started when the other, | ||
321 | 2531 | <filename>lxc</filename>, is about to begin, and stops when it stops. If the | ||
322 | 2532 | USE_LXC_BRIDGE variable is set to false in <filename>/etc/defaults/lxc</filename>, | ||
323 | 2533 | then it will immediately exit. If it is true, and an error occurs | ||
324 | 2534 | bringing up the LXC bridge, then the <filename>lxc</filename> job will not start. | ||
325 | 2535 | <filename>lxc-net</filename> will bring down the LXC bridge when stopped, unless | ||
326 | 2536 | a container is running which is using that bridge. | ||
327 | 2537 | </para> | ||
328 | 2538 | |||
329 | 2539 | <para> | ||
330 | 2540 | The <filename>lxc</filename> job starts on runlevel 2-5. If the LXC_AUTO variable | ||
331 | 2541 | is set to true, then it will look under <filename>/etc/lxc</filename> for containers | ||
332 | 2542 | which should be started automatically. When the <filename>lxc</filename> job is | ||
333 | 2543 | stopped, either manually or by entering runlevel 0, 1, or 6, it will | ||
334 | 2544 | stop those containers. | ||
335 | 2545 | </para> | ||
336 | 2546 | |||
337 | 2547 | <para> | ||
338 | 2548 | To register a container to start automatically, create a symbolic | ||
339 | 2549 | link <filename>/etc/default/lxc/name.conf</filename> pointing to the container's | ||
340 | 2550 | config file. For instance, the configuration file for a container | ||
341 | 2551 | <filename>CN</filename> is <filename>/var/lib/lxc/CN/config</filename>. To make that container | ||
342 | 2552 | auto-start, use the command: | ||
343 | 2553 | </para> | ||
344 | 2554 | |||
345 | 2555 | <screen> | ||
346 | 2556 | <command> | ||
347 | 2557 | sudo ln -s /var/lib/lxc/CN/config /etc/lxc/auto/CN.conf | ||
348 | 2558 | </command> | ||
349 | 2559 | </screen> | ||
350 | 2560 | </sect3> | ||
351 | 2561 | |||
352 | 2562 | </sect2> | ||
353 | 2563 | |||
354 | 2564 | <sect2 id="lxc-admin" status="review"> | ||
355 | 2565 | <title>Container Administration</title> | ||
356 | 2566 | <sect3 id="lxc-creation" status="review"> | ||
357 | 2567 | <title>Creating Containers</title> | ||
358 | 2568 | |||
359 | 2569 | <para> | ||
360 | 2570 | The easiest way to create containers is using <command>lxc-create</command>. This | ||
361 | 2571 | script uses distribution-specific templates under | ||
362 | 2572 | <filename>/usr/lib/lxc/templates/</filename> to set up container-friendly chroots under | ||
363 | 2573 | <filename>/var/lib/lxc/CN/rootfs</filename>, and initialize the configuration in | ||
364 | 2574 | <filename>/var/lib/lxc/CN/fstab</filename> and | ||
365 | 2575 | <filename>/var/lib/lxc/CN/config</filename>, where CN is the container name | ||
366 | 2576 | </para> | ||
367 | 2577 | |||
368 | 2578 | <para> | ||
369 | 2579 | The simplest container creation command would look like: | ||
370 | 2580 | </para> | ||
371 | 2581 | |||
372 | 2582 | <screen> | ||
373 | 2583 | <command> | ||
374 | 2584 | sudo lxc-create -t ubuntu -n CN | ||
375 | 2585 | </command> | ||
376 | 2586 | </screen> | ||
377 | 2587 | |||
378 | 2588 | <para> | ||
379 | 2589 | This tells lxc-create to use the ubuntu template (-t ubuntu) and to call | ||
380 | 2590 | the container CN (-n CN). Since no configuration file was specified | ||
381 | 2591 | (which would have been done with `-f file'), it will use the default | ||
382 | 2592 | configuration file under <filename>/etc/lxc/lxc.conf</filename>. This gives the container | ||
383 | 2593 | a single veth network interface attached to the lxcbr0 bridge. | ||
384 | 2594 | </para> | ||
385 | 2595 | |||
386 | 2596 | <para> | ||
387 | 2597 | The container creation templates can also accept arguments. These can | ||
388 | 2598 | be listed after --. For instance | ||
389 | 2599 | </para> | ||
390 | 2600 | |||
391 | 2601 | <screen> | ||
392 | 2602 | <command> | ||
393 | 2603 | sudo lxc-create -t ubuntu -n oneiric1 -- -r oneiric | ||
394 | 2604 | </command> | ||
395 | 2605 | </screen> | ||
396 | 2606 | |||
397 | 2607 | <para> | ||
398 | 2608 | passes the arguments '-r oneiric1' to the ubuntu template. | ||
399 | 2609 | </para> | ||
400 | 2610 | |||
401 | 2611 | <sect4 id="lxc-help" status="review"> | ||
402 | 2612 | <title>Help</title> | ||
403 | 2613 | <para> | ||
404 | 2614 | Help on the lxc-create command can be seen by using<command> lxc-create -h</command>. | ||
405 | 2615 | However, the templates also take their own options. If you do | ||
406 | 2616 | </para> | ||
407 | 2617 | |||
408 | 2618 | <screen> | ||
409 | 2619 | <command> | ||
410 | 2620 | sudo lxc-create -t ubuntu -h | ||
411 | 2621 | </command> | ||
412 | 2622 | </screen> | ||
413 | 2623 | |||
414 | 2624 | <para> | ||
415 | 2625 | then the general <command>lxc-create</command> help will be followed by help output | ||
416 | 2626 | specific to the ubuntu template. If no template is specified, then only | ||
417 | 2627 | help for <command>lxc-create</command> itself will be shown. | ||
418 | 2628 | </para> | ||
419 | 2629 | </sect4> | ||
420 | 2630 | |||
421 | 2631 | <sect4 id="lxc-ubuntu" status="review"> | ||
422 | 2632 | <title>Ubuntu template</title> | ||
423 | 2633 | |||
424 | 2634 | <para> | ||
425 | 2635 | The ubuntu template can be used to create Ubuntu system containers with any | ||
426 | 2636 | release at least as new as 10.04 LTS. It uses debootstrap to create | ||
427 | 2637 | a cached container filesystem which gets copied into place each time a | ||
428 | 2638 | container is created. The cached image is saved and only re-generated | ||
429 | 2639 | when you create a container | ||
430 | 2640 | using the <emphasis>-F</emphasis> (flush) option to the template, i.e.: | ||
431 | 2641 | </para> | ||
432 | 2642 | |||
433 | 2643 | <screen> | ||
434 | 2644 | <command> | ||
435 | 2645 | sudo lxc-create -t ubuntu -n CN -- -F | ||
436 | 2646 | </command> | ||
437 | 2647 | </screen> | ||
438 | 2648 | |||
439 | 2649 | <para> | ||
440 | 2650 | The Ubuntu release installed by the template will be the same as that on | ||
441 | 2651 | the host, unless otherwise specified with the <emphasis>-r</emphasis> option, i.e. | ||
442 | 2652 | </para> | ||
443 | 2653 | |||
444 | 2654 | <screen> | ||
445 | 2655 | <command> | ||
446 | 2656 | sudo lxc-create -t ubuntu -n CN -- -r lucid | ||
447 | 2657 | </command> | ||
448 | 2658 | </screen> | ||
449 | 2659 | |||
450 | 2660 | <para> | ||
451 | 2661 | If you want to create a 32-bit container on a 64-bit host, pass <emphasis>-a i386</emphasis> | ||
452 | 2662 | to the container. If you have the qemu-user-static package installed, then you can | ||
453 | 2663 | create a container using any architecture supported by qemu-user-static. | ||
454 | 2664 | </para> | ||
455 | 2665 | |||
456 | 2666 | <para> | ||
457 | 2667 | The container will have a user named <emphasis>ubuntu</emphasis> whose password is <emphasis>ubuntu</emphasis> | ||
458 | 2668 | and who is a member of the <emphasis>sudo</emphasis> group. If you wish to inject a public ssh | ||
459 | 2669 | key for the <emphasis>ubuntu</emphasis> user, you can do so with <emphasis>-S sshkey.pub</emphasis>. | ||
460 | 2670 | </para> | ||
461 | 2671 | |||
462 | 2672 | <para> | ||
463 | 2673 | You can also <emphasis>bind</emphasis> user jdoe from the host into the container using | ||
464 | 2674 | the <emphasis>-b jdoe</emphasis> option. This will copy jdoe's password and shadow | ||
465 | 2675 | entries into the container, make sure his default group and shell are | ||
466 | 2676 | available, add him to the sudo group, and bind-mount his home directory | ||
467 | 2677 | into the container when the container is started. | ||
468 | 2678 | </para> | ||
469 | 2679 | |||
470 | 2680 | <para> | ||
471 | 2681 | When a container is created, the <filename>release-updates</filename> archive is added | ||
472 | 2682 | to the container's <filename>sources.list</filename>, and its package archive will be | ||
473 | 2683 | updated. If the container release is older than 12.04 LTS, then the | ||
474 | 2684 | lxcguest package will be automatically installed. Alternatively, if the <emphasis>--trim</emphasis> | ||
475 | 2685 | option is specified, then the lxcguest package will not be installed, | ||
476 | 2686 | and many services will be removed from the container. This will result | ||
477 | 2687 | in a faster-booting, but less upgrade-able container. | ||
478 | 2688 | </para> | ||
479 | 2689 | </sect4> | ||
480 | 2690 | |||
481 | 2691 | <sect4 id="lxc-ubuntu-cloud" status="review"> | ||
482 | 2692 | <title>Ubuntu-cloud template</title> | ||
483 | 2693 | |||
484 | 2694 | <para> | ||
485 | 2695 | The ubuntu-cloud template creates Ubuntu containers by downloading and | ||
486 | 2696 | extracting the published Ubuntu cloud images. It accepts some of the same | ||
487 | 2697 | options as the ubuntu template, namely <emphasis>-r release</emphasis>, <emphasis>-S sshkey.pub</emphasis>, | ||
488 | 2698 | <emphasis>-a arch</emphasis>, and <emphasis>-F</emphasis> to flush the cached image. It also accepts a few | ||
489 | 2699 | extra options. The <emphasis>-C</emphasis> option will create a <emphasis>cloud</emphasis> container, | ||
490 | 2700 | configured for use with a metadata service. The <emphasis>-u</emphasis> option accepts a | ||
491 | 2701 | cloud-init user-data file to configure the container on start. If <emphasis>-L</emphasis> | ||
492 | 2702 | is passed, then no locales will be installed. The <emphasis>-T</emphasis> option can be | ||
493 | 2703 | used to choose a tarball location to extract in place of the published | ||
494 | 2704 | cloud image tarball. Finally the <emphasis>-i</emphasis> option sets a host id for | ||
495 | 2705 | cloud-init, which by default is set to a random string. | ||
496 | 2706 | </para> | ||
497 | 2707 | </sect4> | ||
498 | 2708 | |||
499 | 2709 | <sect4 id="lxc-other-templates" status="review"> | ||
500 | 2710 | <title> Other templates</title> | ||
501 | 2711 | |||
502 | 2712 | <para> | ||
503 | 2713 | The ubuntu and ubuntu-cloud templates are well supported. Other | ||
504 | 2714 | templates are available however. The debian template creates a | ||
505 | 2715 | Debian based container, using debootstrap much as the ubuntu | ||
506 | 2716 | template does. By default it installs a <emphasis>debian squeeze</emphasis> | ||
507 | 2717 | image. An alternate release can be chosen by setting the SUITE | ||
508 | 2718 | environment variable, i.e.: | ||
509 | 2719 | </para> | ||
510 | 2720 | |||
511 | 2721 | <screen> | ||
512 | 2722 | <command> | ||
513 | 2723 | sudo SUITE=sid lxc-create -t debian -n d1 | ||
514 | 2724 | </command> | ||
515 | 2725 | </screen> | ||
516 | 2726 | |||
517 | 2727 | <para> | ||
518 | 2728 | Since debian cannot be safely booted inside a container, debian | ||
519 | 2729 | containers will be trimmed as with the <emphasis>--trim</emphasis> option to | ||
520 | 2730 | the ubuntu template. | ||
521 | 2731 | </para> | ||
522 | 2732 | |||
523 | 2733 | <para> | ||
524 | 2734 | To purge the container image cache, call the template directly | ||
525 | 2735 | and pass it the <emphasis>--clean</emphasis> option. | ||
526 | 2736 | </para> | ||
527 | 2737 | |||
528 | 2738 | <screen> | ||
529 | 2739 | <command> | ||
530 | 2740 | sudo SUITE=sid /usr/lib/lxc/templates/lxc-debian --clean | ||
531 | 2741 | </command> | ||
532 | 2742 | </screen> | ||
533 | 2743 | |||
534 | 2744 | <para> | ||
535 | 2745 | A fedora template exists, which creates containers based on | ||
536 | 2746 | fedora releases <= 14. Fedora release 15 and higher are | ||
537 | 2747 | based on systemd, which the template is not yet able to convert | ||
538 | 2748 | into a container-bootable setup. Before the fedora template is | ||
539 | 2749 | able to run, you'll need to make sure that <command>yum</command> and <command>curl</command> | ||
540 | 2750 | are installed. A fedora 12 container can be created with | ||
541 | 2751 | </para> | ||
542 | 2752 | |||
543 | 2753 | <screen> | ||
544 | 2754 | <command> | ||
545 | 2755 | sudo lxc-create -t fedora -n fedora12 -- -R 12 | ||
546 | 2756 | </command> | ||
547 | 2757 | </screen> | ||
548 | 2758 | |||
549 | 2759 | <para> | ||
550 | 2760 | A OpenSuSE template exists, but it requires the <command>zypper</command> program, | ||
551 | 2761 | which is not yet packaged. The OpenSuSE template is therefore | ||
552 | 2762 | not supported. | ||
553 | 2763 | </para> | ||
554 | 2764 | |||
555 | 2765 | <para> | ||
556 | 2766 | Two more templates exist mainly for experimental purposes. The | ||
557 | 2767 | busybox template creates a very small system container based | ||
558 | 2768 | entirely on busybox. The sshd template creates an application | ||
559 | 2769 | container running sshd in a private network namespace. The | ||
560 | 2770 | host's library and binary directories are bind-mounted into the | ||
561 | 2771 | container, though not its <filename>/home</filename> or | ||
562 | 2772 | <filename>/root</filename>. To create, start, and ssh into an ssh | ||
563 | 2773 | container, you might: | ||
564 | 2774 | </para> | ||
565 | 2775 | |||
566 | 2776 | <screen> | ||
567 | 2777 | <command> | ||
568 | 2778 | sudo lxc-create -t sshd -n ssh1 | ||
569 | 2779 | ssh-keygen -f id | ||
570 | 2780 | sudo mkdir /var/lib/lxc/ssh1/rootfs/root/.ssh | ||
571 | 2781 | sudo cp id.pub /var/lib/lxc/ssh1/rootfs/root/.ssh/authorized_keys | ||
572 | 2782 | sudo lxc-start -n ssh1 -d | ||
573 | 2783 | ssh -i id root@ssh1. | ||
574 | 2784 | </command> | ||
575 | 2785 | </screen> | ||
576 | 2786 | |||
577 | 2787 | </sect4> | ||
578 | 2788 | |||
579 | 2789 | <sect4 id="lxc-backing-stores" status="review"> | ||
580 | 2790 | <title> Backing Stores</title> | ||
581 | 2791 | |||
582 | 2792 | <para> | ||
583 | 2793 | By default, <command>lxc-create</command> places the container's root | ||
584 | 2794 | filesystem as a directory tree at <filename>/var/lib/lxc/CN/rootfs.</filename> | ||
585 | 2795 | Another option is to use LVM logical volumes. If a volume group named <emphasis>lxc</emphasis> | ||
586 | 2796 | exists, you can create an lvm-backed container called CN using: | ||
587 | 2797 | </para> | ||
588 | 2798 | |||
589 | 2799 | <screen> | ||
590 | 2800 | <command> | ||
591 | 2801 | sudo lxc-create -t ubuntu -n CN -B lvm | ||
592 | 2802 | </command> | ||
593 | 2803 | </screen> | ||
594 | 2804 | |||
595 | 2805 | <para> | ||
596 | 2806 | If you want to use a volume group named schroots, with a 5G xfs | ||
597 | 2807 | filesystem, then you would use | ||
598 | 2808 | </para> | ||
599 | 2809 | |||
600 | 2810 | <screen> | ||
601 | 2811 | <command> | ||
602 | 2812 | sudo lxc-create -t ubuntu -n CN -B lvm --vgname schroots --fssize 5G --fstype xfs | ||
603 | 2813 | </command> | ||
604 | 2814 | </screen> | ||
605 | 2815 | </sect4> | ||
606 | 2816 | |||
607 | 2817 | </sect3> | ||
608 | 2818 | |||
609 | 2819 | <sect3 id="lxc-cloning" status="review"> | ||
610 | 2820 | <title>Cloning</title> | ||
611 | 2821 | |||
612 | 2822 | <para> | ||
613 | 2823 | For rapid provisioning, you may wish to customize a canonical | ||
614 | 2824 | container according to your needs and then make multiple copies of it. | ||
615 | 2825 | This can be done with the <command>lxc-clone</command> program. Given an existing | ||
616 | 2826 | container called C1, a new container called C2 can be created | ||
617 | 2827 | using | ||
618 | 2828 | </para> | ||
619 | 2829 | |||
620 | 2830 | |||
621 | 2831 | <screen> | ||
622 | 2832 | <command> | ||
623 | 2833 | sudo lxc-clone -o C1 -n C2 | ||
624 | 2834 | </command> | ||
625 | 2835 | </screen> | ||
626 | 2836 | |||
627 | 2837 | <para> | ||
628 | 2838 | If <filename>/var/lib/lxc</filename> is a btrfs filesystem, then | ||
629 | 2839 | <command>lxc-clone</command> will create C2's filesystem as a snapshot of | ||
630 | 2840 | C1's. If the container's root filesystem is lvm backed, then you can | ||
631 | 2841 | specify the <emphasis>-s</emphasis> option to create the new rootfs as a lvm snapshot of the | ||
632 | 2842 | original as follows: | ||
633 | 2843 | </para> | ||
634 | 2844 | |||
635 | 2845 | <screen> | ||
636 | 2846 | <command> | ||
637 | 2847 | sudo lxc-clone -s -o C1 -n C2 | ||
638 | 2848 | </command> | ||
639 | 2849 | </screen> | ||
640 | 2850 | |||
641 | 2851 | <para> | ||
642 | 2852 | Both lvm and btrfs snapshots will provide fast cloning with very | ||
643 | 2853 | small initial disk usage. | ||
644 | 2854 | </para> | ||
645 | 2855 | </sect3> | ||
646 | 2856 | |||
647 | 2857 | <sect3 id="lxc-start-stop" status="review"> | ||
648 | 2858 | <title>Starting and stopping</title> | ||
649 | 2859 | |||
650 | 2860 | <para> | ||
651 | 2861 | To start a container, use <command>lxc-start -n CN</command>. By default | ||
652 | 2862 | <command>lxc-start</command> will execute <filename>/sbin/init</filename> | ||
653 | 2863 | in the container. You can provide a different program to execute, plus | ||
654 | 2864 | arguments, as further arguments to <command>lxc-start</command>: | ||
655 | 2865 | </para> | ||
656 | 2866 | |||
657 | 2867 | <screen> | ||
658 | 2868 | <command> | ||
659 | 2869 | sudo lxc-start -n container /sbin/init loglevel=debug | ||
660 | 2870 | </command> | ||
661 | 2871 | </screen> | ||
662 | 2872 | |||
663 | 2873 | <para> | ||
664 | 2874 | If you do not specify the <emphasis>-d</emphasis> (daemon) option, then you will see a | ||
665 | 2875 | console (on the container's <filename>/dev/console</filename>, see | ||
666 | 2876 | <xref linkend="lxc-consoles"/> for more information) on the terminal. If | ||
667 | 2877 | you specify the <emphasis>-d</emphasis> option, you will not see that console, and lxc-start | ||
668 | 2878 | will immediately exit success - even if a later part of container startup | ||
669 | 2879 | has failed. You can use <command>lxc-wait</command> or | ||
670 | 2880 | <command>lxc-monitor</command> (see <xref | ||
671 | 2881 | linkend="lxc-monitoring"/>) to check on the success or failure of the | ||
672 | 2882 | container startup. | ||
673 | 2883 | </para> | ||
674 | 2884 | |||
675 | 2885 | <para> | ||
676 | 2886 | To obtain LXC debugging information, use <emphasis>-o filename -l debuglevel</emphasis>, | ||
677 | 2887 | for instance: | ||
678 | 2888 | </para> | ||
679 | 2889 | |||
680 | 2890 | <screen> | ||
681 | 2891 | <command> | ||
682 | 2892 | sudo lxc-start -o lxc.debug -l DEBUG -n container | ||
683 | 2893 | </command> | ||
684 | 2894 | </screen> | ||
685 | 2895 | |||
686 | 2896 | <para> | ||
687 | 2897 | Finally, you can specify configuration parameters inline using <emphasis>-s</emphasis>. | ||
688 | 2898 | However, it is generally recommended to place them in the container's | ||
689 | 2899 | configuration file instead. Likewise, an entirely alternate config | ||
690 | 2900 | file can be specified with the <emphasis>-f</emphasis> option, but this is not | ||
691 | 2901 | generally recommended. | ||
692 | 2902 | </para> | ||
693 | 2903 | |||
694 | 2904 | <para> | ||
695 | 2905 | While <command>lxc-start</command> runs the container's | ||
696 | 2906 | <filename>/sbin/init</filename>, <command>lxc-execute</command> uses a | ||
697 | 2907 | minimal init program called <command>lxc-init</command>, which attempts to | ||
698 | 2908 | mount <filename>/proc</filename>, <filename>/dev/mqueue</filename>, and | ||
699 | 2909 | <filename>/dev/shm</filename>, executes the programs specified on the | ||
700 | 2910 | command line, and waits for those to finish executing. | ||
701 | 2911 | <command>lxc-start</command> is intended to be used for <emphasis>system containers</emphasis>, | ||
702 | 2912 | while <command>lxc-execute</command> is intended for <emphasis>application | ||
703 | 2913 | containers</emphasis> (see <ulink url="https://www.ibm.com/developerworks/linux/library/l-lxc-containers/"> | ||
704 | 2914 | this article</ulink> for more). | ||
705 | 2915 | </para> | ||
706 | 2916 | |||
707 | 2917 | <para> | ||
708 | 2918 | You can stop a container several ways. You can use <command>shutdown</command>, | ||
709 | 2919 | <command>poweroff</command> and <command>reboot</command> while logged into | ||
710 | 2920 | the container. To cleanly shut down a container externally (i.e. from the host), you can issue | ||
711 | 2921 | the <command>sudo lxc-shutdown -n CN</command> command. This takes an optional | ||
712 | 2922 | timeout value. If not specified, the command issues a SIGPWR signal to the | ||
713 | 2923 | container and immediately returns. If the option is used, as in | ||
714 | 2924 | <command>sudo lxc-shutdown -n CN -t 10</command>, then the command will wait the | ||
715 | 2925 | specified number of seconds for the container to cleanly shut down. Then, | ||
716 | 2926 | if the container is still running, it will kill it (and any running | ||
717 | 2927 | applications). You can also immediately kill the container (without any | ||
718 | 2928 | chance for applications to cleanly shut down) using | ||
719 | 2929 | <command>sudo lxc-stop -n CN</command>. Finally, | ||
720 | 2930 | <command>lxc-kill</command> can be used more generally to send any signal | ||
721 | 2931 | number to the container's init. | ||
722 | 2932 | </para> | ||
723 | 2933 | |||
724 | 2934 | <para> | ||
725 | 2935 | While the container is shutting down, you can expect to see some (harmless) | ||
726 | 2936 | error messages, as follows: | ||
727 | 2937 | </para> | ||
728 | 2938 | |||
729 | 2939 | <screen> | ||
730 | 2940 | $ sudo poweroff | ||
731 | 2941 | [sudo] password for ubuntu: = | ||
732 | 2942 | |||
733 | 2943 | $ = | ||
734 | 2944 | |||
735 | 2945 | Broadcast message from ubuntu@cn1 | ||
736 | 2946 | (/dev/lxc/console) at 18:17 ... | ||
737 | 2947 | |||
738 | 2948 | The system is going down for power off NOW! | ||
739 | 2949 | * Asking all remaining processes to terminate... | ||
740 | 2950 | ...done. | ||
741 | 2951 | * All processes ended within 1 seconds.... | ||
742 | 2952 | ...done. | ||
743 | 2953 | * Deconfiguring network interfaces... | ||
744 | 2954 | ...done. | ||
745 | 2955 | * Deactivating swap... | ||
746 | 2956 | ...fail! | ||
747 | 2957 | umount: /run/lock: not mounted | ||
748 | 2958 | umount: /dev/shm: not mounted | ||
749 | 2959 | mount: / is busy | ||
750 | 2960 | * Will now halt | ||
751 | 2961 | </screen> | ||
752 | 2962 | |||
753 | 2963 | <para> | ||
754 | 2964 | A container can be frozen with <command>sudo lxc-freeze -n CN</command>. This | ||
755 | 2965 | will block all its processes until the container is later unfrozen using | ||
756 | 2966 | <command>sudo lxc-unfreeze -n CN</command>. | ||
757 | 2967 | </para> | ||
758 | 2968 | |||
759 | 2969 | </sect3> | ||
760 | 2970 | |||
761 | 2971 | <sect3 id="lxc-monitoring" status="review"> | ||
762 | 2972 | <title>Monitoring container status </title> | ||
763 | 2973 | |||
764 | 2974 | <para> | ||
765 | 2975 | Two commands are available to monitor container state changes. | ||
766 | 2976 | <command>lxc-monitor</command> monitors one or more containers for any | ||
767 | 2977 | state changes. It takes a container name as usual with the <emphasis>-n</emphasis> option, | ||
768 | 2978 | but in this case the container name can be a posix regular expression to | ||
769 | 2979 | allow monitoring desirable sets of containers. | ||
770 | 2980 | <command>lxc-monitor</command> continues running as it prints container | ||
771 | 2981 | changes. <command>lxc-wait</command> waits for a specific state change and | ||
772 | 2982 | then exits. For instance, | ||
773 | 2983 | </para> | ||
774 | 2984 | |||
775 | 2985 | |||
776 | 2986 | <screen> | ||
777 | 2987 | <command> | ||
778 | 2988 | sudo lxc-monitor -n cont[0-5]* | ||
779 | 2989 | </command> | ||
780 | 2990 | </screen> | ||
781 | 2991 | |||
782 | 2992 | <para> | ||
783 | 2993 | would print all state changes to any containers matching the | ||
784 | 2994 | listed regular expression, whereas | ||
785 | 2995 | </para> | ||
786 | 2996 | |||
787 | 2997 | <screen> | ||
788 | 2998 | <command> | ||
789 | 2999 | sudo lxc-wait -n cont1 -s 'STOPPED|FROZEN' | ||
790 | 3000 | </command> | ||
791 | 3001 | </screen> | ||
792 | 3002 | |||
793 | 3003 | <para> | ||
794 | 3004 | will wait until container cont1 enters state STOPPED or state FROZEN | ||
795 | 3005 | and then exit. | ||
796 | 3006 | </para> | ||
797 | 3007 | </sect3> | ||
798 | 3008 | |||
799 | 3009 | <sect3 id="lxc-consoles" status="review"> | ||
800 | 3010 | <title>Consoles</title> | ||
801 | 3011 | |||
802 | 3012 | <para> | ||
803 | 3013 | Containers have a configurable number of consoles. One always exists on | ||
804 | 3014 | the container's <filename>/dev/console.</filename> This is shown on the | ||
805 | 3015 | terminal from which you ran <command>lxc-start</command>, unless the <emphasis>-d</emphasis> | ||
806 | 3016 | option is specified. The output on <filename>/dev/console</filename> can | ||
807 | 3017 | be redirected to a file using the <emphasis>-c console-file</emphasis> option to | ||
808 | 3018 | <command>lxc-start</command>. The number of extra consoles is specified by | ||
809 | 3019 | the <command>lxc.tty</command> variable, and is usually set to 4. Those | ||
810 | 3020 | consoles are shown on <filename>/dev/ttyN</filename> (for 1 <= N <= | ||
811 | 3021 | 4). To log into console 3 from the host, use | ||
812 | 3022 | </para> | ||
813 | 3023 | |||
814 | 3024 | <screen> | ||
815 | 3025 | <command> | ||
816 | 3026 | sudo lxc-console -n container -t 3 | ||
817 | 3027 | </command> | ||
818 | 3028 | </screen> | ||
819 | 3029 | |||
820 | 3030 | <para> | ||
821 | 3031 | or if the <emphasis>-t N</emphasis> option is not specified, an unused console will be | ||
822 | 3032 | automatically chosen. To exit the console, use the escape sequence | ||
823 | 3033 | Ctrl-a q. Note that the escape sequence does not work in the console | ||
824 | 3034 | resulting from <command>lxc-start</command> without the <emphasis>-d</emphasis> | ||
825 | 3035 | option. | ||
826 | 3036 | </para> | ||
827 | 3037 | |||
828 | 3038 | <para> | ||
829 | 3039 | Each container console is actually a Unix98 pty in the host's (not the | ||
830 | 3040 | guest's) pty mount, bind-mounted over the guest's | ||
831 | 3041 | <filename>/dev/ttyN</filename> and <filename>/dev/console</filename>. | ||
832 | 3042 | Therefore, if the guest unmounts those or otherwise tries to access the | ||
833 | 3043 | actual character device <command>4:N</command>, it will not be serving | ||
834 | 3044 | getty to the LXC consoles. (With the default settings, the container will | ||
835 | 3045 | not be able to access that character device and getty will therefore fail.) | ||
836 | 3046 | This can easily happen when a boot script blindly mounts a new | ||
837 | 3047 | <filename>/dev</filename>. | ||
838 | 3048 | </para> | ||
839 | 3049 | </sect3> | ||
840 | 3050 | |||
841 | 3051 | <sect3 id="lxc-introspection" status="review"> | ||
842 | 3052 | <title>Container Inspection</title> | ||
843 | 3053 | |||
844 | 3054 | <para> | ||
845 | 3055 | Several commands are available to gather information on existing | ||
846 | 3056 | containers. <command>lxc-ls</command> will report all existing containers | ||
847 | 3057 | in its first line of output, and all running containers in the second line. | ||
848 | 3058 | <command>lxc-list</command> provides the same information in a more verbose | ||
849 | 3059 | format, listing running containers first and stopped containers next. | ||
850 | 3060 | <command>lxc-ps</command> will provide lists of processes in containers. | ||
851 | 3061 | To provide <command>ps</command> arguments to <command>lxc-ps</command>, | ||
852 | 3062 | prepend them with <command>--</command>. For instance, for listing of all | ||
853 | 3063 | processes in container plain, | ||
854 | 3064 | </para> | ||
855 | 3065 | |||
856 | 3066 | <screen> | ||
857 | 3067 | <command> | ||
858 | 3068 | sudo lxc-ps -n plain -- -ef | ||
859 | 3069 | </command> | ||
860 | 3070 | </screen> | ||
861 | 3071 | |||
862 | 3072 | <para> | ||
863 | 3073 | <command>lxc-info</command> provides the state of a container and the pid of its init | ||
864 | 3074 | process. <command>lxc-cgroup</command> can be used to query or set the values of a | ||
865 | 3075 | container's control group limits and information. This can be more convenient | ||
866 | 3076 | than interacting with the <command>cgroup</command> filesystem. For instance, to query | ||
867 | 3077 | the list of devices which a running container is allowed to access, | ||
868 | 3078 | you could use | ||
869 | 3079 | </para> | ||
870 | 3080 | |||
871 | 3081 | <screen> | ||
872 | 3082 | <command> | ||
873 | 3083 | sudo lxc-cgroup -n CN devices.list | ||
874 | 3084 | </command> | ||
875 | 3085 | </screen> | ||
876 | 3086 | |||
877 | 3087 | <para> | ||
878 | 3088 | or to add mknod, read, and write access to <filename>/dev/sda</filename>, | ||
879 | 3089 | </para> | ||
880 | 3090 | |||
881 | 3091 | <screen> | ||
882 | 3092 | <command> | ||
883 | 3093 | sudo lxc-cgroup -n CN devices.allow "b 8:* rwm" | ||
884 | 3094 | </command> | ||
885 | 3095 | </screen> | ||
886 | 3096 | |||
887 | 3097 | <para> | ||
888 | 3098 | and, to limit it to 300M of RAM, | ||
889 | 3099 | </para> | ||
890 | 3100 | |||
891 | 3101 | <screen> | ||
892 | 3102 | <command> | ||
893 | 3103 | lxc-cgroup -n CN memory.limit_in_bytes 300000000 | ||
894 | 3104 | </command> | ||
895 | 3105 | </screen> | ||
896 | 3106 | |||
897 | 3107 | <para> | ||
898 | 3108 | <command>lxc-netstat</command> executes <command>netstat</command> in the | ||
899 | 3109 | running container, giving you a glimpse of its network state. | ||
900 | 3110 | </para> | ||
901 | 3111 | |||
902 | 3112 | <para> | ||
903 | 3113 | <command>lxc-backup</command> will create backups of the root filesystems | ||
904 | 3114 | of all existing containers (except lvm-based ones), using | ||
905 | 3115 | <command>rsync</command> to back the contents up under | ||
906 | 3116 | <filename>/var/lib/lxc/CN/rootfs.backup.1</filename>. These backups can be | ||
907 | 3117 | restored using <command>lxc-restore.</command> However, | ||
908 | 3118 | <command>lxc-backup</command> and <command>lxc-restore</command> are | ||
909 | 3119 | fragile with respect to customizations and therefore their use is not | ||
910 | 3120 | recommended. | ||
911 | 3121 | </para> | ||
912 | 3122 | |||
913 | 3123 | </sect3> | ||
914 | 3124 | |||
915 | 3125 | <sect3 id="lxc-destroying" status="review"> | ||
916 | 3126 | <title>Destroying containers</title> | ||
917 | 3127 | |||
918 | 3128 | <para> | ||
919 | 3129 | Use <command>lxc-destroy</command> to destroy an existing container. | ||
920 | 3130 | </para> | ||
921 | 3131 | |||
922 | 3132 | <screen> | ||
923 | 3133 | <command> | ||
924 | 3134 | sudo lxc-destroy -n CN | ||
925 | 3135 | </command> | ||
926 | 3136 | </screen> | ||
927 | 3137 | |||
928 | 3138 | <para> | ||
929 | 3139 | If the container is running, <command>lxc-destroy</command> will exit with a message | ||
930 | 3140 | informing you that you can force stopping and destroying the container | ||
931 | 3141 | with | ||
932 | 3142 | </para> | ||
933 | 3143 | |||
934 | 3144 | <screen> | ||
935 | 3145 | <command> | ||
936 | 3146 | sudo lxc-destroy -n CN -f | ||
937 | 3147 | </command> | ||
938 | 3148 | </screen> | ||
939 | 3149 | |||
940 | 3150 | </sect3> | ||
941 | 3151 | |||
942 | 3152 | <sect3 id="lxc-namespaces" status="review"> | ||
943 | 3153 | <title>Advanced namespace usage</title> | ||
944 | 3154 | |||
945 | 3155 | <para> | ||
946 | 3156 | One of the Linux kernel features used by LXC to create containers is | ||
947 | 3157 | private namespaces. Namespaces allow a set of tasks to have private | ||
948 | 3158 | mappings of names to resources for things like pathnames and process | ||
949 | 3159 | IDs. (See <xref linkend="lxc-resources">Resources</xref> for a link | ||
950 | 3160 | to more information). Unlike control groups and other mount features which | ||
951 | 3161 | are also used to create containers, namespaces cannot be manipulated using | ||
952 | 3162 | a filesystem interface. Therefore, LXC ships with the <command>lxc-unshare</command> | ||
953 | 3163 | program, which is mainly for testing. It provides the ability to create | ||
954 | 3164 | new tasks in private namespaces. For instance, | ||
955 | 3165 | </para> | ||
956 | 3166 | |||
957 | 3167 | <screen> | ||
958 | 3168 | <command> | ||
959 | 3169 | sudo lxc-unshare -s 'MOUNT|PID' /bin/bash | ||
960 | 3170 | </command> | ||
961 | 3171 | </screen> | ||
962 | 3172 | |||
963 | 3173 | <para> | ||
964 | 3174 | creates a bash shell with private pid and mount namespaces. | ||
965 | 3175 | In this shell, you can do | ||
966 | 3176 | </para> | ||
967 | 3177 | |||
968 | 3178 | <screen> | ||
969 | 3179 | root@ubuntu:~# mount -t proc proc /proc | ||
970 | 3180 | root@ubuntu:~# ps -ef | ||
971 | 3181 | UID PID PPID C STIME TTY TIME CMD | ||
972 | 3182 | root 1 0 6 10:20 pts/9 00:00:00 /bin/bash | ||
973 | 3183 | root 110 1 0 10:20 pts/9 00:00:00 ps -ef | ||
974 | 3184 | </screen> | ||
975 | 3185 | |||
976 | 3186 | <para> | ||
977 | 3187 | so that <command>ps</command> shows only the tasks in your new namespace. | ||
978 | 3188 | </para> | ||
979 | 3189 | </sect3> | ||
980 | 3190 | |||
981 | 3191 | <sect3 id="lxc-ephemeral" status="review"> | ||
982 | 3192 | <title>Ephemeral containers</title> | ||
983 | 3193 | |||
984 | 3194 | <para> | ||
985 | 3195 | Ephemeral containers are one-time containers. Given an existing | ||
986 | 3196 | container CN, you can run a command in an ephemeral container | ||
987 | 3197 | created based on CN, with the host's jdoe user bound into the | ||
988 | 3198 | container, using: | ||
989 | 3199 | </para> | ||
990 | 3200 | |||
991 | 3201 | <screen> | ||
992 | 3202 | <command> | ||
993 | 3203 | lxc-start-ephemeral -b jdoe -o CN -- /home/jdoe/run_my_job | ||
994 | 3204 | </command> | ||
995 | 3205 | </screen> | ||
996 | 3206 | |||
997 | 3207 | <para> | ||
998 | 3208 | When the job is finished, the container will be discarded. | ||
999 | 3209 | </para> | ||
1000 | 3210 | |||
1001 | 3211 | </sect3> | ||
1002 | 3212 | <sect3 id="lxc-commands" status="review"> | ||
1003 | 3213 | <title>Container Commands</title> | ||
1004 | 3214 | |||
1005 | 3215 | Following is a table of all container commands: | ||
1006 | 3216 | |||
1007 | 3217 | <table> | ||
1008 | 3218 | <title> Container commands</title> | ||
1009 | 3219 | <tgroup cols="2" rowsep="1"> | ||
1010 | 3220 | <thead> | ||
1011 | 3221 | <row> | ||
1012 | 3222 | <entry valign="left"><para>Command</para></entry> | ||
1013 | 3223 | <entry valign="left"><para>Synopsis</para></entry> | ||
1014 | 3224 | </row> | ||
1015 | 3225 | </thead> | ||
1016 | 3226 | <tbody> | ||
1017 | 3227 | <row> | ||
1018 | 3228 | <entry><para>lxc-attach </para></entry> | ||
1019 | 3229 | <entry><para>(NOT SUPPORTED) Run a command in a running container</para></entry> | ||
1020 | 3230 | </row> | ||
1021 | 3231 | <row> | ||
1022 | 3232 | <entry><para>lxc-backup </para></entry> | ||
1023 | 3233 | <entry><para>Back up the root filesystems for all lvm-backed containers</para></entry> | ||
1024 | 3234 | </row> | ||
1025 | 3235 | <row> | ||
1026 | 3236 | <entry><para>lxc-cgroup </para></entry> | ||
1027 | 3237 | <entry><para>View and set container control group settings</para></entry> | ||
1028 | 3238 | </row> | ||
1029 | 3239 | <row> | ||
1030 | 3240 | <entry><para>lxc-checkconfig </para></entry> | ||
1031 | 3241 | <entry><para>Verify host support for containers</para></entry> | ||
1032 | 3242 | </row> | ||
1033 | 3243 | <row> | ||
1034 | 3244 | <entry><para>lxc-checkpoint </para></entry> | ||
1035 | 3245 | <entry><para>(NOT SUPPORTED) Checkpoint a running container</para></entry> | ||
1036 | 3246 | </row> | ||
1037 | 3247 | <row> | ||
1038 | 3248 | <entry><para>lxc-clone </para></entry> | ||
1039 | 3249 | <entry><para>Clone a new container from an existing one</para></entry> | ||
1040 | 3250 | </row> | ||
1041 | 3251 | <row> | ||
1042 | 3252 | <entry><para>lxc-console </para></entry> | ||
1043 | 3253 | <entry><para>Open a console in a running container</para></entry> | ||
1044 | 3254 | </row> | ||
1045 | 3255 | <row> | ||
1046 | 3256 | <entry><para>lxc-create </para></entry> | ||
1047 | 3257 | <entry><para>Create a new container</para></entry> | ||
1048 | 3258 | </row> | ||
1049 | 3259 | <row> | ||
1050 | 3260 | <entry><para>lxc-destroy </para></entry> | ||
1051 | 3261 | <entry><para>Destroy an existing container</para></entry> | ||
1052 | 3262 | </row> | ||
1053 | 3263 | <row> | ||
1054 | 3264 | <entry><para>lxc-execute </para></entry> | ||
1055 | 3265 | <entry><para>Run a command in a (not running) application container</para></entry> | ||
1056 | 3266 | </row> | ||
1057 | 3267 | <row> | ||
1058 | 3268 | <entry><para>lxc-freeze </para></entry> | ||
1059 | 3269 | <entry><para>Freeze a running container</para></entry> | ||
1060 | 3270 | </row> | ||
1061 | 3271 | <row> | ||
1062 | 3272 | <entry><para>lxc-info </para></entry> | ||
1063 | 3273 | <entry><para>Print information on the state of a container</para></entry> | ||
1064 | 3274 | </row> | ||
1065 | 3275 | <row> | ||
1066 | 3276 | <entry><para>lxc-kill </para></entry> | ||
1067 | 3277 | <entry><para>Send a signal to a container's init</para></entry> | ||
1068 | 3278 | </row> | ||
1069 | 3279 | <row> | ||
1070 | 3280 | <entry><para>lxc-list </para></entry> | ||
1071 | 3281 | <entry><para>List all containers</para></entry> | ||
1072 | 3282 | </row> | ||
1073 | 3283 | <row> | ||
1074 | 3284 | <entry><para>lxc-ls </para></entry> | ||
1075 | 3285 | <entry><para>List all containers with shorter output than lxc-list</para></entry> | ||
1076 | 3286 | </row> | ||
1077 | 3287 | <row> | ||
1078 | 3288 | <entry><para>lxc-monitor </para></entry> | ||
1079 | 3289 | <entry><para>Monitor state changes of one or more containers</para></entry> | ||
1080 | 3290 | </row> | ||
1081 | 3291 | <row> | ||
1082 | 3292 | <entry><para>lxc-netstat </para></entry> | ||
1083 | 3293 | <entry><para>Execute netstat in a running container</para></entry> | ||
1084 | 3294 | </row> | ||
1085 | 3295 | <row> | ||
1086 | 3296 | <entry><para>lxc-ps </para></entry> | ||
1087 | 3297 | <entry><para>View process info in a running container</para></entry> | ||
1088 | 3298 | </row> | ||
1089 | 3299 | <row> | ||
1090 | 3300 | <entry><para>lxc-restart </para></entry> | ||
1091 | 3301 | <entry><para>(NOT SUPPORTED) Restart a checkpointed container</para></entry> | ||
1092 | 3302 | </row> | ||
1093 | 3303 | <row> | ||
1094 | 3304 | <entry><para>lxc-restore </para></entry> | ||
1095 | 3305 | <entry><para>Restore containers from backups made by lxc-backup</para></entry> | ||
1096 | 3306 | </row> | ||
1097 | 3307 | <row> | ||
1098 | 3308 | <entry><para>lxc-setcap </para></entry> | ||
1099 | 3309 | <entry><para>(NOT RECOMMENDED) Set file capabilities on LXC tools</para></entry> | ||
1100 | 3310 | </row> | ||
1101 | 3311 | <row> | ||
1102 | 3312 | <entry><para>lxc-setuid </para></entry> | ||
1103 | 3313 | <entry><para>(NOT RECOMMENDED) Set or remove setuid bits on LXC tools</para></entry> | ||
1104 | 3314 | </row> | ||
1105 | 3315 | <row> | ||
1106 | 3316 | <entry><para>lxc-shutdown </para></entry> | ||
1107 | 3317 | <entry><para>Safely shut down a container</para></entry> | ||
1108 | 3318 | </row> | ||
1109 | 3319 | <row> | ||
1110 | 3320 | <entry><para>lxc-start </para></entry> | ||
1111 | 3321 | <entry><para>Start a stopped container</para></entry> | ||
1112 | 3322 | </row> | ||
1113 | 3323 | <row> | ||
1114 | 3324 | <entry><para>lxc-start-ephemeral </para></entry> | ||
1115 | 3325 | <entry><para>Start an ephemeral (one-time) container</para></entry> | ||
1116 | 3326 | </row> | ||
1117 | 3327 | <row> | ||
1118 | 3328 | <entry><para>lxc-stop </para></entry> | ||
1119 | 3329 | <entry><para>Immediately stop a running container</para></entry> | ||
1120 | 3330 | </row> | ||
1121 | 3331 | <row> | ||
1122 | 3332 | <entry><para>lxc-unfreeze </para></entry> | ||
1123 | 3333 | <entry><para>Unfreeze a frozen container</para></entry> | ||
1124 | 3334 | </row> | ||
1125 | 3335 | <row> | ||
1126 | 3336 | <entry><para>lxc-unshare </para></entry> | ||
1127 | 3337 | <entry><para>Testing tool to manually unshare namespaces</para></entry> | ||
1128 | 3338 | </row> | ||
1129 | 3339 | <row> | ||
1130 | 3340 | <entry><para>lxc-version </para></entry> | ||
1131 | 3341 | <entry><para>Print the version of the LXC tools</para></entry> | ||
1132 | 3342 | </row> | ||
1133 | 3343 | <row> | ||
1134 | 3344 | <entry><para>lxc-wait </para></entry> | ||
1135 | 3345 | <entry><para>Wait for a container to reach a particular state</para></entry> | ||
1136 | 3346 | </row> | ||
1137 | 3347 | </tbody> | ||
1138 | 3348 | </tgroup> | ||
1139 | 3349 | </table> | ||
1140 | 3350 | |||
1141 | 3351 | </sect3> | ||
1142 | 3352 | </sect2> | ||
1143 | 3353 | |||
1144 | 3354 | <sect2 id="lxc-conf" status="review"> | ||
1145 | 3355 | <title>Configuration File</title> | ||
1146 | 3356 | |||
1147 | 3357 | <para> | ||
1148 | 3358 | LXC containers are very flexible. The Ubuntu <application>lxc</application> package sets defaults | ||
1149 | 3359 | to make creation of Ubuntu system containers as simple as possible. | ||
1150 | 3360 | If you need more flexibility, this chapter will show how to fine-tune | ||
1151 | 3361 | your containers as you need. | ||
1152 | 3362 | </para> | ||
1153 | 3363 | |||
1154 | 3364 | <para> | ||
1155 | 3365 | Detailed information is available in the <command>lxc.conf(5)</command> man page. | ||
1156 | 3366 | Note that the default configurations created by the ubuntu templates | ||
1157 | 3367 | are reasonable for a system container and usually do not need | ||
1158 | 3368 | customization. | ||
1159 | 3369 | </para> | ||
1160 | 3370 | |||
1161 | 3371 | <sect3 id="lxc-conf-options" status="review"> | ||
1162 | 3372 | <title>Choosing configuration files and options</title> | ||
1163 | 3373 | |||
1164 | 3374 | <para> | ||
1165 | 3375 | The container setup is controlled by the LXC configuration options. | ||
1166 | 3376 | Options can be specified at several points: | ||
1167 | 3377 | </para> | ||
1168 | 3378 | |||
1169 | 3379 | <itemizedlist> | ||
1170 | 3380 | <listitem><para> | ||
1171 | 3381 | During container creation, a configuration file can be specified. | ||
1172 | 3382 | However, creation templates often insert their own configuration | ||
1173 | 3383 | options, so we usually specify only network configuration options at | ||
1174 | 3384 | this point. For other configuration, it is usually better to edit the | ||
1175 | 3385 | configuration file after container creation. | ||
1176 | 3386 | </para></listitem> | ||
1177 | 3387 | |||
1178 | 3388 | <listitem><para> | ||
1179 | 3389 | The file <filename>/var/lib/lxc/CN/config</filename> is used at | ||
1180 | 3390 | container startup by default. | ||
1181 | 3391 | </para></listitem> | ||
1182 | 3392 | |||
1183 | 3393 | <listitem><para> | ||
1184 | 3394 | <command>lxc-start</command> accepts an alternate configuration file with | ||
1185 | 3395 | the <emphasis>-f filename</emphasis> option. | ||
1186 | 3396 | </para></listitem> | ||
1187 | 3397 | |||
1188 | 3398 | <listitem><para> | ||
1189 | 3399 | Specific configuration variables can be overridden at <command>lxc-start</command> | ||
1190 | 3400 | using <emphasis>-s key=value</emphasis>. It is generally better to edit the container | ||
1191 | 3401 | configuration file. | ||
1192 | 3402 | </para></listitem> | ||
1193 | 3403 | |||
1194 | 3404 | </itemizedlist> | ||
1195 | 3405 | |||
1196 | 3406 | </sect3> | ||
1197 | 3407 | |||
1198 | 3408 | <sect3 id="lxc-conf-net" status="review"> | ||
1199 | 3409 | <title>Network Configuration</title> | ||
1200 | 3410 | |||
1201 | 3411 | <para> | ||
1202 | 3412 | Container networking in LXC is very flexible. It is triggered by | ||
1203 | 3413 | the <command>lxc.network.type</command> configuration file entries. | ||
1204 | 3414 | If no such entries exist, then the container will share the host's | ||
1205 | 3415 | networking stack. Services and connections started in the container | ||
1206 | 3416 | will be using the host's IP address. | ||
1207 | 3417 | If at least one <command>lxc.network.type</command> entry is present, then the container | ||
1208 | 3418 | will have a private (layer 2) network stack. It will have its own | ||
1209 | 3419 | network interfaces and firewall rules. There are several options | ||
1210 | 3420 | for <command>lxc.network.type</command>: | ||
1211 | 3421 | </para> | ||
1212 | 3422 | |||
1213 | 3423 | <itemizedlist> | ||
1214 | 3424 | <listitem><para> | ||
1215 | 3425 | <command>lxc.network.type=empty</command>: | ||
1216 | 3426 | The container will have no network interfaces other than loopback. | ||
1217 | 3427 | </para></listitem> | ||
1218 | 3428 | |||
1219 | 3429 | <listitem><para> | ||
1220 | 3430 | <command>lxc.network.type=veth</command>: | ||
1221 | 3431 | This is the default when using the ubuntu or ubuntu-cloud templates, | ||
1222 | 3432 | and creates a veth network tunnel. One end of this tunnel | ||
1223 | 3433 | becomes the network interface inside the container. The other end | ||
1224 | 3434 | is attached to a bridged on the host. Any number of such tunnels | ||
1225 | 3435 | can be created by adding more <command>lxc.network.type=veth</command> | ||
1226 | 3436 | entries in the container configuration file. The bridge to which the | ||
1227 | 3437 | host end of the tunnel will be attached is specified with | ||
1228 | 3438 | <command>lxc.network.link = lxcbr0</command>. | ||
1229 | 3439 | </para></listitem> | ||
1230 | 3440 | |||
1231 | 3441 | <listitem><para> | ||
1232 | 3442 | <command>lxc.network.type=phys</command> | ||
1233 | 3443 | A physical network interface (i.e. eth2) is passed into the container. | ||
1234 | 3444 | </para></listitem> | ||
1235 | 3445 | </itemizedlist> | ||
1236 | 3446 | |||
1237 | 3447 | <para> | ||
1238 | 3448 | Two other options are to | ||
1239 | 3449 | use vlan or macvlan, however their use is more complicated and is | ||
1240 | 3450 | not described here. A few other networking options exist: | ||
1241 | 3451 | </para> | ||
1242 | 3452 | |||
1243 | 3453 | <itemizedlist> | ||
1244 | 3454 | <listitem><para> | ||
1245 | 3455 | <command>lxc.network.flags</command> can only be set to <emphasis>up</emphasis> and ensures that the network interface is up. | ||
1246 | 3456 | </para></listitem> | ||
1247 | 3457 | |||
1248 | 3458 | <listitem><para> | ||
1249 | 3459 | <command>lxc.network.hwaddr</command> specifies a mac address to assign the the | ||
1250 | 3460 | nic inside the container. | ||
1251 | 3461 | </para></listitem> | ||
1252 | 3462 | |||
1253 | 3463 | <listitem><para> | ||
1254 | 3464 | <command>lxc.network.ipv4</command> and <command>lxc.network.ipv6</command> | ||
1255 | 3465 | set the respective IP addresses, if those should be static. | ||
1256 | 3466 | </para></listitem> | ||
1257 | 3467 | |||
1258 | 3468 | <listitem><para> | ||
1259 | 3469 | <command>lxc.network.name</command> specifies a name to assign inside the | ||
1260 | 3470 | container. If this is not specified, a good default (i.e. eth0 for the | ||
1261 | 3471 | first nic) is chosen. | ||
1262 | 3472 | </para></listitem> | ||
1263 | 3473 | |||
1264 | 3474 | <listitem><para> | ||
1265 | 3475 | <command>lxc.network.lxcscript.up</command> specifies a script to be called | ||
1266 | 3476 | after the host side of the networking has been set up. See the | ||
1267 | 3477 | <command>lxc.conf(5)</command> manual page for details. | ||
1268 | 3478 | </para></listitem> | ||
1269 | 3479 | </itemizedlist> | ||
1270 | 3480 | |||
1271 | 3481 | </sect3> | ||
1272 | 3482 | |||
1273 | 3483 | <sect3 id="lxc-conf-cgroup" status="review"> | ||
1274 | 3484 | <title>Control group configuration</title> | ||
1275 | 3485 | |||
1276 | 3486 | <para> | ||
1277 | 3487 | Cgroup options can be specified using <command>lxc.cgroup</command> | ||
1278 | 3488 | entries. <command>lxc.cgroup.subsystem.item = value</command> instructs | ||
1279 | 3489 | LXC to set cgroup <command>subsystem</command>'s <command>item</command> to | ||
1280 | 3490 | <command>value</command>. It is perhaps simpler to realize that this will | ||
1281 | 3491 | simply write <command>value</command> to the file <command>item</command> | ||
1282 | 3492 | for the container's control group for subsystem | ||
1283 | 3493 | <command>subsystem</command>. For instance, to set the memory limit to | ||
1284 | 3494 | 320M, you could add | ||
1285 | 3495 | </para> | ||
1286 | 3496 | |||
1287 | 3497 | <screen> | ||
1288 | 3498 | <command> | ||
1289 | 3499 | lxc.cgroup.memory.limit_in_bytes = 320000000 | ||
1290 | 3500 | </command> | ||
1291 | 3501 | </screen> | ||
1292 | 3502 | |||
1293 | 3503 | <para> | ||
1294 | 3504 | which will cause 320000000 to be written to the file | ||
1295 | 3505 | <filename>/sys/fs/cgroup/memory/lxc/CN/limit_in_bytes</filename>. | ||
1296 | 3506 | </para> | ||
1297 | 3507 | </sect3> | ||
1298 | 3508 | |||
1299 | 3509 | <sect3 id="lxc-conf-mounts" status="review"> | ||
1300 | 3510 | <title>Rootfs, mounts and fstab</title> | ||
1301 | 3511 | |||
1302 | 3512 | <para> | ||
1303 | 3513 | An important part of container setup is the mounting of various | ||
1304 | 3514 | filesystems into place. The following is an example configuration file | ||
1305 | 3515 | excerpt demonstrating the commonly used configuration options: | ||
1306 | 3516 | </para> | ||
1307 | 3517 | |||
1308 | 3518 | <screen> | ||
1309 | 3519 | <command> | ||
1310 | 3520 | lxc.rootfs = /var/lib/lxc/CN/rootfs | ||
1311 | 3521 | lxc.mount.entry=proc /var/lib/lxc/CN/rootfs/proc proc nodev,noexec,nosuid 0 0 | ||
1312 | 3522 | lxc.mount = /var/lib/lxc/CN/fstab | ||
1313 | 3523 | </command> | ||
1314 | 3524 | </screen> | ||
1315 | 3525 | |||
1316 | 3526 | <para> | ||
1317 | 3527 | The first line says that the container's root filesystem is already mounted | ||
1318 | 3528 | at <filename>/var/lib/lxc/CN/rootfs</filename>. If the filesystem is a | ||
1319 | 3529 | block device (such as an LVM logical volume), then the path to the block | ||
1320 | 3530 | device must be given instead. | ||
1321 | 3531 | </para> | ||
1322 | 3532 | |||
1323 | 3533 | <para> | ||
1324 | 3534 | Each <command>lxc.mount.entry</command> line should contain an item to | ||
1325 | 3535 | mount in valid fstab format. The target directory should be prefixed by | ||
1326 | 3536 | <filename>/var/lib/lxc/CN/rootfs</filename>, even if | ||
1327 | 3537 | <command>lxc.rootfs</command> points to a block device. | ||
1328 | 3538 | </para> | ||
1329 | 3539 | |||
1330 | 3540 | <para> | ||
1331 | 3541 | Finally, <command>lxc.mount</command> points to a file, in fstab format, | ||
1332 | 3542 | containing further items to mount. Note that all of these entries will be | ||
1333 | 3543 | mounted by the host before the container init is started. In this way it | ||
1334 | 3544 | is possible to bind mount various directories from the host into the | ||
1335 | 3545 | container. | ||
1336 | 3546 | </para> | ||
1337 | 3547 | </sect3> | ||
1338 | 3548 | |||
1339 | 3549 | <sect3 id="lxc-conf-other" status="review"> | ||
1340 | 3550 | <title>Other configuration options</title> | ||
1341 | 3551 | |||
1342 | 3552 | <itemizedlist> | ||
1343 | 3553 | |||
1344 | 3554 | <listitem> | ||
1345 | 3555 | <para> | ||
1346 | 3556 | <command>lxc.cap.drop</command> can be used to prevent the container from having | ||
1347 | 3557 | or ever obtaining the listed capabilities. For instance, including | ||
1348 | 3558 | </para> | ||
1349 | 3559 | |||
1350 | 3560 | <screen> | ||
1351 | 3561 | <command> | ||
1352 | 3562 | lxc.cap.drop = sys_admin | ||
1353 | 3563 | </command> | ||
1354 | 3564 | </screen> | ||
1355 | 3565 | |||
1356 | 3566 | <para> | ||
1357 | 3567 | will prevent the container from mounting filesystems, as well as all other | ||
1358 | 3568 | actions which require cap_sys_admin. See the <command>capabilities(7)</command> | ||
1359 | 3569 | manual page for a list of capabilities and their meanings. | ||
1360 | 3570 | </para> | ||
1361 | 3571 | </listitem> | ||
1362 | 3572 | |||
1363 | 3573 | <listitem><para> | ||
1364 | 3574 | <command>lxc.console=/path/to/consolefile</command> will cause console | ||
1365 | 3575 | messages to be written to the specified file. | ||
1366 | 3576 | </para></listitem> | ||
1367 | 3577 | |||
1368 | 3578 | <listitem><para> | ||
1369 | 3579 | <command>lxc.arch</command> specifies the architecture for the container, for instance | ||
1370 | 3580 | x86, or x86_64. | ||
1371 | 3581 | </para></listitem> | ||
1372 | 3582 | |||
1373 | 3583 | <listitem><para> | ||
1374 | 3584 | <command>lxc.tty=5</command> specifies that 5 consoles (in addition to | ||
1375 | 3585 | <filename>/dev/console</filename>) should be created. That is, consoles | ||
1376 | 3586 | will be available on <filename>/dev/tty1</filename> through | ||
1377 | 3587 | <filename>/dev/tty5</filename>. The ubuntu templates set this value to 4. | ||
1378 | 3588 | </para></listitem> | ||
1379 | 3589 | |||
1380 | 3590 | <listitem> | ||
1381 | 3591 | <para> | ||
1382 | 3592 | <command>lxc.pts=1024</command> specifies that the container should have a | ||
1383 | 3593 | private (Unix98) devpts filesystem mount. If this is not specified, then | ||
1384 | 3594 | the container will share <filename>/dev/pts</filename> with the host, which | ||
1385 | 3595 | is rarely desired. The number 1024 means that 1024 ptys should be allowed | ||
1386 | 3596 | in the container, however this number is currently ignored. Before | ||
1387 | 3597 | starting the container init, LXC will do (essentially) a | ||
1388 | 3598 | </para> | ||
1389 | 3599 | |||
1390 | 3600 | <screen> | ||
1391 | 3601 | <command> | ||
1392 | 3602 | sudo mount -t devpts -o newinstance devpts /dev/pts | ||
1393 | 3603 | </command> | ||
1394 | 3604 | </screen> | ||
1395 | 3605 | |||
1396 | 3606 | <para> | ||
1397 | 3607 | inside the container. It is important to realize that the container should | ||
1398 | 3608 | not mount devpts filesystems of its own. It may safely do bind or move | ||
1399 | 3609 | mounts of its mounted <filename>/dev/pts</filename>. But if it does | ||
1400 | 3610 | </para> | ||
1401 | 3611 | |||
1402 | 3612 | <screen> | ||
1403 | 3613 | <command> | ||
1404 | 3614 | sudo mount -t devpts devpts /dev/pts | ||
1405 | 3615 | </command> | ||
1406 | 3616 | </screen> | ||
1407 | 3617 | |||
1408 | 3618 | <para> | ||
1409 | 3619 | it will remount the host's devpts | ||
1410 | 3620 | instance. If it adds the newinstance mount option, then it will mount a new | ||
1411 | 3621 | private (empty) instance. In neither case will it remount the instance | ||
1412 | 3622 | which was set up by LXC. For this reason, and to prevent the container | ||
1413 | 3623 | from using the host's ptys, the default apparmor policy will not allow | ||
1414 | 3624 | containers to mount devpts filesystems after the container's init has been | ||
1415 | 3625 | started. | ||
1416 | 3626 | </para> | ||
1417 | 3627 | </listitem> | ||
1418 | 3628 | |||
1419 | 3629 | <listitem><para> | ||
1420 | 3630 | <command>lxc.devttydir</command> specifies a directory under | ||
1421 | 3631 | <filename>/dev</filename> in which LXC will create its console devices. If | ||
1422 | 3632 | this option is not specified, then the ptys will be bind-mounted over | ||
1423 | 3633 | <filename>/dev/console</filename> and <filename>/dev/ttyN.</filename> | ||
1424 | 3634 | However, rare package updates may try to blindly <emphasis>rm -f</emphasis> and then | ||
1425 | 3635 | <emphasis>mknod</emphasis> those devices. They will fail (because the file has been | ||
1426 | 3636 | bind-mounted), causing the package update to fail. When | ||
1427 | 3637 | <command>lxc.devttydir</command> is set to LXC, for instance, then LXC will | ||
1428 | 3638 | bind-mount the console ptys onto <filename>/dev/lxc/console</filename> and | ||
1429 | 3639 | <filename>/dev/lxc/ttyN,</filename> and subsequently symbolically link them | ||
1430 | 3640 | to <filename>/dev/console</filename> and <filename>/dev/ttyN.</filename> | ||
1431 | 3641 | This allows the package updates to succeed, at the risk of making future | ||
1432 | 3642 | gettys on those consoles fail until the next reboot. This problem will be | ||
1433 | 3643 | ideally solved with device namespaces. | ||
1434 | 3644 | </para></listitem> | ||
1435 | 3645 | |||
1436 | 3646 | </itemizedlist> | ||
1437 | 3647 | |||
1438 | 3648 | </sect3> | ||
1439 | 3649 | |||
1440 | 3650 | </sect2> | ||
1441 | 3651 | |||
1442 | 3652 | <sect2 id="lxc-container-updates" status="review"> | ||
1443 | 3653 | <title>Updates in Ubuntu containers</title> | ||
1444 | 3654 | |||
1445 | 3655 | <para> | ||
1446 | 3656 | Because of some limitations which are placed on containers, package upgrades at | ||
1447 | 3657 | times can fail. For instance, a package install or upgrade might fail if it | ||
1448 | 3658 | is not allowed to create or open a block device. This often blocks all future | ||
1449 | 3659 | upgrades until the issue is resolved. In some cases, | ||
1450 | 3660 | you can work around this by chrooting into the container, to avoid the | ||
1451 | 3661 | container restrictions, and completing the upgrade in the chroot. | ||
1452 | 3662 | </para> | ||
1453 | 3663 | |||
1454 | 3664 | <para> | ||
1455 | 3665 | Some of the specific things known to occasionally impede package | ||
1456 | 3666 | upgrades include: | ||
1457 | 3667 | </para> | ||
1458 | 3668 | |||
1459 | 3669 | <itemizedlist> | ||
1460 | 3670 | <listitem><para> | ||
1461 | 3671 | The container modifications performed when creating containers with the | ||
1462 | 3672 | --trim option. | ||
1463 | 3673 | </para></listitem> | ||
1464 | 3674 | <listitem><para> | ||
1465 | 3675 | Actions performed by lxcguest. For instance, because | ||
1466 | 3676 | <filename>/lib/init/fstab</filename> is bind-mounted from another file, | ||
1467 | 3677 | mountall upgrades which insist on replacing that file can fail. | ||
1468 | 3678 | </para></listitem> | ||
1469 | 3679 | <listitem><para> | ||
1470 | 3680 | The over-mounting of console devices with ptys from the host can | ||
1471 | 3681 | cause trouble with udev upgrades. | ||
1472 | 3682 | </para></listitem> | ||
1473 | 3683 | <listitem><para> | ||
1474 | 3684 | Apparmor policy and devices cgroup restrictions can prevent | ||
1475 | 3685 | package upgrades from performing certain actions. | ||
1476 | 3686 | </para></listitem> | ||
1477 | 3687 | <listitem><para> | ||
1478 | 3688 | Capabilities dropped by use of <command>lxc.cap.drop</command> can likewise stop package | ||
1479 | 3689 | upgrades from performing certain actions. | ||
1480 | 3690 | </para></listitem> | ||
1481 | 3691 | </itemizedlist> | ||
1482 | 3692 | </sect2> | ||
1483 | 3693 | |||
1484 | 3694 | <sect2 id="lxc-libvirt" status="review"> | ||
1485 | 3695 | <title>Libvirt LXC</title> | ||
1486 | 3696 | |||
1487 | 3697 | <para> | ||
1488 | 3698 | Libvirt is a powerful hypervisor management solution with which you can | ||
1489 | 3699 | administer Qemu, Xen and LXC virtual machines, both locally and remote. | ||
1490 | 3700 | The libvirt LXC driver is a separate implementation from what we normally | ||
1491 | 3701 | call <emphasis>LXC</emphasis>. A few differences include: | ||
1492 | 3702 | </para> | ||
1493 | 3703 | |||
1494 | 3704 | <itemizedlist> | ||
1495 | 3705 | <listitem><para> | ||
1496 | 3706 | Configuration is stored in xml format | ||
1497 | 3707 | </para></listitem> | ||
1498 | 3708 | <listitem><para> | ||
1499 | 3709 | There no tools to facilitate container creation | ||
1500 | 3710 | </para></listitem> | ||
1501 | 3711 | <listitem><para> | ||
1502 | 3712 | By default there is no console on <filename>/dev/console</filename> | ||
1503 | 3713 | </para></listitem> | ||
1504 | 3714 | <listitem><para> | ||
1505 | 3715 | There is no support (yet) for container reboot or full shutdown | ||
1506 | 3716 | </para></listitem> | ||
1507 | 3717 | </itemizedlist> | ||
1508 | 3718 | |||
1509 | 3719 | <!-- | ||
1510 | 3720 | <sect3 id="lxc-libvirt-virtinst" status="review"> | ||
1511 | 3721 | <title>virt-install</title> | ||
1512 | 3722 | |||
1513 | 3723 | <para> | ||
1514 | 3724 | virt-install can be used to create an LXC container. (test and | ||
1515 | 3725 | verify). Serge hasn't gotten this to work. | ||
1516 | 3726 | </para> | ||
1517 | 3727 | |||
1518 | 3728 | </sect3> | ||
1519 | 3729 | --> | ||
1520 | 3730 | |||
1521 | 3731 | <sect3 id="lxc-libvirt-convert" status="review"> | ||
1522 | 3732 | <title>Converting a LXC container to libvirt-lxc</title> | ||
1523 | 3733 | |||
1524 | 3734 | <para> | ||
1525 | 3735 | |||
1526 | 3736 | <xref linkend="lxc-creation"/> showed how to create LXC containers. | ||
1527 | 3737 | If you've created a valid LXC container in this way, you can | ||
1528 | 3738 | manage it with libvirt. Fetch a sample xml file from | ||
1529 | 3739 | </para> | ||
1530 | 3740 | |||
1531 | 3741 | <screen> | ||
1532 | 3742 | <command> | ||
1533 | 3743 | wget http://people.canonical.com/~serge/o1.xml | ||
1534 | 3744 | </command> | ||
1535 | 3745 | </screen> | ||
1536 | 3746 | |||
1537 | 3747 | <para> | ||
1538 | 3748 | Edit this file to replace the container name and root | ||
1539 | 3749 | filesystem locations. Then you can define the container with: | ||
1540 | 3750 | </para> | ||
1541 | 3751 | |||
1542 | 3752 | <screen> | ||
1543 | 3753 | <command> | ||
1544 | 3754 | virsh -c lxc:/// define o1.xml | ||
1545 | 3755 | </command> | ||
1546 | 3756 | </screen> | ||
1547 | 3757 | </sect3> | ||
1548 | 3758 | |||
1549 | 3759 | <sect3 id="lxc-libvirt-fromcloud" status="review"> | ||
1550 | 3760 | <title>Creating a container from cloud image</title> | ||
1551 | 3761 | |||
1552 | 3762 | <para> | ||
1553 | 3763 | If you prefer to create a pristine new container just for LXC, you | ||
1554 | 3764 | can download an ubuntu cloud image, extract it, and point a libvirt | ||
1555 | 3765 | LXC xml file to it. For instance, find the url for a root tarball | ||
1556 | 3766 | for the latest daily Ubuntu 12.04 LTS cloud image using | ||
1557 | 3767 | </para> | ||
1558 | 3768 | |||
1559 | 3769 | <screen> | ||
1560 | 3770 | <command> | ||
1561 | 3771 | url1=`ubuntu-cloudimg-query precise daily $arch --format "%{url}\n"` | ||
1562 | 3772 | url=`echo $url1 | sed -e 's/.tar.gz/-root\0/'` | ||
1563 | 3773 | wget $url | ||
1564 | 3774 | filename=`basename $url` | ||
1565 | 3775 | </command> | ||
1566 | 3776 | </screen> | ||
1567 | 3777 | |||
1568 | 3778 | <para> | ||
1569 | 3779 | Extract the downloaded tarball, for instance | ||
1570 | 3780 | </para> | ||
1571 | 3781 | |||
1572 | 3782 | <screen> | ||
1573 | 3783 | <command> | ||
1574 | 3784 | mkdir $HOME/c1 | ||
1575 | 3785 | cd $HOME/c1 | ||
1576 | 3786 | sudo tar zxf $filename | ||
1577 | 3787 | </command> | ||
1578 | 3788 | </screen> | ||
1579 | 3789 | |||
1580 | 3790 | <para> | ||
1581 | 3791 | Download the xml template | ||
1582 | 3792 | </para> | ||
1583 | 3793 | |||
1584 | 3794 | <screen> | ||
1585 | 3795 | <command> | ||
1586 | 3796 | wget http://people.canonical.com/~serge/o1.xml | ||
1587 | 3797 | </command> | ||
1588 | 3798 | </screen> | ||
1589 | 3799 | |||
1590 | 3800 | <para> | ||
1591 | 3801 | In the xml template, replace the name o1 with c1 and the source directory | ||
1592 | 3802 | <filename>/var/lib/lxc/o1/rootfs</filename> with | ||
1593 | 3803 | <filename>$HOME/c1</filename>. Then define the container using | ||
1594 | 3804 | </para> | ||
1595 | 3805 | |||
1596 | 3806 | <screen> | ||
1597 | 3807 | <command> | ||
1598 | 3808 | virsh define o1.xml | ||
1599 | 3809 | </command> | ||
1600 | 3810 | </screen> | ||
1601 | 3811 | |||
1602 | 3812 | </sect3> | ||
1603 | 3813 | |||
1604 | 3814 | <sect3 id="lxc-libvirt-interacting" status="review"> | ||
1605 | 3815 | <title>Interacting with libvirt containers</title> | ||
1606 | 3816 | |||
1607 | 3817 | <para> | ||
1608 | 3818 | As we've seen, you can create a libvirt-lxc container using | ||
1609 | 3819 | </para> | ||
1610 | 3820 | |||
1611 | 3821 | <screen> | ||
1612 | 3822 | <command> | ||
1613 | 3823 | virsh -c lxc:/// define container.xml | ||
1614 | 3824 | </command> | ||
1615 | 3825 | </screen> | ||
1616 | 3826 | |||
1617 | 3827 | <para> | ||
1618 | 3828 | To start a container called <emphasis>container</emphasis>, use | ||
1619 | 3829 | </para> | ||
1620 | 3830 | |||
1621 | 3831 | <screen> | ||
1622 | 3832 | <command> | ||
1623 | 3833 | virsh -c lxc:/// start container | ||
1624 | 3834 | </command> | ||
1625 | 3835 | </screen> | ||
1626 | 3836 | |||
1627 | 3837 | <para> | ||
1628 | 3838 | To stop a running container, use | ||
1629 | 3839 | </para> | ||
1630 | 3840 | |||
1631 | 3841 | <screen> | ||
1632 | 3842 | <command> | ||
1633 | 3843 | virsh -c lxc:/// destroy container | ||
1634 | 3844 | </command> | ||
1635 | 3845 | </screen> | ||
1636 | 3846 | |||
1637 | 3847 | <para> | ||
1638 | 3848 | Note that whereas the <command>lxc-destroy</command> command deletes the | ||
1639 | 3849 | container, the <command>virsh destroy</command> command stops a running | ||
1640 | 3850 | container. To delete the container definition, use | ||
1641 | 3851 | </para> | ||
1642 | 3852 | |||
1643 | 3853 | <screen> | ||
1644 | 3854 | <command> | ||
1645 | 3855 | virsh -c lxc:/// undefine container | ||
1646 | 3856 | </command> | ||
1647 | 3857 | </screen> | ||
1648 | 3858 | |||
1649 | 3859 | <para> | ||
1650 | 3860 | To get a console to a running container, use | ||
1651 | 3861 | </para> | ||
1652 | 3862 | |||
1653 | 3863 | <screen> | ||
1654 | 3864 | <command> | ||
1655 | 3865 | virsh -c lxc:/// console container | ||
1656 | 3866 | </command> | ||
1657 | 3867 | </screen> | ||
1658 | 3868 | |||
1659 | 3869 | <para> | ||
1660 | 3870 | Exit the console by simultaneously pressing control and ]. | ||
1661 | 3871 | </para> | ||
1662 | 3872 | |||
1663 | 3873 | </sect3> | ||
1664 | 3874 | |||
1665 | 3875 | </sect2> | ||
1666 | 3876 | |||
1667 | 3877 | <sect2 id="lxc-guest" status="review"> | ||
1668 | 3878 | <title>The lxcguest package</title> | ||
1669 | 3879 | |||
1670 | 3880 | <para> | ||
1671 | 3881 | In the 11.04 (Natty) and 11.10 (Oneiric) releases of Ubuntu, a package was introduced called | ||
1672 | 3882 | <emphasis role="italic">lxcguest</emphasis>. An unmodified root image could not be safely booted inside a | ||
1673 | 3883 | container, but an image with the lxcguest package installed could be | ||
1674 | 3884 | booted as a container, on bare hardware, or in a Xen, kvm, or VMware virtual | ||
1675 | 3885 | machine. | ||
1676 | 3886 | </para> | ||
1677 | 3887 | |||
1678 | 3888 | <para> | ||
1679 | 3889 | As of the 12.04 LTS release, the work previously done by the lxcguest package | ||
1680 | 3890 | was pushed into the core packages, and the lxcguest package was removed. | ||
1681 | 3891 | As a result, an unmodified 12.04 LTS image can be booted as a | ||
1682 | 3892 | container, on bare hardware, or in a Xen, kvm, or VMware virtual machine. | ||
1683 | 3893 | To use an older release, the lxcguest package should still be used. | ||
1684 | 3894 | </para> | ||
1685 | 3895 | |||
1686 | 3896 | </sect2> | ||
1687 | 3897 | |||
1688 | 3898 | <sect2 id="lxc-security" status="review"> | ||
1689 | 3899 | <title>Security</title> | ||
1690 | 3900 | |||
1691 | 3901 | <para> | ||
1692 | 3902 | A namespace maps ids to resources. By not providing a container any id | ||
1693 | 3903 | with which to reference a resource, the resource can be protected. This | ||
1694 | 3904 | is the basis of some of the security afforded to container users. For | ||
1695 | 3905 | instance, IPC namespaces are completely isolated. Other namespaces, | ||
1696 | 3906 | however, have various <emphasis role="italic">leaks</emphasis> which allow privilege to be | ||
1697 | 3907 | inappropriately exerted from a container into another container or to | ||
1698 | 3908 | the host. | ||
1699 | 3909 | </para> | ||
1700 | 3910 | |||
1701 | 3911 | <para> | ||
1702 | 3912 | By default, LXC containers are started under a apparmor policy to | ||
1703 | 3913 | restrict some actions. However, while stronger security is a goal | ||
1704 | 3914 | for future releases, in 1204 LTS the goal of the apparmor policy is not | ||
1705 | 3915 | to stop malicious actions but rather to stop accidental harm of the | ||
1706 | 3916 | host by the guest. | ||
1707 | 3917 | </para> | ||
1708 | 3918 | |||
1709 | 3919 | <para> | ||
1710 | 3920 | See the <ulink url="http://wiki.ubuntu.com/LxcSecurity">LXC security</ulink> | ||
1711 | 3921 | wiki page for more, uptodate information. | ||
1712 | 3922 | </para> | ||
1713 | 3923 | |||
1714 | 3924 | <sect3 id="lxc-seccomp" status="review"> | ||
1715 | 3925 | <title>Exploitable system calls</title> | ||
1716 | 3926 | |||
1717 | 3927 | <para> | ||
1718 | 3928 | It is a core container feature that containers share a kernel with the | ||
1719 | 3929 | host. Therefore, if the kernel contains any exploitable system calls, | ||
1720 | 3930 | the container can exploit these as well. Once the container controls the | ||
1721 | 3931 | kernel it can fully control any resource known to the host. | ||
1722 | 3932 | </para> | ||
1723 | 3933 | |||
1724 | 3934 | </sect3> | ||
1725 | 3935 | </sect2> | ||
1726 | 3936 | |||
1727 | 3937 | <sect2 id="lxc-resources" status="review"> | ||
1728 | 3938 | <title>Resources</title> | ||
1729 | 3939 | <itemizedlist> | ||
1730 | 3940 | |||
1731 | 3941 | <listitem> | ||
1732 | 3942 | <para> | ||
1733 | 3943 | The DeveloperWorks article <ulink url="https://www.ibm.com/developerworks/linux/library/l-lxc-containers/">LXC: Linux container tools</ulink> was an early introduction to the use of containers. | ||
1734 | 3944 | </para> | ||
1735 | 3945 | </listitem> | ||
1736 | 3946 | |||
1737 | 3947 | <listitem> | ||
1738 | 3948 | <para> | ||
1739 | 3949 | The <ulink url="http://www.ibm.com/developerworks/linux/library/l-lxc-security/index.html"> Secure Containers Cookbook</ulink> demonstrated the use of security modules to make containers more secure. | ||
1740 | 3950 | </para> | ||
1741 | 3951 | </listitem> | ||
1742 | 3952 | |||
1743 | 3953 | <listitem> | ||
1744 | 3954 | <para> | ||
1745 | 3955 | Manual pages referenced above can be found at: | ||
1746 | 3956 | <programlisting> | ||
1747 | 3957 | <ulink url="http://manpages.ubuntu.com/manpages/en/man7/capabilities.7.html">capabilities</ulink> | ||
1748 | 3958 | <ulink url="http://manpages.ubuntu.com/manpages/en/man5/lxc.conf.5.html">lxc.conf</ulink> | ||
1749 | 3959 | </programlisting> | ||
1750 | 3960 | </para> | ||
1751 | 3961 | </listitem> | ||
1752 | 3962 | |||
1753 | 3963 | <listitem> | ||
1754 | 3964 | <para> | ||
1755 | 3965 | The upstream LXC project is hosted at <ulink url="http://lxc.sf.net">Sourceforge</ulink>. | ||
1756 | 3966 | </para> | ||
1757 | 3967 | </listitem> | ||
1758 | 3968 | |||
1759 | 3969 | <listitem> | ||
1760 | 3970 | <para> | ||
1761 | 3971 | LXC security issues are listed and discussed at <ulink url="http://wiki.ubuntu.com/LxcSecurity">the LXC Security wiki page</ulink> | ||
1762 | 3972 | </para> | ||
1763 | 3973 | </listitem> | ||
1764 | 3974 | |||
1765 | 3975 | <listitem> | ||
1766 | 3976 | <para> For more on namespaces in Linux, see: S. Bhattiprolu, E. W. Biederman, S. E. Hallyn, and D. Lezcano. Virtual Servers and Check- point/Restart in Mainstream Linux. SIGOPS Op- erating Systems Review, 42(5), 2008.</para> | ||
1767 | 3977 | </listitem> | ||
1768 | 3978 | |||
1769 | 3979 | </itemizedlist> | ||
1770 | 3980 | </sect2> | ||
1771 | 3981 | </sect1> | ||
1772 | 2218 | </chapter> | 3982 | </chapter> |
This is a very significant contribution to the guide. Thank you!
Technical:
All tests performed using default settings and with a simple ubuntu-based container. I did not check all commands.
1. I tried to start a container (cn1) on a KVM guest. I was able to log in but shutting down threw warnings/errors. Normal?
------- ------- ------- ---
(/dev/ lxc/console) at 18:17 ...
$ sudo poweroff
[sudo] password for ubuntu:
$
Broadcast message from ubuntu@cn1
The system is going down for power off NOW! ------- ------- ---
* Asking all remaining processes to terminate...
...done.
* All processes ended within 1 seconds....
...done.
* Deconfiguring network interfaces...
...done.
* Deactivating swap...
...fail!
umount: /run/lock: not mounted
umount: /dev/shm: not mounted
mount: / is busy
* Will now halt
-------
2. This command output doesn't look right. Normal?:
------- ------- ------- ---
$ sudo lxc-start -n cn1 -d
$ lxc-ls
cn1
cn1
$ lxc-list
RUNNING
STOPPED ------- ------- ---
-------
3. Should include how to escape from a container console (Ctrl-a q).
Style:
Under "Host Setup", for /etc/default/lxc, since you say "true by default" for value of USE_LXC_BRIDGE, it makes sense to also say "true by default" for value of LXC_AUTO.
In general, consider using italics when introducing new terms/commands/ package_ names or when trying to emphasize a word. Example: "a package was introduced called ``lxcguest''..." or "...have various ``leaks'' which allow...". This quoting style is awkward.
We should encourage proper practice and prepend all commands requiring privileged access with 'sudo'.
I question the section title of "Container Introspection". The term introspection pertains to the fields of philosophy and psychology. Maybe "Inspection" is better.
Under "Advanced namespace usage", there is a block of code that is not formatted properly. It shows '<pre>' tags and I don't think the red colour is called for. I also think you should provide an external resource/link to 'private namespaces' as well as giving a one-line description of a basic use-case.
Standardize on using "LXC" and not "lxc" or "Lxc" except when referring to a package name? Dunno, 'lxc.sourceforg e.net' shows kind of the reverse: "LXC is the userspace control package for Linux Containers" and "Linux Containers (lxc) implement:". Can be confusing to readers. Proceed as you see fit.
"IP address" instead of "ip address".
Awkward: "The type can be one of several types."
Missing a 'The'? "Following is an example configuration file..."
Extra character? "...which require cap_sys_admin}."
You've made bold man page references before. "See capabilities(7) for a list..."
Rework: "For instance, if a package's postinst fails if it cannot open a block device..."
The standard is to capitalize release codenames: "In the natty and oneiric releases of Ubuntu..."
Add resources section (external links, man pages) at end of page. See end of https:/ /help.ubuntu. com/11. 10/serverguide/ C/openldap- server. html for an example.