doc/lxc-unshare.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-unshare</refentrytitle>
  39     <manvolnum>1</manvolnum>
  40   </refmeta>
  41
  42   <refnamediv>
  43     <refname>lxc-unshare</refname>
  44
  45     <refpurpose>
  46       Run a task in a new set of namespaces.
  47     </refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <cmdsynopsis>
  52       <command>lxc-unshare</command>
  53       <arg choice="req">-s, --namespaces <replaceable>namespaces</replaceable></arg>
  54       <arg choice="opt">-u, --user <replaceable>user</replaceable></arg>
  55       <arg choice="opt">-H, --hostname <replaceable>hostname</replaceable></arg>
  56       <arg choice="opt">-i, --ifname <replaceable>ifname</replaceable></arg>
  57       <arg choice="opt">-d, --daemon</arg>
  58       <arg choice="opt">-M, --remount</arg>
  59       <arg choice="req">command</arg>
  60     </cmdsynopsis>
  61   </refsynopsisdiv>
  62
  63   <refsect1>
  64     <title>Description</title>
  65
  66     <para>
  67       <command>lxc-unshare</command> can be used to run a task in a cloned set
  68       of namespaces.  This command is mainly provided for testing purposes.
  69       Despite its name, it always uses clone rather than unshare to create
  70       the new task with fresh namespaces.  Apart from testing kernel
  71       regressions this should make no difference.
  72     </para>
  73
  74   </refsect1>
  75
  76   <refsect1>
  77
  78     <title>Options</title>
  79
  80     <variablelist>
  81
  82       <varlistentry>
  83         <term>
  84           <option>-s, --namespaces <replaceable>namespaces</replaceable></option>
  85         </term>
  86         <listitem>
  87           <para>
  88             Specify the namespaces to attach to, as a pipe-separated list,
  89             e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
  90             <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
  91             <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
  92             <replaceable>USER </replaceable> and
  93             <replaceable>NETWORK</replaceable>. This allows one to change
  94             the context of the process to e.g. the network namespace of the
  95             container while retaining the other namespaces as those of the
  96             host. (The pipe symbol needs to be escaped, e.g.
  97             <replaceable>MOUNT\|PID</replaceable> or quoted, e.g.
  98             <replaceable>"MOUNT|PID"</replaceable>.)
  99           </para>
 100         </listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term>
 105           <option>-u, --user <replaceable>user</replaceable></option>
 106         </term>
 107         <listitem>
 108           <para>
 109             Specify a userid which the new task should become.
 110           </para>
 111         </listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term>
 116           <option>-H, --hostname <replaceable>hostname</replaceable></option>
 117         </term>
 118         <listitem>
 119           <para>
 120             Set the hostname in the new container.  Only allowed if
 121             the UTSNAME namespace is set.
 122           </para>
 123         </listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term>
 128           <option>-i, --ifname <replaceable>interfacename</replaceable></option>
 129         </term>
 130         <listitem>
 131           <para>
 132             Move the named interface into the container.  Only allowed
 133             if the NETWORK namespace is set.  You may specify this
 134             argument multiple times to move multiple interfaces into
 135             container.
 136           </para>
 137         </listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term>
 142           <option>-d, --daemon</option>
 143         </term>
 144         <listitem>
 145           <para>
 146             Daemonize (do not wait for the container to exit before exiting)
 147           </para>
 148         </listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term>
 153           <option>-M, --remount</option>
 154         </term>
 155         <listitem>
 156           <para>
 157             Mount default filesystems (/proc /dev/shm and /dev/mqueue)
 158             in the container.  Only allowed if MOUNT namespace is set.
 159           </para>
 160         </listitem>
 161       </varlistentry>
 162
 163     </variablelist>
 164
 165   </refsect1>
 166
 167   <refsect1>
 168     <title>Examples</title>
 169       <para>
 170         To spawn a new shell with its own UTS (hostname) namespace,
 171         <programlisting>
 172           lxc-unshare -s UTSNAME /bin/bash
 173         </programlisting>
 174         If the hostname is changed in that shell, the change will not be
 175         reflected on the host.
 176       </para>
 177       <para>
 178         To spawn a shell in a new network, pid, and mount namespace,
 179         <programlisting>
 180           lxc-unshare -s "NETWORK|PID|MOUNT" /bin/bash
 181         </programlisting>
 182         The resulting shell will have pid 1 and will see no network interfaces.
 183         After re-mounting /proc in that shell,
 184         <programlisting>
 185           mount -t proc proc /proc
 186         </programlisting>
 187         ps output will show there are no other processes in the namespace.
 188       </para>
 189       <para>
 190         To spawn a shell in a new network, pid, mount, and hostname
 191         namespace.
 192         <programlisting>
 193           lxc-unshare -s "NETWORK|PID|MOUNT|UTSNAME" -M -H myhostname -i veth1 /bin/bash
 194         </programlisting>
 195
 196         The resulting shell will have pid 1 and will see two network
 197         interfaces (lo and veth1).  The hostname will be "myhostname" and
 198         /proc will have been remounted.  ps output will show there are
 199         no other processes in the namespace.
 200       </para>
 201   </refsect1>
 202
 203   &seealso;
 204
 205   <refsect1>
 206     <title>Author</title>
 207     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 208   </refsect1>
 209
 210 </refentry>
 211
 212 <!-- Keep this comment at the end of the file
 213 Local variables:
 214 mode: sgml
 215 sgml-omittag:t
 216 sgml-shorttag:t
 217 sgml-minimize-attributes:nil
 218 sgml-always-quote-attributes:t
 219 sgml-indent-step:2
 220 sgml-indent-data:t
 221 sgml-parent-document:nil
 222 sgml-default-dtd-file:nil
 223 sgml-exposed-tags:nil
 224 sgml-local-catalogs:nil
 225 sgml-local-ecat-files:nil
 226 End:
 227 -->