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.

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.

Also, this was written using 7.09, then editied with another person who uses 8.09, so some of this may be outdated, but should be mostly relevant.

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.

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 http://the.earth.li/~sgtatham/putty/latest/x86/putty.exe. 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 at http://winscp.net/download/winscp419.exe), 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.

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’. Now, exit your editor and run ‘rm /etc/resolv.conf’. Now, run ‘touch /etc/resolv.conf’ which will recreate the file. Edit the file again, and put this in it:

nameserver 4.2.2.2
nameserver 4.2.2.3


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. Then proceed to call your ISP and complain about the fact that you can’t use other DNS servers. Threaten to cancel your service, because that is very effective.

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.

The other RFC1918 ranges are 10/8 and 176.16/12 (172.16.0.0-172.31.255.255)

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 ipkg command, and you have okpg, simply replace the i with an o.

The three most useful commands are ipkg update, which will update your package list, ipkg list, which will list all of the available packages and can be used with grep to locate specific packages, and ipkg install to install a package. You should run ipkg update before installing anything. If ipkg update gives you error 404s, try looking in /etc/ipkg.conf to see if your sources are correct. Mine are:

src release http://downloads.openwrt.org/kamikaze/7.09/brcm-2.4/packages
src packages http://downloads.openwrt.org/kamikaze/7.09/packages/mipsel

Replace 7.09 with your version. It will tell you the version when you log in. If you don’t want to log in again, run ‘cat /etc/banner’.

For example, to install ‘nano’, run ‘ipkg install nano’.

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.

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

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 parabolic reflector that will focus the radio signal broadcast by your router to whichever direction you choose.

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

OKS

OKS has a public, caching, standards-compliant DNS server:
76.121.249.193

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

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.