Archives For March 2013

Recently I was looking for a way to SSH from a network that blocked my outgoing SSH connection. I’d be nice to have a way around firewalls and be able to access your private Linux terminal. To be able to debug a problem from an remote location, for example.

A collegue suggested a tool called ‘Shell In A Box‘. Shell In A Box implements a web server that can export arbitrary command line tools to a web based terminal emulator using just JavaScript and CSS without any additional browser plugins. This means: connecting your browser via HTTPS to your own hosted Shell In A Box web site, and access a Linux terminal from there.

How cool is that? In this blog I’ll show you how to set it up in a secure way.

Building and installing Shell In A Box
I want to setup Shell In A Box on my Raspberry Pi. It’s a great device running Linux that has a very small energy consumption footprint. Ideal for an always-on device I’d say!

Since there is no package available, we’ve to compile our own. It’s best to get the sources from Github (original here), since the Github repository contains some patches and fixes for issues on Firefox.

These commands install the required dependencies, clone the Git repository and start building:

apt-get install git dpkg-dev debhelper autotools-dev libssl-dev libpam0g-dev zlib1g-dev libssl1.0.0 libpam0g openssl
git clone
cd shellinabox_fork

During my first attempt, I ran into this problem:

dpkg-source -b shellinabox-2.14
dpkg-source: error: can't build with source format '3.0 (quilt)': no upstream tarball found at ../shellinabox_2.14.orig.tar.{bz2,gz,lzma,xz}
dpkg-buildpackage: error: dpkg-source -b shellinabox-2.14 gave error exit status 255

When grepping for ‘quilt’ I found a file called ‘/debian/source/format’. From what I can tell this does not do anything important, so I ended up deleting the file. Guess what, it now works.

rm ./debian/source/format

Build the package again, this should now succeed.


This process will take some time (especially on the Raspberry Pi). Afterwards you’ll find the .deb file ready to be installed.

dpkg -i ../shellinabox_2.14-1_armhf.deb

I changed the configuration, to disallow the build-in SSL and to bind to localhost only. I did this because another web server will serve our terminal. I will explain in a minute.

vim /etc/default/shellinabox

And edit this line:

SHELLINABOX_ARGS="--no-beep -s /terminal:LOGIN --disable-ssl --localhost-only"

Finally, restart the deamon:

/etc/init.d/shellinabox restart

And check if all went well:

/etc/init.d/shellinabox status

You should see:

Shell In A Box Daemon is running

Another way to verify is to check the open ports:

netstat -ntl

You should see:

Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address Foreign Address State 
tcp 0 0* LISTEN

Setting up Lighttpd as a proxy

Shell In A Box runs on port 4200 by default. Although this can be changed to a more common 80 or even 443, this is not what I want. I decided to integrate it with another webserver, to be able to combine other services and use just one url (and one SSL certificate). Since the Raspberry Pi isn’t that powerful, I choose Lighttpd.

apt-get instal lighttpd
cd /etc/lighttpd/conf-enabled
ln -s ../conf-available/10-proxy.conf

This installs Lighttpd and enables Proxy support. Now add the Proxy config:

vim /etc/lighttpd/lighttpd.conf

And add:

proxy.server = (
 "/terminal" =>
  ( (
    "host" => "",
    "port" => 4200
  ) )

Save and restart Lighttpd:

/etc/init.d/lighttpd restart

Connect to and your Shell In A Box terminal should appear.

Although this is cool already, we’re not quite there. No one will SSH on an unencrypted web page, right? So, we’ll configure an SSL certificate to enable encryption. For double safety, we’ll also set a username/password on the web page. One then needs to know this password to access the login promt, and needs a valid local username/password to really use the terminal.

Adding encryption with SSL
By using a HTTPS-url, our traffic is encrypted. Let’s generate a private key (and remove the passphrase):

openssl genrsa -des3 -out 2048
cp -pr
openssl rsa -in -out

If you do not remove the passphrase, you will need to type it every time you start the web server. To request a SSL-certificate, you need to supply a CSR (Certificate Signing Request) and send that to a SSL provider such as Thawte or Verisign.

openssl req -new -key -out

To be able to continue now, let’s self-sign the certificate:

openssl x509 -in -out -req -signkey -days 365
cat >>

A self-signed certificate will display a warning in our browser, but that’s ok for now. Once the real certificate comes back from our SSL provider, it’s easy to replace it. The warning will then disappear.

Time to tell Lighttpd about our certificate:

vim /etc/lighttpd/lighttpd.conf

Add these lines:

$SERVER["socket"] == "" {
  ssl.engine = "enable"
  ssl.pemfile = "/etc/lighttpd/ssl/" = ""
  server.document-root = "/home/lighttpd/"
  server.errorlog = "/var/log/lighttpd/pi.example.org_serror.log"
  accesslog.filename = "/var/log/lighttpd/pi.example.org_saccess.log"

And restart Lighttpd:

/etc/init.d/lighttpd restart

Now Shell In A Box should be available on:

Enhancing security by adding HTTP-auth
Since the /terminal page now makes an actual terminal available to web users, I added an extra password for security. You can use the ‘HTTP Auth’ method for this. It will pop up a message box that requires an valid username/password before the /terminal page is shown.

First enable the module:

cd /etc/lighttpd/conf-enabled
ln -s ../conf-available/05-auth.conf

Then extend the config of the virtual host config you created above. The final result should be:

$SERVER["socket"] == "" {
  ssl.engine = "enable"
  ssl.pemfile = "/etc/lighttpd/ssl/" = ""
  server.document-root = "/home/lighttpd/"
  server.errorlog = "/var/log/lighttpd/pi.example.org_serror.log"
  accesslog.filename = "/var/log/lighttpd/pi.example.org_saccess.log"

  auth.debug = 2
  auth.backend = "htpasswd"
  auth.backend.htpasswd.userfile = "/etc/lighttpd/shellinabox-htpasswd"

  auth.require = ( "/terminal/" =>
      "method" => "basic",
      "realm" => "Password protected area",
      "require" => "user=remibergsma"

Reload Lighttpd to make the changes active:

/etc/init.d/lighttpd reload

To set a password:

apt-get install apache2-utils
htpasswd -c -m /etc/lighttpd/shellinabox-htpasswd remibergsma

You can enter multiple users, just remember to remove the ‘-c’ flag when adding more users, as this overwrites the current file.

When you visit you will need to enter a valid username and password, before the page loads.

The final result: SSH in a browser window!
You should now be able to use a terminal via your own protected webpage. It’s mostly like a real terminal/SSH session but from a browser. Wow 🙂

Shell In A Box in action

Shell In A Box in action


I always use GNU Screen, so I know for sure my commands keep running whatever happens.

Using GNU Screen in a browser

Using GNU Screen in a browser


A lot of people seem interested in safe browsing over untrusted wifi and using a Raspberry Pi with an OpenVPN server to accomplish that. In this blog post, I’ll continue the series and explain how to set up secure browsing on mobile devices based on iOS.

When I’m not at home I use my iPhone or iPad and connect to the internet using either 3G or public wifi. I want to configure my mobile device to setup an encrypted VPN tunnel and route all traffic through it, so I have a safe browsing experience. Fortunately, there now is an OpenVPN app available on iOS that allows you to do that! Please install this app using the App Store, and continue reading to set it all up.

Preparing and importing the certificate
I’d suggest creating a separate certificate for each device you want to connect to your OpenVPN server. Although, it is possible to reuse the certificates on multiple devices, I’d recommend not to do so. First of all you will not be able to connect at the same time. Security-wise it is also smart to use one certificate for each device: whenever you lose your device, you can easily revoke the certificate and still connect from your other devices.

cd /etc/openvpn/easy-rsa/2.0/
. ./vars
./build-key remiiphone

You will now have a private key and certificate generated for your mobile device (check the ./keys directory). To be able to work with it on a mobiel device, we convert it to pkcs12 format using this command:

openssl pkcs12 -export -in keys/remiiphone.crt -inkey keys/remiiphone.key -certfile keys/ca.crt -name remiiphone -out remiiphone.p12

The password it asks is to protect the file. Remember the password, we will need it when installing on the mobile device. The file ‘remiiphone.p12’ should be created.

Next step is to bring this file to our mobile device. I did first scp it from the Pi to my iMac, then send myself an e-mail with the .p12 file attached. Since the file is password protected, it is safe to e-mail.

When you open the e-mail on your mobile device, and click the .p12 attachment you will be asked to install the certificate. Click install and confirm installation. If your device has a passcode, you will be asked to enter it. Afterwards, you need to type the password you choose when generating the p12 file. Finally, because I use a self-signed certificate, from an untrusted CA, iOS mentions the certificate is ‘Not Trusted’. Don’t worry, it’s fine.

The screenshots below show you how it looks like:

Installing the p12 certificate

Installing the p12 certificate

Unsigned profile warning

Unsigned profile warning

Enter device code

Enter device code

Enter password

Enter password

Installed certificate

Installed certificate

Your certificate is now installed on iOS and it is ready to be used by the OpenVPN app.

Preparing and importing the OpenVPN configuration file
Next step is to provide the OpenVPN app with a configuration file. When you use the .ovpn extension, you can easily import it later on. But let’s start with setting up the configuration file.

dev tun
proto udp
remote 1194
# other options (mostly defaults)
user nobody
group nogroup
resolv-retry infinite

Let me explain: This tells the OpenVPN app we’ll be using client mode and use the ‘tun’ device (the only supported in iOS). The server is using udp (choose udp or tcp) and can be found on using port 1194. Please adjust accordingly. Line 5 tells it to use compression, and line 6 sends all traffic through the tunnel. This is exactly what we want: this allows secure browsing.

The thing that took me some time to figure out is that you need to specify the CA certificate in the OpenVPN app. Even though it was included in the .p12 file we imported, iOS would strip it and therefore not import it. That’s why you should include it in your .ovpn file. Replace lines 8-12 with your CA certificate. It needs more lines, for sure. Just paste everything between the CA tags in the file and you’ll be fine. If you’ll get this error message, your CA is probably not right:

CORE_ERROR PolarSSL: error parsing ca certificate : X509 - The certificate format is invalid, e.g. different type expected [ERR]

Finally, I have some more settings in the file that are mostly defaults. Note: it is also possible to add your private key and certificate directly to the .ovpn file, in the same way as the CA is done above. I’d recommend not to do that because your .ovpn file is then all somebody needs to be able to connect. Since there is no password protection, e-mailing the file is insecure and dangerous!

Save the file, call it pi.ovpn or so, and e-mail this file to yourself as well. The e-mail app on iOS will allow you to import this configuration to the OpenVPN app by clicking on the file. The OpenVPN app will show your imported configuration. Confirm by tapping the  green + icon. Next step, select the certificate to use with this profile. Here you will select the certificate we imported into iOS in the previous step. As a result, we can omit the username and password fields, as we use our certificate instead.

Welcome screen

Welcome screen

Import .ovpn file

Import .ovpn file

Confirm import

Confirm import

Select certificate

Select certificate

Configuration imported

Configuration imported

Your OpenVPN client configuration is now imported and ready for use. Let’s test it!  All you have to do to connect, is to tap on the OFF button just below the status ‘Disconnected’. You should now be connected to your OpenVPN server. Note the VPN icon on top of the screen while you’re connected.

The best way to verify everything is working properly, is to open your mobile Safari and visit a website that displays your ip address (such as It should show your OpenVPN server’s public ip address, instead of your mobile or wifi ip address. Try disconnecting and compare the ip addresses. Cool hah?!