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