FreeWRT ifupdown (fwifupdown) (fwifupdown_0.2-1)

FreeWRT ifupdown is not a replacement for busybox ifupdown. It's a set of
scripts using busybox ifupdown to enhance it's capabilities.


1. Features

	The major goal of fwifupdown is the handling of network device dependencies.
	It provides status information to syslog and STDOUT as well.


2. Supported device types

	Fwifupdown tries to figure out the type of given interface either from given
	config or from information given by the system (/proc, various system tools).

	2.1 Legacy interface support

	This is the default, if no other device type can be figured out, the ifupdown
	behavior is equal to busybox ifupdown.

	2.2 IP alias support

	Alias interfaces are figured out by its name foo:*
	Only static configuration method is supported because all others make no
	sense.

	2.3 VLAN support

	VLAN interfaces from name eth*.* are supported, all other not.
	All configuration methods provided by busybox are supported.

	2.3.1 Config variables (/etc/network/interfaces)

	switch-ports
		priority:	base
		value:		list of switch ports
		default:	empty


	2.4 Bridge support

	Bridge interfaces from every name are supported.
	All configuration methods provided by busybox are supported.

	2.4.1 Config variables (/etc/network/interfaces)

	bridge-ifaces
		priority:	base if you like to add bridge interfaces
		value:		list of interface names
		default:	empty


	2.5 Tuntap support

	Tuntap interfaces from name tun|tap are supported, all other not.
	All configuration methods provided by busybox are supported.
	Tuntap interfaces can be created by tunctl or openvpn.

	2.5.1 Config variables (/etc/network/interfaces)

	tuntap
		priority: 	optional
		value:		tunctl | openvpn
		default:	tunctl

	tuntap-user
		priority:	optional
		value:		tunctl -u option
		default:	0


	2.6 PPP support

	PPP is not supported at the moment.

	2.7 Wireless support

	Only broadcom wireless is supported at the moment.
	All configuration methods provided by busybox should work.


3. Supported interface configuration methods

	All configuration methods provided by busybox are supported because
	busybox does this job if nothing else is stated below.

	3.1 DHCP support

	The default dhcp client is busybox udhcpc, if nothing else is configured or
	the configured client is not present.

	3.1.1 Config variables (/etc/network/interfaces)

	3.1.1.1 Global config variables

	dhcp-client
		priority: 	optional
		value:		executable of your choice

	dhcp-client-opts
		priority:	optional
		value:		dhcp client command line opts
		
	3.1.1.2 udhcpc config variables

	hostname
		priority:	optional

	clientid
		priority:	optional

	script
		priority:	optional


4. Network configuration

	The network configuration file is /etc/network/interfaces, filestructure
	and syntax are equal to the old busybox network configuration.

	There's one difference: There is no need to tag all needed devices as
	"auto", only the main devices must be tagged, not the devices they depend
	on.

	4.1 Example configuration with wireless bridging and openvpn tunnel

	# file /etc/network/interfaces
	#
	auto lo
	iface lo inet loopback

	# LAN
	auto br0
	iface br0 inet static
		address 192.168.1.1
		netmask 255.255.255.0
		broadcast +
		bridge-ifaces wl0 tap0 eth0.0

	# WAN
	auto eth0.1
	iface eth0.1 inet dhcp
		switch-ports 0 5
		dhcp-client dhcpcd
		dhcp-client-opts -t 45

	iface eth0.0 inet static
		switch-ports 1 2 3 4 5*
		address 0.0.0.0
		netmask 255.255.255.255
		broadcast +

	iface tap0 inet static
        	tuntap openvpn
		address 0.0.0.0
		netmask 255.255.255.255
		broadcast +

	iface wl0 inet static
		address 0.0.0.0
		netmask 255.255.255.255
		broadcast +
		wireless-type broadcom
		wireless-country DE
		wireless-mode ap
		wireless-ssid FreeWRT
		wireless-channel 11
		wireless-security wpa-psk
		wireless-authorization psk
		wireless-encryption tkip
		wireless-wpa-key MyWpaKey
		wireless-wpa-gtk-rekey 3600
	
	### end configuration ###

	4.2 Inline hooks

	Configuration file inline hooks are possible, see FreeWRT handbook.


5. fwifupdown configuration

	The fwifupdown configuration file is /etc/conf.d/ifupdown.

	5.1 Configuration variables

	CFG_BUSYBOX_COMPAT
		To activate usage of fwifupdown instead of busybox ifupdown comment
		this or set to something but not 1
		If CFG_BUSYBOX_COMPAT is set to 1 (which is the default) then the
		fwifupdown behavior is exactly like the busybox ifupdown behavior
		because no fwifupdown code will be executed.

	CFG_PRINTING_OFF
		To disable printing to STDOUT set this to 1

	CFG_SYSLOG_OFF
		To disable logging to syslog set this to 1


6. Development

	6.1 How it works

	Fwifupdown replaces the ifup and ifdown links to busybox with links to
	/opt/ifupdown/bin/ifupdown.sh at system starttime.

	Ifupdown checks at runtime /etc/conf.d/ifupdown for CFG_BUSYBOX_COMPAT=1 and
	calls either busybox ifupdown or FreeWRT ifupdown. This is useful for
	migration and testing. The default is busybox ifupdown.

	If fwifupdown is used the hook directories /etc/network/if-* will be overlayed
	(mount --bind) with /opt/ifupdown/hook/ to avoid network misconfigurations.

	All device type specific stuff is located in /opt/ifupdown/lib/ or in
	/etc/network/lib/ which overlays /opt/ifupdown/lib/.

	Hooks in /etc/network/if-* are obsolete now and will never been called.


	6.2 Hook scripts

	Hooks are located in /opt/ifupdown/lib/ or /etc/network/lib.
	/etc/network/lib always overlays /opt/ifupdown/lib.

	The script name specifies the interface type.


	6.2.1 Main functions

	Hook scripts must contain at least one function named iface_type() to identify
	the interface type or they will ignored.

	iface_type()
		Add code here to figure out the interface type.
		This function is mandatory.

	if_preup()
		If you like to do things before bringing up the interface add code
		here.
		This function is optional.

	if_up()
		If you like to do things after bringing up the interface add code
		here.
		This function is optional.

	if_down()
		If you like to do things before bringing down the interface add code
		here.
		This function is optional.

	if_postdown()
		If you like to do things after bringing down the interface add code
		here.
		This function is optional.
	
	
	6.2.2 How to return from above functions

	There are six possibilities to leave above functions.

	return 0
		Use this if you like to indicate success.
		This is what you want mostly.

	return != 0
		Use this if you like to indicate no success.
		If one of the above functions returns with no success the appropriate
		fail function (see below) will be called.
		This is what you want mostly.
	
	exit 0
		That's the same like builtin exit 0

	exit != 0
		Use this if you like to stop execution of fwifupdown code and you like
		to bypass further execution of busybox ifupdown.c code as well as
		further execution of fwifupdown code.
		This breaks recursive ifupdown which is used to handle dependencies.
		Do this only if you are a bit familar with busybox ifupdown.c

	builtin exit 0
		Use this if you like to stop execution of fwifupdown code and continue
		directly with further busybox ifupdown.c code.
		Do this only if you are a bit familar with busybox ifupdown.c

	builtin exit != 0
		Use this if you like to stop execution of fwifupdown code and you like
		to bypass further execution of busybox ifupdown.c code.
		Do this only if you are a bit familar with busybox ifupdown.c


	6.2.3 Failsafe

	You can use the functions below if you like to add failsafe code.

	fail_preup()
		If you like to do things if the appropriate main function returns with
		no sucess add code here.
		This function is optional.

	fail_up()
		If you like to do things if the appropriate main function returns with
		no sucess add code here.
		This function is optional.

	fail_down()
		If you like to do things if the appropriate main function returns with
		no sucess add code here.
		This function is optional.

	fail_postdown()
		If you like to do things if the appropriate main function returns with
		no sucess add code here.
		This function is optional.

	6.2.4 Runtime configuration variables

	There are some runtime configuration variables which may be useful in some
	cases.

	RT_PREUP_PRINTING_OFF
		If you don't like the default printing to STDOUT and logging to syslog
		switch it off by setting this to 1

	RT_UP_PRINTING_OFF
		If you don't like the default printing to STDOUT and logging to syslog
		switch it off by setting this to 1

	RT_DOWN_PRINTING_OFF
		If you don't like the default printing to STDOUT and logging to syslog
		switch it off by setting this to 1

	RT_POSTDOWN_PRINTING_OFF
		If you don't like the default printing to STDOUT and logging to syslog
		switch it off by setting this to 1

	RT_PREUP_IFUP_CHECK_OFF
		If you don't like the initial "interface up check" proceed by ifup
		simply switch it off by setting this to 1

	RT_UP_IFUP_CHECK_OFF
		If you don't like the "interface up check" proceed by ifup after the
		interface should be gone up simply switch it off by setting this to 1

	RT_POSTDOWN_IFDOWN_CHECK_OFF
		If you don't like the "interface down check" proceed by ifdown after the
		interface should be gone down simply switch it off by setting this to 1

	RT_BB_NOEXEC
		If you like to prevent further execution of busybox ifupdown.c code
		after passing the fwifupdown main_ifupdown code set this to	1.


	6.2.5 Other script variables

	The following variables are set by fwifupdown:

	ENVFILE
		script environment temp file (ipc for recursive ifupdown calls)

	LIBDIR
		library directory (/opt/ifupdown/lib/)
		
	LIBDIR_OVERLAY
		library overlay directory (/etc/network/lib/)

	IF_FOO*
		interface config vars form /etc/network/interfaces

	ADDRFAM
		address family

	METHOD
		parameter 'method' from /etc/network/interfaces (manual, wvdial, ppp,
		static, bootp, dhcp, loopback)
	
	PATH
		$PATH passed to busybox
	
	IFUPDOWN_ENV
		$IFUPDOWN_ENV passed to busybox

	IFACE
		interface name
	
	PARENT_IFACE
		interface name of parent interface

	IFACE_TYPE
		the interface type (vlan, bridge, iface, ...)
	
	PARENT_IFACE_TYPE
		parent interface type

	IFACE_STATE
		the initial interface state (up | down)

	H_ERR
		set to 1 if an handler error occured
	
	MODE
		ifupdown mode (start, stop)
	
	SUBMODE
		ifupdown submode (if-pre-up, if-up, if-down, if-post-down)

	GOOD
		ansi escape color definition

	WARN
		ansi escape color definition

	BAD
		ansi escape color definition
	
	HILITE
		ansi escape color definition
	
	BRACKET
		ansi escape color definition
	
	NORMAL
		ansi escape color definition

	TAB
		tab width (n spaces)
	
	ENDCOL
		ansi escape position definition (end column)

	FIRSTCOL
		ansi escape position definition (fist column)
	
	MP_GOOD
		message prefix "good"
	
	MP_BAD
		message prefix "bad"
	
	MP_NONE
		message prefix "none"
	
	ME_GOOD
		message end "good"
	
	ME_BAD
		message end "bad"

# vim:ts=4