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