Installation Guide

From X-Wrt

Jump to: navigation, search


Installing X-Wrt


Getting started

Installing, flashing or upgrading a wireless router with an alternative firmware is in most cases a fairly simple task. You need a wireless router, some way of downloading the required firmware image and a computer. Your personal computer needs to have a network interface, but all you have to do is more or less independent of the operating system (the author of this has experience with FreeBSD, Mac OS X, Linux & WinXP).

as a note; Windows users should install an application such as the free telnet/ssh client Putty [1], if you want to be able to login directly to the wireless router. Should you choose to login to a wireless router running OpenWrt via ssh (in this case using the default terminal of OS X) it would look similar to the picture below:


The ssh-shell access offers a more-or-less common text-interface[2], where the more basic commands are supported. The default shell is 'ash' and the default text-editor is 'vi'. The OpenWrt system is based on just one user: root (aka. superuser) with a root-password. The default IP-address is normally:

The ssh-login sequence would be similar to the following:

  • ssh root@
  • The system will prompt for ssh authorization, type: yes
  • Type password
  • You have now logged into the default OpenWrt shell
  • Type exit to logout, and break the ssh-tunnel

Before Installing

Getting started does always begin with a question before you actually begin. The question you need to ask yourself is essential to the success of your endeavour:

  • Do I have an AP or router which is compatible with OpenWrt, and with X-Wrt?

If you already own a wireless router/AP then check if it is mentioned on the list of hardware supported by OpenWrt [3]. Alternatively scroll down a little and look at the list of hardware which is known to be supported.

Actual Install

The following will hopefully "walk" you through the complete process of installing X-Wrt, which is an alternative and extended web interface (webif) for OpenWrt. There are several different ways of getting there - so it's up to you the reader to choose the one which fits your personal skill levels and experience.


The following will in short form introduce what a wireless network router is, and list hardware which is known to be supported by OpenWrt.

Wireless router - the basics

Wireless routers can take different shapes and sizes, as the picture shows:


Generally all wireless routers have several ethernet ports, a wireless interface, and a number of LED's which indicate status and activity.

  • One WAN port
  • LAN port/s, normally 4-5 port switch[4]
  • Wireless interface with one or two antennas
  • One reset-button
  • Some devices also have a USB-port

When you unpack a new wireless network router you will typically have a little box which in its default configuration makes the following "assumption":

  • You have access to a WAN[5] which supports DHCP[6] (often through an ADSL modem[7])
  • You intend to base your network setup on a LAN with NAT[8] and dynamic DHCP IP-adress[9] allocation

In other words, if the new router is connected with an ethernet cable to the WAN, and then plugged into a electrical power-outlet - you should be able to connect via either one of the ports of the switch or via the wireless network interface build-into a laptop. Either way, the router will offer (serve) an IP-adress in the private network range[10].

The little wireless router is in reality a complete server, a computer with a CPU, memory, storage and interfaces through which an administrator can acquire access, and an operating system based on Linux[11] (in the case of the hardware mentioned below).

Supported hardware

The following list of wireless routers which are known to be supported by OpenWrt is not complete. It is always recommended to seek out advice if in doubt, and consult the official OpenWrt table-of-hardware [12] before purchase. It is sometimes an art to buy the right wireless router model, then manufactures keep changing specifications and hardware without notice. You might think that; this is the correct model, but when you look at the version number on the packing it tells you otherwise. The list of wireless routers known to be supported is split into firmware image categories, to download the appropriate image please click on the individual link (These images are the 'default', if you need PPTP images it is required to download these from the ftp repository):

  • openwrt-wrt54g-squashfs.bin[13]
    • Linksys WRT54G 1.0
    • Linksys WRT54G 1.1
    • Linksys WRT54G 2.0
    • Linksys WRT54G 2.2
    • Linksys WRT54G 3.0
    • Linksys WRT54G 3.1
    • Linksys WRT54G 4.0
    • Linksys WRT54GL 1.0
    • Linksys WRT54GL 1.1
  • openwrt-wrt54gs-squashfs.bin[14]
    • Linksys WRT54GS 1.0
    • Linksys WRT54GS 1.1
    • Linksys WRT54GS 2.0
    • Linksys WRT54GS 2.1
    • Linksys WRT54GS 3.0
  • openwrt-wrt54gs_v4-squashfs.bin[15]
    • Linksys WRT54GS 4.0
  • openwrt-wrtsl54gs-squashfs.bin[16]
    • Linksys WRTSL54GS
  • openwrt-brcm-2.4-squashfs.trx[17]
    • Buffalo WBR-G54
    • Buffalo WLA-G54
    • Buffalo WBR2-G54
    • Buffalo WBR2-G54S
    • Buffalo WHR-G54S
    • Buffalo WHR-HP-G54
    • ASUS WL500G
    • ASUS WL500G-Deluxe
    • ASUS WL500G-Premium
    • Mitsubishi R100 Diamond Digital Wireless Gateway
    • Ravotek W54-RT
  • openwrt-we800g-squashfs.bin[18]
    • Motorola WE800G
  • openwrt-wa840g-squashfs.bin[19]
    • Motorola WA840G
  • openwrt-wr850g-squashfs.bin[20]
    • Motorola WR850G
    • Motorola WR850GP
  • Non-stock: openwrt-brcm-2.4-squashfs.trx
    • Belkin F5D7230-4 pre. v1444
    • Siemens Gigaset SE505

There are other rebadged or less common brands (in which case it would be a good idea to look for advice). It is not recommended to acquire neither Netgear, ZyXel nor D-Link wireless routers in as much as these typically are unsupported or 'unstable/non-functional' work-in-progress (WIP) when it comes to OpenWrt support.

The best place to start looking for other supported wireless routers is in the OpenWrt table-of-hardware [21].

Before You Upgrade

It is a good idea to write down a little check list, if you are new at upgrading/re-flashing wireless routers. It could look something like this:

  1. Do I have electricity :-)
  2. Two ethernet cables (minimum)
  3. The correct firmware image
  4. A minimum of 60 minutes
  5. Food, drinks, music (and other nice things)
  6. And most important of all - are you relaxed?

Choice of installation

Depending on your skill levels, your plans with the router, the setup which is intended and numerous other aspects it is needed to make a choice between how to install the extended X-Wrt web-interface. The guide will go through each of the choices, which are:

  • Pre-built image (recommended for most users)
  • OpenWrt and X-Wrt via X-Wrt website
  • OpenWrt and X-Wrt as ipkg

Prebuilt image

If you are new to the process of upgrading an off-the-shelf product, or just want to get the router up-and-running quickly - this would be the right choice.

X-Wrt via website

Should you already have OpenWrt RC5/RC6/0.9 installed and functioning on a supported router, but little experience with working in the text-interface of a terminal-window -this option would be a safe way to upgrade from the standard OpenWrt webif to the extended interface of X-Wrt.

ipkg install

For users who have experience with OpenWrt and want to have more control over the local setup. There is nothing magical or difficult about installing X-Wrt via the buildin ipkg system of OpenWrt. It is suggested that all users familiarize themselves with this aspect of the underlying OpenWrt system. Installing the X-Wrt package is a relatively safe and uncomplicated way of beginning to learn how to use the text interface.

The different types of firmware image(s)

Depending on the type of broadband-connection the wired WAN-port will be connected to, it is advised to install the correct type of image. This choice is required independent of what way you install X-Wrt. There is a choice between the following:

  • Default image: The common connection type is based on the use of a dynamically, or static, assigned IP-adress. Where the WAN-port of the router is connected to the LAN-port of an ADSL-modem, in which case the standard TCP/IP is being used [22]. PPPOE (Point-to-Point over Ethernet)[23] is included in the default image. PPPoE, Point-to-Point Protocol over Ethernet, is a network protocol for encapsulating PPP frames in Ethernet frames. It is used mainly with ADSL services. It offers standard PPP features such as authentication, encryption, and compression. Unfortunately it has an MTU[24] lower than that of standard Ethernet which can sometimes cause problems with badly configured firewalls.
  • PPTP: (Point-to-Point Tunneling Protocol)[25]. PPTP works by sending a regular PPP session to the peer with the Generic Routing Encapsulation (GRE) protocol. A second session on TCP port 1723 is used to initiate and manage the GRE session. PPTP is difficult to forward past a network firewall because it requires two network sessions.

The documentation from your local ISP (Internet Service Provider) should be able to answer the question about which image to download and use for the upgrade. If in doubt, then use the default image for testing - you can always re-flash a different firmware.

Physical setup

When it comes to the actual process of upgrading the firmware it is highly recommended to be very conservative. It might seem an easy solution to initiate the upgrade while connected via wireless, but a wireless connection is not always completely stable. During normal use it happens that a number of data-packets are lost and therefore have to be re-sent. If packets are lost during an upgrade across a wireless connection it will result in a non-functional firmware, and the router will be "bricked". If boot-wait is turned on by default, or has been turned on before the upgrade, then it is possible to recover via a manual tftp upload of a new firmware image. The same problem might arise if the power to the router is turned off during the upgrade.

This is the reason why you should always connect to the router with cables and be sure not to turn off the router during the upgrade process.

As soon as the Underlying OpenWrt system has been installed, all other modifications and daily administration can take place via a wireless link.

(Note: Would be nice with an image showing a correct connected setup?)

Pre-built OpenWrt/X-Wrt

The easiest way to upgrade to the X-Wrt webif is by flashing one of the pre-built OpenWrt White Russian images. This procedure is recommended for most users.

The process consists in short form of the following steps:

  • Browse the X-Wrt ftp directory [26] for the OpenWrt/X-Wrt firmware image appropriate for your router (based on the filename).
  • Flash the image to your router by using the existing firmware's web interface to upgrade the firmware.
  • The router will automatically reboot on the first install of X-Wrt - and you are finished.

In the case of having bought a new router, like the cheap and commonly available WRT54GL model, you would need to do the following in a real-world case:

  • Download the correct prebuild image, with the title: openwrt-wrt54g-squashfs.bin[27]. This can be done while you have a functioning setup, with the not-yet upgraded router acting as a gateway[28].
  • Store the downloaded firmware in a practical place, and then log into the router (the same way as for your normal management):
  1. Type the IP-adress of the router in the adress bar of your browser
  2. Login with your username and password
  • Navigate to the Firmware Upgrade page of the original web-interface, the page should look similar to the image below (other router models might look different, but the principle is the same):


  • Browse to the already correctly downloaded firmware image, then check if everything seems to be ready - and then press the 'Upgrade' button.
  • While the physical upgrade/install is running the progress bar will move ahead - and it is important to not interrupt this phase.
  • The upgrade is finished when the router automatically reboots. When all the LED's on the front of the router have stopped blinking, and have become stable, you should be able to login.

First login

The Login procedure to the new and upgraded system is similar to before. On the first login you will first see a re-direct page (which re-directs the inquirery of the browser to the correct administration page in the file-directory of the OpenWrt system). Then the system will prompt the user (you) for a new password, which you enter"your password. Hereafter a normal login will require the following:

  • Username: root
  • Password: "your password"

Why should I enter a Root Password?

  • You need to enter a root password to keep strangers out of your router. The webif also does not allow you to configure your router till after a root password has been entered.

How is it done?

  • You can enter a root password by entering 'passwd root' and the command prompt of your router or by accessing the webif.

What is a best Root Password?

  • A good root password is one that is more then 8 characters in length and uses a mix of upper and lower case letters numbers and symbols.

How can I "recover" if I have forgotten my Root Password

  • If you flashed a squashfs image (only prebuilt option as of RC6) you can use failsafe to get into your router and reset the password as described in the OpenWrt wiki[29].


Information about how to use and configure the X-Wrt webif is found in the X-Wrt User Manual[30] - which presently is very much a work-in-progress :-)

If you have questions or need practical help - feell free to ask questions on either the X-Wrt IRC channel ( #x-wrt) or in the forum[31]. More detailed help with and documentation about the OpenWrt system are available on OpenWrt's Wiki [32]

OpenWrt and then X-Wrt via the website

The point of departure in the case is that you already have a functioning OpenWrt system installed on your router, but wishes to upgrade to the many extra features of the extended web-interface of X-Wrt. Or you just would like to experience what the default webif of OpenWrt looks like, as a direct way of comparing the two. The latter requires that you first install the latest OpenWrt image. The following will consist of:

  • Download OpenWrt image
  • Installing OpenWrt
  • Quick configuration
  • X-Wrt via website

Getting the correct image

As in the above example, is is needed to download the correct prebuild OpenWrt image - in this case the original image from OpenWrt which does not contain the X-Wrt extensions. This requires a quick browser navigation to the correct firmware repository, hosted at[33] - and the directory should look similar to the shown image:


Again it is assumed that the router you would like to upgrade is a WRT54G/GL - which then would require the download of the file named:

  • openwrt-wrt54g-squashfs.bin.

This image targets the WRT54G version 1-4 and the more recent WRT54GL model, which is identical to the version 4 of the earlier series.

Upgrading to OpenWrt

The initial upgrade procedure is identical to the above example - login and navigate to the original upgrade page and follow the explained steps. BUT, there is one major exception. When the upgrade has finished the route might not reboot by itself. The installation is not completed before the router has been rebooted, and the router will remain non-functional until this has happened. In the case that the router does not reboot automatically, you have to follow the below described procedure.

Reboot - the manual way

The upgrade to OpenWrt has finished when the progress-bar reaches the end, hereafter it should be safe to reboot. Though, while the upgrade is in progress the LED's on the front of the router will be blinking and it is required that this 'blinking' has stopped before the reboot is initiated.

Manual reboot:Pull the power pluck, count to ten and then re-connect the router.

When re-connected the LED's on the front of the router will be blinking, until the boot has completed, whereafter you can safely login. Generally speaking, the LED's are a quick way of diagnosting common problems with wireless routers, and problem solving does often take its beginning with describing what the LED's are "doing" (or not doing).

OpenWrt is installed: Then what?

All the LED's are stable and showing that the router is ready to serve - the following LED's are on (the LED's might differ between the various router models):

  • Power
  • WLAN
  • Internet

In the case that the 'Internet' LED is not on, this might be caused by the settings of the ISP, which provides the internet-access, to route the WAN. The problem is normally solved by changing the default WAN settings of the OpenWrt system. This is easily done by a simple login to the default OpenWrt webif.

Before proceeding to install the X-Wrt extensions it is recommended, and sometimes required, to make a few basic changes to the default configuration of the OpenWrt system. This is also a practical way of ensuring that the router is completely functional, and to prevent potential problems.

Login to the OpenWrt webif

Login to your new OpenWrt system is done as previously explained - with the exception that you now have the added option to access the router via ssh-login (as shown in the beginning of this document).


The default OpenWrt web-interface consists of four categories, and it is called 'OpenWrt Admin Console':

  • Info
  • Status
  • System
  • Network

Each of these categories has a number of taps, or sub-pages, as shown on the image of the OpenWrt info page. Added to this are a few basic informations (in the top right corner) about:

  • Host Name
  • Uptime
  • Load (CPU load over time)
  • Version (of the installed firmware)

In the lower right corner you'll find three buttons titled:

  • Apply changes
  • Clear changes
  • Review changes

Depending on the context - what page you'r on - a fourth button will be visible:

  • Save changes

IMPORTANT: When you make changes in the settings of the system it is required that these are saved and applied before they become functional. In other words, it is needed to "click" the buttons before changes take place (the changes need to be written to the NVRAM [34] where the configuration is stored, before changes can take place).

Root Password

The first thing which should be done is to change, or add, the 'root password' of the router. This is done by:

  • Goto -> System -> Password Change

It is then only needed to enter the new password and confirm it - followed by saving and applying the changes.

Enable boot_wait

The second important thing to do is to enable boot_wait on the router. If boot_wait is not enabled it becomes impossible to access it router in the case of severe problems, eg. a faulty firmware or similar. Boot_wait means literally that the router waits a few seconds before it initiates the standard boot-sequence. This "waiting" makes it possible to access the router via tftp[35], and in this way upload a new stable firmware image. Tftp access does also double as an alternative way of installing/upgrading the router (only a few router models have boot_wait enabled in their original configuration).


As shown on the image, all which is needed is to switch boot_wait to 'Enabled' - and while you'r on the page it might be good to enter a new 'Host Name', and then remember to save/apply the changes.

WAN and LAN settings

The OpenWrt default configuration assumes the following:

  • The router is connected to a WAN with dynamic DHCP
  • The LAN is a private network[36], typically in the range

Quite often you do not need to make any changes to the default settings, but it is good to check if the LAN settings are correct or needs changes. This is done by:

  • Goto -> Network -> LAN


The LAN page handles the following settings (as shown):

  • IP Adress
  • Netmask[37]
  • Default Gateway
  • DNS Servers[38]

Furthermore might it be needed to check if you have the correct connection type to the WAN. This is done by:

  • Goto -> Network > WAN

On the WAN page there are the following settings:

  • Connection Type
    • None
    • DHCP
    • Static IP
    • PPPoE
  • IP Adress
  • Netmask

Normally you would not have to change more than the 'Connection Type' setting, to suit the requirements set by the ISP. The rest of the fields can be left empty at this moment.

If the connection type is PPPoE, you may need to input a username and password. In this case, note that the PPPoE password cannot be left blank, as this will result in the appropriate nvram variable not being set. (Perhaps it is possible to set a blank password through the OpenWRT command line interface?)

X-Wrt as ipkg install (via SSH)

This choice of installing the X-Wrt webif requires an already installed OpenWrt system (minimum RC5, but it is recommended to upgrade to 'latest'). Hereafter everything takes place via ssh/telnet login. Make sure the wireless router has internet access and that DNS is configured.

First, setup the x-wrt repository, by editing /etc/ipkg.conf and adding the line

src xwrt

Then, run ipkg update

After adding the xwrt repository, all which is needed to be done is to run one of the following:

The 'latest milestone' is the present stable version, whereas the 'latest daily' is the development version. The later might in respect to this have minor bugs, but typically more features.

How this is done in praxis is shown in the two following images. First, it is needed to login via ssh and you simply type, or copy/past the command - and then push 'enter/return'


During the actual upgrade/installation text will scroll down the terminalwindow, informing you of the progress.


When everything is finished, you will be prompted with the message: Successfully terminated, which means the installation procedure was a success. Hereupon you should be able to login to the new X-Wrt webif with your prefered browser, as described above.

ipkg system

The place to start to learn more about the ipkg system is here[39]. The site which the link points at, contains the basic documentation and commands related to the the ipkg system used on OpenWrt (and several other platforms). In short, ipkg is similar to the Debian apt-get package system[40]. There are numerous packages in the 'ports' list of OpenWrt, so you should feel free to modify the setup to fit your needs.

Build Software Method

This method is somewhat more technical and requires that you have a usable platform for compiling the image yourself - it is recommended to use a Linux OS platform for this, then cross-compilation from one platform to another is still highly prone to failure.

If you either need, or feel the urge, to build your own firmware image you should consult the following link [41].

After Upgrade

Login to the new webif

Enable boot_wait

Why enabling boot_wait?

What is tftp and how to recover from an upgrade gone wrong?

Upgrade to latest X-Wrt build

Use the button on the main Info page.

Why should I do this?

  • This can be done if you encounter a bug that has been fixed in later builds or if you just want to try out new features.

Configuration and use

Detailed information about how the combination of OpenWrt and X-Wrt is configured and used is found in the User Manual.

Personal tools