diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/config.txt | 72 | ||||
| -rw-r--r-- | docs/network-scripts.txt | 52 | ||||
| -rw-r--r-- | docs/network.txt | 79 |
3 files changed, 203 insertions, 0 deletions
diff --git a/docs/config.txt b/docs/config.txt new file mode 100644 index 0000000000..59881580b4 --- /dev/null +++ b/docs/config.txt @@ -0,0 +1,72 @@ + == Structure of the configuration files == + +The config files are divided into sections and options/values. + +Every section has a type, but does not necessarily have a name. +Every option has a name and a value and is assigned to the section +it was written under. + +Syntax: + +config <type> [<name>] # Section + option <name> <value> # Option + + +Every parameter needs to be a single string and is formatted exactly +like a parameter for a shell function. The same rules for Quoting and +special characters also apply, as it is parsed by the shell. + + + + == Parsing configuration files in custom scripts == + +To be able to load configuration files, you need to include the common +functions with: + +. /etc/functions.sh + +Then you can use config_load <name> to load config files. The function +first checks for <name> as absolute filename and falls back to loading +it from /etc/config (which is the most common way of using it). + +If you want to use special callbacks for sections and/or options, you +need to define the following shell functions before running config_load +(after including /etc/functions.sh): + +config_cb() { + local type="$1" + local name="$2" + # commands to be run for every section +} + +option_cb() { + # commands to be run for every option +} + +You can also alter option_cb from config_cb based on the section type. +This allows you to process every single config section based on its type +individually. + +config_cb is run every time a new section starts (before options are being +processed). You can access the last section through the CONFIG_SECTION +variable. Also an extra call to config_cb (without a new section) is generated +after config_load is done. +That allows you to process sections both before and after all options were +processed. + +You can access already processed options with the config_get command +Syntax: + +config_get <section> <option> # prints the value of the option +config_get <variable> <section> <option> # stores the value inside the variable + +In busybox ash the three-option config_get is faster, because it does not +result in an extra fork, so it is the preferred way. + +Additionally you can also modify or add options to sections by using the +config_set command. + +Syntax: + +config_set <section> <option> <value> + diff --git a/docs/network-scripts.txt b/docs/network-scripts.txt new file mode 100644 index 0000000000..024161bdeb --- /dev/null +++ b/docs/network-scripts.txt @@ -0,0 +1,52 @@ + Structure of the network scripts in buildroot-ng + + +1) Usage + +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. + + + +2) Writing protocol handlers + +You can add custom protocol handlers by adding shell scripts to +/lib/network. They provide the following two shell functions: + +scan_<protocolname>() { + local config="$1" + # change the interface names if necessary +} + +setup_interface_<protocolname>() { + local interface="$1" + local config="$2" + # set up the interface +} + +scan_<protocolname> is optional and only necessary if your protocol +uses a custom device, e.g. a tunnel or a PPP device. + diff --git a/docs/network.txt b/docs/network.txt new file mode 100644 index 0000000000..69dbaa60ba --- /dev/null +++ b/docs/network.txt @@ -0,0 +1,79 @@ + Network configuration in buildroot-ng + + +The network configuration in buildroot-ng is stored in /etc/config/network +and is divided into interface configurations. +Each interface configuration either refers directly to an ethernet/wifi +interface (eth0, wl0, ..) or to a bridge containing multiple interfaces. +It looks like this: + + config interface "lan" + option ifname "eth0" + option proto "static" + option ipaddr "192.168.1.1" + option netmask "255.255.255.0" + option gateway "192.168.1.254" + option dns "192.168.1.254" + +"ifname" specifies the Linux interface name. +If you want to use bridging on one or more interfaces, set "ifname" to a list +of interfaces and add: + option type "bridge" + +It is possible to use VLAN tagging on an interface simply by adding the VLAN IDs +to it, e.g. "eth0.1". These can be nested as well. + +This sets up a simple static configuration for eth0. "proto" specifies the +'protocol' used for the interface. The default image usually provides 'none' +'static', 'dhcp' and 'pppoe'. Others can be added by installing additional +packages. + +When using the 'static' method like in the example, the options "ipaddr" and +"netmask" are mandatory, while "gateway" and "dns" are optional. +DHCP currently only accepts "ipaddr" (IP address to request from the server) +and "hostname" (client hostname identify as) - both are optional. + +PPP based protocols (pppoe, pptp, ...) accept these options: + username: + The PPP username (usually with PAP authentication) + password: + The PPP password + keepalive: + Ping the PPP server (using LCP). The value of this option + specifies the maximum number of failed pings before reconnecting. + The ping interval defaults to 5, but can be changed by appending + ",<interval>" to the keepalive value + demand: + Use Dial on Demand (value specifies the maximum idle time) + + (pptp) + server: The remote pptp server IP + +For all protocol types, you can also specify the MTU by using the "mtu" option. + + + + + Setting up the switch (currently broadcom only) + + +The switch configuration is set by adding a 'switch' config section. +Example: + + config switch eth0 + option vlan0 "1 2 3 4 5*" + option vlan1 "0 5" + +On Broadcom hardware the section name needs to be eth0, as the switch driver +does not detect the switch on any other physical device. +Every vlan option needs to have the name vlan<n> where <n> is the VLAN number +as used in the switch driver. +As value it takes a list of ports with these optional suffixes: + + '*': Set the default VLAN (PVID) of the Port to the current VLAN + 'u': Force the port to be untagged + 't': Force the port to be tagged + +The CPU port defaults to tagged, all other ports to untagged. +On Broadcom hardware the CPU port is always 5. The other ports may vary with +different hardware. |