/[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.10 - (hide annotations) (download) (as text)
Thu Dec 22 19:55:49 2005 UTC (8 years, 7 months ago) by jkt
Branch: MAIN
Changes since 1.9: +48 -49 lines
File MIME type: application/xml
#116267, hb-net-*: adding <c>s, <path>s, proper capitalization,...

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

  ViewVC Help
Powered by ViewVC 1.1.20