/[gentoo]/xml/htdocs/doc/en/handbook/hb-net-advanced.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-net-advanced.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.16 - (show annotations) (download) (as text)
Sun Aug 14 16:12:13 2011 UTC (3 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.15: +22 -45 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-advanced.xml,v 1.15 2009/02/13 04:40:27 nightmorph Exp $ -->
8
9 <sections>
10
11 <abstract>
12 Here we learn about how the configuration works - you need to know this
13 before we learn about modular networking.
14 </abstract>
15
16 <version>9</version>
17 <date>2011-08-13</date>
18
19 <section>
20 <title>Advanced Configuration</title>
21 <body>
22
23 <p>
24 The <c>config_eth0</c> variable is the heart of an interface configuration. It's
25 a high level instruction list for configuring the interface (<c>eth0</c> in this
26 case). Each command in the instruction list is performed sequentially. The
27 interface is deemed OK if at least one command works.
28 </p>
29
30 <p>
31 Here's a list of built-in instructions.
32 </p>
33
34 <table>
35 <tr>
36 <th>Command</th>
37 <th>Description</th>
38 </tr>
39 <tr>
40 <ti><c>null</c></ti>
41 <ti>Do nothing</ti>
42 </tr>
43 <tr>
44 <ti><c>noop</c></ti>
45 <ti>
46 If the interface is up and there is an address then abort configuration
47 successfully
48 </ti>
49 </tr>
50 <tr>
51 <ti>an IPv4 or IPv6 address</ti>
52 <ti>Add the address to the interface</ti>
53 </tr>
54 <tr>
55 <ti>
56 <c>dhcp</c>, <c>adsl</c> or <c>apipa</c> (or a custom command from a 3rd
57 party module)
58 </ti>
59 <ti>
60 Run the module which provides the command. For example <c>dhcp</c> will run
61 a module that provides DHCP which can be one of either <c>dhcpcd</c>,
62 <c>dhclient</c> or <c>pump</c>.
63 </ti>
64 </tr>
65 </table>
66
67 <p>
68 If a command fails, you can specify a fallback command. The fallback has to
69 match the config structure exactly.
70 </p>
71
72 <p>
73 You can chain these commands together. Here are some real world examples.
74 </p>
75
76 <pre caption="Configuration examples">
77 <comment># Adding three IPv4 addresses</comment>
78 config_eth0=(
79 "192.168.0.2/24"
80 "192.168.0.3/24"
81 "192.168.0.4/24"
82 )
83
84 <comment># Adding an IPv4 address and two IPv6 addresses</comment>
85 config_eth0=(
86 "192.168.0.2/24"
87 "4321:0:1:2:3:4:567:89ab"
88 "4321:0:1:2:3:4:567:89ac"
89 )
90
91 <comment># Keep our kernel assigned address, unless the interface goes
92 # down so assign another via DHCP. If DHCP fails then add a
93 # static address determined by APIPA</comment>
94 config_eth0=(
95 "noop"
96 "dhcp"
97 )
98 fallback_eth0=(
99 "null"
100 "apipa"
101 )
102 </pre>
103
104 <note>
105 When using the <c>ifconfig</c> module and adding more than one address,
106 interface aliases are created for each extra address. So with the above two
107 examples you will get interfaces <c>eth0</c>, <c>eth0:1</c> and <c>eth0:2</c>.
108 You cannot do anything special with these interfaces as the kernel and other
109 programs will just treat <c>eth0:1</c> and <c>eth0:2</c> as <c>eth0</c>.
110 </note>
111
112 <impo>
113 The fallback order is important! If we did not specify the <c>null</c> option
114 then the <c>apipa</c> command would only be run if the <c>noop</c> command
115 failed.
116 </impo>
117
118 <note>
119 <uri link="?part=4&amp;chap=3#apipa">APIPA</uri> and <uri
120 link="?part=4&amp;chap=3#dhcp">DHCP</uri> are discussed later.
121 </note>
122
123 </body>
124 </section>
125 <section>
126 <title>Network Dependencies</title>
127 <body>
128
129 <p>
130 Init scripts in <path>/etc/init.d</path> can depend on a specific network
131 interface or just net. All network interfaces in Gentoo's init system provide
132 what is called <e>net</e>.
133 </p>
134
135 <p>
136 If, in <path>/etc/rc.conf</path>, <c>rc_depend_strict="YES"</c> is set, then all
137 network interfaces that provide net must be active before a dependency on "net"
138 is assumed to be met. In other words, if you have a <path>net.eth0</path> and
139 <path>net.eth1</path> and an init script depends on "net", then both must be
140 enabled.
141 </p>
142
143 <p>
144 On the other hand, if <c>rc_depend_strict="NO"</c> is set, then the "net"
145 dependency is marked as resolved the moment at least one network interface is
146 brought up.
147 </p>
148
149 <p>
150 But what about <path>net.br0</path> depending on <path>net.eth0</path> and
151 <path>net.eth1</path>? <path>net.eth1</path> may be a wireless or PPP device
152 that needs configuration before it can be added to the bridge. This cannot be
153 done in <path>/etc/init.d/net.br0</path> as that's a symbolic link to
154 <path>net.lo</path>.
155 </p>
156
157 <p>
158 The answer is defining an <c>rc_need_</c> setting in
159 <path>/etc/conf.d/net</path>.
160 </p>
161
162 <pre caption="net.br0 dependency in /etc/conf.d/net">
163 rc_need_br0="net.eth0 net.eth1"
164 </pre>
165
166 <p>
167 For a more detailed discussion about dependency, consult the section <uri
168 link="?part=2&amp;chap=4#doc_chap4">Writing Init Scripts</uri> in the Gentoo
169 Handbook. More information about <path>/etc/rc.conf</path> is available as
170 comments within that file.
171 </p>
172
173 </body>
174 </section>
175
176 <section id="variable_name">
177 <title>Variable names and values</title>
178 <body>
179
180 <p>
181 Variable names are dynamic. They normally follow the structure of
182 <c>variable_${interface|mac|essid|apmac}</c>. For example, the variable
183 <c>dhcpcd_eth0</c> holds the value for dhcpcd options for eth0 and
184 <c>dhcpcd_essid</c> holds the value for dhcpcd options when any interface
185 connects to the ESSID "essid".
186 </p>
187
188 <p>
189 However, there is no hard and fast rule that states interface names must be
190 ethx. In fact, many wireless interfaces have names like wlanx, rax as well as
191 ethx. Also, some user defined interfaces such as bridges can be given any name,
192 such as foo. To make life more interesting, wireless Access Points can have
193 names with non alpha-numeric characters in them - this is important because
194 you can configure networking parameters per ESSID.
195 </p>
196
197 <p>
198 The downside of all this is that Gentoo uses bash variables for networking -
199 and bash cannot use anything outside of English alpha-numerics. To get around
200 this limitation we change every character that is not an English alpha-numeric
201 into a <c>_</c> character.
202 </p>
203
204 <p>
205 Another downside of bash is the content of variables - some characters need to
206 be escaped. This can be achived by placing the <c>\</c> character in front of
207 the character that needs to be escaped. The following list of characters needs
208 to be escaped in this way: <c>"</c>, <c>'</c> and <c>\</c>.
209 </p>
210
211 <p>
212 In this example we use wireless ESSID as they can contain the widest scope
213 of characters. We shall use the ESSID <c>My "\ NET</c>:
214 </p>
215
216 <pre caption="variable name example">
217 <comment>(This does work, but the domain is invalid)</comment>
218 dns_domain_My____NET="My \"\\ NET"
219
220 <comment>(The above sets the dns domain to My "\ NET when a wireless card
221 connects to an AP whose ESSID is My "\ NET)</comment>
222 </pre>
223
224 </body>
225 </section>
226 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20