en/handbook/hb-net-functions.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-functions.xml,v 1.12 2010/05/14 22:12:57 nightmorph Exp $ -->

<sections>

<abstract>
If you're feeling adventurous, you can add your own functions to networking.
</abstract>

<version>9</version>
<date>2011-10-30</date>

<section>
<title>Standard function hooks</title>
<body>

<p>
Four functions can be defined in <path>/etc/conf.d/net</path> which will be
called surrounding the <c>start</c>/<c>stop</c> operations.  The functions are
called with the interface name first so that one function can control multiple
adapters.
</p>

<p>
The return values for the <c>preup()</c> and <c>predown()</c> functions should
be 0 (success) to indicate that configuration or deconfiguration of the
interface can continue. If <c>preup()</c> returns a non-zero value, then
interface configuration will be aborted. If <c>predown()</c> returns a non-zero
value, then the interface will not be allowed to continue deconfiguration.
</p>

<p>
The return values for the <c>postup()</c> and <c>postdown()</c> functions are
ignored since there's nothing to do if they indicate failure.
</p>

<p>
<c>${IFACE}</c> is set to the interface being brought up/down. <c>${IFVAR}</c>
is <c>${IFACE}</c> converted to variable name bash allows.
</p>

<pre caption="pre/post up/down function examples in /etc/conf.d/net">
preup() {
  <comment># Test for link on the interface prior to bringing it up.  This
  # only works on some network adapters and requires the ethtool
  # package to be installed.</comment>
  if ethtool ${IFACE} | grep -q 'Link detected: no'; then
    ewarn "No link on ${IFACE}, aborting configuration"
    return 1
  fi

  <comment># Remember to return 0 on success</comment>
  return 0
}

predown() {
  <comment># The default in the script is to test for NFS root and disallow
  # downing interfaces in that case.  Note that if you specify a
  # predown() function you will override that logic.  Here it is, in
  # case you still want it...</comment>
  if is_net_fs /; then
    eerror "root filesystem is network mounted -- can't stop ${IFACE}"
    return 1
  fi

  <comment># Remember to return 0 on success</comment>
  return 0
}

postup() {
  <comment># This function could be used, for example, to register with a
  # dynamic DNS service.  Another possibility would be to
  # send/receive mail once the interface is brought up.</comment>
       return 0
}

postdown() {
  <comment># This function is mostly here for completeness... I haven't
  # thought of anything nifty to do with it yet ;-)</comment>
  return 0
}
</pre>

<note>
For more information on writing your own functions, please read
<path>/usr/share/doc/openrc-*/net.example.bz2</path>.
</note>

</body>
</section>
<section>
<title>Wireless Tools function hooks</title>
<body>

<note>
This will not work with WPA Supplicant - but the <c>${ESSID}</c> and
<c>${ESSIDVAR}</c> variables are available in the <c>postup()</c> function.
</note>

<p>
Two functions can be defined in <path>/etc/conf.d/net</path> which will be
called surrounding the associate function. The functions are called with the
interface name first so that one function can control multiple adapters.
</p>

<p>
The return values for the <c>preassociate()</c> function should be 0 (success)
to indicate that configuration or deconfiguration of the interface can continue.
If <c>preassociate()</c> returns a non-zero value, then interface configuration
will be aborted.
</p>

<p>
The return value for the <c>postassociate()</c> function is ignored since
there's nothing to do if it indicates failure.
</p>

<p>
<c>${ESSID}</c> is set to the exact ESSID of the AP you're connecting to. 
<c>${ESSIDVAR}</c> is <c>${ESSID}</c> converted to a variable name bash allows.
</p>

<pre caption="pre/post association functions in /etc/conf.d/net">
preassociate() {
  <comment># The below adds two configuration variables leap_user_ESSID
  # and leap_pass_ESSID. When they are both configured for the ESSID
  # being connected to then we run the CISCO LEAP script</comment>

  local user pass
  eval user=\"\$\{leap_user_${ESSIDVAR}\}\"
  eval pass=\"\$\{leap_pass_${ESSIDVAR}\}\"

  if [[ -n ${user} &amp;&amp; -n ${pass} ]]; then
    if [[ ! -x /opt/cisco/bin/leapscript ]]; then
      eend "For LEAP support, please emerge net-misc/cisco-aironet-client-utils"
      return 1
    fi
    einfo "Waiting for LEAP Authentication on \"${ESSID//\\\\//}\""
    if /opt/cisco/bin/leapscript ${user} ${pass} | grep -q 'Login incorrect'; then
      ewarn "Login Failed for ${user}"
      return 1
    fi
  fi

  return 0
}

postassociate() {
  <comment># This function is mostly here for completeness... I haven't
  # thought of anything nifty to do with it yet ;-)</comment>

  return 0
}
</pre>

<note>
<c>${ESSID}</c> and <c>${ESSIDVAR}</c> are unavailable in <c>predown()</c> and
<c>postdown()</c> functions.
</note>

<note>
For more information on writing your own functions, please read
<path>/usr/share/doc/openrc-*/net.example.bz2</path>.
</note>

</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.2	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6	swift	1.1
7	swift	1.13	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-net-functions.xml,v 1.12 2010/05/14 22:12:57 nightmorph Exp $ -->
8	neysx	1.5
9	swift	1.1	<sections>
10
11	neysx	1.9	<abstract>
12			If you're feeling adventurous, you can add your own functions to networking.
13			</abstract>
14
15	swift	1.13	<version>9</version>
16			<date>2011-10-30</date>
17	swift	1.1
18			<section>
19			<title>Standard function hooks</title>
20			<body>
21
22			<p>
23	nightmorph	1.12	Four functions can be defined in <path>/etc/conf.d/net</path> which will be
24			called surrounding the <c>start</c>/<c>stop</c> operations. The functions are
25			called with the interface name first so that one function can control multiple
26			adapters.
27	swift	1.1	</p>
28
29			<p>
30	jkt	1.7	The return values for the <c>preup()</c> and <c>predown()</c> functions should
31			be 0 (success) to indicate that configuration or deconfiguration of the
32			interface can continue. If <c>preup()</c> returns a non-zero value, then
33			interface configuration will be aborted. If <c>predown()</c> returns a non-zero
34			value, then the interface will not be allowed to continue deconfiguration.
35	swift	1.1	</p>
36
37			<p>
38	jkt	1.7	The return values for the <c>postup()</c> and <c>postdown()</c> functions are
39			ignored since there's nothing to do if they indicate failure.
40	swift	1.1	</p>
41
42			<p>
43	jkt	1.6	<c>${IFACE}</c> is set to the interface being brought up/down. <c>${IFVAR}</c>
44			is <c>${IFACE}</c> converted to variable name bash allows.
45	swift	1.1	</p>
46
47	nightmorph	1.12	<pre caption="pre/post up/down function examples in /etc/conf.d/net">
48	swift	1.1	preup() {
49	swift	1.4	<comment># Test for link on the interface prior to bringing it up. This
50			# only works on some network adapters and requires the ethtool
51			# package to be installed.</comment>
52			if ethtool ${IFACE} \| grep -q 'Link detected: no'; then
53			ewarn "No link on ${IFACE}, aborting configuration"
54			return 1
55			fi
56	swift	1.1
57	swift	1.4	<comment># Remember to return 0 on success</comment>
58			return 0
59	swift	1.1	}
60
61			predown() {
62	swift	1.4	<comment># The default in the script is to test for NFS root and disallow
63			# downing interfaces in that case. Note that if you specify a
64			# predown() function you will override that logic. Here it is, in
65			# case you still want it...</comment>
66			if is_net_fs /; then
67			eerror "root filesystem is network mounted -- can't stop ${IFACE}"
68			return 1
69			fi
70	swift	1.1
71	swift	1.4	<comment># Remember to return 0 on success</comment>
72			return 0
73	swift	1.1	}
74
75			postup() {
76	swift	1.4	<comment># This function could be used, for example, to register with a
77			# dynamic DNS service. Another possibility would be to
78			# send/receive mail once the interface is brought up.</comment>
79	swift	1.1	return 0
80			}
81
82			postdown() {
83	swift	1.4	<comment># This function is mostly here for completeness... I haven't
84			# thought of anything nifty to do with it yet ;-)</comment>
85			return 0
86	swift	1.1	}
87			</pre>
88
89	nightmorph	1.12	<note>
90			For more information on writing your own functions, please read
91	swift	1.13	<path>/usr/share/doc/openrc-*/net.example.bz2</path>.
92	nightmorph	1.12	</note>
93
94	swift	1.1	</body>
95			</section>
96			<section>
97			<title>Wireless Tools function hooks</title>
98			<body>
99
100			<note>
101			This will not work with WPA Supplicant - but the <c>${ESSID}</c> and
102	jkt	1.7	<c>${ESSIDVAR}</c> variables are available in the <c>postup()</c> function.
103	swift	1.1	</note>
104
105			<p>
106	nightmorph	1.12	Two functions can be defined in <path>/etc/conf.d/net</path> which will be
107			called surrounding the associate function. The functions are called with the
108			interface name first so that one function can control multiple adapters.
109	swift	1.1	</p>
110
111			<p>
112	jkt	1.7	The return values for the <c>preassociate()</c> function should be 0 (success)
113			to indicate that configuration or deconfiguration of the interface can continue.
114			If <c>preassociate()</c> returns a non-zero value, then interface configuration
115			will be aborted.
116	swift	1.1	</p>
117
118			<p>
119	jkt	1.7	The return value for the <c>postassociate()</c> function is ignored since
120			there's nothing to do if it indicates failure.
121	swift	1.1	</p>
122
123			<p>
124	swift	1.3	<c>${ESSID}</c> is set to the exact ESSID of the AP you're connecting to.
125	nightmorph	1.12	<c>${ESSIDVAR}</c> is <c>${ESSID}</c> converted to a variable name bash allows.
126	swift	1.1	</p>
127
128	nightmorph	1.12	<pre caption="pre/post association functions in /etc/conf.d/net">
129	swift	1.1	preassociate() {
130	swift	1.4	<comment># The below adds two configuration variables leap_user_ESSID
131			# and leap_pass_ESSID. When they are both configured for the ESSID
132			# being connected to then we run the CISCO LEAP script</comment>
133
134			local user pass
135			eval user=\"\$\{leap_user_${ESSIDVAR}\}\"
136			eval pass=\"\$\{leap_pass_${ESSIDVAR}\}\"
137
138			if [[ -n ${user} && -n ${pass} ]]; then
139			if [[ ! -x /opt/cisco/bin/leapscript ]]; then
140			eend "For LEAP support, please emerge net-misc/cisco-aironet-client-utils"
141			return 1
142			fi
143			einfo "Waiting for LEAP Authentication on \"${ESSID//\\\\//}\""
144			if /opt/cisco/bin/leapscript ${user} ${pass} \| grep -q 'Login incorrect'; then
145			ewarn "Login Failed for ${user}"
146			return 1
147			fi
148			fi
149	swift	1.1
150	swift	1.4	return 0
151	swift	1.1	}
152
153			postassociate() {
154	swift	1.4	<comment># This function is mostly here for completeness... I haven't
155			# thought of anything nifty to do with it yet ;-)</comment>
156	swift	1.1
157	swift	1.4	return 0
158	swift	1.1	}
159			</pre>
160
161			<note>
162	jkt	1.7	<c>${ESSID}</c> and <c>${ESSIDVAR}</c> are unavailable in <c>predown()</c> and
163			<c>postdown()</c> functions.
164	swift	1.1	</note>
165
166	nightmorph	1.12	<note>
167			For more information on writing your own functions, please read
168	swift	1.13	<path>/usr/share/doc/openrc-*/net.example.bz2</path>.
169	nightmorph	1.12	</note>
170
171	swift	1.1	</body>
172			</section>
173
174			</sections>