source: freewrt/Docs/fwifupdown/fwifupdown.txt@ 727dae0d

Last change on this file since 727dae0d was 4c593d5, checked in by Thorsten Glaser <tg@…>, 18 years ago

these annoy me while tab-completing, use caps for stuff that isn't used by ADK

git-svn-id: ​svn://www.freewrt.org/trunk/freewrt@2851 afb5a338-a214-0410-bd46-81f09a774fd1
  • Property mode set to 100644
File size: 10.7 KB
Line 
1FreeWRT ifupdown (fwifupdown) (fwifupdown_0.2-1)
2
3FreeWRT ifupdown is not a replacement for busybox ifupdown. It's a set of
4scripts using busybox ifupdown to enhance it's capabilities.
5
6
71. Features
8
9 The major goal of fwifupdown is the handling of network device dependencies.
10 It provides status information to syslog and STDOUT as well.
11
12
132. Supported device types
14
15 Fwifupdown tries to figure out the type of given interface either from given
16 config or from information given by the system (/proc, various system tools).
17
18 2.1 Legacy interface support
19
20 This is the default, if no other device type can be figured out, the ifupdown
21 behavior is equal to busybox ifupdown.
22
23 2.2 IP alias support
24
25 Alias interfaces are figured out by its name foo:*
26 Only static configuration method is supported because all others make no
27 sense.
28
29 2.3 VLAN support
30
31 VLAN interfaces from name eth*.* are supported, all other not.
32 All configuration methods provided by busybox are supported.
33
34 2.3.1 Config variables (/etc/network/interfaces)
35
36 switch-ports
37 priority: base
38 value: list of switch ports
39 default: empty
40
41
42 2.4 Bridge support
43
44 Bridge interfaces from every name are supported.
45 All configuration methods provided by busybox are supported.
46
47 2.4.1 Config variables (/etc/network/interfaces)
48
49 bridge-ifaces
50 priority: base if you like to add bridge interfaces
51 value: list of interface names
52 default: empty
53
54
55 2.5 Tuntap support
56
57 Tuntap interfaces from name tun|tap are supported, all other not.
58 All configuration methods provided by busybox are supported.
59 Tuntap interfaces can be created by tunctl or openvpn.
60
61 2.5.1 Config variables (/etc/network/interfaces)
62
63 tuntap
64 priority: optional
65 value: tunctl | openvpn
66 default: tunctl
67
68 tuntap-user
69 priority: optional
70 value: tunctl -u option
71 default: 0
72
73
74 2.6 PPP support
75
76 PPP is not supported at the moment.
77
78 2.7 Wireless support
79
80 Only broadcom wireless is supported at the moment.
81 All configuration methods provided by busybox should work.
82
83
843. Supported interface configuration methods
85
86 All configuration methods provided by busybox are supported because
87 busybox does this job if nothing else is stated below.
88
89 3.1 DHCP support
90
91 The default dhcp client is busybox udhcpc, if nothing else is configured or
92 the configured client is not present.
93
94 3.1.1 Config variables (/etc/network/interfaces)
95
96 3.1.1.1 Global config variables
97
98 dhcp-client
99 priority: optional
100 value: executable of your choice
101
102 dhcp-client-opts
103 priority: optional
104 value: dhcp client command line opts
105
106 3.1.1.2 udhcpc config variables
107
108 hostname
109 priority: optional
110
111 clientid
112 priority: optional
113
114 script
115 priority: optional
116
117
1184. Network configuration
119
120 The network configuration file is /etc/network/interfaces, filestructure
121 and syntax are equal to the old busybox network configuration.
122
123 There's one difference: There is no need to tag all needed devices as
124 "auto", only the main devices must be tagged, not the devices they depend
125 on.
126
127 4.1 Example configuration with wireless bridging and openvpn tunnel
128
129 # file /etc/network/interfaces
130 #
131 auto lo
132 iface lo inet loopback
133
134 # LAN
135 auto br0
136 iface br0 inet static
137 address 192.168.1.1
138 netmask 255.255.255.0
139 broadcast +
140 bridge-ifaces wl0 tap0 eth0.0
141
142 # WAN
143 auto eth0.1
144 iface eth0.1 inet dhcp
145 switch-ports 0 5
146 dhcp-client dhcpcd
147 dhcp-client-opts -t 45
148
149 iface eth0.0 inet static
150 switch-ports 1 2 3 4 5*
151 address 0.0.0.0
152 netmask 255.255.255.255
153 broadcast +
154
155 iface tap0 inet static
156 tuntap openvpn
157 address 0.0.0.0
158 netmask 255.255.255.255
159 broadcast +
160
161 iface wl0 inet static
162 address 0.0.0.0
163 netmask 255.255.255.255
164 broadcast +
165 wireless-type broadcom
166 wireless-country DE
167 wireless-mode ap
168 wireless-ssid FreeWRT
169 wireless-channel 11
170 wireless-security wpa-psk
171 wireless-authorization psk
172 wireless-encryption tkip
173 wireless-wpa-key MyWpaKey
174 wireless-wpa-gtk-rekey 3600
175
176 ### end configuration ###
177
178 4.2 Inline hooks
179
180 Configuration file inline hooks are possible, see FreeWRT handbook.
181
182
1835. fwifupdown configuration
184
185 The fwifupdown configuration file is /etc/conf.d/ifupdown.
186
187 5.1 Configuration variables
188
189 CFG_BUSYBOX_COMPAT
190 To activate usage of fwifupdown instead of busybox ifupdown comment
191 this or set to something but not 1
192 If CFG_BUSYBOX_COMPAT is set to 1 (which is the default) then the
193 fwifupdown behavior is exactly like the busybox ifupdown behavior
194 because no fwifupdown code will be executed.
195
196 CFG_PRINTING_OFF
197 To disable printing to STDOUT set this to 1
198
199 CFG_SYSLOG_OFF
200 To disable logging to syslog set this to 1
201
202
2036. Development
204
205 6.1 How it works
206
207 Fwifupdown replaces the ifup and ifdown links to busybox with links to
208 /opt/ifupdown/bin/ifupdown.sh at system starttime.
209
210 Ifupdown checks at runtime /etc/conf.d/ifupdown for CFG_BUSYBOX_COMPAT=1 and
211 calls either busybox ifupdown or FreeWRT ifupdown. This is useful for
212 migration and testing. The default is busybox ifupdown.
213
214 If fwifupdown is used the hook directories /etc/network/if-* will be overlayed
215 (mount --bind) with /opt/ifupdown/hook/ to avoid network misconfigurations.
216
217 All device type specific stuff is located in /opt/ifupdown/lib/ or in
218 /etc/network/lib/ which overlays /opt/ifupdown/lib/.
219
220 Hooks in /etc/network/if-* are obsolete now and will never been called.
221
222
223 6.2 Hook scripts
224
225 Hooks are located in /opt/ifupdown/lib/ or /etc/network/lib.
226 /etc/network/lib always overlays /opt/ifupdown/lib.
227
228 The script name specifies the interface type.
229
230
231 6.2.1 Main functions
232
233 Hook scripts must contain at least one function named iface_type() to identify
234 the interface type or they will ignored.
235
236 iface_type()
237 Add code here to figure out the interface type.
238 This function is mandatory.
239
240 if_preup()
241 If you like to do things before bringing up the interface add code
242 here.
243 This function is optional.
244
245 if_up()
246 If you like to do things after bringing up the interface add code
247 here.
248 This function is optional.
249
250 if_down()
251 If you like to do things before bringing down the interface add code
252 here.
253 This function is optional.
254
255 if_postdown()
256 If you like to do things after bringing down the interface add code
257 here.
258 This function is optional.
259
260
261 6.2.2 How to return from above functions
262
263 There are six possibilities to leave above functions.
264
265 return 0
266 Use this if you like to indicate success.
267 This is what you want mostly.
268
269 return != 0
270 Use this if you like to indicate no success.
271 If one of the above functions returns with no success the appropriate
272 fail function (see below) will be called.
273 This is what you want mostly.
274
275 exit 0
276 That's the same like builtin exit 0
277
278 exit != 0
279 Use this if you like to stop execution of fwifupdown code and you like
280 to bypass further execution of busybox ifupdown.c code as well as
281 further execution of fwifupdown code.
282 This breaks recursive ifupdown which is used to handle dependencies.
283 Do this only if you are a bit familar with busybox ifupdown.c
284
285 builtin exit 0
286 Use this if you like to stop execution of fwifupdown code and continue
287 directly with further busybox ifupdown.c code.
288 Do this only if you are a bit familar with busybox ifupdown.c
289
290 builtin exit != 0
291 Use this if you like to stop execution of fwifupdown code and you like
292 to bypass further execution of busybox ifupdown.c code.
293 Do this only if you are a bit familar with busybox ifupdown.c
294
295
296 6.2.3 Failsafe
297
298 You can use the functions below if you like to add failsafe code.
299
300 fail_preup()
301 If you like to do things if the appropriate main function returns with
302 no sucess add code here.
303 This function is optional.
304
305 fail_up()
306 If you like to do things if the appropriate main function returns with
307 no sucess add code here.
308 This function is optional.
309
310 fail_down()
311 If you like to do things if the appropriate main function returns with
312 no sucess add code here.
313 This function is optional.
314
315 fail_postdown()
316 If you like to do things if the appropriate main function returns with
317 no sucess add code here.
318 This function is optional.
319
320 6.2.4 Runtime configuration variables
321
322 There are some runtime configuration variables which may be useful in some
323 cases.
324
325 RT_PREUP_PRINTING_OFF
326 If you don't like the default printing to STDOUT and logging to syslog
327 switch it off by setting this to 1
328
329 RT_UP_PRINTING_OFF
330 If you don't like the default printing to STDOUT and logging to syslog
331 switch it off by setting this to 1
332
333 RT_DOWN_PRINTING_OFF
334 If you don't like the default printing to STDOUT and logging to syslog
335 switch it off by setting this to 1
336
337 RT_POSTDOWN_PRINTING_OFF
338 If you don't like the default printing to STDOUT and logging to syslog
339 switch it off by setting this to 1
340
341 RT_PREUP_IFUP_CHECK_OFF
342 If you don't like the initial "interface up check" proceed by ifup
343 simply switch it off by setting this to 1
344
345 RT_UP_IFUP_CHECK_OFF
346 If you don't like the "interface up check" proceed by ifup after the
347 interface should be gone up simply switch it off by setting this to 1
348
349 RT_POSTDOWN_IFDOWN_CHECK_OFF
350 If you don't like the "interface down check" proceed by ifdown after the
351 interface should be gone down simply switch it off by setting this to 1
352
353 RT_BB_NOEXEC
354 If you like to prevent further execution of busybox ifupdown.c code
355 after passing the fwifupdown main_ifupdown code set this to 1.
356
357
358 6.2.5 Other script variables
359
360 The following variables are set by fwifupdown:
361
362 ENVFILE
363 script environment temp file (ipc for recursive ifupdown calls)
364
365 LIBDIR
366 library directory (/opt/ifupdown/lib/)
367
368 LIBDIR_OVERLAY
369 library overlay directory (/etc/network/lib/)
370
371 IF_FOO*
372 interface config vars form /etc/network/interfaces
373
374 ADDRFAM
375 address family
376
377 METHOD
378 parameter 'method' from /etc/network/interfaces (manual, wvdial, ppp,
379 static, bootp, dhcp, loopback)
380
381 PATH
382 $PATH passed to busybox
383
384 IFUPDOWN_ENV
385 $IFUPDOWN_ENV passed to busybox
386
387 IFACE
388 interface name
389
390 PARENT_IFACE
391 interface name of parent interface
392
393 IFACE_TYPE
394 the interface type (vlan, bridge, iface, ...)
395
396 PARENT_IFACE_TYPE
397 parent interface type
398
399 IFACE_STATE
400 the initial interface state (up | down)
401
402 H_ERR
403 set to 1 if an handler error occured
404
405 MODE
406 ifupdown mode (start, stop)
407
408 SUBMODE
409 ifupdown submode (if-pre-up, if-up, if-down, if-post-down)
410
411 GOOD
412 ansi escape color definition
413
414 WARN
415 ansi escape color definition
416
417 BAD
418 ansi escape color definition
419
420 HILITE
421 ansi escape color definition
422
423 BRACKET
424 ansi escape color definition
425
426 NORMAL
427 ansi escape color definition
428
429 TAB
430 tab width (n spaces)
431
432 ENDCOL
433 ansi escape position definition (end column)
434
435 FIRSTCOL
436 ansi escape position definition (fist column)
437
438 MP_GOOD
439 message prefix "good"
440
441 MP_BAD
442 message prefix "bad"
443
444 MP_NONE
445 message prefix "none"
446
447 ME_GOOD
448 message end "good"
449
450 ME_BAD
451 message end "bad"
452
453# vim:ts=4
Note: See TracBrowser for help on using the repository browser.