/[gentoo]/xml/htdocs/doc/en/handbook/hb-net-wireless.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-net-wireless.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.20 - (show annotations) (download) (as text)
Sun Aug 14 16:12:13 2011 UTC (3 years, 3 months ago) by swift
Branch: MAIN
Changes since 1.19: +15 -15 lines
File MIME type: application/xml
Bug #213988 - Various fixes on OpenRC in handbook

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6
7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-wireless.xml,v 1.19 2010/11/07 20:16:49 nightmorph Exp $ -->
8
9 <sections>
10
11 <abstract>
12 Wireless configuration can be tricky. Hopefully we'll get you working!
13 </abstract>
14
15 <version>10</version>
16 <date>2011-08-13</date>
17
18 <section>
19 <title>Introduction</title>
20 <body>
21
22 <p>
23 Wireless networking on Linux is usually pretty straightforward. There are two
24 ways of configuring wifi: graphical clients, or the command line.
25 </p>
26
27 <p>
28 The <e>easiest</e> way is to use a graphical client once you've installed a <uri
29 link="/doc/en/?catid=desktop">desktop environment</uri>. Most graphical clients,
30 such as <uri link="http://wicd.sourceforge.net">wicd</uri> and <uri
31 link="http://www.gnome.org/projects/NetworkManager">NetworkManager</uri>, are
32 pretty self-explanatory. They offer a handy point-and-click interface that gets
33 you on a network in just a few seconds.
34 </p>
35
36 <note>
37 <c>wicd</c> offers a command line utility <e>in addition</e> to the main
38 graphical interface. You can get it by emerging <c>wicd</c> with the
39 <c>ncurses</c> USE flag set. This <c>wicd-curses</c> utility is particularly
40 useful for folks who don't use a gtk-based desktop environment, but still want
41 an easy command line tool that doesn't require hand-editing configuration
42 files.
43 </note>
44
45 <p>
46 However, if you don't want to use a graphical client, then you can configure
47 wifi on the command line by editing a few configuration files. This takes a bit
48 more time to setup, but it also requires the fewest packages to download and
49 install. Since the graphical clients are mostly self-explanatory (with helpful
50 screenshots at their homepages), we'll focus on the command line alternatives.
51 </p>
52
53 <p>
54 You can setup wireless networking on the command line by installing
55 <c>wireless-tools</c> or <c>wpa_supplicant</c>. The important thing to remember
56 is that you configure wireless networks on a global basis and not an interface
57 basis.
58 </p>
59
60 <p>
61 <c>wpa_supplicant</c> is the best choice. For a list of supported drivers, <uri
62 link="http://hostap.epitest.fi/wpa_supplicant">read the wpa_supplicant
63 site</uri>.
64 </p>
65
66 <p>
67 <c>wireless-tools</c> supports nearly all cards and drivers, but it cannot
68 connect to WPA-only Access Points. If your networks only offer WEP encryption or
69 are completely open, you may prefer the simplicity of <c>wireless-tools</c>.
70 </p>
71
72 <warn>
73 The <c>linux-wlan-ng</c> driver is not supported by baselayout at this time.
74 This is because <c>linux-wlan-ng</c> have its own setup and configuration which
75 is completely different to everyone else's. The <c>linux-wlan-ng</c> developers
76 are rumoured to be changing their setup over to <c>wireless-tools</c>, so when
77 this happens you may use <c>linux-wlan-ng</c> with baselayout.
78 </warn>
79
80 </body>
81 </section>
82 <section>
83 <title>WPA Supplicant</title>
84 <body>
85
86 <p>
87 <uri link="http://hostap.epitest.fi/wpa_supplicant">WPA Supplicant</uri> is a
88 package that allows you to connect to WPA enabled access points.
89 </p>
90
91 <pre caption="Install wpa_supplicant">
92 # <i>emerge net-wireless/wpa_supplicant</i>
93 </pre>
94
95 <impo>
96 You have to have <c>CONFIG_PACKET</c> enabled in your kernel for
97 <c>wpa_supplicant</c> to work. Try running <c>grep CONFIG_PACKET
98 /usr/src/linux/.config</c> to see if you have it enabled in your kernel.
99 </impo>
100
101 <note>
102 Depending on your USE flags, <c>wpa_supplicant</c> can install a graphical
103 interface written in Qt4, which will integrate nicely with KDE. To get it, run
104 <c>echo "net-wireless/wpa_supplicant qt4" >> /etc/portage/package.use</c> as
105 root before emerging <c>wpa_supplicant</c>.
106 </note>
107
108 <p>
109 Now we have to configure <path>/etc/conf.d/net</path> to so that we prefer
110 <c>wpa_supplicant</c> over <c>wireless-tools</c> (if both are installed,
111 <c>wireless-tools</c> is the default).
112 </p>
113
114 <pre caption="configure /etc/conf.d/net for wpa_supplicant">
115 <comment># Prefer wpa_supplicant over wireless-tools</comment>
116 modules="wpa_supplicant"
117
118 <comment># It's important that we tell wpa_supplicant which driver we should
119 # be using as it's not very good at guessing yet</comment>
120 wpa_supplicant_eth0="-Dmadwifi"
121 </pre>
122
123 <note>
124 If you're using the host-ap driver you will need to put the card in <e>Managed
125 mode</e> before it can be used with <c>wpa_supplicant</c> correctly. You can use
126 <c>iwconfig_eth0="mode managed"</c> to achieve this in
127 <path>/etc/conf.d/net</path>.
128 </note>
129
130 <p>
131 That was simple, wasn't it? However, we still have to configure
132 <c>wpa_supplicant</c> itself which is a bit more tricky depending on how secure
133 the Access Points are that you are trying to connect to. The below example is
134 taken and simplified from
135 <path>/usr/share/doc/wpa_supplicant-&lt;version&gt;/wpa_supplicant.conf.gz</path>
136 which ships with <c>wpa_supplicant</c>.
137 </p>
138
139 <pre caption="An example /etc/wpa_supplicant/wpa_supplicant.conf">
140 <comment># The below line not be changed otherwise we refuse to work</comment>
141 ctrl_interface=/var/run/wpa_supplicant
142
143 <comment># Ensure that only root can read the WPA configuration</comment>
144 ctrl_interface_group=0
145
146 <comment># Let wpa_supplicant take care of scanning and AP selection</comment>
147 ap_scan=1
148
149 <comment># Simple case: WPA-PSK, PSK as an ASCII passphrase, allow all valid ciphers</comment>
150 network={
151 ssid="simple"
152 psk="very secret passphrase"
153 <comment># The higher the priority the sooner we are matched</comment>
154 priority=5
155 }
156
157 <comment># Same as previous, but request SSID-specific scanning (for APs that reject
158 # broadcast SSID)</comment>
159 network={
160 ssid="second ssid"
161 scan_ssid=1
162 psk="very secret passphrase"
163 priority=2
164 }
165
166 <comment># Only WPA-PSK is used. Any valid cipher combination is accepted</comment>
167 network={
168 ssid="example"
169 proto=WPA
170 key_mgmt=WPA-PSK
171 pairwise=CCMP TKIP
172 group=CCMP TKIP WEP104 WEP40
173 psk=06b4be19da289f475aa46a33cb793029d4ab3db7a23ee92382eb0106c72ac7bb
174 priority=2
175 }
176
177 <comment># Plaintext connection (no WPA, no IEEE 802.1X)</comment>
178 network={
179 ssid="plaintext-test"
180 key_mgmt=NONE
181 }
182
183 <comment># Shared WEP key connection (no WPA, no IEEE 802.1X)</comment>
184 network={
185 ssid="static-wep-test"
186 key_mgmt=NONE
187 <comment># Keys in quotes are ASCII keys</comment>
188 wep_key0="abcde"
189 <comment># Keys specified without quotes are hex keys</comment>
190 wep_key1=0102030405
191 wep_key2="1234567890123"
192 wep_tx_keyidx=0
193 priority=5
194 }
195
196 <comment># Shared WEP key connection (no WPA, no IEEE 802.1X) using Shared Key
197 # IEEE 802.11 authentication</comment>
198 network={
199 ssid="static-wep-test2"
200 key_mgmt=NONE
201 wep_key0="abcde"
202 wep_key1=0102030405
203 wep_key2="1234567890123"
204 wep_tx_keyidx=0
205 priority=5
206 auth_alg=SHARED
207 }
208
209 <comment># IBSS/ad-hoc network with WPA-None/TKIP</comment>
210 network={
211 ssid="test adhoc"
212 mode=1
213 proto=WPA
214 key_mgmt=WPA-NONE
215 pairwise=NONE
216 group=TKIP
217 psk="secret passphrase"
218 }
219 </pre>
220
221 </body>
222 </section>
223 <section>
224 <title>Wireless Tools</title>
225
226 <subsection>
227 <title>Initial setup and Managed Mode</title>
228 <body>
229
230 <p>
231 <uri
232 link="http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html">Wireless
233 Tools</uri> provide a generic way to configure basic wireless interfaces up to
234 the WEP security level. While WEP is a weak security method it's also the most
235 prevalent.
236 </p>
237
238 <p>
239 Wireless Tools configuration is controlled by a few main variables. The sample
240 configuration file below should describe all you need. One thing to bear in mind
241 is that no configuration means "connect to the strongest unencrypted Access
242 Point" - we will always try and connect you to something.
243 </p>
244
245 <pre caption="Install wireless-tools">
246 # <i>emerge net-wireless/wireless-tools</i>
247 </pre>
248
249 <note>
250 Although you can store your wireless settings in
251 <path>/etc/conf.d/wireless</path> this guide recommends you store them in
252 <path>/etc/conf.d/net</path>.
253 </note>
254
255 <impo>
256 You <e>will</e> need to consult the <uri
257 link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
258 </impo>
259
260 <pre caption="sample iwconfig setup in /etc/conf.d/net">
261 <comment># Prefer iwconfig over wpa_supplicant</comment>
262 modules="iwconfig"
263
264 <comment># Configure WEP keys for Access Points called ESSID1 and ESSID2</comment>
265 <comment># You may configure up to 4 WEP keys, but only 1 can be active at
266 # any time so we supply a default index of [1] to set key [1] and then
267 # again afterwards to change the active key to [1]
268 # We do this incase you define other ESSID's to use WEP keys other than 1
269 #
270 # Prefixing the key with s: means it's an ASCII key, otherwise a HEX key
271 #
272 # enc open specified open security (most secure)
273 # enc restricted specified restricted security (least secure)</comment>
274 key_ESSID1="[1] s:yourkeyhere key [1] enc open"
275 key_ESSID2="[1] aaaa-bbbb-cccc-dd key [1] enc restricted"
276
277 <comment># The below only work when we scan for available Access Points</comment>
278
279 <comment># Sometimes more than one Access Point is visible so we need to
280 # define a preferred order to connect in</comment>
281 preferred_aps="'ESSID1' 'ESSID2'"
282 </pre>
283
284 </body>
285 </subsection>
286 <subsection>
287 <title>Fine tune Access Point Selection</title>
288 <body>
289
290 <p>
291 You can add some extra options to fine-tune your Access Point selection, but
292 these are not normally required.
293 </p>
294
295 <p>
296 You can decide whether we only connect to preferred Access Points or not. By
297 default if everything configured has failed and we can connect to an unencrypted
298 Access Point then we will. This can be controlled by the <c>associate_order</c>
299 variable. Here's a table of values and how they control this.
300 </p>
301
302 <table>
303 <tr>
304 <th>Value</th>
305 <th>Description</th>
306 </tr>
307 <tr>
308 <ti><c>any</c></ti>
309 <ti>Default behaviour</ti>
310 </tr>
311 <tr>
312 <ti><c>preferredonly</c></ti>
313 <ti>We will only connect to visible APs in the preferred list</ti>
314 </tr>
315 <tr>
316 <ti><c>forcepreferred</c></ti>
317 <ti>
318 We will forceably connect to APs in the preferred order if they are not
319 found in a scan
320 </ti>
321 </tr>
322 <tr>
323 <ti><c>forcepreferredonly</c></ti>
324 <ti>
325 Do not scan for APs - instead just try to connect to each one in order
326 </ti>
327 </tr>
328 <tr>
329 <ti><c>forceany</c></ti>
330 <ti>Same as <c>forcepreferred</c> + connect to any other available AP</ti>
331 </tr>
332 </table>
333
334 <p>
335 Finally we have some <c>blacklist_aps</c> and <c>unique_ap</c> selection.
336 <c>blacklist_aps</c> works in a similar way to <c>preferred_aps</c>.
337 <c>unique_ap</c> is a <c>yes</c> or <c>no</c> value that says if a second
338 wireless interface can connect to the same Access Point as the first interface.
339 </p>
340
341 <pre caption="blacklist_aps and unique_ap example">
342 <comment># Sometimes you never want to connect to certain access points</comment>
343 blacklist_aps="'ESSID3' 'ESSID4'"
344
345 <comment># If you have more than one wireless card, you can say if you want
346 # to allow each card to associate with the same Access Point or not
347 # Values are "yes" and "no"
348 # Default is "yes"</comment>
349 unique_ap="yes"
350 </pre>
351
352 </body>
353 </subsection>
354 <subsection>
355 <title>Ad-Hoc and Master Modes</title>
356 <body>
357
358 <p>
359 If you want to set yourself up as an Ad-Hoc node if you fail to connect to any
360 Access Point in managed mode, you can do that too.
361 </p>
362
363 <pre caption="fallback to ad-hoc mode">
364 adhoc_essid_eth0="This Adhoc Node"
365 </pre>
366
367 <p>
368 What about connecting to Ad-Hoc networks or running in Master mode to become an
369 Access Point? Here's a configuration just for that! You may need to specify WEP
370 keys as shown above.
371 </p>
372
373 <pre caption="sample ad-hoc/master configuration">
374 <comment># Set the mode - can be managed (default), ad-hoc or master
375 # Not all drivers support all modes</comment>
376 mode_eth0="ad-hoc"
377
378 <comment># Set the ESSID of the interface
379 # In managed mode, this forces the interface to try and connect to the
380 # specified ESSID and nothing else</comment>
381 essid_eth0="This Adhoc Node"
382
383 <comment># We use channel 3 if you don't specify one</comment>
384 channel_eth0="9"
385 </pre>
386
387 <impo>
388 The below is taken verbatim from the BSD wavelan documentation found at <uri
389 link="http://www.netbsd.org/Documentation/network/wavelan.html">the NetBSD
390 documentation</uri>. There are 14 channels possible; We are told that channels
391 1-11 are legal for North America, channels 1-13 for most of Europe, channels
392 10-13 for France, and only channel 14 for Japan. If in doubt, please refer to
393 the documentation that came with your card or access point. Make sure that the
394 channel you select is the same channel your access point (or the other card in
395 an ad-hoc network) is on. The default for cards sold in North America and most
396 of Europe is 3; the default for cards sold in France is 11, and the default for
397 cards sold in Japan is 14.
398 </impo>
399
400 </body>
401 </subsection>
402 <subsection>
403 <title>Troubleshooting Wireless Tools</title>
404 <body>
405
406 <p>
407 There are some more variables you can use to help get your wireless up and
408 running due to driver or environment problems. Here's a table of other things
409 you can try.
410 </p>
411
412 <table>
413 <tr>
414 <th>Variable</th>
415 <th>Default Value</th>
416 <th>Description</th>
417 </tr>
418 <tr>
419 <ti><c>iwconfig_eth0</c></ti>
420 <ti/>
421 <ti>See the iwconfig man page for details on what to send <c>iwconfig</c></ti>
422 </tr>
423 <tr>
424 <ti><c>iwpriv_eth0</c></ti>
425 <ti/>
426 <ti>See the iwpriv man page for details on what to send <c>iwpriv</c></ti>
427 </tr>
428 <tr>
429 <ti><c>sleep_scan_eth0</c></ti>
430 <ti><c>0</c></ti>
431 <ti>
432 The number of seconds to sleep before attempting to scan. This is needed
433 when the driver/firmware needs more time to active before it can be used.
434 </ti>
435 </tr>
436 <tr>
437 <ti><c>sleep_associate_eth0</c></ti>
438 <ti><c>5</c></ti>
439 <ti>
440 The number of seconds to wait for the interface to associate with the
441 Access Point before moving onto the next one
442 </ti>
443 </tr>
444 <tr>
445 <ti><c>associate_test_eth0</c></ti>
446 <ti><c>MAC</c></ti>
447 <ti>
448 Some drivers do not reset the MAC address associated with an invalid one
449 when they lose or attempt association. Some drivers do not reset the
450 quality level when they lose or attempt association. Valid settings are
451 <c>MAC</c>, <c>quality</c> and <c>all</c>.
452 </ti>
453 </tr>
454 <tr>
455 <ti><c>scan_mode_eth0</c></ti>
456 <ti/>
457 <ti>
458 Some drivers have to scan in ad-hoc mode, so if scanning fails
459 try setting <c>ad-hoc</c> here
460 </ti>
461 </tr>
462 <tr>
463 <ti><c>iwpriv_scan_pre_eth0</c></ti>
464 <ti/>
465 <ti>
466 Sends some <c>iwpriv</c> commands to the interface before scanning.
467 See the iwpriv man page for more details.
468 </ti>
469 </tr>
470 <tr>
471 <ti><c>iwpriv_scan_post_eth0</c></ti>
472 <ti/>
473 <ti>
474 Sends some <c>iwpriv</c> commands to the interface after scanning.
475 See the iwpriv man page for more details.
476 </ti>
477 </tr>
478 </table>
479
480 </body>
481 </subsection>
482 </section>
483 <section>
484 <title>Defining network configuration per ESSID</title>
485 <body>
486
487 <p>
488 Sometimes, you need a static IP when you connect to <e>ESSID1</e> and you need
489 DHCP when you connect to <e>ESSID2</e>. In fact, most module variables can be
490 defined per ESSID. Here's how we do this.
491 </p>
492
493 <note>
494 These work if you're using WPA Supplicant or Wireless Tools.
495 </note>
496
497 <impo>
498 You <e>will</e> need to consult the <uri
499 link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
500 </impo>
501
502 <pre caption="override network settings per ESSID">
503 config_ESSID1="192.168.0.3/24 brd 192.168.0.255"
504 routes_ESSID1="default via 192.168.0.1"
505
506 config_ESSID2="dhcp"
507 fallback_ESSID2="192.168.3.4/24"
508 fallback_route_ESSID2="default via 192.168.3.1"
509
510 <comment># We can define nameservers and other things too</comment>
511 <comment># NOTE: DHCP will override these unless it's told not too</comment>
512 dns_servers_ESSID1="192.168.0.1 192.168.0.2"
513 dns_domain_ESSID1="some.domain"
514 dns_search_domains_ESSID1="search.this.domain search.that.domain"
515
516 <comment># You override by the MAC address of the Access Point
517 # This handy if you goto different locations that have the same ESSID</comment>
518 config_001122334455="dhcp"
519 dhcpcd_001122334455="-t 10"
520 dns_servers_001122334455="192.168.0.1 192.168.0.2"
521 </pre>
522
523 </body>
524 </section>
525 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20