en/handbook/hb-net-advanced.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-advanced.xml,v 1.17 2011/08/17 08:05:11 swift Exp $ -->

<sections>

<abstract>
Here we learn about how the configuration works - you need to know this
before we learn about modular networking.
</abstract>

<version>11</version>
<date>2011-08-19</date>

<section>
<title>Advanced Configuration</title>
<body>

<p>
The <c>config_eth0</c> variable is the heart of an interface configuration. It's
a high level instruction list for configuring the interface (<c>eth0</c> in this
case). Each command in the instruction list is performed sequentially. The
interface is deemed OK if at least one command works.
</p>

<p>
Here's a list of built-in instructions.
</p>

<table>
<tr>
  <th>Command</th>
  <th>Description</th>
</tr>
<tr>
  <ti><c>null</c></ti>
  <ti>Do nothing</ti>
</tr>
<tr>
  <ti><c>noop</c></ti>
  <ti>
    If the interface is up and there is an address then abort configuration
    successfully
  </ti>
</tr>
<tr>
  <ti>an IPv4 or IPv6 address</ti>
  <ti>Add the address to the interface</ti>
</tr>
<tr>
  <ti>
    <c>dhcp</c>, <c>adsl</c> or <c>apipa</c> (or a custom command from a 3rd
    party module)
  </ti>
  <ti>
    Run the module which provides the command. For example <c>dhcp</c> will run
    a module that provides DHCP which can be one of either <c>dhcpcd</c>,
    <c>dhclient</c> or <c>pump</c>.
  </ti>
</tr>
</table>

<p>
If a command fails, you can specify a fallback command. The fallback has to
match the config structure exactly.
</p>

<p>
You can chain these commands together. Here are some real world examples.
</p>

<pre caption="Configuration examples">
<comment># Adding three IPv4 addresses</comment>
config_eth0="192.168.0.2/24
192.168.0.3/24
192.168.0.4/24"

<comment># Adding an IPv4 address and two IPv6 addresses</comment>
config_eth0="192.168.0.2/24
4321:0:1:2:3:4:567:89ab
4321:0:1:2:3:4:567:89ac"

<comment># Keep our kernel assigned address, unless the interface goes
# down so assign another via DHCP. If DHCP fails then add a
# static address determined by APIPA</comment>
config_eth0="noop
dhcp"
fallback_eth0="null
apipa"
</pre>

<note>
When using the <c>ifconfig</c> module and adding more than one address,
interface aliases are created for each extra address. So with the above two
examples you will get interfaces <c>eth0</c>, <c>eth0:1</c> and <c>eth0:2</c>.
You cannot do anything special with these interfaces as the kernel and other
programs will just treat <c>eth0:1</c> and <c>eth0:2</c> as <c>eth0</c>.
</note>

<impo>
The fallback order is important! If we did not specify the <c>null</c> option
then the <c>apipa</c> command would only be run if the <c>noop</c> command
failed.
</impo>

<note>
<uri link="?part=4&amp;chap=3#apipa">APIPA</uri> and <uri
link="?part=4&amp;chap=3#dhcp">DHCP</uri> are discussed later.
</note>

</body>
</section>
<section>
<title>Network Dependencies</title>
<body>

<p>
Init scripts in <path>/etc/init.d</path> can depend on a specific network
interface or just net. All network interfaces in Gentoo's init system provide
what is called <e>net</e>.
</p>

<p>
If, in <path>/etc/rc.conf</path>, <c>rc_depend_strict="YES"</c> is set, then all
network interfaces that provide net must be active before a dependency on "net"
is assumed to be met. In other words, if you have a <path>net.eth0</path> and
<path>net.eth1</path> and an init script depends on "net", then both must be
enabled.
</p>

<p>
On the other hand, if <c>rc_depend_strict="NO"</c> is set, then the "net"
dependency is marked as resolved the moment at least one network interface is
brought up.
</p>

<p>
But what about <path>net.br0</path> depending on <path>net.eth0</path> and
<path>net.eth1</path>? <path>net.eth1</path> may be a wireless or PPP device
that needs configuration before it can be added to the bridge. This cannot be
done in <path>/etc/init.d/net.br0</path> as that's a symbolic link to
<path>net.lo</path>.
</p>

<p>
The answer is defining an <c>rc_need_</c> setting in
<path>/etc/conf.d/net</path>.
</p>

<pre caption="net.br0 dependency in /etc/conf.d/net">
rc_need_br0="net.eth0 net.eth1"
</pre>

<p>
That alone, however, is not sufficient. Gentoo's networking init scripts use a
virtual dependency called <e>net</e> to inform the system when networking is
available. Clearly, in the above case, networking should only be marked as
available when <path>net.br0</path> is up, not when the others are. So we need
to tell that in <path>/etc/conf.d/net</path> as well:
</p>

<pre caption="Updating virtual dependencies and provisions for networking">
rc_net_lo_provide="!net"
rc_net_eth0_provide="!net"
rc_net_eth1_provide="!net"
</pre>

<p>
For a more detailed discussion about dependency, consult the section <uri
link="?part=2&amp;chap=4#doc_chap4">Writing Init Scripts</uri> in the Gentoo
Handbook. More information about <path>/etc/rc.conf</path> is available as
comments within that file.
</p>

</body>
</section>

<section id="variable_name">
<title>Variable names and values</title>
<body>

<p>
Variable names are dynamic. They normally follow the structure of
<c>variable_${interface|mac|essid|apmac}</c>. For example, the variable
<c>dhcpcd_eth0</c> holds the value for dhcpcd options for eth0 and
<c>dhcpcd_essid</c> holds the value for dhcpcd options when any interface
connects to the ESSID "essid".
</p>

<p>
However, there is no hard and fast rule that states interface names must be
ethx. In fact, many wireless interfaces have names like wlanx, rax as well as 
ethx. Also, some user defined interfaces such as bridges can be given any name,
such as foo. To make life more interesting, wireless Access Points can have 
names with non alpha-numeric characters in them - this is important because 
you can configure networking parameters per ESSID.
</p>

<p>
The downside of all this is that Gentoo uses bash variables for networking -
and bash cannot use anything outside of English alpha-numerics. To get around
this limitation we change every character that is not an English alpha-numeric
into a <c>_</c> character.
</p>

<p>
Another downside of bash is the content of variables - some characters need to
be escaped. This can be achived by placing the <c>\</c> character in front of
the character that needs to be escaped. The following list of characters needs
to be escaped in this way: <c>"</c>, <c>'</c> and  <c>\</c>.
</p>

<p>
In this example we use wireless ESSID as they can contain the widest scope
of characters. We shall use the ESSID <c>My "\ NET</c>:
</p>

<pre caption="variable name example">
<comment>(This does work, but the domain is invalid)</comment>
dns_domain_My____NET="My \"\\ NET"

<comment>(The above sets the dns domain to My "\ NET when a wireless card
connects to an AP whose ESSID is My "\ NET)</comment>
</pre>

</body>
</section>
</sections>
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&chap=3#apipa">APIPA</uri> and <uri
112			link="?part=4&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&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>