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 informations 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 informations, 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>--fstype FSTYPE</replaceable> will create an FSTYPE
 147             filesystem on the LV, rather than the default, which is ext4.
 148             <replaceable>--fssize SIZE</replaceable> will create a LV (and
 149             filesystem) of size SIZE rather than the default, which is 1G.
 150           </para>
 151         </listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term>
 156           <option>-- <replaceable>template-options</replaceable></option>
 157         </term>
 158         <listitem>
 159           <para>
 160             This will pass <replaceable>template-options</replaceable> to the
 161             template as arguments.  To see the list of options supported by
 162             the template, you can run
 163             <command>lxc-create -t TEMPLATE -h</command>.
 164           </para>
 165         </listitem>
 166       </varlistentry>
 167
 168     </variablelist>
 169
 170   </refsect1>
 171
 172   <refsect1>
 173     <title>Diagnostic</title>
 174
 175     <variablelist>
 176
 177       <varlistentry>
 178         <term>The container already exists</term>
 179         <listitem>
 180           <para>
 181             As the message mention it, you try to create a container
 182             but there is a container with the same name. You can use
 183             the <command>lxc-ls -l</command> command to list the
 184             available containers on the system.
 185           </para>
 186         </listitem>
 187       </varlistentry>
 188
 189     </variablelist>
 190
 191   </refsect1>
 192
 193   &seealso;
 194
 195   <refsect1>
 196     <title>Author</title>
 197     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 198   </refsect1>
 199
 200 </refentry>
 201
 202 <!-- Keep this comment at the end of the file
 203 Local variables:
 204 mode: sgml
 205 sgml-omittag:t
 206 sgml-shorttag:t
 207 sgml-minimize-attributes:nil
 208 sgml-always-quote-attributes:t
 209 sgml-indent-step:2
 210 sgml-indent-data:t
 211 sgml-parent-document:nil
 212 sgml-default-dtd-file:nil
 213 sgml-exposed-tags:nil
 214 sgml-local-catalogs:nil
 215 sgml-local-ecat-files:nil
 216 End:
 217 -->