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