/[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 - (hide annotations) (download) (as text)
Thu Sep 25 08:21:34 2014 UTC (8 weeks, 3 days 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 swift 1.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 swift 1.2 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.1
7 jkt 1.32 <!-- $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 neysx 1.5
9 swift 1.1 <sections>
10    
11 neysx 1.19 <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 jkt 1.32 <version>15</version>
17     <date>2014-09-25</date>
18 swift 1.1
19     <section>
20     <title>Network Modules</title>
21     <body>
22    
23     <p>
24 jkt 1.9 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 swift 1.1 </p>
28    
29     <p>
30 jkt 1.9 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 swift 1.1 </p>
36    
37 vapier 1.15 <note>
38     All settings discussed here are stored in <path>/etc/conf.d/net</path> unless
39     otherwise specified.
40     </note>
41    
42 swift 1.1 <pre caption="Module preference">
43 swift 1.27 <comment># Prefer ifconfig over iproute2</comment>
44     modules="ifconfig"
45 swift 1.1
46     <comment># You can also specify other modules for an interface
47 nightmorph 1.25 # In this case we prefer pump over dhcpcd</comment>
48 swift 1.26 modules_eth0="pump"
49 swift 1.1
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 swift 1.26 modules="!iwconfig"
54 swift 1.1 </pre>
55    
56     </body>
57     </section>
58     <section>
59     <title>Interface Handlers</title>
60     <body>
61    
62     <p>
63 jkt 1.10 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 swift 1.1 </p>
66    
67     <p>
68 swift 1.27 <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 swift 1.1 </p>
72    
73     <pre caption="To install iproute2">
74     # <i>emerge sys-apps/iproute2</i>
75    
76 swift 1.27 <comment># To prefer ifconfig over iproute2 if both are installed as openrc prefers
77     # to use iproute2 then</comment>
78     modules="ifconfig"
79 swift 1.1 </pre>
80    
81     <p>
82 jkt 1.10 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 swift 1.1 </p>
86    
87     <pre caption="ifconfig and iproute2 examples">
88 swift 1.26 config_eth0="192.168.0.2/24"
89     config_eth0="192.168.0.2 netmask 255.255.255.0"
90 swift 1.1
91     <comment># We can also specify broadcast</comment>
92 swift 1.26 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 swift 1.1 </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 jkt 1.10 other things like wireless, PPP or other things if required before you can use
108 swift 1.1 DHCP.
109     </p>
110    
111     <p>
112 nightmorph 1.25 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 swift 1.1 </p>
115    
116     <table>
117 swift 1.2 <tr>
118     <th>DHCP Module</th>
119     <th>Package</th>
120     <th>Pros</th>
121     <th>Cons</th>
122     </tr>
123     <tr>
124 jkt 1.10 <ti><c>dhclient</c></ti>
125     <ti><c>net-misc/dhcp</c></ti>
126 swift 1.2 <ti>
127 swift 1.3 Made by ISC, the same people who make the BIND DNS software. Very
128     configurable
129 swift 1.2 </ti>
130     <ti>
131 swift 1.3 Configuration is overly complex, software is quite bloated, cannot get
132     NTP servers from DHCP, does not send hostname by default
133 swift 1.2 </ti>
134     </tr>
135     <tr>
136 jkt 1.10 <ti><c>dhcpcd</c></ti>
137     <ti><c>net-misc/dhcpcd</c></ti>
138 swift 1.2 <ti>
139 nightmorph 1.20 Long time Gentoo default, no reliance on outside tools, actively developed
140     by Gentoo
141 swift 1.2 </ti>
142 nightmorph 1.20 <ti>Can be slow at times, does not yet daemonize when lease is infinite</ti>
143 swift 1.2 </tr>
144     <tr>
145 jkt 1.10 <ti><c>pump</c></ti>
146     <ti><c>net-misc/pump</c></ti>
147 swift 1.2 <ti>
148 swift 1.3 Lightweight, no reliance on outside tools
149 swift 1.2 </ti>
150     <ti>
151 swift 1.3 No longer maintained upstream, unreliable, especially over modems, cannot
152     get NIS servers from DHCP
153 swift 1.2 </ti>
154     </tr>
155 swift 1.1 </table>
156    
157     <p>
158 jkt 1.9 If you have more than one DHCP client installed, you need to specify which one
159 jkt 1.10 to use - otherwise we default to <c>dhcpcd</c> if available.
160 swift 1.1 </p>
161    
162     <p>
163 jkt 1.10 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
164 flammie 1.17 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
165 swift 1.1 </p>
166    
167     <p>
168     We try and make DHCP relatively agnostic - as such we support the following
169 jkt 1.10 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
170     them:
171 swift 1.1 </p>
172    
173     <ul>
174 jkt 1.10 <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 swift 1.1 </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 swift 1.26 modules="dhcpcd"
183 swift 1.1
184 swift 1.26 config_eth0="dhcp"
185 swift 1.1 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 nightmorph 1.25 <c>dhcpcd</c> and <c>pump</c> send the current hostname to the
191 jkt 1.10 DHCP server by default so you don't need to specify this anymore.
192 swift 1.1 </note>
193    
194     </body>
195     </section>
196     <section>
197 nightmorph 1.23 <title>ADSL with PPPoE/PPPoA</title>
198 swift 1.1 <body>
199    
200     <p>
201     First we need to install the ADSL software.
202     </p>
203    
204 nightmorph 1.22 <pre caption="Install the ppp package">
205     # <i>emerge net-dialup/ppp</i>
206 swift 1.1 </pre>
207    
208 nightmorph 1.22 <p>
209 nightmorph 1.23 Second, create the PPP net script and the net script for the ethernet interface
210     to be used by PPP:
211 nightmorph 1.22 </p>
212    
213 nightmorph 1.23 <pre caption="Creating the PPP and ethernet scripts">
214 nightmorph 1.22 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0</i>
215 nightmorph 1.23 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.eth0</i>
216 nightmorph 1.22 </pre>
217 swift 1.1
218     <p>
219 swift 1.26 Be sure to set <c>rc_depend_strict</c> to "YES" in <path>/etc/rc.conf</path>.
220 nightmorph 1.23 </p>
221    
222     <p>
223 nightmorph 1.22 Now we need to configure <path>/etc/conf.d/net</path>.
224 swift 1.1 </p>
225    
226 nightmorph 1.22 <pre caption="A basic PPPoE setup">
227 swift 1.26 config_eth0=null <comment>(Specify your ethernet interface)</comment>
228     config_ppp0="ppp"
229 nightmorph 1.23 link_ppp0="eth0" <comment>(Specify your ethernet interface)</comment>
230 swift 1.26 plugins_ppp0="pppoe"
231 nightmorph 1.22 username_ppp0='user'
232     password_ppp0='password'
233 swift 1.26 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 swift 1.1 </pre>
245    
246     <p>
247 nightmorph 1.22 You can also set your password in <path>/etc/ppp/pap-secrets</path>.
248 swift 1.1 </p>
249    
250 nightmorph 1.22 <pre caption="Sample /etc/ppp/pap-secrets">
251 swift 1.1 <comment># The * is important</comment>
252 swift 1.4 "username" * "password"
253 swift 1.1 </pre>
254    
255 nightmorph 1.23 <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 nightmorph 1.22 <impo>
262     Please carefully read the section on ADSL and PPP in
263 swift 1.30 <path>/usr/share/doc/netifrc-*/net.example.bz2</path>. It contains many
264 swift 1.26 more detailed explanations of all the settings your particular PPP setup will
265 swift 1.30 likely need.
266 nightmorph 1.22 </impo>
267    
268 swift 1.1 </body>
269     </section>
270     <section id="apipa">
271     <title>APIPA (Automatic Private IP Addressing)</title>
272     <body>
273    
274     <p>
275 jkt 1.9 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 swift 1.1 </p>
279    
280     <p>
281 jkt 1.9 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 swift 1.1 </p>
284    
285     <p>
286 jkt 1.10 For APIPA support, emerge <c>net-misc/iputils</c> or <c>net-analyzer/arping</c>.
287 swift 1.1 </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 swift 1.26 config_eth0="dhcp"
292     fallback_eth0="apipa"
293 swift 1.1
294     <comment># Just use APIPA</comment>
295 swift 1.26 config_eth0="apipa"
296 swift 1.1 </pre>
297    
298     </body>
299     </section>
300     <section>
301     <title>Bonding</title>
302     <body>
303    
304     <p>
305 jkt 1.10 For link bonding/trunking emerge <c>net-misc/ifenslave</c>.
306 swift 1.1 </p>
307    
308     <p>
309 jkt 1.32 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 swift 1.1 </p>
321    
322 swift 1.28 <p>
323     First, clear the configuration of the participating interfaces:
324     </p>
325 swift 1.1
326 swift 1.28 <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 swift 1.1
332 swift 1.28 <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 jkt 1.32 <comment># Pick a correct mode and additional configuration options which suit your needs</comment>
340     mode_bond0="balance-alb"
341 swift 1.1 </pre>
342    
343 swift 1.28 <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 swift 1.1 </body>
349     </section>
350     <section>
351     <title>Bridging (802.1d support)</title>
352     <body>
353    
354     <p>
355 jkt 1.10 For bridging support emerge <c>net-misc/bridge-utils</c>.
356 swift 1.1 </p>
357    
358     <p>
359 jkt 1.9 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 swift 1.1 </p>
364    
365     <pre caption="Bridge configuration in /etc/conf.d/net">
366 nightmorph 1.24 <comment># Configure the bridge - "man brctl" for more details</comment>
367 swift 1.29 brctl_br0="setfd 0
368     sethello 2
369     stp on"
370 swift 1.1
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 swift 1.26 config_eth0="null"
376     config_eth1="null"
377 swift 1.1
378     <comment># Finally give the bridge an address - you could use DHCP as well</comment>
379 swift 1.26 config_br0="192.168.0.1/24"
380 swift 1.1
381     <comment># Depend on eth0 and eth1 as they may require extra configuration</comment>
382 swift 1.26 rc_need_br0="net.eth0 net.eth1"
383 swift 1.1 </pre>
384    
385     <impo>
386 jkt 1.10 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 swift 1.1 </impo>
389    
390     </body>
391     </section>
392     <section>
393     <title>MAC Address</title>
394     <body>
395    
396     <p>
397 swift 1.26 If you need to, you can change the MAC address of your interfaces through
398     the network configuration file too.
399 swift 1.1 </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 flammie 1.17 <comment># To randomize between the same physical type of connection (e.g. fibre,
409 swift 1.1 # copper, wireless) , all vendors</comment>
410     mac_eth0="random-samekind"
411    
412 flammie 1.17 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
413 swift 1.1 # 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 jkt 1.9 You don't need to emerge anything for tunnelling as the interface handler can do
429     it for you.
430 swift 1.1 </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 swift 1.26 config_vpn0="192.168.0.2 peer 192.168.1.1"
441 swift 1.1 </pre>
442    
443     </body>
444     </section>
445     <section>
446     <title>VLAN (802.1q support)</title>
447     <body>
448    
449     <p>
450 swift 1.31 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 swift 1.1 </p>
453    
454 swift 1.2 <p>
455 jkt 1.9 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 swift 1.1 </p>
460    
461 swift 1.28 <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 swift 1.1 vlans_eth0="1 2"
468 swift 1.28 </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 swift 1.1
486 swift 1.28 <pre caption="Configuring the VLANs">
487     vlan1_name="vlan1"
488     vlan1_ingress="2:6 3:5"
489     eth0_vlan1_egress="1:2"
490 swift 1.1 </pre>
491    
492     <impo>
493 jkt 1.10 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 swift 1.1 </impo>
496    
497     </body>
498     </section>
499    
500     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20