aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/config.txt72
-rw-r--r--docs/network-scripts.txt52
-rw-r--r--docs/network.txt79
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.