I know this page needs a stylesheet really badly...

Rop's OpenWRT software repository

( See this repository's index at nthill's OpenWRT Package Tracker )

Linksys WRT54 family of routers

Linksys makes wireless routers called WRT54G and WRT54GS. They are nifty little diskless networking computers with a wireless card, and they pack a surprising amount of power for a low price. I started playing with WRTs late 2004 and quickly discovered that there was a complete Linux distribution for it, called OpenWRT. The Linksys software that comes with the device is also based on Linux, but OpenWRT packs a 'Flash File System', meaning you can create and change single files in the flash ROM of the device, instead of having to create a whole new 'disk image' every time you need to change one file. By 2005 I had built some of my own stuff and had a few things done that I wanted to share, hence I created this software repository.

Here you'll find 'ipkg packages', stored together with an index file in a standardized format. Ipkg packages are the standard way of distributing software for OpenWRT. I tried to include not only my own packages, but also all the 'dependencies', the other packages my packages need in order to work.

Let's get started: If you are not yet running OpenWRT on your Linksys, go to the OpenWRT website first, and follow the instructions there.

Got OpenWRT?

Good. Once you've looked around and are a little familiar with the Operating System, you need to add a line that reads:

src rop http://www.xs4all.nl/~rop/openwrt

to the file /etc/ipkg.conf. After you've done that, run 'ipkg update'. Now you're ready to install software from this repository. I strongly recommend doing it this way instead of supplying the package URLs to ipkg directly, because of the 'dependencies', which are all included here.

Comments

I'd like to hear any comments. I'm on the OpenWRT forum as 'rop', but you can also e-mail me.


ipkg-create

I do write my own stuff as well, but the packages I build are often built around other people's stuff. Sometimes I only fix a small problem, add a few lines to a config file or modify an installation script. I found the existing way of making packages too much geared towards people that make stuff just once on some other Linux box. I want to tinker with stuff while it's on the WRT, and not have to redo my tiny change to a config file on some Linux box just because I can't make a package on the WRT. So I built ipkg-create

If you install ipkg-create, it will replace the ipkg shell script, renaming the existing one to 'ipkg.orig'. Yes, you read it right: the whole ipkg system is actually a shell script. The new version of ipkg accepts a new command 'ipkg create' which will rebuild an installed package on the system, using the meta information stored in /usr/lib/ipkg/info.

To create a package, you must have the meta-information in the first place. Your old version of ipkg threw this information away, except for the scripts it needs to execute on uninstall and a list of files. My new ipkg keeps the <package>.control file, which holds the meta information, as well as the <package>.preinst and <package>.postinst installation scripts.

Modifying existing packages

So if you install a package after ipkg-create has been installed, you can simply run 'ipkg create <package>' to re-create that package. Your new package will be placed in /tmp. This already allows you to install a package, tinker with a few lines in a config, and then re-create it. You may or may not want to edit the /usr/lib/ipkg/info/<package>.control file to replace the name of the package maintainer if you plan to share the resulting package.

If you want to re-create a package you've installed before you installed ipkg-create, you'll have to create the /usr/lib/ipkg/info/<package>.control file yourself. If you installed from a repository, the necessary information for the control file may be in one of the files in /usr/lib/ipkg/lists. Make sure you leave out the Filename, MD5sum, and Size lines when creating your control file.

Creating a whole new package

The most powerful thing ipkg-create can do is help you create a whole new package from scratch. It may sound much more complex than it is, and the easy steps below will quickly help you create your first package. In the examples below, replace '<package>' with the name of your package, without the '<' or '>' signs.

list: a list of files and directories

First install/compile or otherwise create the files which are to be part of the new package. Test everything, and make sure you're packaging working things. Then, at /usr/lib/ipkg/info/<package>.list, create a list of files and directories which are part of your new package. The system is pretty picky about this file: any directories have to be in the order the system needs to create them, so from the top down. And you need to list all directories, even if you are sure they exist already. So an example <package>.list file would look like this:

/usr
/usr/bin
/usr/bin/someprogram
/etc
/etc/someprogram.conf

control: the meta-information

Then you will want to create a file /usr/lib/ipkg/info/<package>.control, which holds the meta-information about your new package. It might look like this:

Package: someprogram
Version: 0.3
Architecture: mipsel
Source: http://www.someprogram.net
Maintainer: Rop Gonggrijp 
Section: net
Priority: optional
Description: Someprogram does, ehm, you know, something really really well.

conffiles: a list of configuration files

Ipkg comes with a mechanism that helps prevent overriding configuration files that have been changed by the user. If you wish to signal that some files are configuration files, you must list them in /usr/lib/ipkg/<package>.conffiles. In our case, this file might contain:

/etc/someprogram.conf

scripts

You could also include scripts to run before and/or after both installation and unistallation. These scripts are also in /usr/lib/ipkg/info and must be named <package>.preinst, <package>.postinst, <package>.prerm and <package>.postrm. In them, you can list shell instructions to create and remove symlinks, start the actual installed program, or whatever else you thinks should happen right before or after installation or uninstallation. Make sure the files are chmod'ed to be executable.

Now you're all set. Simply run 'ipkg create <package>' and watch your package be built. For instance, this is what I see when I build the ipkg-create package itself:

root@OpenWrt:/# ipkg create ipkg-create
ipkg_create: Creating ipkg-create...
Package at /tmp/ipkg-create_0.8b_mipsel.ipk
root@OpenWrt:/#

Uploading files

Ipkg-create doesn't only help you create packages, it can also upload them to a repository, and update the repository index file as well. To do that, you need to tell ipkg how to upload to a given repository, and supply the repository to be uploaded on the command line using the '-u' flag. First of all, you need to specify how to upload. We use the /etc/ipkg.conf file for this. For a repository that you can upload to, add a line that starts with the word 'upload' followed by a space and then the upload command in double quotes, followed by a space and then any upload options. In my case, my /etc/ipkg.conf file looks like this:

src rop http://www.xs4all.nl/~rop/openwrt
upload rop "scp -p %s rop@xs2.xs4all.nl:~/WWW/openwrt" multi
src openwrt http://openwrt.org/ipkg
dest root /
dest ram /tmp

The lower three lines were in there already: they define the official OpenWRT repository as well as what locations software can be installed to. The top line tell ipkg where the 'rop' repository is. The line below says we can upload to 'rop', and gives the scp command to do that. The '%s' part will be replaced by any filenames to be uploaded. The option 'multi' after the command specifies that the command will take a list of files, so I can upload a number of packages plus the index file all at once. 'multi' is currently the only upload option.

So, if I were to create and upload the ipkg-create package itself, it would look like this:

root@OpenWrt:/# ipkg -u rop create ipkg-create
ipkg_create: Creating ipkg-create...
Package at /tmp/ipkg-create_0.8b_mipsel.ipk
Downloading http://www.xs4all.nl/~rop/openwrt/Packages ...
Connecting to www.xs4all.nl[194.109.6.92]:80
Packages             100% |*****************************|  5926       00:00 ETA
Done.
Updated list of available packages in /usr/lib/ipkg/lists/rop
WARNING: Ignoring unknown argument '-x'
WARNING: Ignoring unknown argument '-oForwardAgent no'
WARNING: Ignoring unknown argument '-oClearAllForwardings yes'
Password:
Packages                                      100% 5926     0.0KB/s   00:00
ipkg-create_0.8b_mipsel.ipk                   100%   12KB   0.0KB/s   00:00
Upload complete
root@OpenWrt:/# sh: turning off NDELAY mode
root@OpenWrt:/#
Note that I typed in my password in the exchange above, and note the "WARNING: ..." lines as well as "sh: turning off NDELAY mode". They come from scp (part of the 'dropbear' ssh package). If you also use dropbear's scp to upload, you can safely ignore these messages.

Sharing packages

Sharing packages is great, and is a great way to help others with a WRT that wouldn't trust themselves compiling or changing stuff. But sharing packages you created with others on the net comes with responsability as well. Your software, or compilation of software, will be installed by people that know less about Linux, OpenWRT or computers in general than you do. Meaning they may not be able to quickly clean up the mess if your package screws up. So please make sure your package doesn't simply overwrite stuff they will need even after your package is uninstalled. Make sure your uninstall scripts leave the system the way it was before the package was installed. Put a clear desciption in the control file so people know what they're installing. And most importantly: test, test and then test again. Install your package on a an 'empty' OpenWRT if you can, and repeatedly test the install and uninstall to see if all is well. Make sure you list the dependencies in the 'Depends:' line of the control file, and consider hosting mirrored copies of any depencies (if there's no legal issues with that).


php

Two versions of PHP here. The package 'php4' contains a stock PHP4, with a wrapper script to enable PHP to be ran from thttpd or Busybox's httpd. Something to do with an environment variable that needs to be set. Just install the package and check /cgi-bin/phpdemo.php to see how it's done.

There's also a php5 package, which for historical reasons is simply called 'php'. I first decided to compile my own because I thought I wanted to use the SQLite database stuff included in PHP5 as well as 'sockets' which aren't compiled into PHP by default. At 2.2 MB, the resulting PHP binary is rather large, but since the JFFS flash filesystem under OpenWRT compresses its data, it 'only' ends up using 900 kB or so out of the 6 MB available in flash (on my GS). Simply type 'ipkg install php' if you want to install this version of php. It will also install a demo to show that this php is usable from the OpenWRT built-in 'busybox webserver'. If you haven't changed the default IP-address of your Linksys, surf to http://192.168.1.1/cgi-bin/phpdemo.php after you've installed the package.

Note: for the PHP5 I didn't yet know the wrapper trick to get the CGI version to work. At some point I gave up and made the CLI version. This means if you use the php5 you'll have to make any HTTP header info yourself, and make sure there's no empty lines before it. It ain't completely pretty, but check the phpdemo.php example to see how I get it to work.

thttpd

I needed to run more than one CGI-BIn program at the same time. So I packaged thttpd: a simple, small, fast, and secure HTTP server. This package is compiled and configured to be a drop-in replacement for busybox's httpd. (This thttpd is not compiled with PHP support) The package is configured such that it is a drop-in replacement of busybox's httpd: directories are the same, it also runs as root(!), all the paths are set correctly, the CGI-BIN path is the same. It kills httpd, renames the init.d startup for it and then places its own startup script, after which it starts itself after the install is complete. So you can be browsing the box while you install this package, and all of a sudden you'll be served by a different daemon. (Uninstall is equally seemless...)

tor & privoxy

I like privacy and anonimity technology, and Tor is one of the current state-of-the-art masterpieces. It employs something called 'Onion Routing' to create a path of routers between the Tor user and the site to which he/she wishes to connect. Through cryptography, Tor makes sure none of these routers know the entire path, and it is thus very hard for an attacker to figure out where a connection is going to or coming from. For instance this can be great if you're visiting the competition's website without them knowing it's you, or for shopping around for a new job without your current employer knowing you're about to quit.

Tor installs what's called a 'socks proxy' which other applications can connect to. But if you told your web-browser to connect straight to this socks proxy, it would still (in the clear) ask your regular DNS servers you use for the IP-address of 'www.iwannaquitmyjob.com', which might not be what you want. So you need to install 'Privoxy', an HTTP proxy in front of Tor. It will help by tunneling the DNS name instead of the IP-address to Tor. My packages do all the config file stuff and generally make things easy. Install both packages like below.

Tor needs the correct time to be set on the Linksys in order to work. Use my 'settime' package to set the time automatically, both at boot and periodically. Ofcourse you can leave out the settime package from the 'ipkg install' command below if you already have a reliable method for making sure your Linksys has correct time.

root@OpenWrt:/usr/lib/ipkg/info# ipkg install tor privoxy settime

Downloading http://www.xs4all.nl/~rop/openwrt/tor_0.0.9.1_mipsel.ipk ...
Connecting to www.xs4all.nl[194.109.6.92]:80
tor_0.0.9.1_mipsel.i 100% |******************************************************|   629 KB    00:00 ETA
Done.
Unpacking tor...Done.
Configuring tor...
Starting Tor
Jan 27 15:46:32.512 [notice] tor_init(): Tor v0.0.9.1. This is experimental software. Do not rely on it for strong anonymity.
Jan 27 15:46:32.529 [warn] Fixing permissions on directory /usr/share/tor
Done.

Downloading http://www.xs4all.nl/~rop/openwrt/privoxy_3.0.3_mipsel.ipk ...
Connecting to www.xs4all.nl[194.109.6.92]:80
privoxy_3.0.3_mipsel 100% |******************************************************|   200 KB    00:00 ETA
Done.
Unpacking privoxy...Done.
Configuring privoxy...
Starting privoxy
Jan 27 15:50:24 Privoxy(01024) Info: loading configuration file '/etc/privoxy/config':
Jan 27 15:50:24 Privoxy(01024) Info: Privoxy version 3.0.3
Jan 27 15:50:24 Privoxy(01024) Info: Program name: /usr/sbin/privoxy
Jan 27 15:50:26 Privoxy(01024) Info: Listening on port 8118 on all IP addresses
Done.

Downloading http://www.xs4all.nl/~rop/openwrt/settime_0.2b_mipsel.ipk ...
Connecting to www.xs4all.nl[194.109.6.92]:80
settime_0.2b_mipsel. 100% |******************************************************|  1224       00:00 ETA
Done.
Unpacking settime...Done.
Configuring settime...
NTP server to use (ENTER for ntp.xs4all.nl):
Done.

At this point, simply tell any web-browsers on the network to use your Linksys as HTTP proxy on port 8118, and you're all set. Privoxy, Tor and the ntp setting of time are all set up to be started automatically when the system reboots.

torify with tsocks

The Tor package by itself also installs a library called 'tsocks' and a script called 'torify'. This allows you to connect any networking application on the Linksys itself through Tor. Example: If you run 'torify ssh <host>', you will be ssh-connected through Tor.


toritall

Toritall is a work in progress. It is an experimental script which allows you make all the TCP connections from the subnet behind your Linksys go through Tor. Toritall (brace yourself!) uses the Linux 'ip' command to do source routing to connect the subnet traffic (but not the traffic from the Linksys itself) to a pppd daemon, which in turn connects to a torified slirp. Slirp is a ppp daemon that runs in user mode and does not make any network devices. Torifying it (see above) and then connecting to it from a normal pppd allows us to have a ppp0 network device that ends up in the Tor socks proxy. Simply install the package with 'ipkg install toritall': all the (many) depencies will be installed automagically. After it installed it all, run 'toritall start' to start the diversion through Tor, and 'toritall stop' to route subnet traffic straight to the net again.

Toritall is still highly experimental and production use is strongly discouraged. Known problems include:

Whoops. Version 0.3b now actually works: there was a hardcoded IP-address in there which made it work only here.


settime

If you install settime by typing 'ipkg install settime', you will be asked for an ntp server. If you enter a valid server here (or hit enter for the default server: ntp.xs4all.nl), the system will be set up to query that server for the correct time, both at boot and once an hour after that. Settime sets up crond to run to do the once an hour bit.


joe

Nothing really special about the joe editor package in this repository, except that it also sets up the 'jpico' symlink to the joe binary, and places a 'jpicorc' config file in /etc/joe.


kismet-drone & kismet-server

The famous 802.11 wireless sniffer, compiled for the Linksys. Other packages on the net only give you the kismet_drone binary, so you have to run server and client on your PC. By installing the kismet-server package, you only need to run the kismet_client on the PC. I'm building a nice piece of software which is a kismet_client, so that's why I needed the server on the Linksys. You need to add the IP number or range of any cnnecting clients to the config files if you wish to connect to either from anywhere but the Linksys itself. Also note that the names of the packages have a minus sign while the binaries have an underscore: the underscore is not a legal character in an ipkg package name.

You might also enjoy a kismet_client.exe for Windows. If so: download kismet_client_win32.zip, unpack to one directory and run kismet_client.exe. You can change the "host" line in the kismet_ui.conf file if the internal IP-address of your Linksys isn't 192.168.1.1.