Thursday, October 10, 2013

PirateBox Reloaded

It's been a while since the last PirateBox update. The last version was based on a PAW server plug-in  that didn't work well for all users.
Meanwhile I developed a stand alone PirateBox Android app that hopefully will work better.

The new app is based on CyanogenMod 7 and was tested on a Nexus One.
I have no other devices running CyanogenMod but I hope that the app will run too on different versions of that ROM.

CyanogenMod 7 and Nexus One

This post will describe the app in some detail. Technical details about the networking part will not be covered, because these were described in the earlier post. The techniques are the same, so there is no need to go through all of that again.
For those of you not interested, don't worry, here is the download link to the app straight away. Just download the APK and install it. A rooted device is necessary and it has only be tested with CyanogenMod 7.

So here is the Google Drive download link: PirateBox APKs

Running the App

For those still reading here is the more detailed part...
When you start the app you will  see the (not so spectacular) main screen which basically consists of an image and a start button. If your device is not rooted or the device is missing some prerequisites there will be a message telling so and you will not be able to proceed.

PirateBox - Switched off

After pressing the start button the app will start to setup the network. There is no need to start the hotspot beforehand, that will be done automatically. The app also take care to create an open hotspot and to name it appropriately.
After all is set up, you should see three icons underneath the start button and a notification in form of a scull.

PirateBox - Running

The icons show the active components that are configured during start up. These are, from left to right, the web server, the access point and the network configuration.

 Connecting via Browser

The PirateBox should show up as access point with the default SSID named  PirateBox - Share Freely. The name can be changed inside the setting, but we'll come to that in the next section.

PirateBox - Wi-Fi Access Point

After connecting to the access point you should be able to enter any HTTP URL inside your browser's address bar to get to the index page of the PirateBox.

PirateBox - Index page

App Settings

The app has a few settings. We will discuss them briefly.

PirateBox - Settings

Start On Boot: If you check that option, the PirateBox will start up after the device has been booted and the SD card is ready.

SSID Name: You can change the SSID name here. The app will try to change the name immediately. A restart should not be necessary. The default name is PirateBox - Share Freely as mentioned above.

Storage Directory: The directory which contains the uploaded files and the messages inside the shoutbox. You can locate the directory wherever you like. The directory /sdcard/pb_store is the default.

Enable Updates: On default the configuration and HTML files are updated with each new version of the app. If you don not want to do that, because you want to use your own configuration, un-check that option and no updates will be done.

iOS WISPr Support: iOS devices use WISPr request to detect if the device is indeed online. If not the device will not permanently connect to the hotspot. If that option is enabled the iOS device assumes it's online.

WP NCSI Support: Basically the same as for iOS devices. Windows Phone request a NCSI file to check if it's online.

App Broadcasts

This is a more advances topic and directed to developers which would like to interface with the app.
You do not need to read this section to use the app.
The app broadcast Intents to make indications  about the state of the PirateBox , of file uploads and shout messages.
Here are the broadcasts and the extra values provided.

Extras: state (boolean)
Description: Indicates the state of the web server.

Extras: state (boolean)
Description: Indicates if the access point is running or not.

Extras: state (boolean)
Description: If the state is true, the networking (dnsmasq and iptables) are configured.

Extras: name (String), text (String)
Description: If a message is entered into the shoutbox, the name and text will be included inside the extras of this Intent.

Extras: file (String)
Description: Upon file upload the extra will contain the FQN of the file.

Current State

The app is in an very early state. I've tested as good as I could. There are surely bugs and  in some cases the app might not work at all.

New updates of the APK will show up in the Google Drive folder linked below.
So if you are interested, check the folder from time to time.

Feedback is always welcome!

Source Code

The source code is now available on GitHub.

In Case of Errors

If the PirateBox does not work as expected, please send me a mail describing your setup and include the LogCat output ... thanks

Mail address: jochen [at]

Download Links

Google Drive: PirateBox APKs


If you tried the app, please provide feedback by filling out the following questionnaire ... thanks!
The results can be viewed here, so you know on which configurations PirateBox is running.


  1. Installs and sets up tethering on CM 10, but doesn't get around to setting up the networking or share folders.

    If you want debug logs or other support, let us know where to find the logs and how to get them to you.

    1. Thanks for testing!

      Could you please send me the LogCat output after trying to start the PirateBox.
      Mail address: jochen [at]

      I'll try to get hold of a device running CM 10.

    2. I've uploaded version 0.2 beta.
      Hope that will now work for Android 3.x and up too.
      Couldn't get CM 10 with working WiFi tethering installed on my P920 test device.
      Had the chance to test it on a Samsung i9100 running EHNDROIDX 13.7.18 (Android 4.2.2).
      That worked fine, so I hope it will now work for you as well.

  2. Tested 0.2 Beta on a HTC Evo 4G on two roms. Ubersonic RC3 which is based on CM9 (Android 4.0.4) which didn't work and then CM 7.2, which works fine.

    Also tested on my rooted Htc One on 4.3 and it says 'Unsupported Device Command 'iptables' not found' which I wasn't too surprised by.

  3. I get "Piratebox running" message and I am able to connect to the SSID, problem is I don't get redirected to the Piratebox page

    I'm running S3 mini with

    1. You could try to connect to the PiratBox and do a nslookup.
      Looking up any name should result in the IP address of your Android hotspot.
      If not, it's not going to work.

  4. Works like a charm with my old ZTE Blade ( runs on ParanoidAndroid 2.81). Thumbs up!

  5. Awesome stuff. Can I have access to the decompiled code please? I'd like to make some adjustments and tailor it for my own uses. Many thanks in advance.

  6. Would be too much to ask to get a github repo for this ? I love the idea of PirateBox and I'm just learning about android, this would be a very nice app to study and contribute to.
    Great app, thanks !

    1. I thought about that. Let's see when I find time...

  7. The On button keeps flashing. "Pirate box is not running" and the access point icon in the app comes up every couple of seconds for just an instant. After a while of that it will eventually turn on and I am able to connect to it, but I don't get redirected to the piratebox page with a client. And it will turn off by itself after a while.

    1. Thanks for the report.
      Could you please fill out the questionnaire to get your device data ... thanks!

    2. I just sent you a questionnaire, on galaxy s3 mini

    3. Also, tried it today again and it started turning OFF and ON the AP, even continued doing it after closing out the app and turning on the flight mode.

    4. Did you fix this issue? I hace the same, could you help me?

    5. Did you fix this issue? I hace the same, could you help me?

  8. Seems to work perfectly on my old Nexus One running CM7, awesome job. I was just wondering, is it possible to add PHP support?
    I fiddled around quite a bit with PAW, PHP and the piratebox plugin to try and get them to play nice, but I wasn't able to serve PHP properly. I'd like to add a slightly more advanced forum while also keeping the piratebox functionality.

    1. There might be a blog post about it in the future, but here is the quick install guide.
      So you don't have to wait too long...

      1. Download the ZIP file:
      2. Extract the pb_php_setup folder to your PirateBox "html" installation directory (this might be /data/data/ or /sdcard/pireatebox/html)
      3. Start PirateBox with option "Autostart AP" off (so you can use the IP number whitout having to use the PirateBox AP)
      4. Open the webpage http://[PirateBox IP]/pb_php_setup inside a browser
      5. Press the install button
      6. Restart PirateBox
      7. Delete the html/pb_php_setup directory

      Hope that works...

  9. Great work on this port! I love it, although I am having a strange problem...

    It works intermittently. Sometimes I connect and am able to use it no problem, however sometimes it won't redirect say the address http://piratebox but when that happens I can use the Port from the app (45454) and it will work at http://piratebox:45454. I tried changing the port in the /sdcard/piratebox/conf/server.xml file to 80 but that causes the server to stop right after starting.

    The ~/piratebox/logs/server.log file is empty as well so I'm not sure where to find the LogCat file you wanted a copy of

    Using 0.3.1 beta and LG T-Mobile G2X (p999) with CyanogenMod 7.2.0-p999 Android version: 2.3.7

    1. Also, when I don't turn on the AP and access it though my network i can just connect to the IP directly without the port number, so it appears there's a problem between the server and the android tethering

    2. Normal (Java based) apps cannot run on privileged ports that's why the app uses iptables to forward port 80 to the port the server runs on.
      So if the forwarding does not work, the iptables rule might be lost (if it worked before).
      If forwarding is no longer working, you could try a re-setup from the root shell. FOr how this is done you can have a look at the Github source (NetworkUtil.redirectPort()).

      If the name resolution does not work that might be a dnsmasq problem. Dnsmasq is used to answer all DNS request with the IP of the Android device.
      For that to work, the dnsmasq that has been started when tethering comes up is killed and restarted with different parameters.
      For a test, start the PirateBox, connect to it and launch a nslookup from your PC. All requests should be answered with the IP of the Android device.
      You can have a look how dnsmasq is started by looking at the GitHub code (PirateBoxService.setupDnsmasq()).

    3. DNS has worked the whole time that's the first thing I would check.

      ~ $ nslookup
      > piratebox

      Name: piratebox


      So it has to be the port forwarding, I did a little googling and was looking at

      it doesn't seem to have the method redirectPort? I was wondering if perhaps that had something to do with it? (I'm just now starting to learn android programming)

  10. Submitted my system details yesterday via Docs form. Got a bit more info: I can add port 45454 to any http URL but https URLs don't work. The server seems to be rewriting URLs correctly, so wondering if an HTML file containing a redirect in its header can be placed somewhere to intercept requests on port 80?

  11. You're now added to my tutorial, thanks a lot for your work! ;)

  12. Galaxy s5
    I was able to download and connect to the ssid via my laptop. The issue is not being able to access the web page. left domain name default ( still no luck. Tried ns lookup still no luck... i guess ill buy the hardware and make my own.. great idea though

  13. This doesn't work on Samsung Galaxy S4 or Prestigio Multipad 10.1 it says that they need to be rooted.

  14. Just tried it on my old rooted Galaxy Infuse SGH I997R running 2.3.3 and it's working like a charm! I was using an old TP-Link router with a flash drive plugged into it as my piratebox for a while but about a year ago I messed up the configuration entirely to the point where I couldn't even get back into it through recovery mode so I had about given up on running a PBox. Thanks for this awesome tool!

    1. Ey, A mi me pasó lo mismo con un 3020. Estoy haciendo una etnografía sobre redes libres y me interesaría que me cuentes tu experiencia con pirate box y sobre todo con ese viejo router tp-link.

  15. Is this project still alive?

    I've been trying to get this working on my rooted Samsung SCH-S738C (4.04) (Build: IMM76D.S738CWYAMJ1).

    First I got 2 errors. 1 was not being able to back up my dnsmasq. I installed busybox and fixed that. The 2nd was command "iptables" not found. Indeed I did not have it on my system so I installed an app that gave me the command, but this error still persists. Do I need iptables(-save & -load)?


Note: Only a member of this blog may post a comment.