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 <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 <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 <replaceable>backingstore</replaceable></option>
 126         </term>
 127         <listitem>
 128           <para>
 129             'backingstore' is one of 'dir', 'lvm', 'loop', 'btrfs', 'zfs', 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 'best', then lxc will try, in order, btrfs,
 162             zfs, lvm, and finally a directory backing store.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term>
 169           <option>-- <replaceable>template-options</replaceable></option>
 170         </term>
 171         <listitem>
 172           <para>
 173             This will pass <replaceable>template-options</replaceable> to the
 174             template as arguments.  To see the list of options supported by
 175             the template, you can run
 176             <command>lxc-create -t TEMPLATE -h</command>.
 177           </para>
 178         </listitem>
 179       </varlistentry>
 180
 181     </variablelist>
 182
 183   </refsect1>
 184
 185   &commonoptions;
 186
 187   <refsect1>
 188     <title>Diagnostic</title>
 189
 190     <variablelist>
 191
 192       <varlistentry>
 193         <term>The container already exists</term>
 194         <listitem>
 195           <para>
 196             As the message mention it, you try to create a container
 197             but there is a container with the same name. You can use
 198             the <command>lxc-ls</command> command to list the
 199             available containers on the system.
 200           </para>
 201         </listitem>
 202       </varlistentry>
 203
 204     </variablelist>
 205
 206   </refsect1>
 207
 208   &seealso;
 209
 210   <refsect1>
 211     <title>Author</title>
 212     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 213   </refsect1>
 214
 215 </refentry>
 216
 217 <!-- Keep this comment at the end of the file
 218 Local variables:
 219 mode: sgml
 220 sgml-omittag:t
 221 sgml-shorttag:t
 222 sgml-minimize-attributes:nil
 223 sgml-always-quote-attributes:t
 224 sgml-indent-step:2
 225 sgml-indent-data:t
 226 sgml-parent-document:nil
 227 sgml-default-dtd-file:nil
 228 sgml-exposed-tags:nil
 229 sgml-local-catalogs:nil
 230 sgml-local-ecat-files:nil
 231 End:
 232 -->