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.15 2009/02/13 04:40:27 nightmorph Exp $ -->

<sections>

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

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