Network scripts

On OpenWrt, parsing of the network configuration and translation into system commands is handled by the network scripts in /lib/network/. The config.sh script implements the base protocols like static, dhcp and none as well as some common utility functions.

The network setup is extended by protocol handlers, additional scripts which provide configuration support for protcols like PPPoE or 3G.

Using network scripts

To be able to access the network functions, you need to include the necessary shell scripts by running:

. /etc/functions.sh # common functions include /lib/network # include /lib/network/*.sh scan_interfaces # read and parse the network config

Some protocols, such as PPP might change the configured interface names at run time (e.g. eth0 ⇒ ppp0 for PPPoE). That’s why you have to run scan_interfaces instead of reading the values from the config directly. After running scan_interfaces, the ’ifname’ option will always contain the effective interface name (which is used for IP traffic) and if the physical device name differs from it, it will be stored in the ’device’ option. That means that running config_get lan ifname after scan_interfaces might not return the same result as running it before.

After running scan_interfaces, the following functions are available:

  • find_config interface
    Looks for a network configuration that includes the specified network interface.
  • setup_interface interface [config] [protocol]
    Will set up the specified interface, optionally overriding the network configuration name or the protocol that it uses.

Writing protocol handlers

Note from 2013-10-03: This section is outdated! Please update it! see netifd, scripts are now in /lib/netifd/proto, and the function names are a bit different.

You can add custom protocol handlers by adding shell scripts to /lib/network/. The functions additional protocol backends may provide are explained below.

Scan

Protocols that create purely virtual interfaces (like PPP, 6in4 or IP tunnels) need to implement a scan procedure to synthesize an ifname required for ifup and ifdown procedures in order to map interfaces to config sections.

When called, one parameter is passed:

  1. Config, the UCI section name suitable for config_get calls
scan_protocolname() { local config="$1" # change the interface names if necessary }

This function is optional for protocols operating on physical interfaces.

Coldplug

By default, only interfaces present in /proc/net/dev, like eth0, are brought up on boot. Protocols which use virtual interfaces may provide a coldplug procedure to handle the bringup of the interface automatically.

If a protocol implements a coldplug handler and the auto option is not set to false in the associated config section, the system will trigger the handler procedure in order to start the interface.

When called, one parameter is passed:

  1. Config, the UCI section name suitable for config_get calls
coldplug_interface_protocolname() { local config="$1" # trigger bringup of interface, typically by calling setup_interface_…() }

This function is optional.

Setup

The setup procedure implements the actual protocol specifc configuration logic and interface bringup.

When called, two parameters are passed:

  1. Interface, the Linux interface name for calls to ifconfig, route and similar
  2. Config, the UCI section name suitable for config_get calls
setup_interface_protocolname() { local interface="$1" local config="$2" # set up the interface }

This function must be implemented by any protocol backend.

Stop

Protocols that need special shutdown handling, for example to kill associated daemons, may implement a stop procedure. This procedure is called when an interface is brought down before the associated UCI state is cleared.

When called, one parameter is passed:

  1. Config, the UCI section name suitable for config_get calls
stop_interface_protocolname() { local config="$1" # tear down the interface }

This function is optional.

Back to top

doc/devel/network-scripting.txt · Last modified: 2013/10/03 19:24 by cidermole