/[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.16 - (show annotations) (download) (as text)
Sat Apr 1 03:20:52 2006 UTC (8 years, 7 months ago) by vapier
Branch: MAIN
Changes since 1.15: +3 -3 lines
File MIME type: application/xml
update version/date

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.15 2006/04/01 03:19:51 vapier Exp $ -->
8
9 <sections>
10
11 <version>1.8</version>
12 <date>2006-03-31</date>
13
14 <section>
15 <title>Network Modules</title>
16 <body>
17
18 <p>
19 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 </p>
23
24 <p>
25 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 </p>
31
32 <note>
33 All settings discussed here are stored in <path>/etc/conf.d/net</path> unless
34 otherwise specified.
35 </note>
36
37 <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 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 </p>
61
62 <p>
63 <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 </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 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 </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 other things like wireless, PPP or other things if required before you can use
102 DHCP.
103 </p>
104
105 <p>
106 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 </p>
109
110 <table>
111 <tr>
112 <th>DHCP Module</th>
113 <th>Package</th>
114 <th>Pros</th>
115 <th>Cons</th>
116 </tr>
117 <tr>
118 <ti><c>dhclient</c></ti>
119 <ti><c>net-misc/dhcp</c></ti>
120 <ti>
121 Made by ISC, the same people who make the BIND DNS software. Very
122 configurable
123 </ti>
124 <ti>
125 Configuration is overly complex, software is quite bloated, cannot get
126 NTP servers from DHCP, does not send hostname by default
127 </ti>
128 </tr>
129 <tr>
130 <ti><c>dhcpcd</c></ti>
131 <ti><c>net-misc/dhcpcd</c></ti>
132 <ti>
133 Long time Gentoo default, no reliance on outside tools
134 </ti>
135 <ti>
136 No longer maintained upstream, can be slow at times, does not daemonize
137 when lease is infinite
138 </ti>
139 </tr>
140 <tr>
141 <ti><c>pump</c></ti>
142 <ti><c>net-misc/pump</c></ti>
143 <ti>
144 Lightweight, no reliance on outside tools
145 </ti>
146 <ti>
147 No longer maintained upstream, unreliable, especially over modems, cannot
148 get NIS servers from DHCP
149 </ti>
150 </tr>
151 <tr>
152 <ti><c>udhcpc</c></ti>
153 <ti><c>net-misc/udhcp</c></ti>
154 <ti>
155 Lightweight - smallest DHCP client around, made for embedded systems
156 </ti>
157 <ti>
158 Unproven - no distro uses it by default, cannot define a timeout beyond 3
159 seconds
160 </ti>
161 </tr>
162 </table>
163
164 <p>
165 If you have more than one DHCP client installed, you need to specify which one
166 to use - otherwise we default to <c>dhcpcd</c> if available.
167 </p>
168
169 <p>
170 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
171 <e>(change module to the DHCP module you're using - ie <c>dhcpcd_eth0</c>)</e>.
172 </p>
173
174 <p>
175 We try and make DHCP relatively agnostic - as such we support the following
176 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
177 them:
178 </p>
179
180 <ul>
181 <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 </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 <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 </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 <c>baselayout-1.11.x</c> supports PPPoE only. Hopefully future versions will
217 support PPPoA.
218 </warn>
219
220 <p>
221 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 </p>
224
225 <pre caption="Configure eth0 for ADSL in /etc/conf.d/net">
226 config_eth0=( "adsl" )
227 adsl_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 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 </p>
251
252 <p>
253 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 </p>
256
257 <p>
258 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
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 <c>net-misc/ifenslave</c>.
278 </p>
279
280 <p>
281 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 </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 <c>net-misc/bridge-utils</c>.
307 </p>
308
309 <p>
310 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 </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 <uri
338 link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
339 </impo>
340
341 </body>
342 </section>
343 <section>
344 <title>MAC Address</title>
345 <body>
346
347 <p>
348 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 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 </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 can do
383 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 <c>net-misc/vconfig</c>.
405 </p>
406
407 <p>
408 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 </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 <uri
431 link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
432 </impo>
433
434 </body>
435 </section>
436
437 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20