path: root/docs/network.tex

The network configuration 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.15}. These can be nested as well. See the switch section for
this.

\begin{Verbatim}
config interface
    option ifname    "eth0.15"
    option proto     "none"
\end{Verbatim}

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.
You can specify more than one DNS server, separated with spaces:

\begin{Verbatim}
config interface     "lan"
    option ifname    "eth0"
    option proto     "static"
    ...
    option dns       "192.168.1.254 192.168.1.253" (optional)
\end{Verbatim}

DHCP currently only accepts \texttt{ipaddr} (IP address to request from the server)
and \texttt{hostname} (client hostname identify as) - both are optional.

\begin{Verbatim}
config interface     "lan"
    option ifname    "eth0"
    option proto     "dhcp"
    option ipaddr    "192.168.1.1" (optional)
    option hostname  "openwrt"     (optional)
\end{Verbatim}

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.
A sample PPPoE config would look like this:

\begin{Verbatim}
config interface     "lan"
    option ifname    "eth0"
    option proto     "pppoe"
    option username  "username"
    option password  "openwrt"
    option mtu       "1492"      (optional)
\end{Verbatim}

\subsubsection{Setting up static routes}

You can set up static routes for a specific interface that will be brought up 
after the interface is configured.

Simply add a config section like this:

\begin{Verbatim}
config route foo
	option interface  "lan"
	option target     "1.1.1.0"
	option netmask    "255.255.255.0"
	option gateway    "192.168.1.1"
\end{Verbatim}

The name for the route section is optional, the \texttt{interface}, \texttt{target} and 
\texttt{gateway} options are mandatory.
Leaving out the \texttt{netmask} option will turn the route into a host route.

\subsubsection{Setting up the switch (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.

For instance, if you wish to have 3 vlans, like one 3-port switch, 1 port in a
DMZ, and another one as your WAN interface, use the following configuration :

\begin{Verbatim}
config switch       "eth0"
    option vlan0    "1 2 3 5*"
    option vlan1    "0 5"
    option vlan2    "4 5"
\end{Verbatim}

Three interfaces will be automatically created using this switch layout :
\texttt{eth0.0} (vlan0), \texttt{eth0.1} (vlan1) and \texttt{eth0.2} (vlan2).
You can then assign those interfaces to a custom network configuration name
like \texttt{lan}, \texttt{wan} or \texttt{dmz} for instance.

\subsubsection{Setting up the switch (swconfig)}

\emph{swconfig} based configurations have a different structure with one extra
section per vlan. The example below shows a typical configuration:

\begin{Verbatim}
config 'switch' 'eth0'
        option 'reset' '1'
        option 'enable_vlan' '1'

config 'switch_vlan' 'eth0_1'
        option 'device' 'eth0'
        option 'vlan' '1'
        option 'ports' '0 1 2 3 5t'

config 'switch_vlan' 'eth0_2'
        option 'device' 'eth0'
        option 'vlan' '2'
        option 'ports' '4 5t'
\end{Verbatim}

\subsubsection{Setting up IPv6 connectivity}

OpenWrt supports IPv6 connectivity using PPP, Tunnel brokers or static
assignment.

If you use PPP, IPv6 will be setup using IP6CP and there is nothing to
configure.

To setup an IPv6 tunnel to a tunnel broker, you can install the
\texttt{6scripts} package and edit the \texttt{/etc/config/6tunnel}
file and change the settings accordingly :

\begin{Verbatim}
config 6tunnel
        option tnlifname     'sixbone'
        option remoteip4     '1.0.0.1'
        option localip4      '1.0.0.2'
        option localip6      '2001::DEAD::BEEF::1'
\end{Verbatim}

\begin{itemize}
    \item{\texttt{'tnlifname'}:}
        Set the interface name of the IPv6 in IPv4 tunnel
    \item{\texttt{'remoteip4'}:}
        IP address of the remote end to establish the 6in4 tunnel.
	This address is given by the tunnel broker
    \item{\texttt{'localip4'}:}
	IP address of your router to establish the 6in4 tunnel.
	It will usually match your WAN IP address.
    \item{\texttt{'localip6'}:}
	IPv6 address to setup on your tunnel side
	This address is given by the tunnel broker
\end{itemize}

Using the same package you can also setup an IPv6 bridged connection:

\begin{Verbatim}
config 6bridge
	option bridge	'br6'
\end{Verbatim}

By default the script bridges the WAN interface with the LAN interface
and uses ebtables to filter anything that is not IPv6 on the bridge.
This configuration is particularly useful if your router is not
IPv6 ND proxy capable (see: http://www.rfc-archive.org/getrfc.php?rfc=4389).

IPv6 static addressing is also supported using a similar setup as
IPv4 but with the \texttt{ip6} prefixing (when applicable).

\begin{Verbatim}
config interface     "lan"
    option ifname    "eth0"
    option proto     "static"
    option ip6addr   "fe80::200:ff:fe00:0/64"
    option ip6gw     "2001::DEAF:BEE:1"
\end{Verbatim}