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