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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.22 - (hide annotations) (download) (as text)
Sun Apr 8 01:28:11 2007 UTC (7 years ago) by nightmorph
Branch: MAIN
Changes since 1.21: +31 -17 lines
File MIME type: application/xml
new ADSL/PPP setup, bug 171584. note that i went ahead and did the major version number bump a day or so ahead of the release schedule. i figure, why not. early is better.

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 swift 1.2 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.1
7 nightmorph 1.22 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-modules.xml,v 1.21 2007/01/04 06:03:26 nightmorph Exp $ -->
8 neysx 1.5
9 swift 1.1 <sections>
10    
11 neysx 1.19 <abstract>
12     Gentoo provides you flexible networking - here you are told about choosing
13     different DHCP clients, setting up bonding, bridging, VLANs and more.
14     </abstract>
15    
16 nightmorph 1.22 <version>8.0</version>
17     <date>2007-04-07</date>
18 swift 1.1
19     <section>
20     <title>Network Modules</title>
21     <body>
22    
23     <p>
24 jkt 1.9 We now support modular networking scripts, which means we can easily add support
25     for new interface types and configuration modules while keeping compatibility
26     with existing ones.
27 swift 1.1 </p>
28    
29     <p>
30 jkt 1.9 Modules load by default if the package they need is installed. If you specify a
31     module here that doesn't have its package installed then you get an error
32     stating which package you need to install. Ideally, you only use the modules
33     setting when you have two or more packages installed that supply the same
34     service and you need to prefer one over the other.
35 swift 1.1 </p>
36    
37 vapier 1.15 <note>
38     All settings discussed here are stored in <path>/etc/conf.d/net</path> unless
39     otherwise specified.
40     </note>
41    
42 swift 1.1 <pre caption="Module preference">
43     <comment># Prefer iproute2 over ifconfig</comment>
44     modules=( "iproute2" )
45    
46     <comment># You can also specify other modules for an interface
47     # In this case we prefer udhcpc over dhcpcd</comment>
48     modules_eth0=( "udhcpc" )
49    
50     <comment># You can also specify which modules not to use - for example you may be
51     # using a supplicant or linux-wlan-ng to control wireless configuration but
52     # you still want to configure network settings per ESSID associated with.</comment>
53     modules=( "!iwconfig" )
54     </pre>
55    
56     </body>
57     </section>
58     <section>
59     <title>Interface Handlers</title>
60     <body>
61    
62     <p>
63 jkt 1.10 We provide two interface handlers presently: <c>ifconfig</c> and
64     <c>iproute2</c>. You need one of these to do any kind of network configuration.
65 swift 1.1 </p>
66    
67     <p>
68 jkt 1.10 <c>ifconfig</c> is the current Gentoo default and it's included in the system
69     profile. <c>iproute2</c> is a more powerful and flexible package, but it's not
70     included by default.
71 swift 1.1 </p>
72    
73     <pre caption="To install iproute2">
74     # <i>emerge sys-apps/iproute2</i>
75    
76     <comment># To prefer iproute2 over ifconfig if both are installed</comment>
77     modules=( "iproute2" )
78     </pre>
79    
80     <p>
81 jkt 1.10 As both <c>ifconfig</c> and <c>iproute2</c> do very similar things we allow
82     their basic configuration to work with each other. For example both the below
83     code snippet work regardless of which module you are using.
84 swift 1.1 </p>
85    
86     <pre caption="ifconfig and iproute2 examples">
87     config_eth0=( "192.168.0.2/24" )
88     config_eth0=( "192.168.0.2 netmask 255.255.255.0" )
89    
90     <comment># We can also specify broadcast</comment>
91     config_eth0=( "192.168.0.2/24 brd 192.168.0.255" )
92     config_eth0=( "192.168.0.2 netmask 255.255.255.0 broadcast 192.168.0.255" )
93     </pre>
94    
95     </body>
96     </section>
97     <section id="dhcp">
98     <title>DHCP</title>
99     <body>
100    
101     <p>
102     DHCP is a means of obtaining network information (IP address, DNS servers,
103     Gateway, etc) from a DHCP server. This means that if there is a DHCP server
104     running on the network, you just have to tell each client to use DHCP and it
105     sets up the network all by itself. Of course, you will have to configure for
106 jkt 1.10 other things like wireless, PPP or other things if required before you can use
107 swift 1.1 DHCP.
108     </p>
109    
110     <p>
111 jkt 1.10 DHCP can be provided by <c>dhclient</c>, <c>dhcpcd</c>, <c>pump</c> or
112     <c>udhcpc</c>. Each DHCP module has its pros and cons - here's a quick run down.
113 swift 1.1 </p>
114    
115     <table>
116 swift 1.2 <tr>
117     <th>DHCP Module</th>
118     <th>Package</th>
119     <th>Pros</th>
120     <th>Cons</th>
121     </tr>
122     <tr>
123 jkt 1.10 <ti><c>dhclient</c></ti>
124     <ti><c>net-misc/dhcp</c></ti>
125 swift 1.2 <ti>
126 swift 1.3 Made by ISC, the same people who make the BIND DNS software. Very
127     configurable
128 swift 1.2 </ti>
129     <ti>
130 swift 1.3 Configuration is overly complex, software is quite bloated, cannot get
131     NTP servers from DHCP, does not send hostname by default
132 swift 1.2 </ti>
133     </tr>
134     <tr>
135 jkt 1.10 <ti><c>dhcpcd</c></ti>
136     <ti><c>net-misc/dhcpcd</c></ti>
137 swift 1.2 <ti>
138 nightmorph 1.20 Long time Gentoo default, no reliance on outside tools, actively developed
139     by Gentoo
140 swift 1.2 </ti>
141 nightmorph 1.20 <ti>Can be slow at times, does not yet daemonize when lease is infinite</ti>
142 swift 1.2 </tr>
143     <tr>
144 jkt 1.10 <ti><c>pump</c></ti>
145     <ti><c>net-misc/pump</c></ti>
146 swift 1.2 <ti>
147 swift 1.3 Lightweight, no reliance on outside tools
148 swift 1.2 </ti>
149     <ti>
150 swift 1.3 No longer maintained upstream, unreliable, especially over modems, cannot
151     get NIS servers from DHCP
152 swift 1.2 </ti>
153     </tr>
154     <tr>
155 jkt 1.10 <ti><c>udhcpc</c></ti>
156     <ti><c>net-misc/udhcp</c></ti>
157 swift 1.2 <ti>
158 jkt 1.10 Lightweight - smallest DHCP client around, made for embedded systems
159 swift 1.2 </ti>
160     <ti>
161 swift 1.3 Unproven - no distro uses it by default, cannot define a timeout beyond 3
162     seconds
163 swift 1.2 </ti>
164     </tr>
165 swift 1.1 </table>
166    
167     <p>
168 jkt 1.9 If you have more than one DHCP client installed, you need to specify which one
169 jkt 1.10 to use - otherwise we default to <c>dhcpcd</c> if available.
170 swift 1.1 </p>
171    
172     <p>
173 jkt 1.10 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
174 flammie 1.17 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
175 swift 1.1 </p>
176    
177     <p>
178     We try and make DHCP relatively agnostic - as such we support the following
179 jkt 1.10 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
180     them:
181 swift 1.1 </p>
182    
183     <ul>
184 jkt 1.10 <li><c>release</c> - releases the IP address for re-use</li>
185     <li><c>nodns</c> - don't overwrite <path>/etc/resolv.conf</path></li>
186     <li><c>nontp</c> - don't overwrite <path>/etc/ntp.conf</path></li>
187     <li><c>nonis</c> - don't overwrite <path>/etc/yp.conf</path></li>
188 swift 1.1 </ul>
189    
190     <pre caption="Sample DHCP configuration in /etc/conf.d/net">
191     <comment># Only needed if you have more than one DHCP module installed</comment>
192     modules=( "dhcpcd" )
193    
194     config_eth0=( "dhcp" )
195     dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment>
196     dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment>
197     </pre>
198    
199     <note>
200 jkt 1.10 <c>dhcpcd</c>, <c>udhcpc</c> and <c>pump</c> send the current hostname to the
201     DHCP server by default so you don't need to specify this anymore.
202 swift 1.1 </note>
203    
204     </body>
205     </section>
206     <section>
207     <title>ADSL Modem</title>
208     <body>
209    
210     <p>
211     First we need to install the ADSL software.
212     </p>
213    
214 nightmorph 1.22 <pre caption="Install the ppp package">
215     # <i>emerge net-dialup/ppp</i>
216 swift 1.1 </pre>
217    
218 nightmorph 1.22 <note>
219     If you need PPPoA, then you need to use >=<c>baselayout-1.12.x</c>.
220     </note>
221    
222     <p>
223     Second, create the PPP net script:
224     </p>
225    
226     <pre caption="Creating the PPP net script">
227     # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0</i>
228     </pre>
229 swift 1.1
230     <p>
231 nightmorph 1.22 Now we need to configure <path>/etc/conf.d/net</path>.
232 swift 1.1 </p>
233    
234 nightmorph 1.22 <pre caption="A basic PPPoE setup">
235     config_ppp0=( "ppp" )
236     link_ppp0="eth0" <comment>(For PPPoE users; replace eth0 with your actual PPP interface)</comment>
237     plugins_ppp0=( "pppoe" )
238     username_ppp0='user'
239     password_ppp0='password'
240 swift 1.1 </pre>
241    
242     <p>
243 nightmorph 1.22 You can also set your password in <path>/etc/ppp/pap-secrets</path>.
244 swift 1.1 </p>
245    
246 nightmorph 1.22 <pre caption="Sample /etc/ppp/pap-secrets">
247 swift 1.1 <comment># The * is important</comment>
248 swift 1.4 "username" * "password"
249 swift 1.1 </pre>
250    
251 nightmorph 1.22 <impo>
252     Please carefully read the section on ADSL and PPP in
253     <path>/etc/conf.d/net.example</path>. It contains many more detailed
254     explanations of all the settings your particular PPP setup will likely need.
255     </impo>
256    
257 swift 1.1 </body>
258     </section>
259     <section id="apipa">
260     <title>APIPA (Automatic Private IP Addressing)</title>
261     <body>
262    
263     <p>
264 jkt 1.9 APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 by
265     arping a random address in that range on the interface. If no reply is found
266     then we assign that address to the interface.
267 swift 1.1 </p>
268    
269     <p>
270 jkt 1.9 This is only useful for LANs where there is no DHCP server and you don't connect
271     directly to the internet and all other computers use APIPA.
272 swift 1.1 </p>
273    
274     <p>
275 jkt 1.10 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
276 swift 1.1 </p>
277    
278     <pre caption="APIPA configuration in /etc/conf.d/net">
279     <comment># Try DHCP first - if that fails then fallback to APIPA</comment>
280     config_eth0=( "dhcp" )
281     fallback_eth0=( "apipa" )
282    
283     <comment># Just use APIPA</comment>
284     config_eth0=( "apipa" )
285     </pre>
286    
287     </body>
288     </section>
289     <section>
290     <title>Bonding</title>
291     <body>
292    
293     <p>
294 jkt 1.10 For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
295 swift 1.1 </p>
296    
297     <p>
298 jkt 1.9 Bonding is used to increase network bandwidth. If you have two network cards
299     going to the same network, you can bond them together so your applications see
300     just one interface but they really use both network cards.
301 swift 1.1 </p>
302    
303     <pre caption="bonding configuration in /etc/conf.d/net">
304 jkt 1.13 <comment># To bond interfaces together</comment>
305 swift 1.1 slaves_bond0="eth0 eth1 eth2"
306    
307     <comment># You may not want to assign an IP to the bonded interface</comment>
308     config_bond0=( "null" )
309    
310     <comment># Depend on eth0, eth1 and eth2 as they may require extra configuration</comment>
311     depend_bond0() {
312 swift 1.4 need net.eth0 net.eth1 net.eth2
313 swift 1.1 }
314     </pre>
315    
316     </body>
317     </section>
318     <section>
319     <title>Bridging (802.1d support)</title>
320     <body>
321    
322     <p>
323 jkt 1.10 For bridging support emerge <c>net-misc/bridge-utils</c>.
324 swift 1.1 </p>
325    
326     <p>
327 jkt 1.9 Bridging is used to join networks together. For example, you may have a server
328     that connects to the internet via an ADSL modem and a wireless access card to
329     enable other computers to connect to the internet via the ADSL modem. You could
330     create a bridge to join the two interfaces together.
331 swift 1.1 </p>
332    
333     <pre caption="Bridge configuration in /etc/conf.d/net">
334     <comment># Configure the bridge - "man btctl" for more details</comment>
335     brctl_br0=( "setfd 0" "sethello 0" "stp off" )
336    
337     <comment># To add ports to bridge br0</comment>
338     bridge_br0="eth0 eth1"
339    
340     <comment># You need to configure the ports to null values so dhcp does not get started</comment>
341     config_eth0=( "null" )
342     config_eth1=( "null" )
343    
344     <comment># Finally give the bridge an address - you could use DHCP as well</comment>
345     config_br0=( "192.168.0.1/24" )
346    
347     <comment># Depend on eth0 and eth1 as they may require extra configuration</comment>
348     depend_br0() {
349 swift 1.4 need net.eth0 net.eth1
350 swift 1.1 }
351     </pre>
352    
353     <impo>
354 jkt 1.10 For using some bridge setups, you may need to consult the <uri
355     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
356 swift 1.1 </impo>
357    
358     </body>
359     </section>
360     <section>
361     <title>MAC Address</title>
362     <body>
363    
364     <p>
365 rane 1.11 You don't need to emerge anything for changing the MAC address of your
366     interface if you have <c>sys-apps/baselayout-1.11.14</c> or newer and want to
367 fox2mike 1.12 change to a specific MAC address. However, if you need to change to a random MAC
368     address or have a baselayout older than the version mentioned above, you have
369     to emerge <c>net-analyzer/macchanger</c> to be able to make use of this feature.
370 swift 1.1 </p>
371    
372     <pre caption="MAC Address change example">
373     <comment># To set the MAC address of the interface</comment>
374     mac_eth0="00:11:22:33:44:55"
375    
376     <comment># To randomize the last 3 bytes only</comment>
377     mac_eth0="random-ending"
378    
379 flammie 1.17 <comment># To randomize between the same physical type of connection (e.g. fibre,
380 swift 1.1 # copper, wireless) , all vendors</comment>
381     mac_eth0="random-samekind"
382    
383 flammie 1.17 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
384 swift 1.1 # wireless) , all vendors</comment>
385     mac_eth0="random-anykind"
386    
387     <comment># Full randomization - WARNING: some MAC addresses generated by this may
388     # NOT act as expected</comment>
389     mac_eth0="random-full"
390     </pre>
391    
392     </body>
393     </section>
394     <section>
395     <title>Tunnelling</title>
396     <body>
397    
398     <p>
399 jkt 1.9 You don't need to emerge anything for tunnelling as the interface handler can do
400     it for you.
401 swift 1.1 </p>
402    
403     <pre caption="Tunnelling configuration in /etc/conf.d/net">
404     <comment># For GRE tunnels</comment>
405     iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
406    
407     <comment># For IPIP tunnels</comment>
408     iptunnel_vpn0="mode ipip remote 207.170.82.2 ttl 255"
409    
410     <comment># To configure the interface</comment>
411     config_vpn0=( "192.168.0.2 peer 192.168.1.1" )
412     </pre>
413    
414     </body>
415     </section>
416     <section>
417     <title>VLAN (802.1q support)</title>
418     <body>
419    
420     <p>
421 jkt 1.10 For VLAN support, emerge <c>net-misc/vconfig</c>.
422 swift 1.1 </p>
423    
424 swift 1.2 <p>
425 jkt 1.9 Virtual LAN is a group of network devices that behave as if they were connected
426     to a single network segment - even though they may not be. VLAN members can only
427     see members of the same VLAN even though they may share the same physical
428     network.
429 swift 1.1 </p>
430    
431     <pre caption="VLAN configuration in /etc/conf.d/net">
432     <comment># Specify the VLAN numbers for the interface like so</comment>
433     <comment># Please ensure your VLAN IDs are NOT zero-padded</comment>
434     vlans_eth0="1 2"
435    
436     <comment># You can also configure the VLAN</comment>
437     <comment># see for vconfig man page for more details</comment>
438     vconfig_eth0=( "set_name_type VLAN_PLUS_VID_NO_PAD" )
439     vconfig_vlan1=( "set_flag 1" "set_egress_map 2 6" )
440    
441     <comment># Configure the interface as usual</comment>
442     config_vlan1=( "172.16.3.1 netmask 255.255.254.0" )
443     config_vlan2=( "172.16.2.1 netmask 255.255.254.0" )
444     </pre>
445    
446     <impo>
447 jkt 1.10 For using some VLAN setups, you may need to consult the <uri
448     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
449 swift 1.1 </impo>
450    
451     </body>
452     </section>
453    
454     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20