root/trunk/freewrt/Docs/fwifupdown/fwifupdown.txt

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