/[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 - (hide 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 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.5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.1
7 swift 1.17 <!-- $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 fox2mike 1.3
9 swift 1.1 <sections>
10    
11 neysx 1.13 <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 swift 1.17 <version>10</version>
17     <date>2011-08-17</date>
18 swift 1.1
19     <section>
20     <title>Advanced Configuration</title>
21     <body>
22    
23     <p>
24 jkt 1.11 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 swift 1.1 </p>
29    
30     <p>
31 nightmorph 1.14 Here's a list of built-in instructions.
32 swift 1.1 </p>
33    
34     <table>
35 swift 1.5 <tr>
36     <th>Command</th>
37     <th>Description</th>
38     </tr>
39     <tr>
40 jkt 1.11 <ti><c>null</c></ti>
41 swift 1.5 <ti>Do nothing</ti>
42     </tr>
43     <tr>
44 jkt 1.11 <ti><c>noop</c></ti>
45 swift 1.5 <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 jkt 1.11 <c>dhcp</c>, <c>adsl</c> or <c>apipa</c> (or a custom command from a 3rd
57     party module)
58 swift 1.5 </ti>
59     <ti>
60 jkt 1.11 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 nightmorph 1.15 <c>dhclient</c> or <c>pump</c>.
63 swift 1.5 </ti>
64     </tr>
65 swift 1.1 </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 swift 1.4 You can chain these commands together. Here are some real world examples.
74 swift 1.1 </p>
75    
76 swift 1.6 <pre caption="Configuration examples">
77 swift 1.1 <comment># Adding three IPv4 addresses</comment>
78 swift 1.17 config_eth0="192.168.0.2/24
79     192.168.0.3/24
80     192.168.0.4/24"
81 swift 1.1
82     <comment># Adding an IPv4 address and two IPv6 addresses</comment>
83 swift 1.17 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 swift 1.1 )
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 swift 1.17 config_eth0="noop
92     dhcp"
93     fallback_eth0="null
94     apipa"
95 swift 1.1 )
96     </pre>
97    
98     <note>
99 jkt 1.11 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 swift 1.1 </note>
105    
106     <impo>
107 jkt 1.11 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 swift 1.1 </impo>
111    
112     <note>
113 jkt 1.10 <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 swift 1.1 </note>
116    
117     </body>
118     </section>
119     <section>
120     <title>Network Dependencies</title>
121     <body>
122    
123 swift 1.5 <p>
124     Init scripts in <path>/etc/init.d</path> can depend on a specific network
125 swift 1.16 interface or just net. All network interfaces in Gentoo's init system provide
126     what is called <e>net</e>.
127 swift 1.1 </p>
128    
129 swift 1.16 <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 swift 1.1
143     <p>
144 jkt 1.11 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 swift 1.1 </p>
150    
151     <p>
152 swift 1.16 The answer is defining an <c>rc_need_</c> setting in
153 jkt 1.11 <path>/etc/conf.d/net</path>.
154 swift 1.1 </p>
155    
156     <pre caption="net.br0 dependency in /etc/conf.d/net">
157 swift 1.16 rc_need_br0="net.eth0 net.eth1"
158 swift 1.1 </pre>
159    
160     <p>
161 swift 1.17 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 jkt 1.10 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 swift 1.16 Handbook. More information about <path>/etc/rc.conf</path> is available as
178     comments within that file.
179 swift 1.1 </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 fox2mike 1.3 Variable names are dynamic. They normally follow the structure of
190 swift 1.1 <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 jkt 1.11 connects to the ESSID "essid".
194 swift 1.1 </p>
195    
196     <p>
197     However, there is no hard and fast rule that states interface names must be
198 swift 1.5 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 swift 1.1 </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 jkt 1.11 into a <c>_</c> character.
210 swift 1.1 </p>
211    
212     <p>
213 fox2mike 1.3 Another downside of bash is the content of variables - some characters need to
214 jkt 1.11 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 swift 1.6 to be escaped in this way: <c>"</c>, <c>'</c> and <c>\</c>.
217 swift 1.1 </p>
218    
219     <p>
220     In this example we use wireless ESSID as they can contain the widest scope
221 swift 1.6 of characters. We shall use the ESSID <c>My "\ NET</c>:
222 swift 1.1 </p>
223    
224     <pre caption="variable name example">
225 nightmorph 1.14 <comment>(This does work, but the domain is invalid)</comment>
226 swift 1.1 dns_domain_My____NET="My \"\\ NET"
227    
228 nightmorph 1.14 <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 swift 1.1 </pre>
231    
232     </body>
233     </section>
234     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20