/[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.11
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.11 2006/01/03 07:32:56 rane Exp $ -->
8 8
9<sections> 9<sections>
10 10
11<version>1.4</version> 11<version>1.6</version>
12<date>2005-09-07</date> 12<date>2006-01-03</date>
13 13
14<section> 14<section>
15<title>Network Modules</title> 15<title>Network Modules</title>
16<body> 16<body>
17 17
18<p> 18<p>
19We now support modular networking scripts, which means we can easily 19We now support modular networking scripts, which means we can easily add support
20add support for new interface types and configuration modules while keeping 20for new interface types and configuration modules while keeping compatibility
21compatibility with existing ones. 21with existing ones.
22</p>
23
24<p> 22</p>
23
24<p>
25Modules load by default if the package they need is installed. If 25Modules 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 26module 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. 27stating 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 28setting when you have two or more packages installed that supply the same
29packages installed that supply the same service and you need to prefer 29service and you need to prefer one over the other.
30one over the other.
31</p> 30</p>
32 31
33<pre caption="Module preference"> 32<pre caption="Module preference">
34<comment># Prefer iproute2 over ifconfig</comment> 33<comment># Prefer iproute2 over ifconfig</comment>
35modules=( "iproute2" ) 34modules=( "iproute2" )
49<section> 48<section>
50<title>Interface Handlers</title> 49<title>Interface Handlers</title>
51<body> 50<body>
52 51
53<p> 52<p>
54We provide two interface handlers presently: ifconfig and iproute2. 53We provide two interface handlers presently: <c>ifconfig</c> and
55You need one of these to do any kind of network configuration. 54<c>iproute2</c>. You need one of these to do any kind of network configuration.
56</p>
57
58<p> 55</p>
56
57<p>
59ifconfig is the current Gentoo default and it's included in the system profile. 58<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 59profile. <c>iproute2</c> is a more powerful and flexible package, but it's not
61default. 60included by default.
62</p> 61</p>
63 62
64<pre caption="To install iproute2"> 63<pre caption="To install iproute2">
65# <i>emerge sys-apps/iproute2</i> 64# <i>emerge sys-apps/iproute2</i>
66 65
67<comment># To prefer iproute2 over ifconfig if both are installed</comment> 66<comment># To prefer iproute2 over ifconfig if both are installed</comment>
68modules=( "iproute2" ) 67modules=( "iproute2" )
69</pre> 68</pre>
70 69
71<p> 70<p>
72As both ifconfig and iproute2 do very similar things we allow their basic 71As 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 72their basic configuration to work with each other. For example both the below
74snippets work regardless of which module you are using. 73code snippet work regardless of which module you are using.
75</p> 74</p>
76 75
77<pre caption="ifconfig and iproute2 examples"> 76<pre caption="ifconfig and iproute2 examples">
78config_eth0=( "192.168.0.2/24" ) 77config_eth0=( "192.168.0.2/24" )
79config_eth0=( "192.168.0.2 netmask 255.255.255.0" ) 78config_eth0=( "192.168.0.2 netmask 255.255.255.0" )
92<p> 91<p>
93DHCP is a means of obtaining network information (IP address, DNS servers, 92DHCP 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 93Gateway, 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 94running 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 95sets 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 96other things like wireless, PPP or other things if required before you can use
98DHCP. 97DHCP.
99</p> 98</p>
100 99
101<p> 100<p>
102DHCP can be provided by dhclient, dhcpcd, pump or udhcpc. Each DHCP module has 101DHCP can be provided by <c>dhclient</c>, <c>dhcpcd</c>, <c>pump</c> or
103its pros and cons - here's a quick run down. 102<c>udhcpc</c>. Each DHCP module has its pros and cons - here's a quick run down.
104</p> 103</p>
105 104
106<table> 105<table>
107<tr> 106<tr>
108 <th>DHCP Module</th> 107 <th>DHCP Module</th>
109 <th>Package</th> 108 <th>Package</th>
110 <th>Pros</th> 109 <th>Pros</th>
111 <th>Cons</th> 110 <th>Cons</th>
112</tr> 111</tr>
113<tr> 112<tr>
114 <ti>dhclient</ti> 113 <ti><c>dhclient</c></ti>
115 <ti>net-misc/dhcp</ti> 114 <ti><c>net-misc/dhcp</c></ti>
116 <ti> 115 <ti>
117 Made by ISC, the same people who make the BIND DNS software. Very 116 Made by ISC, the same people who make the BIND DNS software. Very
118 configurable 117 configurable
119 </ti> 118 </ti>
120 <ti> 119 <ti>
121 Configuration is overly complex, software is quite bloated, cannot get 120 Configuration is overly complex, software is quite bloated, cannot get
122 NTP servers from DHCP, does not send hostname by default 121 NTP servers from DHCP, does not send hostname by default
123 </ti> 122 </ti>
124</tr> 123</tr>
125<tr> 124<tr>
126 <ti>dhcpcd</ti> 125 <ti><c>dhcpcd</c></ti>
127 <ti>net-misc/dhcpcd</ti> 126 <ti><c>net-misc/dhcpcd</c></ti>
128 <ti> 127 <ti>
129 Long time Gentoo default, no reliance on outside tools 128 Long time Gentoo default, no reliance on outside tools
130 </ti> 129 </ti>
131 <ti> 130 <ti>
132 No longer maintained upstream, can be slow at times, does not daemonize 131 No longer maintained upstream, can be slow at times, does not daemonize
133 when lease is infinite 132 when lease is infinite
134 </ti> 133 </ti>
135</tr> 134</tr>
136<tr> 135<tr>
137 <ti>pump</ti> 136 <ti><c>pump</c></ti>
138 <ti>net-misc/pump</ti> 137 <ti><c>net-misc/pump</c></ti>
139 <ti> 138 <ti>
140 Lightweight, no reliance on outside tools 139 Lightweight, no reliance on outside tools
141 </ti> 140 </ti>
142 <ti> 141 <ti>
143 No longer maintained upstream, unreliable, especially over modems, cannot 142 No longer maintained upstream, unreliable, especially over modems, cannot
144 get NIS servers from DHCP 143 get NIS servers from DHCP
145 </ti> 144 </ti>
146</tr> 145</tr>
147<tr> 146<tr>
148 <ti>udhcpc</ti> 147 <ti><c>udhcpc</c></ti>
149 <ti>net-misc/udhcp</ti> 148 <ti><c>net-misc/udhcp</c></ti>
150 <ti> 149 <ti>
151 Lightweight - smallest dhcp client around, made for embedded systems 150 Lightweight - smallest DHCP client around, made for embedded systems
152 </ti> 151 </ti>
153 <ti> 152 <ti>
154 Unproven - no distro uses it by default, cannot define a timeout beyond 3 153 Unproven - no distro uses it by default, cannot define a timeout beyond 3
155 seconds 154 seconds
156 </ti> 155 </ti>
157</tr> 156</tr>
158</table> 157</table>
159 158
160<p> 159<p>
161If you have more than one DHCP client installed, you need to specify which 160If you have more than one DHCP client installed, you need to specify which one
162one to use - otherwise we default to dhcpcd if available. 161to use - otherwise we default to <c>dhcpcd</c> if available.
163</p>
164
165<p> 162</p>
163
164<p>
166To send specific options to the dhcp module, use module_eth0="..." 165To 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> 166<e>(change module to the DHCP module you're using - ie <c>dhcpcd_eth0</c>)</e>
168</p> 167</p>
169 168
170<p> 169<p>
171We try and make DHCP relatively agnostic - as such we support the following 170We 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 171commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
172them:
173</p> 173</p>
174 174
175<ul> 175<ul>
176 <li>release - releases the IP address for re-use</li> 176 <li><c>release</c> - releases the IP address for re-use</li>
177 <li>nodns - don't overwrite /etc/resolv.conf</li> 177 <li><c>nodns</c> - don't overwrite <path>/etc/resolv.conf</path></li>
178 <li>nontp - don't overwrite /etc/ntp.conf</li> 178 <li><c>nontp</c> - don't overwrite <path>/etc/ntp.conf</path></li>
179 <li>nonis - don't overwrite /etc/yp.conf</li> 179 <li><c>nonis</c> - don't overwrite <path>/etc/yp.conf</path></li>
180</ul> 180</ul>
181 181
182<pre caption="Sample DHCP configuration in /etc/conf.d/net"> 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> 183<comment># Only needed if you have more than one DHCP module installed</comment>
184modules=( "dhcpcd" ) 184modules=( "dhcpcd" )
187dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment> 187dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment>
188dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment> 188dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment>
189</pre> 189</pre>
190 190
191<note> 191<note>
192dhcpcd, udhcpc and pump send the current hostname to the DHCP server by 192<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. 193DHCP server by default so you don't need to specify this anymore.
194</note> 194</note>
195 195
196</body> 196</body>
197</section> 197</section>
198<section> 198<section>
206<pre caption="Install the rp-pppoe package"> 206<pre caption="Install the rp-pppoe package">
207# <i>emerge net-dialup/rp-pppoe</i> 207# <i>emerge net-dialup/rp-pppoe</i>
208</pre> 208</pre>
209 209
210<warn> 210<warn>
211baselayout-1.11.x supports PPPOE only. Hopefully future versions will support 211<c>baselayout-1.11.x</c> supports PPPoE only. Hopefully future versions will
212PPPOA. 212support PPPoA.
213</warn> 213</warn>
214 214
215<p> 215<p>
216Now we need to instruct configure eth0 to be an ADSL interface and enter our 216Now we need to instruct configure <c>eth0</c> to be an ADSL interface and enter
217username. 217our username.
218</p> 218</p>
219 219
220<pre caption="Configure eth0 for ADSL"> 220<pre caption="Configure eth0 for ADSL">
221config_eth0=( "adsl" ) 221config_eth0=( "adsl" )
222adsl_user_eth0="username" 222adsl_user_eth0="username"
223</pre> 223</pre>
224 224
225<p> 225<p>
226Finally you need to define your username and password in 226Finally you need to define your username and password in
227<path>/etc/ppp/pap-secrets</path> 227<path>/etc/ppp/pap-secrets</path>.
228</p> 228</p>
229 229
230<pre caption="sample /etc/ppp/pap-secrets"> 230<pre caption="sample /etc/ppp/pap-secrets">
231<comment># The * is important</comment> 231<comment># The * is important</comment>
232"username" * "password" 232"username" * "password"
237<section id="apipa"> 237<section id="apipa">
238<title>APIPA (Automatic Private IP Addressing)</title> 238<title>APIPA (Automatic Private IP Addressing)</title>
239<body> 239<body>
240 240
241<p> 241<p>
242APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 242APIPA 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 243arping a random address in that range on the interface. If no reply is found
244found then we assign that address to the interface. 244then we assign that address to the interface.
245</p>
246
247<p> 245</p>
246
247<p>
248This is only useful for LANs where there is no DHCP server and you don't 248This 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. 249directly to the internet and all other computers use APIPA.
250</p>
251
252<p> 250</p>
251
252<p>
253For APIPA support, emerge net-misc/iputils or net-analyzer/arping 253For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
254</p> 254</p>
255 255
256<pre caption="APIPA configuration in /etc/conf.d/net"> 256<pre caption="APIPA configuration in /etc/conf.d/net">
257<comment># Try DHCP first - if that fails then fallback to APIPA</comment> 257<comment># Try DHCP first - if that fails then fallback to APIPA</comment>
258config_eth0=( "dhcp" ) 258config_eth0=( "dhcp" )
267<section> 267<section>
268<title>Bonding</title> 268<title>Bonding</title>
269<body> 269<body>
270 270
271<p> 271<p>
272For link bonding/trunking emerge net-misc/ifenslave 272For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
273</p>
274
275<p> 273</p>
274
275<p>
276Bonding is used to increase network bandwidth. If you have two network 276Bonding 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 277going 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. 278just one interface but they really use both network cards.
279</p> 279</p>
280 280
281<pre caption="bonding configuration in /etc/conf.d/net"> 281<pre caption="bonding configuration in /etc/conf.d/net">
282<comment>To bond interfaces together</comment> 282<comment>To bond interfaces together</comment>
283slaves_bond0="eth0 eth1 eth2" 283slaves_bond0="eth0 eth1 eth2"
296<section> 296<section>
297<title>Bridging (802.1d support)</title> 297<title>Bridging (802.1d support)</title>
298<body> 298<body>
299 299
300<p> 300<p>
301For bridging support emerge net-misc/bridge-utils 301For bridging support emerge <c>net-misc/bridge-utils</c>.
302</p>
303
304<p> 302</p>
303
304<p>
305Bridging is used to join networks together. For example, you may have a 305Bridging 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 306that 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 307enable 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. 308create a bridge to join the two interfaces together.
309</p> 309</p>
310 310
311<pre caption="Bridge configuration in /etc/conf.d/net"> 311<pre caption="Bridge configuration in /etc/conf.d/net">
312<comment># Configure the bridge - "man btctl" for more details</comment> 312<comment># Configure the bridge - "man btctl" for more details</comment>
313brctl_br0=( "setfd 0" "sethello 0" "stp off" ) 313brctl_br0=( "setfd 0" "sethello 0" "stp off" )
327 need net.eth0 net.eth1 327 need net.eth0 net.eth1
328} 328}
329</pre> 329</pre>
330 330
331<impo> 331<impo>
332For using some bridge setups, you may need to consult the 332For using some bridge setups, you may need to consult the <uri
333<uri link="?part=4&amp;chap=2#variable_name">variable name</uri> 333link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
334documentation.
335</impo> 334</impo>
336 335
337</body> 336</body>
338</section> 337</section>
339<section> 338<section>
340<title>MAC Address</title> 339<title>MAC Address</title>
341<body> 340<body>
342 341
343<p> 342<p>
344You don't need to emerge anything for changing the MAC address of your 343You 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 344interface 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 345change to a specific address. However, if you need to change to a random
346address, a random address of a given type or have an older baselayout, you have
347need to emerge net-analyzer/macchanger. 347to emerge <c>net-analyzer/macchanger</c>.
348</p> 348</p>
349 349
350<pre caption="MAC Address change example"> 350<pre caption="MAC Address change example">
351<comment># To set the MAC address of the interface</comment> 351<comment># To set the MAC address of the interface</comment>
352mac_eth0="00:11:22:33:44:55" 352mac_eth0="00:11:22:33:44:55"
372<section> 372<section>
373<title>Tunnelling</title> 373<title>Tunnelling</title>
374<body> 374<body>
375 375
376<p> 376<p>
377You don't need to emerge anything for tunnelling as the interface handler 377You don't need to emerge anything for tunnelling as the interface handler can do
378can do it for you. 378it for you.
379</p> 379</p>
380 380
381<pre caption="Tunnelling configuration in /etc/conf.d/net"> 381<pre caption="Tunnelling configuration in /etc/conf.d/net">
382<comment># For GRE tunnels</comment> 382<comment># For GRE tunnels</comment>
383iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255" 383iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
394<section> 394<section>
395<title>VLAN (802.1q support)</title> 395<title>VLAN (802.1q support)</title>
396<body> 396<body>
397 397
398<p> 398<p>
399For VLAN support, emerge net-misc/vconfig 399For VLAN support, emerge <c>net-misc/vconfig</c>.
400</p>
401
402<p> 400</p>
401
402<p>
403Virtual LAN is a group of network devices that behave as if they were 403Virtual 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. 404to 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 405see members of the same VLAN even though they may share the same physical
406share the same physical network. 406network.
407</p> 407</p>
408 408
409<pre caption="VLAN configuration in /etc/conf.d/net"> 409<pre caption="VLAN configuration in /etc/conf.d/net">
410<comment># Specify the VLAN numbers for the interface like so</comment> 410<comment># Specify the VLAN numbers for the interface like so</comment>
411<comment># Please ensure your VLAN IDs are NOT zero-padded</comment> 411<comment># Please ensure your VLAN IDs are NOT zero-padded</comment>
420config_vlan1=( "172.16.3.1 netmask 255.255.254.0" ) 420config_vlan1=( "172.16.3.1 netmask 255.255.254.0" )
421config_vlan2=( "172.16.2.1 netmask 255.255.254.0" ) 421config_vlan2=( "172.16.2.1 netmask 255.255.254.0" )
422</pre> 422</pre>
423 423
424<impo> 424<impo>
425For using some VLAN setups, you may need to consult the 425For using some VLAN setups, you may need to consult the <uri
426<uri link="?part=4&amp;chap=2#variable_name">variable name</uri> 426link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
427documentation.
428</impo> 427</impo>
429 428
430</body> 429</body>
431</section> 430</section>
432 431

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

  ViewVC Help
Powered by ViewVC 1.1.20