Thursday, December 1, 2011

PirateBox on Android

A while ago psundegroud created the thread [TUT]Roll Your Own PirateBox! PirateBoxMobile. At that time my only rooted device was an old Samsung Galaxy I7500 running Android 1.6. We managed to get this working. The two main issues were that WiFi Tether was needed, which didn't run on all Android devices and that only Ad-Hoc mode was available. The missing Infrastructure mode prevented most Androids from seeing the PirateBox hotspot.

Note: This post is somewhat outdated. The current state of the PirateBox can be found here: PirateBox Reloaded

Meanwhile I have a rooted Notion Ink Adam running AdamComb v0.3. So I tried to get PirateBox running by using the built in tether app. Built in tethering uses Infrastructure mode, which solves above mentioned problem.

On my Adam this is really working fine and I hope that it will also run on other Android units.
I'll divide the post in two parts. The first part describes the technical details, so if someone has problems in getting this to work this might be helpful for further testing.

Along with setting up the scripts I have also written a plugin for PAW which should make setup really easy.
If you are not interested in the technical details you can right jump to the Installing the Plugin section.

Techical Details

Setting up the PirateBox during boot is done by PAW startup scripts.

The main tasks of these scripts are:
  • Killing dnsmasq and restarting it with changed parameters, so that DNS requests always respond with the IP of the Android device.
  • Configuring iptables so that requests to port 80 are redirected to the port PAW is listening on, because PAW can not operate on privileged ports.
  • Change the PAW configuration to use the PirateBox Handler, which ensures that all unknown request are forwarded to the base URL (

The startup scripts are located in the subfolders 0 and 1 of the directory /sdcard/paw/etc/init. These folders represent PAW runlevels. Runlevel 0 is before the server starts and after server shutdown and 1 is after server start and before the server shuts down. Scripts beginning with S_ will be called on startup and scripts starting with K_ will be run at shutdown.

So here is a short summary what these scripts are doing.

  • Checks if tethering is running. If not none of the steps below will be performed.
  • Kills the "original" dnsmasq process and starts a new one.
  • Executes iptables commands to get port redirection working.
  • Replaces the original PAW configuration with the PirateBox configuration.

  • Checks if tethering is running. If not none of the steps below will be performed.
  • Restores the original PAW configuration.
  • Displays a PirateBox notification.
  • Sets the max upload limit to 200MB.

  • Clears the PirateBox notification.
  • Kills dnsmasq process.
  • Stops tetherig and restarts WiFi.

  • Removes iptables rules for port redirection.

If you run into problems have a look at these scripts and try to run the commands inside the scripts individually.

Installing the Plugin

PAW Plug-in Menu
Installing the plugin is easy. I've put it on the PAW plugin page, so you'll find it within the PAW web application or you can direct download it from the PAW Plugin Page.
After download extract the ZIP file to the /sdcard/paw/html/app/plugins directory of your Android device.
Now after re-entering the PAW web application, the PirateBox plugin should be visible in the Plugins menu.

If the plugin setup screen shows a warning in red, the installation is likely to fail, because some prerequisites are missing.
If no warnings are displayed, press the Install button. You can also try to setup a PirateBox Access Point (AP) automatically. I'm not sure, if this is working on all devices. If it's not working, please create an AP manually.
To uninstall the plugin, press the Uninstall button.

PirateBox Plugin

It is important to note, that PirateBox will only be started if tethering is active before PAW starts up.
Otherwise the normal PAW configuration will be applied. So you can choose between these two configurations.

I hope that's not just working on my Adam but on many other devices as well.

Here are some screenshots from my setup...

PirateBox Startup

Connected to PirateBox

PirateBox on Nexus One
PirateBox in Chromium


Here is a video that shows the PirateBox in action...


Since version 0.3 of the plugin, PirateBox is also working on rooted Galaxy Nexus devices running Ice Cream Sandwich.
Here is a video...


  1. I cant find these apps and all the PHP apps in the downloads. I think you have posted the PHP setup files instead. Also is the PAW server open source. I want to use it in a project.

  2. The link looks good to me.
    Here is the direct download:

    PAW for Android is not open source, but the project it is based on is:

  3. If you would like to integrate PAW in your own project, have a look at PAW Runtime:

  4. Thanks for that. Im a bit confused on the runtime. It doesnt seem to work for me. Im not sure of the difference between the two. I would be happy if I could get that to work. I will give it a try. The main thing I need is the connection bit at the moment. Is that in the runtime.

    many thanks for quick reply.
    I think there is a lot of scope for adding to this. I have speeded up a lot of the scripts but java etc are not my strong points. Just php etc.


  5. If you send me a mail with a description what you want to do, I'll have a look.


  6. Took me awhile to get piratebox plugin installed. Nowhere do you make it clear that the plugin menu is access through the web interface, but that's my only gripe about your amazing app. I'm still struggling with getting the piratebox plugin to run. It doesn't see Wi-fi Tether for Root is running I assume. I just flashed ICS onto this Nexus S 4G so perhaps there's a baked-in tether app onboard. I'll report back. So close!

  7. The plot thickens. I'm running an ICS rom (AOSP v6) on my Sprint Nexus S 4G. I installed Wi-fi Tether for Root Users, but there is a native tether application. The native tether app shuts down as soon as I turn it on. The Wi-fi Tether for Root Users causes this toast to pop up when I start the Paw Server. Screen Cap ->

    Any ideas?

  8. This has been tested with HC/ICS with the native tethering app. The Galaxy Nexus was on stock 4.0.1 at the time of testing.
    I now have 4.0.2 (without root), so I can't test that any more. The native tethering worked for me quite well, so it's strange, that it's crashing on your device.
    Other tethering apps I haven't tested with HC/ICS but it might be that the tether app you used notices that dnsmasq is stopped and hence terminates.

  9. I've installed POW and PirateBox plugin on my Samsung Galaxy S2 (Gingerbread 2.3.5, International). When I try to setup it with AP creation through the web interface, it reboots my phone. Without AP creation it works OK.

    With built-in tethering PirateBox works flawlessly and I can access it on my phone, I assume also upload/download files; haven't tried with remote device yet. When I try to use Wireless Tether for root users, POW starts as normal, without PirateBox interface.

    Is there a way to change the directory with the PirateBox files? I would like to switch it to /sdcard/external_sd/piratebox/ to be able to use bigger SD cards.

    1. The AP creation does not work on all devices, that's why it is optional.
      Interesting that it forces the S2 to reboot.

      The plugin works with built in tethering. Other tether apps will not work.

      In principle it is possible to change the location of the upload files. This would mean quite some changes to the scripts and possibly configuration files.

  10. Hmm... I just downloaded the newest version 0.84.1 of PAW Server. The server works fine but when I tried to install PirateBox, PAW Server has been denied superuser permissions. Restarted PAW Server with Wireless Tether on, nothing changed.

    Galaxy Tab SGH-T849
    Android 2.2
    Rooted via z4root

    1. This will only work if superuser permissions are granted. Otherwise the startup scripts can not change the network configuration.

    2. I know it's probably something I screwed up and Superuser isn't your app but I can't for the life of me get Superuser to give access to PAW Server. I tried setting Automatic response to Prompt but it never asked me. Superuser just denied PAW Server permissions. I tried to set it Allow, but even that didn't work. Any suggestions?

      Thanks for all your work.

    3. Sorry, I have no idea why that is not working. It always worked for me.

    4. I'm having a similar issue with SuperSU - I'm never prompted to give SU access to PAW, and PAW doesn't appear in the SuperSU logs.

    5. Hmmmm, I realised that after hitting install in the PAW web interface that a SuperSU popup appeared on my phone. I granted it permission, but it still isn't working.
      The PAW web interface says that the plugin is installed, however.
      Also, I tried uninstalling the PirateBox plugin, and the re-installing it, but the app never requested SU again.
      I notice that when I shutdown PAW that tethering turns off with it. Related?
      Samsung Galaxy S2

    6. Hmm .. it's hard to tell what's going wrong.
      You might have to have a closer look at the startup scripts.

  11. all is ok for me,
    nexus one miui rom only with the miui tether app (doesn't work with tether for root)

    but how to upload big files bigger than 2M?

    1. The upload size should be increased (I think to 200MB) by the startup scripts.
      If that isn't working you can try to set it manually. The size can be set in the file:

      After that a server restart is necessary.

    2. oh you were right, i tried from my PC it is ok for 200mb.

      But before i was testing with my android tablet and it was not ok. i was thinking it was limited to 2mb.

      So now it's all good. :)

      If i want to make my piratebox in french can i just modify the text in the list.xhtml ?

    3. Yes, just modify the xhtml files. These are html files mixed with BeanShell code.

  12. This comment has been removed by the author.

  13. droid razr - everything works except redirection

    1. If redirection of port 80 to 8080 is not working for you, the iptables command seems to be different on your device. You could try to find the right command and edit the 0/S_PirateBox.bsh script.

    2. spoke too soon: uploads work from desktop only and can be accessed on the SD card from the android device, but when downloading from either desktop or android, the browser is redirected to Checked startup scripts, couldn't see any errors. ran the scripts manually to no avail.

      Stock tethering, stock (rooted) rom, logcats available if needed. chat works wonderfully tho :)

    3. Hmm, strange ... this is working flawlessly on my Adam.

    4. I'll keep playing and post updates. Thanks for the advice on the iptables commands, i'll go over those after work and see if i can find something

  14. Eyh guyz, i try to install paw server and piratebox plugin. Everything is launching but when i connect to the wifi, no IP has been addressed to the device so i cant open the page of pbox..any idea?

  15. When i try to change manually the up limit in server.xml, my paw server is crashing every time i launched it .. why?

    1. Have a look at logcat. There should be an exception output in there.

  16. Can we hope that your PAW Server is working with wifi tether apps ? (like wifi tethering for root users)

    1. The plugin described in this post is build to support native tethering.
      The original post on the XDA forum worked with WiFi Tether, because I only had an Android 1.6 device by that time.
      So if you depend on WiFi Tether the original setup might work for you.
      If not, you can always try to modify the startup scripts to get it working.

    2. I dont like the original setup because ther eis a problem in redirecting the user to the global page :/ .

    3. is hard coded. This might not be optimal, but if the PirateBox is working as intended, that shouldn't really matter. All requests should be handled by the PirateBox itself.

  17. Hi, thanks for the good job ! :D
    One question : do you think it's possible to install the piratebox without SD card, just using internal memory ? And if so, where should I unzip the files ?


    1. The configuration has to stay inside the /sdcard/paw directory, but you can move the /sdcard/paw/html directory to a different location.
      For more info have a look at the following blog entry:

  18. hello, thans for the tutorial, is helpfull,
    It is normal I could navigate to folders? I'ts always redirecting to the /html folder.

    when I create folders on my external sdcard piratebox_plugin/html/upload/$name_of_the_folder/
    is always redirected to the home page piratebox. and is not possible to have an folder architecture on /upload folder. just files, I dont understand, it's non implemented on android piratbox? the posibilities are implemented [code addon] (and tested great) on my TL-WR703N but I need to have this function (basic) in android phone, do you have an idea?

    many thanks

  19. I am on HTC Evo 4G.
    Android 2.2
    Root via UnRevoked
    I get to the point where it tells me that the Pirate Box is started.
    The only SSID I see if the standard one for the Evo hotspot app.
    I am able to give password info for the hotspot, but once connected I am unable to access the box via the given address.

    I think this may be caused by one of two things, but I am really not sure. 1) my Evo is not connected to Sprint and thus while it tries to find an ip address from the network the network is not forthcoming with one so my other devices are never properly given their own up addresses to function on the system.

    2). This has something to do.with creating an AP. which I am not at all clear what that might consist of.

    any help.would be appreciated.

  20. Any updates on this? I've an old LG Vortex (pos, i know...) i'd like to use, if possible. It runs cm7.2 / 2.3.7, and native tether allows connection, but no PB...

  21. I've installed paw successfully (from the play store) on my routed Nexus 7 3G, extracted PirateBox into the into the plugins. However I can't get it installed when I click install in the interface on my browser. I restart the App through the menu and activate it again. Nothing happens. As it it described, tethering can not be integrated in the ROM or it won't work. I think it is this problem, as tethering is enabled in the Paranoid Android ROM. It would be very handy if the script was updated so that it would still work, especially since you could add a USB drive to your Nexus 7.

  22. Hi! Thank you for your great job!
    I try to install pirateBox but i have the same problem: I can't get plugin installed =(
    I try to click on "install plugin", a little green box appears, but the plugin is always marked on no installed...
    Also supersu never asked me for superuser rights with paw server...
    Someone could help me?
    Thank you very much and sorry for my bad english =/

  23. I love the idea of this but for the life of me I can't get it to work properly on my Galaxy Note 2

    I've got the tethering to work and can get to the management console of the server and can click to install the plugin. It will say that its installed and that I need to cycle the server to start it up however when I do this it says that the plugin isn't installed and so I have to start over ... I and my fellow CCNA students have attempted to trouble shoot this but we've come up empty. Any help would be of great assistance.


    1. I haven't looked into that for quite a while and I don't even have a rooted phone currently.
      It most likeliky depends on the ROM you are using if things are working or not.
      Most of the work is done inside 0/S_PirateBox.bsh.
      I would try to execute the "iptables" and "dnsmasq" from that script inside a shell and see if they are working.
      If that is working it should also be possible to do inside the script.

    2. I ran into a similar issue. My solution was to dig up the index.html file to the PirateBox plugin and take a look at what it actually executes when I hit the install button. The main thing it does is copies all of those init files over from the plugin directory to PAW's etc directory. If I had to guess I would say that on some devices PAW has a hard time moving those files around.

      To work around this, if you're familiar with adb and a general unix shell, simply...

      cp /sdcard/paw/html/app/plugins/piratebox/etc/init/0/* /sdcard/paw/etc/init/0/
      cp /sdcard/paw/html/app/plugins/piratebox/etc/init/1/* /sdcard/paw/etc/init/1/

      If that's a bit advance for you, and file manager app will allow you to copy those files over by hand.

      After I did that PirateBox booted up just fine with hotspot enabled. I wish there was a way PAW can just invoke the wifi hotspot on its own.

      Thanks for bundling this, you saved me a few days of my life putting a solar rig together for a RaspberryPi and a wifi access point, and writing a bunch of crappy PHP to do the same thing.

    3. Thanks for the info and the time for trying this out.
      I hope I've corrected the error inside the index.xhtml file and uploaded a new version.

  24. Anyway that this plugin could be modified to be used as a captive portal page? I'm trying to use the paw server as a way to share photos at family events, but without needing to provide an address. Ideally people would connect to the network and it would bring up the webpage. Any thoughts would be appreciated.

    1. It should not be too hard to build a captive portal. The HTML files are inside the html folder of the plugin ZIP file.
      The plugin seems not to be working on all configurations, so you'll have to test.

  25. Hey, I'd like a chance to translate this to Spanish if possible.

    1. Thanks for the offer to contribute. The latest version contains already a Spanish translation for the web interface.

    2. Sorry, Spanish is currently not included, but it will be in the next version (0.5.5 beta).

  26. I was wondering if there was a way to target a tethering app instead of the built in tethering.


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