modified on 5 December 2009 at 23:46 ••• 61,120 views

RouterStation OpenWRT SW Setup Guide

From Ubiquiti Wiki

Jump to: navigation, search

Contents

Overview

This is a supplemental walkthrough of using OpenWRT "Kamikaze" on the Ubiquiti RouterStation family of products. We will explain how to turn a RouterStation board into a 1-3 radio AP with 1-12 virtual access points (using multi-BSSID). All RJ45 ports will be switched and connected to the LAN. When you are done with this walkthrough you should be familiar with the Kamikaze configuration files and be prepared for creating more specialized configurations.

Preparation

In order to get the most out of this document, you should print out a copy of http://downloads.openwrt.org/kamikaze/docs/openwrt.html. Whenever possible, this walkthrough will not attempt to reword these existing instructions. We will focus on a specific RouterStation configuration as an example to make the general instructions more concrete and usable. The general information in the docs will help you understand the meaning of the options and how to customize your RouterStation, and hopefully this document will be useful for some to get their head around the 'blank slate' of a fresh OpenWRT installation.

All of section 1 of http://downloads.openwrt.org/kamikaze/docs/openwrt.html applies to the setup operations described in this document. In addition, section 2.4 includes some information on debugging that includes serial and EJTAG.

Now, put this walkthrough aside and go skim over the first six pages of http://downloads.openwrt.org/kamikaze/docs/openwrt.html for a couple minutes. Don't try to understand the gory details but try to remember what kind of information you see and how OpenWRT tends to organize configuration files, etc. Just get a flavor for how Kamikaze handles configuration and initialization. Then, when you are ready to connect your RS board, proceed to the next section.

Connecting to RouterStation

The first thing we need to do is connect to the RouterStation. When you receive your RouterStation, it has been configured to allow three types of access:

  1. Network connections are supported using SSH version 2. Default credentials are provided in the package with your board, and in section 8 (no joke intended).
  2. RouterStation boards allow access via the serial console at 115200 baud 8-N-1.
    • The six pin connector, J3, has serial lines which you can connect to a level shifter/UART to the CPU. The board runs at low voltage, so you will need a level shifter that can operate from 3.3V and provide level shifting to RS232 power levels (normally you should need only +/- 5V for most PC's). Minimally, this means that the logic level 1 is anything above 3V and 0 is anything below -3V.
    • Digikey (and many other online vendors) will sell "level shifting" or "usb to ttl" or "usb to uart" type converters in board, cable and DIP styles.
    • One clean solution is to order one of the FTDI parts in the TTL-232R-3V3 series. These inexpensive USB to UART parts are readily available from digikey.com. Several variations are available:
      • TTL-232R-3V3 (with 6-pin header)
      • TTL-232R-3V3-WE (wire ended)
      • TTL-232R-3V3-PCB (USB + PCB + solder pads)
    The TTL-232R-3V3 header can be rewired by removing the sockets from the header and reconnecting them to match the RouterStation pin out. Only three wires should be connected to the RouterStation such that the six pin header now has:
    1 - NC,
    2 - ORANGE (Signal IN/RX),
    3 - NC,
    4 - NC,
    5 - YELLOW (Signal OUT/TX),
    6 - BLACK (GROUND)
    Just remember NOT to connect the +3.3V power from the USB cable to the +3.3V power pin on the RouterStation. Everybody has power, just leave that pin disconnected.
    • Any TTL to RS232 adapter (3.3V) should suite in case RS232 port is used (instead of USB) ([1] [2]).
    These parts are $20 or less in single unit quantities.
  3. RouterStation ships with a simple HTML diagnostic web page installed. If you access http://192.168.1.20 you should see something like the following:
Obviously the web page isn't much use, but once you have connected your serial cable or accessed the device over SSH to root@address 192.168.1.20, we are ready to begin. Note that if you use the serial port, you may see a lot of kernel logging/debug output during startup. Wait until it quiets down to start your work. The OpenWRT platform is configured to let you into a shell very quickly, before startup has completed.
Once you make it in, you should find yourself staring at the Kamikaze banner:

Configuration

Now, that we are connected, we can make changes to the file system. These changes will not overwrite the original files, but rather, will be stored as an 'overlay'. The underlying original file system is read-only, and all writes are saved in a separate area of flash as an "overlay filesystem" (we will talk more about this later). You will have to use either SED or VI as these are installed by default and we do not have a network connection yet, that would allow downloading.

Identification

Most of the configuration data we care about is in /etc/ and /etc/config. Start by editing /etc/config/system (using vi or sed) and specify a hostname and timezone.

Basic Network Settings

In order for the network access on the RouterStation to work, we need to add a default gateway to route any non-local traffic through. While we are at it, we should change the IP address from the default - so we won't conflict with the next device plugged in.

Edit the file, /etc/config/network. The file should start out looking like this:


We want to add gateway and dns options under the "lan" network configuration section so we can reach the internet.

If your gateway and DNS were both 192.168.1.1, then your file would now look like this:


Finally, let's change the IP address so that we do not conflict with other new boards plugged into the same network. Change option ipaddr and option netmask as necessary.

If you were going to change the IP address to 192.168.1.41/24 then this is what your network configuration would now look like:

Verification

To get these changes to take effect, you must reboot the device. Use the "reboot" command.

Once the system has restarted, ping your gateway. This will prove you have your internal network settings configured correctly.


Now make sure you can ping an external address by name, proving your DNS and your gateway are working together correctly, to connect you to the outside world.

Access Points

Access point configuration is stored in the file /etc/config/wireless. Power off the RouterStation, insert some Ubiquiti 802.11a/b/g card(s), and power the device back up. The /etc/config/wireless file will now contain configuration sections for each radio it has found. For security reasons, these new AP configurations are always disabled by OpenWRT by default. This prevents someone using a settings reset (sometimes called "factory reset" or hard reset) to gain access to your network. The file should initially look something like this:


There will be one wifi-device and one wifi-iface for each card you have inserted.

Enabling APs

To enable the AP, remove the "option disabled" lines and the "REMOVE THIS LINE" comment.

Configuring Radios

Each radio can have a channel restriction (option channel), country code (option country), distance (option distance), and a mode restriction (see option agmode).

option channel
Optionally specify the channel of operation for the AP.
option country
Optionally specify the country of operation for the AP (us, uk, fr, de, etc.).
option distance
Optionally specify the distance between the AP and the farthest supported station (for setting ack timeouts).
option agmode
Optionally set the mode for the card. Choices are: 11b, 11g, 11a, and 11bg.

Configuring APs

option ssid
You will probably want to change the SSID's, here's a command for that (assuming you want the same SSID on each virtual AP): command is missing, this needs to be filled in.
option network
Having the "option network" set to LAN means that users on the wireless device will be connected (bridged) to the LAN network - as configured in /etc/config/network (e.g. If option network is "lan", then Atheros devices would be added to "br-lan".) .
option encryption
You can choose none, wep, psk, psk2, wpa, or wpa2 for encryption. "psk" and "wpa" are WPA1. "psk2" and "wpa2" are WPA2. If you select wpa or wpa2, then you must also configure the RADIUS server (option server), port (option port), and shared secret (option key).
option key, key1, key2, key3, key4
This option applies if you have selected encryption. The key will be the WEP key ("wep" encryption, WPA key ("psk" or "psk2" encryption) or RADIUS shared secret ("wpa" or "wpa2" encryption).
option server and option port
If you have selected "wpa" or "wpa2" as your encryption means then you must enter the server IP address and port by adding "option server <ip address>", "option port <port>" entries.

Multi-BSSID (virtual APs)

To create more than one AP (you can have up to four per radio), copy the "config wifi-iface" section until you have from 0-4 APs defined per radio.

Assuming we wanted to create a three-sector AP with the same SSID for each sector, "ACME" then we might end up with a configuration containing three pairs of sections. Each section would have a radio on a different non-overlapping channel.

Each AP setup should look more or less like this:

Reboot

Again, you will need to reboot for these options to take effect. Upon reboot, your APs will be up and running.

More Information

Full details on all available options are in the manual for Kamikaze. See http://downloads.openwrt.org/kamikaze/docs/openwrt.html for the full documentation on the options. Fairly complete control over routing/bridging/firewalling/QOS settings is provided.

The Overlay File system

Examination

Now, we have modified a couple of files in previous steps, so let's look at the overlay files. By default these are in /jffs (a JFFS2 file system, by the way). You can use the command "find /jffs -type f" and you should see something like the following:


From this, you can see that we have changed a few files. We just changed network and system in this example sequence. The startup scripts also changed wireless, dropbear keys, and httpd, by the way, and I was playing with the USB storage hotplug script.

Reverting Overlaid Changes

If we want to undo one of these changes, we must perform this in two steps. I will assume the file is 'important' and should not be replaced until a reboot. To have it not overwritten, you can delete the modified copy UNDER /jffs (OR you can delete the file in the real original location, and mini-fo will delete both). However, we now have a record in mini-fo that we deleted the file to take care of. The metadata looks like this for a deleted file:


If we edit that file and remove the line recording "D" for delete, and reboot, the file comes back.

Live Updates [with opkg]

Now that the network is working, you can hopefully update the packager's information, assuming access to the Internet. Use "opkg update" and it should download updated package lists.

Live Upgrades [with opkg]

You can upgrade the system with "opkg update" followed by "opkg upgrade". For each configuration file you have modified it will give you the following prompt:


You'll know what is right in your situation, but "diff is installed" so I recommend you use that and make sure you know what you are getting before you choose.


See http://wiki.openwrt.org/OpenWrtDocs/Using for details on the effects of upgrade.

From section 2.4 of that document, "Upgrading OpenWrt completely replaces the filesystem. This means that your previous password and ssh keys will be erased and you will have to set your password again." This also means it will revert to default OpenWRT behavior (again see http://wiki.openwrt.org/OpenWrtDocs/Using page). By default they have no root password and you have to login over telnet.

If you want to keep your password, use the passwd command. This will save the change to the mini-fo overlay filesystem and it will persist across the upgrade. If you have changed your password (and you should) then your password will still be present after the upgrade, though you might have to login via telnet. You can then decide on telnet or ssh depending on your preference. If you really wanted to keep the ubnt password, you could use "cp /etc/passwd /jffs/etc/passwd" to keep the existing "ubnt" password.

WARNING: The latest OpenWRT code changed the expected board ID from what our boot loader emits by default. In order for your board to be recognized as a RS board you must change the boot script in RedBoot so that exec has the following arguments: exec -c "board=UBNT-RS" - this will make it work with OpenWRT trunk/head revision (but not with the root file system RS ships with). (Unfortunately, the name was changed in OpenWRT trunk after the RS firmware went to manufacturing. If you are rebuilding the firmware yourself, you can add support for the actual board name returned by our boot loader fairly easily - or you can update your boot script. In the future we will change "UBNT-RS" to be passed automatically.

Updating the flash image using the reset/tftp recovery option may reset the boot script as part of recovery - which is normally a good thing for de-bricking boards, but might erase your customized exec parameters (like hacked board ID setting for OpenWRT trunk/head).

As a general precaution, make sure you have a serial connection to the RouterStation before attempting to upgrade to the bleeding edge code from OpenWRT.

Tips for Live Upgrades and Updates

The only trick with upgrading to an overlay file system is that it doesn't erase the old file system, it just marks things as removed. Therefore, you need an awful lot of flash storage available, especially while both kernels and all modules are installed. Installing some updates and additional packages will fit, of course, but if you intend to "upgrade" a live system you will need to use an external media such as a USB disk or an SD card.

Installing a new Firmware Image

Note: The RouterStation and the RouterStation Pro firmware images are NOT COMPATIBLE. Be sure you are using an image that was build for your device!!

The ideal system is one that is tailored to meet your needs precisely. It will output a file in a format that can be understood by our recovery utility in the boot loader. Look for the image with "ubnt" in the name. Boot the system in recovery mode by holding the reset switch for a few seconds while powering on the device. You can then upload the new firmware to the device using TFTP to the device on the default IP address, 192.168.1.20.

Ubiquiti's RouterStation UI/Firmwire Challenge resulted in three new and innovative user interfaces. If you'd like to try one on your RouterStation you can find images on the winner's pages.

Notes for Users

User Account Information
  • The default username is root and the password is “ubnt”.
Ethernet Access
  • The default IP address is 192.168.1.20/255.255.255.0
  • The boot loader (RedBoot) will *ONLY* work with the WAN port (the one marked PoE)
  • The OpenWRT Linux build will respond on ALL ports by default, and bridges them by default.
  • The device will look like a 4-port switch until you install firewall/filtering/forwarding rules between LAN and WAN, or disable the bridge entirely.
  • The device ships configured with SSH enabled, and telnet disabled.
  • The first Ethernet device (eth0) is WAN; the second (eth1) is the LAN switch (all three LAN ports).
  • Ethernet Switch Security
    • Taking eth1 (LAN port) down will disable the CPU's MAC and block traffic between the CPU and the switch, but does NOT stop the switch from passing traffic between RJ45 ports 1-3.
    • Traffic is NEVER passed between LAN and WAN by the switch chip.
    • If you want a bridge between LAN and WAN - you need to configure one in /etc/config/network and secure it with /etc/config/firewall rules.
    • Switching between LAN ports is offloaded, and ACL/VLAN/QOS/etc are not configurable with current OpenWRT AG7100 drivers.

(NOTE: Atheros appears to license an SDK for building managed switch applications using this AR8316 chip (unconfirmed)).

Serial Console Access
  • On RouterStation, a six-pin header in a single row is provided for connecting a level-shifting UART.
    • J3 has { pin1 - 3.3V, pin2 - S_IN, pin5 - S_OUT, pin6 - GND }
    • The serial header has very low voltage and must be "level shifted" by another chip such as the MAX3232E.
    • The chip must handle low power signals and turn them into something a standard PC serial port can use.
    • If you use a USB cable/module with this level shifting UART built in, just be careful not to connect both [USB and RS's J3 pin 1] power sources at once!!
  • Connecting to Routerstation
EJTAG port
  • The EJTAG port is a standard MIPS EJTAG connection.
  • MIPS32/EJTAG compatible JTAG probe devices should work.
  • UBNT (and Atheros) use the Abatron BDI 3000 for this, and it works well.
  • Depending on when you got your RouterStation and how your JTAG cable is constructed - you may need to remove a pin that is commonly used to key, or ensure proper orientation of, the EJTAG connector.
USB Expansion / Compatibility
  • USB card readers will show up as USB devices for each card and hotplug will mount the cards as /mnt/usbdrive[x]. They will be mounted on startup and after insertion.
  • USB SD/SDHC cards have been tested up to 16GB. No other card types have been tested, but the USB device class is the same so it should work for most readers.
  • USB memory sticks / flash drives will be mounted as /mnt/usbdrive[X]. They will be mounted on startup and after insertion.
  • USB hubs can be connected, allowing multiple storage devices, addition of audio cards, serial ports, etc..
  • We have not yet tested external IDE/SATA hard drives or CD-ROM drives, but these should work as long as they are externally powered.
  • We have not yet tested USB sound cards, though the modules were enabled.
Unbricking
  • We will have a copies of the RouterStation firmware available for download on our web site. This includes the shipping versions of kernel and the rootfs from the shipping RouterStation. These will be packed up in a form that can be uploaded to our the boot loader while in rescue mode.
  • Power on the board while holding down SW4. The board will be in rescue mode, waiting for a TFTP upload of the UBNT firmware file.
Mounting
  • You should use #3 pan-head screws for mounting the devices and standoffs should have a small outside diameter or use non-metalic material.
FreeBSD

Notes for Developers

Documentation
  • There is no publicly available source of documentation for the AR7100-series of processors, other than the OpenWRT codebase.
  • Fortunately, OpenWRT includes a very well written and maintained GPL implementation of support for the board. Imre and Gabor of OpenWRT got permission to include parts of Atheros' BSP under the GPL - and have fielded a solid implementation.
Hacking AR7100-series SoC
  • Begin your adventures in target/linux/ar71xx and look for target/linux/ar71xx/files/include/asm-mips/mach-ar71xx/ar71xx.h to get your bearings.
  • From ar71xx.h you can get the memory map, register addresses, IRQs, PLL programming, special purpose registers, etc.
  • If you have questions beyond what you can figure out from the kernel code, please post them to either the ubnt or openwrt forums and we'll try to help.
Building
  • Ubiquiti will provide our current set of patches (always submitted to OpenWRT, but not always accepted/merged into the OpenWRT mainline yet)
GPIO
  • GPIO: AR71xx GPIO is provided by OpenWRT using sysfs.
  • See http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/gpio.txt;hb=HEAD for full documentation on GPIO access.
  • To make GPIO available from user-space, sysfs is supported. The base address on RouterStation is 0 and GPIO 9-15 (7 GPIO lines) are available for use in your projects.
  • To enable all available GPIO for user-space access via sysfs: for f in $(seq 9 15); do echo $f >/sys/class/gpio/export; done;
  • To reverse this, use:for f in $(seq 9 15); do echo $f >/sys/class/gpio/unexport; done;
  • Here’s an example of setting up GPIO 10 for output, initially high… sleep for a second and then set it low.
    • echo 10 > /sys/class/gpio/export
    • echo “high” >/sys/class/gpio/gpio10/direction
    • sleep 1
    • echo “0” >/sys/class/gpio/gpio10/value
  • Here’s an example of setting up GPIO 9 for input, and reading the value:
    • echo 9 > /sys/class/gpio/export
    • echo “in” >/sys/class/gpio/gpio9/direction
    • GPIO9VALUE=$(cat /sys/class/gpio/gpio9/value)
    • If [ ${GPIO9VALUE} -eq 0 ]; then echo “GPIO 9 is currently high”; \ else echo “GPIO 9 is currently low”; fi;