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="opt">-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           </para>
 119         </listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term>
 124           <option>-B <replaceable>backingstore</replaceable></option>
 125         </term>
 126         <listitem>
 127           <para>
 128             'backingstore' is one of 'none', 'dir', 'lvm', 'loop', or 'btrfs'.  The
 129             default is 'none', meaning that the container root filesystem
 130             will be a directory under <filename>@LXCPATH@/container/rootfs</filename>.
 131             'dir' has the same meaning as 'none', but also allows the optional
 132             <replaceable>--dir ROOTFS</replaceable> to be specified, meaning
 133             that the container rootfs should be placed under the specified path,
 134             rather than the default.  If 'btrfs' is specified, then the
 135             target filesystem must be btrfs, and the container rootfs will be
 136             created as a new subvolume.  This allows snapshotted clones to be
 137             created, but also causes rsync --one-filesystem to treat it as a
 138             separate filesystem.
 139             If backingstore is 'lvm', then an lvm block device will be
 140             used and the following further options are available:
 141             <replaceable>--lvname lvname1</replaceable> will create an LV
 142             named <filename>lvname1</filename> rather than the default, which
 143             is the container name.  <replaceable>--vgname vgname1</replaceable>
 144             will create the LV in volume group <filename>vgname1</filename>
 145             rather than the default, <filename>lxc</filename>.
 146             <replaceable>--thinpool thinpool1</replaceable> will create the
 147             LV as a thin-provisioned volume in the pool named
 148             <filename>thinpool1</filename> rather than the
 149             default, <filename>lxc</filename>.
 150             <replaceable>--fstype FSTYPE</replaceable> will create an FSTYPE
 151             filesystem on the LV, rather than the default, which is ext4.
 152             <replaceable>--fssize SIZE</replaceable> will create a LV (and
 153             filesystem) of size SIZE rather than the default, which is 1G.
 154           </para>
 155         </listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term>
 160           <option>-- <replaceable>template-options</replaceable></option>
 161         </term>
 162         <listitem>
 163           <para>
 164             This will pass <replaceable>template-options</replaceable> to the
 165             template as arguments.  To see the list of options supported by
 166             the template, you can run
 167             <command>lxc-create -t TEMPLATE -h</command>.
 168           </para>
 169         </listitem>
 170       </varlistentry>
 171
 172     </variablelist>
 173
 174   </refsect1>
 175
 176   <refsect1>
 177     <title>Diagnostic</title>
 178
 179     <variablelist>
 180
 181       <varlistentry>
 182         <term>The container already exists</term>
 183         <listitem>
 184           <para>
 185             As the message mention it, you try to create a container
 186             but there is a container with the same name. You can use
 187             the <command>lxc-ls -l</command> command to list the
 188             available containers on the system.
 189           </para>
 190         </listitem>
 191       </varlistentry>
 192
 193     </variablelist>
 194
 195   </refsect1>
 196
 197   &seealso;
 198
 199   <refsect1>
 200     <title>Author</title>
 201     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 202   </refsect1>
 203
 204 </refentry>
 205
 206 <!-- Keep this comment at the end of the file
 207 Local variables:
 208 mode: sgml
 209 sgml-omittag:t
 210 sgml-shorttag:t
 211 sgml-minimize-attributes:nil
 212 sgml-always-quote-attributes:t
 213 sgml-indent-step:2
 214 sgml-indent-data:t
 215 sgml-parent-document:nil
 216 sgml-default-dtd-file:nil
 217 sgml-exposed-tags:nil
 218 sgml-local-catalogs:nil
 219 sgml-local-ecat-files:nil
 220 End:
 221 -->