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