/[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 - (hide annotations) (download) (as text)
Sun Aug 14 16:12:13 2011 UTC (2 years, 8 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 swift 1.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 neysx 1.4 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6    
7 swift 1.20 <!-- $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 swift 1.1
9     <sections>
10    
11 neysx 1.13 <abstract>
12 nightmorph 1.17 Wireless configuration can be tricky. Hopefully we'll get you working!
13 neysx 1.13 </abstract>
14    
15 swift 1.20 <version>10</version>
16     <date>2011-08-13</date>
17 swift 1.1
18     <section>
19     <title>Introduction</title>
20     <body>
21    
22     <p>
23 nightmorph 1.17 Wireless networking on Linux is usually pretty straightforward. There are two
24     ways of configuring wifi: graphical clients, or the command line.
25 swift 1.1 </p>
26    
27     <p>
28 nightmorph 1.17 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 jkt 1.6 link="http://hostap.epitest.fi/wpa_supplicant">read the wpa_supplicant
63 nightmorph 1.17 site</uri>.
64 swift 1.1 </p>
65    
66     <p>
67 jkt 1.7 <c>wireless-tools</c> supports nearly all cards and drivers, but it cannot
68 nightmorph 1.17 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 swift 1.1 </p>
71    
72     <warn>
73 nightmorph 1.15 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 swift 1.1 </warn>
79    
80     </body>
81     </section>
82     <section>
83     <title>WPA Supplicant</title>
84     <body>
85 swift 1.2
86 swift 1.1 <p>
87 jkt 1.6 <uri link="http://hostap.epitest.fi/wpa_supplicant">WPA Supplicant</uri> is a
88 nightmorph 1.18 package that allows you to connect to WPA enabled access points.
89 swift 1.1 </p>
90    
91     <pre caption="Install wpa_supplicant">
92     # <i>emerge net-wireless/wpa_supplicant</i>
93     </pre>
94    
95     <impo>
96 jkt 1.7 You have to have <c>CONFIG_PACKET</c> enabled in your kernel for
97 nightmorph 1.19 <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 swift 1.1 </impo>
100    
101 nightmorph 1.17 <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 swift 1.1 <p>
109     Now we have to configure <path>/etc/conf.d/net</path> to so that we prefer
110 jkt 1.7 <c>wpa_supplicant</c> over <c>wireless-tools</c> (if both are installed,
111     <c>wireless-tools</c> is the default).
112 swift 1.1 </p>
113    
114     <pre caption="configure /etc/conf.d/net for wpa_supplicant">
115     <comment># Prefer wpa_supplicant over wireless-tools</comment>
116 swift 1.20 modules="wpa_supplicant"
117 swift 1.1
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 jkt 1.7 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 jkt 1.9 <c>iwconfig_eth0="mode managed"</c> to achieve this in
127 swift 1.3 <path>/etc/conf.d/net</path>.
128 swift 1.1 </note>
129    
130     <p>
131 jkt 1.10 That was simple, wasn't it? However, we still have to configure
132 jkt 1.7 <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 nightmorph 1.14 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 swift 1.1 </p>
138    
139 nightmorph 1.17 <pre caption="An example /etc/wpa_supplicant/wpa_supplicant.conf">
140 swift 1.1 <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 swift 1.2 ssid="simple"
152     psk="very secret passphrase"
153     <comment># The higher the priority the sooner we are matched</comment>
154     priority=5
155 swift 1.1 }
156    
157     <comment># Same as previous, but request SSID-specific scanning (for APs that reject
158     # broadcast SSID)</comment>
159     network={
160 swift 1.2 ssid="second ssid"
161     scan_ssid=1
162     psk="very secret passphrase"
163     priority=2
164 swift 1.1 }
165    
166     <comment># Only WPA-PSK is used. Any valid cipher combination is accepted</comment>
167     network={
168 swift 1.2 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 swift 1.1 }
176    
177     <comment># Plaintext connection (no WPA, no IEEE 802.1X)</comment>
178     network={
179 swift 1.2 ssid="plaintext-test"
180     key_mgmt=NONE
181 swift 1.1 }
182    
183     <comment># Shared WEP key connection (no WPA, no IEEE 802.1X)</comment>
184     network={
185 swift 1.2 ssid="static-wep-test"
186     key_mgmt=NONE
187 nightmorph 1.16 <comment># Keys in quotes are ASCII keys</comment>
188 swift 1.2 wep_key0="abcde"
189 nightmorph 1.16 <comment># Keys specified without quotes are hex keys</comment>
190 swift 1.2 wep_key1=0102030405
191     wep_key2="1234567890123"
192     wep_tx_keyidx=0
193     priority=5
194 swift 1.1 }
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 swift 1.2 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 swift 1.1 }
208    
209     <comment># IBSS/ad-hoc network with WPA-None/TKIP</comment>
210     network={
211 swift 1.2 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 swift 1.1 }
219 swift 1.2 </pre>
220 swift 1.1
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 jkt 1.6 <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 swift 1.1 </p>
237    
238     <p>
239 jkt 1.6 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 swift 1.1 </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 jkt 1.9 <path>/etc/conf.d/net</path>.
253 swift 1.1 </note>
254    
255     <impo>
256 jkt 1.6 You <e>will</e> need to consult the <uri
257     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
258 swift 1.1 </impo>
259    
260     <pre caption="sample iwconfig setup in /etc/conf.d/net">
261     <comment># Prefer iwconfig over wpa_supplicant</comment>
262 swift 1.20 modules="iwconfig"
263 swift 1.1
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 jkt 1.9 #
270 swift 1.1 # Prefixing the key with s: means it's an ASCII key, otherwise a HEX key
271 jkt 1.9 #
272 swift 1.1 # 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 swift 1.20 preferred_aps="'ESSID1' 'ESSID2'"
282 swift 1.1 </pre>
283    
284     </body>
285     </subsection>
286     <subsection>
287     <title>Fine tune Access Point Selection</title>
288     <body>
289    
290     <p>
291 jkt 1.6 You can add some extra options to fine-tune your Access Point selection, but
292     these are not normally required.
293 swift 1.1 </p>
294    
295     <p>
296 jkt 1.6 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 swift 1.1 </p>
301    
302     <table>
303 swift 1.2 <tr>
304     <th>Value</th>
305     <th>Description</th>
306     </tr>
307     <tr>
308 jkt 1.7 <ti><c>any</c></ti>
309 swift 1.2 <ti>Default behaviour</ti>
310     </tr>
311     <tr>
312 jkt 1.7 <ti><c>preferredonly</c></ti>
313 swift 1.2 <ti>We will only connect to visible APs in the preferred list</ti>
314     </tr>
315     <tr>
316 jkt 1.7 <ti><c>forcepreferred</c></ti>
317 swift 1.2 <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 jkt 1.7 <ti><c>forcepreferredonly</c></ti>
324 swift 1.2 <ti>
325     Do not scan for APs - instead just try to connect to each one in order
326     </ti>
327     </tr>
328     <tr>
329 jkt 1.7 <ti><c>forceany</c></ti>
330 jkt 1.9 <ti>Same as <c>forcepreferred</c> + connect to any other available AP</ti>
331 swift 1.2 </tr>
332 swift 1.1 </table>
333    
334     <p>
335 jkt 1.7 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 jkt 1.9 <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 swift 1.1 </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 swift 1.20 blacklist_aps="'ESSID3' 'ESSID4'"
344 swift 1.1
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 jkt 1.6 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 swift 1.1 </p>
362    
363     <pre caption="fallback to ad-hoc mode">
364     adhoc_essid_eth0="This Adhoc Node"
365     </pre>
366    
367     <p>
368 jkt 1.6 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 swift 1.1 </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 jkt 1.6 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 swift 1.1 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 jkt 1.6 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 swift 1.1 </p>
411    
412     <table>
413 swift 1.2 <tr>
414     <th>Variable</th>
415     <th>Default Value</th>
416     <th>Description</th>
417     </tr>
418     <tr>
419 jkt 1.7 <ti><c>iwconfig_eth0</c></ti>
420 swift 1.2 <ti/>
421 jkt 1.7 <ti>See the iwconfig man page for details on what to send <c>iwconfig</c></ti>
422 swift 1.2 </tr>
423     <tr>
424 jkt 1.7 <ti><c>iwpriv_eth0</c></ti>
425 swift 1.2 <ti/>
426 jkt 1.7 <ti>See the iwpriv man page for details on what to send <c>iwpriv</c></ti>
427 swift 1.2 </tr>
428     <tr>
429 jkt 1.7 <ti><c>sleep_scan_eth0</c></ti>
430     <ti><c>0</c></ti>
431 swift 1.2 <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 jkt 1.7 <ti><c>sleep_associate_eth0</c></ti>
438     <ti><c>5</c></ti>
439 swift 1.2 <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 jkt 1.7 <ti><c>associate_test_eth0</c></ti>
446     <ti><c>MAC</c></ti>
447 swift 1.2 <ti>
448 vanquirius 1.11 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 jkt 1.7 <c>MAC</c>, <c>quality</c> and <c>all</c>.
452 swift 1.2 </ti>
453     </tr>
454     <tr>
455 jkt 1.7 <ti><c>scan_mode_eth0</c></ti>
456 swift 1.2 <ti/>
457     <ti>
458     Some drivers have to scan in ad-hoc mode, so if scanning fails
459 jkt 1.7 try setting <c>ad-hoc</c> here
460 swift 1.2 </ti>
461     </tr>
462     <tr>
463 jkt 1.7 <ti><c>iwpriv_scan_pre_eth0</c></ti>
464 swift 1.2 <ti/>
465     <ti>
466 jkt 1.7 Sends some <c>iwpriv</c> commands to the interface before scanning.
467     See the iwpriv man page for more details.
468 swift 1.2 </ti>
469     </tr>
470     <tr>
471 jkt 1.7 <ti><c>iwpriv_scan_post_eth0</c></ti>
472 swift 1.2 <ti/>
473     <ti>
474 jkt 1.7 Sends some <c>iwpriv</c> commands to the interface after scanning.
475     See the iwpriv man page for more details.
476 swift 1.2 </ti>
477     </tr>
478 swift 1.1 </table>
479    
480     </body>
481     </subsection>
482     </section>
483     <section>
484     <title>Defining network configuration per ESSID</title>
485     <body>
486    
487     <p>
488 neysx 1.8 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 swift 1.1 </p>
492    
493     <note>
494     These work if you're using WPA Supplicant or Wireless Tools.
495     </note>
496    
497     <impo>
498 jkt 1.7 You <e>will</e> need to consult the <uri
499     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
500 swift 1.1 </impo>
501    
502     <pre caption="override network settings per ESSID">
503 swift 1.20 config_ESSID1="192.168.0.3/24 brd 192.168.0.255"
504     routes_ESSID1="default via 192.168.0.1"
505 swift 1.1
506 swift 1.20 config_ESSID2="dhcp"
507     fallback_ESSID2="192.168.3.4/24"
508     fallback_route_ESSID2="default via 192.168.3.1"
509 swift 1.1
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 swift 1.20 dns_servers_ESSID1="192.168.0.1 192.168.0.2"
513 swift 1.1 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 swift 1.20 config_001122334455="dhcp"
519 swift 1.1 dhcpcd_001122334455="-t 10"
520 swift 1.20 dns_servers_001122334455="192.168.0.1 192.168.0.2"
521 swift 1.1 </pre>
522    
523     </body>
524     </section>
525     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20