doc/lxc-create.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
  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-create</refentrytitle>
  38     <manvolnum>1</manvolnum>
  39   </refmeta>
  40
  41   <refnamediv>
  42     <refname>lxc-create</refname>
  43
  44     <refpurpose>
  45       creates a container
  46     </refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <cmdsynopsis>
  51       <command>lxc-create</command>
  52       <arg choice="req">-n <replaceable>name</replaceable></arg>
  53       <arg choice="opt">-f <replaceable>config_file</replaceable></arg>
  54       <arg choice="req">-t <replaceable>template</replaceable></arg>
  55       <arg choice="opt">-B <replaceable>backingstore</replaceable></arg>
  56       <arg choice="opt">-- <replaceable>template-options</replaceable></arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  63     <para>
  64       <command>lxc-create</command> creates a system object where is
  65       stored the configuration information and where can be stored
  66       user information. The identifier <replaceable>name</replaceable>
  67       is used to specify the container to be used with the different
  68       lxc commands.
  69     </para>
  70     <para>
  71       The object is a directory created in <filename>@LXCPATH@</filename>
  72       and identified by its name.
  73     </para>
  74
  75     <para>
  76       The object is the definition of the different resources an
  77       application can use or can see. The more the configuration file
  78       contains information, the more the container is isolated and
  79       the more the application is jailed.
  80     </para>
  81
  82     <para>
  83       If the configuration file <replaceable>config_file</replaceable>
  84       is not specified, the container will be created with the default
  85       isolation: processes, sysv ipc and mount points.
  86     </para>
  87   </refsect1>
  88
  89   <refsect1>
  90     <title>Options</title>
  91     <variablelist>
  92
  93       <varlistentry>
  94         <term>
  95           <option>-f, --config <replaceable>config_file</replaceable></option>
  96         </term>
  97         <listitem>
  98           <para>
  99             Specify the configuration file to configure the virtualization
 100             and isolation functionalities for the container.
 101           </para>
 102         </listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term>
 107           <option>-t, --template <replaceable>template</replaceable></option>
 108         </term>
 109         <listitem>
 110           <para>
 111             'template' is the short name of an existing 'lxc-template'
 112             script that is called by lxc-create,
 113             eg. busybox, debian, fedora, ubuntu or sshd.
 114             Refer to the examples in <filename>@LXCTEMPLATEDIR@</filename>
 115             for details of the expected script structure.
 116             Alternatively, the full path to an executable template script
 117             can also be passed as a parameter.
 118             "none" can be used to force lxc-create to skip rootfs creation.
 119           </para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term>
 125           <option>-B, --bdev <replaceable>backingstore</replaceable></option>
 126         </term>
 127         <listitem>
 128           <para>
 129             'backingstore' is one of 'dir', 'lvm', 'loop', 'btrfs', 'zfs', 'rbd', or 'best'.  The
 130             default is 'dir', meaning that the container root filesystem
 131             will be a directory under <filename>@LXCPATH@/container/rootfs</filename>.
 132             This backing store type allows the optional
 133             <replaceable>--dir ROOTFS</replaceable> to be specified, meaning
 134             that the container rootfs should be placed under the specified path,
 135             rather than the default.  (The 'none' backingstore type is an alias for
 136             'dir'.)  If 'btrfs' is specified, then the
 137             target filesystem must be btrfs, and the container rootfs will be
 138             created as a new subvolume.  This allows snapshotted clones to be
 139             created, but also causes rsync --one-filesystem to treat it as a
 140             separate filesystem.
 141             If backingstore is 'lvm', then an lvm block device will be
 142             used and the following further options are available:
 143             <replaceable>--lvname lvname1</replaceable> will create an LV
 144             named <filename>lvname1</filename> rather than the default, which
 145             is the container name.  <replaceable>--vgname vgname1</replaceable>
 146             will create the LV in volume group <filename>vgname1</filename>
 147             rather than the default, <filename>lxc</filename>.
 148             <replaceable>--thinpool thinpool1</replaceable> will create the
 149             LV as a thin-provisioned volume in the pool named
 150             <filename>thinpool1</filename> rather than the
 151             default, <filename>lxc</filename>.
 152             <replaceable>--fstype FSTYPE</replaceable> will create an FSTYPE
 153             filesystem on the LV, rather than the default, which is ext4.
 154             <replaceable>--fssize SIZE</replaceable> will create a LV (and
 155             filesystem) of size SIZE rather than the default, which is 1G.
 156           </para>
 157           <para>
 158             If backingstore is 'loop', you can use <replaceable>--fstype FSTYPE</replaceable> and <replaceable>--fssize SIZE</replaceable> as 'lvm'. The default values for these options are the same as 'lvm'.
 159           </para>
 160           <para>
 161             If backingstore is 'rbd', then you will need to have a valid configuration in <filename>ceph.conf</filename> and a <filename>ceph.client.admin.keyring</filename> defined.
 162             You can specify the following options :
 163             <replaceable>--rbdname RBDNAME</replaceable> will create a blockdevice named RBDNAME rather than the default, which is the container name.
 164             <replaceable>--rbdpool POOL</replaceable> will create the blockdevice in the pool named POOL, rather than the default, which is 'lxc'.
 165           </para>
 166           <para>
 167             If backingstore is 'best', then lxc will try, in order, btrfs,
 168             zfs, lvm, and finally a directory backing store.
 169           </para>
 170         </listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term>
 175           <option>-- <replaceable>template-options</replaceable></option>
 176         </term>
 177         <listitem>
 178           <para>
 179             This will pass <replaceable>template-options</replaceable> to the
 180             template as arguments.  To see the list of options supported by
 181             the template, you can run
 182             <command>lxc-create -t TEMPLATE -h</command>.
 183           </para>
 184         </listitem>
 185       </varlistentry>
 186
 187     </variablelist>
 188
 189   </refsect1>
 190
 191   &commonoptions;
 192
 193   <refsect1>
 194     <title>Diagnostic</title>
 195
 196     <variablelist>
 197
 198       <varlistentry>
 199         <term>The container already exists</term>
 200         <listitem>
 201           <para>
 202             As the message mention it, you try to create a container
 203             but there is a container with the same name. You can use
 204             the <command>lxc-ls</command> command to list the
 205             available containers on the system.
 206           </para>
 207         </listitem>
 208       </varlistentry>
 209
 210     </variablelist>
 211
 212   </refsect1>
 213
 214   &seealso;
 215
 216   <refsect1>
 217     <title>Author</title>
 218     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 219   </refsect1>
 220
 221 </refentry>
 222
 223 <!-- Keep this comment at the end of the file
 224 Local variables:
 225 mode: sgml
 226 sgml-omittag:t
 227 sgml-shorttag:t
 228 sgml-minimize-attributes:nil
 229 sgml-always-quote-attributes:t
 230 sgml-indent-step:2
 231 sgml-indent-data:t
 232 sgml-parent-document:nil
 233 sgml-default-dtd-file:nil
 234 sgml-exposed-tags:nil
 235 sgml-local-catalogs:nil
 236 sgml-local-ecat-files:nil
 237 End:
 238 -->