aboutsummaryrefslogtreecommitdiffstats
path: root/wpa_supplicant/doc/docbook/wpa_priv.sgml
blob: 9c114cc3e712bbca6d33e3c20d433dd58aa66da1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<refentry>
  <refmeta>
    <refentrytitle>wpa_priv</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>wpa_priv</refname>

    <refpurpose>wpa_supplicant privilege separation helper</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>wpa_priv</command>
      <arg>-c <replaceable>ctrl path</replaceable></arg>
      <arg>-Bdd</arg>
      <arg>-P <replaceable>pid file</replaceable></arg>
      <arg>driver:ifname <replaceable>[driver:ifname ...]</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Overview</title>

    <para><command>wpa_priv</command> is a privilege separation helper that
    minimizes the size of <command>wpa_supplicant</command> code that needs
    to be run with root privileges.</para>

    <para>If enabled, privileged operations are done in the wpa_priv process
    while leaving rest of the code (e.g., EAP authentication and WPA
    handshakes) to operate in an unprivileged process (wpa_supplicant) that
    can be run as non-root user. Privilege separation restricts the effects
    of potential software errors by containing the majority of the code in an
    unprivileged process to avoid the possibility of a full system
    compromise.</para>

    <para><command>wpa_priv</command> needs to be run with network admin
    privileges (usually, root user). It opens a UNIX domain socket for each
    interface that is included on the command line; any other interface will
    be off limits for <command>wpa_supplicant</command> in this kind of
    configuration. After this, <command>wpa_supplicant</command> can be run as
    a non-root user (e.g., all standard users on a laptop or as a special
    non-privileged user account created just for this purpose to limit access
    to user files even further).</para>
  </refsect1>
  <refsect1>
    <title>Example configuration</title>

    <para>The following steps are an example of how to configure
    <command>wpa_priv</command> to allow users in the
    <emphasis>wpapriv</emphasis> group to communicate with
    <command>wpa_supplicant</command> with privilege separation:</para>

    <para>Create user group (e.g., wpapriv) and assign users that
    should be able to use wpa_supplicant into that group.</para>

    <para>Create /var/run/wpa_priv directory for UNIX domain sockets and
    control user access by setting it accessible only for the wpapriv
    group:</para>

<blockquote><programlisting>
mkdir /var/run/wpa_priv
chown root:wpapriv /var/run/wpa_priv
chmod 0750 /var/run/wpa_priv
</programlisting></blockquote>

    <para>Start <command>wpa_priv</command> as root (e.g., from system
    startup scripts) with the enabled interfaces configured on the
    command line:</para>

<blockquote><programlisting>
wpa_priv -B -c /var/run/wpa_priv -P /var/run/wpa_priv.pid wext:wlan0
</programlisting></blockquote>

    <para>Run <command>wpa_supplicant</command> as non-root with a user
    that is in the wpapriv group:</para>

<blockquote><programlisting>
wpa_supplicant -i ath0 -c wpa_supplicant.conf
</programlisting></blockquote>

  </refsect1>
  <refsect1>
    <title>Command Arguments</title>
    <variablelist>
      <varlistentry>
	<term>-c ctrl path</term>

	<listitem><para>Specify the path to wpa_priv control directory
	(Default: /var/run/wpa_priv/).</para></listitem>
      </varlistentry>

      <varlistentry>
	<term>-B</term>
	<listitem><para>Run as a daemon in the background.</para></listitem>
      </varlistentry>

      <varlistentry>
	<term>-P file</term>

	<listitem><para>Set the location of the PID
	file.</para></listitem>
      </varlistentry>

      <varlistentry>
	<term>driver:ifname [driver:ifname ...]</term>

	<listitem><para>The &lt;driver&gt; string dictates which of the
	supported <command>wpa_supplicant</command> driver backends is to be
	used. To get a list of supported driver types see wpa_supplicant help
	(e.g, wpa_supplicant -h). The driver backend supported by most good
	drivers is <emphasis>wext</emphasis>.</para>

	<para>The &lt;ifname&gt; string specifies which network
	interface is to be managed by <command>wpa_supplicant</command>
	(e.g., wlan0 or ath0).</para>

	<para><command>wpa_priv</command> does not use the network interface
	before <command>wpa_supplicant</command> is started, so it is fine to
	include network interfaces that are not available at the time wpa_priv
	is started. wpa_priv can control multiple interfaces with one process,
	but it is also possible to run multiple <command>wpa_priv</command>
	processes at the same time, if desired.</para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry>
	<refentrytitle>wpa_supplicant</refentrytitle>
	<manvolnum>8</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
  <refsect1>
    <title>Legal</title>
    <para>wpa_supplicant is copyright (c) 2003-2014,
    Jouni Malinen <email>j@w1.fi</email> and
    contributors.
    All Rights Reserved.</para>

    <para>This program is licensed under the BSD license (the one with
    advertisement clause removed).</para>
  </refsect1>
</refentry>