qi-hardware/openwrt-xburst
1
0
Fork 0
mirror of git://projects.qi-hardware.com/openwrt-xburst.git synced 2024-11-19 05:04:04 +02:00
Code

add initial version of our new documentation - not too pretty yet, but will be improved

Browse Source 
git-svn-id: svn://svn.openwrt.org/openwrt/trunk@5060 3c298f89-4303-0410-b956-a3cf2f4a3e73
This commit is contained in:
nbd 2006-10-13 22:41:34 +00:00
parent f52d66ff00
commit dfe52f0a79
8 changed files with 279 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/Makefile Normal file
View 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
View 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}

72
docs/config.txt
View File

@ -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
View 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.

52
docs/network-scripts.txt
View File

@ -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
View 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.

79
docs/network.txt
View File

@ -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
View 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}