docs/network.tex

   1 The network configuration is stored in \texttt{/etc/config/network}
   2 and is divided into interface configurations.
   3 Each interface configuration either refers directly to an ethernet/wifi
   4 interface (\texttt{eth0}, \texttt{wl0}, ..) or to a bridge containing multiple interfaces.
   5 It looks like this:
   6
   7 \begin{Verbatim}
   8 config interface     "lan"
   9     option ifname    "eth0"
  10     option proto     "static"
  11     option ipaddr    "192.168.1.1"
  12     option netmask   "255.255.255.0"
  13     option gateway   "192.168.1.254"
  14     option dns       "192.168.1.254"
  15 \end{Verbatim}
  16
  17 \texttt{ifname} specifies the Linux interface name.
  18 If you want to use bridging on one or more interfaces, set \texttt{ifname} to a list
  19 of interfaces and add:
  20 \begin{Verbatim}
  21     option type     "bridge"
  22 \end{Verbatim}
  23
  24 It is possible to use VLAN tagging on an interface simply by adding the VLAN IDs
  25 to it, e.g. \texttt{eth0.15}. These can be nested as well. See the switch section for
  26 this.
  27
  28 \begin{Verbatim}
  29 config interface
  30     option ifname    "eth0.15"
  31     option proto     "none"
  32 \end{Verbatim}
  33
  34 This sets up a simple static configuration for \texttt{eth0}. \texttt{proto} specifies the
  35 protocol used for the interface. The default image usually provides \texttt{'none'}
  36 \texttt{'static'}, \texttt{'dhcp'} and \texttt{'pppoe'}. Others can be added by installing additional
  37 packages.
  38
  39 When using the \texttt{'static'} method like in the example, the  options \texttt{ipaddr} and
  40 \texttt{netmask} are mandatory, while \texttt{gateway} and \texttt{dns} are optional.
  41 You can specify more than one DNS server, separated with spaces:
  42
  43 \begin{Verbatim}
  44 config interface     "lan"
  45     option ifname    "eth0"
  46     option proto     "static"
  47     ...
  48     option dns       "192.168.1.254 192.168.1.253" (optional)
  49 \end{Verbatim}
  50
  51 DHCP currently only accepts \texttt{ipaddr} (IP address to request from the server)
  52 and \texttt{hostname} (client hostname identify as) - both are optional.
  53
  54 \begin{Verbatim}
  55 config interface     "lan"
  56     option ifname    "eth0"
  57     option proto     "dhcp"
  58     option ipaddr    "192.168.1.1" (optional)
  59     option hostname  "openwrt"     (optional)
  60 \end{Verbatim}
  61
  62 PPP based protocols (\texttt{pppoe}, \texttt{pptp}, ...) accept these options:
  63 \begin{itemize}
  64     \item{username} \\
  65         The PPP username (usually with PAP authentication)
  66     \item{password} \\
  67         The PPP password
  68     \item{keepalive} \\
  69         Ping the PPP server (using LCP). The value of this option
  70         specifies the maximum number of failed pings before reconnecting.
  71         The ping interval defaults to 5, but can be changed by appending
  72         ",<interval>" to the keepalive value
  73     \item{demand} \\
  74         Use Dial on Demand (value specifies the maximum idle time.
  75     \item{server: (pptp)} \\
  76         The remote pptp server IP
  77 \end{itemize}
  78
  79 For all protocol types, you can also specify the MTU by using the \texttt{mtu} option.
  80 A sample PPPoE config would look like this:
  81
  82 \begin{Verbatim}
  83 config interface     "lan"
  84     option ifname    "eth0"
  85     option proto     "pppoe"
  86     option username  "username"
  87     option password  "openwrt"
  88     option mtu       "1492"      (optional)
  89 \end{Verbatim}
  90
  91 \subsubsection{Setting up static routes}
  92
  93 You can set up static routes for a specific interface that will be brought up
  94 after the interface is configured.
  95
  96 Simply add a config section like this:
  97
  98 \begin{Verbatim}
  99 config route foo
 100         option interface  "lan"
 101         option target     "1.1.1.0"
 102         option netmask    "255.255.255.0"
 103         option gateway    "192.168.1.1"
 104 \end{Verbatim}
 105
 106 The name for the route section is optional, the \texttt{interface}, \texttt{target} and
 107 \texttt{gateway} options are mandatory.
 108 Leaving out the \texttt{netmask} option will turn the route into a host route.
 109
 110 \subsubsection{Setting up the switch (broadcom only)}
 111
 112 The switch configuration is set by adding a \texttt{'switch'} config section.
 113 Example:
 114
 115 \begin{Verbatim}
 116 config switch       "eth0"
 117     option vlan0    "1 2 3 4 5*"
 118     option vlan1    "0 5"
 119 \end{Verbatim}
 120
 121 On Broadcom hardware the section name needs to be eth0, as the switch driver
 122 does not detect the switch on any other physical device.
 123 Every vlan option needs to have the name vlan<n> where <n> is the VLAN number
 124 as used in the switch driver.
 125 As value it takes a list of ports with these optional suffixes:
 126
 127 \begin{itemize}
 128     \item{\texttt{'*'}:}
 129         Set the default VLAN (PVID) of the Port to the current VLAN
 130     \item{\texttt{'u'}:}
 131         Force the port to be untagged
 132     \item{\texttt{'t'}:}
 133         Force the port to be tagged
 134 \end{itemize}
 135
 136 The CPU port defaults to tagged, all other ports to untagged.
 137 On Broadcom hardware the CPU port is always 5. The other ports may vary with
 138 different hardware.
 139
 140 For instance, if you wish to have 3 vlans, like one 3-port switch, 1 port in a
 141 DMZ, and another one as your WAN interface, use the following configuration :
 142
 143 \begin{Verbatim}
 144 config switch       "eth0"
 145     option vlan0    "1 2 3 5*"
 146     option vlan1    "0 5"
 147     option vlan2    "4 5"
 148 \end{Verbatim}
 149
 150 Three interfaces will be automatically created using this switch layout :
 151 \texttt{eth0.0} (vlan0), \texttt{eth0.1} (vlan1) and \texttt{eth0.2} (vlan2).
 152 You can then assign those interfaces to a custom network configuration name
 153 like \texttt{lan}, \texttt{wan} or \texttt{dmz} for instance.
 154
 155 \subsubsection{Setting up the switch (swconfig)}
 156
 157 \emph{swconfig} based configurations have a different structure with one extra
 158 section per vlan. The example below shows a typical configuration:
 159
 160 \begin{Verbatim}
 161 config 'switch' 'eth0'
 162         option 'reset' '1'
 163         option 'enable_vlan' '1'
 164
 165 config 'switch_vlan' 'eth0_1'
 166         option 'device' 'eth0'
 167         option 'vlan' '1'
 168         option 'ports' '0 1 2 3 5t'
 169
 170 config 'switch_vlan' 'eth0_2'
 171         option 'device' 'eth0'
 172         option 'vlan' '2'
 173         option 'ports' '4 5t'
 174 \end{Verbatim}
 175
 176 \subsubsection{Setting up IPv6 connectivity}
 177
 178 OpenWrt supports IPv6 connectivity using PPP, Tunnel brokers or static
 179 assignment.
 180
 181 If you use PPP, IPv6 will be setup using IP6CP and there is nothing to
 182 configure.
 183
 184 To setup an IPv6 tunnel to a tunnel broker, you can install the
 185 \texttt{6scripts} package and edit the \texttt{/etc/config/6tunnel}
 186 file and change the settings accordingly :
 187
 188 \begin{Verbatim}
 189 config 6tunnel
 190         option tnlifname     'sixbone'
 191         option remoteip4     '1.0.0.1'
 192         option localip4      '1.0.0.2'
 193         option localip6      '2001::DEAD::BEEF::1'
 194 \end{Verbatim}
 195
 196 \begin{itemize}
 197     \item{\texttt{'tnlifname'}:}
 198         Set the interface name of the IPv6 in IPv4 tunnel
 199     \item{\texttt{'remoteip4'}:}
 200         IP address of the remote end to establish the 6in4 tunnel.
 201         This address is given by the tunnel broker
 202     \item{\texttt{'localip4'}:}
 203         IP address of your router to establish the 6in4 tunnel.
 204         It will usually match your WAN IP address.
 205     \item{\texttt{'localip6'}:}
 206         IPv6 address to setup on your tunnel side
 207         This address is given by the tunnel broker
 208 \end{itemize}
 209
 210 Using the same package you can also setup an IPv6 bridged connection:
 211
 212 \begin{Verbatim}
 213 config 6bridge
 214         option bridge   'br6'
 215 \end{Verbatim}
 216
 217 By default the script bridges the WAN interface with the LAN interface
 218 and uses ebtables to filter anything that is not IPv6 on the bridge.
 219 This configuration is particularly useful if your router is not
 220 IPv6 ND proxy capable (see: http://www.rfc-archive.org/getrfc.php?rfc=4389).
 221
 222 IPv6 static addressing is also supported using a similar setup as
 223 IPv4 but with the \texttt{ip6} prefixing (when applicable).
 224
 225 \begin{Verbatim}
 226 config interface     "lan"
 227     option ifname    "eth0"
 228     option proto     "static"
 229     option ip6addr   "fe80::200:ff:fe00:0/64"
 230     option ip6gw     "2001::DEAF:BEE:1"
 231 \end{Verbatim}