/[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.26 - (hide annotations) (download) (as text)
Sun Aug 14 16:12:13 2011 UTC (3 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.25: +49 -61 lines
File MIME type: application/xml
Bug #213988 - Various fixes on OpenRC in handbook

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 swift 1.26 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-modules.xml,v 1.25 2009/02/13 04:40:27 nightmorph 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 swift 1.26 <version>9</version>
17     <date>2011-08-13</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     <comment># Prefer iproute2 over ifconfig</comment>
44 swift 1.26 modules="iproute2"
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 jkt 1.10 <c>ifconfig</c> is the current Gentoo default and it's included in the system
69     profile. <c>iproute2</c> is a more powerful and flexible package, but it's not
70     included by default.
71 swift 1.1 </p>
72    
73     <pre caption="To install iproute2">
74     # <i>emerge sys-apps/iproute2</i>
75    
76     <comment># To prefer iproute2 over ifconfig if both are installed</comment>
77 swift 1.26 modules="iproute2"
78 swift 1.1 </pre>
79    
80     <p>
81 jkt 1.10 As both <c>ifconfig</c> and <c>iproute2</c> do very similar things we allow
82     their basic configuration to work with each other. For example both the below
83     code snippet work regardless of which module you are using.
84 swift 1.1 </p>
85    
86     <pre caption="ifconfig and iproute2 examples">
87 swift 1.26 config_eth0="192.168.0.2/24"
88     config_eth0="192.168.0.2 netmask 255.255.255.0"
89 swift 1.1
90     <comment># We can also specify broadcast</comment>
91 swift 1.26 config_eth0="192.168.0.2/24 brd 192.168.0.255"
92     config_eth0="192.168.0.2 netmask 255.255.255.0 broadcast 192.168.0.255"
93 swift 1.1 </pre>
94    
95     </body>
96     </section>
97     <section id="dhcp">
98     <title>DHCP</title>
99     <body>
100    
101     <p>
102     DHCP is a means of obtaining network information (IP address, DNS servers,
103     Gateway, etc) from a DHCP server. This means that if there is a DHCP server
104     running on the network, you just have to tell each client to use DHCP and it
105     sets up the network all by itself. Of course, you will have to configure for
106 jkt 1.10 other things like wireless, PPP or other things if required before you can use
107 swift 1.1 DHCP.
108     </p>
109    
110     <p>
111 nightmorph 1.25 DHCP can be provided by <c>dhclient</c>, <c>dhcpcd</c>, or <c>pump</c>. Each
112     DHCP module has its pros and cons - here's a quick run down.
113 swift 1.1 </p>
114    
115     <table>
116 swift 1.2 <tr>
117     <th>DHCP Module</th>
118     <th>Package</th>
119     <th>Pros</th>
120     <th>Cons</th>
121     </tr>
122     <tr>
123 jkt 1.10 <ti><c>dhclient</c></ti>
124     <ti><c>net-misc/dhcp</c></ti>
125 swift 1.2 <ti>
126 swift 1.3 Made by ISC, the same people who make the BIND DNS software. Very
127     configurable
128 swift 1.2 </ti>
129     <ti>
130 swift 1.3 Configuration is overly complex, software is quite bloated, cannot get
131     NTP servers from DHCP, does not send hostname by default
132 swift 1.2 </ti>
133     </tr>
134     <tr>
135 jkt 1.10 <ti><c>dhcpcd</c></ti>
136     <ti><c>net-misc/dhcpcd</c></ti>
137 swift 1.2 <ti>
138 nightmorph 1.20 Long time Gentoo default, no reliance on outside tools, actively developed
139     by Gentoo
140 swift 1.2 </ti>
141 nightmorph 1.20 <ti>Can be slow at times, does not yet daemonize when lease is infinite</ti>
142 swift 1.2 </tr>
143     <tr>
144 jkt 1.10 <ti><c>pump</c></ti>
145     <ti><c>net-misc/pump</c></ti>
146 swift 1.2 <ti>
147 swift 1.3 Lightweight, no reliance on outside tools
148 swift 1.2 </ti>
149     <ti>
150 swift 1.3 No longer maintained upstream, unreliable, especially over modems, cannot
151     get NIS servers from DHCP
152 swift 1.2 </ti>
153     </tr>
154 swift 1.1 </table>
155    
156     <p>
157 jkt 1.9 If you have more than one DHCP client installed, you need to specify which one
158 jkt 1.10 to use - otherwise we default to <c>dhcpcd</c> if available.
159 swift 1.1 </p>
160    
161     <p>
162 jkt 1.10 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
163 flammie 1.17 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
164 swift 1.1 </p>
165    
166     <p>
167     We try and make DHCP relatively agnostic - as such we support the following
168 jkt 1.10 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
169     them:
170 swift 1.1 </p>
171    
172     <ul>
173 jkt 1.10 <li><c>release</c> - releases the IP address for re-use</li>
174     <li><c>nodns</c> - don't overwrite <path>/etc/resolv.conf</path></li>
175     <li><c>nontp</c> - don't overwrite <path>/etc/ntp.conf</path></li>
176     <li><c>nonis</c> - don't overwrite <path>/etc/yp.conf</path></li>
177 swift 1.1 </ul>
178    
179     <pre caption="Sample DHCP configuration in /etc/conf.d/net">
180     <comment># Only needed if you have more than one DHCP module installed</comment>
181 swift 1.26 modules="dhcpcd"
182 swift 1.1
183 swift 1.26 config_eth0="dhcp"
184 swift 1.1 dhcpcd_eth0="-t 10" <comment># Timeout after 10 seconds</comment>
185     dhcp_eth0="release nodns nontp nonis" <comment># Only get an address</comment>
186     </pre>
187    
188     <note>
189 nightmorph 1.25 <c>dhcpcd</c> and <c>pump</c> send the current hostname to the
190 jkt 1.10 DHCP server by default so you don't need to specify this anymore.
191 swift 1.1 </note>
192    
193     </body>
194     </section>
195     <section>
196 nightmorph 1.23 <title>ADSL with PPPoE/PPPoA</title>
197 swift 1.1 <body>
198    
199     <p>
200     First we need to install the ADSL software.
201     </p>
202    
203 nightmorph 1.22 <pre caption="Install the ppp package">
204     # <i>emerge net-dialup/ppp</i>
205 swift 1.1 </pre>
206    
207 nightmorph 1.22 <p>
208 nightmorph 1.23 Second, create the PPP net script and the net script for the ethernet interface
209     to be used by PPP:
210 nightmorph 1.22 </p>
211    
212 nightmorph 1.23 <pre caption="Creating the PPP and ethernet scripts">
213 nightmorph 1.22 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0</i>
214 nightmorph 1.23 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.eth0</i>
215 nightmorph 1.22 </pre>
216 swift 1.1
217     <p>
218 swift 1.26 Be sure to set <c>rc_depend_strict</c> to "YES" in <path>/etc/rc.conf</path>.
219 nightmorph 1.23 </p>
220    
221     <p>
222 nightmorph 1.22 Now we need to configure <path>/etc/conf.d/net</path>.
223 swift 1.1 </p>
224    
225 nightmorph 1.22 <pre caption="A basic PPPoE setup">
226 swift 1.26 config_eth0=null <comment>(Specify your ethernet interface)</comment>
227     config_ppp0="ppp"
228 nightmorph 1.23 link_ppp0="eth0" <comment>(Specify your ethernet interface)</comment>
229 swift 1.26 plugins_ppp0="pppoe"
230 nightmorph 1.22 username_ppp0='user'
231     password_ppp0='password'
232 swift 1.26 pppd_ppp0="
233     noauth
234     defaultroute
235     usepeerdns
236     holdoff 3
237     child-timeout 60
238     lcp-echo-interval 15
239     lcp-echo-failure 3
240     noaccomp noccp nobsdcomp nodeflate nopcomp novj novjccomp"
241    
242     rc_need_ppp0="net.eth0"
243 swift 1.1 </pre>
244    
245     <p>
246 nightmorph 1.22 You can also set your password in <path>/etc/ppp/pap-secrets</path>.
247 swift 1.1 </p>
248    
249 nightmorph 1.22 <pre caption="Sample /etc/ppp/pap-secrets">
250 swift 1.1 <comment># The * is important</comment>
251 swift 1.4 "username" * "password"
252 swift 1.1 </pre>
253    
254 nightmorph 1.23 <p>
255     If you use PPPoE with a USB modem you'll need to emerge <c>br2684ctl</c>. Please
256     read <path>/usr/portage/net-dialup/speedtouch-usb/files/README</path> for
257     information on how to properly configure it.
258     </p>
259    
260 nightmorph 1.22 <impo>
261     Please carefully read the section on ADSL and PPP in
262 swift 1.26 <path>/usr/share/doc/openrc-0.8.3-r1/net.example.bz2</path>. It contains many
263     more detailed explanations of all the settings your particular PPP setup will
264     likely need. Of course, change <c>0.8.3-r1</c> with the version of OpenRC
265     installed on your system.
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.9 Bonding is used to increase network bandwidth. If you have two network cards
310     going to the same network, you can bond them together so your applications see
311     just one interface but they really use both network cards.
312 swift 1.1 </p>
313    
314     <pre caption="bonding configuration in /etc/conf.d/net">
315 jkt 1.13 <comment># To bond interfaces together</comment>
316 swift 1.1 slaves_bond0="eth0 eth1 eth2"
317    
318     <comment># You may not want to assign an IP to the bonded interface</comment>
319 swift 1.26 config_bond0="null"
320 swift 1.1
321     <comment># Depend on eth0, eth1 and eth2 as they may require extra configuration</comment>
322 swift 1.26 rc_need_bond0="net.eth0 net.eth1 net.eth2"
323 swift 1.1 </pre>
324    
325     </body>
326     </section>
327     <section>
328     <title>Bridging (802.1d support)</title>
329     <body>
330    
331     <p>
332 jkt 1.10 For bridging support emerge <c>net-misc/bridge-utils</c>.
333 swift 1.1 </p>
334    
335     <p>
336 jkt 1.9 Bridging is used to join networks together. For example, you may have a server
337     that connects to the internet via an ADSL modem and a wireless access card to
338     enable other computers to connect to the internet via the ADSL modem. You could
339     create a bridge to join the two interfaces together.
340 swift 1.1 </p>
341    
342     <pre caption="Bridge configuration in /etc/conf.d/net">
343 nightmorph 1.24 <comment># Configure the bridge - "man brctl" for more details</comment>
344 swift 1.26 brctl_br0="setfd 0" "sethello 0" "stp off"
345 swift 1.1
346     <comment># To add ports to bridge br0</comment>
347     bridge_br0="eth0 eth1"
348    
349     <comment># You need to configure the ports to null values so dhcp does not get started</comment>
350 swift 1.26 config_eth0="null"
351     config_eth1="null"
352 swift 1.1
353     <comment># Finally give the bridge an address - you could use DHCP as well</comment>
354 swift 1.26 config_br0="192.168.0.1/24"
355 swift 1.1
356     <comment># Depend on eth0 and eth1 as they may require extra configuration</comment>
357 swift 1.26 rc_need_br0="net.eth0 net.eth1"
358 swift 1.1 </pre>
359    
360     <impo>
361 jkt 1.10 For using some bridge setups, you may need to consult the <uri
362     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
363 swift 1.1 </impo>
364    
365     </body>
366     </section>
367     <section>
368     <title>MAC Address</title>
369     <body>
370    
371     <p>
372 swift 1.26 If you need to, you can change the MAC address of your interfaces through
373     the network configuration file too.
374 swift 1.1 </p>
375    
376     <pre caption="MAC Address change example">
377     <comment># To set the MAC address of the interface</comment>
378     mac_eth0="00:11:22:33:44:55"
379    
380     <comment># To randomize the last 3 bytes only</comment>
381     mac_eth0="random-ending"
382    
383 flammie 1.17 <comment># To randomize between the same physical type of connection (e.g. fibre,
384 swift 1.1 # copper, wireless) , all vendors</comment>
385     mac_eth0="random-samekind"
386    
387 flammie 1.17 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
388 swift 1.1 # wireless) , all vendors</comment>
389     mac_eth0="random-anykind"
390    
391     <comment># Full randomization - WARNING: some MAC addresses generated by this may
392     # NOT act as expected</comment>
393     mac_eth0="random-full"
394     </pre>
395    
396     </body>
397     </section>
398     <section>
399     <title>Tunnelling</title>
400     <body>
401    
402     <p>
403 jkt 1.9 You don't need to emerge anything for tunnelling as the interface handler can do
404     it for you.
405 swift 1.1 </p>
406    
407     <pre caption="Tunnelling configuration in /etc/conf.d/net">
408     <comment># For GRE tunnels</comment>
409     iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
410    
411     <comment># For IPIP tunnels</comment>
412     iptunnel_vpn0="mode ipip remote 207.170.82.2 ttl 255"
413    
414     <comment># To configure the interface</comment>
415 swift 1.26 config_vpn0="192.168.0.2 peer 192.168.1.1"
416 swift 1.1 </pre>
417    
418     </body>
419     </section>
420     <section>
421     <title>VLAN (802.1q support)</title>
422     <body>
423    
424     <p>
425 jkt 1.10 For VLAN support, emerge <c>net-misc/vconfig</c>.
426 swift 1.1 </p>
427    
428 swift 1.2 <p>
429 jkt 1.9 Virtual LAN is a group of network devices that behave as if they were connected
430     to a single network segment - even though they may not be. VLAN members can only
431     see members of the same VLAN even though they may share the same physical
432     network.
433 swift 1.1 </p>
434    
435     <pre caption="VLAN configuration in /etc/conf.d/net">
436     <comment># Specify the VLAN numbers for the interface like so</comment>
437     <comment># Please ensure your VLAN IDs are NOT zero-padded</comment>
438     vlans_eth0="1 2"
439    
440     <comment># You can also configure the VLAN</comment>
441     <comment># see for vconfig man page for more details</comment>
442 swift 1.26 vconfig_eth0="set_name_type VLAN_PLUS_VID_NO_PAD"
443     vconfig_vlan1="set_flag 1" "set_egress_map 2 6"
444 swift 1.1
445     <comment># Configure the interface as usual</comment>
446 swift 1.26 config_vlan1="172.16.3.1 netmask 255.255.254.0"
447     config_vlan2="172.16.2.1 netmask 255.255.254.0"
448 swift 1.1 </pre>
449    
450     <impo>
451 jkt 1.10 For using some VLAN setups, you may need to consult the <uri
452     link="?part=4&amp;chap=2#variable_name">variable name</uri> documentation.
453 swift 1.1 </impo>
454    
455     </body>
456     </section>
457    
458     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20