/[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 - (hide 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 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.16 <!-- $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 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.16 <version>9</version>
17     <date>2011-08-13</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     config_eth0=(
79 swift 1.7 "192.168.0.2/24"
80     "192.168.0.3/24"
81     "192.168.0.4/24"
82 swift 1.1 )
83    
84     <comment># Adding an IPv4 address and two IPv6 addresses</comment>
85     config_eth0=(
86 swift 1.7 "192.168.0.2/24"
87     "4321:0:1:2:3:4:567:89ab"
88     "4321:0:1:2:3:4:567:89ac"
89 swift 1.1 )
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 swift 1.7 "noop"
96     "dhcp"
97 swift 1.1 )
98     fallback_eth0=(
99 swift 1.7 "null"
100     "apipa"
101 swift 1.1 )
102     </pre>
103    
104     <note>
105 jkt 1.11 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 swift 1.1 </note>
111    
112     <impo>
113 jkt 1.11 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 swift 1.1 </impo>
117    
118     <note>
119 jkt 1.10 <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 swift 1.1 </note>
122    
123     </body>
124     </section>
125     <section>
126     <title>Network Dependencies</title>
127     <body>
128    
129 swift 1.5 <p>
130     Init scripts in <path>/etc/init.d</path> can depend on a specific network
131 swift 1.16 interface or just net. All network interfaces in Gentoo's init system provide
132     what is called <e>net</e>.
133 swift 1.1 </p>
134    
135 swift 1.16 <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 swift 1.1
149     <p>
150 jkt 1.11 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 swift 1.1 </p>
156    
157     <p>
158 swift 1.16 The answer is defining an <c>rc_need_</c> setting in
159 jkt 1.11 <path>/etc/conf.d/net</path>.
160 swift 1.1 </p>
161    
162     <pre caption="net.br0 dependency in /etc/conf.d/net">
163 swift 1.16 rc_need_br0="net.eth0 net.eth1"
164 swift 1.1 </pre>
165    
166     <p>
167 jkt 1.10 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 swift 1.16 Handbook. More information about <path>/etc/rc.conf</path> is available as
170     comments within that file.
171 swift 1.1 </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 fox2mike 1.3 Variable names are dynamic. They normally follow the structure of
182 swift 1.1 <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 jkt 1.11 connects to the ESSID "essid".
186 swift 1.1 </p>
187    
188     <p>
189     However, there is no hard and fast rule that states interface names must be
190 swift 1.5 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 swift 1.1 </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 jkt 1.11 into a <c>_</c> character.
202 swift 1.1 </p>
203    
204     <p>
205 fox2mike 1.3 Another downside of bash is the content of variables - some characters need to
206 jkt 1.11 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 swift 1.6 to be escaped in this way: <c>"</c>, <c>'</c> and <c>\</c>.
209 swift 1.1 </p>
210    
211     <p>
212     In this example we use wireless ESSID as they can contain the widest scope
213 swift 1.6 of characters. We shall use the ESSID <c>My "\ NET</c>:
214 swift 1.1 </p>
215    
216     <pre caption="variable name example">
217 nightmorph 1.14 <comment>(This does work, but the domain is invalid)</comment>
218 swift 1.1 dns_domain_My____NET="My \"\\ NET"
219    
220 nightmorph 1.14 <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 swift 1.1 </pre>
223    
224     </body>
225     </section>
226     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20