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:
- Reflash the TL-MR3040 with the PirateBox version of OpenWrt 12.09 “Attitude Adjustment”.
- Do the first-time OpenWrt set-up.
- Install PirateBox v1.0
That much is going to be a lengthy posting in and of itself. In part 2, we’ll
- 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
- Throw away the index page, and replace it with one of our own
- Implement the rest of the web site in the shared directory on the USB drive
- 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 http://stable.openwrt.piratebox.de/auto/openwrt-ar71xx-generic-tl-mr3040-v2-squashfs-factory.bin
For a version 1 device, you will want http://stable.openwrt.piratebox.de/auto/openwrt-ar71xx-generic-tl-mr3040-v1-squashfs-factory.bin
In either case, get a copy of http://stable.openwrt.piratebox.de/auto/install_piratebox.zip, 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 192.168.0.1 on its Ethernet port, so we want our system to have an address on the same network that won’t collide. 192.168.0.2 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 “192.168.0.2” in the box below the pop-up and click “Apply”.
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 192.168.0.2 to 192.168.1.2, since when a new device comes up on OpenWrt, it uses the default address 192.168.1.1.
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
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.
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 install_piratebox.zip 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.