/[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.17 - (hide annotations) (download) (as text)
Mon Jun 19 12:08:14 2006 UTC (8 years, 3 months ago) by flammie
Branch: MAIN
Changes since 1.16: +4 -4 lines
File MIME type: application/xml
Fix e.g.'s and i.e.'s. No content change.

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 flammie 1.17 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-modules.xml,v 1.16 2006/04/01 03:20:52 vapier Exp $ -->
8 neysx 1.5
9 swift 1.1 <sections>
10    
11 vapier 1.16 <version>1.8</version>
12     <date>2006-03-31</date>
13 swift 1.1
14     <section>
15     <title>Network Modules</title>
16     <body>
17    
18     <p>
19 jkt 1.9 We now support modular networking scripts, which means we can easily add support
20     for new interface types and configuration modules while keeping compatibility
21     with existing ones.
22 swift 1.1 </p>
23    
24     <p>
25 jkt 1.9 Modules load by default if the package they need is installed. If you specify a
26     module here that doesn't have its package installed then you get an error
27     stating which package you need to install. Ideally, you only use the modules
28     setting when you have two or more packages installed that supply the same
29     service and you need to prefer one over the other.
30 swift 1.1 </p>
31    
32 vapier 1.15 <note>
33     All settings discussed here are stored in <path>/etc/conf.d/net</path> unless
34     otherwise specified.
35     </note>
36    
37 swift 1.1 <pre caption="Module preference">
38     <comment># Prefer iproute2 over ifconfig</comment>
39     modules=( "iproute2" )
40    
41     <comment># You can also specify other modules for an interface
42     # In this case we prefer udhcpc over dhcpcd</comment>
43     modules_eth0=( "udhcpc" )
44    
45     <comment># You can also specify which modules not to use - for example you may be
46     # using a supplicant or linux-wlan-ng to control wireless configuration but
47     # you still want to configure network settings per ESSID associated with.</comment>
48     modules=( "!iwconfig" )
49     </pre>
50    
51     </body>
52     </section>
53     <section>
54     <title>Interface Handlers</title>
55     <body>
56    
57     <p>
58 jkt 1.10 We provide two interface handlers presently: <c>ifconfig</c> and
59     <c>iproute2</c>. You need one of these to do any kind of network configuration.
60 swift 1.1 </p>
61    
62     <p>
63 jkt 1.10 <c>ifconfig</c> is the current Gentoo default and it's included in the system
64     profile. <c>iproute2</c> is a more powerful and flexible package, but it's not
65     included by default.
66 swift 1.1 </p>
67    
68     <pre caption="To install iproute2">
69     # <i>emerge sys-apps/iproute2</i>
70    
71     <comment># To prefer iproute2 over ifconfig if both are installed</comment>
72     modules=( "iproute2" )
73     </pre>
74    
75     <p>
76 jkt 1.10 As both <c>ifconfig</c> and <c>iproute2</c> do very similar things we allow
77     their basic configuration to work with each other. For example both the below
78     code snippet work regardless of which module you are using.
79 swift 1.1 </p>
80    
81     <pre caption="ifconfig and iproute2 examples">
82     config_eth0=( "192.168.0.2/24" )
83     config_eth0=( "192.168.0.2 netmask 255.255.255.0" )
84    
85     <comment># We can also specify broadcast</comment>
86     config_eth0=( "192.168.0.2/24 brd 192.168.0.255" )
87     config_eth0=( "192.168.0.2 netmask 255.255.255.0 broadcast 192.168.0.255" )
88     </pre>
89    
90     </body>
91     </section>
92     <section id="dhcp">
93     <title>DHCP</title>
94     <body>
95    
96     <p>
97     DHCP is a means of obtaining network information (IP address, DNS servers,
98     Gateway, etc) from a DHCP server. This means that if there is a DHCP server
99     running on the network, you just have to tell each client to use DHCP and it
100     sets up the network all by itself. Of course, you will have to configure for
101 jkt 1.10 other things like wireless, PPP or other things if required before you can use
102 swift 1.1 DHCP.
103     </p>
104    
105     <p>
106 jkt 1.10 DHCP can be provided by <c>dhclient</c>, <c>dhcpcd</c>, <c>pump</c> or
107     <c>udhcpc</c>. Each DHCP module has its pros and cons - here's a quick run down.
108 swift 1.1 </p>
109    
110     <table>
111 swift 1.2 <tr>
112     <th>DHCP Module</th>
113     <th>Package</th>
114     <th>Pros</th>
115     <th>Cons</th>
116     </tr>
117     <tr>
118 jkt 1.10 <ti><c>dhclient</c></ti>
119     <ti><c>net-misc/dhcp</c></ti>
120 swift 1.2 <ti>
121 swift 1.3 Made by ISC, the same people who make the BIND DNS software. Very
122     configurable
123 swift 1.2 </ti>
124     <ti>
125 swift 1.3 Configuration is overly complex, software is quite bloated, cannot get
126     NTP servers from DHCP, does not send hostname by default
127 swift 1.2 </ti>
128     </tr>
129     <tr>
130 jkt 1.10 <ti><c>dhcpcd</c></ti>
131     <ti><c>net-misc/dhcpcd</c></ti>
132 swift 1.2 <ti>
133 swift 1.3 Long time Gentoo default, no reliance on outside tools
134 swift 1.2 </ti>
135     <ti>
136 swift 1.3 No longer maintained upstream, can be slow at times, does not daemonize
137     when lease is infinite
138 swift 1.2 </ti>
139     </tr>
140     <tr>
141 jkt 1.10 <ti><c>pump</c></ti>
142     <ti><c>net-misc/pump</c></ti>
143 swift 1.2 <ti>
144 swift 1.3 Lightweight, no reliance on outside tools
145 swift 1.2 </ti>
146     <ti>
147 swift 1.3 No longer maintained upstream, unreliable, especially over modems, cannot
148     get NIS servers from DHCP
149 swift 1.2 </ti>
150     </tr>
151     <tr>
152 jkt 1.10 <ti><c>udhcpc</c></ti>
153     <ti><c>net-misc/udhcp</c></ti>
154 swift 1.2 <ti>
155 jkt 1.10 Lightweight - smallest DHCP client around, made for embedded systems
156 swift 1.2 </ti>
157     <ti>
158 swift 1.3 Unproven - no distro uses it by default, cannot define a timeout beyond 3
159     seconds
160 swift 1.2 </ti>
161     </tr>
162 swift 1.1 </table>
163    
164     <p>
165 jkt 1.9 If you have more than one DHCP client installed, you need to specify which one
166 jkt 1.10 to use - otherwise we default to <c>dhcpcd</c> if available.
167 swift 1.1 </p>
168    
169     <p>
170 jkt 1.10 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
171 flammie 1.17 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
172 swift 1.1 </p>
173    
174     <p>
175     We try and make DHCP relatively agnostic - as such we support the following
176 jkt 1.10 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
177     them:
178 swift 1.1 </p>
179    
180     <ul>
181 jkt 1.10 <li><c>release</c> - releases the IP address for re-use</li>
182     <li><c>nodns</c> - don't overwrite <path>/etc/resolv.conf</path></li>
183     <li><c>nontp</c> - don't overwrite <path>/etc/ntp.conf</path></li>
184     <li><c>nonis</c> - don't overwrite <path>/etc/yp.conf</path></li>
185 swift 1.1 </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 jkt 1.10 <c>dhcpcd</c>, <c>udhcpc</c> and <c>pump</c> send the current hostname to the
198     DHCP server by default so you don't need to specify this anymore.
199 swift 1.1 </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 jkt 1.10 <c>baselayout-1.11.x</c> supports PPPoE only. Hopefully future versions will
217     support PPPoA.
218 swift 1.1 </warn>
219    
220     <p>
221 vapier 1.14 Now we need to configure <c>eth0</c> to be an ADSL interface and enter our
222     username by updating <path>/etc/conf.d/net</path>.
223 swift 1.1 </p>
224    
225 vapier 1.14 <pre caption="Configure eth0 for ADSL in /etc/conf.d/net">
226 swift 1.1 config_eth0=( "adsl" )
227 jkt 1.8 adsl_user_eth0="username"
228 swift 1.1 </pre>
229    
230     <p>
231     Finally you need to define your username and password in
232 jkt 1.10 <path>/etc/ppp/pap-secrets</path>.
233 swift 1.1 </p>
234    
235     <pre caption="sample /etc/ppp/pap-secrets">
236     <comment># The * is important</comment>
237 swift 1.4 "username" * "password"
238 swift 1.1 </pre>
239    
240     </body>
241     </section>
242     <section id="apipa">
243     <title>APIPA (Automatic Private IP Addressing)</title>
244     <body>
245    
246     <p>
247 jkt 1.9 APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 by
248     arping a random address in that range on the interface. If no reply is found
249     then we assign that address to the interface.
250 swift 1.1 </p>
251    
252     <p>
253 jkt 1.9 This is only useful for LANs where there is no DHCP server and you don't connect
254     directly to the internet and all other computers use APIPA.
255 swift 1.1 </p>
256    
257     <p>
258 jkt 1.10 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
259 swift 1.1 </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 jkt 1.10 For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
278 swift 1.1 </p>
279    
280     <p>
281 jkt 1.9 Bonding is used to increase network bandwidth. If you have two network cards
282     going to the same network, you can bond them together so your applications see
283     just one interface but they really use both network cards.
284 swift 1.1 </p>
285    
286     <pre caption="bonding configuration in /etc/conf.d/net">
287 jkt 1.13 <comment># To bond interfaces together</comment>
288 swift 1.1 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 swift 1.4 need net.eth0 net.eth1 net.eth2
296 swift 1.1 }
297     </pre>
298    
299     </body>
300     </section>
301     <section>
302     <title>Bridging (802.1d support)</title>
303     <body>
304    
305     <p>
306 jkt 1.10 For bridging support emerge <c>net-misc/bridge-utils</c>.
307 swift 1.1 </p>
308    
309     <p>
310 jkt 1.9 Bridging is used to join networks together. For example, you may have a server
311     that connects to the internet via an ADSL modem and a wireless access card to
312     enable other computers to connect to the internet via the ADSL modem. You could
313     create a bridge to join the two interfaces together.
314 swift 1.1 </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 swift 1.4 need net.eth0 net.eth1
333 swift 1.1 }
334     </pre>
335    
336     <impo>
337 jkt 1.10 For using some bridge setups, you may need to consult the <uri
338     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
339 swift 1.1 </impo>
340    
341     </body>
342     </section>
343     <section>
344     <title>MAC Address</title>
345     <body>
346    
347     <p>
348 rane 1.11 You don't need to emerge anything for changing the MAC address of your
349     interface if you have <c>sys-apps/baselayout-1.11.14</c> or newer and want to
350 fox2mike 1.12 change to a specific MAC address. However, if you need to change to a random MAC
351     address or have a baselayout older than the version mentioned above, you have
352     to emerge <c>net-analyzer/macchanger</c> to be able to make use of this feature.
353 swift 1.1 </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 flammie 1.17 <comment># To randomize between the same physical type of connection (e.g. fibre,
363 swift 1.1 # copper, wireless) , all vendors</comment>
364     mac_eth0="random-samekind"
365    
366 flammie 1.17 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
367 swift 1.1 # 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 jkt 1.9 You don't need to emerge anything for tunnelling as the interface handler can do
383     it for you.
384 swift 1.1 </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 jkt 1.10 For VLAN support, emerge <c>net-misc/vconfig</c>.
405 swift 1.1 </p>
406    
407 swift 1.2 <p>
408 jkt 1.9 Virtual LAN is a group of network devices that behave as if they were connected
409     to a single network segment - even though they may not be. VLAN members can only
410     see members of the same VLAN even though they may share the same physical
411     network.
412 swift 1.1 </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 jkt 1.10 For using some VLAN setups, you may need to consult the <uri
431     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
432 swift 1.1 </impo>
433    
434     </body>
435     </section>
436    
437     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20