Evade georestrictions with the Raspberry Pi

In this article I will talk about the use of a professional VPN service called Hide My Ass (I have no affiliation with them).  This allows you to send and receive data online while appearing (to everyone else on the Internet) as though you are in a different country.  They have VPN servers all over the world so essentially this allows you to easily select the country from which you want to access georestricted content.  Their service is not free however there are several benefits.  The main one being that it will anonymously encrypt your Internet activity and prevent anyone from violating your privacy online.  Their service can be used on most computers and smart phones besides the Raspberry Pi but you can read their FAQ for more information.  There are also some reviews on YouTube.

Okay don’t panic! I know this article looks huge.  It’s only this long because it explains the solution in three different ways, only one of which you will likley want to use.  There is also a lot of detail so you don’t go wrong!

So what are georestrictions then? Simply put; it’s when the content of an Internet service is restricted based on your current location in the world.  An example is your local catch-up TV service.  If you go on holiday to another country for the weekend, you will no longer be able to log in and watch the latest episode of your favorite show.  This is because their site is georestricted to your country only.  Similarly TV streaming services show a different range of available programmes to USA subscribers as opposed to European ones.

The above image is a general overview of what we need to do.  Normally you would connect your device directly to your router but in this case we need to put a Raspberry Pi between your device and the router so that it can perform the magic that avoids the georestrictions.

Note: Please understand that by doing this to watch an Internet TV service you may be breaching your terms of service agreement with them. Please check before you continue.

Notice the red and green arrows in the above diagram.  Following the green arrows the network data will flow from your device to the Pi, the Pi will do the magic, then from the Pi to the Router, then from the Router out into the Internet and back along the red arrows.

Each pair of green and red arrows represent an actual connection between devices be it wired or wireless.  You can ignore the ones between the router and the Internet, the only ones that matter to us are the ones on either side of the Raspberry Pi.  How you want to do this is entirely up to you but it is quite common for one side to be wired, since the model B Pi comes with an Ethernet port, and the other to be wireless.

So to summarise your Pi needs to accommodate two network connections.  One that goes from the device to the Pi and one that goes from the Pi to the router.  The easiest way for you to satisfy this requirement is to get hold of a wireless dongle or an Ethernet dongle.

or

What you chose should be determined by the existing devices you’re using.  Your smart TV may only have an Ethernet port, or your Nintendo Wii can only support wireless.  I can recommend the Edimax wireless dongle above as this is known to work well with the Raspberry Pi.  Also if you’re intending to use multiple USB devices please have a read about potential power issues.  A powered USB hub is often a quick and easy solution to these.

Before we get going I just want to mention a Windows program that you should familiarise yourself with. Putty.exe (above) is an SSH terminal client program that will basically allow you to have the Raspberry Pi command prompt (the Shell) inside a desktop window.  You can copy and paste Linux commands directly into Putty from a web site such as this without having to manually type them out.  There is more info about this in one of my previous blog posts.  A paste in Putty is done by a right click of the mouse.

If you’re using Linux or OSX the equivalent of this is just to open a Terminal window and enter the following command.  Replace <IP> with the IP address of the Raspberry Pi.

ssh <IP> -l pi

So here are some example configurations of the proposed system.  Maybe one of these will satisfy your needs?

Example 1: The Wireless Bridge

  • Device is connected to the Raspberry Pi over Ethernet.
  • Raspberry Pi is connected to the router over wireless.
  • 1 x USB Wireless dongle needed.
  • 1 x Ethernet cable needed.
  • do

Example 2: The Wireless Hotspot (takes longer to set up)

  • Raspberry Pi is hosting a wireless hotspot.
  • Device is connected to the Raspberry Pi hotspot over wireless.
  • Raspberry Pi is connected to the router over Ethernet.
  • 1 x USB Wireless dongle needed.
  • 1 x Ethernet cable needed.
  • do

Example 3: The Ethernet Router

  • Device is connected to the Raspberry Pi over Ethernet.
  • Raspberry Pi is connected to the router over Ethernet.
  • 1 x USB Ethernet dongle needed.
  • 2 x Ethernet cables needed.
  • do


Example 1: The Wireless Bridge

  • 1 x USB Wireless dongle needed.
  • 1 x Ethernet cable needed.

This diagram is only schematic

 

Start with a blank SD card.  Download and install the latest image of Raspbian either using a raw image or with the NOOBS software.  Boot up the Pi and don’t forget to expand the file system to fill the SD card.  Insert the USB wireless dongle now if you have not done so already.

After rebooting log in and enter the following command.

lsusb

Ensure that the dongle is displayed in the list.  If it is not shown, do not continue you must solve this first.  It may be a power issue which you’ll need a powered USB hub to solve.

The next task is to establish a wireless connection to your router. One of the quickest ways to do this is to use the software on the Pi desktop. Enter startx at the command prompt to go into X windows. One of the icons on the desktop will be named WiFi Config (see above).  Here is a quick guide on how to use it.  Make a note of the wireless IP address you get!

Ensure that the wireless connection is successful and that the connection is stable before you continue.  Leave the Ethernet port disconnected for now and reboot the Pi to double check that you get an IP address via the wireless adapter during bootup.

sudo reboot

Upon boot up you can log in and check the IP address by entering the command ifconfig, look for the line starting with inet addr under wlan0.  If that line is missing then you have troubleshooting to do before you continue.  Use the wlan0 IP address for all SSH sessions from Putty or a Terminal window from here on.

Ensure the Ethernet port is disconnected and SSH into the Raspberry Pi using the wireless IP address.  There is a small background service that runs on Raspbian which is designed to make the Pi network connection defer to the Ethernet port even when a wireless network is available.  This is typical laptop behaviour but we don’t want this here because it will interfere with our set up.  Enter the following commands;

sudo apt-get remove ifplugd
sudo apt-get autoremove

We’re going to make the Pi Ethernet port behave in a similar way to your router.  This means assigning a static IP address to it and installing a DHCP service that will respond to requests from your device.  It’s a good idea to use an IP range that is very different to your router, so let’s use 10.0.0.X.  To configure this we must edit the network interfaces file, enter the following command;

sudo nano /etc/network/interfaces

Modify the content of the file so that it is the same as below.  In this file eth0 is the Ethernet port and wlan0 is the wireless dongle.

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
address 10.0.0.1
netmask 255.255.255.0

auto wlan0
iface wlan0 inet manual
wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

Press Ctrl – X, y and enter to save and quit out of nano.  Now to install and configure the DHCP service called dnsmasq.  Enter the following commands;

sudo apt-get update
sudo apt-get install dnsmasq

I am going to explicitly specify a configuration file for the dnsmasq service so let’s first make a backup of the default config file and then save my one in its place.

cd /etc
sudo mv dnsmasq.conf dnsmasq.default
sudo nano dnsmasq.conf

You should now be editing a blank file.  Copy and paste the following into it.

interface=eth0
dhcp-range=10.0.0.2,10.0.0.250,255.255.255.0,12h
dhcp-option=3,10.0.0.1
dhcp-option=6,8.8.8.8,8.8.4.4

The first line tells dnsmasq to listen for DHCP requests on the Ethernet port.  The second line is specifying the range of IP addresses that can be given out with a 12 hour lease.  The third and fourth lines provides the default gateway and DNS server settings to the client devices.  You may recognise the Google public DNS servers here.  You could also use Open DNS here too.  But you’ll have to manually substitute their IP addresses for the Google ones I have specified.

Press Ctrl – X, y and enter to save and quit out of nano.  We’re also going to use these DNS servers on the Pi itself.  The ones provided by your router settings for the wireless connection will not be usable once we start using a VPN later on.  Enter the following command;

sudo nano /etc/dhcp/dhclient.conf

Scroll down and find a line saying;

#prepend domain-name-servers 127.0.0.1;

Add this line in immediately after it;

prepend domain-name-servers 8.8.8.8, 8.8.4.4;

Press Ctrl – X, y and enter to save and quit out of nano.  Next we need to enable IP v4 forwarding.  Essentially we are going to be forwarding IP traffic from the Ethernet port to the wireless dongle and back again, similar to how your router does it.  Enter the following command;

sudo nano /etc/sysctl.conf

Find the line that says this (below) and remove the hash at the start of the line.

#net.ipv4.ip_forward=1

Press Ctrl – X, y and enter to save and quit out of nano.  Now enter the following command;

sudo sysctl -p

The software that controls this IP forwarding is called iptables, we now just need to install it however you may find your Raspbian install already has the latest version.

sudo apt-get install iptables

Okay now for the magic part!  We’re going to create a few scripts that will instruct the Pi to forward the network traffic.  There are going to be two modes.  A normal router mode which will make the Raspberry Pi just pass all traffic straight through without doing anything.  Ideal if you’re just wanting to use your device in the normal way that you always have been.  Here we go from the eth0 interface to the wlan0 interface when you look at what ifconfig shows.

The second mode is called tunnel mode which uses a VPN connection.  In tunnel mode we make a VPN connection to a HMA server in another country which gives us an interface called tun0.  We then forward from the eth0 interface to the tun0 interface.

Think about this like a virtual underground tunnel that starts at your home then goes underground all the way to the desired country.  When your network traffic goes through the tunnel it comes out on the other side and it looks to everyone else like it came from there.  No one else can see inside the tunnel.

Enter the following commands;

cd ~
mkdir scripts
cd scripts
sudo nano router.sh

Copy and paste in the following code.

echo "Router mode"
iptables -F
iptables -X

iptables -A INPUT -i lo -j ACCEPT
iptables -A OUTPUT -o lo -j ACCEPT
iptables -A INPUT -i eth0 -j ACCEPT
iptables -A OUTPUT -o eth0 -j ACCEPT

iptables -A POSTROUTING -t nat -o wlan0 -j MASQUERADE
iptables -A FORWARD -i eth0 -j ACCEPT

Press Ctrl – X, y and enter to save and quit out of nano.  We’re going to use a command to make the script executable (so it will run) and then we’re going to make a copy which we will tweak slightly to give us the script for the tunnel mode.  Enter the following commands;

sudo chmod +x router.sh
cp router.sh tunnel.sh
sudo nano tunnel.sh

Change the message at the start to say “Tunnel mode” and modify the second to last line to replace wlan0 with tun0.  Like so;

iptables -A POSTROUTING -t nat -o tun0 -j MASQUERADE

Press Ctrl – X, y and enter to save and quit out of nano.  Okay we’re almost there.
Connect your device to the Pi directly via the Ethernet cable and reboot.

sudo reboot

First lets test that normal router mode is working.  Log in either via SSH using the wireless IP address or on the console of the Pi itself.  Enter the following command to turn on router mode;

sudo ~/scripts/router.sh

Your Pi is now doing something called Network Address Translation or NAT for short.  Now use your device be it a games console or smart TV to access the Internet in the usual way.  You may have to go into its connection settings and specify to use a wired internet connection, you don’t want it to be using a wireless connection directly to the router as this will bypass the Raspberry Pi.  Verify that you can still do the things you would normally do on your device.  Check that the expected activity lights on the Pi and your wireless dongle are blinking when you do this.

If this is unsuccessful then do not continue.  Go back through the previous instructions and double check that everything has been done correctly.

The last part is common to all three examples so click below to skip to the end.

Finishing off


Example 2: The Wireless Hotspot

  • 1 x USB Wireless dongle needed.
  • 1 x Ethernet cable needed.

This diagram is only schematic

 

Okay so this will take a bit longer to set up but it should work just as well as the other methods.  We’re going to set up a wireless hot spot or access point on the Raspberry Pi.  This will allow you to connect your device over wireless as well as other devices like smart phones and tablets.  All of which will be able to share the georestriction evasion that is being provided by the VPN.

Start with a blank SD card. Download and install the latest image of Raspbian either using a raw image or with the NOOBS software. Boot up the Pi and don’t forget to expand the file system to fill the SD card.

Ensure you have an Ethernet cable connecting your Raspberry Pi to your router and use the eth0 IP address (shown by the ifconfig command) for all SSH sessions from Putty or a Terminal window from here on.  Insert the USB wireless dongle now if you have not done so already.

After rebooting log in and enter the following command.

lsusb

Ensure that the dongle is displayed in the list. If it is not shown, do not continue you must solve this first.  It may be a power issue which you’ll need a powered USB hub to solve.

The software used to provide the wireless hotspot is called hostapd.  We need to install this package first.  Enter the following commands;

sudo apt-get update
sudo apt-get install hostapd

Allow this to finish.

Note: If the lsusb command shows that your wireless dongle is a Realtek RTL8188CUS device then there are some extra steps that you need to go through.  The Edimax dongle that I recommended above is one of these!

Realtek RTL8188CUS devices only
skip this

We need to compile hostapd from source code to make it work with this type of wireless dongle.  Below are the instructions for doing this.

First let’s make a dev folder in our home directory where we’ll do this work.  Enter these commands;

cd ~
mkdir dev
cd dev

Next we need to download a package directly from Realtek which contains the source code we want to compile.  There are various ways you can achieve this.  You can download the file on the Raspberry Pi itself using Midori (type startx to go into the X desktop), or you could download it on another machine and copy it over using a USB pen drive.

Point your browser here (or copy/paste the below into the address bar);

http://www.realtek.com.tw/downloads/downloadsView.aspx?Langid=1&PNid=21&PFid=48&Level=5&Conn=4&DownTypeID=3&GetDown=false

Under Step 1 tick RTL8188CUS and under Step 2 click go.  Locate and click on “Unix (Linux)” and choose one of the download sites on the right hand side of the table.  Give it a moment to connect and then download the file.

You will now have a .zip file with a long file name, put this into the dev folder that we created above.  This will be inside your home, pi, directory if you’re using the File Manager program under the X desktop (Start > Accessories > File Manager).

Log out of the X desktop and return to the command prompt.  To check the above has been done correctly, enter the following commands;

cd ~/dev
ls -l

If the zip file with the long name is not shown then do not continue, you have not copied the file correctly.  Solve this before you continue.

Next, to get to the source code we want, we must first unzip the file and within it there is a second zip file that we must also unzip.  Please note that the exact file names specified here may become changed by Realtek without any notice in the future.  So it’s a good idea to always check the names of files and folders using the ls (list) command.

Enter the following commands;

cd ~/dev
unzip RTL8192xC_USB_linux_v3.4.4_4749.20121105.zip
cd RTL8188C_8192C_USB_linux_v3.4.4_4749.20121105
cd wpa_supplicant_hostapd
unzip wpa_supplicant_hostapd-0.8_rtw_20120803.zip
cd wpa_supplicant_hostapd-0.8
cd hostapd
ls -l

If everything has been successful your command prompt should now look something like this (below) and one of the files shown in the list above should be called Makefile.

pi@raspberrypi ~/dev/RTL8188C_8192C_USB_linux_v3.4.4_4749.20121105/wpa_supplicant_hostapd/wpa_supplicant_hostapd-0.8/hostapd $

If this is not the case then do not continue, you need to solve this first.  Check that the file names above are correct by using the ls command before each one.  If the file names shown by ls are different then just modify them to match what ls shows.  The things most likely to change are the numbers at the end of the filenames since these represent dates and versions of the code.

Just to forewarn you; the compile process takes a while to complete.  So when you start it you can go away and make a cup of tea or watch an episode of your favorite show.  If you’re connected over SSH using Putty or a terminal window it’s a good idea to do the compilation inside a screen session.  This will allow you to initiate the compile and then disconnect from the Pi while leaving it running.  If you’re using the Pi console (as in keyboard, mouse and monitor directly) then you can skip straight to make below.

You can install the screen program by using the following command;

sudo apt-get install screen

Once that has finished enter the following command to begin a new screen session;

screen bash

You can now begin the compile process.  Enter the following command;

make

If you used a screen session then you can hold down Ctrl – A and then also press D to disconnect it.  You can now safely log out of the Pi leaving the compile running.  Do not reboot or power off the Pi during this process.

Tick tock, tick tock.

I will assume the compile process has finished now.  If you used a screen session you should log back into the Pi and then you can use the following command to re-connect to it;

screen -r

If you type ls now you should notice that two new files are shown in a green colour.  These are;

hostapd
hostapd_cli

We now need to manually copy these files into a couple of other places on the system.  Enter the following commands;

sudo service hostapd stop
sudo cp ./hostapd /usr/local/bin
sudo cp ./hostapd /usr/sbin
sudo cp ./hostapd_cli /usr/local/bin
sudo cp ./hostapd_cli /usr/sbin

The last thing to do here is to copy a template configuration file which we will user later.  There is one supplied in the Realtek zip file that we downloaded earlier.  To find it go two folders back from where you are now.  Enter the following commands;

cd ..
cd ..
ls -l

Your command prompt should now look like this (below);

pi@raspberrypi ~/dev/RTL8188C_8192C_USB_linux_v3.4.4_4749.20121105/wpa_supplicant_hostapd $

You should see that one of the files in the list above is rtl_hostapd_2G.conf.  This is the file we want to use as a template.  Enter the following command to copy it;

sudo cp ./rtl_hostapd_2G.conf /etc/hostapd/hostapd.conf

That’s it, hostapd is compiled and installed.  We can now resume the setup process for the rest of the system.

If you are still inside a screen session you can enter exit to close it down.

Main configuration

The first thing we need to do is tell hostapd where it’s configuration file is.  Enter the following command;

sudo nano /etc/default/hostapd

Locate the following line;

#DAEMON_CONF=""

Remove the hash at the start of the line and enter the path to where we shall save the config file (as per below);

DAEMON_CONF="/etc/hostapd/hostapd.conf"

Press Ctrl – X, y and enter to save and quit out of nano.  We can now go ahead and configure the settings in the hostapd config file.  Each line of the file is a different setting and the format is settingName=value.  Pay close attention to these settings since here is where you can specify things like the SSID of the access point and the password to join it.

Enter the following command;

sudo nano /etc/hostapd/hostapd.conf

If you had to recompile hostapd from source then this file will already contain some settings, you will need to manually merge the settings below with the settings in your current file. This means you should insert settings that are missing and update ones that already exist.  Otherwise you can just copy and paste them right in.

Note: The order in which these appear in the file does not matter.

First we need to specify the interface to listen on, this will be wlan0 as shown by the ifconfig command.

interface=wlan0

Then the driver name.  Do not modify this setting if you recompiled hostapd.

driver=nl80211

These next two lines are to configure the hostapd daemon process, this is a background process that stays in memory all the time.

ctrl_interface=/var/run/hostapd
ctrl_interface_group=0

Next the important settings!  The wireless network name (ssid), the wireless channel and it’s pass phrase to join.  Valid wireless channels range from 1-11, or 1-14 depending on your location in the world.  Modify these how you see fit.

ssid=RaspberryPiWiFi
channel=8
wpa_passphrase=MyWiFiPassword

Your choice of wireless channel is quite important if you live in an area with high wireless traffic.  You may wish to download and use some wireless diagnostics tools to see what other wireless channels are being used in your local area.   I can recommend one called inSSIDer.  Ideally you should try and pick the most empty or unused channel you can find.

Next is the wireless mode, valid options are a, b or g.  I reccomend to use g for the 2.4 GHz band.

hw_mode=g

Next I would advise to use WPA-2 with WPA-PSK as the wireless encryption system.

wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=CCMP #TKIP is another possible choice here
rsn_pairwise=CCMP

These last settings control how often the wireless hostspot sends out a beacon.

beacon_int=100
auth_algs=3
wmm_enabled=1

Press Ctrl – X, y and enter to save and quit out of nano.  If you reboot the Pi now you should see that your phone or tablet will detect the new wireless network after the Pi comes back up.  However you will not yet be able to join it.  We need to do some more work before you can do that.

It will be a good idea to monitor the boot up output of the Raspberry Pi for any errors showing in red.

sudo reboot

If everything has worked you should have seen no errors in the boot up sequence and your phone or tablet can now see the new wireless network (but not join it).  If this is not the case then stop, something is wrong and you need to troubleshoot before you continue.

We’re going to make the hotspot behave in a similar way to your router.  This means assigning a static IP address to it and installing a DHCP service that will respond to requests from your device.  It’s a good idea to use an IP range that is very different to your router, so let’s use 10.0.0.X.  To configure this we must edit the network interfaces file, enter the following command;

sudo nano /etc/network/interfaces

Modify the content of the file so that it is the same as below.  In this file eth0 is the Ethernet port and wlan0 is the wireless dongle.

auto lo

iface lo inet loopback
iface eth0 inet dhcp

auto wlan0
iface wlan0 inet static
address 10.0.0.1
netmask 255.255.255.0

allow-hotplug wlan0
#iface wlan0 inet manual
#wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

Please ensure that you put a hash # at the start of the two lines shown above in red!

Press Ctrl – X, y and enter to save and quit out of nano.  Now to install and configure the DHCP service called dnsmasq.  Enter the following commands;

sudo apt-get install dnsmasq

I am going to explicitly specify a configuration file for the dnsmasq service so let’s first make a backup of the default config file and then save my one in its place.

cd /etc
sudo mv dnsmasq.conf dnsmasq.default
sudo nano dnsmasq.conf

You should now be editing a blank file.  Copy and paste the following into it.

interface=wlan0
dhcp-range=10.0.0.2,10.0.0.250,255.255.255.0,12h
dhcp-option=3,10.0.0.1
dhcp-option=6,8.8.8.8,8.8.4.4

The first line tells dnsmasq to listen for DHCP requests on the wireless dongle.  The second line is specifying the range of IP addresses that can be given out with a 12 hour lease.  The third and fourth lines provides the default gateway and DNS server settings to the client devices.  You may recognise the Google public DNS servers here.  You could also use Open DNS here too.  But you’ll have to manually substitute their IP addresses for the Google ones I have specified.

Press Ctrl – X, y and enter to save and quit out of nano.  We’re also going to use these DNS servers on the Pi itself.  The ones provided by your router settings for the Ethernet connection will not be usable once we start using a VPN later on.  Enter the following command;

sudo nano /etc/dhcp/dhclient.conf

Scroll down and find a line saying;

#prepend domain-name-servers 127.0.0.1;

Add this line in immediately after it;

prepend domain-name-servers 8.8.8.8, 8.8.4.4;

Press Ctrl – X, y and enter to save and quit out of nano.  Next we need to enable IP v4 forwarding.  Essentially we are going to be forwarding IP traffic from the Wireless dongle to the Ethernet port and back again, similar to how your router does it.  Enter the following command;

sudo nano /etc/sysctl.conf

Find the line that says this (below) and remove the hash at the start of the line.

#net.ipv4.ip_forward=1

Press Ctrl – X, y and enter to save and quit out of nano.  Now enter the following command;

sudo sysctl -p

The software that controls this IP forwarding is called iptables, we now just need to install it however you may find your Raspbian install already has the latest version.

sudo apt-get install iptables

Okay now for the magic part!  We’re going to create a few scripts that will instruct the Pi to forward the network traffic.  There are going to be two modes.  A normal router mode which will make the Raspberry Pi just pass all traffic straight through without doing anything.  Ideal if you’re just wanting to use your devices in the normal way that you always have been.  Here we go from the wlan0 interface to the eth0 interface when you look at what ifconfig shows.

The second mode is called tunnel mode which uses a VPN connection.  In tunnel mode we make a VPN connection to a HMA server in another country which gives us an interface called tun0.  We then forward from the wlan0 interface to the tun0 interface.

Think about this like a virtual underground tunnel that starts at your home then goes underground all the way to the desired country.  When your network traffic goes through the tunnel it comes out on the other side and it looks to everyone else like it came from there.  No one else can see inside the tunnel.

Enter the following commands;

cd ~
mkdir scripts
cd scripts
sudo nano router.sh

Copy and paste in the following code.

echo "Router mode"
iptables -F
iptables -X

iptables -A INPUT -i lo -j ACCEPT
iptables -A OUTPUT -o lo -j ACCEPT
iptables -A INPUT -i wlan0 -j ACCEPT
iptables -A OUTPUT -o wlan0 -j ACCEPT

iptables -A POSTROUTING -t nat -o eth0 -j MASQUERADE
iptables -A FORWARD -i wlan0 -j ACCEPT

Press Ctrl – X, y and enter to save and quit out of nano.  We’re going to use a command to make the script executable (so it will run) and then we’re going to make a copy which we will tweak slightly to give us the script for the tunnel mode.  Enter the following commands;

sudo chmod +x router.sh
cp router.sh tunnel.sh
sudo nano tunnel.sh

Change the message at the start to say “Tunnel mode” and modify the second to last line to replace eth0 with tun0.  Like so;

iptables -A POSTROUTING -t nat -o tun0 -j MASQUERADE

Press Ctrl – X, y and enter to save and quit out of nano.  Okay we’re almost there.  After the next reboot we’ll be able to properly test out the wireless hotspot.

sudo reboot

First lets test that normal router mode is working.  Log in either via SSH using the Ethernet IP address or on the console of the Pi itself.  Enter the following command to turn on router mode;

sudo ~/scripts/router.sh

Your Pi is now doing something called Network Address Translation or NAT for short.  Now use your device or phone to connect to the wireless hostpot and check that you can access the Internet in the usual way.  Remember the wireless network name and password that you specified in the hostapd configuration file earlier!  Verify that you can still do the things you would normally do on your device.  Check that the expected activity lights on the Pi and your wireless dongle are blinking when you do this.

Note: If you test with an iPhone give this some patience as I found these are a bit slow on joining the hotspot.

If this is unsuccessful then do not continue.  Go back through the previous instructions and double check that everything has been done correctly.

The last part is common to all three examples so click below to skip to the end.

Finishing off


Example 3: The Ethernet Router

  • 1 x USB Ethernet dongle needed.
  • 2 x Ethernet cables needed.

This diagram is only schematic

 

Note: I tested this with an Apple USB Ethernet dongle (MC704ZM/A) from eBay, circa 2010.  However I found that the dongle was of poor quality and only lasted for about three weeks.  It may have been due to the age of the device though (two years out of warranty).  Please post below if anyone has a similar experience with one of these Apple dongles.

Start with a blank SD card.  Download and install the latest image of Raspbian either using a raw image or with the NOOBS software.  Boot up the Pi and don’t forget to expand the file system to fill the SD card.  Insert the USB Ethernet dongle now if you have not done so already.

After rebooting log in and enter the following command.

lsusb

Ensure that the dongle is displayed in the list.  If it is not shown, do not continue you must solve this first.  It may be a power issue which you’ll need a powered USB hub to solve.

Note: For the sake of following this article correctly and keeping things simple my instructions will assume that you use the built in Ethernet port to connect from the Pi to the router and the USB Ethernet dongle to connect from the Pi to your device.  You could swap them around but you’ll have to invert eth0 and eth1 in all the instructions that follow.

Ensure you have an Ethernet cable connecting your Raspberry Pi to your router and use the eth0 IP address (shown by the ifconfig command) for all SSH sessions from Putty or a Terminal window from here on.  Don’t plug an Ethernet cable into the USB Ethernet dongle for now.

We’re going to make the USB Ethernet dongle behave in a similar way to your router.  This means assigning a static IP address to it and installing a DHCP service that will respond to requests from your device.  It’s a good idea to use an IP range that is very different to your router, so let’s use 10.0.0.X.  To configure this we must edit the network interfaces file, enter the following command;

sudo nano /etc/network/interfaces

Modify the content of the file so that it is the same as below.  In this file eth0 is the built in Ethernet port and eth1 is the USB Ethernet dongle.

auto lo

iface lo inet loopback
iface eth0 inet dhcp

auto eth1
iface eth1 inet static
address 10.0.0.1
netmask 255.255.255.0

#allow-hotplug wlan0
#iface wlan0 inet manual
#wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

Press Ctrl – X, y and enter to save and quit out of nano.  Now to install and configure the DHCP service called dnsmasq.  Enter the following commands;

sudo apt-get update
sudo apt-get install dnsmasq

I am going to explicitly specify a configuration file for the dnsmasq service so let’s first make a backup of the default config file and then save my one in its place.

cd /etc
sudo mv dnsmasq.conf dnsmasq.default
sudo nano dnsmasq.conf

You should now be editing a blank file.  Copy and paste the following into it.

interface=eth1
dhcp-range=10.0.0.2,10.0.0.250,255.255.255.0,12h
dhcp-option=3,10.0.0.1
dhcp-option=6,8.8.8.8,8.8.4.4

The first line tells dnsmasq to listen for DHCP requests on the USB Ethernet dongle.  The second line is specifying the range of IP addresses that can be given out with a 12 hour lease.  The third and fourth lines provides the default gateway and DNS server settings to the client devices.  You may recognise the Google public DNS servers here.  You could also use Open DNS here too.  But you’ll have to manually substitute their IP addresses for the Google ones I have specified.

Press Ctrl – X, y and enter to save and quit out of nano.  We’re also going to use these DNS servers on the Pi itself.  The ones provided by your router settings for the built in ethernet connection will not be usable once we start using a VPN later on.  Enter the following command;

sudo nano /etc/dhcp/dhclient.conf

Scroll down and find a line saying;

#prepend domain-name-servers 127.0.0.1;

Add this line in immediately after it;

prepend domain-name-servers 8.8.8.8, 8.8.4.4;

Press Ctrl – X, y and enter to save and quit out of nano.  Next we need to enable IP v4 forwarding.  Essentially we are going to be forwarding IP traffic from the USB Ethernet port to the built in one and back again, similar to how your router does it.  Enter the following command;

sudo nano /etc/sysctl.conf

Find the line that says this (below) and remove the hash at the start of the line.

#net.ipv4.ip_forward=1

Press Ctrl – X, y and enter to save and quit out of nano.  Now enter the following command;

sudo sysctl -p

The software that controls this IP forwarding is called iptables, we now just need to install it however you may find your Raspbian install already has the latest version.

sudo apt-get install iptables

Okay now for the magic part!  We’re going to create a few scripts that will instruct the Pi to forward the network traffic.  There are going to be two modes.  A normal router mode which will make the Raspberry Pi just pass all traffic straight through without doing anything.  Ideal if you’re just wanting to use your device in the normal way that you always have been.  Here we go from the eth1 interface to the eth0 interface when you look at what ifconfig shows.

The second mode is called tunnel mode which uses a VPN connection.  In tunnel mode we make a VPN connection to a HMA server in another country which gives us an interface called tun0.  We then forward from the eth1 interface to the tun0 interface.

Think about this like a virtual underground tunnel that starts at your home then goes underground all the way to the desired country.  When your network traffic goes through the tunnel it comes out on the other side and it looks to everyone else like it came from there.  No one else can see inside the tunnel.

Enter the following commands;

cd ~
mkdir scripts
cd scripts
sudo nano router.sh

Copy and paste in the following code.

echo "Router mode"
iptables -F
iptables -X

iptables -A INPUT -i lo -j ACCEPT
iptables -A OUTPUT -o lo -j ACCEPT
iptables -A INPUT -i eth1 -j ACCEPT
iptables -A OUTPUT -o eth1 -j ACCEPT

iptables -A POSTROUTING -t nat -o eth0 -j MASQUERADE
iptables -A FORWARD -i eth1 -j ACCEPT

Press Ctrl – X, y and enter to save and quit out of nano.  We’re going to use a command to make the script executable (so it will run) and then we’re going to make a copy which we will tweak slightly to give us the script for the tunnel mode.  Enter the following commands;

sudo chmod +x router.sh
cp router.sh tunnel.sh
sudo nano tunnel.sh

Change the message at the start to say “Tunnel mode” and modify the second to last line to replace eth0 with tun0.  Like so;

iptables -A POSTROUTING -t nat -o tun0 -j MASQUERADE

Press Ctrl – X, y and enter to save and quit out of nano.  Okay we’re almost there.
Connect your device to the USB Ethernet donge directly via an Ethernet cable and reboot.

sudo reboot

First lets test that normal router mode is working.  Log in either via SSH using the build in Ethernet port IP address or on the console of the Pi itself.  Enter the following command to turn on router mode;

sudo ~/scripts/router.sh

Your Pi is now doing something called Network Address Translation or NAT for short.  Now use your device be it a games console or smart TV to access the Internet in the usual way.  You may have to go into its connection settings and specify to use a wired internet connection, you don’t want it to be using a wireless connection directly to the router as this will bypass the Raspberry Pi.  Verify that you can still do the things you would normally do on your device.  Check that the expected activity lights on the Pi and your USB Ethernet dongle are blinking when you do this.

If this is unsuccessful then do not continue.  Go back through the previous instructions and double check that everything has been done correctly.


Finishing off

Now for tunnel mode. For this you will need to have an account with Hide My Ass. If you have not created one yet then do so now or if you are not happy to pay for one then do not continue. I originally only signed up for one month when I first joined them, but after that I upgraded to a whole year because I really liked it. This choice is entirely up to you though and you may find that other VPN services could work in its place. If so then some of the instructions that follow will not be relevant to you.

There are a couple of prerequisite packages that you need to install first. Enter the following commands;

sudo apt-get install screen openvpn

Screen is a Linux application that allows you to run something from an SSH client but then disconnect and leave it running in the background.  We will be doing this with the VPN connection script which we must download next.  Enter the following commands;

cd ~/scripts
wget http://hmastuff.com/hma-vpn.sh
sudo chmod +x hma-vpn.sh

Okay now we are ready to bring up the VPN and go into tunnel mode, lets go with New York as the location.  Use the following commands;

sudo ~/scripts/tunnel.sh
screen sudo ~/scripts/hma-vpn.sh -p tcp "New York"

For the first time only you will be prompted for your HMA username and password, this will be saved to a file called password.txt for future uses.  If this has been successful you should see a message saying that you are now connected to the HMA VPN as well as your new IP address is.

 *******************************************
*                                           *
*   You are now connected to HMA Pro! VPN   *
*                                           *
 *******************************************

Security notice!  If you try to SSH to this IP address via Putty or a Terminal window you will be able to log in.  So it is a good idea to change the default password for the pi user at some point.  You can use the following command to do this;

passwd

If you hold down Ctrl – A and then also press D you can disconnect the screen session whereupon you will be able to exit Putty or your Terminal window leaving the VPN up.

Okay so now go to your device and attempt to access some georestricted content from the USA.  You should find that you are able to do so.  If you get any problems with using the HMA VPN here is a link to their support page.  They respond to emails quite well and they have quite a cool instant support chat feature.

To close down the VPN connection you can log back in over SSH and enter the following command to resume the screen session;

screen -r

If you press Ctrl – C this will disconnect the VPN.  You can then switch back into router mode by entering;

sudo ~/scripts/router.sh

You can change the location from New York to another city simply by replacing the word New York in the above command to something like Stockholm for if you wanted to access content from Sweden.  You can get a list of all available servers around the globe using this command (give it a minute or two);

sudo ~/scripts/hma-vpn.sh -l >~/servers.txt

That will then create a file called servers.txt in your home folder that you can examine later with nano or Leafpad.

Aliases

I appreciate that these commands are quite long and would be difficult to remember however we can quite easily make some aliases for them.  This will allow you to assign a word to invoke the commands.  Like tunnel for tunnel mode and router for router mode.

Enter the following command;

sudo nano ~/.bash_aliases

You may or may not be looking at an empty file now.  Some games from the Pi Store set these up so that you can run them without having to go into X windows.  Anyway, append the following to the end of the file;

alias router='sudo ~/scripts/router.sh'
alias tunnel='sudo ~/scripts/tunnel.sh && screen sudo ~/scripts/hma-vpn.sh -p tcp "New York"'
alias sweden='sudo ~/scripts/tunnel.sh && screen sudo ~/scripts/hma-vpn.sh -p tcp "Stockholm"'
alias attach='screen -r'

Press Ctrl – X, y and enter to save and quit out of nano.  You will need to reboot in order for these commands to become active.  After which you will be able to type router for router mode, tunnel for tunnel mode and attach to resume the screen session when you want to close down the VPN.

sudo reboot

For added convenience you can even use an SSH program on your smart phone.  Search your app store for “ssh client” and see what is available.  Below is a screen shot from an iPhone one called WebSSH.  With these you can often just use the back button to disconnect the screen session instead of holding down Ctrl – A and then aslo pressing D.

Note: A quick word about latency.  Latency (often called ping time) is the name given to the time it takes for a network message to get from its point of origin to its destination and back again.  You can measure this with the ping command, the unit of measurement is milliseconds.

ping 8.8.8.8

When you use a VPN all your network traffic is going to pass through the location that you chose and therefore your latency will be affected by the physical distance this location is away from you.  For example if you live in Canada and you make a VPN connection to Sydney in Australia your latency will increase massively.  So do bear this in mind when choosing a location to VPN into.  It’s not such a problem for streaming Internet TV but it will be very noticeable if you want to play online games via the VPN tunnel.

If you find any mistakes or errors please feel free to post below.

Windows Networking on the Raspberry Pi

The goal of this article is to configure the Raspberry Pi so that it can integrate into an existing Windows Networking environment without needing to make changes to any of the other, perhaps numerous, Windows PCs.  I know that there are numerous other ways to achieve networking like this though so please don’t feel the need to tell me about them in the comments below.  Please note that I will be doing a version of this article for the Apple Macintosh too.

A good way to do some programming on the Pi is to access the Pi file system over the network.  The advantage this gives you is that you can speedily browse the web for snippets of code under Windows and then copy / paste them directly into a file on the Pi.  This method works really well for me and it also allows me to easily back up my source code onto my main Windows machine.  Or you might just want to turn your Pi into a NAS device!

So this guide is intended for someone who is familiar with Windows Networking already.  If you have never used it before there are plenty of good guides out there which you can read.  Perhaps try and network two normal Windows PCs before you try this.

So we’re going to use Raspbian for this, first off make sure you download the most recent Raspbian image and burn it onto an SD card.

Before we get going I just want to mention a Windows program that you should familiarise yourself with.  Putty (above) is a terminal client program that will basically allow you to have the Raspberry Pi command prompt (the Shell) inside a desktop window (see below).  Raspbian comes with an SSH (Secure Shell) server that makes this possible.

Don’t confuse this with a full remote desktop program though, it just gives you the command prompt.   If you were to try and type startx inside Putty it wouldn’t work.  Putty only supports text based ouput.  However you can do things like install programs, move files around, reboot the Pi etc.  Basically everything you would normally be able to do if you were using the normal Linux command prompt on the Pi itself.

Where am I going with this?  You can copy and paste Linux commands directly into Putty from a web site such as this without having to manually type them out.  It will save you having to carefully check that you’ve typed the commands in correctly and therefore bags of time.

You can download Putty from here (putty.exe is the one you want).  It doesn’t have an installer package, it’s just a standalone exe file.  When you run it you’ll see the configuration screen below.

Enter the IP address of your Pi into the host name field and click the Open button.  If you don’t know the IP address just type ifconfig at the Pi command prompt and the address is on the second line just after inet addr.  You can ignore the security warning (below) and click yes (you’ll only see that warning once).  Note the Save and Load buttons, you need to provide a name under Saved Sessions to use those.

You’ll then have the usual login prompt, login with the same username and password as you would use on the Pi itself.  A paste in Putty is done by a right click of the mouse.  Copy and paste the following command into Putty and press enter.

sudo apt-get update

This just updates the package list so it’s ready for when we want to start installing new software, which is next!

We’re going to install a utility called Samba, yes like the Brazilian dancing but actually nothing like it.  It’s a suite of tools that allow Linux based machines to interact with Windows Networks and it’s also available for Raspbian.

Here is the next command to paste into Putty;

sudo apt-get install samba samba-common samba-common-bin winbind

A message saying that about 50 MB of disk space is required will show along with a prompt asking if you want to continue.  Just type y and press enter and the installation will begin, it may take a few minutes to finish.  If you’re wondering what winbind is; this is a small background process that announces your Pi by name to Windows PCs on the network, allowing them to use the actual host name instead of the IP address.

If you go to a Windows PC now, bring up a command prompt and enter ping raspberrypi (or whatever host name your Pi has) you’ll see that you get a reply.  You can also use the same host name in Putty from now on.  We’re not quite finished yet though.

We now need to edit the configuration file for Samba to specify how we want things to work, its a bit laborious but we only need to do it once.  I recommend you also do this in Putty so you can continue to copy and paste.  So we’re going to change to the Samba config folder, make a backup of the default config file and then edit the file using a program called nano.  Enter the following commands one by one.

cd /etc/samba

sudo cp smb.conf smb.backup

sudo nano smb.conf

You will now see the top of the config file, it should look something like this;

#
# Sample configuration file for the Samba suite for Debian GNU/Linux.
#
#
# This is the main Samba configuration file. You should read the
# smb.conf(5) manual page in order to understand the options listed
# here. Samba has a huge number of configurable options most of which
# are not shown in this example

A hash symbol indicates a comment in this file, so any line that starts with one is either a comment or a disabled setting.  Scroll down until you find [global].  You should see a line saying workgroup = WORKGROUP.  Change this to match the workgroup or domain of your Windows PCs, this will make the Pi visible when you browse the network in Windows.  Also add a setting called realm and one called netbios name just below and set them to the host name of the Pi.

   workgroup = WORKGROUP
   realm = raspberrypi
   netbios name = raspberrypi

Press Ctrl – O then enter to save.  Do this periodically so you don’t lose any changes.  Don’t concern yourself with what all the various settings mean, you can read up on this if you really want to know.  The comments often describe them quite well though.

A bit further down you should find this line, remove the semi colon.

;   name resolve order = lmhosts host wins bcast
   name resolve order = lmhosts host wins bcast

Next scroll down until you find;

####### Authentication #######

A bit below that you should see this line, remove the hash.

#   security = user
   security = user

So this is turning on user level security.  It will allow you to access the Pi from a Windows PC using your Raspbian login (for example ; pi / raspberry).  Save your changes.

So we now need to set up some Samba shares, these are equivalent to Windows shares and allow you to see the files from another computer.  Let’s make two shares.  One which is the home directory of the Raspbian user (cd ~ at the command prompt) and one NAS type share that all users can access.

Scroll right, right down until you find this.

#======================= Share Definitions =======================

Just under it you’ll see [homes].  Modify the settings so that they match what is below, copy and paste if desired.

[homes]
   comment = Home Directories
   browseable = no
   valid users = @users
   writable = yes
   create mask = 0700
   directory mask = 0700

A bit further below you’ll see a line saying read only, change the yes to no.

   read only = yes
   read only = no

Press Ctrl – X, y then enter to save and exit nano.  We now need to create the physical folder for the NAS-all-users share.  For this example I’m going to make the location of the NAS folder /home/samba-share/nas (which is on the Pi SD card) however you may want to change this to share a USB drive that you’ve connected to the Pi.  In which case the path would be something like /media/usb0.  You’ll need to check out what the drive name is by using the command below.  If you need some help with mounting NTFS drives, have a look here.

ls /media

The name usb0 may not be the same for you.  You can then just substitute /home/samba-share/nas for the correct /media/usb0 path in all the text that follows.

If your nas folder is going to be on the SD card then you should copy and paste the following commands into Putty one by one.  Otherwise you can skip them.

sudo mkdir -p /home/samba-share/nas

sudo chown -R root:users /home/samba-share/nas/

sudo chmod -R ug+rwx,o+rx-w /home/samba-share/nas/

The first line creates the actual folder and the second two set the permissions on it so that all users can have read, write and delete permissions.  We now need to add the settings to smb.conf to make this folder visible as a Samba share, so run nano again.

sudo nano smb.conf

Scroll right to the end of the file and paste in the following settings.

[nas]
   comment = All users
   path = /home/samba-share/nas
   valid users = @users
   force group = users
   create mask = 0660
   directory mask = 0771
   writable = yes
   read only = no

Press Ctrl – X, y then enter to save and exit nano.  The last thing to do is to create a Samba user to match your Raspbian user, then we can reboot and it should be ready to go.  Copy and paste the following command, you will be prompted to enter a password twice, enter the same password that you use to login to Raspbian with (e.g. raspberry).  Note that when you type a password no letters are shown, this is normal Linux/Raspbian behaviour.

sudo smbpasswd -a pi

You should then see Added user pi.  That is the configuration side of things done now, you can go ahead and reboot the pi.  You can send the reboot command from Putty, but you’ll then see a messaging saying that the server closed the connection.  This is obviously because it’s going down for a reboot!

sudo reboot

While the Pi reboots you can go onto your Windows PC and get ready to browse the network.  On Windows XP you should see something like this.

And on Windows Vista or 7 something like this.  If you’re using Windows 8, please have a look at the comments on this article at the end.

Double click the Pi server icon in Windows and you should be prompted for a username and password.  Use the same that you use for Raspbian (e.g. pi / raspberry).  You should then see two shares; nas and pi.  In some cases you may see the nas share only, before being prompted for the login details.  If this happens you’ll be prompted when you try to access the nas share whereupon the pi share should become visible.

Once you’re in, go into the pi share and to test it’s working just right click and go New > Folder.  If it lets you create and name the folder you’re in business.  Maybe try copying a large file over to the Pi and see what kind of transfer speed you get.

You can check that the changes you made from Windows are now visible on the Pi itself.  Either login on the Pi or via Putty and just type ls from the home directory.  Below we can see the “dave” folder I created from Windows.

So that is pretty much it.  If you’re interested in seeing a good way to do some code editing from Windows with the Pi just being used to test and run the program then read on, otherwise you’re done.

So if you already have a preferred code editing tool then you can just use that.  Otherwise I can recommend a nice lightweight program called Notepad++.  This program is tremendously convenient for code editing since it integrates with the Windows shell right click menu, allowing you to right click on any file to edit it.

So from Windows, browse into the pi share.  Right click and go New > Text Document and name the file test.c.  You now need to open this file in your Windows code editor.  If you’re using your own program you may need to re-browse to the pi share from the File > Open menu.  However with Notepad++ you can just right-click the file and select Edit with Notepad++.

Copy and Paste the following code into your code editor.

#include <stdio.h>

main()
{
    printf("Hello World\n");
}

So you should now have something like this.

Save the file from your code editor and we’ll now go onto the Pi to compile and run it.  You can either log onto the Pi itself or use Putty.  After logging in type ls and you should see the test.c file, that you created from Windows, is shown.  Enter the following commands to compile and run the program (gcc is the c compiler program).

gcc test.c -o test.bin

./test.bin

If everything has worked you should see the Hello World message, as shown below.

Every time you make changes to test.c you will need to recompile it using the gcc command above.  Try doing that now with the code below.  This will make your Pi count to a million, press Ctrl – C while running if you want to stop it.

#include <stdio.h>

main()
{
    int i;
    for (i = 1; i <= 1000000; i++)
    {
        printf("%d\n", i);
    }
}

The good thing about Notepad++ is that it provides some nice features that colourise the source code.  Most code editing tools will do this as it makes the code easier for a human to read.  We’ve just been using C, but Notepad++ will also do the same thing for other languages like Python too.

From Windows have a look inside the python_games folder and check out the code in the .py files that are in there.  Good luck.