/[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.17 - (show annotations) (download) (as text)
Wed Aug 17 08:05:11 2011 UTC (3 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.16: +27 -19 lines
File MIME type: application/xml
Part of bug #337140 - Tell users that "provide net" needs to be influenced when you are dealing with stuff like bridges. Also fixes another OpenRC issue

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.16 2011/08/14 16:12:13 swift 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>10</version>
17 <date>2011-08-17</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="192.168.0.2/24
79 192.168.0.3/24
80 192.168.0.4/24"
81
82 <comment># Adding an IPv4 address and two IPv6 addresses</comment>
83 config_eth0="192.168.0.2/24
84 4321:0:1:2:3:4:567:89ab
85 4321:0:1:2:3:4:567:89ac"
86 )
87
88 <comment># Keep our kernel assigned address, unless the interface goes
89 # down so assign another via DHCP. If DHCP fails then add a
90 # static address determined by APIPA</comment>
91 config_eth0="noop
92 dhcp"
93 fallback_eth0="null
94 apipa"
95 )
96 </pre>
97
98 <note>
99 When using the <c>ifconfig</c> module and adding more than one address,
100 interface aliases are created for each extra address. So with the above two
101 examples you will get interfaces <c>eth0</c>, <c>eth0:1</c> and <c>eth0:2</c>.
102 You cannot do anything special with these interfaces as the kernel and other
103 programs will just treat <c>eth0:1</c> and <c>eth0:2</c> as <c>eth0</c>.
104 </note>
105
106 <impo>
107 The fallback order is important! If we did not specify the <c>null</c> option
108 then the <c>apipa</c> command would only be run if the <c>noop</c> command
109 failed.
110 </impo>
111
112 <note>
113 <uri link="?part=4&amp;chap=3#apipa">APIPA</uri> and <uri
114 link="?part=4&amp;chap=3#dhcp">DHCP</uri> are discussed later.
115 </note>
116
117 </body>
118 </section>
119 <section>
120 <title>Network Dependencies</title>
121 <body>
122
123 <p>
124 Init scripts in <path>/etc/init.d</path> can depend on a specific network
125 interface or just net. All network interfaces in Gentoo's init system provide
126 what is called <e>net</e>.
127 </p>
128
129 <p>
130 If, in <path>/etc/rc.conf</path>, <c>rc_depend_strict="YES"</c> is set, then all
131 network interfaces that provide net must be active before a dependency on "net"
132 is assumed to be met. In other words, if you have a <path>net.eth0</path> and
133 <path>net.eth1</path> and an init script depends on "net", then both must be
134 enabled.
135 </p>
136
137 <p>
138 On the other hand, if <c>rc_depend_strict="NO"</c> is set, then the "net"
139 dependency is marked as resolved the moment at least one network interface is
140 brought up.
141 </p>
142
143 <p>
144 But what about <path>net.br0</path> depending on <path>net.eth0</path> and
145 <path>net.eth1</path>? <path>net.eth1</path> may be a wireless or PPP device
146 that needs configuration before it can be added to the bridge. This cannot be
147 done in <path>/etc/init.d/net.br0</path> as that's a symbolic link to
148 <path>net.lo</path>.
149 </p>
150
151 <p>
152 The answer is defining an <c>rc_need_</c> setting in
153 <path>/etc/conf.d/net</path>.
154 </p>
155
156 <pre caption="net.br0 dependency in /etc/conf.d/net">
157 rc_need_br0="net.eth0 net.eth1"
158 </pre>
159
160 <p>
161 That alone, however, is not sufficient. Gentoo's networking init scripts use a
162 virtual dependency called <e>net</e> to inform the system when networking is
163 available. Clearly, in the above case, networking should only be marked as
164 available when <path>net.br0</path> is up, not when the others are. So we need
165 to tell that in <path>/etc/conf.d/net</path> as well:
166 </p>
167
168 <pre caption="Updating virtual dependencies and provisions for networking">
169 rc_net_lo_provide="!net"
170 rc_net_eth0_provide="!net"
171 rc_net_eth1_provide="!net"
172 </pre>
173
174 <p>
175 For a more detailed discussion about dependency, consult the section <uri
176 link="?part=2&amp;chap=4#doc_chap4">Writing Init Scripts</uri> in the Gentoo
177 Handbook. More information about <path>/etc/rc.conf</path> is available as
178 comments within that file.
179 </p>
180
181 </body>
182 </section>
183
184 <section id="variable_name">
185 <title>Variable names and values</title>
186 <body>
187
188 <p>
189 Variable names are dynamic. They normally follow the structure of
190 <c>variable_${interface|mac|essid|apmac}</c>. For example, the variable
191 <c>dhcpcd_eth0</c> holds the value for dhcpcd options for eth0 and
192 <c>dhcpcd_essid</c> holds the value for dhcpcd options when any interface
193 connects to the ESSID "essid".
194 </p>
195
196 <p>
197 However, there is no hard and fast rule that states interface names must be
198 ethx. In fact, many wireless interfaces have names like wlanx, rax as well as
199 ethx. Also, some user defined interfaces such as bridges can be given any name,
200 such as foo. To make life more interesting, wireless Access Points can have
201 names with non alpha-numeric characters in them - this is important because
202 you can configure networking parameters per ESSID.
203 </p>
204
205 <p>
206 The downside of all this is that Gentoo uses bash variables for networking -
207 and bash cannot use anything outside of English alpha-numerics. To get around
208 this limitation we change every character that is not an English alpha-numeric
209 into a <c>_</c> character.
210 </p>
211
212 <p>
213 Another downside of bash is the content of variables - some characters need to
214 be escaped. This can be achived by placing the <c>\</c> character in front of
215 the character that needs to be escaped. The following list of characters needs
216 to be escaped in this way: <c>"</c>, <c>'</c> and <c>\</c>.
217 </p>
218
219 <p>
220 In this example we use wireless ESSID as they can contain the widest scope
221 of characters. We shall use the ESSID <c>My "\ NET</c>:
222 </p>
223
224 <pre caption="variable name example">
225 <comment>(This does work, but the domain is invalid)</comment>
226 dns_domain_My____NET="My \"\\ NET"
227
228 <comment>(The above sets the dns domain to My "\ NET when a wireless card
229 connects to an AP whose ESSID is My "\ NET)</comment>
230 </pre>
231
232 </body>
233 </section>
234 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20