doc/lxc-clone.sgml.in

   1 <!--
   2
   3 lxc: linux Container library
   4
   5 (C) Copyright IBM Corp. 2007, 2008
   6
   7 Authors:
   8 Daniel Lezcano <daniel.lezcano at free.fr>
   9 Serge Hallyn <serge.hallyn at ubuntu.com>
  10
  11 This library is free software; you can redistribute it and/or
  12 modify it under the terms of the GNU Lesser General Public
  13 License as published by the Free Software Foundation; either
  14 version 2.1 of the License, or (at your option) any later version.
  15
  16 This library is distributed in the hope that it will be useful,
  17 but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19 Lesser General Public License for more details.
  20
  21 You should have received a copy of the GNU Lesser General Public
  22 License along with this library; if not, write to the Free Software
  23 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  24
  25 -->
  26
  27 <!DOCTYPE refentry PUBLIC @docdtd@ [
  28
  29 <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
  30 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
  31 ]>
  32
  33 <refentry>
  34
  35   <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
  36
  37   <refmeta>
  38     <refentrytitle>lxc-clone</refentrytitle>
  39     <manvolnum>1</manvolnum>
  40   </refmeta>
  41
  42   <refnamediv>
  43     <refname>lxc-clone</refname>
  44
  45     <refpurpose>
  46       clone a new container from an existing one.
  47     </refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <cmdsynopsis>
  52       <command>lxc-clone</command>
  53       <arg choice="opt">-s </arg>
  54       <arg choice="opt">-K </arg>
  55       <arg choice="opt">-M </arg>
  56       <arg choice="opt">-H </arg>
  57       <arg choice="opt">-B <replaceable>backingstore</replaceable></arg>
  58       <arg choice="opt">-L <replaceable>fssize</replaceable></arg>
  59       <arg choice="opt">-p <replaceable>lxcpath</replaceable></arg>
  60       <arg choice="opt">-P <replaceable>newlxcpath</replaceable></arg>
  61       <arg choice="opt">-R </arg>
  62       <arg choice="req">-o <replaceable>orig</replaceable></arg>
  63       <arg choice="req">-n <replaceable>new</replaceable></arg>
  64       <arg choice="opt">-- hook arguments</arg>
  65     </cmdsynopsis>
  66     <cmdsynopsis>
  67       <command>lxc-clone</command>
  68       <arg choice="opt">-s </arg>
  69       <arg choice="opt">-K </arg>
  70       <arg choice="opt">-M </arg>
  71       <arg choice="opt">-H </arg>
  72       <arg choice="opt">-B <replaceable>backingstore</replaceable></arg>
  73       <arg choice="opt">-L <replaceable>fssize</replaceable></arg>
  74       <arg choice="opt">-p <replaceable>lxcpath</replaceable></arg>
  75       <arg choice="opt">-P <replaceable>newlxcpath</replaceable></arg>
  76       <arg choice="opt">-R </arg>
  77       <arg choice="req">orig</arg>
  78       <arg choice="req">new</arg>
  79       <arg choice="opt">-- hook arguments</arg>
  80     </cmdsynopsis>
  81   </refsynopsisdiv>
  82
  83   <refsect1>
  84     <title>Description</title>
  85
  86     <para>
  87       <command>lxc-clone</command> Creates a new container as a clone of an existing
  88       container.  Two types of clones are supported: copy and snapshot.  A copy
  89       clone copies the root filessytem from the original container to the new.  A
  90       snapshot filesystem uses the backing store's snapshot functionality to create
  91       a very small copy-on-write snapshot of the original container.  Snapshot
  92       clones require the new container backing store to support snapshotting.  Currently
  93       this includes only aufs, btrfs, lvm, overlayfs and zfs.  LVM devices do not support
  94       snapshots of snapshots.
  95     </para>
  96
  97     <para>
  98       The backing store of the new container will be the same type as the
  99       original container, with one exception, overlay containers.
 100       aufs and overlayfs snapshots can be created of directory backed
 101       containers.  This can be requested by using (for overlayfs) the
 102       <replaceable>-B overlayfs</replaceable> arguments.
 103     </para>
 104
 105     <para>
 106       The names of the original and new container can be given (in that order)
 107       after all options, or can be specified with the
 108       <replaceable>-o</replaceable> and <replaceable>-n</replaceable> options,
 109       respectively.
 110     </para>
 111
 112   </refsect1>
 113
 114   <refsect1>
 115
 116     <title>Options</title>
 117
 118     <variablelist>
 119
 120       <varlistentry>
 121         <term>
 122           <option>-s, --snapshot</option>
 123         </term>
 124         <listitem>
 125           <para>
 126             The new container's rootfs will be a snapshot of the original. This option can be specified when the backing store is LVM, btrfs or zfs, and must be specified when you want to snapshot using aufs or overlayfs.
 127           </para>
 128         </listitem>
 129       </varlistentry>
 130
 131       <varlistentry>
 132         <term>
 133           <option>-K, --keepname</option>
 134         </term>
 135         <listitem>
 136           <para>
 137             Do not change the hostname of the container (in the root
 138             filesystem).
 139           </para>
 140         </listitem>
 141       </varlistentry>
 142
 143       <varlistentry>
 144         <term>
 145           <option>-M, --keepmac</option>
 146         </term>
 147         <listitem>
 148           <para>
 149             Use the same MAC address as the original container, rather than
 150             generating a new random one.
 151           </para>
 152         </listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term>
 157           <option>-H, --copyhooks</option>
 158         </term>
 159         <listitem>
 160           <para>
 161             Copy all mount hooks into the new container's directory, and
 162             update any lxcpaths and container names as needed.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term>
 169           <option>-L, --fssize <replaceable>fssize</replaceable></option>
 170         </term>
 171         <listitem>
 172           <para>
 173             In the case of a block device backed container, a size for the new
 174             block device.  By default, the new device will be made the
 175             same size as the original.
 176           </para>
 177         </listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term>
 182           <option>-p, --lxcpath <replaceable>lxcpath</replaceable></option>
 183         </term>
 184         <listitem>
 185           <para>
 186             The lxcpath of the original container.  By default, the system
 187             wide configured lxcpath will be used.
 188           </para>
 189         </listitem>
 190       </varlistentry>
 191
 192       <varlistentry>
 193         <term>
 194           <option>-P, --newpath <replaceable>newlxcpath</replaceable></option>
 195         </term>
 196         <listitem>
 197           <para>
 198             The lxcpath for the new container.  By default the same lxcpath
 199             as the original will be used.  Note that with btrfs snapshots,
 200             changing lxcpaths may not be possible, as subvolume snapshots
 201             must be in the same btrfs filesystem.
 202           </para>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term>
 208           <option>-B, --backingstore <replaceable>backingstore</replaceable></option>
 209         </term>
 210         <listitem>
 211           <para>
 212             Select a different backing store for the new container.  By
 213             default the same as the original container's is used.  Note that
 214             currently changing the backingstore is only supported for
 215             aufs and overlayfs snapshots of directory backed containers.  Valid
 216             backing stores include dir (directory), aufs, btrfs, lvm, zfs, loop
 217             and overlayfs.
 218           </para>
 219         </listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term>
 224           <option>-R, --rename</option>
 225         </term>
 226         <listitem>
 227           <para>
 228             Rename an existing container.
 229             <replaceable>orig</replaceable> is renamed <replaceable>new</replaceable>.
 230           </para>
 231         </listitem>
 232       </varlistentry>
 233
 234       <varlistentry>
 235         <term>
 236           <option>-o, --orig <replaceable>orig</replaceable></option>
 237         </term>
 238         <listitem>
 239           <para>
 240             The name of the original container to clone.
 241           </para>
 242         </listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term>
 247           <option>-n, --new <replaceable>new</replaceable></option>
 248         </term>
 249         <listitem>
 250           <para>
 251             The name of the new container to create.
 252           </para>
 253         </listitem>
 254       </varlistentry>
 255
 256
 257     </variablelist>
 258
 259   </refsect1>
 260
 261   <refsect1>
 262     <title>Clone hook</title>
 263     <para>
 264       If the container being cloned has one or more <filename>lxc.hook.clone</filename>
 265       specified, then the specified hooks will be called for the new container.  The
 266       first 3 arguments passed to the clone hook will be the container name, a section
 267       ('lxc'), and the hook type ('clone').  Extra arguments passed
 268       <command>lxc-clone</command> will be passed to the hook program starting at
 269       argument 4.  The <filename>LXC_ROOTFS_MOUNT</filename> environment variable gives
 270       the path under which the container's root filesystem is mounted.  The
 271       configuration file pathname is stored in <filename>LXC_CONFIG_FILE</filename>, the
 272       new container name in <filename>LXC_NAME</filename>, the old container name in
 273       <filename>LXC_SRC_NAME</filename>, and the path or device on which
 274       the rootfs is located is in <filename>LXC_ROOTFS_PATH</filename>.
 275     </para>
 276   </refsect1>
 277
 278   &seealso;
 279
 280   <refsect1>
 281     <title>Author</title>
 282     <para>Serge Hallyn <email>serge.hallyn@ubuntu.com</email></para>
 283   </refsect1>
 284
 285 </refentry>
 286
 287 <!-- Keep this comment at the end of the file
 288 Local variables:
 289 mode: sgml
 290 sgml-omittag:t
 291 sgml-shorttag:t
 292 sgml-minimize-attributes:nil
 293 sgml-always-quote-attributes:t
 294 sgml-indent-step:2
 295 sgml-indent-data:t
 296 sgml-parent-document:nil
 297 sgml-default-dtd-file:nil
 298 sgml-exposed-tags:nil
 299 sgml-local-catalogs:nil
 300 sgml-local-ecat-files:nil
 301 End:
 302 -->