wpa_priv.sgml revision 04949598a23f501be6eec21697465fd46a28840a 
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>
64mkdir /var/run/wpa_priv
65chown root:wpapriv /var/run/wpa_priv
66chmod 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>
74wpa_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>
81wpa_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-2012,
141    Jouni Malinen <email>j@w1.fi</email> and
142    contributors.
143    All Rights Reserved.</para>
144
145    <para>This program is licensed under the BSD license (the one with
146    advertisement clause removed).</para>
147  </refsect1>
148</refentry>
149