/[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.2 - (hide annotations) (download) (as text)
Tue Jun 14 10:04:44 2005 UTC (9 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.1: +68 -75 lines
File MIME type: application/xml
Coding style

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

  ViewVC Help
Powered by ViewVC 1.1.20