wpa_supplicant/doc/docbook/wpa_priv.sgml

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2
   3 <refentry>
   4   <refmeta>
   5     <refentrytitle>wpa_priv</refentrytitle>
   6     <manvolnum>8</manvolnum>
   7   </refmeta>
   8   <refnamediv>
   9     <refname>wpa_priv</refname>
  10
  11     <refpurpose>wpa_supplicant privilege separation helper</refpurpose>
  12   </refnamediv>
  13
  14   <refsynopsisdiv>
  15     <cmdsynopsis>
  16       <command>wpa_priv</command>
  17       <arg>-c <replaceable>ctrl path</replaceable></arg>
  18       <arg>-Bdd</arg>
  19       <arg>-P <replaceable>pid file</replaceable></arg>
  20       <arg>driver:ifname <replaceable>[driver:ifname ...]</replaceable></arg>
  21     </cmdsynopsis>
  22   </refsynopsisdiv>
  23
  24   <refsect1>
  25     <title>Overview</title>
  26
  27     <para><command>wpa_priv</command> is a privilege separation helper that
  28     minimizes the size of <command>wpa_supplicant</command> code that needs
  29     to be run with root privileges.</para>
  30
  31     <para>If enabled, privileged operations are done in the wpa_priv process
  32     while leaving rest of the code (e.g., EAP authentication and WPA
  33     handshakes) to operate in an unprivileged process (wpa_supplicant) that
  34     can be run as non-root user. Privilege separation restricts the effects
  35     of potential software errors by containing the majority of the code in an
  36     unprivileged process to avoid the possibility of a full system
  37     compromise.</para>
  38
  39     <para><command>wpa_priv</command> needs to be run with network admin
  40     privileges (usually, root user). It opens a UNIX domain socket for each
  41     interface that is included on the command line; any other interface will
  42     be off limits for <command>wpa_supplicant</command> in this kind of
  43     configuration. After this, <command>wpa_supplicant</command> can be run as
  44     a non-root user (e.g., all standard users on a laptop or as a special
  45     non-privileged user account created just for this purpose to limit access
  46     to user files even further).</para>
  47   </refsect1>
  48   <refsect1>
  49     <title>Example configuration</title>
  50
  51     <para>The following steps are an example of how to configure
  52     <command>wpa_priv</command> to allow users in the
  53     <emphasis>wpapriv</emphasis> group to communicate with
  54     <command>wpa_supplicant</command> with privilege separation:</para>
  55
  56     <para>Create user group (e.g., wpapriv) and assign users that
  57     should be able to use wpa_supplicant into that group.</para>
  58
  59     <para>Create /var/run/wpa_priv directory for UNIX domain sockets and
  60     control user access by setting it accessible only for the wpapriv
  61     group:</para>
  62
  63 <blockquote><programlisting>
  64 mkdir /var/run/wpa_priv
  65 chown root:wpapriv /var/run/wpa_priv
  66 chmod 0750 /var/run/wpa_priv
  67 </programlisting></blockquote>
  68
  69     <para>Start <command>wpa_priv</command> as root (e.g., from system
  70     startup scripts) with the enabled interfaces configured on the
  71     command line:</para>
  72
  73 <blockquote><programlisting>
  74 wpa_priv -B -c /var/run/wpa_priv -P /var/run/wpa_priv.pid wext:wlan0
  75 </programlisting></blockquote>
  76
  77     <para>Run <command>wpa_supplicant</command> as non-root with a user
  78     that is in the wpapriv group:</para>
  79
  80 <blockquote><programlisting>
  81 wpa_supplicant -i ath0 -c wpa_supplicant.conf
  82 </programlisting></blockquote>
  83
  84   </refsect1>
  85   <refsect1>
  86     <title>Command Arguments</title>
  87     <variablelist>
  88       <varlistentry>
  89         <term>-c ctrl path</term>
  90
  91         <listitem><para>Specify the path to wpa_priv control directory
  92         (Default: /var/run/wpa_priv/).</para></listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term>-B</term>
  97         <listitem><para>Run as a daemon in the background.</para></listitem>
  98       </varlistentry>
  99
 100       <varlistentry>
 101         <term>-P file</term>
 102
 103         <listitem><para>Set the location of the PID
 104         file.</para></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term>driver:ifname [driver:ifname ...]</term>
 109
 110         <listitem><para>The &lt;driver&gt; string dictates which of the
 111         supported <command>wpa_supplicant</command> driver backends is to be
 112         used. To get a list of supported driver types see wpa_supplicant help
 113         (e.g, wpa_supplicant -h). The driver backend supported by most good
 114         drivers is <emphasis>wext</emphasis>.</para>
 115
 116         <para>The &lt;ifname&gt; string specifies which network
 117         interface is to be managed by <command>wpa_supplicant</command>
 118         (e.g., wlan0 or ath0).</para>
 119
 120         <para><command>wpa_priv</command> does not use the network interface
 121         before <command>wpa_supplicant</command> is started, so it is fine to
 122         include network interfaces that are not available at the time wpa_priv
 123         is started. wpa_priv can control multiple interfaces with one process,
 124         but it is also possible to run multiple <command>wpa_priv</command>
 125         processes at the same time, if desired.</para></listitem>
 126       </varlistentry>
 127     </variablelist>
 128   </refsect1>
 129   <refsect1>
 130     <title>See Also</title>
 131     <para>
 132       <citerefentry>
 133         <refentrytitle>wpa_supplicant</refentrytitle>
 134         <manvolnum>8</manvolnum>
 135       </citerefentry>
 136     </para>
 137   </refsect1>
 138   <refsect1>
 139     <title>Legal</title>
 140     <para>wpa_supplicant is copyright (c) 2003-2007,
 141     Jouni Malinen <email>j@w1.fi</email> and
 142     contributors.
 143     All Rights Reserved.</para>
 144
 145     <para>This program is dual-licensed under both the GPL version 2
 146     and BSD license. Either license may be used at your option.</para>
 147   </refsect1>
 148 </refentry>