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.10 2007/03/07 01:00:20 nightmorph Exp $ -->

<sections>

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

<version>8.0</version>
<date>2007-05-07</date>

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

<p>
Four functions can be defined 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">
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>

</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 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 variable name bash allows.
</p>

<pre caption="pre/post association functions">
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>

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