/[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.12 - (show annotations) (download) (as text)
Tue Jan 3 07:47:17 2006 UTC (8 years, 11 months ago) by fox2mike
Branch: MAIN
Changes since 1.11: +5 -5 lines
File MIME type: application/xml
Cleaning up after a sleepy rane ;)

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.11 2006/01/03 07:32:56 rane Exp $ -->
8
9 <sections>
10
11 <version>1.7</version>
12 <date>2006-01-03</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 <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 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 </p>
56
57 <p>
58 <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 </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 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 </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 other things like wireless, PPP or other things if required before you can use
97 DHCP.
98 </p>
99
100 <p>
101 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 </p>
104
105 <table>
106 <tr>
107 <th>DHCP Module</th>
108 <th>Package</th>
109 <th>Pros</th>
110 <th>Cons</th>
111 </tr>
112 <tr>
113 <ti><c>dhclient</c></ti>
114 <ti><c>net-misc/dhcp</c></ti>
115 <ti>
116 Made by ISC, the same people who make the BIND DNS software. Very
117 configurable
118 </ti>
119 <ti>
120 Configuration is overly complex, software is quite bloated, cannot get
121 NTP servers from DHCP, does not send hostname by default
122 </ti>
123 </tr>
124 <tr>
125 <ti><c>dhcpcd</c></ti>
126 <ti><c>net-misc/dhcpcd</c></ti>
127 <ti>
128 Long time Gentoo default, no reliance on outside tools
129 </ti>
130 <ti>
131 No longer maintained upstream, can be slow at times, does not daemonize
132 when lease is infinite
133 </ti>
134 </tr>
135 <tr>
136 <ti><c>pump</c></ti>
137 <ti><c>net-misc/pump</c></ti>
138 <ti>
139 Lightweight, no reliance on outside tools
140 </ti>
141 <ti>
142 No longer maintained upstream, unreliable, especially over modems, cannot
143 get NIS servers from DHCP
144 </ti>
145 </tr>
146 <tr>
147 <ti><c>udhcpc</c></ti>
148 <ti><c>net-misc/udhcp</c></ti>
149 <ti>
150 Lightweight - smallest DHCP client around, made for embedded systems
151 </ti>
152 <ti>
153 Unproven - no distro uses it by default, cannot define a timeout beyond 3
154 seconds
155 </ti>
156 </tr>
157 </table>
158
159 <p>
160 If you have more than one DHCP client installed, you need to specify which one
161 to use - otherwise we default to <c>dhcpcd</c> if available.
162 </p>
163
164 <p>
165 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 </p>
168
169 <p>
170 We try and make DHCP relatively agnostic - as such we support the following
171 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
172 them:
173 </p>
174
175 <ul>
176 <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 </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 <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 </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 <c>baselayout-1.11.x</c> supports PPPoE only. Hopefully future versions will
212 support PPPoA.
213 </warn>
214
215 <p>
216 Now we need to instruct configure <c>eth0</c> to be an ADSL interface and enter
217 our username.
218 </p>
219
220 <pre caption="Configure eth0 for ADSL">
221 config_eth0=( "adsl" )
222 adsl_user_eth0="username"
223 </pre>
224
225 <p>
226 Finally you need to define your username and password in
227 <path>/etc/ppp/pap-secrets</path>.
228 </p>
229
230 <pre caption="sample /etc/ppp/pap-secrets">
231 <comment># The * is important</comment>
232 "username" * "password"
233 </pre>
234
235 </body>
236 </section>
237 <section id="apipa">
238 <title>APIPA (Automatic Private IP Addressing)</title>
239 <body>
240
241 <p>
242 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 </p>
246
247 <p>
248 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 </p>
251
252 <p>
253 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
254 </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 For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
273 </p>
274
275 <p>
276 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 </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 need net.eth0 net.eth1 net.eth2
291 }
292 </pre>
293
294 </body>
295 </section>
296 <section>
297 <title>Bridging (802.1d support)</title>
298 <body>
299
300 <p>
301 For bridging support emerge <c>net-misc/bridge-utils</c>.
302 </p>
303
304 <p>
305 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 </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 need net.eth0 net.eth1
328 }
329 </pre>
330
331 <impo>
332 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 </impo>
335
336 </body>
337 </section>
338 <section>
339 <title>MAC Address</title>
340 <body>
341
342 <p>
343 You don't need to emerge anything for changing the MAC address of your
344 interface if you have <c>sys-apps/baselayout-1.11.14</c> or newer and want to
345 change to a specific MAC address. However, if you need to change to a random MAC
346 address or have a baselayout older than the version mentioned above, you have
347 to emerge <c>net-analyzer/macchanger</c> to be able to make use of this feature.
348 </p>
349
350 <pre caption="MAC Address change example">
351 <comment># To set the MAC address of the interface</comment>
352 mac_eth0="00:11:22:33:44:55"
353
354 <comment># To randomize the last 3 bytes only</comment>
355 mac_eth0="random-ending"
356
357 <comment># To randomize between the same physical type of connection (eg fibre,
358 # copper, wireless) , all vendors</comment>
359 mac_eth0="random-samekind"
360
361 <comment># To randomize between any physical type of connection (eg fibre, copper,
362 # wireless) , all vendors</comment>
363 mac_eth0="random-anykind"
364
365 <comment># Full randomization - WARNING: some MAC addresses generated by this may
366 # NOT act as expected</comment>
367 mac_eth0="random-full"
368 </pre>
369
370 </body>
371 </section>
372 <section>
373 <title>Tunnelling</title>
374 <body>
375
376 <p>
377 You don't need to emerge anything for tunnelling as the interface handler can do
378 it for you.
379 </p>
380
381 <pre caption="Tunnelling configuration in /etc/conf.d/net">
382 <comment># For GRE tunnels</comment>
383 iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
384
385 <comment># For IPIP tunnels</comment>
386 iptunnel_vpn0="mode ipip remote 207.170.82.2 ttl 255"
387
388 <comment># To configure the interface</comment>
389 config_vpn0=( "192.168.0.2 peer 192.168.1.1" )
390 </pre>
391
392 </body>
393 </section>
394 <section>
395 <title>VLAN (802.1q support)</title>
396 <body>
397
398 <p>
399 For VLAN support, emerge <c>net-misc/vconfig</c>.
400 </p>
401
402 <p>
403 Virtual LAN is a group of network devices that behave as if they were connected
404 to a single network segment - even though they may not be. VLAN members can only
405 see members of the same VLAN even though they may share the same physical
406 network.
407 </p>
408
409 <pre caption="VLAN configuration in /etc/conf.d/net">
410 <comment># Specify the VLAN numbers for the interface like so</comment>
411 <comment># Please ensure your VLAN IDs are NOT zero-padded</comment>
412 vlans_eth0="1 2"
413
414 <comment># You can also configure the VLAN</comment>
415 <comment># see for vconfig man page for more details</comment>
416 vconfig_eth0=( "set_name_type VLAN_PLUS_VID_NO_PAD" )
417 vconfig_vlan1=( "set_flag 1" "set_egress_map 2 6" )
418
419 <comment># Configure the interface as usual</comment>
420 config_vlan1=( "172.16.3.1 netmask 255.255.254.0" )
421 config_vlan2=( "172.16.2.1 netmask 255.255.254.0" )
422 </pre>
423
424 <impo>
425 For using some VLAN setups, you may need to consult the <uri
426 link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
427 </impo>
428
429 </body>
430 </section>
431
432 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20