doc/lxc-usernsexec.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-usernsexec</refentrytitle>
  39     <manvolnum>1</manvolnum>
  40   </refmeta>
  41
  42   <refnamediv>
  43     <refname>lxc-usernsexec</refname>
  44
  45     <refpurpose>
  46       Run a task as root in a new user namespace.
  47     </refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <cmdsynopsis>
  52       <command>lxc-usernsexec</command>
  53       <arg choice="opt">-m <replaceable>uid-map</replaceable></arg>
  54       <arg choice="req">-- command</arg>
  55     </cmdsynopsis>
  56   </refsynopsisdiv>
  57
  58   <refsect1>
  59     <title>Description</title>
  60
  61     <para>
  62       <command>lxc-usernsexec</command> can be used to run a task as root
  63       in a new user namespace.
  64     </para>
  65
  66   </refsect1>
  67
  68   <refsect1>
  69
  70     <title>Options</title>
  71
  72     <variablelist>
  73
  74       <varlistentry>
  75         <term>
  76           <option>-m <replaceable>uid-map</replaceable></option>
  77         </term>
  78         <listitem>
  79           <para>
  80           The uid map to use in the user namespace.  Each map consists of
  81           four colon-separate values.  First a character 'u', 'g' or 'b' to
  82           specify whether this map pertains to user ids, group ids, or
  83           both; next the first userid in the user namespace;  next the
  84           first userid as seen on the host;  and finally the number of
  85           ids to be mapped.
  86           </para>
  87           <para>
  88           More than one map can be specified.  If no map is
  89           specified, then by default the full uid and gid ranges granted
  90           by /etc/subuid and /etc/subgid will be mapped to the
  91           uids and gids starting at 0 in the container.
  92           </para>
  93           <para>
  94           Note that <replaceable>lxc-usernsexec</replaceable> always tries
  95           to setuid and setgid to 0 in the namespace.  Therefore uid 0 in
  96           the namespace must be mapped.
  97           </para>
  98         </listitem>
  99       </varlistentry>
 100
 101
 102     </variablelist>
 103
 104   </refsect1>
 105
 106   <refsect1>
 107     <title>Examples</title>
 108       <para>
 109         To spawn a shell with the full allotted subuids mapped into
 110         the container, use
 111         <programlisting>
 112           lxc-usernsexec
 113         </programlisting>
 114         To run a different shell than <replaceable>/bin/sh</replaceable>, use
 115         <programlisting>
 116           lxc-usernsexec -- /bin/bash
 117         </programlisting>
 118       </para>
 119       <para>
 120         If your user id is 1000, root in a container is mapped to 190000, and
 121         you wish to chown a file you own to root in the container, you can use:
 122         <programlisting>
 123           lxc-usernsexec -m b:0:1000:1 -m b:1:190000:1 -- /bin/chown 1:1 $file
 124         </programlisting>
 125         This maps your userid to root in the user namespace, and 190000 to uid 1.
 126         Since root in the user namespace is privileged over all userids mapped
 127         into the namespace, you are allowed to change the file ownership, which
 128         you could not do on the host using a simple chown.
 129       </para>
 130   </refsect1>
 131
 132   &seealso;
 133
 134   <refsect1>
 135     <title>Author</title>
 136     <para>Serge Hallyn <email>serge.hallyn@ubuntu.com</email></para>
 137   </refsect1>
 138
 139 </refentry>
 140
 141 <!-- Keep this comment at the end of the file
 142 Local variables:
 143 mode: sgml
 144 sgml-omittag:t
 145 sgml-shorttag:t
 146 sgml-minimize-attributes:nil
 147 sgml-always-quote-attributes:t
 148 sgml-indent-step:2
 149 sgml-indent-data:t
 150 sgml-parent-document:nil
 151 sgml-default-dtd-file:nil
 152 sgml-exposed-tags:nil
 153 sgml-local-catalogs:nil
 154 sgml-local-ecat-files:nil
 155 End:
 156 -->