/[gentoo]/xml/htdocs/doc/en/handbook/hb-net-modules.xml
Gentoo

Diff of /xml/htdocs/doc/en/handbook/hb-net-modules.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.8 Revision 1.24
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> 2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3 3
4<!-- The content of this document is licensed under the CC-BY-SA license --> 4<!-- The content of this document is licensed under the CC-BY-SA license -->
5<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 5<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 6
7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-modules.xml,v 1.8 2005/09/07 19:00:28 jkt Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-modules.xml,v 1.24 2007/11/02 20:33:55 nightmorph Exp $ -->
8 8
9<sections> 9<sections>
10 10
11<abstract>
12Gentoo provides you flexible networking - here you are told about choosing
13different DHCP clients, setting up bonding, bridging, VLANs and more.
14</abstract>
15
11<version>1.4</version> 16<version>8.3</version>
12<date>2005-09-07</date> 17<date>2007-11-02</date>
13 18
14<section> 19<section>
15<title>Network Modules</title> 20<title>Network Modules</title>
16<body> 21<body>
17 22
18<p> 23<p>
19We now support modular networking scripts, which means we can easily 24We now support modular networking scripts, which means we can easily add support
20add support for new interface types and configuration modules while keeping 25for new interface types and configuration modules while keeping compatibility
21compatibility with existing ones. 26with existing ones.
22</p>
23
24<p> 27</p>
28
29<p>
25Modules load by default if the package they need is installed. If 30Modules load by default if the package they need is installed. If you specify a
26you specify a module here that doesn't have its package installed 31module here that doesn't have its package installed then you get an error
27then you get an error stating which package you need to install. 32stating which package you need to install. Ideally, you only use the modules
28Ideally, you only use the modules setting when you have two or more 33setting when you have two or more packages installed that supply the same
29packages installed that supply the same service and you need to prefer 34service and you need to prefer one over the other.
30one over the other.
31</p> 35</p>
36
37<note>
38All settings discussed here are stored in <path>/etc/conf.d/net</path> unless
39otherwise specified.
40</note>
32 41
33<pre caption="Module preference"> 42<pre caption="Module preference">
34<comment># Prefer iproute2 over ifconfig</comment> 43<comment># Prefer iproute2 over ifconfig</comment>
35modules=( "iproute2" ) 44modules=( "iproute2" )
36 45
49<section> 58<section>
50<title>Interface Handlers</title> 59<title>Interface Handlers</title>
51<body> 60<body>
52 61
53<p> 62<p>
54We provide two interface handlers presently: ifconfig and iproute2. 63We provide two interface handlers presently: <c>ifconfig</c> and
55You need one of these to do any kind of network configuration. 64<c>iproute2</c>. You need one of these to do any kind of network configuration.
56</p>
57
58<p> 65</p>
66
67<p>
59ifconfig is the current Gentoo default and it's included in the system profile. 68<c>ifconfig</c> is the current Gentoo default and it's included in the system
60iproute2 is a more powerful and flexible package, but it's not included by 69profile. <c>iproute2</c> is a more powerful and flexible package, but it's not
61default. 70included by default.
62</p> 71</p>
63 72
64<pre caption="To install iproute2"> 73<pre caption="To install iproute2">
65# <i>emerge sys-apps/iproute2</i> 74# <i>emerge sys-apps/iproute2</i>
66 75
67<comment># To prefer iproute2 over ifconfig if both are installed</comment> 76<comment># To prefer iproute2 over ifconfig if both are installed</comment>
68modules=( "iproute2" ) 77modules=( "iproute2" )
69</pre> 78</pre>
70 79
71<p> 80<p>
72As both ifconfig and iproute2 do very similar things we allow their basic 81As both <c>ifconfig</c> and <c>iproute2</c> do very similar things we allow
73configuration to work with each other. For example both the below code 82their basic configuration to work with each other. For example both the below
74snippets work regardless of which module you are using. 83code snippet work regardless of which module you are using.
75</p> 84</p>
76 85
77<pre caption="ifconfig and iproute2 examples"> 86<pre caption="ifconfig and iproute2 examples">
78config_eth0=( "192.168.0.2/24" ) 87config_eth0=( "192.168.0.2/24" )
79config_eth0=( "192.168.0.2 netmask 255.255.255.0" ) 88config_eth0=( "192.168.0.2 netmask 255.255.255.0" )
92<p> 101<p>
93DHCP is a means of obtaining network information (IP address, DNS servers, 102DHCP is a means of obtaining network information (IP address, DNS servers,
94Gateway, etc) from a DHCP server. This means that if there is a DHCP server 103Gateway, etc) from a DHCP server. This means that if there is a DHCP server
95running on the network, you just have to tell each client to use DHCP and it 104running on the network, you just have to tell each client to use DHCP and it
96sets up the network all by itself. Of course, you will have to configure for 105sets up the network all by itself. Of course, you will have to configure for
97other things like wireless, ppp or other things if required before you can use 106other things like wireless, PPP or other things if required before you can use
98DHCP. 107DHCP.
99</p> 108</p>
100 109
101<p> 110<p>
102DHCP can be provided by dhclient, dhcpcd, pump or udhcpc. Each DHCP module has 111DHCP can be provided by <c>dhclient</c>, <c>dhcpcd</c>, <c>pump</c> or
103its pros and cons - here's a quick run down. 112<c>udhcpc</c>. Each DHCP module has its pros and cons - here's a quick run down.
104</p> 113</p>
105 114
106<table> 115<table>
107<tr> 116<tr>
108 <th>DHCP Module</th> 117 <th>DHCP Module</th>
109 <th>Package</th> 118 <th>Package</th>
110 <th>Pros</th> 119 <th>Pros</th>
111 <th>Cons</th> 120 <th>Cons</th>
112</tr> 121</tr>
113<tr> 122<tr>
114 <ti>dhclient</ti> 123 <ti><c>dhclient</c></ti>
115 <ti>net-misc/dhcp</ti> 124 <ti><c>net-misc/dhcp</c></ti>
116 <ti> 125 <ti>
117 Made by ISC, the same people who make the BIND DNS software. Very 126 Made by ISC, the same people who make the BIND DNS software. Very
118 configurable 127 configurable
119 </ti> 128 </ti>
120 <ti> 129 <ti>
121 Configuration is overly complex, software is quite bloated, cannot get 130 Configuration is overly complex, software is quite bloated, cannot get
122 NTP servers from DHCP, does not send hostname by default 131 NTP servers from DHCP, does not send hostname by default
123 </ti> 132 </ti>
124</tr> 133</tr>
125<tr> 134<tr>
126 <ti>dhcpcd</ti> 135 <ti><c>dhcpcd</c></ti>
127 <ti>net-misc/dhcpcd</ti> 136 <ti><c>net-misc/dhcpcd</c></ti>
128 <ti>
129 Long time Gentoo default, no reliance on outside tools
130 </ti> 137 <ti>
138 Long time Gentoo default, no reliance on outside tools, actively developed
139 by Gentoo
131 <ti> 140 </ti>
132 No longer maintained upstream, can be slow at times, does not daemonize 141 <ti>Can be slow at times, does not yet daemonize when lease is infinite</ti>
133 when lease is infinite
134 </ti>
135</tr> 142</tr>
136<tr> 143<tr>
137 <ti>pump</ti> 144 <ti><c>pump</c></ti>
138 <ti>net-misc/pump</ti> 145 <ti><c>net-misc/pump</c></ti>
139 <ti> 146 <ti>
140 Lightweight, no reliance on outside tools 147 Lightweight, no reliance on outside tools
141 </ti> 148 </ti>
142 <ti> 149 <ti>
143 No longer maintained upstream, unreliable, especially over modems, cannot 150 No longer maintained upstream, unreliable, especially over modems, cannot
144 get NIS servers from DHCP 151 get NIS servers from DHCP
145 </ti> 152 </ti>
146</tr> 153</tr>
147<tr> 154<tr>
148 <ti>udhcpc</ti> 155 <ti><c>udhcpc</c></ti>
149 <ti>net-misc/udhcp</ti> 156 <ti><c>net-misc/udhcp</c></ti>
150 <ti> 157 <ti>
151 Lightweight - smallest dhcp client around, made for embedded systems 158 Lightweight - smallest DHCP client around, made for embedded systems
152 </ti> 159 </ti>
153 <ti> 160 <ti>
154 Unproven - no distro uses it by default, cannot define a timeout beyond 3 161 Unproven - no distro uses it by default, cannot define a timeout beyond 3
155 seconds 162 seconds
156 </ti> 163 </ti>
157</tr> 164</tr>
158</table> 165</table>
159 166
160<p> 167<p>
161If you have more than one DHCP client installed, you need to specify which 168If you have more than one DHCP client installed, you need to specify which one
162one to use - otherwise we default to dhcpcd if available. 169to use - otherwise we default to <c>dhcpcd</c> if available.
163</p>
164
165<p> 170</p>
171
172<p>
166To send specific options to the dhcp module, use module_eth0="..." 173To send specific options to the DHCP module, use <c>module_eth0="..."</c>
167<e>(change module to the DHCP module you're using - ie dhcpcd_eth0)</e> 174<e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
168</p> 175</p>
169 176
170<p> 177<p>
171We try and make DHCP relatively agnostic - as such we support the following 178We try and make DHCP relatively agnostic - as such we support the following
172commands using the dhcp_eth0 variable. The default is not to set any of them 179commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
180them:
173</p> 181</p>
174 182
175<ul> 183<ul>
176 <li>release - releases the IP address for re-use</li> 184 <li><c>release</c> - releases the IP address for re-use</li>
177 <li>nodns - don't overwrite /etc/resolv.conf</li> 185 <li><c>nodns</c> - don't overwrite <path>/etc/resolv.conf</path></li>
178 <li>nontp - don't overwrite /etc/ntp.conf</li> 186 <li><c>nontp</c> - don't overwrite <path>/etc/ntp.conf</path></li>
179 <li>nonis - don't overwrite /etc/yp.conf</li> 187 <li><c>nonis</c> - don't overwrite <path>/etc/yp.conf</path></li>
180</ul> 188</ul>
181 189
182<pre caption="Sample DHCP configuration in /etc/conf.d/net"> 190<pre caption="Sample DHCP configuration in /etc/conf.d/net">
183<comment># Only needed if you have more than one DHCP module installed</comment> 191<comment># Only needed if you have more than one DHCP module installed</comment>
184modules=( "dhcpcd" ) 192modules=( "dhcpcd" )
187dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment> 195dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment>
188dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment> 196dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment>
189</pre> 197</pre>
190 198
191<note> 199<note>
192dhcpcd, udhcpc and pump send the current hostname to the DHCP server by 200<c>dhcpcd</c>, <c>udhcpc</c> and <c>pump</c> send the current hostname to the
193default so you don't need to specify this anymore. 201DHCP server by default so you don't need to specify this anymore.
194</note> 202</note>
195 203
196</body> 204</body>
197</section> 205</section>
198<section> 206<section>
199<title>ADSL Modem</title> 207<title>ADSL with PPPoE/PPPoA</title>
200<body> 208<body>
201 209
202<p> 210<p>
203First we need to install the ADSL software. 211First we need to install the ADSL software.
204</p> 212</p>
205 213
206<pre caption="Install the rp-pppoe package"> 214<pre caption="Install the ppp package">
207# <i>emerge net-dialup/rp-pppoe</i> 215# <i>emerge net-dialup/ppp</i>
208</pre> 216</pre>
209 217
210<warn> 218<note>
211baselayout-1.11.x supports PPPOE only. Hopefully future versions will support 219If you need PPPoA, then make sure to use >=<c>baselayout-1.12.x</c>.
212PPPOA. 220</note>
213</warn>
214 221
215<p>
216Now we need to instruct configure eth0 to be an ADSL interface and enter our
217username.
218</p> 222<p>
219 223Second, create the PPP net script and the net script for the ethernet interface
220<pre caption="Configure eth0 for ADSL"> 224to be used by PPP:
221config_eth0=( "adsl" )
222adsl_user_eth0="username"
223</pre>
224
225<p> 225</p>
226Finally you need to define your username and password in 226
227<path>/etc/ppp/pap-secrets</path> 227<pre caption="Creating the PPP and ethernet scripts">
228# <i>ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0</i>
229# <i>ln -s /etc/init.d/net.lo /etc/init.d/net.eth0</i>
230</pre>
231
228</p> 232<p>
233Be sure to set RC_NET_STRICT_CHECKING="yes" in <path>/etc/conf.d/rc</path>.
234</p>
229 235
236<p>
237Now we need to configure <path>/etc/conf.d/net</path>.
238</p>
239
240<pre caption="A basic PPPoE setup">
241config_eth0=( null ) <comment>(Specify your ethernet interface)</comment>
242config_ppp0=( "ppp" )
243link_ppp0="eth0" <comment>(Specify your ethernet interface)</comment>
244plugins_ppp0=( "pppoe" )
245username_ppp0='user'
246password_ppp0='password'
247pppd_ppp0=(
248 "noauth"
249 "defaultroute"
250 "usepeerdns"
251 "holdoff 3"
252 "child-timeout 60"
253 "lcp-echo-interval 15"
254 "lcp-echo-failure 3"
255 noaccomp noccp nobsdcomp nodeflate nopcomp novj novjccomp
256)
257
258depend_ppp0() {
259 need net.eth0
260}
261</pre>
262
263<p>
264You can also set your password in <path>/etc/ppp/pap-secrets</path>.
265</p>
266
230<pre caption="sample /etc/ppp/pap-secrets"> 267<pre caption="Sample /etc/ppp/pap-secrets">
231<comment># The * is important</comment> 268<comment># The * is important</comment>
232"username" * "password" 269"username" * "password"
233</pre> 270</pre>
234 271
272<p>
273If you use PPPoE with a USB modem you'll need to emerge <c>br2684ctl</c>. Please
274read <path>/usr/portage/net-dialup/speedtouch-usb/files/README</path> for
275information on how to properly configure it.
276</p>
277
278<impo>
279Please carefully read the section on ADSL and PPP in
280<path>/etc/conf.d/net.example</path>. It contains many more detailed
281explanations of all the settings your particular PPP setup will likely need.
282</impo>
283
235</body> 284</body>
236</section> 285</section>
237<section id="apipa"> 286<section id="apipa">
238<title>APIPA (Automatic Private IP Addressing)</title> 287<title>APIPA (Automatic Private IP Addressing)</title>
239<body> 288<body>
240 289
241<p> 290<p>
242APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 291APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 by
243by arping a random address in that range on the interface. If no reply is 292arping a random address in that range on the interface. If no reply is found
244found then we assign that address to the interface. 293then we assign that address to the interface.
245</p>
246
247<p> 294</p>
295
296<p>
248This is only useful for LANs where there is no DHCP server and you don't 297This is only useful for LANs where there is no DHCP server and you don't connect
249connect directly to the internet and all other computers use APIPA. 298directly to the internet and all other computers use APIPA.
250</p>
251
252<p> 299</p>
300
301<p>
253For APIPA support, emerge net-misc/iputils or net-analyzer/arping 302For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
254</p> 303</p>
255 304
256<pre caption="APIPA configuration in /etc/conf.d/net"> 305<pre caption="APIPA configuration in /etc/conf.d/net">
257<comment># Try DHCP first - if that fails then fallback to APIPA</comment> 306<comment># Try DHCP first - if that fails then fallback to APIPA</comment>
258config_eth0=( "dhcp" ) 307config_eth0=( "dhcp" )
267<section> 316<section>
268<title>Bonding</title> 317<title>Bonding</title>
269<body> 318<body>
270 319
271<p> 320<p>
272For link bonding/trunking emerge net-misc/ifenslave 321For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
273</p>
274
275<p> 322</p>
323
324<p>
276Bonding is used to increase network bandwidth. If you have two network 325Bonding is used to increase network bandwidth. If you have two network cards
277cards going to the same network, you can bond them together so your 326going to the same network, you can bond them together so your applications see
278applications see just one interface but they really use both network cards. 327just one interface but they really use both network cards.
279</p> 328</p>
280 329
281<pre caption="bonding configuration in /etc/conf.d/net"> 330<pre caption="bonding configuration in /etc/conf.d/net">
282<comment>To bond interfaces together</comment> 331<comment># To bond interfaces together</comment>
283slaves_bond0="eth0 eth1 eth2" 332slaves_bond0="eth0 eth1 eth2"
284 333
285<comment># You may not want to assign an IP to the bonded interface</comment> 334<comment># You may not want to assign an IP to the bonded interface</comment>
286config_bond0=( "null" ) 335config_bond0=( "null" )
287 336
296<section> 345<section>
297<title>Bridging (802.1d support)</title> 346<title>Bridging (802.1d support)</title>
298<body> 347<body>
299 348
300<p> 349<p>
301For bridging support emerge net-misc/bridge-utils 350For bridging support emerge <c>net-misc/bridge-utils</c>.
302</p>
303
304<p> 351</p>
352
353<p>
305Bridging is used to join networks together. For example, you may have a 354Bridging is used to join networks together. For example, you may have a server
306server that connects to the internet via an ADSL modem and a wireless 355that connects to the internet via an ADSL modem and a wireless access card to
307access card to enable other computers to connect to the internet via the 356enable other computers to connect to the internet via the ADSL modem. You could
308ADSL modem. You could create a bridge to join the two interfaces together. 357create a bridge to join the two interfaces together.
309</p> 358</p>
310 359
311<pre caption="Bridge configuration in /etc/conf.d/net"> 360<pre caption="Bridge configuration in /etc/conf.d/net">
312<comment># Configure the bridge - "man btctl" for more details</comment> 361<comment># Configure the bridge - "man brctl" for more details</comment>
313brctl_br0=( "setfd 0" "sethello 0" "stp off" ) 362brctl_br0=( "setfd 0" "sethello 0" "stp off" )
314 363
315<comment># To add ports to bridge br0</comment> 364<comment># To add ports to bridge br0</comment>
316bridge_br0="eth0 eth1" 365bridge_br0="eth0 eth1"
317 366
327 need net.eth0 net.eth1 376 need net.eth0 net.eth1
328} 377}
329</pre> 378</pre>
330 379
331<impo> 380<impo>
332For using some bridge setups, you may need to consult the 381For using some bridge setups, you may need to consult the <uri
333<uri link="?part=4&amp;chap=2#variable_name">variable name</uri> 382link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
334documentation.
335</impo> 383</impo>
336 384
337</body> 385</body>
338</section> 386</section>
339<section> 387<section>
340<title>MAC Address</title> 388<title>MAC Address</title>
341<body> 389<body>
342 390
343<p> 391<p>
344You don't need to emerge anything for changing the MAC address of your 392You don't need to emerge anything for changing the MAC address of your
345interface if you change to a specific address. However, if you need to 393interface if you have <c>sys-apps/baselayout-1.11.14</c> or newer and want to
346change to a random address or a random address of a given type then you 394change to a specific MAC address. However, if you need to change to a random MAC
347need to emerge net-analyzer/macchanger. 395address or have a baselayout older than the version mentioned above, you have
396to emerge <c>net-analyzer/macchanger</c> to be able to make use of this feature.
348</p> 397</p>
349 398
350<pre caption="MAC Address change example"> 399<pre caption="MAC Address change example">
351<comment># To set the MAC address of the interface</comment> 400<comment># To set the MAC address of the interface</comment>
352mac_eth0="00:11:22:33:44:55" 401mac_eth0="00:11:22:33:44:55"
353 402
354<comment># To randomize the last 3 bytes only</comment> 403<comment># To randomize the last 3 bytes only</comment>
355mac_eth0="random-ending" 404mac_eth0="random-ending"
356 405
357<comment># To randomize between the same physical type of connection (eg fibre, 406<comment># To randomize between the same physical type of connection (e.g. fibre,
358# copper, wireless) , all vendors</comment> 407# copper, wireless) , all vendors</comment>
359mac_eth0="random-samekind" 408mac_eth0="random-samekind"
360 409
361<comment># To randomize between any physical type of connection (eg fibre, copper, 410<comment># To randomize between any physical type of connection (e.g. fibre, copper,
362# wireless) , all vendors</comment> 411# wireless) , all vendors</comment>
363mac_eth0="random-anykind" 412mac_eth0="random-anykind"
364 413
365<comment># Full randomization - WARNING: some MAC addresses generated by this may 414<comment># Full randomization - WARNING: some MAC addresses generated by this may
366# NOT act as expected</comment> 415# NOT act as expected</comment>
372<section> 421<section>
373<title>Tunnelling</title> 422<title>Tunnelling</title>
374<body> 423<body>
375 424
376<p> 425<p>
377You don't need to emerge anything for tunnelling as the interface handler 426You don't need to emerge anything for tunnelling as the interface handler can do
378can do it for you. 427it for you.
379</p> 428</p>
380 429
381<pre caption="Tunnelling configuration in /etc/conf.d/net"> 430<pre caption="Tunnelling configuration in /etc/conf.d/net">
382<comment># For GRE tunnels</comment> 431<comment># For GRE tunnels</comment>
383iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255" 432iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
394<section> 443<section>
395<title>VLAN (802.1q support)</title> 444<title>VLAN (802.1q support)</title>
396<body> 445<body>
397 446
398<p> 447<p>
399For VLAN support, emerge net-misc/vconfig 448For VLAN support, emerge <c>net-misc/vconfig</c>.
400</p>
401
402<p> 449</p>
450
451<p>
403Virtual LAN is a group of network devices that behave as if they were 452Virtual LAN is a group of network devices that behave as if they were connected
404connected to a single network segment - even though they may not be. 453to a single network segment - even though they may not be. VLAN members can only
405VLAN members can only see members of the same VLAN even though they may 454see members of the same VLAN even though they may share the same physical
406share the same physical network. 455network.
407</p> 456</p>
408 457
409<pre caption="VLAN configuration in /etc/conf.d/net"> 458<pre caption="VLAN configuration in /etc/conf.d/net">
410<comment># Specify the VLAN numbers for the interface like so</comment> 459<comment># Specify the VLAN numbers for the interface like so</comment>
411<comment># Please ensure your VLAN IDs are NOT zero-padded</comment> 460<comment># Please ensure your VLAN IDs are NOT zero-padded</comment>
420config_vlan1=( "172.16.3.1 netmask 255.255.254.0" ) 469config_vlan1=( "172.16.3.1 netmask 255.255.254.0" )
421config_vlan2=( "172.16.2.1 netmask 255.255.254.0" ) 470config_vlan2=( "172.16.2.1 netmask 255.255.254.0" )
422</pre> 471</pre>
423 472
424<impo> 473<impo>
425For using some VLAN setups, you may need to consult the 474For using some VLAN setups, you may need to consult the <uri
426<uri link="?part=4&amp;chap=2#variable_name">variable name</uri> 475link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
427documentation.
428</impo> 476</impo>
429 477
430</body> 478</body>
431</section> 479</section>
432 480

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.24

  ViewVC Help
Powered by ViewVC 1.1.20