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-advanced.xml,v 1.7 2005/06/14 10:16:47 swift Exp $ -->

<sections>

<version>1.1</version>
<date>2005-06-14</date>

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

<p>
Four functions can be defined which will be called surrounding the
start/stop 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 preup and predown functions should be 0
(success) to indicate that configuration or deconfiguration of the
interface can continue.  If preup returns a non-zero value, then
interface configuration will be aborted.  If predown returns a
non-zero value, then the interface will not be allowed to continue
deconfiguration.
</p>

<p>
The return values for the postup and postdown 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 mii-diag
  # package to be installed.</comment>
  if mii-tool ${IFACE} 2> /dev/null | grep -q 'no link'; then
    ewarn "No link on ${IFACE}, aborting configuration"
    return 1
  fi

  <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 postup() 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 preassociate function should be 0
(success) to indicate that configuration or deconfiguration of the
interface can continue.  If preassociate returns a non-zero value, then
interface configuration will be aborted.
</p>

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