doc/lxc-user-nic.sgml.in

   1 <!--
   2
   3 lxc: linux Container library
   4
   5 (C) Copyright Canonical Ltd. 2013
   6
   7 Authors:
   8 Serge Hallyn <serge.hallyn@ubuntu.com>
   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-user-nic</refentrytitle>
  38     <manvolnum>1</manvolnum>
  39   </refmeta>
  40
  41   <refnamediv>
  42     <refname>lxc-user-nic</refname>
  43
  44     <refpurpose>
  45       Manage nics in another network namespace
  46     </refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <cmdsynopsis>
  51       <command>lxc-user-nic</command>
  52       <command>create</command>
  53       <arg choice="req"><replaceable>lxcpath</replaceable></arg>
  54       <arg choice="req"><replaceable>name</replaceable></arg>
  55       <arg choice="req"><replaceable>pid</replaceable></arg>
  56       <arg choice="req"><replaceable>type</replaceable></arg>
  57       <arg choice="req"><replaceable>bridge</replaceable></arg>
  58       <arg choice="req"><replaceable>container nicname</replaceable></arg>
  59     </cmdsynopsis>
  60
  61     <cmdsynopsis>
  62       <command>lxc-user-nic</command>
  63       <command>delete</command>
  64       <arg choice="req"><replaceable>lxcpath</replaceable></arg>
  65       <arg choice="req"><replaceable>name</replaceable></arg>
  66       <arg choice="req"><replaceable>path to network namespace</replaceable></arg>
  67       <arg choice="req"><replaceable>type</replaceable></arg>
  68       <arg choice="req"><replaceable>bridge</replaceable></arg>
  69       <arg choice="req"><replaceable>container nicname</replaceable></arg>
  70     </cmdsynopsis>
  71   </refsynopsisdiv>
  72
  73   <refsect1>
  74     <title>Description</title>
  75
  76     <para>
  77       <command>lxc-user-nic</command> is a setuid-root program with which
  78       unprivileged users may manage network interfaces for use by a
  79       lxc container.
  80     </para>
  81     <para>
  82       It will consult the configuration file <filename>@LXC_USERNIC_CONF@</filename>
  83       to determine the number of interfaces which the calling user is allowed to
  84       create, and which bridge he may attach them to.  It tracks the
  85       number of interfaces each user has created using the file
  86       <filename>@LXC_USERNIC_DB@</filename>.  It ensures that the calling
  87       user is privileged over the network namespace to which the interface
  88       will be attached.
  89       <command>lxc-user-nic</command> also allows to delete network devices.
  90       Currently only ovs ports can be deleted.
  91     </para>
  92
  93   </refsect1>
  94
  95   <refsect1>
  96
  97     <title>Options</title>
  98
  99     <variablelist>
 100       <varlistentry>
 101         <term>
 102           <option><replaceable>lxcpath</replaceable></option>
 103         </term>
 104         <listitem>
 105           <para>
 106           The path of the container. This is currently not used.
 107           </para>
 108         </listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term>
 113           <option><replaceable>name</replaceable></option>
 114         </term>
 115         <listitem>
 116           <para>
 117           The name of the container. This is currently not used.
 118           </para>
 119         </listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term>
 124           <option><replaceable>pid</replaceable></option>
 125         </term>
 126         <listitem>
 127           <para>
 128           The process id for the task to whose network namespace the interface
 129           should be attached.
 130           </para>
 131         </listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term>
 136           <option><replaceable>type</replaceable></option>
 137         </term>
 138         <listitem>
 139           <para>
 140           The network interface type to attach. Currently only veth is
 141           supported.  With this type, two interfaces representing each
 142           tunnel endpoint are created.  One endpoint will be attached
 143           to the specified bridge, while the other will be passed into
 144           the container.
 145           </para>
 146         </listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term>
 151           <option><replaceable>bridge</replaceable></option>
 152         </term>
 153         <listitem>
 154           <para>
 155           The bridge to which to attach the network interface, for
 156           instance <filename>lxcbr0</filename>.
 157           </para>
 158         </listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term>
 163           <option><replaceable>container nicname</replaceable></option>
 164         </term>
 165         <listitem>
 166           <para>
 167           The desired interface name in the container. This will be
 168           <filename>eth0</filename> if unspecified.
 169           </para>
 170         </listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term>
 175           <option><replaceable>path to network namespace</replaceable></option>
 176         </term>
 177         <listitem>
 178           <para>
 179           A path to open to get a file descriptor for the target
 180           network namespace.
 181           This is only relevant when an veth device is deleted.
 182           </para>
 183         </listitem>
 184       </varlistentry>
 185
 186     </variablelist>
 187
 188   </refsect1>
 189
 190   <refsect1>
 191     <title>See Also</title>
 192
 193     <simpara>
 194       <citerefentry>
 195         <refentrytitle><command>lxc</command></refentrytitle>
 196         <manvolnum>1</manvolnum>
 197       </citerefentry>,
 198
 199       <citerefentry>
 200         <refentrytitle><command>lxc-start</command></refentrytitle>
 201         <manvolnum>1</manvolnum>
 202       </citerefentry>,
 203
 204       <citerefentry>
 205         <refentrytitle><command>lxc-usernet</command></refentrytitle>
 206         <manvolnum>5</manvolnum>
 207       </citerefentry>
 208     </simpara>
 209    </refsect1>
 210
 211   <refsect1>
 212     <title>Author</title>
 213     <para>Christian Brauner <email>christian@brauner.io</email></para>
 214     <para>Serge Hallyn <email>serge@hallyn.com</email></para>
 215     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 216   </refsect1>
 217
 218 </refentry>
 219
 220 <!-- Keep this comment at the end of the file
 221 Local variables:
 222 mode: sgml
 223 sgml-omittag:t
 224 sgml-shorttag:t
 225 sgml-minimize-attributes:nil
 226 sgml-always-quote-attributes:t
 227 sgml-indent-step:2
 228 sgml-indent-data:t
 229 sgml-parent-document:nil
 230 sgml-default-dtd-file:nil
 231 sgml-exposed-tags:nil
 232 sgml-local-catalogs:nil
 233 sgml-local-ecat-files:nil
 234 End:
 235 -->