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.

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)

Credits

© 2009 Matt Ventura and Darren VanBuren. This work is licensed under the GNU Free Documentation License version 1.3.

Tags: gnu, linux, openwrt, tutorial

This entry was posted on Monday, August 17th, 2009 at 22:40 and is filed under linux. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.