Building a Customized PirateBox, Part 1: Build a PirateBox

I wanted to have something fun and portable that I could use to promote the software literacy effort I’m spinning up here, and I thought it would be great to make a PirateBox that I could “re-brand” and use to share files and a microsite about what I’m doing and why it’s important.

The PirateBox project has spawned a number of customized versions, like LibraryBox, BibleBox, and others. I’m calling the one I’ve put together “nanonet”, and you can see a version of the web site it runs here.

What You’ll Need

  • A TP-Link TL-MR3040
  • A small USB drive — you only need the room for the base PirateBox install, under twenty megabytes, plus whatever space you’ll need for the web site you want to serve plus any files you want to share.
  • A Debian 7 “Wheezy”-like system with an Ethernet port that you can dedicate to this for a little while

I did my build on Linux Mint 17, but this will probably work on any Linux command line.


A “vanilla” PirateBox offers a chat window, a forum board, and the ability to upload and download files, in addition to its single-page HTML site. For my application, I wasn’t really interested in having people upload to the device, I just wanted to make material available for people to download.

The only “administrative” access to the PirateBox is via the Ethernet port, so there aren’t really any security issues to worry about on a device like this.


The TL-MR3040 is, in today’s terms, a tiny device, although in the mid-to-late ’90s, it would have been more or less the equal of a reasonably powerful PC. Its biggest limitation is internal storage: it’s got 16MB of RAM, and only 4MB of flash memory to play around with.

That’s going to limit what we’ll be able to put on the device, and aside from what’s needed to make PirateBox itself run, we’re going to limit ourselves to an index page, the stuff needed to support it (e.g. minified jQuery, etc.) Every thing else can go onto the USB drive, in a “Shared” directory.

We’re going to take things in the following order:

  1. Reflash the TL-MR3040 with the PirateBox version of OpenWrt 12.09 “Attitude Adjustment”.
  2. Do the first-time OpenWrt set-up.
  3. Install PirateBox v1.0

That much is going to be a lengthy posting in and of itself. In part 2, we’ll

  1. Extract an image of the on-board PirateBox web site from the install — this is the only portion where I actually used Linux, everything else was done on OS X
  2. Throw away the index page, and replace it with one of our own
  3. Implement the rest of the web site in the shared directory on the USB drive
  4. Customize things like the SSID of the WiFi network, the favicon, etc., to reflect the new “branding”

Installing OpenWrt “Attitude Adjustment” (PirateBox Edition)

Check which version of the MR3040 you’ve got, there are two different firmware versions, and you can brick your device if you try to reflash it with the wrong one.

To do this, take off the back — you’ll need to do this to install the battery anyway — and look at the barcoded label stuck on the label underneath where the battery goes. This photo shows the label on a v2.2 device, as indicated. For this one, we’d want v2 firmware. Do not guess at this. Be sure to check.


For a version 2 device, you will want

For a version 1 device, you will want

In either case, get a copy of, and expand it. Put the resulting folder, called install, onto your FAT-formatted USB drive. Do not insert the USB drive into the MR3040 at this time.

Again, be sure you’ve gotten the correct bin file for your device!

Start by installing the battery and plugging the MR3040 into a powered USB port via its own mini-USB port to charge it up. Both of mine have arrived with flat batteries. This will take an hour or two.

Configure the Ethernet port on your system. The MR3040’s factory configuration uses the link-local IP address on its Ethernet port, so we want our system to have an address on the same network that won’t collide. is fine.

To set it up on OS X, choose “System Preferences” from the Apple menu, then double-click on “Network”.

In the Network control panel, select your Ethernet port in the sidebar and then choose “Using DHCP with manual address” from the pop-up menu. Enter “” in the box below the pop-up and click “Apply”.

System PreferencesScreenSnapz004

Connect the MR3040 to your computer’s Ethernet port — they include a short cable in the box — slide the 3-way switch on the side to “3G/4G”, and turn it on. It takes a little while to boot, but you can check to see when it’s up with the command


at a Terminal command line. When you start getting responses to the ping, open up a browser window and enter the URL

The browser will ask you for a user name and password. For a new TL-MR3040, these are admin and admin. This will get you to the Administration app for the TP-Link software.

Click on “System Tools” in the sidebar menu, then on “Firmware Upgrade” when the accordion menu opens. That will get you to this screen. Note that the factory firmware version for the device is shown here. In this case, it’s v1, more than likely, yours will be v2.

Be very sure that the version of the firmware that you’ve gotten from the PirateBox site is the same as the version shown here. You can brick your device if you mix them up, and you’re a lot better off bricking your device after you’ve successfully installed OpenWrt than you are before, for reasons we’ll discuss another time.


Click the “Select” (or “Parcourir”) button to the right, and choose the bin file you downloaded earlier.

A scroll bar will appear indicating the progress of the firmware update. DO NOT INTERRUPT POWER ON THE DEVICE WHILE THIS IS GOING ON. While you’re waiting, go back to your Ethernet preferences panel and change the address you’re using from to, since when a new device comes up on OpenWrt, it uses the default address

Bring up a terminal window, and start pinging that address with the command


When you start getting a response to your pings — and it can take a while, maybe ten or fifteen minutes — we can proceed to the next step. (If you’re not getting ping responses after twenty minutes, the most likely problem is that you haven’t reconfigured your own system’s Ethernet port correctly.)

First Login to OpenWrt

Initially, OpenWrt only allows telnet access, has a single user, root, who has no password set, so the very first thing we want to do is telnet in and set that password.


When prompted to log in, enter root and hit return. You should see this:


Once you see this screen, you’re talking to ash, the OpenWrt command shell. Change the root password:


You’ll be prompted to enter your new root password twice. Choose something you won’t forget! Assigning a password to root will “activate” OpenWrt, and once we’ve closed the telnet connection, we’ll only be able to access the system via SSH from that point on, so you’ll need to use the command

ssh root@

When you’re prompted, enter your password, and you should be back at the OpenWrt command prompt shown above.

We’re now ready to complete our PirateBox installation. Get out of the telnet (or ssh) connection by typing


and power off the MR3040.

Install PirateBox

Finally, we’re ready to install PirateBox v1.0 onto our newly-configured TL-MR3040. This part is easy.

With the power still off, insert your prepared USB drive — FAT-formatted, with the install folder you unpacked from the file you downloaded earlier — into the USB port of the MR3040.

Turn the power on. Go do something else for fifteen minutes or so.

What you’ll observe, if you watch it, it a lot of blinking and flashing, occasionally interrupted by short periods when only the power light is lit — that indicates that the MR3040 is rebooting, which is does three or four times before the installation is completed.

After about the third reboot, if you scan your local Wifi networks, you’ll see the network “Piratebox — Share Freely!” appear. You can connect to that network, but it may go away if the install hasn’t actually completed yet.

Once you’ve been able to get onto the Wifi network that the MR3040 is creating, open a new browser page, and navigate to any address you haven’t browsed recently — caching can confuse things — or just go to http://piratebox.lan, the name the Piratebox uses to refer to itself. You should see this.


Congratulations! You’ve just created a PirateBox, a tiny self-contained web server based on a tiny version of Linux.

Explore and have fun — you can upload and download files, put up messages on a forum, or leave brief notes on the home page. It turns out that, when you’re out with a crowd, a PirateBox can be an easier way to share around things like photos rather than having to email them.

In part two, we’ll dig a little deeper into the internals of PirateBox and show how you can put pretty much any sort of a web site onto one.

If you follow this tutorial, please let me know how things worked out for you in the comments. If you run into snags, I’ll do what I can to help out.

Easy Build for OpenWrt On Ubuntu/Debian

I just got a TP-Link TL-MR3040 a few days ago, and successfully set it up as a PirateBox, which involved refreshing the firmware with OpenWrt rather than a stock image. This is actually a pretty cool little device for the $35, it’ll run Linux, and with OpenWrt, not only can it function as a router, it can act as a tiny server running off a file system attached via USB.

I’ve tried this build on multiple platforms, and documented some of that in a previous version of this posting. While I’ve successfully gotten the core of OpenWrt to build on OS X, and a number of things to build on CentOS, I’ve only gotten consistent and reliable results overall on Debian-like systems, so that’s what I’m going to be sticking to here.

In particular, I’ve had nothing but trouble trying to build an OpenWrt image for a Raspberry Pi anywhere other than on Debian or a Debian derivative. I have verified working builds for both the TL-MR3040 and the Raspberry Pi on Mint 17.

The instructions for building a firmware image on the OpenWrt wiki are a version or more out of date — they’re for building Attitude Adjustment, rather than Barrier Breaker.

The procedure for building top-of-trunk for OpenWrt developers is better documented than the Attitude Adjustment build seems to have been, but still a little bit scattered.

Additionally, the guide for setting up a build environment on OS X relies on MacPorts, and I prefer Homebrew, is similarly outdated, and there are a wrinkle or two along the way, so I figured I should document what I’ve done. I’m not recommending, at this point, that you try building this stuff directly on OS X. Use a VM running Debian or Mint instead, that’s my recommendation.

Set Up the Prerequisites

On Ubuntu 14.04 LTS “Trusty Tahr”/Debian 7.7.0/Mint 17

sudo apt-get install subversion build-essential libncurses5-dev zlib1g-dev gawk git ccache gettext libssl-dev xsltproc zip

On OS X 10.10 “Yosemite”

On OS X, we’ll want to specifically set up a case-sensitive file system to work on. We can create a .dmg file that we can use for our development with the following commands. Twenty gig is plenty of space.

hdiutil create -size 20g -fs "Case-sensitive HFS+" -volname OpenWrt OpenWrt.dmg
hdiutil attach OpenWrt.dmg

Getting the build environment set up right here is a little more ornate. If you don’t have Homebrew (and you should), you’ll need to get that installed first. You’ll also need to install Xcode and the Xcode Command Line Tools.

brew update
brew upgrade
brew install coreutils e2fsprogs ossp-uuid asciidoc binutils fastjar gtk+ gnu-getopt gnu-tar intltool openssl subversion rsync sdcc gawk wget findutils

When brew installs the gnu toolset, it doesn’t automatically link it into your path, and the build wants to use gnu-compatible tools. However, brew does create an auxiliary directory of gnu-compatible aliases at /usr/local/opt/coreutils/libexec/gnubin, and for the purposes of the build, we can set our path to preference those tools temporarily.

ln -s /usr/local/Cellar/gnu-getopt/1.1.5/bin/getopt /usr/local/opt/coreutils/libexec/gnubin/getopt
ln -s /usr/local/bin/gtar /usr/local/opt/coreutils/libexec/gnubin/tar
export PATH=/usr/local/opt/coreutils/libexec/gnubin:$PATH

Get the Sources

Get the Barrier Breaker sources from the upstream repo to build the current stable release:

git clone git://

Or pull down the latest OpenWrt “Chaos Calmer” sources to build the “bleeding edge” top-of-trunk version:

git clone git://

Prepare For the Build

Connect to the source directory, and update and install all the feeds. These represents the build schemes for all of the optional components that you can add to your OpenWrt system.

cd ~/openwrt
./scripts/feeds update -a
./scripts/feeds install -a

Configure the build.

make prereq

This sets up prerequisites for the build and then takes you into menuconfig, a screen-driven configuration utility based on the one used to set up builds for the Linux kernel.

For starts, you simply want to pick an appropriate “Target system” and “Target profile”. For the TP-Link TL-MR3040, the target system is “Atheros AR7xxx/9xxx”, subtarget “generic”. For a Raspberry Pi, the target system is “BRCOM947xx/953xx”, the only profile is “Raspberry Pi”.


For an initial build, I’d suggest simply picking the correct target and leaving it at that. You can start adding other options once you’ve verified that you can produce a working build and have an idea how much free space you’ve got to play with on the system. You want to start out minimal, the MR3040 only has 4MB (!) of available flash memory.

When you’re done here, select “Exit”, and save your configuration file as .config when prompted to do so.

Build that sucker!

All it takes is a make at this point. I like to use make V=s because I like to watch it do its thing.


Results will be in the bin/ folder, in a subfolder corresponding to the architecture you’ve built for — in my case “ar71xx”.