/[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.19 - (hide annotations) (download) (as text)
Sat Oct 28 09:17:55 2006 UTC (7 years, 8 months ago) by neysx
Branch: MAIN
Changes since 1.18: +6 -1 lines
File MIME type: application/xml
Moved chapter abstracts into shared chapters
No content change, hence no bump

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 neysx 1.19 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-modules.xml,v 1.18 2006/08/30 22:52:28 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.18 <version>7.0</version>
17     <date>2006-08-30</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 swift 1.3 Long time Gentoo default, no reliance on outside tools
139 swift 1.2 </ti>
140     <ti>
141 swift 1.3 No longer maintained upstream, can be slow at times, does not daemonize
142     when lease is infinite
143 swift 1.2 </ti>
144     </tr>
145     <tr>
146 jkt 1.10 <ti><c>pump</c></ti>
147     <ti><c>net-misc/pump</c></ti>
148 swift 1.2 <ti>
149 swift 1.3 Lightweight, no reliance on outside tools
150 swift 1.2 </ti>
151     <ti>
152 swift 1.3 No longer maintained upstream, unreliable, especially over modems, cannot
153     get NIS servers from DHCP
154 swift 1.2 </ti>
155     </tr>
156     <tr>
157 jkt 1.10 <ti><c>udhcpc</c></ti>
158     <ti><c>net-misc/udhcp</c></ti>
159 swift 1.2 <ti>
160 jkt 1.10 Lightweight - smallest DHCP client around, made for embedded systems
161 swift 1.2 </ti>
162     <ti>
163 swift 1.3 Unproven - no distro uses it by default, cannot define a timeout beyond 3
164     seconds
165 swift 1.2 </ti>
166     </tr>
167 swift 1.1 </table>
168    
169     <p>
170 jkt 1.9 If you have more than one DHCP client installed, you need to specify which one
171 jkt 1.10 to use - otherwise we default to <c>dhcpcd</c> if available.
172 swift 1.1 </p>
173    
174     <p>
175 jkt 1.10 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
176 flammie 1.17 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
177 swift 1.1 </p>
178    
179     <p>
180     We try and make DHCP relatively agnostic - as such we support the following
181 jkt 1.10 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
182     them:
183 swift 1.1 </p>
184    
185     <ul>
186 jkt 1.10 <li><c>release</c> - releases the IP address for re-use</li>
187     <li><c>nodns</c> - don't overwrite <path>/etc/resolv.conf</path></li>
188     <li><c>nontp</c> - don't overwrite <path>/etc/ntp.conf</path></li>
189     <li><c>nonis</c> - don't overwrite <path>/etc/yp.conf</path></li>
190 swift 1.1 </ul>
191    
192     <pre caption="Sample DHCP configuration in /etc/conf.d/net">
193     <comment># Only needed if you have more than one DHCP module installed</comment>
194     modules=( "dhcpcd" )
195    
196     config_eth0=( "dhcp" )
197     dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment>
198     dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment>
199     </pre>
200    
201     <note>
202 jkt 1.10 <c>dhcpcd</c>, <c>udhcpc</c> and <c>pump</c> send the current hostname to the
203     DHCP server by default so you don't need to specify this anymore.
204 swift 1.1 </note>
205    
206     </body>
207     </section>
208     <section>
209     <title>ADSL Modem</title>
210     <body>
211    
212     <p>
213     First we need to install the ADSL software.
214     </p>
215    
216     <pre caption="Install the rp-pppoe package">
217     # <i>emerge net-dialup/rp-pppoe</i>
218     </pre>
219    
220     <warn>
221 jkt 1.10 <c>baselayout-1.11.x</c> supports PPPoE only. Hopefully future versions will
222     support PPPoA.
223 swift 1.1 </warn>
224    
225     <p>
226 vapier 1.14 Now we need to configure <c>eth0</c> to be an ADSL interface and enter our
227     username by updating <path>/etc/conf.d/net</path>.
228 swift 1.1 </p>
229    
230 vapier 1.14 <pre caption="Configure eth0 for ADSL in /etc/conf.d/net">
231 swift 1.1 config_eth0=( "adsl" )
232 jkt 1.8 adsl_user_eth0="username"
233 swift 1.1 </pre>
234    
235     <p>
236     Finally you need to define your username and password in
237 jkt 1.10 <path>/etc/ppp/pap-secrets</path>.
238 swift 1.1 </p>
239    
240     <pre caption="sample /etc/ppp/pap-secrets">
241     <comment># The * is important</comment>
242 swift 1.4 "username" * "password"
243 swift 1.1 </pre>
244    
245     </body>
246     </section>
247     <section id="apipa">
248     <title>APIPA (Automatic Private IP Addressing)</title>
249     <body>
250    
251     <p>
252 jkt 1.9 APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 by
253     arping a random address in that range on the interface. If no reply is found
254     then we assign that address to the interface.
255 swift 1.1 </p>
256    
257     <p>
258 jkt 1.9 This is only useful for LANs where there is no DHCP server and you don't connect
259     directly to the internet and all other computers use APIPA.
260 swift 1.1 </p>
261    
262     <p>
263 jkt 1.10 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
264 swift 1.1 </p>
265    
266     <pre caption="APIPA configuration in /etc/conf.d/net">
267     <comment># Try DHCP first - if that fails then fallback to APIPA</comment>
268     config_eth0=( "dhcp" )
269     fallback_eth0=( "apipa" )
270    
271     <comment># Just use APIPA</comment>
272     config_eth0=( "apipa" )
273     </pre>
274    
275     </body>
276     </section>
277     <section>
278     <title>Bonding</title>
279     <body>
280    
281     <p>
282 jkt 1.10 For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
283 swift 1.1 </p>
284    
285     <p>
286 jkt 1.9 Bonding is used to increase network bandwidth. If you have two network cards
287     going to the same network, you can bond them together so your applications see
288     just one interface but they really use both network cards.
289 swift 1.1 </p>
290    
291     <pre caption="bonding configuration in /etc/conf.d/net">
292 jkt 1.13 <comment># To bond interfaces together</comment>
293 swift 1.1 slaves_bond0="eth0 eth1 eth2"
294    
295     <comment># You may not want to assign an IP to the bonded interface</comment>
296     config_bond0=( "null" )
297    
298     <comment># Depend on eth0, eth1 and eth2 as they may require extra configuration</comment>
299     depend_bond0() {
300 swift 1.4 need net.eth0 net.eth1 net.eth2
301 swift 1.1 }
302     </pre>
303    
304     </body>
305     </section>
306     <section>
307     <title>Bridging (802.1d support)</title>
308     <body>
309    
310     <p>
311 jkt 1.10 For bridging support emerge <c>net-misc/bridge-utils</c>.
312 swift 1.1 </p>
313    
314     <p>
315 jkt 1.9 Bridging is used to join networks together. For example, you may have a server
316     that connects to the internet via an ADSL modem and a wireless access card to
317     enable other computers to connect to the internet via the ADSL modem. You could
318     create a bridge to join the two interfaces together.
319 swift 1.1 </p>
320    
321     <pre caption="Bridge configuration in /etc/conf.d/net">
322     <comment># Configure the bridge - "man btctl" for more details</comment>
323     brctl_br0=( "setfd 0" "sethello 0" "stp off" )
324    
325     <comment># To add ports to bridge br0</comment>
326     bridge_br0="eth0 eth1"
327    
328     <comment># You need to configure the ports to null values so dhcp does not get started</comment>
329     config_eth0=( "null" )
330     config_eth1=( "null" )
331    
332     <comment># Finally give the bridge an address - you could use DHCP as well</comment>
333     config_br0=( "192.168.0.1/24" )
334    
335     <comment># Depend on eth0 and eth1 as they may require extra configuration</comment>
336     depend_br0() {
337 swift 1.4 need net.eth0 net.eth1
338 swift 1.1 }
339     </pre>
340    
341     <impo>
342 jkt 1.10 For using some bridge setups, you may need to consult the <uri
343     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
344 swift 1.1 </impo>
345    
346     </body>
347     </section>
348     <section>
349     <title>MAC Address</title>
350     <body>
351    
352     <p>
353 rane 1.11 You don't need to emerge anything for changing the MAC address of your
354     interface if you have <c>sys-apps/baselayout-1.11.14</c> or newer and want to
355 fox2mike 1.12 change to a specific MAC address. However, if you need to change to a random MAC
356     address or have a baselayout older than the version mentioned above, you have
357     to emerge <c>net-analyzer/macchanger</c> to be able to make use of this feature.
358 swift 1.1 </p>
359    
360     <pre caption="MAC Address change example">
361     <comment># To set the MAC address of the interface</comment>
362     mac_eth0="00:11:22:33:44:55"
363    
364     <comment># To randomize the last 3 bytes only</comment>
365     mac_eth0="random-ending"
366    
367 flammie 1.17 <comment># To randomize between the same physical type of connection (e.g. fibre,
368 swift 1.1 # copper, wireless) , all vendors</comment>
369     mac_eth0="random-samekind"
370    
371 flammie 1.17 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
372 swift 1.1 # wireless) , all vendors</comment>
373     mac_eth0="random-anykind"
374    
375     <comment># Full randomization - WARNING: some MAC addresses generated by this may
376     # NOT act as expected</comment>
377     mac_eth0="random-full"
378     </pre>
379    
380     </body>
381     </section>
382     <section>
383     <title>Tunnelling</title>
384     <body>
385    
386     <p>
387 jkt 1.9 You don't need to emerge anything for tunnelling as the interface handler can do
388     it for you.
389 swift 1.1 </p>
390    
391     <pre caption="Tunnelling configuration in /etc/conf.d/net">
392     <comment># For GRE tunnels</comment>
393     iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
394    
395     <comment># For IPIP tunnels</comment>
396     iptunnel_vpn0="mode ipip remote 207.170.82.2 ttl 255"
397    
398     <comment># To configure the interface</comment>
399     config_vpn0=( "192.168.0.2 peer 192.168.1.1" )
400     </pre>
401    
402     </body>
403     </section>
404     <section>
405     <title>VLAN (802.1q support)</title>
406     <body>
407    
408     <p>
409 jkt 1.10 For VLAN support, emerge <c>net-misc/vconfig</c>.
410 swift 1.1 </p>
411    
412 swift 1.2 <p>
413 jkt 1.9 Virtual LAN is a group of network devices that behave as if they were connected
414     to a single network segment - even though they may not be. VLAN members can only
415     see members of the same VLAN even though they may share the same physical
416     network.
417 swift 1.1 </p>
418    
419     <pre caption="VLAN configuration in /etc/conf.d/net">
420     <comment># Specify the VLAN numbers for the interface like so</comment>
421     <comment># Please ensure your VLAN IDs are NOT zero-padded</comment>
422     vlans_eth0="1 2"
423    
424     <comment># You can also configure the VLAN</comment>
425     <comment># see for vconfig man page for more details</comment>
426     vconfig_eth0=( "set_name_type VLAN_PLUS_VID_NO_PAD" )
427     vconfig_vlan1=( "set_flag 1" "set_egress_map 2 6" )
428    
429     <comment># Configure the interface as usual</comment>
430     config_vlan1=( "172.16.3.1 netmask 255.255.254.0" )
431     config_vlan2=( "172.16.2.1 netmask 255.255.254.0" )
432     </pre>
433    
434     <impo>
435 jkt 1.10 For using some VLAN setups, you may need to consult the <uri
436     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
437 swift 1.1 </impo>
438    
439     </body>
440     </section>
441    
442     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20