doc/lxc-copy.sgml.in

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