aboutsummaryrefslogtreecommitdiffstats
path: root/wpa_supplicant/doc/docbook/wpa_supplicant.conf.sgml
blob: ebefe115a1ab7e1eba8264f8ffe028c0f2c5f77a (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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
  <refmeta>
    <refentrytitle>wpa_supplicant.conf</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>wpa_supplicant.conf</refname>
    <refpurpose>configuration file for wpa_supplicant</refpurpose>
  </refnamediv>
  <refsect1>
    <title>Overview</title>

    <para><command>wpa_supplicant</command> is configured using a text
    file that lists all accepted networks and security policies,
    including pre-shared keys. See the example configuration file,
    probably in <command>/usr/share/doc/wpa_supplicant/</command>, for
    detailed information about the configuration format and supported
    fields.</para>

    <para>All file paths in this configuration file should use full
    (absolute, not relative to working directory) path in order to allow
    working directory to be changed. This can happen if wpa_supplicant is
    run in the background.</para>

    <para>Changes to configuration file can be reloaded be sending
    SIGHUP signal to <command>wpa_supplicant</command> ('killall -HUP
    wpa_supplicant'). Similarly, reloading can be triggered with
    the <emphasis>wpa_cli reconfigure</emphasis> command.</para>

    <para>Configuration file can include one or more network blocks,
    e.g., one for each used SSID. wpa_supplicant will automatically
    select the best network based on the order of network blocks in
    the configuration file, network security level (WPA/WPA2 is
    preferred), and signal strength.</para>
  </refsect1>

  <refsect1>
    <title>Quick Examples</title>

    <orderedlist>
      <listitem>

      <para>WPA-Personal (PSK) as home network and WPA-Enterprise with
      EAP-TLS as work network.</para>

<blockquote><programlisting>
# allow frontend (e.g., wpa_cli) to be used by all users in 'wheel' group
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
#
# home network; allow all valid ciphers
network={
	ssid="home"
	scan_ssid=1
	key_mgmt=WPA-PSK
	psk="very secret passphrase"
}
#
# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
network={
	ssid="work"
	scan_ssid=1
	key_mgmt=WPA-EAP
	pairwise=CCMP TKIP
	group=CCMP TKIP
	eap=TLS
	identity="user@example.com"
	ca_cert="/etc/cert/ca.pem"
	client_cert="/etc/cert/user.pem"
	private_key="/etc/cert/user.prv"
	private_key_passwd="password"
}
</programlisting></blockquote>   
      </listitem>

      <listitem>
	<para>WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
        use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
        Aegis, Interlink RAD-Series)</para>

<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
	ssid="example"
	scan_ssid=1
	key_mgmt=WPA-EAP
	eap=PEAP
	identity="user@example.com"
	password="foobar"
	ca_cert="/etc/cert/ca.pem"
	phase1="peaplabel=0"
	phase2="auth=MSCHAPV2"
}
</programlisting></blockquote>
      </listitem>

      <listitem>
	<para>EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
        identity for the unencrypted use. Real identity is sent only
        within an encrypted TLS tunnel.</para>


<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
	ssid="example"
	scan_ssid=1
	key_mgmt=WPA-EAP
	eap=TTLS
	identity="user@example.com"
	anonymous_identity="anonymous@example.com"
	password="foobar"
	ca_cert="/etc/cert/ca.pem"
	phase2="auth=MD5"
}
</programlisting></blockquote>

      </listitem>

      <listitem>
	<para>IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
        (require both unicast and broadcast); use EAP-TLS for
        authentication</para>

<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
	ssid="1x-test"
	scan_ssid=1
	key_mgmt=IEEE8021X
	eap=TLS
	identity="user@example.com"
	ca_cert="/etc/cert/ca.pem"
	client_cert="/etc/cert/user.pem"
	private_key="/etc/cert/user.prv"
	private_key_passwd="password"
	eapol_flags=3
}
</programlisting></blockquote>
      </listitem>


      <listitem>
	<para>Catch all example that allows more or less all
        configuration modes. The configuration options are used based
        on what security policy is used in the selected SSID. This is
        mostly for testing and is not recommended for normal
        use.</para>

<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
	ssid="example"
	scan_ssid=1
	key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
	pairwise=CCMP TKIP
	group=CCMP TKIP WEP104 WEP40
	psk="very secret passphrase"
	eap=TTLS PEAP TLS
	identity="user@example.com"
	password="foobar"
	ca_cert="/etc/cert/ca.pem"
	client_cert="/etc/cert/user.pem"
	private_key="/etc/cert/user.prv"
	private_key_passwd="password"
	phase1="peaplabel=0"
	ca_cert2="/etc/cert/ca2.pem"
	client_cert2="/etc/cer/user.pem"
	private_key2="/etc/cer/user.prv"
	private_key2_passwd="password"
}
</programlisting></blockquote>
      </listitem>

      <listitem>
	<para>Authentication for wired Ethernet. This can be used with
       <emphasis>wired</emphasis> interface (-Dwired on command line).</para>

<blockquote><programlisting>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
ap_scan=0
network={
	key_mgmt=IEEE8021X
	eap=MD5
	identity="user"
	password="password"
	eapol_flags=0
}
</programlisting></blockquote>
      </listitem>
    </orderedlist>





  </refsect1>
  <refsect1>
    <title>Certificates</title>

    <para>Some EAP authentication methods require use of
    certificates. EAP-TLS uses both server side and client
    certificates whereas EAP-PEAP and EAP-TTLS only require the server
    side certificate. When client certificate is used, a matching
    private key file has to also be included in configuration. If the
    private key uses a passphrase, this has to be configured in
    wpa_supplicant.conf ("private_key_passwd").</para>

    <para>wpa_supplicant supports X.509 certificates in PEM and DER
    formats. User certificate and private key can be included in the
    same file.</para>

    <para>If the user certificate and private key is received in
    PKCS#12/PFX format, they need to be converted to suitable PEM/DER
    format for wpa_supplicant. This can be done, e.g., with following
    commands:</para>
<blockquote><programlisting>
# convert client certificate and private key to PEM format
openssl pkcs12 -in example.pfx -out user.pem -clcerts
# convert CA certificate (if included in PFX file) to PEM format
openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
</programlisting></blockquote>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry>
	<refentrytitle>wpa_supplicant</refentrytitle>
	<manvolnum>8</manvolnum>
      </citerefentry>
      <citerefentry>
	<refentrytitle>openssl</refentrytitle>
	<manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>