/[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.18 - (hide annotations) (download) (as text)
Fri Aug 19 16:07:30 2011 UTC (3 years ago) by swift
Branch: MAIN
Changes since 1.17: +3 -5 lines
File MIME type: application/xml
Remove trailing ) from code listings, thanks to nimiux for spotting them

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

  ViewVC Help
Powered by ViewVC 1.1.20