/[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 - (show annotations) (download) (as text)
Sat Oct 28 09:17:55 2006 UTC (8 years, 5 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 <?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 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6
7 <!-- $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
9 <sections>
10
11 <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 <version>7.0</version>
17 <date>2006-08-30</date>
18
19 <section>
20 <title>Network Modules</title>
21 <body>
22
23 <p>
24 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 </p>
28
29 <p>
30 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 </p>
36
37 <note>
38 All settings discussed here are stored in <path>/etc/conf.d/net</path> unless
39 otherwise specified.
40 </note>
41
42 <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 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 </p>
66
67 <p>
68 <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 </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 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 </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 other things like wireless, PPP or other things if required before you can use
107 DHCP.
108 </p>
109
110 <p>
111 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 </p>
114
115 <table>
116 <tr>
117 <th>DHCP Module</th>
118 <th>Package</th>
119 <th>Pros</th>
120 <th>Cons</th>
121 </tr>
122 <tr>
123 <ti><c>dhclient</c></ti>
124 <ti><c>net-misc/dhcp</c></ti>
125 <ti>
126 Made by ISC, the same people who make the BIND DNS software. Very
127 configurable
128 </ti>
129 <ti>
130 Configuration is overly complex, software is quite bloated, cannot get
131 NTP servers from DHCP, does not send hostname by default
132 </ti>
133 </tr>
134 <tr>
135 <ti><c>dhcpcd</c></ti>
136 <ti><c>net-misc/dhcpcd</c></ti>
137 <ti>
138 Long time Gentoo default, no reliance on outside tools
139 </ti>
140 <ti>
141 No longer maintained upstream, can be slow at times, does not daemonize
142 when lease is infinite
143 </ti>
144 </tr>
145 <tr>
146 <ti><c>pump</c></ti>
147 <ti><c>net-misc/pump</c></ti>
148 <ti>
149 Lightweight, no reliance on outside tools
150 </ti>
151 <ti>
152 No longer maintained upstream, unreliable, especially over modems, cannot
153 get NIS servers from DHCP
154 </ti>
155 </tr>
156 <tr>
157 <ti><c>udhcpc</c></ti>
158 <ti><c>net-misc/udhcp</c></ti>
159 <ti>
160 Lightweight - smallest DHCP client around, made for embedded systems
161 </ti>
162 <ti>
163 Unproven - no distro uses it by default, cannot define a timeout beyond 3
164 seconds
165 </ti>
166 </tr>
167 </table>
168
169 <p>
170 If you have more than one DHCP client installed, you need to specify which one
171 to use - otherwise we default to <c>dhcpcd</c> if available.
172 </p>
173
174 <p>
175 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
176 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
177 </p>
178
179 <p>
180 We try and make DHCP relatively agnostic - as such we support the following
181 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
182 them:
183 </p>
184
185 <ul>
186 <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 </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 <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 </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 <c>baselayout-1.11.x</c> supports PPPoE only. Hopefully future versions will
222 support PPPoA.
223 </warn>
224
225 <p>
226 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 </p>
229
230 <pre caption="Configure eth0 for ADSL in /etc/conf.d/net">
231 config_eth0=( "adsl" )
232 adsl_user_eth0="username"
233 </pre>
234
235 <p>
236 Finally you need to define your username and password in
237 <path>/etc/ppp/pap-secrets</path>.
238 </p>
239
240 <pre caption="sample /etc/ppp/pap-secrets">
241 <comment># The * is important</comment>
242 "username" * "password"
243 </pre>
244
245 </body>
246 </section>
247 <section id="apipa">
248 <title>APIPA (Automatic Private IP Addressing)</title>
249 <body>
250
251 <p>
252 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 </p>
256
257 <p>
258 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 </p>
261
262 <p>
263 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
264 </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 For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
283 </p>
284
285 <p>
286 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 </p>
290
291 <pre caption="bonding configuration in /etc/conf.d/net">
292 <comment># To bond interfaces together</comment>
293 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 need net.eth0 net.eth1 net.eth2
301 }
302 </pre>
303
304 </body>
305 </section>
306 <section>
307 <title>Bridging (802.1d support)</title>
308 <body>
309
310 <p>
311 For bridging support emerge <c>net-misc/bridge-utils</c>.
312 </p>
313
314 <p>
315 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 </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 need net.eth0 net.eth1
338 }
339 </pre>
340
341 <impo>
342 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 </impo>
345
346 </body>
347 </section>
348 <section>
349 <title>MAC Address</title>
350 <body>
351
352 <p>
353 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 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 </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 <comment># To randomize between the same physical type of connection (e.g. fibre,
368 # copper, wireless) , all vendors</comment>
369 mac_eth0="random-samekind"
370
371 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
372 # 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 You don't need to emerge anything for tunnelling as the interface handler can do
388 it for you.
389 </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 For VLAN support, emerge <c>net-misc/vconfig</c>.
410 </p>
411
412 <p>
413 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 </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 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 </impo>
438
439 </body>
440 </section>
441
442 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20