/[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 - (show annotations) (download) (as text)
Sun Aug 14 16:12:13 2011 UTC (3 years, 1 month 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 <?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.25 2009/02/13 04:40:27 nightmorph 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>9</version>
17 <date>2011-08-13</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 iproute2 over ifconfig</comment>
44 modules="iproute2"
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 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 </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 modules="iproute2"
78 </pre>
79
80 <p>
81 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 </p>
85
86 <pre caption="ifconfig and iproute2 examples">
87 config_eth0="192.168.0.2/24"
88 config_eth0="192.168.0.2 netmask 255.255.255.0"
89
90 <comment># We can also specify broadcast</comment>
91 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 </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 other things like wireless, PPP or other things if required before you can use
107 DHCP.
108 </p>
109
110 <p>
111 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 </p>
114
115 <table>
116 <tr>
117 <th>DHCP Module</th>
118 <th>Package</th>
119 <th>Pros</th>
120 <th>Cons</th>
121 </tr>
122 <tr>
123 <ti><c>dhclient</c></ti>
124 <ti><c>net-misc/dhcp</c></ti>
125 <ti>
126 Made by ISC, the same people who make the BIND DNS software. Very
127 configurable
128 </ti>
129 <ti>
130 Configuration is overly complex, software is quite bloated, cannot get
131 NTP servers from DHCP, does not send hostname by default
132 </ti>
133 </tr>
134 <tr>
135 <ti><c>dhcpcd</c></ti>
136 <ti><c>net-misc/dhcpcd</c></ti>
137 <ti>
138 Long time Gentoo default, no reliance on outside tools, actively developed
139 by Gentoo
140 </ti>
141 <ti>Can be slow at times, does not yet daemonize when lease is infinite</ti>
142 </tr>
143 <tr>
144 <ti><c>pump</c></ti>
145 <ti><c>net-misc/pump</c></ti>
146 <ti>
147 Lightweight, no reliance on outside tools
148 </ti>
149 <ti>
150 No longer maintained upstream, unreliable, especially over modems, cannot
151 get NIS servers from DHCP
152 </ti>
153 </tr>
154 </table>
155
156 <p>
157 If you have more than one DHCP client installed, you need to specify which one
158 to use - otherwise we default to <c>dhcpcd</c> if available.
159 </p>
160
161 <p>
162 To send specific options to the DHCP module, use <c>module_eth0="..."</c>
163 <e>(change module to the DHCP module you're using - i.e. <c>dhcpcd_eth0</c>)</e>.
164 </p>
165
166 <p>
167 We try and make DHCP relatively agnostic - as such we support the following
168 commands using the <c>dhcp_eth0</c> variable. The default is not to set any of
169 them:
170 </p>
171
172 <ul>
173 <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 </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 modules="dhcpcd"
182
183 config_eth0="dhcp"
184 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 <c>dhcpcd</c> and <c>pump</c> send the current hostname to the
190 DHCP server by default so you don't need to specify this anymore.
191 </note>
192
193 </body>
194 </section>
195 <section>
196 <title>ADSL with PPPoE/PPPoA</title>
197 <body>
198
199 <p>
200 First we need to install the ADSL software.
201 </p>
202
203 <pre caption="Install the ppp package">
204 # <i>emerge net-dialup/ppp</i>
205 </pre>
206
207 <p>
208 Second, create the PPP net script and the net script for the ethernet interface
209 to be used by PPP:
210 </p>
211
212 <pre caption="Creating the PPP and ethernet scripts">
213 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0</i>
214 # <i>ln -s /etc/init.d/net.lo /etc/init.d/net.eth0</i>
215 </pre>
216
217 <p>
218 Be sure to set <c>rc_depend_strict</c> to "YES" in <path>/etc/rc.conf</path>.
219 </p>
220
221 <p>
222 Now we need to configure <path>/etc/conf.d/net</path>.
223 </p>
224
225 <pre caption="A basic PPPoE setup">
226 config_eth0=null <comment>(Specify your ethernet interface)</comment>
227 config_ppp0="ppp"
228 link_ppp0="eth0" <comment>(Specify your ethernet interface)</comment>
229 plugins_ppp0="pppoe"
230 username_ppp0='user'
231 password_ppp0='password'
232 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 </pre>
244
245 <p>
246 You can also set your password in <path>/etc/ppp/pap-secrets</path>.
247 </p>
248
249 <pre caption="Sample /etc/ppp/pap-secrets">
250 <comment># The * is important</comment>
251 "username" * "password"
252 </pre>
253
254 <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 <impo>
261 Please carefully read the section on ADSL and PPP in
262 <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 </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. 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 </p>
313
314 <pre caption="bonding configuration in /etc/conf.d/net">
315 <comment># To bond interfaces together</comment>
316 slaves_bond0="eth0 eth1 eth2"
317
318 <comment># You may not want to assign an IP to the bonded interface</comment>
319 config_bond0="null"
320
321 <comment># Depend on eth0, eth1 and eth2 as they may require extra configuration</comment>
322 rc_need_bond0="net.eth0 net.eth1 net.eth2"
323 </pre>
324
325 </body>
326 </section>
327 <section>
328 <title>Bridging (802.1d support)</title>
329 <body>
330
331 <p>
332 For bridging support emerge <c>net-misc/bridge-utils</c>.
333 </p>
334
335 <p>
336 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 </p>
341
342 <pre caption="Bridge configuration in /etc/conf.d/net">
343 <comment># Configure the bridge - "man brctl" for more details</comment>
344 brctl_br0="setfd 0" "sethello 0" "stp off"
345
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 config_eth0="null"
351 config_eth1="null"
352
353 <comment># Finally give the bridge an address - you could use DHCP as well</comment>
354 config_br0="192.168.0.1/24"
355
356 <comment># Depend on eth0 and eth1 as they may require extra configuration</comment>
357 rc_need_br0="net.eth0 net.eth1"
358 </pre>
359
360 <impo>
361 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 </impo>
364
365 </body>
366 </section>
367 <section>
368 <title>MAC Address</title>
369 <body>
370
371 <p>
372 If you need to, you can change the MAC address of your interfaces through
373 the network configuration file too.
374 </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 <comment># To randomize between the same physical type of connection (e.g. fibre,
384 # copper, wireless) , all vendors</comment>
385 mac_eth0="random-samekind"
386
387 <comment># To randomize between any physical type of connection (e.g. fibre, copper,
388 # 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 You don't need to emerge anything for tunnelling as the interface handler can do
404 it for you.
405 </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 config_vpn0="192.168.0.2 peer 192.168.1.1"
416 </pre>
417
418 </body>
419 </section>
420 <section>
421 <title>VLAN (802.1q support)</title>
422 <body>
423
424 <p>
425 For VLAN support, emerge <c>net-misc/vconfig</c>.
426 </p>
427
428 <p>
429 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 </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 vconfig_eth0="set_name_type VLAN_PLUS_VID_NO_PAD"
443 vconfig_vlan1="set_flag 1" "set_egress_map 2 6"
444
445 <comment># Configure the interface as usual</comment>
446 config_vlan1="172.16.3.1 netmask 255.255.254.0"
447 config_vlan2="172.16.2.1 netmask 255.255.254.0"
448 </pre>
449
450 <impo>
451 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 </impo>
454
455 </body>
456 </section>
457
458 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20