Debian Codegraph @

doc/lxc-copy.sgml.in

raw
1 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
2
3 <!DOCTYPE refentry PUBLIC @docdtd@ [
4
5 <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
6 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
7 ]>
8
9 <refentry>
10
11 <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
12
13 <refmeta>
14 <refentrytitle>lxc-copy</refentrytitle>
15 <manvolnum>1</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>lxc-copy</refname>
20
21 <refpurpose>
22 copy an existing container.
23 </refpurpose>
24 </refnamediv>
25
26 <refsynopsisdiv>
27 <cmdsynopsis>
28 <command>lxc-copy</command>
29 <arg choice="req">-n, --name <replaceable>name</replaceable></arg>
30 <arg choice="opt">-P, --lxcpath <replaceable>path</replaceable></arg>
31 <arg choice="req">-N, --newname <replaceable>newname</replaceable></arg>
32 <arg choice="opt">-p, --newpath <replaceable>newpath</replaceable></arg>
33 <arg choice="opt">-B, --backingstorage <replaceable>backingstorage</replaceable></arg>
34 <arg choice="opt">-s, --snapshot</arg>
35 <arg choice="opt">-a, --allowrunning</arg>
36 <arg choice="opt">-K, --keepname</arg>
37 <arg choice="opt">-D, --keepdata</arg>
38 <arg choice="opt">-M, --keepmac</arg>
39 <arg choice="opt">-L, --fssize <replaceable>size [unit]</replaceable></arg>
40 <arg choice="opt">-- hook arguments</arg>
41 </cmdsynopsis>
42 <cmdsynopsis>
43 <command>lxc-copy</command>
44 <arg choice="req">-n, --name <replaceable>name</replaceable></arg>
45 <arg choice="opt">-P, --lxcpath <replaceable>path</replaceable></arg>
46 <arg choice="opt">-N, --newname <replaceable>newname</replaceable></arg>
47 <arg choice="opt">-p, --newpath <replaceable>newpath</replaceable></arg>
48 <arg choice="req">-e, --ephemeral</arg>
49 <arg choice="opt">-B, --backingstorage <replaceable>backingstorage</replaceable></arg>
50 <arg choice="opt">-s, --snapshot</arg>
51 <arg choice="opt">-a, --allowrunning</arg>
52 <arg choice="opt">-K, --keepname</arg>
53 <arg choice="opt">-D, --keepdata</arg>
54 <arg choice="opt">-M, --keepmac</arg>
55 <arg choice="opt">-L, --fssize <replaceable>size [unit]</replaceable></arg>
56 <arg choice="opt">-- hook arguments</arg>
57 </cmdsynopsis>
58 <cmdsynopsis>
59 <command>lxc-copy</command>
60 <arg choice="req">-n, --name <replaceable>name</replaceable></arg>
61 <arg choice="opt">-P, --lxcpath <replaceable>path</replaceable></arg>
62 <arg choice="opt">-N, --newname <replaceable>newname</replaceable></arg>
63 <arg choice="opt">-p, --newpath <replaceable>newpath</replaceable></arg>
64 <arg choice="req">-e, --ephemeral</arg>
65 <arg choice="opt">-B, --backingstorage <replaceable>backingstorage</replaceable></arg>
66 <arg choice="opt">-s, --snapshot</arg>
67 <arg choice="opt">-t, --tmpfs</arg>
68 <arg choice="opt">-K, --keepname</arg>
69 <arg choice="opt">-M, --keepmac</arg>
70 <arg choice="opt">-- hook arguments</arg>
71 </cmdsynopsis>
72 <cmdsynopsis>
73 <command>lxc-copy</command>
74 <arg choice="req">-n, --name <replaceable>name</replaceable></arg>
75 <arg choice="opt">-P, --lxcpath <replaceable>path</replaceable></arg>
76 <arg choice="req">-N, --newname <replaceable>newname</replaceable></arg>
77 <arg choice="opt">-p, --newpath <replaceable>newpath</replaceable></arg>
78 <arg choice="req">-R, --rename</arg>
79 </cmdsynopsis>
80 </refsynopsisdiv>
81
82 <refsect1>
83 <title>Description</title>
84
85 <para>
86 <command>lxc-copy</command> creates and optionally starts (ephemeral or
87 non-ephemeral) copies of existing containers.
88 </para>
89 <para>
90 <command>lxc-copy</command> creates copies of existing containers. Copies
91 can be complete clones of the original container. In this case the whole
92 root filesystem of the container is simply copied to the new container. Or
93 they can be snapshots, i.e. small copy-on-write copies of the original
94 container. In this case the specified backing storage for the copy must
95 support snapshots. This currently includes btrfs, lvm (lvm devices
96 do not support snapshots of snapshots.), overlay, and zfs.
97 </para>
98
99 <para>
100 The copy's backing storage will be of the same type as the original
101 container. overlay snapshots of directory backed containers are
102 exempted from this rule.
103 </para>
104
105 <para>
106 When the <replaceable>-e</replaceable> flag is specified an ephemeral
107 snapshot of the original container is created and started. Ephemeral
108 containers will have <command>lxc.ephemeral = 1</command> set in their
109 config file and will be destroyed on shutdown. When
110 <replaceable>-e</replaceable> is used in combination with
111 <replaceable>-D</replaceable> a non-ephemeral snapshot of the original
112 container is created and started.
113 Ephemeral containers can also be placed on a tmpfs with <replaceable>-t</replaceable>
114 flag. NOTE: If an ephemeral container that is placed on a tmpfs is rebooted
115 all changes made to it will currently be lost!
116 </para>
117
118 <para>
119 When <replaceable>-e</replaceable> is specified and no newname is given via
120 <replaceable>-N</replaceable> a random name for the snapshot will be chosen.
121 </para>
122
123 <para>
124 Containers created and started with <replaceable>-e</replaceable> can have
125 custom mounts. These are specified with the <replaceable>-m</replaceable>
126 flag. Currently two types of mounts are supported:
127 <replaceable>bind</replaceable>, and
128 <replaceable>overlay</replaceable>. Mount types are specified as suboptions
129 to the <replaceable>-m</replaceable> flag and can be specified multiple
130 times separated by commas. <replaceable>overlay</replaceable> mounts are
131 currently specified in the format <replaceable>-m
132 overlay=/src:/dest</replaceable>. When no destination
133 <replaceable>dest</replaceable> is specified
134 <replaceable>dest</replaceable> will be identical to
135 <replaceable>src</replaceable>. Read-only <replaceable>bind</replaceable>
136 mounts are specified <replaceable>-m bind=/src:/dest:ro</replaceable> and
137 read-write <replaceable>bind</replaceable> mounts <replaceable>-m
138 bind=/src:/dest:rw</replaceable>. Read-write
139 <replaceable>bind</replaceable> mounts are the default and
140 <replaceable>rw</replaceable> can be missing when a read-write mount is
141 wanted. When <replaceable>dest</replaceable> is missing
142 <replaceable>dest</replaceable> will be identical to
143 <replaceable>src</replaceable>. An example for multiple mounts would be
144 <replaceable>-m
145 bind=/src1:/dest1:ro,bind=/src2:ro,overlay=/src3:/dest3</replaceable>.
146 </para>
147
148 <para>
149 The mounts, their options, and formats supported via the
150 <replaceable>-m</replaceable> flag are subject to change.
151 </para>
152 </refsect1>
153
154 <refsect1>
155
156 <title>Options</title>
157
158 <variablelist>
159
160 <varlistentry>
161 <term> <option>-N,--newname <replaceable>newname</replaceable></option> </term>
162 <listitem>
163 <para>The name for the copy.</para>
164 </listitem>
165 </varlistentry>
166
167 <varlistentry>
168 <term> <option>-p,--newpath <replaceable>newpath</replaceable></option> </term>
169 <listitem>
170 <para>The path for the copy.</para>
171 </listitem>
172 </varlistentry>
173
174 <varlistentry>
175 <term> <option>-R,--rename </option> </term>
176 <listitem>
177 <para>Rename the original container. </para>
178 </listitem>
179 </varlistentry>
180
181 <varlistentry>
182 <term> <option>-s,--snapshot </option> </term>
183 <listitem>
184 <para> Create a snapshot of the original container. The backing
185 storage for the copy must support snapshots. This currently includes
186 btrfs, lvm, overlay, and zfs. </para>
187 </listitem>
188 </varlistentry>
189
190 <varlistentry>
191 <term> <option>-a,--allowrunning </option> </term>
192 <listitem>
193 <para> Allow the creation of a Snapshot of an already running container.
194 This may cause data corruption or data loss depending on the used
195 filesystem and applications. Use with care. </para>
196 </listitem>
197 </varlistentry>
198
199 <varlistentry>
200 <term> <option>-F,--foreground</option> </term>
201 <listitem>
202 <para>Run the snapshot in the foreground. The snapshots console will
203 be attached to the current tty. (This option can only be specified
204 in conjunction with <replaceable>-e</replaceable>.)
205 </para>
206 </listitem>
207 </varlistentry>
208
209 <varlistentry>
210 <term> <option>-d, --daemon</option> </term>
211 <listitem>
212 <para> Run the snapshot as a daemon (This is the default mode for
213 ephemeral containers.). As the container has no more tty, if an
214 error occurs nothing will be displayed, the log file can
215 be used to check the error. (This option can only be specified in
216 conjunction with <replaceable>-e</replaceable>.)
217 </para>
218 </listitem>
219 </varlistentry>
220
221 <varlistentry>
222 <term> <option>-m, --mount <replaceable>mounttype</replaceable></option> </term>
223 <listitem>
224 <para> Specify a mount for a snapshot The
225 <replaceable>opts</replaceable> argument for the mount type can by
226 of type {bind, overlay}. For example <option>-m
227 bind=/src:/dest:ro,overlay=/src:/dest</option> (This option can
228 currently only be specified in conjunction with
229 <replaceable>-e</replaceable>.).</para>
230 </listitem>
231 </varlistentry>
232
233 <varlistentry>
234 <term> <option>-t, --tmpfs </option></term>
235 <listitem>
236 <para> When this option is specified the ephemeral container will be
237 placed on a tmpfs. NOTE: Rebooting an ephemeral container that is
238 located on a tmpfs will currently cause all changes made to it to be
239 lost. This flag will only work for ephemeral containers created with
240 the <replaceable>-e</replaceable> flag. The original container, from
241 which the ephemeral snapshot is created, must be stored as a simple
242 directory.
243 </para> </listitem>
244 </varlistentry>
245
246 <varlistentry>
247 <term> <option>-B, --backingstorage <replaceable>backingstorage</replaceable></option></term>
248 <listitem>
249 <para>Specify the backing storage type to be used for the copy
250 where 'backingstorage' is of type 'btrfs', 'dir', 'lvm', 'loop',
251 'overlay', or 'zfs'. </para>
252 </listitem>
253 </varlistentry>
254
255 <varlistentry>
256 <term> <option>-L, --fssize <replaceable>size [unit]</replaceable></option></term>
257 <listitem>
258 <para>Specify the size for an 'lvm' filesystem. </para>
259 </listitem>
260 </varlistentry>
261
262 <varlistentry>
263 <term> <option>-K, --keepname </option></term>
264 <listitem>
265 <para> When this option is specified the hostname of the original
266 container will be kept for the copy.</para> </listitem>
267 </varlistentry>
268
269 <varlistentry>
270 <term> <option>-D, --keepdata </option></term>
271 <listitem>
272 <para>When this option is specified with
273 <replaceable>-e</replaceable> a non-ephemeral container is created
274 and started. </para> </listitem>
275 </varlistentry>
276
277 <varlistentry>
278 <term> <option>-M, --keepmac </option></term>
279 <listitem>
280 <para> When this option is specified the MAC address of the original
281 container will be kept for the copy.</para> </listitem>
282 </varlistentry>
283
284 </variablelist>
285
286 </refsect1>
287
288 <refsect1>
289 <title>Copy hook</title>
290 <para>
291 If the container being copied has one or more
292 <filename>lxc.hook.clone</filename> specified, then the specified hooks
293 will be called for the new container. The first 3 arguments passed to the
294 clone hook will be the container name, a section ('lxc'), and the hook
295 type ('clone'). Extra arguments passed to <command>lxc-copy</command> will
296 be passed to the hook program starting at argument 4. The
297 <filename>LXC_ROOTFS_MOUNT</filename> environment variable gives
298 the path under which the container's root filesystem is mounted. The
299 configuration file pathname is stored in
300 <filename>LXC_CONFIG_FILE</filename>, the new container name in
301 <filename>LXC_NAME</filename>, the old container name in
302 <filename>LXC_SRC_NAME</filename>, and the path or device on which the
303 rootfs is located is in <filename>LXC_ROOTFS_PATH</filename>.
304 </para>
305 </refsect1>
306
307 &commonoptions;
308
309 &seealso;
310
311 </refentry>
312
313 <!-- Keep this comment at the end of the file
314 Local variables:
315 mode: sgml
316 sgml-omittag:t
317 sgml-shorttag:t
318 sgml-minimize-attributes:nil
319 sgml-always-quote-attributes:t
320 sgml-indent-step:2
321 sgml-indent-data:t
322 sgml-parent-document:nil
323 sgml-default-dtd-file:nil
324 sgml-exposed-tags:nil
325 sgml-local-catalogs:nil
326 sgml-local-ecat-files:nil
327 End:
328 -->