source: networking/netprogs/wpa_supplicant.xml@ 0e16b36

trunk
Last change on this file since 0e16b36 was 0e16b36, checked in by Bruce Dubbs <bdubbs@…>, 3 weeks ago

Archive qt5.

There are a large number of packages that needed to be changed to
remove qt5, but most are harmless. One package that is affected
is vlc where the gui interface is no longer available. Videos
can still be played from the command line and the kf6 dependency
on vlc is still satisfied.

If necessary qt5 can be restored for vlc.

Also three other files are archived that are no longer needed.
  • Property mode set to 100644
File size: 20.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY wpa_supplicant-download-http
8 "https://w1.fi/releases/wpa_supplicant-&wpa_supplicant-version;.tar.gz">
9 <!ENTITY wpa_supplicant-download-ftp " ">
10 <!ENTITY wpa_supplicant-md5sum "72a4a00eddb7a499a58113c3361ab094">
11 <!ENTITY wpa_supplicant-size "3.7 MB">
12 <!ENTITY wpa_supplicant-buildsize "35 MB">
13 <!ENTITY wpa_supplicant-time "0.3 SBU (without optional gui)">
14]>
15
16<sect1 id="wpa_supplicant" xreflabel="wpa_supplicant-&wpa_supplicant-version;">
17 <?dbhtml filename="wpa_supplicant.html"?>
18
19
20 <title>wpa_supplicant-&wpa_supplicant-version;</title>
21
22 <indexterm zone="wpa_supplicant">
23 <primary sortas="a-wpa_supplicant">wpa_supplicant</primary>
24 </indexterm>
25
26 <sect2 role="package">
27 <title>Introduction to WPA Supplicant</title>
28
29 <para>
30 <application>WPA Supplicant</application> is a Wi-Fi Protected Access
31 (WPA) client and IEEE 802.1X supplicant. It implements WPA key negotiation
32 with a WPA Authenticator and Extensible Authentication Protocol (EAP)
33 authentication with an Authentication Server. In addition, it controls the
34 roaming and IEEE 802.11 authentication/association of the wireless LAN
35 driver. This is useful for connecting to a password protected wireless
36 access point.
37 </para>
38
39 &lfs122_checked;
40
41 <bridgehead renderas="sect3">Package Information</bridgehead>
42 <itemizedlist spacing="compact">
43 <listitem>
44 <para>
45 Download (HTTP): <ulink url="&wpa_supplicant-download-http;"/>
46 </para>
47 </listitem>
48 <listitem>
49 <para>
50 Download (FTP): <ulink url="&wpa_supplicant-download-ftp;"/>
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 Download MD5 sum: &wpa_supplicant-md5sum;
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 Download size: &wpa_supplicant-size;
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Estimated disk space required: &wpa_supplicant-buildsize;
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Estimated build time: &wpa_supplicant-time;
71 </para>
72 </listitem>
73 </itemizedlist>
74<!--
75 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
76 <itemizedlist spacing="compact">
77 <listitem>
78 <para>
79 Required patch:
80 <ulink url="&patch-root;/wpa_supplicant-&wpa_supplicant-version;-security_fix-1.patch"/>
81 </para>
82 </listitem>
83 </itemizedlist>
84-->
85 <bridgehead renderas="sect3">WPA Supplicant Dependencies</bridgehead>
86
87 <bridgehead renderas="sect4">Required (Runtime)</bridgehead>
88 <para role="nodump">
89 <xref linkend="wireless-kernel"/>
90 </para>
91
92 <bridgehead renderas="sect4">Recommended</bridgehead>
93 <para role="recommended">
94 <xref linkend="desktop-file-utils"/> (for running
95 <command>update-desktop-database</command>) and
96 <xref linkend="libnl"/>
97 </para>
98
99 <bridgehead renderas="sect4">Optional</bridgehead>
100 <para role="optional">
101 <phrase revision="sysv"><xref linkend="dbus"/> and</phrase>
102 <xref linkend="libxml2"/>
103 </para>
104
105
106 </sect2>
107
108 <sect2 role="kernel" id="wpa_supplicant-kernel">
109 <title>Kernel Configuration</title>
110
111 <para>
112 To use <application>wpa_supplicant</application>, the kernel must have
113 the appropriate drivers and other support available. Read
114 <xref linkend='wireless-kernel'/> for details.
115 </para>
116
117 <indexterm zone="wpa_supplicant wpa_supplicant-kernel">
118 <primary sortas="d-wpa_supplicant">wpa_supplicant</primary>
119 </indexterm>
120 </sect2>
121
122 <sect2 role="installation">
123 <title>Installation of WPA Supplicant</title>
124
125 <para>
126 First you will need to create an initial configuration file for the
127 build process. You can read <filename>wpa_supplicant/README</filename>
128 and <filename>wpa_supplicant/defconfig</filename> for the explanation
129 of the following options as well as other options that can be used.
130 Create a build configuration file that should work for standard WiFi
131 setups by running the following command:
132 </para>
133
134<screen><userinput>cat &gt; wpa_supplicant/.config &lt;&lt; "EOF"
135<literal>CONFIG_BACKEND=file
136CONFIG_CTRL_IFACE=y
137CONFIG_DEBUG_FILE=y
138CONFIG_DEBUG_SYSLOG=y
139CONFIG_DEBUG_SYSLOG_FACILITY=LOG_DAEMON
140CONFIG_DRIVER_NL80211=y
141CONFIG_DRIVER_WEXT=y
142CONFIG_DRIVER_WIRED=y
143CONFIG_EAP_GTC=y
144CONFIG_EAP_LEAP=y
145CONFIG_EAP_MD5=y
146CONFIG_EAP_MSCHAPV2=y
147CONFIG_EAP_OTP=y
148CONFIG_EAP_PEAP=y
149CONFIG_EAP_TLS=y
150CONFIG_EAP_TTLS=y
151CONFIG_IEEE8021X_EAPOL=y
152CONFIG_IPV6=y
153CONFIG_LIBNL32=y
154CONFIG_PEERKEY=y
155CONFIG_PKCS12=y
156CONFIG_READLINE=y
157CONFIG_SMARTCARD=y
158CONFIG_WPS=y
159CFLAGS += -I/usr/include/libnl3</literal>
160EOF</userinput></screen>
161
162 <para>
163 If you wish to use <application>WPA Supplicant</application> with
164 <xref linkend="NetworkManager"/>, make sure that you have installed
165 <xref linkend="dbus"/> and <xref linkend="libxml2"/>, then add the
166 following options to the <application>WPA Supplicant</application>
167 build configuration file by running the following command:
168 </para>
169
170<screen><userinput>cat &gt;&gt; wpa_supplicant/.config &lt;&lt; "EOF"
171<literal>CONFIG_CTRL_IFACE_DBUS=y
172CONFIG_CTRL_IFACE_DBUS_NEW=y
173CONFIG_CTRL_IFACE_DBUS_INTRO=y</literal>
174EOF</userinput></screen>
175
176<!-- Fixed in version 2.11
177 <para>
178 Next, patch a security vulnerability that occurs when connecting to some
179 networks:
180 <!- - CVE-2023-52160, see Ticket #19304. - ->
181 </para>
182
183<screen><userinput>patch -Np1 -i ../wpa_supplicant-&wpa_supplicant-version;-security_fix-1.patch</userinput></screen>
184-->
185 <para>
186 Install <application>WPA Supplicant</application> by running the
187 following commands:
188 </para>
189
190<screen><userinput>cd wpa_supplicant &amp;&amp;
191make BINDIR=/usr/sbin LIBDIR=/usr/lib</userinput></screen>
192
193 <para>
194 This package does not come with a test suite.
195 </para>
196
197 <para>
198 Now, as the <systemitem class="username">root</systemitem> user:
199 </para>
200
201<screen role="root"><userinput>install -v -m755 wpa_{cli,passphrase,supplicant} /usr/sbin/ &amp;&amp;
202install -v -m644 doc/docbook/wpa_supplicant.conf.5 /usr/share/man/man5/ &amp;&amp;
203install -v -m644 doc/docbook/wpa_{cli,passphrase,supplicant}.8 /usr/share/man/man8/</userinput></screen>
204
205 <para revision="systemd">
206 Install the <application>systemd</application> support files by
207 running the following command as the <systemitem
208 class="username">root</systemitem> user:
209 </para>
210
211<screen role="root" revision="systemd"><userinput>install -v -m644 systemd/*.service /usr/lib/systemd/system/</userinput></screen>
212
213 <para>
214 If you have built <application>WPA Supplicant</application> with
215 <application>D-Bus</application> support, you will need to install
216 <application>D-Bus</application> configuration files. Install them
217 by running the following commands as the
218 <systemitem class="username">root</systemitem> user:
219 </para>
220
221<screen role="root"><userinput>install -v -m644 dbus/fi.w1.wpa_supplicant1.service \
222 /usr/share/dbus-1/system-services/ &amp;&amp;
223install -v -d -m755 /etc/dbus-1/system.d &amp;&amp;
224install -v -m644 dbus/dbus-wpa_supplicant.conf \
225 /etc/dbus-1/system.d/wpa_supplicant.conf</userinput></screen>
226
227 <para>
228 If you have built the <application>WPA Supplicant</application> GUI
229 program, install it by running the following commands as the
230 <systemitem class="username">root</systemitem> user:
231 </para>
232
233<screen role="root"><userinput>install -v -m755 wpa_gui-qt4/wpa_gui /usr/bin/ &amp;&amp;
234install -v -m644 doc/docbook/wpa_gui.8 /usr/share/man/man8/ &amp;&amp;
235install -v -m644 wpa_gui-qt4/wpa_gui.desktop /usr/share/applications/ &amp;&amp;
236install -v -m644 wpa_gui-qt4/icons/wpa_gui.svg /usr/share/pixmaps/</userinput></screen>
237
238 <note>
239 <para>
240 You will need to restart the system <application>D-Bus</application> daemon
241 before you can use the <application>WPA Supplicant</application>
242 <application>D-Bus</application> interface.
243 </para>
244 </note>
245
246 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
247 href="../../xincludes/update-desktop-database.xml"/>
248
249 </sect2>
250
251 <sect2 role="configuration">
252 <title>Configuring wpa_supplicant</title>
253
254 <important>
255 <para>
256 If you are using WPA Supplicant with
257 <xref linkend='NetworkManager'/> (or anything communicating with
258 WPA Supplicant via D-Bus), this section should be skipped. Running
259 a D-Bus connected WPA Supplicant instance and another WPA supplicant
260 instance configured following this section simultaneously can cause
261 subtle issues.
262 </para>
263 </important>
264
265 <sect3 id="wpa_supplicant-config">
266 <title>Config File</title>
267
268 <para revision="sysv">
269 <filename>/etc/sysconfig/wpa_supplicant-*.conf</filename>
270 </para>
271
272 <para revision="systemd">
273 <filename>/etc/wpa_supplicant/wpa_supplicant-*.conf</filename>
274 </para>
275
276 <indexterm zone="wpa_supplicant wpa_supplicant-config" revision="sysv">
277 <primary
278 sortas="e-etc-sysconfig-wpa_supplicant-star.conf">/etc/sysconfig/wpa_supplicant-*.conf</primary>
279 </indexterm>
280
281 <indexterm zone="wpa_supplicant wpa_supplicant-config" revision="systemd">
282 <primary
283 sortas="e-etc-wpa_supplicant-wpa_supplicant-star.conf">/etc/wpa_supplicant/wpa_supplicant-*.conf</primary>
284 </indexterm>
285
286 </sect3>
287
288 <sect3>
289 <title>Configuration Information</title>
290
291 <para>
292 To connect to an access point that uses a password, you need to put
293 the pre-shared key in
294 <phrase revision="sysv">
295 <filename>
296 /etc/sysconfig/wpa_supplicant-<replaceable>wifi0</replaceable>.conf</filename>.
297 </phrase>
298 <phrase revision="systemd">
299 <filename>
300 /etc/wpa_supplicant/wpa_supplicant-<replaceable>wifi0</replaceable>.conf</filename>.
301 </phrase>
302 SSID is the string that the access point/router transmits to
303 identify itself. Run the following command as the
304 <systemitem class="username">root</systemitem> user:
305 </para>
306
307<screen role="nodump" revision="sysv"><userinput>wpa_passphrase <replaceable>SSID</replaceable> <replaceable>SECRET_PASSWORD</replaceable> &gt; /etc/sysconfig/wpa_supplicant-<replaceable>wifi0</replaceable>.conf</userinput></screen>
308
309<screen role="nodump" revision="systemd"><userinput>install -v -dm755 /etc/wpa_supplicant &amp;&amp;
310wpa_passphrase <replaceable>SSID</replaceable> <replaceable>SECRET_PASSWORD</replaceable> &gt; /etc/wpa_supplicant/wpa_supplicant-<replaceable>wifi0</replaceable>.conf</userinput></screen>
311
312 <para>
313 <phrase revision="sysv">
314 <filename>
315 /etc/sysconfig/wpa_supplicant-<replaceable>wifi0</replaceable>.conf
316 </filename>
317 </phrase>
318 <phrase revision="systemd">
319 <filename>
320 /etc/wpa_supplicant/wpa_supplicant-<replaceable>wifi0</replaceable>.conf
321 </filename>
322 </phrase>
323 can hold the details of several access points. When
324 <command>wpa_supplicant</command> is started, it will scan for the
325 SSIDs it can see and choose the appropriate password to connect.
326 </para>
327
328 <para>
329 If you want to connect to an access point that isn't password
330 protected, put an entry like this in
331 <phrase revision="sysv">
332 <filename>
333/etc/sysconfig/wpa_supplicant-<replaceable>wifi0</replaceable>.conf</filename>.
334 </phrase>
335 <phrase revision="systemd">
336 <filename>
337/etc/wpa_supplicant/wpa_supplicant-<replaceable>wifi0</replaceable>.conf</filename>.
338 </phrase>
339 Replace "Some-SSID" with the SSID of the access point/router.
340 </para>
341
342<screen>network={
343 ssid="<replaceable>Some-SSID</replaceable>"
344 key_mgmt=NONE
345}</screen>
346
347 <para>
348 Connecting to a new access point that is not in the configuration
349 file can be accomplished manually via the command line or GUI, but it
350 must be done via a privileged user. To do that, add the following to
351 the configuration file:
352 </para>
353
354<screen>ctrl_interface=DIR=/run/wpa_supplicant GROUP=&lt;privileged group&gt;
355update_config=1</screen>
356
357 <para>
358 Replace the &lt;privileged group&gt; above with a system group where
359 members have the ability to connect to a wireless access point.
360 </para>
361
362 <para>
363 There are many options that you could use to tweak how you connect
364 to each access point. They are described in some detail in the
365 <filename>wpa_supplicant/wpa_supplicant.conf</filename> file in the
366 source tree.
367 </para>
368
369 </sect3>
370
371 <sect3>
372 <title>Connecting to an Access Point</title>
373
374 <para id="wpa-service" revision="sysv">
375 If you want to configure network interfaces at boot using
376 <command>wpa_supplicant</command>, you need to install the
377 <filename>/lib/services/wpa</filename> script
378 included in <xref linkend="bootscripts"/> package:
379 </para>
380
381<screen role="root" revision="sysv"><userinput>make install-service-wpa</userinput></screen>
382
383 <indexterm zone="wpa_supplicant wpa-service" revision="sysv">
384 <primary sortas="f-wpa">wpa</primary>
385 </indexterm>
386
387 <para revision="sysv">
388 If your router/access point uses DHCP to allocate IP addresses, you
389 can install <xref linkend="dhcpcd" role="nodep"/> and use it to
390 automatically obtain network addresses. Create the
391 <filename>/etc/sysconfig/ifconfig-<replaceable>wifi0</replaceable>
392 </filename> by running the following command as the
393 <systemitem class="username">root</systemitem> user:
394 </para>
395
396<screen role="root" revision="sysv"><userinput>cat &gt; /etc/sysconfig/ifconfig.<replaceable>wifi0</replaceable> &lt;&lt; "EOF"
397<literal>ONBOOT="yes"
398IFACE="<replaceable>wlan0</replaceable>"
399SERVICE="wpa"
400
401# Additional arguments to wpa_supplicant
402WPA_ARGS=""
403
404WPA_SERVICE="dhcpcd"
405DHCP_START="-b -q <replaceable>&lt;insert appropriate start options here&gt;</replaceable>"
406DHCP_STOP="-k <replaceable>&lt;insert additional stop options here&gt;</replaceable>"</literal>
407EOF</userinput></screen>
408
409 <para revision="sysv">
410 Alternatively, if you use static addresses on your local network,
411 then create the
412 <filename>/etc/sysconfig/ifconfig-<replaceable>wifi0</replaceable>
413 </filename> by running the following command as the
414 <systemitem class="username">root</systemitem> user:
415 </para>
416
417<screen role="root" revision="sysv"><userinput>cat &gt; /etc/sysconfig/ifconfig.<replaceable>wifi0</replaceable> &lt;&lt; "EOF"
418<literal>ONBOOT="yes"
419IFACE="<replaceable>wlan0</replaceable>"
420SERVICE="wpa"
421
422# Additional arguments to wpa_supplicant
423WPA_ARGS=""
424
425WPA_SERVICE="ipv4-static"
426IP="192.168.1.1"
427GATEWAY="192.168.1.2"
428PREFIX="24"
429BROADCAST="192.168.1.255"</literal>
430EOF</userinput></screen>
431
432 <para revision="systemd">
433 There are 3 types of <application>systemd</application> units
434 that were installed:
435 </para>
436
437 <itemizedlist spacing="compact" revision="systemd">
438 <listitem>
439 <para>
440 wpa_supplicant@.service
441 </para>
442 </listitem>
443 <listitem>
444 <para>
445 wpa_supplicant-nl80211@.service
446 </para>
447 </listitem>
448 <listitem>
449 <para>
450 wpa_supplicant-wired@.service
451 </para>
452 </listitem>
453 </itemizedlist>
454
455 <para revision="systemd">
456 The only difference between 3 of them is what driver
457 is used for connecting (-D option). The first one uses
458 the default driver, the second one uses the nl80211
459 driver and the third one uses the wired driver.
460 </para>
461
462 <para>
463 You can connect to the wireless access point by
464 running the following command as the
465 <systemitem class="username">root</systemitem> user:
466 </para>
467
468<screen role="root" revision="sysv"><userinput>ifup <replaceable>wifi0</replaceable></userinput></screen>
469
470 <para revision="sysv">
471 Replace <replaceable>wlan0</replaceable> with the correct
472 wireless interface and <replaceable>wifi0</replaceable>
473 with desired name for the configuration file. Please note
474 that <filename>wpa_supplicant-*.conf</filename> and
475 <filename>ifconfig.*</filename> configuration files need
476 to have identical names, ie both contain
477 <replaceable>wifi0</replaceable> in their name.
478 </para>
479
480<screen role="root" revision="systemd"><userinput>systemctl start wpa_supplicant@<replaceable>wlan0</replaceable></userinput></screen>
481
482 <para revision="systemd">
483 To connect to the wireless access point at
484 boot, simply enable the appropriate
485 <command>wpa_supplicant</command> service
486 by running the following command as the
487 <systemitem class="username">root</systemitem> user:
488 </para>
489
490<screen role="root" revision="systemd"><userinput>systemctl enable wpa_supplicant@<replaceable>wlan0</replaceable></userinput></screen>
491
492 <para revision="systemd">
493 Depending on your setup, you can replace the
494 <filename>wpa_supplicant@.service</filename>
495 with any other listed above.
496 </para>
497
498 <para revision="systemd">
499 To assign a network address to your wireless interface, consult the
500 <ulink url="&lfs-root;/chapter09/network.html">General Network Configuration</ulink>
501 page in LFS.
502 </para>
503
504 </sect3>
505
506 </sect2>
507
508 <sect2 role="content">
509 <title>Contents</title>
510
511 <segmentedlist>
512 <segtitle>Installed Programs</segtitle>
513 <segtitle>Installed Libraries</segtitle>
514 <segtitle>Installed Directories</segtitle>
515
516 <seglistitem>
517 <seg>
518 wpa_gui, wpa_supplicant, wpa_passphrase and wpa_cli
519 </seg>
520 <seg>
521 None
522 </seg>
523 <seg>
524 None
525 </seg>
526 </seglistitem>
527 </segmentedlist>
528
529 <variablelist>
530 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
531 <?dbfo list-presentation="list"?>
532 <?dbhtml list-presentation="table"?>
533
534 <varlistentry id="wpa_gui">
535 <term><command>wpa_gui</command></term>
536 <listitem>
537 <para>
538 is a graphical frontend program for interacting with
539 <application>wpa_supplicant</application>
540 </para>
541 <indexterm zone="wpa_supplicant wpa_gui">
542 <primary sortas="b-wpa_gui">wpa_gui</primary>
543 </indexterm>
544 </listitem>
545 </varlistentry>
546
547 <varlistentry id="wpa_supplicant-prog">
548 <term><command>wpa_supplicant</command></term>
549 <listitem>
550 <para>
551 is a daemon that can connect to a password protected wireless
552 access point
553 </para>
554 <indexterm zone="wpa_supplicant wpa_supplicant-prog">
555 <primary sortas="b-wpa_supplicant">wpa_supplicant</primary>
556 </indexterm>
557 </listitem>
558 </varlistentry>
559
560 <varlistentry id="wpa_passphrase">
561 <term><command>wpa_passphrase</command></term>
562 <listitem>
563 <para>
564 takes an SSID and a password and generates a simple
565 configuration that <command>wpa_supplicant</command> can
566 understand
567 </para>
568 <indexterm zone="wpa_supplicant wpa_passphrase">
569 <primary sortas="b-wpa_passphrase">wpa_passphrase</primary>
570 </indexterm>
571 </listitem>
572 </varlistentry>
573
574 <varlistentry id="wpa_cli">
575 <term><command>wpa_cli</command></term>
576 <listitem>
577 <para>
578 is a command line interface used to control a running
579 <command>wpa_supplicant</command> daemon
580 </para>
581 <indexterm zone="wpa_supplicant wpa_cli">
582 <primary sortas="b-wpa_cli">wpa_cli</primary>
583 </indexterm>
584 </listitem>
585 </varlistentry>
586
587 </variablelist>
588
589 </sect2>
590
591</sect1>
Note: See TracBrowser for help on using the repository browser.