--- /dev/null
+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
--- /dev/null
+\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}
+
+++ /dev/null
- == 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>
-
--- /dev/null
+\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.
+
+++ /dev/null
- 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.
-
--- /dev/null
+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.
+++ /dev/null
- 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.
--- /dev/null
+\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}
projects / openwrt.git / commitdiff