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 <replaceable>namespaces</replaceable></arg>
  54       <arg choice="req">-u <replaceable>user</replaceable></arg>
  55       <arg choice="req">command</arg>
  56     </cmdsynopsis>
  57   </refsynopsisdiv>
  58
  59   <refsect1>
  60     <title>Description</title>
  61
  62     <para>
  63       <command>lxc-unshare</command> can be used to run a task in a cloned set
  64       of namespaces.  This command is mainly provided for testing purposes.
  65       Despite its name, it always uses clone rather than unshare to create
  66       the new task with fresh namespaces.  Apart from testing kernel
  67       regressions this should make no difference.
  68     </para>
  69
  70   </refsect1>
  71
  72   <refsect1>
  73
  74     <title>Options</title>
  75
  76     <variablelist>
  77
  78       <varlistentry>
  79         <term>
  80           <option>-s <replaceable>namespaces</replaceable></option>
  81         </term>
  82         <listitem>
  83           <para>
  84             Specify the namespaces to attach to, as a pipe-separated list,
  85             e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
  86             <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
  87             <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
  88             <replaceable>USER </replaceable> and
  89             <replaceable>NETWORK</replaceable>. This allows one to change
  90             the context of the process to e.g. the network namespace of the
  91             container while retaining the other namespaces as those of the
  92             host.
  93           </para>
  94         </listitem>
  95       </varlistentry>
  96
  97       <varlistentry>
  98         <term>
  99           <option>-u <replaceable>user</replaceable></option>
 100         </term>
 101         <listitem>
 102           <para>
 103             Specify a user which the new task should become.  This option is
 104             only valid if a user namespace is unshared.
 105           </para>
 106         </listitem>
 107       </varlistentry>
 108
 109     </variablelist>
 110
 111   </refsect1>
 112
 113   <refsect1>
 114     <title>Examples</title>
 115       <para>
 116         To spawn a new shell with its own UTS (hostname) namespace,
 117         <programlisting>
 118           lxc-unshare -s UTSNAME /bin/bash
 119         </programlisting>
 120         If the hostname is changed in that shell, the change will not be
 121         reflected on the host.
 122       </para>
 123       <para>
 124         To spawn a shell in a new network, pid, and mount namespace,
 125         <programlisting>
 126           lxc-unshare -s "NETWORK|PID|MOUNT" /bin/bash
 127         </programlisting>
 128         The resulting shell will have pid 1 and will see no network interfaces.
 129         After re-mounting /proc in that shell,
 130         <programlisting>
 131           mount -t proc proc /proc
 132         </programlisting>
 133         ps output will show there are no other processes in the namespace.
 134       </para>
 135   </refsect1>
 136
 137   &seealso;
 138
 139   <refsect1>
 140     <title>Author</title>
 141     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 142   </refsect1>
 143
 144 </refentry>
 145
 146 <!-- Keep this comment at the end of the file
 147 Local variables:
 148 mode: sgml
 149 sgml-omittag:t
 150 sgml-shorttag:t
 151 sgml-minimize-attributes:nil
 152 sgml-always-quote-attributes:t
 153 sgml-indent-step:2
 154 sgml-indent-data:t
 155 sgml-parent-document:nil
 156 sgml-default-dtd-file:nil
 157 sgml-exposed-tags:nil
 158 sgml-local-catalogs:nil
 159 sgml-local-ecat-files:nil
 160 End:
 161 -->