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