I’ve attempted to write a complete OpenWRT setup tutorial, since many out there lack certain parts. This will cover the basics and the more advanced things you can do with OpenWRT. Read more for the tutorial.

Note: This was written for OpenWRT 7.09 and later edited for 8.09. Some information may be outdated.

I will be adding more to this later, so stay tuned. You can also subscribe to my RSS feed or follow me on Twitter (@mattventura.)

First, this assumes that you already have OpenWRT installed. If you don’t have it installed, you find the proper firmware file from openwrt.org, log into your router, and use the “firmware update” page to install the new firmware. Also, some of the advanced things assume that you have a Linksys WRT54G series router. It also assumes you have some computer skills.

If you have already done any of these steps, just skip it.

First of all, OpenWRT has a web interface, a telnet interface, and an ssh interface. This tutorial covers the telnet/ssh interface, since if you installed OpenWRT, you apparently already know how to use a web interface.

Note that more recent versions of OpenWRT use uci more (the files in /etc/config/) and as such things set in the normal configuration file for a service may be overridden (eg /etc/config/dnsmasq overrides /etc/dnsmasq.conf). Always try to use /etc/config/* first before configuring programs through their normal /etc/* files.

Web Interface Setup Notes

The OpenWRT web interface isn’t quite self explanatory, and knowing how to use a CLI is an extremely useful skill. If you don’t figure out the web interface, just follow our CLI instructions.

The initial password doesn’t exist, so please, change your password by going to System > Admin Password.

The CLI (Telnet and SSH)

First, you need to connect to the router. By default, on 8.09 wireless should be enabled, but it will be disabled for earlier versions. So if you don’t see a wifi network called “OpenWrt,” grab an Ethernet cable and connect to your router. Open up a command line and run ‘telnet 192.168.1.1’. You will get in without a password if you have not set one. You should really set one by running ‘passwd’ on the router and typing a password, if you don’t set one, by default, outside attackers can’t hit either the router’s Web UI (for 8.09+) or SSH. Now, close your telnet session and make sure you have an SSH client. For windows, you can use PuTTY, available at here. Log into the router (192.168.1.1) using username ‘root’ and the password you set in the telnet session or in the web interface. You should now be logged in. Now, if you know how to use a unix text editor (vi is the only one that comes standard on OpenWRT, see the ‘installing software’ section if you don’t like vi) you can use one. If you don’t, I recommend downloading WinSCP (available here), which will let you browse and edit files and folders with a commander-style GUI, and will make many parts of this much easier if you aren’t familiar with traditional Unix text editors since it has a built in text editor. WinSCP connects to your router through SSH, so just connect to 192.168.1.1 with username ‘root’ and the password you set. You will see your computer’s files on the left and the router’s files on the right. You can change it from commander-style to explorer style if you are more comfortable.

First Step: Configure Wifi

Start by opening the file /etc/config/wireless. If you need to enable wifi, you should see something about deleting a line to enable wifi. Just delete the line it says you should delete. Now, you can change the SSID by editing the ‘option ssid’ line. To get encryption, change the bottom part of the file to follow this example:


config wifi-iface
option device wl0
option network lan
option mode ap
option ssid openwrt
option encryption wep
option key abcd12345678901234567890ef


The ‘key’ setting should be a 10 or 26 digit hexadecimal number (only 0-9 and a-f). Be sure to include the ‘option encryption wep’ line. You can reboot to apply the changes (use the ‘reboot’ command) or run ‘/etc/init.d/network restart’. If you want to use WPA, you can use the ‘nas’ package or wpa_supplicant if you are more proficient. (Note: newer versions may support WPA/WPA2 out of the box)

Step 2: Change DNS servers (optional)

Right now, your OpenWRT router is using your ISP’s DNS servers, which probably aren’t the best out there. This step is optional, but can speed up web browsing by a significant amount, depending on how bad your ISP’s DNS servers are. First, edit /etc/dnsmasq.conf and find the ‘resolv-file’ line. Change that line to ‘resolv-file=/etc/resolv.conf.dnsmasq’. Now, exit your editor and run ‘rm /etc/resolv.conf’. Now, run ‘touch /etc/resolv.conf’ and ‘touch /etc/resolv.conf.dnsmasq’ which will create the resolv files. Edit the resolv.conf.dnsmasq file, and put this in it:

nameserver 4.2.2.2
nameserver 4.2.2.3

Then, in resolv.conf, simply put ‘nameserver 127.0.0.1’. This tells dnsmasq (a combo dhcp+caching DNS server that comes with OpenWRT) to use 4.2.2.2 and 4.2.2.3 to resolve queries, but makes everything that happens on the router itself go through the resolver, rather than going to the nameservers directly.

See Appendix A for other DNS servers you can use.

Reboot to apply the changes and check for an increase in speed. If you can connect to your network, but a web browser says that the server cannot be found, your ISP may block outside DNS queries. Simply revert to your ISP’s servers by running ‘rm /etc/resolv.conf’ and then ‘ln -s /tmp/resolv.conf.auto /etc/resolv.conf’, or if you know them, simply replace 4.2.2.3 and 4.2.2.2 with your ISP’s servers.

Step 3: Change your IP and/or Expand your subnet (optional)

You can use the entire 192.168/16 RFC1918 range if you have more than 254 devices on your network. Do not do this step if you have another NAT router somewhere in your network that you cannot configure, as it often causes problems. This will also mess with devices such as the Vonage V-Portal, which will need to be reconfigured in order to be able to make calls. Simply reconfigure it’s LAN IP to be in a different private subnet.

If you still want to use 192.168.1.1 as the router’s IP, edit the file /etc/config/network and local the ‘LAN configuration’ section. Find the ‘option netmask’ line in the LAN configuration section. Change this from 255.255.255.0 to 255.255.0.0. Now you can have 65534 devices on your network instead of only 254. You will need to reconfigure DHCP to get that many DHCP clients though. With the uci configuration for dnsmasq, it is no longer possible to do that through /etc/dnsmasq.conf without editing init scripts.

The other RFC1918 ranges are 10/8 and 176.16/12 (172.16.0.0-172.31.255.255). It is not recommended that you use a massive range, such as the whole 10/8 range, but you could use 10.1/8, 10.2/8, etc, as multiple independent networks, for DMZs or if you just need multiple LANs.

Your basic OpenWRT setup is now complete. Now for the fun stuff.

Installing Software

Older versions of OpenWRT use the ipkg package management, whereas never versions use okpg. Opkg is used the same way as ipkg, so if you see an opkg command, and you have ikpg, simply replace the o with an i, and vice-versa.

The three most useful commands are ‘opkg update’, which will update your package list, ‘opkg list’, which will list all of the available packages and can be used with grep to locate specific packages, and ‘opkg install’ to install a package. You should run ‘opkg update before installing anything. If ipkg update gives you error 404s or otherwise cannot install the software, do an ‘opkg update’



For example, to install ‘nano’, run ‘ipkg install nano’. Note that cheap hardware (eg WRT54GL) tends to have very little storage (4MB). On a WRT54GL, you cannot install both the full vim and bash without running out of space.

Now for more fun.

Front Panel Stuff

LEDs

If you look at your router’s front panel, you’ll undoubtedly see lots of lights. You may also have a button or two–try pressing the Cisco logo on the front. ‘cd’ into /proc/diag/led. Now run ‘ls’ to see what you have for programmable leds. A WRT54G > hardware v3 (the hardware version is on the bottom of the device) or a WRT54GL will have dmz, power, wlan, and will have a orange and a white LED behind the SES button (the Cisco logo). You can input ‘1’ to turn the LED on or ‘0’ to turn the LED off. Try it with the ses_white LED. Don’t try to program the wlan LED, as it blinks when there is wifi traffic, so it won’t stay on or off for long. Also, don’t try to program the power LED, as that is already used for special purposes. So you can use dmz (a small green LED) if you have it, or the two SES LEDS. They can both be on at the same time, producing a mostly white color, but it is generally better to only have the orange or white on at any time if you are using it for indication.

Have a router with GPIO lines? See this.

Buttons

If you have a front-panel button, you can use it to run a script, for example, to toggle Wifi on or off. First, go to /etc/hotplug.d (cd /etc/hotplug.d) and make a directory called ‘button’ (mkdir button). Now, make a file in that folder for your script. It should look like this:

#!/bin/sh
if [ "$BUTTON" = "ses" ] ; then
if [ "$ACTION" = "pressed" ] ; then
#Your stuff goes here.
#It will be run when the SES button is pressed.
fi
fi


Now, make the file executable (chmod a+x ), You can google around for example scripts. The most common is a wifi on-off toggle, which can be done with:


WIFI_RADIOSTATUS=$(uci show wireless.wl0.disabled | cut -d = -f 2)
case "$WIFI_RADIOSTATUS" in
1)
uci set wireless.wl0.disabled=0
wifi
echo 1 > /proc/diag/led/ses_white ;;
0)
uci set wireless.wl0.disabled=1
wifi
echo 0 > /proc/diag/led/ses_white
esac

(script from OpenWrt wiki)

Port Forwarding/Firewalling

Note: this is one of those things that is very outdated. OpenWRT now has a very nice firewall configuration that can be done via the web interface, via uci, or by editing the files directly. I recommend using that for basic port forwarding and such and using firewall.user only for things that the uci firewall configuration does not support.

First of all, let me say that port forwarding ONLY affects incoming connections. Here is a quick workaround: let’s say your site is mysite.com and incoming connections should be forwarded to 192.168.1.50. Add ‘192.168.1.50 mysite.com’ to /etc/hosts. Now when mysite.com is looked up, they will be sent directly to the server. See further down for more info.

Now for the actual forwarding. Edit the file /etc/firewall.user and you can add and delete firewall rules. A forwarding rule looks like this

iptables -t nat -A prerouting_rule -i $WAN -p tcp --dport 555 -j DNAT --to 192.168.1.119
iptables -A forwarding_rule -i $WAN -p tcp --dport 555 -d 192.168.1.119 -j ACCEPT

555 is the TCP port to be forwarded, 192.168.1.119 is the address to forward it to. To forward all ports not handled already:

iptables -t nat -A prerouting_rule -i $WAN --jump DNAT --to 192.168.1.111
iptables -A forwarding_rule -i $WAN -d 192.168.1.111 --jump ACCEPT

Where 192.168.1.111 is the address to forward to. All traffic not already handled by other rules will be caught by this one. Make sure it is the last forwarding rule in /etc/firewall.user.

To drop all outgoing traffic to a specific port:

iptables -A input_rule -p tcp --dport 666 -j DROP

This example will drop all traffic to TCP. To make the router answer ssh connections, even from the internet (which should only be done with a strong password):

iptables -t nat -A prerouting_wan -p tcp --dport 22 -j ACCEPT
iptables -A input_wan -p tcp --dport 22 -j ACCEPT


After adding or removing firewall rules, run /etc/init.d/firewall restart to apply the new rules.

Now, if you want to be able to access it through a traditional hostname, see part two of this tutorial.

Other Stuff

Set the Hostname

To set the hostname of the router, edit /etc/config/hostname.
You should reboot your router after this, using the aforementioned ‘reboot’ command.

See What’s Connected

Here is a shell script that will read your DHCP lease table and check for associated wifi clients and give you a summary of all of them. Be sure to have the wl package installed.

#!/bin/sh

for macaddr in `cat /tmp/dhcp.leases|awk ‘{print $2}’`; do
entry=`cat /tmp/dhcp.leases | grep $macaddr|cut -f 2-5 -d ‘ ‘;`
if wl assoclist | grep `echo “$entry” | awk ‘{x=toupper($1);print x}’|awk ‘{print $1}’` > /dev/null; then
mac=`echo “$entry” | awk ‘{print $1}’`
strength=`wl rssi $mac`; else
strength=”None”;
fi
entry=$entry” “”Wifi: “$strength
echo “$entry”
done

Things you should NOT do

There are a few things you may have heard of that people told you could be done in OpenWRT. The most common is increasing transmit power. This doesn’t actually increase range. It only makes it seem like it increases range. The best way to increase range is to buy a better antenna, buy better wifi cards for your computers that connect via wifi or build a cheap antenna or reflector that will focus the radio signal broadcast by your router to whichever direction you choose. Some old satellite dishes also work well for focusing signals in a particular direction.

Someone may have also told you to overclock your router. This is an easy way to brick it, requiring a JTAG cable to de-brick it. There are only a couple safe clock values (depending on your model), the others will leave you with a brick or a dead CPU (due to overheating.)

Appendix A: DNS servers

Normal DNS servers

You should use at least 2 DNS servers in /etc/resolv.conf. Here is a list of standards-compliant caching DNS servers that return NXDOMAINs for non-existent domains. These are fast and reliable.

Level3 DNS Servers:

• 4.2.2.1
• 4.2.2.2
• 4.2.2.3
• 4.2.2.4
• 4.2.2.5
• 4.2.2.6
• 4.2.2.7

Abnormal DNS servers (guides)

Comcast and Other ISPs

Comcast recently introduced the Comcast Guide, which is where if a domain doesn’t exist, you will be redirected to a guide that will run a search. In order to use Comcast’s DNS servers without the Comcast Guide, you have to provide your modem’s MAC address, account number and other crap that is not fun to provide. For this reason and others (speed, vulnerabilities), we recommend not using Comcast’s DNS servers, or the servers of any other ISP that does this.

OpenDNS

OpenDNS, a San Fransico based company offers the OpenDNS Guide which is easily turned off via a settings dashboard. Settings are set per IP or IP block. OpenDNS offers several other services such as domain blocking, category blocking and even exceptions to the OpenDNS Guide (e.g, VPN reasons) in which case a regular NXDOMAIN will be returned for a nonexistent domain. For example, Boeing employees could add boeing.com as a VPN exception to allow access to in-VPN stuff such as Exchange, Mainframes, file shares, TotalAccess and Software Express.

The OpenDNS name servers are

• 208.67.222.222
• 208.67.220.220
• 208.67.222.220
• 208.67.220.222

Fixing Bogus NXDOMAIN queries

In the case that you must use your ISP’s DNS servers, or you find that they are sufficiently fast, but they return web pages when you browse to a nonexistent page, you can use dnsmasq.conf to block the bogus page. (Please make sure that it is not software on your computer causing this.)

In /etc/dnsmasq.conf, add a line like this:
bogus-nxdomain=1.2.3.4
Replace 1.2.3.4 with the IP that is being returned for nonexistent domains. To find this, just run ‘nslookup fhdsahfahdsucnmcnch.com’ or something of the likes. Restart dnsmasq. (/etc/init.d/dnsmasq restart)

More Stuff

Firewall Addendum

With the firewall and port forwarding tutorial, I forgot to mention that this will not work like a normal home router’s port forwarding. A normal home router will typically forward the packets whether it came from the LAN or WAN interface if the packet it destined for the external interface’s IP. Because of the way the OpenWRT port forwarding is set up, it will only forward from the WAN interface. To fix this, you need to update your hosts file. But in recent openWRT versions, /etc/hosts is generated from /etc/hosts.local. So put your entries in hosts.local and then cp /etc/hosts.local /etc/hosts. A hosts file might look like this:

192.168.1.54 mysite.com images.mysite.com      #If 'mysite.com' is my site, and
                                               #it is hosted behind the router, then make
                                               #sure internal lookups go to the internal IP,
                                               # not the external IP.

More Firewall Stuff

If you need to block an IP from connecting, use a line like this in firewall.user:

iptables -I INPUT -s 11.22.33.44    -j DROP

If you need to block an incoming port after forwarding all ports, this should work:

iptables -I INPUT --proto tcp --dport 2345 -j DROP

If you need to block an outgoing port, use this:

iptables -A FORWARD --proto tcp -i br-lan --dport 2345 -j REJECT

IPv6 tunneling

Note: this is another outdated section. You may have to install packages for it, but both the tunnel setup and radvd setup now have uci configuration files for them. You should always try to use uci configurations when possible.

First, get a tunnel from Hurricane Electric* (tunnelbroker.net) Then, create a new standard tunnel (not BGP tunnel) get the tunnel information. Install the packages kmod-ipv6, kmod-ipv6tables, and radvd.

Put this in /etc/init.d/tunnel (create it if it doesn’t exist)

#!/bin/sh /etc/rc.common
LOCALIP=Your external IP
POPIP=The PoP's IPv4 address
LOCTUN=Your end of the tunnel (IPv6)
REMTUN=The remote end of the tunnel (IPv4)

START=50

start()
  {
   echo -n "Starting  he.net IPv6 tunnel: "
   ip tunnel add he-ipv6 mode sit  remote $POPIP local $LOCALIP ttl 255
   ip link set he-ipv6 up
   ip link set mtu 1280 dev he-ipv6
   ip tunnel change he-ipv6 ttl 64

   ip -6 addr add $LOCTUN/64 dev he-ipv6
   ip -6 route add ::/0 dev he-ipv6
   ip -6 ro add default via $REMTUN dev he-ipv6
   ip -f inet6 addr
   echo "Done."
}
stop()
{
   echo -n "Stopping he.net IPv6 tunnel: "
   ip link set he-ipv6 down
   ip tunnel del he-ipv6
   echo "Done."
}
restart()
{
   stop
   start
}

Now, install radvd and set it up. The config (/etc/config/radvd) should look like this:

config interface
 option interface    'lan'
 option AdvSendAdvert    1
 option AdvManagedFlag    0
 option AdvOtherConfigFlag 0
 option AdvHomeAgentFlag    0
 option ignore        0    

config prefix
 option interface    'lan'
 # If not specified, a non-link-local prefix of the interface is used
 option prefix        '2001:470:b:122::/64' #this is the /64 tunnel you get from HE. Change it to what the page says.
 option AdvOnLink    1
 option AdvAutonomous    1
 option AdvRouterAddr    0
 option ignore        0

config rdnss
 option interface    'lan'
 # If not specified, the link-local address of the interface is used
 option addr        ''
 option ignore        1

Finally, edit /etc/config/network and put in the IPv6 address for br-lan:

config 'interface' 'lan'
 option 'type' 'bridge'
 option 'ifname' 'eth0.0'
 option 'proto' 'static'
 option 'ipaddr' '192.168.1.1'
 option 'netmask' '255.255.0.0'
 option 'ip6addr' '2001:470:b:122::1/64'

Finally, add these to /etc/firewall.user:

iptables -A INPUT -p 41 -i $WAN -j ACCEPT
iptables -t nat -A POSTROUTING --protocol ! 41 -o $WAN -j MASQUERADE

Now, do these commands:

modprobe ipv6
modprobe ipv6tables
/etc/init.d/tunnel start
/etc/init.d/radvd start

To see if it’s working, try ‘ping6 www.kame.net’. To see if route advertisement is working, get on another computer on the network, and try the same (on windows it is ping -6 www.kame.net). You will have to install IPv6 for some windows versions before you can use it (google it.)

If it’s not working, HE.net support is usually helpful. It could be a misconfiguration on your end, or they may have an issue on their end (sometimes if your address space was previously allocated but then deleted you will run into issues.)

*I strongly recommend this over SixXS. SixXS makes you fill out a form and get everything approved (they rejected me.) Then, from what I have heard, you then have to keep your tunnel up to get ‘credits’ which you can then use to buy tunnels and such. HE has no such BS. Sign up, immediately get up to four tunnels each with a routed /48 and /64.

DHCP Options

Using DHCP options can make setting up a network easier. A complete list is here. To use a DHCP option, insert it in /etc/dnsmasq.conf like this:

dhcp-option=6,192.168.1.1

This sets the default DNS server for DHCP clients to 192.168.1.1. This will make the default DNS server for clients to be the router*. Most options are not necessary. A few are done automatically for you. The important ones, depending on your network, are 3, (Default route, set to the router if none specified), 6 (DNS), 44 (WINS). Also note that with certain options, you can have more that one value. Just put another comma and the second value. You can also assign static leases, in this form:

dhcp-host=00:22:6B:73:84:39,openwrt2,192.168.1.2

*A note about DNS: There are 3 DNS servers you can set. One is set in /etc/resolv.conf and will be the default server for lookups on the router and lookups through the LAN clients (by default, see below for the whole story). Sometimes /etc/resolv.conf is a symlink and must be deleted first (just rm /etc/resolv.conf.) The second setting, which is optional, is option 6 in dnsmasq.conf, which will allow you to give the LAN clients a different nameserver. You can set to something else if you already have a caching nameserver on your LAN, or if you want the clients to directly talk to an external caching nameserver. The last setting, which I won’t explain here, just RTFM, allows the queries from clients to be answered by a different nameserver than queries from the router. This is usually unnecessary, but is useful in certain circumstances, for example, having dnsmasq cache queries for the router itself.

Credits

© 2009-10 Matt Ventura. This work is licensed under the GNU Free Documentation License version 1.3. You may copy and modify it under the terms of the license.