| 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 |
--> |