]>
Commit | Line | Data |
---|---|---|
6fc6879b JM |
1 | <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> |
2 | ||
3 | <refentry> | |
4 | <refmeta> | |
5 | <refentrytitle>wpa_supplicant</refentrytitle> | |
6 | <manvolnum>8</manvolnum> | |
7 | </refmeta> | |
8 | <refnamediv> | |
9 | <refname>wpa_supplicant</refname> | |
10 | <refpurpose>Wi-Fi Protected Access client and IEEE 802.1X supplicant</refpurpose> | |
11 | </refnamediv> | |
12 | <refsynopsisdiv> | |
13 | <cmdsynopsis> | |
14 | <command>wpa_supplicant</command> | |
32185f54 | 15 | <arg>-BddfhKLqqsTtuvW</arg> |
6fc6879b JM |
16 | <arg>-i<replaceable>ifname</replaceable></arg> |
17 | <arg>-c<replaceable>config file</replaceable></arg> | |
18 | <arg>-D<replaceable>driver</replaceable></arg> | |
19 | <arg>-P<replaceable>PID_file</replaceable></arg> | |
20 | <arg>-f<replaceable>output file</replaceable></arg> | |
21 | </cmdsynopsis> | |
22 | </refsynopsisdiv> | |
23 | <refsect1> | |
24 | <title>Overview</title> | |
25 | ||
26 | <para> | |
27 | Wireless networks do not require physical access to the network equipment | |
28 | in the same way as wired networks. This makes it easier for unauthorized | |
29 | users to passively monitor a network and capture all transmitted frames. | |
30 | In addition, unauthorized use of the network is much easier. In many cases, | |
31 | this can happen even without user's explicit knowledge since the wireless | |
32 | LAN adapter may have been configured to automatically join any available | |
33 | network. | |
34 | </para> | |
35 | ||
36 | <para> | |
37 | Link-layer encryption can be used to provide a layer of security for | |
38 | wireless networks. The original wireless LAN standard, IEEE 802.11, | |
39 | included a simple encryption mechanism, WEP. However, that proved to | |
40 | be flawed in many areas and network protected with WEP cannot be consider | |
41 | secure. IEEE 802.1X authentication and frequently changed dynamic WEP keys | |
42 | can be used to improve the network security, but even that has inherited | |
43 | security issues due to the use of WEP for encryption. Wi-Fi Protected | |
44 | Access and IEEE 802.11i amendment to the wireless LAN standard introduce | |
45 | a much improvement mechanism for securing wireless networks. IEEE 802.11i | |
46 | enabled networks that are using CCMP (encryption mechanism based on strong | |
47 | cryptographic algorithm AES) can finally be called secure used for | |
48 | applications which require efficient protection against unauthorized | |
49 | access. | |
50 | </para> | |
51 | ||
52 | <para><command>wpa_supplicant</command> is an implementation of | |
53 | the WPA Supplicant component, i.e., the part that runs in the | |
54 | client stations. It implements WPA key negotiation with a WPA | |
55 | Authenticator and EAP authentication with Authentication | |
56 | Server. In addition, it controls the roaming and IEEE 802.11 | |
57 | authentication/association of the wireless LAN driver.</para> | |
58 | ||
59 | <para><command>wpa_supplicant</command> is designed to be a | |
60 | "daemon" program that runs in the background and acts as the | |
61 | backend component controlling the wireless | |
62 | connection. <command>wpa_supplicant</command> supports separate | |
63 | frontend programs and an example text-based frontend, | |
64 | <command>wpa_cli</command>, is included with | |
65 | wpa_supplicant.</para> | |
66 | ||
67 | <para>Before wpa_supplicant can do its work, the network interface | |
68 | must be available. That means that the physical device must be | |
13d9817d | 69 | present and enabled, and the driver for the device must be |
6fc6879b JM |
70 | loaded. The daemon will exit immediately if the device is not already |
71 | available.</para> | |
72 | ||
73 | <para>After <command>wpa_supplicant</command> has configured the | |
74 | network device, higher level configuration such as DHCP may | |
75 | proceed. There are a variety of ways to integrate wpa_supplicant | |
76 | into a machine's networking scripts, a few of which are described | |
77 | in sections below.</para> | |
78 | ||
79 | <para>The following steps are used when associating with an AP | |
80 | using WPA:</para> | |
81 | ||
82 | <itemizedlist> | |
83 | <listitem> | |
84 | <para><command>wpa_supplicant</command> requests the kernel | |
85 | driver to scan neighboring BSSes</para> | |
86 | </listitem> | |
87 | ||
88 | <listitem> | |
89 | <para><command>wpa_supplicant</command> selects a BSS based on | |
90 | its configuration</para> | |
91 | </listitem> | |
92 | ||
93 | <listitem> | |
94 | <para><command>wpa_supplicant</command> requests the kernel | |
95 | driver to associate with the chosen BSS</para> | |
96 | </listitem> | |
97 | ||
98 | <listitem> | |
99 | <para>If WPA-EAP: integrated IEEE 802.1X Supplicant | |
100 | completes EAP authentication with the | |
101 | authentication server (proxied by the Authenticator in the | |
102 | AP)</para> | |
103 | </listitem> | |
104 | ||
105 | <listitem> | |
106 | <para>If WPA-EAP: master key is received from the IEEE 802.1X | |
107 | Supplicant</para> | |
108 | </listitem> | |
109 | ||
110 | <listitem> | |
111 | <para>If WPA-PSK: <command>wpa_supplicant</command> uses PSK | |
112 | as the master session key</para> | |
113 | </listitem> | |
114 | ||
115 | <listitem> | |
116 | <para><command>wpa_supplicant</command> completes WPA 4-Way | |
117 | Handshake and Group Key Handshake with the Authenticator | |
118 | (AP)</para> | |
119 | </listitem> | |
120 | ||
121 | <listitem> | |
122 | <para><command>wpa_supplicant</command> configures encryption | |
123 | keys for unicast and broadcast</para> | |
124 | </listitem> | |
125 | ||
126 | <listitem> | |
127 | <para>normal data packets can be transmitted and received</para> | |
128 | </listitem> | |
129 | </itemizedlist> | |
130 | </refsect1> | |
131 | ||
132 | <refsect1> | |
133 | <title>Supported Features</title> | |
134 | <para>Supported WPA/IEEE 802.11i features:</para> | |
135 | <itemizedlist> | |
136 | <listitem> | |
137 | <para>WPA-PSK ("WPA-Personal")</para> | |
138 | </listitem> | |
139 | ||
140 | <listitem> | |
141 | <para>WPA with EAP (e.g., with RADIUS authentication server) | |
142 | ("WPA-Enterprise") Following authentication methods are | |
143 | supported with an integrate IEEE 802.1X Supplicant:</para> | |
144 | ||
145 | <itemizedlist> | |
146 | <listitem> | |
147 | <para>EAP-TLS</para> | |
148 | </listitem> | |
149 | </itemizedlist> | |
150 | ||
151 | <itemizedlist> | |
152 | <listitem> | |
153 | <para>EAP-PEAP/MSCHAPv2 (both PEAPv0 and PEAPv1)</para> | |
154 | </listitem> | |
155 | ||
156 | ||
157 | <listitem> | |
158 | <para>EAP-PEAP/TLS (both PEAPv0 and PEAPv1)</para> | |
159 | </listitem> | |
160 | ||
161 | <listitem> | |
162 | <para>EAP-PEAP/GTC (both PEAPv0 and PEAPv1)</para> | |
163 | </listitem> | |
164 | ||
165 | <listitem> | |
166 | <para>EAP-PEAP/OTP (both PEAPv0 and PEAPv1)</para> | |
167 | </listitem> | |
168 | ||
169 | <listitem> | |
170 | <para>EAP-PEAP/MD5-Challenge (both PEAPv0 and PEAPv1)</para> | |
171 | </listitem> | |
172 | ||
173 | <listitem> | |
174 | <para>EAP-TTLS/EAP-MD5-Challenge</para> | |
175 | </listitem> | |
176 | ||
177 | <listitem> | |
178 | <para>EAP-TTLS/EAP-GTC</para> | |
179 | </listitem> | |
180 | ||
181 | <listitem><para>EAP-TTLS/EAP-OTP</para></listitem> | |
182 | ||
183 | <listitem><para>EAP-TTLS/EAP-MSCHAPv2</para></listitem> | |
184 | ||
185 | <listitem><para>EAP-TTLS/EAP-TLS</para></listitem> | |
186 | ||
187 | <listitem><para>EAP-TTLS/MSCHAPv2</para></listitem> | |
188 | ||
189 | <listitem><para>EAP-TTLS/MSCHAP</para></listitem> | |
190 | ||
191 | <listitem><para>EAP-TTLS/PAP</para></listitem> | |
192 | ||
193 | <listitem><para>EAP-TTLS/CHAP</para></listitem> | |
194 | ||
195 | <listitem><para>EAP-SIM</para></listitem> | |
196 | ||
197 | <listitem><para>EAP-AKA</para></listitem> | |
198 | ||
199 | <listitem><para>EAP-PSK</para></listitem> | |
200 | ||
201 | <listitem><para>EAP-PAX</para></listitem> | |
202 | ||
203 | <listitem><para>LEAP (note: requires special support from | |
204 | the driver for IEEE 802.11 authentication)</para></listitem> | |
205 | ||
206 | <listitem><para>(following methods are supported, but since | |
207 | they do not generate keying material, they cannot be used | |
208 | with WPA or IEEE 802.1X WEP keying)</para></listitem> | |
209 | ||
210 | <listitem><para>EAP-MD5-Challenge </para></listitem> | |
211 | ||
212 | <listitem><para>EAP-MSCHAPv2</para></listitem> | |
213 | ||
214 | <listitem><para>EAP-GTC</para></listitem> | |
215 | ||
216 | <listitem><para>EAP-OTP</para></listitem> | |
217 | </itemizedlist> | |
218 | </listitem> | |
219 | ||
220 | <listitem> | |
221 | <para>key management for CCMP, TKIP, WEP104, WEP40</para> | |
222 | </listitem> | |
223 | ||
224 | <listitem> | |
225 | <para>RSN/WPA2 (IEEE 802.11i)</para> | |
226 | <itemizedlist> | |
227 | <listitem> | |
228 | <para>pre-authentication</para> | |
229 | </listitem> | |
230 | ||
231 | <listitem> | |
232 | <para>PMKSA caching</para> | |
233 | </listitem> | |
234 | </itemizedlist> | |
235 | </listitem> | |
236 | </itemizedlist> | |
237 | </refsect1> | |
238 | ||
239 | <refsect1> | |
240 | <title>Available Drivers</title> | |
7da67940 KM |
241 | <para>A summary of available driver backends is below. Support for each |
242 | of the driver backends is chosen at wpa_supplicant compile time. For a | |
243 | list of supported driver backends that may be used with the -D option on | |
244 | your system, refer to the help output of wpa_supplicant | |
245 | (<emphasis>wpa_supplicant -h</emphasis>).</para> | |
6fc6879b JM |
246 | |
247 | <variablelist> | |
6fc6879b JM |
248 | <varlistentry> |
249 | <term>wext</term> | |
250 | <listitem> | |
251 | <para>Linux wireless extensions (generic).</para> | |
252 | </listitem> | |
253 | </varlistentry> | |
254 | ||
6fc6879b JM |
255 | <varlistentry> |
256 | <term>wired</term> | |
257 | <listitem> | |
258 | <para>wpa_supplicant wired Ethernet driver</para> | |
259 | </listitem> | |
260 | </varlistentry> | |
261 | ||
e519314e JW |
262 | <varlistentry> |
263 | <term>roboswitch</term> | |
264 | <listitem> | |
265 | <para>wpa_supplicant Broadcom switch driver</para> | |
266 | </listitem> | |
267 | </varlistentry> | |
268 | ||
6fc6879b JM |
269 | <varlistentry> |
270 | <term>bsd</term> | |
271 | <listitem> | |
272 | <para>BSD 802.11 support (Atheros, etc.).</para> | |
273 | </listitem> | |
274 | </varlistentry> | |
275 | ||
276 | <varlistentry> | |
277 | <term>ndis</term> | |
278 | <listitem> | |
279 | <para>Windows NDIS driver.</para> | |
280 | </listitem> | |
281 | </varlistentry> | |
282 | </variablelist> | |
283 | </refsect1> | |
284 | ||
285 | <refsect1> | |
286 | <title>Command Line Options</title> | |
9d6762cf PP |
287 | <para>Most command line options have global scope. Some are given per |
288 | interface, and are only valid if at least one <option>-i</option> option | |
289 | is specified, otherwise they're ignored. Option groups for different | |
290 | interfaces must be separated by <option>-N</option> option.</para> | |
6fc6879b JM |
291 | <variablelist> |
292 | <varlistentry> | |
293 | <term>-b br_ifname</term> | |
294 | <listitem> | |
9d6762cf | 295 | <para>Optional bridge interface name. (Per interface)</para> |
6fc6879b JM |
296 | </listitem> |
297 | </varlistentry> | |
298 | ||
299 | <varlistentry> | |
300 | <term>-B</term> | |
301 | <listitem> | |
302 | <para>Run daemon in the background.</para> | |
303 | </listitem> | |
304 | </varlistentry> | |
305 | ||
306 | <varlistentry> | |
307 | <term>-c filename</term> | |
308 | <listitem> | |
9d6762cf | 309 | <para>Path to configuration file. (Per interface)</para> |
6fc6879b JM |
310 | </listitem> |
311 | </varlistentry> | |
312 | ||
313 | <varlistentry> | |
314 | <term>-C ctrl_interface</term> | |
315 | <listitem> | |
9d6762cf PP |
316 | <para>Path to ctrl_interface socket (Per interface. Only used if |
317 | <option>-c</option> is not).</para> | |
6fc6879b JM |
318 | </listitem> |
319 | </varlistentry> | |
320 | ||
321 | <varlistentry> | |
322 | <term>-i ifname</term> | |
323 | <listitem> | |
9d6762cf PP |
324 | <para>Interface to listen on. Multiple instances of this option can |
325 | be present, one per interface, separated by <option>-N</option> | |
326 | option (see below).</para> | |
6fc6879b JM |
327 | </listitem> |
328 | </varlistentry> | |
329 | ||
330 | <varlistentry> | |
331 | <term>-d</term> | |
332 | <listitem> | |
9d6762cf PP |
333 | <para>Increase debugging verbosity (<option>-dd</option> even |
334 | more).</para> | |
6fc6879b JM |
335 | </listitem> |
336 | </varlistentry> | |
337 | ||
338 | <varlistentry> | |
339 | <term>-D driver</term> | |
340 | <listitem> | |
362f781e JM |
341 | <para>Driver to use (can be multiple drivers: nl80211,wext). |
342 | (Per interface, see the available options below.)</para> | |
6fc6879b JM |
343 | </listitem> |
344 | </varlistentry> | |
345 | ||
32185f54 DW |
346 | <varlistentry> |
347 | <term>-e entropy file</term> | |
348 | <listitem> | |
349 | <para>File for <command>wpa_supplicant</command> to use to | |
350 | maintain its internal entropy store in over restarts.</para> | |
351 | </listitem> | |
352 | </varlistentry> | |
353 | ||
6fc6879b JM |
354 | <varlistentry> |
355 | <term>-f output file</term> | |
356 | <listitem> | |
32185f54 DW |
357 | <para>Log output to specified file instead of stdout. (This |
358 | is only available if <command>wpa_supplicant</command> was | |
359 | built with the <literal>CONFIG_DEBUG_FILE</literal> | |
360 | option.)</para> | |
6fc6879b JM |
361 | </listitem> |
362 | </varlistentry> | |
363 | ||
364 | <varlistentry> | |
365 | <term>-g global ctrl_interface</term> | |
366 | <listitem> | |
9d6762cf PP |
367 | <para>Path to global ctrl_interface socket. If specified, interface |
368 | definitions may be omitted.</para> | |
6fc6879b JM |
369 | </listitem> |
370 | </varlistentry> | |
371 | ||
372 | <varlistentry> | |
373 | <term>-K</term> | |
374 | <listitem> | |
375 | <para>Include keys (passwords, etc.) in debug output.</para> | |
376 | </listitem> | |
377 | </varlistentry> | |
378 | ||
6fc6879b JM |
379 | <varlistentry> |
380 | <term>-h</term> | |
381 | <listitem> | |
382 | <para>Help. Show a usage message.</para> | |
383 | </listitem> | |
384 | </varlistentry> | |
385 | ||
386 | <varlistentry> | |
387 | <term>-L</term> | |
388 | <listitem> | |
d755e01b | 389 | <para>Show license (BSD).</para> |
6fc6879b JM |
390 | </listitem> |
391 | </varlistentry> | |
392 | ||
32185f54 DW |
393 | <varlistentry> |
394 | <term>-o override driver</term> | |
395 | <listitem> | |
396 | <para>Override the driver parameter for new | |
397 | interfaces.</para> | |
398 | </listitem> | |
399 | </varlistentry> | |
400 | ||
401 | <varlistentry> | |
402 | <term>-O override ctrl_interface</term> | |
403 | <listitem> | |
404 | <para>Override the ctrl_interface parameter for new | |
405 | interfaces.</para> | |
406 | </listitem> | |
407 | </varlistentry> | |
408 | ||
6fc6879b JM |
409 | <varlistentry> |
410 | <term>-p</term> | |
411 | <listitem> | |
9d6762cf | 412 | <para>Driver parameters. (Per interface)</para> |
6fc6879b JM |
413 | </listitem> |
414 | </varlistentry> | |
415 | ||
416 | <varlistentry> | |
417 | <term>-P PID_file</term> | |
418 | <listitem> | |
419 | <para>Path to PID file.</para> | |
420 | </listitem> | |
421 | </varlistentry> | |
422 | ||
423 | <varlistentry> | |
424 | <term>-q</term> | |
425 | <listitem> | |
9d6762cf PP |
426 | <para>Decrease debugging verbosity (<option>-qq</option> even |
427 | less).</para> | |
6fc6879b JM |
428 | </listitem> |
429 | </varlistentry> | |
430 | ||
32185f54 DW |
431 | <varlistentry> |
432 | <term>-s</term> | |
433 | <listitem> | |
434 | <para>Log output to syslog instead of stdout. (This is only | |
435 | available if <command>wpa_supplicant</command> was built | |
436 | with the <literal>CONFIG_DEBUG_SYSLOG</literal> | |
437 | option.)</para> | |
438 | </listitem> | |
439 | </varlistentry> | |
440 | ||
441 | <varlistentry> | |
442 | <term>-T</term> | |
443 | <listitem> | |
444 | <para>Log output to Linux tracing in addition to any other | |
445 | destinations. (This is only available | |
446 | if <command>wpa_supplicant</command> was built with | |
447 | the <literal>CONFIG_DEBUG_LINUX_TRACING</literal> | |
448 | option.)</para> | |
449 | </listitem> | |
450 | </varlistentry> | |
451 | ||
452 | <varlistentry> | |
453 | <term>-t</term> | |
454 | <listitem> | |
455 | <para>Include timestamp in debug messages.</para> | |
456 | </listitem> | |
457 | </varlistentry> | |
458 | ||
6fc6879b JM |
459 | <varlistentry> |
460 | <term>-u</term> | |
461 | <listitem> | |
32185f54 DW |
462 | <para>Enable DBus control interface. If enabled, interface |
463 | definitions may be omitted. (This is only available | |
464 | if <command>wpa_supplicant</command> was built with | |
3b797130 | 465 | the <literal>CONFIG_DBUS</literal> option.)</para> |
6fc6879b JM |
466 | </listitem> |
467 | </varlistentry> | |
468 | ||
469 | <varlistentry> | |
470 | <term>-v</term> | |
471 | <listitem> | |
472 | <para>Show version.</para> | |
473 | </listitem> | |
474 | </varlistentry> | |
475 | ||
476 | <varlistentry> | |
477 | <term>-W</term> | |
478 | <listitem> | |
479 | <para>Wait for a control interface monitor before starting.</para> | |
480 | </listitem> | |
481 | </varlistentry> | |
482 | ||
483 | <varlistentry> | |
484 | <term>-N</term> | |
485 | <listitem> | |
486 | <para>Start describing new interface.</para> | |
487 | </listitem> | |
488 | </varlistentry> | |
489 | </variablelist> | |
490 | </refsect1> | |
491 | ||
492 | <refsect1> | |
493 | <title>Examples</title> | |
494 | ||
495 | <para>In most common cases, <command>wpa_supplicant</command> is | |
496 | started with:</para> | |
497 | ||
498 | <blockquote><programlisting> | |
499 | wpa_supplicant -B -c/etc/wpa_supplicant.conf -iwlan0 | |
500 | </programlisting></blockquote> | |
501 | ||
502 | <para>This makes the process fork into background.</para> | |
503 | ||
504 | <para>The easiest way to debug problems, and to get debug log for | |
505 | bug reports, is to start <command>wpa_supplicant</command> on | |
506 | foreground with debugging enabled:</para> | |
507 | ||
508 | <blockquote><programlisting> | |
509 | wpa_supplicant -c/etc/wpa_supplicant.conf -iwlan0 -d | |
362f781e JM |
510 | </programlisting></blockquote> |
511 | ||
512 | <para>If the specific driver wrapper is not known beforehand, it is | |
513 | possible to specify multiple comma separated driver wrappers on the command | |
514 | line. <command>wpa_supplicant</command> will use the first driver | |
515 | wrapper that is able to initialize the interface.</para> | |
516 | ||
517 | <blockquote><programlisting> | |
518 | wpa_supplicant -Dnl80211,wext -c/etc/wpa_supplicant.conf -iwlan0 | |
6fc6879b JM |
519 | </programlisting></blockquote> |
520 | ||
521 | <para><command>wpa_supplicant</command> can control multiple | |
522 | interfaces (radios) either by running one process for each | |
523 | interface separately or by running just one process and list of | |
524 | options at command line. Each interface is separated with -N | |
525 | argument. As an example, following command would start | |
526 | wpa_supplicant for two interfaces:</para> | |
527 | ||
528 | <blockquote><programlisting> | |
529 | wpa_supplicant \ | |
fcbf0b0c JM |
530 | -c wpa1.conf -i wlan0 -D nl80211 -N \ |
531 | -c wpa2.conf -i ath0 -D wext | |
6fc6879b JM |
532 | </programlisting></blockquote> |
533 | </refsect1> | |
534 | ||
535 | <refsect1> | |
536 | <title>OS Requirements</title> | |
537 | <para>Current hardware/software requirements:</para> | |
538 | ||
539 | <itemizedlist> | |
540 | <listitem> | |
541 | <para>Linux kernel 2.4.x or 2.6.x with Linux Wireless | |
542 | Extensions v15 or newer</para> | |
543 | </listitem> | |
544 | ||
545 | ||
546 | <listitem> | |
547 | <para>FreeBSD 6-CURRENT</para> | |
548 | </listitem> | |
549 | ||
550 | <listitem> | |
551 | <para>Microsoft Windows with WinPcap (at least WinXP, may work | |
552 | with other versions)</para> | |
553 | </listitem> | |
554 | </itemizedlist> | |
555 | </refsect1> | |
556 | ||
557 | <refsect1> | |
558 | <title>Supported Drivers</title> | |
559 | <variablelist> | |
6fc6879b JM |
560 | <varlistentry> |
561 | <term>Linux wireless extensions</term> | |
562 | <listitem> | |
563 | <para>In theory, any driver that supports Linux wireless | |
564 | extensions can be used with IEEE 802.1X (i.e., not WPA) when | |
565 | using ap_scan=0 option in configuration file.</para> | |
566 | </listitem> | |
567 | </varlistentry> | |
6774c6a9 | 568 | |
6fc6879b JM |
569 | <varlistentry> |
570 | <term>Wired Ethernet drivers</term> | |
571 | <listitem> | |
572 | <para>Use ap_scan=0.</para> | |
573 | </listitem> | |
574 | </varlistentry> | |
575 | ||
576 | <varlistentry> | |
577 | <term>BSD net80211 layer (e.g., Atheros driver)</term> | |
578 | <listitem> | |
579 | <para>At the moment, this is for FreeBSD 6-CURRENT branch.</para> | |
580 | </listitem> | |
581 | </varlistentry> | |
582 | ||
583 | <varlistentry> | |
584 | <term>Windows NDIS</term> | |
585 | <listitem> | |
586 | <para>The current Windows port requires WinPcap | |
587 | (http://winpcap.polito.it/). See README-Windows.txt for more | |
588 | information.</para> | |
589 | </listitem> | |
590 | </varlistentry> | |
591 | </variablelist> | |
592 | ||
6774c6a9 | 593 | |
6fc6879b JM |
594 | <para>wpa_supplicant was designed to be portable for different |
595 | drivers and operating systems. Hopefully, support for more wlan | |
596 | cards and OSes will be added in the future. See developer.txt for | |
597 | more information about the design of wpa_supplicant and porting to | |
598 | other drivers. One main goal is to add full WPA/WPA2 support to | |
599 | Linux wireless extensions to allow new drivers to be supported | |
600 | without having to implement new driver-specific interface code in | |
601 | wpa_supplicant.</para> | |
602 | </refsect1> | |
603 | ||
604 | <refsect1> | |
605 | <title>Architecture</title> <para>The | |
606 | <command>wpa_supplicant</command> system consists of the following | |
607 | components:</para> | |
608 | ||
609 | <variablelist> | |
610 | <varlistentry> | |
611 | <term><filename>wpa_supplicant.conf</filename> </term> | |
612 | <listitem> | |
613 | <para>the configuration file describing all networks that the | |
614 | user wants the computer to connect to. </para> | |
615 | </listitem> | |
616 | </varlistentry> | |
617 | <varlistentry> | |
618 | <term><command>wpa_supplicant</command></term> | |
619 | <listitem><para>the program that directly interacts with the | |
620 | network interface. </para></listitem> | |
621 | </varlistentry> | |
622 | <varlistentry> | |
623 | <term><command>wpa_cli</command></term> <listitem><para> the | |
624 | client program that provides a high-level interface to the | |
625 | functionality of the daemon. </para></listitem> | |
626 | </varlistentry> | |
627 | <varlistentry> | |
628 | <term><command>wpa_passphrase</command></term> | |
629 | <listitem><para>a utility needed to construct | |
630 | <filename>wpa_supplicant.conf</filename> files that include | |
631 | encrypted passwords.</para></listitem> | |
632 | </varlistentry> | |
633 | </variablelist> | |
634 | </refsect1> | |
635 | ||
636 | <refsect1> | |
637 | <title>Quick Start</title> | |
638 | ||
639 | <para>First, make a configuration file, e.g. | |
640 | <filename>/etc/wpa_supplicant.conf</filename>, that describes the networks | |
641 | you are interested in. See <citerefentry> | |
642 | <refentrytitle>wpa_supplicant.conf</refentrytitle> | |
643 | <manvolnum>5</manvolnum> | |
644 | </citerefentry> | |
645 | for details.</para> | |
646 | ||
647 | <para>Once the configuration is ready, you can test whether the | |
648 | configuration works by running <command>wpa_supplicant</command> | |
649 | with following command to start it on foreground with debugging | |
650 | enabled:</para> | |
651 | ||
652 | <blockquote><programlisting> | |
653 | wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -d | |
654 | </programlisting></blockquote> | |
655 | ||
656 | <para>Assuming everything goes fine, you can start using following | |
657 | command to start <command>wpa_supplicant</command> on background | |
658 | without debugging:</para> | |
659 | ||
660 | <blockquote><programlisting> | |
661 | wpa_supplicant -iwlan0 -c/etc/wpa_supplicant.conf -B | |
662 | </programlisting></blockquote> | |
663 | ||
664 | <para>Please note that if you included more than one driver | |
665 | interface in the build time configuration (.config), you may need | |
666 | to specify which interface to use by including -D<driver | |
667 | name> option on the command line.</para> | |
668 | ||
669 | <!-- XXX at this point, the page could include a little script | |
670 | based on wpa_cli to wait for a connection and then run | |
671 | dhclient --> | |
672 | ||
673 | </refsect1> | |
674 | ||
675 | <refsect1> | |
676 | <title>Interface to pcmcia-cs/cardmrg</title> | |
677 | ||
678 | <para>For example, following small changes to pcmcia-cs scripts | |
679 | can be used to enable WPA support:</para> | |
680 | ||
681 | <para>Add MODE="Managed" and WPA="y" to the network scheme in | |
682 | <filename>/etc/pcmcia/wireless.opts</filename>.</para> | |
683 | ||
eff06a7c KM |
684 | <para>Add the following block to the end of <emphasis>start</emphasis> |
685 | action handler in <filename>/etc/pcmcia/wireless</filename>:</para> | |
6fc6879b JM |
686 | |
687 | <blockquote><programlisting> | |
688 | if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then | |
689 | /usr/local/bin/wpa_supplicant -B -c/etc/wpa_supplicant.conf -i$DEVICE | |
690 | fi | |
691 | </programlisting></blockquote> | |
692 | ||
693 | ||
eff06a7c KM |
694 | <para>Add the following block to the end of <emphasis>stop</emphasis> |
695 | action handler (may need to be separated from other actions) in | |
6fc6879b JM |
696 | <filename>/etc/pcmcia/wireless</filename>:</para> |
697 | ||
698 | <blockquote><programlisting> | |
699 | if [ "$WPA" = "y" -a -x /usr/local/bin/wpa_supplicant ]; then | |
700 | killall wpa_supplicant | |
701 | fi | |
702 | </programlisting></blockquote> | |
703 | ||
704 | <para>This will make <command>cardmgr</command> start | |
705 | <command>wpa_supplicant</command> when the card is plugged | |
706 | in.</para> | |
707 | </refsect1> | |
708 | ||
709 | <refsect1> | |
710 | <title>See Also</title> | |
711 | <para> | |
712 | <citerefentry> | |
713 | <refentrytitle>wpa_background</refentrytitle> | |
714 | <manvolnum>8</manvolnum> | |
715 | </citerefentry> | |
716 | <citerefentry> | |
717 | <refentrytitle>wpa_supplicant.conf</refentrytitle> | |
718 | <manvolnum>5</manvolnum> | |
719 | </citerefentry> | |
720 | <citerefentry> | |
721 | <refentrytitle>wpa_cli</refentrytitle> | |
722 | <manvolnum>8</manvolnum> | |
723 | </citerefentry> | |
724 | <citerefentry> | |
725 | <refentrytitle>wpa_passphrase</refentrytitle> | |
726 | <manvolnum>8</manvolnum> | |
727 | </citerefentry> | |
728 | </para> | |
729 | </refsect1> | |
730 | <refsect1> | |
731 | <title>Legal</title> | |
6774c6a9 | 732 | <para>wpa_supplicant is copyright (c) 2003-2017, |
6fc6879b JM |
733 | Jouni Malinen <email>j@w1.fi</email> and |
734 | contributors. | |
735 | All Rights Reserved.</para> | |
736 | ||
d755e01b JM |
737 | <para>This program is licensed under the BSD license (the one with |
738 | advertisement clause removed).</para> | |
6fc6879b JM |
739 | </refsect1> |
740 | </refentry> |