1<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2<refentry>
3  <refentryinfo>
4    <date>07 August 2019</date>
5  </refentryinfo>
6
7  <refmeta>
8    <refentrytitle>wpa_supplicant.conf</refentrytitle>
9    <manvolnum>5</manvolnum>
10  </refmeta>
11  <refnamediv>
12    <refname>wpa_supplicant.conf</refname>
13    <refpurpose>configuration file for wpa_supplicant</refpurpose>
14  </refnamediv>
15  <refsect1>
16    <title>Overview</title>
17
18    <para><command>wpa_supplicant</command> is configured using a text
19    file that lists all accepted networks and security policies,
20    including pre-shared keys. See the example configuration file,
21    probably in <command>/usr/share/doc/wpa_supplicant/</command>, for
22    detailed information about the configuration format and supported
23    fields.</para>
24
25    <para>All file paths in this configuration file should use full
26    (absolute, not relative to working directory) path in order to allow
27    working directory to be changed. This can happen if wpa_supplicant is
28    run in the background.</para>
29
30    <para>Changes to configuration file can be reloaded be sending
31    SIGHUP signal to <command>wpa_supplicant</command> ('killall -HUP
32    wpa_supplicant'). Similarly, reloading can be triggered with
33    the <emphasis>wpa_cli reconfigure</emphasis> command.</para>
34
35    <para>Configuration file can include one or more network blocks,
36    e.g., one for each used SSID. wpa_supplicant will automatically
37    select the best network based on the order of network blocks in
38    the configuration file, network security level (WPA/WPA2 is
39    preferred), and signal strength.</para>
40  </refsect1>
41
42  <refsect1>
43    <title>Quick Examples</title>
44
45    <orderedlist>
46      <listitem>
47
48      <para>WPA-Personal (PSK) as home network and WPA-Enterprise with
49      EAP-TLS as work network.</para>
50
51<blockquote><programlisting>
52# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
53ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
54#
55# home network; allow all valid ciphers
56network={
57	ssid="home"
58	scan_ssid=1
59	key_mgmt=WPA-PSK
60	psk="very secret passphrase"
61}
62#
63# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
64network={
65	ssid="work"
66	scan_ssid=1
67	key_mgmt=WPA-EAP
68	pairwise=CCMP TKIP
69	group=CCMP TKIP
70	eap=TLS
71	identity="user@example.com"
72	ca_cert="/etc/cert/ca.pem"
73	client_cert="/etc/cert/user.pem"
74	private_key="/etc/cert/user.prv"
75	private_key_passwd="password"
76}
77</programlisting></blockquote>
78      </listitem>
79
80      <listitem>
81	<para>WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
82        use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
83        Aegis, Interlink RAD-Series)</para>
84
85<blockquote><programlisting>
86ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
87network={
88	ssid="example"
89	scan_ssid=1
90	key_mgmt=WPA-EAP
91	eap=PEAP
92	identity="user@example.com"
93	password="foobar"
94	ca_cert="/etc/cert/ca.pem"
95	phase1="peaplabel=0"
96	phase2="auth=MSCHAPV2"
97}
98</programlisting></blockquote>
99      </listitem>
100
101      <listitem>
102	<para>EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
103        identity for the unencrypted use. Real identity is sent only
104        within an encrypted TLS tunnel.</para>
105
106
107<blockquote><programlisting>
108ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
109network={
110	ssid="example"
111	scan_ssid=1
112	key_mgmt=WPA-EAP
113	eap=TTLS
114	identity="user@example.com"
115	anonymous_identity="anonymous@example.com"
116	password="foobar"
117	ca_cert="/etc/cert/ca.pem"
118	phase2="auth=MD5"
119}
120</programlisting></blockquote>
121
122      </listitem>
123
124      <listitem>
125	<para>IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
126        (require both unicast and broadcast); use EAP-TLS for
127        authentication</para>
128
129<blockquote><programlisting>
130ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
131network={
132	ssid="1x-test"
133	scan_ssid=1
134	key_mgmt=IEEE8021X
135	eap=TLS
136	identity="user@example.com"
137	ca_cert="/etc/cert/ca.pem"
138	client_cert="/etc/cert/user.pem"
139	private_key="/etc/cert/user.prv"
140	private_key_passwd="password"
141	eapol_flags=3
142}
143</programlisting></blockquote>
144      </listitem>
145
146
147      <listitem>
148	<para>Catch all example that allows more or less all
149        configuration modes. The configuration options are used based
150        on what security policy is used in the selected SSID. This is
151        mostly for testing and is not recommended for normal
152        use.</para>
153
154<blockquote><programlisting>
155ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
156network={
157	ssid="example"
158	scan_ssid=1
159	key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
160	pairwise=CCMP TKIP
161	group=CCMP TKIP WEP104 WEP40
162	psk="very secret passphrase"
163	eap=TTLS PEAP TLS
164	identity="user@example.com"
165	password="foobar"
166	ca_cert="/etc/cert/ca.pem"
167	client_cert="/etc/cert/user.pem"
168	private_key="/etc/cert/user.prv"
169	private_key_passwd="password"
170	phase1="peaplabel=0"
171	ca_cert2="/etc/cert/ca2.pem"
172	client_cert2="/etc/cer/user.pem"
173	private_key2="/etc/cer/user.prv"
174	private_key2_passwd="password"
175}
176</programlisting></blockquote>
177      </listitem>
178
179      <listitem>
180	<para>Authentication for wired Ethernet. This can be used with
181        <emphasis>wired</emphasis> or <emphasis>roboswitch</emphasis> interface
182        (-Dwired or -Droboswitch on command line).</para>
183
184<blockquote><programlisting>
185ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
186ap_scan=0
187network={
188	key_mgmt=IEEE8021X
189	eap=MD5
190	identity="user"
191	password="password"
192	eapol_flags=0
193}
194</programlisting></blockquote>
195      </listitem>
196    </orderedlist>
197
198
199
200
201
202  </refsect1>
203  <refsect1>
204    <title>Certificates</title>
205
206    <para>Some EAP authentication methods require use of
207    certificates. EAP-TLS uses both server side and client
208    certificates whereas EAP-PEAP and EAP-TTLS only require the server
209    side certificate. When client certificate is used, a matching
210    private key file has to also be included in configuration. If the
211    private key uses a passphrase, this has to be configured in
212    wpa_supplicant.conf ("private_key_passwd").</para>
213
214    <para>wpa_supplicant supports X.509 certificates in PEM and DER
215    formats. User certificate and private key can be included in the
216    same file.</para>
217
218    <para>If the user certificate and private key is received in
219    PKCS#12/PFX format, they need to be converted to suitable PEM/DER
220    format for wpa_supplicant. This can be done, e.g., with following
221    commands:</para>
222<blockquote><programlisting>
223# convert client certificate and private key to PEM format
224openssl pkcs12 -in example.pfx -out user.pem -clcerts
225# convert CA certificate (if included in PFX file) to PEM format
226openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
227</programlisting></blockquote>
228  </refsect1>
229
230  <refsect1>
231    <title>See Also</title>
232    <para>
233      <citerefentry>
234	<refentrytitle>wpa_supplicant</refentrytitle>
235	<manvolnum>8</manvolnum>
236      </citerefentry>
237      <citerefentry>
238	<refentrytitle>openssl</refentrytitle>
239	<manvolnum>1</manvolnum>
240      </citerefentry>
241    </para>
242  </refsect1>
243</refentry>
244