diff options
| -rw-r--r-- | docs/Makefile | 15 | ||||
| -rw-r--r-- | docs/config.tex | 79 | ||||
| -rw-r--r-- | docs/config.txt | 72 | ||||
| -rw-r--r-- | docs/network-scripts.tex | 54 | ||||
| -rw-r--r-- | docs/network-scripts.txt | 52 | ||||
| -rw-r--r-- | docs/network.tex | 86 | ||||
| -rw-r--r-- | docs/network.txt | 79 | ||||
| -rw-r--r-- | docs/openwrt.tex | 45 |
8 files changed, 279 insertions, 203 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..0a4128754 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,15 @@ +openwrt.pdf: Makefile openwrt.tex config.tex network.tex network-scripts.tex + $(MAKE) cleanup + pdflatex openwrt.tex + pdflatex openwrt.tex + $(MAKE) cleanup + +clean: cleanup + rm -f openwrt.pdf + +cleanup: FORCE + rm -f *.log *.aux *.toc + + +FORCE: +.PHONY: FORCE diff --git a/docs/config.tex b/docs/config.tex new file mode 100644 index 000000000..44b6689b5 --- /dev/null +++ b/docs/config.tex @@ -0,0 +1,79 @@ +\subsubsection{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: + +\begin{Verbatim} +config <type> [<name>] # Section + option <name> <value> # Option +\end{Verbatim} + +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. + +\subsubsection{Parsing configuration files in custom scripts} + +To be able to load configuration files, you need to include the common +functions with: + +\begin{Verbatim} +. /etc/functions.sh +\end{Verbatim} + +Then you can use \texttt{config\_load \textit{<name>}} to load config files. The function +first checks for \textit{<name>} as absolute filename and falls back to loading +it from \texttt{/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 \texttt{config\_load} +(after including \texttt{/etc/functions.sh}): + +\begin{Verbatim} +config_cb() { + local type="$1" + local name="$2" + # commands to be run for every section +} + +option_cb() { + # commands to be run for every option +} +\end{Verbatim} + +You can also alter \texttt{option\_cb} from \texttt{config\_cb} based on the section type. +This allows you to process every single config section based on its type +individually. + +\texttt{config\_cb} is run every time a new section starts (before options are being +processed). You can access the last section through the \texttt{CONFIG\_SECTION} +variable. Also an extra call to \texttt{config\_cb} (without a new section) is generated +after \texttt{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 \texttt{config\_get} command +Syntax: + +\begin{Verbatim} +config_get <section> <option> # prints the value of the option +config_get <variable> <section> <option> # stores the value inside the variable +\end{Verbatim} + +In busybox ash the three-option \texttt{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 +\texttt{config\_set} command. + +Syntax: + +\begin{Verbatim} +config_set <section> <option> <value> +\end{Verbatim} + diff --git a/docs/config.txt b/docs/config.txt deleted file mode 100644 index 59881580b..000000000 --- a/docs/config.txt +++ /dev/null @@ -1,72 +0,0 @@ - == 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.tex b/docs/network-scripts.tex new file mode 100644 index 000000000..79a885341 --- /dev/null +++ b/docs/network-scripts.tex @@ -0,0 +1,54 @@ +\subsubsection{Using the network scripts} + +To be able to access the network functions, you need to include +the necessary shell scripts by running: + +\begin{Verbatim} +. /etc/functions.sh # common functions +include /lib/network # include /lib/network/*.sh +scan_interfaces # read and parse the network config +\end{Verbatim} + +Some protocols, such as PPP might change the configured interface names +at run time (e.g. \texttt{eth0} => \texttt{ppp0} for PPPoE). That's why you have to run +\texttt{scan\_interfaces} instead of reading the values from the config directly. +After running \texttt{scan\_interfaces}, the \texttt{'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 \texttt{'device'} +option. +That means that running \texttt{config\_get lan ifname} +after \texttt{scan\_interfaces} might not return the same result as running it before. + +After running \texttt{scan\_interfaces}, the following functions are available: + +\begin{itemize} + \item{\texttt{find\_config \textit{interface}}} \\ + looks for a network configuration that includes + the specified network interface. + + \item{\texttt{setup\_interface \textit{interface [config] [protocol]}}} \\ + will set up the specified interface, optionally overriding the network configuration + name or the protocol that it uses. +\end{itemize} + +\subsubsection{Writing protocol handlers} + +You can add custom protocol handlers by adding shell scripts to +\texttt{/lib/network}. They provide the following two shell functions: + +\begin{Verbatim} +scan_<protocolname>() { + local config="$1" + # change the interface names if necessary +} + +setup_interface_<protocolname>() { + local interface="\$1" + local config="\$2" + # set up the interface +} +\end{Verbatim} + +\texttt{scan\_\textit{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-scripts.txt b/docs/network-scripts.txt deleted file mode 100644 index 024161bde..000000000 --- a/docs/network-scripts.txt +++ /dev/null @@ -1,52 +0,0 @@ - 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.tex b/docs/network.tex new file mode 100644 index 000000000..1ba1bd9b3 --- /dev/null +++ b/docs/network.tex @@ -0,0 +1,86 @@ +The network configuration in Kamikaze is stored in \texttt{/etc/config/network} +and is divided into interface configurations. +Each interface configuration either refers directly to an ethernet/wifi +interface (\texttt{eth0}, \texttt{wl0}, ..) or to a bridge containing multiple interfaces. +It looks like this: + +\begin{Verbatim} +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" +\end{Verbatim} + +\texttt{ifname} specifies the Linux interface name. +If you want to use bridging on one or more interfaces, set \texttt{ifname} to a list +of interfaces and add: +\begin{Verbatim} + option type "bridge" +\end{Verbatim} + +It is possible to use VLAN tagging on an interface simply by adding the VLAN IDs +to it, e.g. \texttt{eth0.1}. These can be nested as well. + +This sets up a simple static configuration for \texttt{eth0}. \texttt{proto} specifies the +protocol used for the interface. The default image usually provides \texttt{'none'} +\texttt{'static'}, \texttt{'dhcp'} and \texttt{'pppoe'}. Others can be added by installing additional +packages. + +When using the \texttt{'static'} method like in the example, the options \texttt{ipaddr} and +\texttt{netmask} are mandatory, while \texttt{gateway} and \texttt{dns} are optional. +DHCP currently only accepts \texttt{ipaddr} (IP address to request from the server) +and \texttt{hostname} (client hostname identify as) - both are optional. + +PPP based protocols (\texttt{pppoe}, \texttt{pptp}, ...) accept these options: +\begin{itemize} + \item{username} \\ + The PPP username (usually with PAP authentication) + \item{password} \\ + The PPP password + \item{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 + \item{demand} \\ + Use Dial on Demand (value specifies the maximum idle time. + + \item{server: (pptp)} \\ + The remote pptp server IP +\end{itemize} + +For all protocol types, you can also specify the MTU by using the \texttt{mtu} option. + + +\subsubsection{Setting up the switch (currently broadcom only)} + +The switch configuration is set by adding a \texttt{'switch'} config section. +Example: + +\begin{Verbatim} +config switch eth0 + option vlan0 "1 2 3 4 5*" + option vlan1 "0 5" +\end{Verbatim} + +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: + +\begin{itemize} + \item{\texttt{'*'}:} + Set the default VLAN (PVID) of the Port to the current VLAN + \item{\texttt{'u'}:} + Force the port to be untagged + \item{\texttt{'t'}:} + Force the port to be tagged +\end{itemize} + +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. diff --git a/docs/network.txt b/docs/network.txt deleted file mode 100644 index 69dbaa60b..000000000 --- a/docs/network.txt +++ /dev/null @@ -1,79 +0,0 @@ - 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. diff --git a/docs/openwrt.tex b/docs/openwrt.tex new file mode 100644 index 000000000..6eda7c021 --- /dev/null +++ b/docs/openwrt.tex @@ -0,0 +1,45 @@ +\documentclass[a4paper]{book} +\usepackage[latin9]{inputenc} +%\usepackage[T1]{fontenc} +\usepackage{fancyvrb} + +\begin{document} + +\tableofcontents + +\chapter{The Router} +\section{Getting started} +\subsection{Installation} +\subsection{Initial configuration} +\subsection{Failsafe mode} +\section{Configuring OpenWrt} +\subsection{Network} +\include{network} + +\subsection{Wireless} + +\section{Advanced configuration} +\include{config} + +\subsection{Hotplug} +\subsection{Init scripts} +\subsection{Network scripts} +\include{network-scripts} + +\chapter{Development issues} +\section{The build system} +\subsection{Building an image} +\subsection{Integrating packages} +\subsection{Creating packages} + +\section{Extra tools} +\subsection{Image Builder} +\subsection{SDK} + +\section{Adding platform support} +\section{Debugging and debricking} +\subsection{Adding a serial port} +\subsection{JTAG} + + +\end{document} |