/[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.32 - (show annotations) (download) (as text)
Thu Sep 25 08:21:34 2014 UTC (3 months ago) by jkt
Branch: MAIN
CVS Tags: HEAD
Changes since 1.31: +16 -6 lines
File MIME type: application/xml
Add an example on how to configure bonding, and clarify what it actually is

Thanks to prometheanfire for reminding us on IRC.

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.31 2014/04/12 06:24:48 swift 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>15</version>
17 <date>2014-09-25</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 ifconfig over iproute2</comment>
44 modules="ifconfig"
45
46 <comment># You can also specify other modules for an interface
47 # In this case we prefer pump over dhcpcd</comment>
48 modules_eth0="pump"
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 installed by default (the <c>net-tools</c> package is part of
69 the system profile). <c>iproute2</c> is a more powerful and flexible package,
70 but it's not included by default.
71 </p>
72
73 <pre caption="To install iproute2">
74 # <i>emerge sys-apps/iproute2</i>
75
76 <comment># To prefer ifconfig over iproute2 if both are installed as openrc prefers
77 # to use iproute2 then</comment>
78 modules="ifconfig"
79 </pre>
80
81 <p>
82 As both <c>ifconfig</c> and <c>iproute2</c> do very similar things we allow
83 their basic configuration to work with each other. For example both the below
84 code snippet work regardless of which module you are using.
85 </p>
86
87 <pre caption="ifconfig and iproute2 examples">
88 config_eth0="192.168.0.2/24"
89 config_eth0="192.168.0.2 netmask 255.255.255.0"
90
91 <comment># We can also specify broadcast</comment>
92 config_eth0="192.168.0.2/24 brd 192.168.0.255"
93 config_eth0="192.168.0.2 netmask 255.255.255.0 broadcast 192.168.0.255"
94 </pre>
95
96 </body>
97 </section>
98 <section id="dhcp">
99 <title>DHCP</title>
100 <body>
101
102 <p>
103 DHCP is a means of obtaining network information (IP address, DNS servers,
104 Gateway, etc) from a DHCP server. This means that if there is a DHCP server
105 running on the network, you just have to tell each client to use DHCP and it
106 sets up the network all by itself. Of course, you will have to configure for
107 other things like wireless, PPP or other things if required before you can use
108 DHCP.
109 </p>
110
111 <p>
112 DHCP can be provided by <c>dhclient</c>, <c>dhcpcd</c>, or <c>pump</c>. Each
113 DHCP module has its pros and cons - here's a quick run down.
114 </p>
115
116 <table>
117 <tr>
118 <th>DHCP Module</th>
119 <th>Package</th>
120 <th>Pros</th>
121 <th>Cons</th>
122 </tr>
123 <tr>
124 <ti><c>dhclient</c></ti>
125 <ti><c>net-misc/dhcp</c></ti>
126 <ti>
127 Made by ISC, the same people who make the BIND DNS software. Very
128 configurable
129 </ti>
130 <ti>
131 Configuration is overly complex, software is quite bloated, cannot get
132 NTP servers from DHCP, does not send hostname by default
133 </ti>
134 </tr>
135 <tr>
136 <ti><c>dhcpcd</c></ti>
137 <ti><c>net-misc/dhcpcd</c></ti>
138 <ti>
139 Long time Gentoo default, no reliance on outside tools, actively developed
140 by Gentoo
141 </ti>
142 <ti>Can be slow at times, does not yet daemonize when lease is infinite</ti>
143 </tr>
144 <tr>
145 <ti><c>pump</c></ti>
146 <ti><c>net-misc/pump</c></ti>
147 <ti>
148 Lightweight, no reliance on outside tools
149 </ti>
150 <ti>
151 No longer maintained upstream, unreliable, especially over modems, cannot
152 get NIS servers from DHCP
153 </ti>
154 </tr>
155 </table>
156
157 <p>
158 If you have more than one DHCP client installed, you need to specify which one
159 to use - otherwise we default to <c>dhcpcd</c> if available.
160 </p>
161
162 <p>
163 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
164 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
165 </p>
166
167 <p>
168 We try and make DHCP relatively agnostic - as such we support the following
169 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
170 them:
171 </p>
172
173 <ul>
174 <li><c>release</c> - releases the IP address for re-use</li>
175 <li><c>nodns</c> - don't overwrite <path>/etc/resolv.conf</path></li>
176 <li><c>nontp</c> - don't overwrite <path>/etc/ntp.conf</path></li>
177 <li><c>nonis</c> - don't overwrite <path>/etc/yp.conf</path></li>
178 </ul>
179
180 <pre caption="Sample DHCP configuration in /etc/conf.d/net">
181 <comment># Only needed if you have more than one DHCP module installed</comment>
182 modules="dhcpcd"
183
184 config_eth0="dhcp"
185 dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment>
186 dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment>
187 </pre>
188
189 <note>
190 <c>dhcpcd</c> and <c>pump</c> send the current hostname to the
191 DHCP server by default so you don't need to specify this anymore.
192 </note>
193
194 </body>
195 </section>
196 <section>
197 <title>ADSL with PPPoE/PPPoA</title>
198 <body>
199
200 <p>
201 First we need to install the ADSL software.
202 </p>
203
204 <pre caption="Install the ppp package">
205 # <i>emerge net-dialup/ppp</i>
206 </pre>
207
208 <p>
209 Second, create the PPP net script and the net script for the ethernet interface
210 to be used by PPP:
211 </p>
212
213 <pre caption="Creating the PPP and ethernet scripts">
214 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0</i>
215 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.eth0</i>
216 </pre>
217
218 <p>
219 Be sure to set <c>rc_depend_strict</c> to "YES" in <path>/etc/rc.conf</path>.
220 </p>
221
222 <p>
223 Now we need to configure <path>/etc/conf.d/net</path>.
224 </p>
225
226 <pre caption="A basic PPPoE setup">
227 config_eth0=null <comment>(Specify your ethernet interface)</comment>
228 config_ppp0="ppp"
229 link_ppp0="eth0" <comment>(Specify your ethernet interface)</comment>
230 plugins_ppp0="pppoe"
231 username_ppp0='user'
232 password_ppp0='password'
233 pppd_ppp0="
234 noauth
235 defaultroute
236 usepeerdns
237 holdoff 3
238 child-timeout 60
239 lcp-echo-interval 15
240 lcp-echo-failure 3
241 noaccomp noccp nobsdcomp nodeflate nopcomp novj novjccomp"
242
243 rc_need_ppp0="net.eth0"
244 </pre>
245
246 <p>
247 You can also set your password in <path>/etc/ppp/pap-secrets</path>.
248 </p>
249
250 <pre caption="Sample /etc/ppp/pap-secrets">
251 <comment># The * is important</comment>
252 "username" * "password"
253 </pre>
254
255 <p>
256 If you use PPPoE with a USB modem you'll need to emerge <c>br2684ctl</c>. Please
257 read <path>/usr/portage/net-dialup/speedtouch-usb/files/README</path> for
258 information on how to properly configure it.
259 </p>
260
261 <impo>
262 Please carefully read the section on ADSL and PPP in
263 <path>/usr/share/doc/netifrc-*/net.example.bz2</path>. It contains many
264 more detailed explanations of all the settings your particular PPP setup will
265 likely need.
266 </impo>
267
268 </body>
269 </section>
270 <section id="apipa">
271 <title>APIPA (Automatic Private IP Addressing)</title>
272 <body>
273
274 <p>
275 APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 by
276 arping a random address in that range on the interface. If no reply is found
277 then we assign that address to the interface.
278 </p>
279
280 <p>
281 This is only useful for LANs where there is no DHCP server and you don't connect
282 directly to the internet and all other computers use APIPA.
283 </p>
284
285 <p>
286 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
287 </p>
288
289 <pre caption="APIPA configuration in /etc/conf.d/net">
290 <comment># Try DHCP first - if that fails then fallback to APIPA</comment>
291 config_eth0="dhcp"
292 fallback_eth0="apipa"
293
294 <comment># Just use APIPA</comment>
295 config_eth0="apipa"
296 </pre>
297
298 </body>
299 </section>
300 <section>
301 <title>Bonding</title>
302 <body>
303
304 <p>
305 For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
306 </p>
307
308 <p>
309 Bonding is used to increase network bandwidth or to improve resiliency in face
310 of hardware failures. If you have two network cards going to the same network,
311 you can bond them together so your applications see just one interface but they
312 really use both network cards.
313 </p>
314
315 <p>
316 There are many ways to configure bonding. Some of them, such as the 802.3ad LACP
317 mode, require support and additional configuration of the network switch. For a
318 reference of the individual options, please refer to your copy of
319 <path>/usr/src/linux/Documentation/networking/bonding.txt</path>.
320 </p>
321
322 <p>
323 First, clear the configuration of the participating interfaces:
324 </p>
325
326 <pre caption="Clearing interface configuration in /etc/conf.d/net">
327 config_eth0="null"
328 config_eth1="null"
329 config_eth2="null"
330 </pre>
331
332 <p>
333 Next, define the bonding between the interfaces:
334 </p>
335
336 <pre caption="Define the bonding">
337 slaves_bond0="eth0 eth1 eth2"
338 config_bond0="192.168.100.4/24"
339 <comment># Pick a correct mode and additional configuration options which suit your needs</comment>
340 mode_bond0="balance-alb"
341 </pre>
342
343 <p>
344 Remove the <path>net.eth*</path> services from the runlevels, create a
345 <path>net.bond0</path> one and add that one to the correct runlevel.
346 </p>
347
348 </body>
349 </section>
350 <section>
351 <title>Bridging (802.1d support)</title>
352 <body>
353
354 <p>
355 For bridging support emerge <c>net-misc/bridge-utils</c>.
356 </p>
357
358 <p>
359 Bridging is used to join networks together. For example, you may have a server
360 that connects to the internet via an ADSL modem and a wireless access card to
361 enable other computers to connect to the internet via the ADSL modem. You could
362 create a bridge to join the two interfaces together.
363 </p>
364
365 <pre caption="Bridge configuration in /etc/conf.d/net">
366 <comment># Configure the bridge - "man brctl" for more details</comment>
367 brctl_br0="setfd 0
368 sethello 2
369 stp on"
370
371 <comment># To add ports to bridge br0</comment>
372 bridge_br0="eth0 eth1"
373
374 <comment># You need to configure the ports to null values so dhcp does not get started</comment>
375 config_eth0="null"
376 config_eth1="null"
377
378 <comment># Finally give the bridge an address - you could use DHCP as well</comment>
379 config_br0="192.168.0.1/24"
380
381 <comment># Depend on eth0 and eth1 as they may require extra configuration</comment>
382 rc_need_br0="net.eth0 net.eth1"
383 </pre>
384
385 <impo>
386 For using some bridge setups, you may need to consult the <uri
387 link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
388 </impo>
389
390 </body>
391 </section>
392 <section>
393 <title>MAC Address</title>
394 <body>
395
396 <p>
397 If you need to, you can change the MAC address of your interfaces through
398 the network configuration file too.
399 </p>
400
401 <pre caption="MAC Address change example">
402 <comment># To set the MAC address of the interface</comment>
403 mac_eth0="00:11:22:33:44:55"
404
405 <comment># To randomize the last 3 bytes only</comment>
406 mac_eth0="random-ending"
407
408 <comment># To randomize between the same physical type of connection (e.g. fibre,
409 # copper, wireless) , all vendors</comment>
410 mac_eth0="random-samekind"
411
412 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
413 # wireless) , all vendors</comment>
414 mac_eth0="random-anykind"
415
416 <comment># Full randomization - WARNING: some MAC addresses generated by this may
417 # NOT act as expected</comment>
418 mac_eth0="random-full"
419 </pre>
420
421 </body>
422 </section>
423 <section>
424 <title>Tunnelling</title>
425 <body>
426
427 <p>
428 You don't need to emerge anything for tunnelling as the interface handler can do
429 it for you.
430 </p>
431
432 <pre caption="Tunnelling configuration in /etc/conf.d/net">
433 <comment># For GRE tunnels</comment>
434 iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
435
436 <comment># For IPIP tunnels</comment>
437 iptunnel_vpn0="mode ipip remote 207.170.82.2 ttl 255"
438
439 <comment># To configure the interface</comment>
440 config_vpn0="192.168.0.2 peer 192.168.1.1"
441 </pre>
442
443 </body>
444 </section>
445 <section>
446 <title>VLAN (802.1q support)</title>
447 <body>
448
449 <p>
450 For VLAN support, make sure that <c>sys-apps/iproute2</c> is installed and ensure
451 that iproute2 is used as configuration module rather than ifconfig.
452 </p>
453
454 <p>
455 Virtual LAN is a group of network devices that behave as if they were connected
456 to a single network segment - even though they may not be. VLAN members can only
457 see members of the same VLAN even though they may share the same physical
458 network.
459 </p>
460
461 <p>
462 To configure VLANs, first specify the VLAN numbers in
463 <path>/etc/conf.d/net</path> like so:
464 </p>
465
466 <pre caption="Specifying VLAN numbers">
467 vlans_eth0="1 2"
468 </pre>
469
470 <p>
471 Next, configure the interface for each VLAN:
472 </p>
473
474 <pre caption="Interface configuration for each VLAN">
475 config_eth0_1="172.16.3.1 netmask 255.255.254.0"
476 routes_eth0_1="default via 172.16.3.254"
477
478 config_eth0_2="172.16.2.1 netmask 255.255.254.0"
479 routes_eth0_2="default via 172.16.2.254"
480 </pre>
481
482 <p>
483 VLAN-specific configurations are handled by <c>vconfig</c> like so:
484 </p>
485
486 <pre caption="Configuring the VLANs">
487 vlan1_name="vlan1"
488 vlan1_ingress="2:6 3:5"
489 eth0_vlan1_egress="1:2"
490 </pre>
491
492 <impo>
493 For using some VLAN setups, you may need to consult the <uri
494 link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
495 </impo>
496
497 </body>
498 </section>
499
500 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20