← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/wpasupplicant/gutsy

« back to all changes in this revision

Viewing changes to doc/docbook/wpa_supplicant.conf.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Reinhard Tartler, Alexander Sack
  • Date: 2007-08-26 16:06:57 UTC
  • mfrom: (1.1.9 upstream)
  • Revision ID: james.westby@ubuntu.com-20070826160657-2m8pxoweuxe8f93t
Tags: 0.6.0+0.5.8-0ubuntu1
https://launchpad.net/bugs/140763
https://launchpad.net/bugs/141233
* New upstream release
* remove patch 11_erroneous_manpage_ref, applied upstream
* remove patch 25_wpas_dbus_unregister_iface_fix, applied upstream

[ Alexander Sack ]
* bumping upstream version to replace development version 0.6.0 with
  this package from stable release branch.
* attempt to fix wierd timeout and high latency issues by going
  back to stable upstream version (0.5.9) (LP: #140763,
  LP: #141233).

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/docbook/wpa_supplicant.conf.sgml
 
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 'wpa_cli reconfigure' 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
 
49
ctrl_interface=/var/run/wpa_supplicant
 
50
ctrl_interface_group=wheel
 
51
#
 
52
# home network; allow all valid ciphers
 
53
network={
 
54
        ssid="home"
 
55
        scan_ssid=1
 
56
        key_mgmt=WPA-PSK
 
57
        psk="very secret passphrase"
 
58
}
 
59
#
 
60
# work network; use EAP-TLS with WPA; allow only CCMP and TKIP ciphers
 
61
network={
 
62
        ssid="work"
 
63
        scan_ssid=1
 
64
        key_mgmt=WPA-EAP
 
65
        pairwise=CCMP TKIP
 
66
        group=CCMP TKIP
 
67
        eap=TLS
 
68
        identity="user@example.com"
 
69
        ca_cert="/etc/cert/ca.pem"
 
70
        client_cert="/etc/cert/user.pem"
 
71
        private_key="/etc/cert/user.prv"
 
72
        private_key_passwd="password"
 
73
}
 
74
</programlisting></blockquote>   
 
75
      </listitem>
 
76
 
 
77
      <listitem>
 
78
        <para>WPA-RADIUS/EAP-PEAP/MSCHAPv2 with RADIUS servers that
 
79
        use old peaplabel (e.g., Funk Odyssey and SBR, Meetinghouse
 
80
        Aegis, Interlink RAD-Series)</para>
 
81
 
 
82
<blockquote><programlisting>
 
83
ctrl_interface=/var/run/wpa_supplicant
 
84
ctrl_interface_group=wheel
 
85
network={
 
86
        ssid="example"
 
87
        scan_ssid=1
 
88
        key_mgmt=WPA-EAP
 
89
        eap=PEAP
 
90
        identity="user@example.com"
 
91
        password="foobar"
 
92
        ca_cert="/etc/cert/ca.pem"
 
93
        phase1="peaplabel=0"
 
94
        phase2="auth=MSCHAPV2"
 
95
}
 
96
</programlisting></blockquote>
 
97
      </listitem>
 
98
 
 
99
      <listitem>
 
100
        <para>EAP-TTLS/EAP-MD5-Challenge configuration with anonymous
 
101
        identity for the unencrypted use. Real identity is sent only
 
102
        within an encrypted TLS tunnel.</para>
 
103
 
 
104
 
 
105
<blockquote><programlisting>
 
106
ctrl_interface=/var/run/wpa_supplicant
 
107
ctrl_interface_group=wheel
 
108
network={
 
109
        ssid="example"
 
110
        scan_ssid=1
 
111
        key_mgmt=WPA-EAP
 
112
        eap=TTLS
 
113
        identity="user@example.com"
 
114
        anonymous_identity="anonymous@example.com"
 
115
        password="foobar"
 
116
        ca_cert="/etc/cert/ca.pem"
 
117
        phase2="auth=MD5"
 
118
}
 
119
</programlisting></blockquote>
 
120
 
 
121
      </listitem>
 
122
 
 
123
      <listitem>
 
124
        <para>IEEE 802.1X (i.e., no WPA) with dynamic WEP keys
 
125
        (require both unicast and broadcast); use EAP-TLS for
 
126
        authentication</para>
 
127
 
 
128
<blockquote><programlisting>
 
129
ctrl_interface=/var/run/wpa_supplicant
 
130
ctrl_interface_group=wheel
 
131
network={
 
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>
 
155
ctrl_interface=/var/run/wpa_supplicant
 
156
ctrl_interface_group=wheel
 
157
network={
 
158
        ssid="example"
 
159
        scan_ssid=1
 
160
        key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
 
161
        pairwise=CCMP TKIP
 
162
        group=CCMP TKIP WEP104 WEP40
 
163
        psk="very secret passphrase"
 
164
        eap=TTLS PEAP TLS
 
165
        identity="user@example.com"
 
166
        password="foobar"
 
167
        ca_cert="/etc/cert/ca.pem"
 
168
        client_cert="/etc/cert/user.pem"
 
169
        private_key="/etc/cert/user.prv"
 
170
        private_key_passwd="password"
 
171
        phase1="peaplabel=0"
 
172
        ca_cert2="/etc/cert/ca2.pem"
 
173
        client_cert2="/etc/cer/user.pem"
 
174
        private_key2="/etc/cer/user.prv"
 
175
        private_key2_passwd="password"
 
176
}
 
177
</programlisting></blockquote>
 
178
      </listitem>
 
179
 
 
180
      <listitem>
 
181
        <para>Authentication for wired Ethernet. This can be used with
 
182
       'wired' interface (-Dwired on command line).</para>
 
183
 
 
184
<blockquote><programlisting>
 
185
ctrl_interface=/var/run/wpa_supplicant
 
186
ctrl_interface_group=wheel
 
187
ap_scan=0
 
188
network={
 
189
        key_mgmt=IEEE8021X
 
190
        eap=MD5
 
191
        identity="user"
 
192
        password="password"
 
193
        eapol_flags=0
 
194
}
 
195
</programlisting></blockquote>
 
196
      </listitem>
 
197
    </orderedlist>
 
198
 
 
199
 
 
200
 
 
201
 
 
202
 
 
203
  </refsect1>
 
204
  <refsect1>
 
205
    <title>Certificates</title>
 
206
 
 
207
    <para>Some EAP authentication methods require use of
 
208
    certificates. EAP-TLS uses both server side and client
 
209
    certificates whereas EAP-PEAP and EAP-TTLS only require the server
 
210
    side certificate. When client certificate is used, a matching
 
211
    private key file has to also be included in configuration. If the
 
212
    private key uses a passphrase, this has to be configured in
 
213
    wpa_supplicant.conf ("private_key_passwd").</para>
 
214
 
 
215
    <para>wpa_supplicant supports X.509 certificates in PEM and DER
 
216
    formats. User certificate and private key can be included in the
 
217
    same file.</para>
 
218
 
 
219
    <para>If the user certificate and private key is received in
 
220
    PKCS#12/PFX format, they need to be converted to suitable PEM/DER
 
221
    format for wpa_supplicant. This can be done, e.g., with following
 
222
    commands:</para>
 
223
<blockquote><programlisting>
 
224
# convert client certificate and private key to PEM format
 
225
openssl pkcs12 -in example.pfx -out user.pem -clcerts
 
226
# convert CA certificate (if included in PFX file) to PEM format
 
227
openssl pkcs12 -in example.pfx -out ca.pem -cacerts -nokeys
 
228
</programlisting></blockquote>
 
229
  </refsect1>
 
230
 
 
231
  <refsect1>
 
232
    <title>See Also</title>
 
233
    <para>
 
234
      <citerefentry>
 
235
        <refentrytitle>wpa_supplicant</refentrytitle>
 
236
        <manvolnum>8</manvolnum>
 
237
      </citerefentry>
 
238
      <citerefentry>
 
239
        <refentrytitle>openssl</refentrytitle>
 
240
        <manvolnum>1</manvolnum>
 
241
      </citerefentry>
 
242
    </para>
 
243
  </refsect1>
 
244
</refentry>