add initial version of our new documentation - not too pretty yet, but will be improved
SVN-Revision: 5060
This commit is contained in:
Felix Fietkau
parent
60c1f0f64d
commit
550f17100a
8 changed files with 279 additions and 203 deletions
15
docs/Makefile
Normal file
15
docs/Makefile
Normal file
|
|
@ -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
|
||||||
79
docs/config.tex
Normal file
79
docs/config.tex
Normal file
|
|
@ -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}
|
||||||
|
|
||||||
|
|
@ -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>
|
|
||||||
|
|
||||||
54
docs/network-scripts.tex
Normal file
54
docs/network-scripts.tex
Normal file
|
|
@ -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.
|
||||||
|
|
||||||
|
|
@ -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.
|
|
||||||
|
|
||||||
86
docs/network.tex
Normal file
86
docs/network.tex
Normal file
|
|
@ -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.
|
||||||
|
|
@ -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.
|
|
||||||
45
docs/openwrt.tex
Normal file
45
docs/openwrt.tex
Normal file
|
|
@ -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}
|
||||||
Loading…
Reference in a new issue