Merge lp:~tsimonq2/serverguide/lxd into lp:serverguide/trunk
- lxd
- Merge into trunk
Status: | Merged |
---|---|
Approved by: | Doug Smythies |
Approved revision: | 279 |
Merged at revision: | 279 |
Proposed branch: | lp:~tsimonq2/serverguide/lxd |
Merge into: | lp:serverguide/trunk |
Diff against target: |
883 lines (+874/-0) 1 file modified
serverguide/C/virtualization.xml (+874/-0) |
To merge this branch: | bzr merge lp:~tsimonq2/serverguide/lxd |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Doug Smythies | Approve | ||
Serge Hallyn | Pending | ||
Review via email: mp+290540@code.launchpad.net |
Commit message
Description of the change
This includes the LXD addition to the server guide, all credit to Serge Hallyn.
Doug Smythies (dsmythies) wrote : | # |
Simon Quigley (tsimonq2) wrote : | # |
That's fine, I just want to make sure Serge saw, so merge if you want, I
just want his approval, as he took this on. :)
Doug Smythies (dsmythies) wrote : | # |
It fails validation, in a great many places, but I suspect all one thing.
The text within a listitem needs to be within <para> bla bla </para> I think, but am not sure.
I am busy with something else at the moment, but I can fix this a little later (it is mindless drone type work).
Simon Quigley (tsimonq2) wrote : | # |
Alright, sounds good. Thanks. :)
Doug Smythies (dsmythies) wrote : | # |
+ well justified]</ulink> based on the original academic paper. It also
should be:
+ well justified</ulink> based on the original academic paper. It also
+ The LXC API deals with a 'container'. The LXD API deals with 'remotes,'
should be (I think):
+ The LXC API deals with a 'container'. The LXD API deals with 'remotes',
We will want to do entity substitution where we can. I think we'll come back and do that later, and probably not even during this cycle.
Note to self: Some of our spacing in the PDF is ridiculously large.
Doug Smythies (dsmythies) wrote : | # |
I'm going to approve with changes on my copy that will be pushed.
Serge Hallyn (serge-hallyn) wrote : | # |
Thanks!
Preview Diff
1 | === modified file 'serverguide/C/virtualization.xml' | |||
2 | --- serverguide/C/virtualization.xml 2016-03-20 21:38:40 +0000 | |||
3 | +++ serverguide/C/virtualization.xml 2016-03-30 23:15:41 +0000 | |||
4 | @@ -786,6 +786,880 @@ | |||
5 | 786 | 786 | ||
6 | 787 | </sect1> | 787 | </sect1> |
7 | 788 | 788 | ||
8 | 789 | <sect1 id="lxd" status="review"> | ||
9 | 790 | <title>LXD</title> | ||
10 | 791 | |||
11 | 792 | <para> | ||
12 | 793 | LXD (pronounced lex-dee) is the lightervisor, or lightweight container | ||
13 | 794 | hypervisor. While this claim has been controversial, it has been <ulink | ||
14 | 795 | url="http://blog.dustinkirkland.com/2015/09/container-summit-presentation-and-live.html">quite | ||
15 | 796 | well justified]</ulink> based on the original academic paper. It also | ||
16 | 797 | nicely distinguishes LXD from <ulink | ||
17 | 798 | url="https://help.ubuntu.com/lts/serverguide/lxc.html">LXC</ulink>. | ||
18 | 799 | </para> | ||
19 | 800 | |||
20 | 801 | <para> | ||
21 | 802 | LXC (lex-see) is a program which creates and administers "containers" on a | ||
22 | 803 | local system. It also provides an API to allow higher level managers, such | ||
23 | 804 | as LXD, to administer containers. In a sense, one could compare LXC to | ||
24 | 805 | QEMU, while comparing LXD to libvirt. | ||
25 | 806 | </para> | ||
26 | 807 | |||
27 | 808 | <para> | ||
28 | 809 | The LXC API deals with a 'container'. The LXD API deals with 'remotes,' | ||
29 | 810 | which serve images and containers. This extends the LXC functionality over | ||
30 | 811 | the network, and allows concise management of tasks like container | ||
31 | 812 | migration and container image publishing. | ||
32 | 813 | </para> | ||
33 | 814 | |||
34 | 815 | <para> | ||
35 | 816 | LXD uses LXC under the covers for some container management tasks. | ||
36 | 817 | However, it keeps its own container configuration information and has its | ||
37 | 818 | own conventions, so that it is best not to use classic LXC commands by hand | ||
38 | 819 | with LXD containers. This document will focus on how to configure and | ||
39 | 820 | administer LXD on Ubuntu systems. | ||
40 | 821 | </para> | ||
41 | 822 | |||
42 | 823 | <sect2 id="lxd-resources"> <title>Online Resources</title> | ||
43 | 824 | |||
44 | 825 | <para> | ||
45 | 826 | There is excellent documentation for <ulink url="http://github.com/lxc/lxd">getting started with LXD</ulink> in the online LXD README. There is also an online server allowing you to <ulink url="http://linuxcontainers.org/lxd/try-it">try out LXD remotely</ulink>. Stéphane Graber also has an <ulink url="https://www.stgraber.org/2016/03/11/lxd-2-0-blog-post-series-012/">excellent blog series</ulink> on LXD 2.0. Finally, there is great documentation on how to <ulink url="https://jujucharms.com/docs/devel/config-LXD">drive lxd using juju</ulink>. | ||
46 | 827 | </para> | ||
47 | 828 | |||
48 | 829 | <para> | ||
49 | 830 | This document will offer an Ubuntu Server-specific view of LXD, focusing | ||
50 | 831 | on administration. | ||
51 | 832 | </para> | ||
52 | 833 | </sect2> | ||
53 | 834 | |||
54 | 835 | <sect2 id="lxd-installation"> <title>Installation</title> | ||
55 | 836 | |||
56 | 837 | <para> | ||
57 | 838 | LXD is pre-installed on Ubuntu Server cloud images. On other systems, the lxd | ||
58 | 839 | package can be installed using: | ||
59 | 840 | </para> | ||
60 | 841 | |||
61 | 842 | <screen> | ||
62 | 843 | <command> | ||
63 | 844 | sudo apt install lxd | ||
64 | 845 | </command> | ||
65 | 846 | </screen> | ||
66 | 847 | |||
67 | 848 | <para> | ||
68 | 849 | This will install LXD as well as the recommended dependencies, including the LXC | ||
69 | 850 | library and lxcfs. | ||
70 | 851 | </para> | ||
71 | 852 | </sect2> | ||
72 | 853 | |||
73 | 854 | <sect2 id="lxd-kernel-prep"> <title> Kernel preparation </title> | ||
74 | 855 | |||
75 | 856 | <para> | ||
76 | 857 | In general, Ubuntu 16.04 should have all the desired features enabled by | ||
77 | 858 | default. One exception to this is that in order to enable swap | ||
78 | 859 | accounting the boot argument <command>swapaccount=1</command> must be set. This can be | ||
79 | 860 | done by appending it to the <command>GRUB_CMDLINE_LINUX_DEFAULT=</command>variable in | ||
80 | 861 | /etc/default/grub, then running 'update-grub' as root and rebooting. | ||
81 | 862 | </para> | ||
82 | 863 | |||
83 | 864 | </sect2> | ||
84 | 865 | |||
85 | 866 | <sect2 id="lxd-configuration"> <title> Configuration </title> | ||
86 | 867 | |||
87 | 868 | <para> | ||
88 | 869 | By default, LXD is installed listening on a local UNIX socket, which | ||
89 | 870 | members of group LXD can talk to. It has no trust password setup. And | ||
90 | 871 | it uses the filesystem at <filename>/var/lib/lxd</filename> to store | ||
91 | 872 | containers. To configure LXD with different settings, use <command>lxd | ||
92 | 873 | init</command>. This will allow you to choose: | ||
93 | 874 | </para> | ||
94 | 875 | |||
95 | 876 | <itemizedlist> | ||
96 | 877 | <listitem> | ||
97 | 878 | Directory or <ulink url="http://open-zfs.org">ZFS</ulink> container | ||
98 | 879 | backend. If you choose ZFS, you can choose which block devices to use, | ||
99 | 880 | or the size of a file to use as backing store. | ||
100 | 881 | </listitem> | ||
101 | 882 | <listitem> Availability over the network | ||
102 | 883 | </listitem> | ||
103 | 884 | <listitem> A 'trust password' used by remote clients to vouch for their client certificate | ||
104 | 885 | </listitem> | ||
105 | 886 | </itemizedlist> | ||
106 | 887 | |||
107 | 888 | <para> | ||
108 | 889 | You must run 'lxd init' as root. 'lxc' commands can be run as any | ||
109 | 890 | user who is member of group lxd. If user joe is not a member of group 'lxd', | ||
110 | 891 | you may run: | ||
111 | 892 | </para> | ||
112 | 893 | |||
113 | 894 | <screen> | ||
114 | 895 | <command> | ||
115 | 896 | adduser joe lxd | ||
116 | 897 | </command> | ||
117 | 898 | </screen> | ||
118 | 899 | |||
119 | 900 | <para> | ||
120 | 901 | as root to change it. The new membership will take effect on the next login, or after | ||
121 | 902 | running 'newgrp lxd' from an existing login. | ||
122 | 903 | </para> | ||
123 | 904 | |||
124 | 905 | <para> | ||
125 | 906 | For more information on server, container, profile, and device configuration, | ||
126 | 907 | please refer to the definitive configuration provided with the source code, | ||
127 | 908 | which can be found <ulink url="https://github.com/lxc/lxd/blob/master/doc/configuration.md">online</ulink> | ||
128 | 909 | </para> | ||
129 | 910 | |||
130 | 911 | </sect2> | ||
131 | 912 | |||
132 | 913 | <sect2 id="lxd-first-container"> <title> Creating your first container </title> | ||
133 | 914 | |||
134 | 915 | <para> | ||
135 | 916 | This section will describe the simplest container tasks. | ||
136 | 917 | </para> | ||
137 | 918 | |||
138 | 919 | <sect3> <title> Creating a container </title> | ||
139 | 920 | |||
140 | 921 | <para> | ||
141 | 922 | Every new container is created based on either an image, an existing container, | ||
142 | 923 | or a container snapshot. At install time, LXD is configured with the following | ||
143 | 924 | image servers: | ||
144 | 925 | </para> | ||
145 | 926 | |||
146 | 927 | <itemizedlist> | ||
147 | 928 | <listitem> | ||
148 | 929 | <filename>ubuntu</filename>: this serves official Ubuntu server cloud image releases. | ||
149 | 930 | </listitem> | ||
150 | 931 | <listitem> | ||
151 | 932 | <filename>ubuntu-daily</filename>: this serves official Ubuntu server cloud images of the daily | ||
152 | 933 | development releases. | ||
153 | 934 | </listitem> | ||
154 | 935 | <listitem> | ||
155 | 936 | <filename>images</filename>: this is a default-installed alias for images.linuxcontainers.org. | ||
156 | 937 | This is serves classical lxc images built using the same images which the | ||
157 | 938 | LXC 'download' template uses. This includes various distributions and | ||
158 | 939 | minimal custom-made Ubuntu images. This is not the recommended | ||
159 | 940 | server for Ubuntu images. | ||
160 | 941 | </listitem> | ||
161 | 942 | </itemizedlist> | ||
162 | 943 | |||
163 | 944 | <para> | ||
164 | 945 | The command to create and start a container is | ||
165 | 946 | </para> | ||
166 | 947 | |||
167 | 948 | <screen> | ||
168 | 949 | <command> | ||
169 | 950 | lxc launch remote:image containername | ||
170 | 951 | </command> | ||
171 | 952 | </screen> | ||
172 | 953 | |||
173 | 954 | <para> | ||
174 | 955 | Images are identified by their hash, but are also aliased. The 'ubuntu' | ||
175 | 956 | server knows many aliases such as '16.04' and 'xenial'. A list of all | ||
176 | 957 | images available from the Ubuntu Server can be seen using: | ||
177 | 958 | </para> | ||
178 | 959 | |||
179 | 960 | <screen> | ||
180 | 961 | <command> | ||
181 | 962 | lxc image list ubuntu: | ||
182 | 963 | </command> | ||
183 | 964 | </screen> | ||
184 | 965 | |||
185 | 966 | <para> | ||
186 | 967 | To see more information about a particular image, including all the aliases it | ||
187 | 968 | is known by, you can use: | ||
188 | 969 | </para> | ||
189 | 970 | |||
190 | 971 | <screen> | ||
191 | 972 | <command> | ||
192 | 973 | lxc image info ubuntu:xenial | ||
193 | 974 | </command> | ||
194 | 975 | </screen> | ||
195 | 976 | |||
196 | 977 | <para> | ||
197 | 978 | You can generally refer to an Ubuntu image using the release name ('xenial') or | ||
198 | 979 | the release number (16.04). In addition, 'lts' is an alias for the latest | ||
199 | 980 | supported LTS release. To choose a different architecture, you can specify the | ||
200 | 981 | desired architecture: | ||
201 | 982 | </para> | ||
202 | 983 | |||
203 | 984 | <screen> | ||
204 | 985 | <command> | ||
205 | 986 | lxc image info ubuntu:lts/arm64 | ||
206 | 987 | </command> | ||
207 | 988 | </screen> | ||
208 | 989 | |||
209 | 990 | <para> | ||
210 | 991 | Now, let's start our first container: | ||
211 | 992 | </para> | ||
212 | 993 | |||
213 | 994 | <screen> | ||
214 | 995 | <command> | ||
215 | 996 | lxc launch ubuntu:xenial x1 | ||
216 | 997 | </command> | ||
217 | 998 | </screen> | ||
218 | 999 | |||
219 | 1000 | <para> | ||
220 | 1001 | This will download the official current Xenial cloud image for your current | ||
221 | 1002 | architecture, then create a container using that image, and finally start it. | ||
222 | 1003 | Once the command returns, you can see it using: | ||
223 | 1004 | </para> | ||
224 | 1005 | |||
225 | 1006 | <screen> | ||
226 | 1007 | <command> | ||
227 | 1008 | lxc list | ||
228 | 1009 | lxc info x1 | ||
229 | 1010 | </command> | ||
230 | 1011 | </screen> | ||
231 | 1012 | |||
232 | 1013 | <para> | ||
233 | 1014 | and open a shell in it using: | ||
234 | 1015 | </para> | ||
235 | 1016 | |||
236 | 1017 | <screen> | ||
237 | 1018 | <command> | ||
238 | 1019 | lxc exec x1 bash | ||
239 | 1020 | </command> | ||
240 | 1021 | </screen> | ||
241 | 1022 | |||
242 | 1023 | <para> | ||
243 | 1024 | The try-it page gives a full synopsis of the commands you can use to administer | ||
244 | 1025 | containers. | ||
245 | 1026 | </para> | ||
246 | 1027 | |||
247 | 1028 | <para> | ||
248 | 1029 | Now that the 'xenial' image has been downloaded, it will be kept in sync until | ||
249 | 1030 | no new containers have been created based on it for (by default) 10 days. After | ||
250 | 1031 | that, it will be deleted. | ||
251 | 1032 | </para> | ||
252 | 1033 | </sect3> | ||
253 | 1034 | </sect2> | ||
254 | 1035 | |||
255 | 1036 | <sect2 id="lxd-server-config"> <title> LXD Server Configuration </title> | ||
256 | 1037 | |||
257 | 1038 | <para> | ||
258 | 1039 | By default, LXD is socket activated and configured to listen only on a | ||
259 | 1040 | local UNIX socket. While LXD may not be running when you first look at the | ||
260 | 1041 | process listing, any LXC command will start it up. For instance: | ||
261 | 1042 | </para> | ||
262 | 1043 | |||
263 | 1044 | <screen> | ||
264 | 1045 | <command> | ||
265 | 1046 | lxc list | ||
266 | 1047 | </command> | ||
267 | 1048 | </screen> | ||
268 | 1049 | |||
269 | 1050 | <para> | ||
270 | 1051 | This will create your client certificate and contact the LXD server for a | ||
271 | 1052 | list of containers. To make the server accessible over the network you can | ||
272 | 1053 | set the http port using: | ||
273 | 1054 | </para> | ||
274 | 1055 | |||
275 | 1056 | <screen> | ||
276 | 1057 | <command> | ||
277 | 1058 | lxc config set core.https_address :8443 | ||
278 | 1059 | </command> | ||
279 | 1060 | </screen> | ||
280 | 1061 | |||
281 | 1062 | <para> | ||
282 | 1063 | This will tell LXD to listen to port 8843 on all addresses. | ||
283 | 1064 | </para> | ||
284 | 1065 | |||
285 | 1066 | <sect3> <title> Authentication</title> | ||
286 | 1067 | |||
287 | 1068 | <para> | ||
288 | 1069 | By default, LXD will allow all members of group 'lxd' (which by default includes | ||
289 | 1070 | all members of group admin) to talk to it over the UNIX socket. Communication | ||
290 | 1071 | over the network is authorized using server and client certificates. | ||
291 | 1072 | </para> | ||
292 | 1073 | |||
293 | 1074 | <para> | ||
294 | 1075 | Before client c1 wishes to use remote r1, r1 must be registered using: | ||
295 | 1076 | </para> | ||
296 | 1077 | |||
297 | 1078 | <screen> | ||
298 | 1079 | <command> | ||
299 | 1080 | lxc remote add r1 r1.example.com:8443 | ||
300 | 1081 | </command> | ||
301 | 1082 | </screen> | ||
302 | 1083 | |||
303 | 1084 | <para> | ||
304 | 1085 | The fingerprint of r1's certificate will be shown, to allow the user at | ||
305 | 1086 | c1 to reject a false certificate. The server in turn will verify that | ||
306 | 1087 | c1 may be trusted in one of two ways. The first is to register it in advance | ||
307 | 1088 | from any already-registered client, using: | ||
308 | 1089 | </para> | ||
309 | 1090 | |||
310 | 1091 | <screen> | ||
311 | 1092 | <command> | ||
312 | 1093 | lxc config trust add r1 certfile.crt | ||
313 | 1094 | </command> | ||
314 | 1095 | </screen> | ||
315 | 1096 | |||
316 | 1097 | <para> | ||
317 | 1098 | Now when the client adds r1 as a known remote, it will not need to provide | ||
318 | 1099 | a password as it is already trusted by the server. | ||
319 | 1100 | </para> | ||
320 | 1101 | |||
321 | 1102 | <para> | ||
322 | 1103 | The other is to configure a 'trust password' with r1, either at initial | ||
323 | 1104 | configuration using 'lxd init', or after the fact using | ||
324 | 1105 | </para> | ||
325 | 1106 | |||
326 | 1107 | <screen> | ||
327 | 1108 | <command> | ||
328 | 1109 | lxc config set core.trust_password PASSWORD | ||
329 | 1110 | </command> | ||
330 | 1111 | </screen> | ||
331 | 1112 | |||
332 | 1113 | <para> | ||
333 | 1114 | The password can then be provided when the client registers | ||
334 | 1115 | r1 as a known remote. | ||
335 | 1116 | </para> | ||
336 | 1117 | |||
337 | 1118 | </sect3> | ||
338 | 1119 | |||
339 | 1120 | <sect3> <title> Backing store </title> | ||
340 | 1121 | |||
341 | 1122 | <para> | ||
342 | 1123 | LXD supports several backing stores. The recommended backing store is ZFS, | ||
343 | 1124 | however this is not available on all platforms. Supported backing stores | ||
344 | 1125 | include: | ||
345 | 1126 | </para> | ||
346 | 1127 | |||
347 | 1128 | <itemizedlist> | ||
348 | 1129 | <listitem> | ||
349 | 1130 | <para> | ||
350 | 1131 | ext4: this is the default, and easiest to use. With an ext4 backing store, | ||
351 | 1132 | containers and images are simply stored as directories on the host filesystem. | ||
352 | 1133 | Launching new containers requires copying a whole filesystem, and 10 containers | ||
353 | 1134 | will take up 10 times as much space as one container. | ||
354 | 1135 | </para> | ||
355 | 1136 | </listitem> | ||
356 | 1137 | |||
357 | 1138 | <listitem> | ||
358 | 1139 | <para> | ||
359 | 1140 | ZFS: if ZFS is supported on your architecture (amd64, arm64, or ppc64le), you | ||
360 | 1141 | can set LXD up to use it using 'lxd init'. If you already have a ZFS pool | ||
361 | 1142 | configured, you can tell LXD to use it by setting the zfs_pool_name configuration | ||
362 | 1143 | key: | ||
363 | 1144 | </para> | ||
364 | 1145 | |||
365 | 1146 | <screen> | ||
366 | 1147 | <command> | ||
367 | 1148 | lxc config set storage.zfs_pool_name lxd | ||
368 | 1149 | </command> | ||
369 | 1150 | </screen> | ||
370 | 1151 | |||
371 | 1152 | <para> | ||
372 | 1153 | With ZFS, launching a new container | ||
373 | 1154 | is fast because the filesystem starts as a copy on write clone of the images' | ||
374 | 1155 | filesystem. Note that unless the container is privileged (see below) LXD will | ||
375 | 1156 | need to change ownership of all files before the container can start, however | ||
376 | 1157 | this is fast and change very little of the actual filesystem data. | ||
377 | 1158 | </para> | ||
378 | 1159 | </listitem> | ||
379 | 1160 | |||
380 | 1161 | <listitem> | ||
381 | 1162 | <para> | ||
382 | 1163 | Btrfs: btrfs can be used with many of the same advantages as | ||
383 | 1164 | ZFS. To use BTRFS as a LXD backing store, simply mount a Btrfs | ||
384 | 1165 | filesystem under <filename>/var/lib/lxd</filename>. LXD will detect | ||
385 | 1166 | this and exploit the Btrfs subvolume feature whenever launching a new | ||
386 | 1167 | container or snapshotting a container. | ||
387 | 1168 | </para> | ||
388 | 1169 | </listitem> | ||
389 | 1170 | |||
390 | 1171 | <listitem> | ||
391 | 1172 | <para> | ||
392 | 1173 | LVM: To use a LVM volume group called 'lxd', you may tell LXD to use that | ||
393 | 1174 | for containers and images using the command | ||
394 | 1175 | </para> | ||
395 | 1176 | |||
396 | 1177 | <screen> | ||
397 | 1178 | <command> | ||
398 | 1179 | lxc config set storage.lvm_vg_name lxd | ||
399 | 1180 | </command> | ||
400 | 1181 | </screen> | ||
401 | 1182 | |||
402 | 1183 | <para> | ||
403 | 1184 | When launching a new container, its rootfs will start as a lv clone. It is | ||
404 | 1185 | immediately mounted so that the file uids can be shifted, then unmounted. | ||
405 | 1186 | Container snapshots also are created as lv snapshots. | ||
406 | 1187 | </para> | ||
407 | 1188 | </listitem> | ||
408 | 1189 | </itemizedlist> | ||
409 | 1190 | </sect3> | ||
410 | 1191 | </sect2> | ||
411 | 1192 | |||
412 | 1193 | <sect2 id="lxd-container-config"> <title> Container configuration </title> | ||
413 | 1194 | |||
414 | 1195 | <para> | ||
415 | 1196 | Containers are configured according to a set of profiles, described in the | ||
416 | 1197 | next section, and a set of container-specific configuration. Profiles are | ||
417 | 1198 | applied first, so that container specific configuration can override profile | ||
418 | 1199 | configuration. | ||
419 | 1200 | </para> | ||
420 | 1201 | |||
421 | 1202 | <para> | ||
422 | 1203 | Container configuration includes properties like the architecture, limits | ||
423 | 1204 | on resources such as CPU and RAM, security details including apparmor | ||
424 | 1205 | restriction overrides, and devices to apply to the container. | ||
425 | 1206 | </para> | ||
426 | 1207 | |||
427 | 1208 | <para> | ||
428 | 1209 | Devices can be of several types, including UNIX character, UNIX block, | ||
429 | 1210 | network interface, or 'disk'. In order to insert a host mount into a | ||
430 | 1211 | container, a 'disk' device type would be used. For instance, to mount | ||
431 | 1212 | /opt in container c1 at /opt, you could use: | ||
432 | 1213 | </para> | ||
433 | 1214 | |||
434 | 1215 | <screen> | ||
435 | 1216 | <command> | ||
436 | 1217 | lxc config device add c1 opt disk source=/opt path=opt | ||
437 | 1218 | </command> | ||
438 | 1219 | </screen> | ||
439 | 1220 | |||
440 | 1221 | <para> | ||
441 | 1222 | See: | ||
442 | 1223 | </para> | ||
443 | 1224 | |||
444 | 1225 | <screen> | ||
445 | 1226 | <command> | ||
446 | 1227 | lxc help config | ||
447 | 1228 | </command> | ||
448 | 1229 | </screen> | ||
449 | 1230 | |||
450 | 1231 | <para> | ||
451 | 1232 | for more information about editing container configurations. You may | ||
452 | 1233 | also use: | ||
453 | 1234 | </para> | ||
454 | 1235 | |||
455 | 1236 | <screen> | ||
456 | 1237 | <command> | ||
457 | 1238 | lxc config edit c1 | ||
458 | 1239 | </command> | ||
459 | 1240 | </screen> | ||
460 | 1241 | |||
461 | 1242 | <para> | ||
462 | 1243 | to edit the whole of c1's configuration in your specified $EDITOR. | ||
463 | 1244 | Comments at the top of the configuration will show examples of | ||
464 | 1245 | correct syntax to help administrators hit the ground running. If | ||
465 | 1246 | the edited configuration is not valid when the $EDITOR is exited, | ||
466 | 1247 | then $EDITOR will be restarted. | ||
467 | 1248 | </para> | ||
468 | 1249 | |||
469 | 1250 | </sect2> | ||
470 | 1251 | |||
471 | 1252 | <sect2 id="lxd-profiles"> <title> Profiles </title> | ||
472 | 1253 | |||
473 | 1254 | <para> | ||
474 | 1255 | Profiles are named collections of configurations which may be applied | ||
475 | 1256 | to more than one container. For instance, all containers created with | ||
476 | 1257 | 'lxc launch', by default, include the 'default' profile, which provides a | ||
477 | 1258 | network interface 'eth0'. | ||
478 | 1259 | </para> | ||
479 | 1260 | |||
480 | 1261 | <para> | ||
481 | 1262 | To mask a device which would be inherited from a profile but which should | ||
482 | 1263 | not be in the final container, define a device by the same name but of | ||
483 | 1264 | type 'none': | ||
484 | 1265 | </para> | ||
485 | 1266 | |||
486 | 1267 | <screen> | ||
487 | 1268 | <command> | ||
488 | 1269 | lxc config device add c1 eth1 none | ||
489 | 1270 | </command> | ||
490 | 1271 | </screen> | ||
491 | 1272 | |||
492 | 1273 | </sect2> | ||
493 | 1274 | <sect2 id="lxd-nesting"> <title> Nesting </title> | ||
494 | 1275 | |||
495 | 1276 | <para> | ||
496 | 1277 | Containers all share the same host kernel. This means that there is always | ||
497 | 1278 | an inherent trade-off between features exposed to the container and host | ||
498 | 1279 | security from malicious containers. Containers by default are therefore | ||
499 | 1280 | restricted from features needed to nest child containers. In order to | ||
500 | 1281 | run lxc or lxd containers under a lxd container, the | ||
501 | 1282 | 'security.nesting' feature must be set to true: | ||
502 | 1283 | </para> | ||
503 | 1284 | |||
504 | 1285 | <screen> | ||
505 | 1286 | <command> | ||
506 | 1287 | lxc config set container1 security.nesting true | ||
507 | 1288 | </command> | ||
508 | 1289 | </screen> | ||
509 | 1290 | |||
510 | 1291 | <para> | ||
511 | 1292 | Once this is done, container1 will be able to start sub-containers. | ||
512 | 1293 | </para> | ||
513 | 1294 | |||
514 | 1295 | <para> | ||
515 | 1296 | In order to run unprivileged (the default in LXD) containers nested under an | ||
516 | 1297 | unprivileged container, you will need to ensure a wide enough UID mapping. | ||
517 | 1298 | Please see the 'UID mapping' section below. | ||
518 | 1299 | </para> | ||
519 | 1300 | |||
520 | 1301 | <sect3> <title> Docker </title> | ||
521 | 1302 | |||
522 | 1303 | <para> | ||
523 | 1304 | In order to facilitate running docker containers inside a LXD container, | ||
524 | 1305 | a 'docker' profile is provided. To launch a new container with the | ||
525 | 1306 | docker profile, you can run: | ||
526 | 1307 | </para> | ||
527 | 1308 | |||
528 | 1309 | <screen> | ||
529 | 1310 | <command> | ||
530 | 1311 | lxc launch xenial container1 -p default -p docker | ||
531 | 1312 | </command> | ||
532 | 1313 | </screen> | ||
533 | 1314 | |||
534 | 1315 | <para> | ||
535 | 1316 | Note that currently the docker package in Ubuntu 16.04 is patched to | ||
536 | 1317 | facilitate running in a container. This support is expected to land | ||
537 | 1318 | upstream soon. | ||
538 | 1319 | </para> | ||
539 | 1320 | |||
540 | 1321 | <para> | ||
541 | 1322 | Note that 'cgroup namespace' support is also required. This is | ||
542 | 1323 | available in the 16.04 kernel as well as in the 4.6 upstream | ||
543 | 1324 | source. | ||
544 | 1325 | </para> | ||
545 | 1326 | |||
546 | 1327 | </sect3> | ||
547 | 1328 | </sect2> | ||
548 | 1329 | |||
549 | 1330 | <sect2 id="lxd-limits"> <title> Limits </title> | ||
550 | 1331 | |||
551 | 1332 | <para> | ||
552 | 1333 | LXD supports flexible constraints on the resources which containers | ||
553 | 1334 | can consume. The limits come in the following categories: | ||
554 | 1335 | </para> | ||
555 | 1336 | |||
556 | 1337 | <itemizedlist> | ||
557 | 1338 | <listitem> | ||
558 | 1339 | CPU: limit cpu available to the container in several ways. | ||
559 | 1340 | </listitem> | ||
560 | 1341 | <listitem> | ||
561 | 1342 | Disk: configure the priority of I/O requests under load | ||
562 | 1343 | </listitem> | ||
563 | 1344 | <listitem> | ||
564 | 1345 | RAM: configure memory and swap availability | ||
565 | 1346 | </listitem> | ||
566 | 1347 | <listitem> | ||
567 | 1348 | Network: configure the network priority under load | ||
568 | 1349 | </listitem> | ||
569 | 1350 | <listitem> | ||
570 | 1351 | Processes: limit the number of concurrent processes in the container. | ||
571 | 1352 | </listitem> | ||
572 | 1353 | </itemizedlist> | ||
573 | 1354 | |||
574 | 1355 | <para> | ||
575 | 1356 | For a full list of limits known to LXD, see | ||
576 | 1357 | <ulink url="https://github.com/lxc/lxd/blob/master/doc/configuration.md"> | ||
577 | 1358 | the configuration documentation</ulink>. | ||
578 | 1359 | </para> | ||
579 | 1360 | |||
580 | 1361 | </sect2> | ||
581 | 1362 | |||
582 | 1363 | <sect2 id="lxd-uid"> <title> UID mappings and Privileged containers </title> | ||
583 | 1364 | |||
584 | 1365 | <para> | ||
585 | 1366 | By default, LXD creates unprivileged containers. This means that root | ||
586 | 1367 | in the container is a non-root UID on the host. It is privileged against | ||
587 | 1368 | the resources owned by the container, but unprivileged with respect to | ||
588 | 1369 | the host, making root in a container roughly equivalent to an unprivileged | ||
589 | 1370 | user on the host. (The main exception is the increased attack surface | ||
590 | 1371 | exposed through the system call interface) | ||
591 | 1372 | </para> | ||
592 | 1373 | |||
593 | 1374 | <para> | ||
594 | 1375 | Briefly, in an unprivileged container, 65536 UIDs are 'shifted' into the | ||
595 | 1376 | container. For instance, UID 0 in the container may be 100000 on the host, | ||
596 | 1377 | UID 1 in the container is 100001, etc, up to 165535. The starting value | ||
597 | 1378 | for UIDs and GIDs, respectively, is determined by the 'root' entry the | ||
598 | 1379 | <filename>/etc/subuid</filename> and <filename>/etc/subgid</filename> files. (See the | ||
599 | 1380 | <ulink url="http://manpages.ubuntu.com/manpages/xenial/en/man5/subuid.5.html"> | ||
600 | 1381 | subuid(5) manual page</ulink>. | ||
601 | 1382 | </para> | ||
602 | 1383 | |||
603 | 1384 | <para> | ||
604 | 1385 | It is possible to request a container to run without a UID mapping by | ||
605 | 1386 | setting the security.privileged flag to true: | ||
606 | 1387 | </para> | ||
607 | 1388 | |||
608 | 1389 | <screen> | ||
609 | 1390 | <command> | ||
610 | 1391 | lxc config set c1 security.privileged true | ||
611 | 1392 | </command> | ||
612 | 1393 | </screen> | ||
613 | 1394 | |||
614 | 1395 | <para> | ||
615 | 1396 | Note however that in this case the root user in the container is the | ||
616 | 1397 | root user on the host. | ||
617 | 1398 | </para> | ||
618 | 1399 | |||
619 | 1400 | </sect2> | ||
620 | 1401 | |||
621 | 1402 | <sect2 id="lxd-aa"> <title> Apparmor </title> | ||
622 | 1403 | |||
623 | 1404 | <para> | ||
624 | 1405 | LXD confines containers by default with an apparmor profile which protects | ||
625 | 1406 | containers from each other and the host from containers. For instance | ||
626 | 1407 | this will prevent root in one container from signaling root in another | ||
627 | 1408 | container, even though they have the same uid mapping. It also prevents | ||
628 | 1409 | writing to dangerous, un-namespaced files such as many sysctls and | ||
629 | 1410 | <filename> /proc/sysrq-trigger</filename>. | ||
630 | 1411 | </para> | ||
631 | 1412 | |||
632 | 1413 | <para> | ||
633 | 1414 | If the apparmor policy for a container needs to be modified for a container | ||
634 | 1415 | c1, specific apparmor policy lines can be added in the 'raw.apparmor' | ||
635 | 1416 | configuration key. | ||
636 | 1417 | </para> | ||
637 | 1418 | |||
638 | 1419 | </sect2> | ||
639 | 1420 | |||
640 | 1421 | <sect2 id="lxd-seccomp"> <title> Seccomp </title> | ||
641 | 1422 | |||
642 | 1423 | <para> | ||
643 | 1424 | All containers are confined by a default seccomp policy. This policy | ||
644 | 1425 | prevents some dangerous actions such as forced umounts, kernel module | ||
645 | 1426 | loading and unloading, kexec, and the open_by_handle_at system call. | ||
646 | 1427 | The seccomp configuration cannot be modified, however a completely | ||
647 | 1428 | different seccomp policy - or none - can be requested using raw.lxc | ||
648 | 1429 | (see below). | ||
649 | 1430 | </para> | ||
650 | 1431 | |||
651 | 1432 | </sect2> | ||
652 | 1433 | <sect2> <title> Raw LXC configuration </title> | ||
653 | 1434 | |||
654 | 1435 | <para> | ||
655 | 1436 | LXD configures containers for the best balance of host safety and | ||
656 | 1437 | container usability. Whenever possible it is highly recommended to | ||
657 | 1438 | use the defaults, and use the LXD configuration keys to request LXD | ||
658 | 1439 | to modify as needed. Sometimes, however, it may be necessary to talk | ||
659 | 1440 | to the underlying lxc driver itself. This can be done by specifying | ||
660 | 1441 | LXC configuration items in the 'raw.lxc' LXD configuration key. These | ||
661 | 1442 | must be valid items as documented in | ||
662 | 1443 | <ulink url="http://manpages.ubuntu.com/manpages/xenial/en/man5/lxc.container.conf.5.html"> | ||
663 | 1444 | the lxc.container.conf(5) manual page</ulink>. | ||
664 | 1445 | </para> | ||
665 | 1446 | |||
666 | 1447 | </sect2> | ||
667 | 1448 | <!-- TODO | ||
668 | 1449 | [//]: # (## Networking) | ||
669 | 1450 | |||
670 | 1451 | [//]: # (Todo Once the ipv6 changes are implemented.) | ||
671 | 1452 | --> | ||
672 | 1453 | |||
673 | 1454 | <sect2> <title> Images and containers </title> | ||
674 | 1455 | |||
675 | 1456 | <para> | ||
676 | 1457 | LXD is image based. When you create your first container, you will | ||
677 | 1458 | generally do so using an existing image. LXD comes pre-configured | ||
678 | 1459 | with three default image remotes: | ||
679 | 1460 | </para> | ||
680 | 1461 | |||
681 | 1462 | <itemizedlist> | ||
682 | 1463 | <listitem> | ||
683 | 1464 | ubuntu: This is a <ulink url="https://launchpad.net/simplestreams">simplestreams-based</ulink> | ||
684 | 1465 | remote serving released ubuntu cloud images. | ||
685 | 1466 | </listitem> | ||
686 | 1467 | |||
687 | 1468 | <listitem> | ||
688 | 1469 | ubuntu-daily: This is another simplestreams based remote which serves | ||
689 | 1470 | 'daily' ubuntu cloud images. These provide quicker but potentially less | ||
690 | 1471 | stable images. | ||
691 | 1472 | </listitem> | ||
692 | 1473 | |||
693 | 1474 | <listitem> | ||
694 | 1475 | images: This is a remote publishing best-effort container images for | ||
695 | 1476 | many distributions, created using community-provided build scripts. | ||
696 | 1477 | </listitem> | ||
697 | 1478 | </itemizedlist> | ||
698 | 1479 | |||
699 | 1480 | <para> | ||
700 | 1481 | To view the images available on one of these servers, you can use: | ||
701 | 1482 | </para> | ||
702 | 1483 | |||
703 | 1484 | <screen> | ||
704 | 1485 | <command> | ||
705 | 1486 | lxc image list ubuntu: | ||
706 | 1487 | </command> | ||
707 | 1488 | </screen> | ||
708 | 1489 | |||
709 | 1490 | <para> | ||
710 | 1491 | Most of the images are known by several aliases for easier reference. To | ||
711 | 1492 | see the full list of aliases, you can use | ||
712 | 1493 | </para> | ||
713 | 1494 | |||
714 | 1495 | <screen> | ||
715 | 1496 | <command> | ||
716 | 1497 | lxc image alias list images: | ||
717 | 1498 | </command> | ||
718 | 1499 | </screen> | ||
719 | 1500 | |||
720 | 1501 | <para> | ||
721 | 1502 | Any alias or image fingerprint can be used to specify how to create the new | ||
722 | 1503 | container. For instance, to create an amd64 Ubuntu 14.04 container, some | ||
723 | 1504 | options are: | ||
724 | 1505 | </para> | ||
725 | 1506 | |||
726 | 1507 | <screen> | ||
727 | 1508 | <command> | ||
728 | 1509 | lxc launch ubuntu:14.04 trusty1 | ||
729 | 1510 | lxc launch ubuntu:trusty trusty1 | ||
730 | 1511 | lxc launch ubuntu:trusty/amd64 trusty1 | ||
731 | 1512 | lxc launch ubuntu:lts trusty1 | ||
732 | 1513 | </command> | ||
733 | 1514 | </screen> | ||
734 | 1515 | |||
735 | 1516 | <para> | ||
736 | 1517 | The 'lts' alias always refers to the latest released LTS image. | ||
737 | 1518 | </para> | ||
738 | 1519 | |||
739 | 1520 | <sect3> <title> Snapshots </title> | ||
740 | 1521 | |||
741 | 1522 | <para> | ||
742 | 1523 | Containers can be renamed and live-migrated using the 'lxc move' command: | ||
743 | 1524 | </para> | ||
744 | 1525 | |||
745 | 1526 | <screen> | ||
746 | 1527 | <command> | ||
747 | 1528 | lxc move c1 final-beta | ||
748 | 1529 | </command> | ||
749 | 1530 | </screen> | ||
750 | 1531 | |||
751 | 1532 | <para> | ||
752 | 1533 | They can also be snapshotted: | ||
753 | 1534 | </para> | ||
754 | 1535 | |||
755 | 1536 | <screen> | ||
756 | 1537 | <command> | ||
757 | 1538 | lxc snapshot c1 YYYY-MM-DD | ||
758 | 1539 | </command> | ||
759 | 1540 | </screen> | ||
760 | 1541 | |||
761 | 1542 | <para> | ||
762 | 1543 | Later changes to c1 can then be reverted by restoring the snapshot: | ||
763 | 1544 | </para> | ||
764 | 1545 | |||
765 | 1546 | <screen> | ||
766 | 1547 | <command> | ||
767 | 1548 | lxc restore u1 YYYY-MM-DD | ||
768 | 1549 | </command> | ||
769 | 1550 | </screen> | ||
770 | 1551 | |||
771 | 1552 | <para> | ||
772 | 1553 | New containers can also be created by copying a container or snapshot: | ||
773 | 1554 | </para> | ||
774 | 1555 | |||
775 | 1556 | <screen> | ||
776 | 1557 | <command> | ||
777 | 1558 | lxc copy u1/YYYY-MM-DD testcontainer | ||
778 | 1559 | </command> | ||
779 | 1560 | </screen> | ||
780 | 1561 | |||
781 | 1562 | </sect3> | ||
782 | 1563 | |||
783 | 1564 | <sect3> <title> Publishing images </title> | ||
784 | 1565 | |||
785 | 1566 | <para> | ||
786 | 1567 | When a container or container snapshot is ready for consumption by others, | ||
787 | 1568 | it can be published as a new image using; | ||
788 | 1569 | </para> | ||
789 | 1570 | |||
790 | 1571 | <screen> | ||
791 | 1572 | <command> | ||
792 | 1573 | lxc publish u1/YYYY-MM-DD --alias foo-2.0 | ||
793 | 1574 | </command> | ||
794 | 1575 | </screen> | ||
795 | 1576 | |||
796 | 1577 | <para> | ||
797 | 1578 | The published image will be private by default, meaning that LXD will not | ||
798 | 1579 | allow clients without a trusted certificate to see them. If the image | ||
799 | 1580 | is safe for public viewing (i.e. contains no private information), then | ||
800 | 1581 | the 'public' flag can be set, either at publish time using | ||
801 | 1582 | </para> | ||
802 | 1583 | |||
803 | 1584 | <screen> | ||
804 | 1585 | <command> | ||
805 | 1586 | lxc publish u1/YYYY-MM-DD --alias foo-2.0 public=true | ||
806 | 1587 | </command> | ||
807 | 1588 | </screen> | ||
808 | 1589 | |||
809 | 1590 | <para> | ||
810 | 1591 | or after the fact using | ||
811 | 1592 | </para> | ||
812 | 1593 | |||
813 | 1594 | <screen> | ||
814 | 1595 | <command> | ||
815 | 1596 | lxc image edit foo-2.0 | ||
816 | 1597 | </command> | ||
817 | 1598 | </screen> | ||
818 | 1599 | |||
819 | 1600 | <para> | ||
820 | 1601 | and changing the value of the public field. | ||
821 | 1602 | </para> | ||
822 | 1603 | |||
823 | 1604 | </sect3> | ||
824 | 1605 | |||
825 | 1606 | <sect3> <title> Image export and import </title> | ||
826 | 1607 | |||
827 | 1608 | <para> | ||
828 | 1609 | Image can be exported as, and imported from, tarballs: | ||
829 | 1610 | </para> | ||
830 | 1611 | |||
831 | 1612 | <screen> | ||
832 | 1613 | <command> | ||
833 | 1614 | lxc image export foo-2.0 foo-2.0.tar.gz | ||
834 | 1615 | lxc image import foo-2.0.tar.gz --alias foo-2.0 --public | ||
835 | 1616 | </command> | ||
836 | 1617 | </screen> | ||
837 | 1618 | |||
838 | 1619 | </sect3> | ||
839 | 1620 | </sect2> | ||
840 | 1621 | |||
841 | 1622 | <sect2 id="lxd-troubleshooting"> <title> Troubleshooting </title> | ||
842 | 1623 | |||
843 | 1624 | <para> | ||
844 | 1625 | To view debug information about LXD itself, on a systemd based host use | ||
845 | 1626 | </para> | ||
846 | 1627 | |||
847 | 1628 | <screen> | ||
848 | 1629 | <command> | ||
849 | 1630 | journalctl -u LXD | ||
850 | 1631 | </command> | ||
851 | 1632 | </screen> | ||
852 | 1633 | |||
853 | 1634 | <para> | ||
854 | 1635 | On an Upstart-based system, you can find the log in | ||
855 | 1636 | <filename>/var/log/upstart/lxd.log</filename>. To make LXD provide | ||
856 | 1637 | much more information about requests it is serving, add '--debug' to | ||
857 | 1638 | LXD's arguments. In systemd, append '--debug' to the 'ExecStart=' line | ||
858 | 1639 | in <filename>/lib/systemd/system/lxd.service</filename>. In Upstart, | ||
859 | 1640 | append it to the <command>exec /usr/bin/lxd</command> line in | ||
860 | 1641 | <filename>/etc/init/lxd.conf</filename>. | ||
861 | 1642 | </para> | ||
862 | 1643 | |||
863 | 1644 | <para> | ||
864 | 1645 | Container logfiles for container c1 may be seen using: | ||
865 | 1646 | </para> | ||
866 | 1647 | |||
867 | 1648 | <screen> | ||
868 | 1649 | <command> | ||
869 | 1650 | lxc info c1 --show-log | ||
870 | 1651 | </command> | ||
871 | 1652 | </screen> | ||
872 | 1653 | |||
873 | 1654 | <para> | ||
874 | 1655 | The configuration file which was used may be found under <filename> /var/log/lxd/c1/lxc.conf</filename> | ||
875 | 1656 | while apparmor profiles can be found in <filename> /var/lib/lxd/security/apparmor/profiles/c1</filename> | ||
876 | 1657 | and seccomp profiles in <filename> /var/lib/lxd/security/seccomp/c1</filename>. | ||
877 | 1658 | </para> | ||
878 | 1659 | </sect2> | ||
879 | 1660 | |||
880 | 1661 | </sect1> | ||
881 | 1662 | |||
882 | 789 | <sect1 id="lxc" status="review"> | 1663 | <sect1 id="lxc" status="review"> |
883 | 790 | <title>LXC</title> | 1664 | <title>LXC</title> |
884 | 791 | 1665 |
Oh, thanks very much Simon. I was just going to setup to do it. I'll review (I know you asked for Serge) it shortly.