Abusing Public WiFi Access Point Protocols for Fun and Beer Measurement (Raspberry Pi)

This is a little sub-project of what I’ve been working on recently – a hideously over-engineered Raspberry Pi-based system to measure the amount of beer left in the kegs in my keezer.

Normally I would simply set up a web server on the Pi and have it on the home network, so I could see the levels remotely. The problem is that the routers are all inside the house and the Pi is in the garage, invisible to them all thanks to the 2 external walls between them. I needed some way to read out the beer levels on my phone – after all, walking up to something and looking at the level gauge is so last millennium.

So – Bluetooth or some sort of ad-hoc Wifi thing? I like to re-use stuff I’ve got lying around in drawers, so the solution seemed to be an old WiFi dongle that was gathering dust. And Bluetooth is awful. Setting up a Pi as an access point is fairly well covered on the internets, but this is a bit different in that we don’t want to forward traffic onto our network like an access point – not that it could connect anyway, being out of range. I also didn’t want to install a web server on the Pi. It’s only a Pi 1 model B, so sticking Apache and PHP on it might be asking a bit much – especially when you can do it all with one command and a small BASH script.

So the cunning plan was to take advantage of a feature of public access points – the ones that show you a registration page for you to fill in with fake info.

When you connect to a public WiFi hotspot your device tries to load a page on the internet using non-SSL http. It might be any page (captive.apple.com/ seems to be popular), but it will be a web page that the device knows should exist and if it loads, your device knows the internet is working.

A public access point intercepts the page request and, rather than forwarding it, sends a 30x redirect HTTP response back to the device – basically hijacking the request and spoofing the reply. Your device then loads up the page it has been redirected to and displays it as a sign-in page.

It is this mechanism that I used to show the keg levels on any phone, just by connecting to the Wifi. This is how to do it if you want to do something similar. I’m assuming you SSH on to a Pi connected with an ethernet cable to your network, and you have a Wifi dongle hanging out of its USB port. In all likelihood they will be eth0 and wlan0 respectively, so I’ll use them.

wlan0 is going to use a different range of IP addresses from the ones used by eth0, so edit /etc/dhcpcd.conf to manually assign an IP address to the wlan0 interface. Add this at the bottom (comment out any existing definition for wlan0):

interface wlan0
    static ip_address=192.168.4.1/24
    nohook wpa_supplicant

Next we need to install hostapd to run the hotspot and dnsmasq to sort out assigning IP addresses to devices that connect.

sudo apt-get install hostapd
sudo apt-get install dnsmasq
sudo systemctl stop hostapd
sudo systemctl stop dnsmasq

The second two commands disable the services we just installed so we can edit config files before starting them again.

Create the file /etc/dnsmasq.conf and put this in it:

interface=wlan0      # Use this interface - usually wlan0
dhcp-range=192.168.4.2,192.168.4.20,255.255.255.0,24h

This tells dnsmasq to assign the range 192.168.4.2 – 192.168.4.20 with a netmask of 255.255.255.0 and a lease time of 24 hours. When dnsmasq restarts it will look at this file and load up the config information.

Now to set up hostapd. Create /etc/hostapd/hostapd.conf and put this in it:

interface=wlan0
driver=nl80211
ssid=Your SSID here
hw_mode=g
channel=7
wmm_enabled=0
macaddr_acl=0
ignore_broadcast_ssid=0

It’s pretty obvious what is happening there, other than some of the technical bits; wmm_enabled is something to do with packets (no idea what, though), macaddr_acl tells it to whitelist all connections and ignore_broadcast_ssid tells it to broadcast the SSID – set it to 1 to hide it. There is no WPA password or setup, obviously. Change the SSID to something hilarious.

Now you need to tell hostapd where to find the config file when it starts. Edit /etc/default/hostapd and add (or uncomment and edit) the line:

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

We have now set up our access point. Start dnsmasq and hostapd again:

sudo systemctl start hostapd
sudo systemctl start dnsmasq

If there are no errors, your AP should show up in the list of APs on your phone, laptop etc. Try connecting to it – it should connect but you won’t be able to see the internet because there is no forwarding. One thing you can still do however, is connect to SSH on the Pi. You really don’t want any ports other than 80 visible from an unsecured AP. We’ll use iptables to set up a firewall and do the test page hijacking.

sudo iptables -A INPUT -p tcp -i wlan0 --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp -i wlan0 -j DROP
sudo iptables -t nat -A PREROUTING -p tcp -i wlan0 --dport 80 -j DNAT --to-destination 192.168.4.1:80

The first one tells iptables to allow through connections on port 80 (HTTP), the second tells iptables to drop all other TCP connections from wlan0. The third redirects any connection with a destination port 80 (regardless of the IP address) to the Pi at IP address 192.168.4.1, port 80, for our server to handle. If you are a bit confused about how iptables work, this flowchart will either clear things up or make it more confusing. Basically there are 4 tables – filter (default if no -t switch), nat, mangle and raw which each contain “chains” such as INPUT which are the instructions on how to route traffic. It’s a vast subject and I learned just enough to work out the 3 lines above. There are other guides that go into more details.

One thing to do at this point is make it so that the iptables configuration is not lost when the system is rebooted. This command saves it to a file:

sudo iptables-save >/etc/iptables.ipv4.nat

To reload the configuration on boot put this in /etc/rc.local

iptables-restore < /etc/iptables.ipv4.nat

So, moving on to the web server. I’m using socat and a bash script. socat is one of those amazing Linux tools that is impossible to explain to a layperson. “What it does is, it takes data from one place and puts it in another but it’s more complicated than that…” and so on. Best just to tell them it’s the computer equivalent of magic, before their eyes glaze over and they start thinking about feigning an illness in order to escape. We are going to use it to pipe data from an internet port to a script and back again. Incoming text from port 80 is sent to the script on stdin and anything written to stdout gets sent back to the port. It’s easy enough to set up with this command:

sudo socat TCP4-LISTEN:80,reuseaddr,fork EXEC:"/home/your_path_here/server.sh >/dev/null" 2>/dev/null &

Obviously change “your_path_here” to where you are doing all this stuff and put this line in /etc/rc.local if you want it to start automatically on boot. The command tells socat to listen on port 80 and then fork off the script when there is a connection. The script referred to as /home/your_path_here/server.sh is this:

#!/bin/bash

PAGE_NAME="kegs"
FOUND_URL="http://1.1.1.1/$PAGE_NAME"

request=""
while read -r  -t 5 line; do
  if [[ ! -z "${line:-}" && $line == *[^[:cntrl:]]* ]]; then
    if [[ ${line:0:4} == "GET " ]]; then
      request=$(expr "$line" : 'GET /\(.*\) HTTP.*')
    fi
  else
    break
  fi
done

if [[ "$request" == "$PAGE_NAME" ]]; then
  printf "HTTP/1.1 200 OK\n"
  printf "Content-Type: text/html\n\n"
  cat index.html	# Show this as a registration page.
else
  printf "HTTP/1.1 302 Found\n"
  printf "Location: $FOUND_URL\n"
  printf "Content-Type: text/html\n\n"
  printf "Redirect to <a href=\"$FOUND_URL\">$FOUND_URL</a>\n"
fi

That’s pretty dinky for a web server, huh? Don’t forget to change permissions of server.sh with chmod 755 server.sh. Rename PAGE_NAME and FOUND_URL to whatever you want. Note that because we are grabbing all port 80 traffic coming in on wlan0, it doesn’t matter what you put for an IP address – it’ll all go to our server. The first block of code reads the HTTP request coming from the device, which will be saying something along the lines of:

GET / HTTP/1.1
Host: captive.apple.com
Accept: image/gif, image/jpeg, */*
... and so on

The script ignores everything except the GET /… part, from which it extracts the page name, if any. It won’t match (unless the test page is called “/kegs” – unlikely), so it will respond with the redirect code 302, to send the device to “/kegs”. The device sees the redirect, thinks it’s for a registration page and loads 1.1.1.1/kegs. This time the script sees that /kegs has been requested, sends a 200 OK code and the contents of index.html, which the device displays. My beer measurement system generates index.html as a page showing how much is left in each keg.

As a useful tool with which to quickly see the levels of my kegs without any fuss, this is rubbish, quite frankly. But then the whole raspberry-pi-based-keg-measurement thing could be replaced with cheap mechanical bathroom scales, so I might as well go all in on the pointless technology.

Updated 10/6/2020 : Improved the firewall rules.

Taming the PiFM Transmitter (Part 2)

In part one of this guide it became clear that a Raspberry Pi with a 700 mm long wire on pin 7, running a variant of the PiFM software is an easy way to make a nuisance of yourself. We might not be broadcasting kilowatts of power and realistically, you are not going to be knocking planes out of the sky, but the Pi is a dirty old man when it comes to broadcasting and we need to clean up its act.

The obvious way to do that is to put a filter between the Pi’s output and the aerial. If the design considerations and analysis of the filter’s performance don’t interest you, skip to the end for circuit diagrams, construction instruction and purchase info (possibly).

As always, these posts are for educational use only. Do not use your Pi as a transmitter unless it is legal for you to do so, which is highly unlikely. Using a filter will not make it any less illegal for you to use your Pi as a transmitter.  Always brush your teeth before bedtime and be nice to people.

To recap, this is typically the sort of thing that comes out of your Pi when you use it as an FM transmitter:

There’s a lovely spike around the 144 MHz mark, which is the amateur radio 2m band. There are probably not many radio hams near me that like the sort of music I listen to. Come to think of it, some times I’m not sure I do either. In general, it’s a broad splattering of crap all over the spectrum. And the Pi’s transmitted output is just as bad, ho ho ho. Ahem. This is the sort of thing we need:

You might notice R1 there. The GPIO pins are not designed to drive inductive or capacitive loads, so we need to make the filter input a bit more friendly. The easiest way is to put a resistor between the Pi and the filter’s inductor. I’ve tried it and it works, but it does reduce the range of the transmission. If you want to try it without R1, don’t blame me if you fry your Pi. There’s about 5 dB loss with this design, which might be fine for you. For me, it reduced the range just enough that the signal was fading out if I stood in the wrong part of the kitchen. The solution was either to avoid using the fridge or to amplify the output a bit.

I’m not an expert with RF circuits (although I probably know more than you), so I used the interwebs to find a design that would

  • Be cheap
  • Work on a 5V supply
  • Not require any fine tuning
  • Be cheap
  • Be easy to make
  • Not have any expensive components

You can probably tell what my priorities were. This was the prototype:

Those with a keen eye have probably already spotted that it looks shit. Bear in mind that it’s already been bodged around a bit, and it looked worse than that by the time I’d finished experimenting with the poor thing. It is a single stage class C amplifier with a low pass filter on the output. The 2N4427 transistor is old and cheap; I bought 5 from China for about £3. Everything else (apart from the variable capacitors) is bog standard and the coils are easy to wind. The variable capacitors are stupidly expensive – there is about £20 worth of them in that photo, so they had to be replaced with fixed ones that cost pennies.

The end result was this circuit:

Pi Hat Filter – click to enlarge.

It’s cheap, simple and it works quite well. This is the finished hat installed and working:

This is the output with the filter hat on:

Out of band signals are attenuated by at least 20 dB, which means they are 1/100th the power of when it was hatless. There is even a little bit of gain at our broadcast frequency, which also amplifies the in-band harmonics, unfortunately. It’s not exactly BBC quality but it should stop you annoying the neighbours. If you want to get the absolute maximum performance out of the filter, use 5-95pF variable capacitors instead of C7, C8, C13 and C16 and keep tweaking them until it becomes apparent that you aren’t really having any effect.

The design files are here.  If you would be interested in a kit of parts or a ready made hat, leave a note in the comments and I’ll look into it.

I’ll leave you with a comparison of the filtered (orange) Vs. unfiltered (blue) Pi:

Good, eh?

Taming the PiFM Transmitter (Part 1)

One of the million things you can do with a Raspberry Pi is using it as an FM radio transmitter. It is stupidly easy; you just attach a 700 mm long wire to pin 7 and install one of the many variants of the original program which was hacked together at a code club meeting. And now you are a radio pirate. This guide is aimed at those who can do the above but don’t know why it might be a bad idea. If you already know about harmonics or know that they are bad but  don’t care why, you can skip to the next post which is about adding a filter to your Pi.

At this point it is traditional to say that broadcasting without a license is illegal in most countries and doing something like using your Pi to stream internet radio stations to the analogue radio in your kitchen is wrong and makes Eben Upton cry.

One thing you will often hear in discussions about Pi radio is that lots of unwanted harmonics are produced on frequencies other than the one you are broadcasting on. These can interfere with legitimate users of that frequency; for example a passing pilot might not want to hear the Crisp Biscuit Breakbeat remix of Josh Wink’s Higher State of Consciousness instead of the control tower telling her where to land. You might think that anything broadcast from your little Pi won’t be powerful enough to interfere with a professional communications system, and you are very probably right. But what exactly is coming from our Pi’s aerial? This is what we would like to see:

What we would like to see coming out of our Pi. Click for a better view.

Along the X axis are all the frequencies from 50 MHz to 350 MHz. The Y axis shows the level of the signal at that frequency in dB. If you just clicked on the “dB” link and are none the wiser, the upshot is that the dB makes it easy to compare the relative powers of signals. For example, a +3 dB difference is twice the power and a -3 dB difference is a half the power. So +6 dB means the signal is quadruple the power of whatever you are comparing it to – it’s the same as a +3 dB doubling and another +3 dB doubling. As the dBs go up in linear fashion, the corresponding power goes up exponentially: +3 dB, +6 dB, +9 dB corresponds to x 2 power, x 4 power and x 8 power.

The graph shows the main peak of our transmission at 107.3 MHz, at about +11 dB, a harmonic at 214.6 MHz at -25 dB and another at 321.9 MHz at -30 dB. These unwanted harmonics are bad, but their levels are a lot lower than the main broadcast frequency. If the harmonic’s signal level is -36 dB compared to the main one, it means it’s about 4000 times weaker and we don’t really need to worry about it, given that the main signal only goes a hundred metres or so. The other unwanted signal is even lower: -41 dB compared to the main signal so I’m not even going to bother to work out the exact value because it is so small. OK, it’s 12,500 times less than the main signal. That won’t even make it out of the room.

So that’s our ideal transmitter, with a nice strong signal on the frequency we want and weaker signals on the frequencies of the harmonics we don’t. How does this compare to the actual signal from a Pi? Take a look at this little beauty – it is what’s coming out of my my Pi when it’s broadcasting on 107.3 MHz:

Actual output from a Pi. Barf.

It’s spewing crap from 50 MHz to 800 MHz and probably beyond. One of the harmonics is actually more powerful than the frequency we want to transmit on. The signals coming out of that aerial are dirtier than a dog in a field of incontinent cows [todo: change this to something more tasteful]. The neighbours are probably wondering why old skool breakbeat trance music is coming out of their hoover.

It gets worse though. The harmonics coming from the Pi change in number, size and position as you change the frequency. Broadcasting on exactly 100 MHz actually produces a graph somewhat similar to the first one, but drop the frequency by 1 MHz to 99 MHz and you get this:

99 MHz – Craptastic!

Now that is quite pretty, but it did genuinely start making lines go down my monitor and a hum come out of my speakers. God knows what it was doing to the output electronics in the poor Pi.

So, before doing anything else, you need to pick a frequency that won’t make music come out of your granddad’s fillings. The cleanest one is 100 MHz, but where I live there’s already a commercial station there, so that was out for me – my little Pi couldn’t compete with the big boys. You don’t want to pick one that’s close to 100 MHz either because they seem to be the dirtiest. Trial and error, picking the gaps between existing stations, seems to be the way to do it. Ideally, you want a spectrum analyser like the one I used to make the graphs, and surprisingly, you can get the hardware for about £20, and use something like this to turn it into a spectrum analyser. At the very least, you could pick a frequency and see how many times your broadcast appears when you tune your radio up and down. As a general rule, the fewer times the better.

But however carefully you choose your frequency, your Pi will still be broadcasting all over the spectrum and possibly making someone near you very angry. You can improve things by putting a filter on its output, and I can show you how in the next post.

Pirpl – it’s another Pirate Radio PLaylist thing!

Old Radio Station EditedIf you liked the previous Pi-rate Radio Jukebox (and 15 people did!), you won’t want to miss this latest version of it.  It’s basically the same thing, but it runs as a daemon, so you can fire up your favourite tunes using a browser rather than logging in to your Pi to start up scripts.  As usual it’s horribly coded in Bash and features a fuck-ugly interface with no aesthetic considerations whatsoever.  You can insert prettiness yourself if you want to – it’s easy enough because the web pages are done as templates.  All the code is commented to pad it out and make it look more substantial than it is clearly show what is going on.

This one is called Pirpl and is pronounced “Purple” because it seemed like a good idea at the time.  Something to do with Pirate Radio PLaylists or something – it’s all a bit tenuous, quite frankly.  Anyway, the main improvement is that rather than telling it what to play from the command line,  you pick what you want to listen to from a list on a web page.  As before, you can tell it to play all the MP3s in a directory (and all sub-directories) or give it a list of MP3s to play in a file.  It’ll then play them (in a random order if you want), showing the current tune on a web page and allowing you to skip a track or stop playing and go back to the playlist chooser.

Other improvements are:

  • Support for MP3 ID tags in both version 1 and version 2 format.  The old player only recognised version 1 tags.
  • Umm… that’s about it really.  The code is slightly better in places, I suppose.  Still the playlist choosing thing is good, isn’t it?

Quick start

pirpl
Nice clean lines. What is not to like?

Want to get going already?  This is the tarred archive (20.8 kB)

Download the archive, untar it, edit the “pirpl_conf” file (you’ll see why in the file) and add playlist information to the “pirpl_playlist.conf” (you’ll see how in the file).  Before you can start it up, you need to make sure that the following packages are installed on your Pi:  netcat, sox, id3v2.  If one or more isn’t then, install any missing ones with

sudo apt-get install netcat sox id3v2

The program that does the transmitting needs to run as root, so setuid  that bad boy up with:

sudo chown root:root pifm
sudo chmod 4755 pifm

Before you can oscillate any electromagnetic fields, you’ll need to make an aerial for your Pi.  Instructions are in first paragraph of the drivel for pirbj.

Once you are sorted, start the whole lot up with the command:

./pirpl.sh pirpl_conf

To stop it press CTRL-C.

The gruesome details

There are quite a few files that make up pirpl.  This is how they work.

pirpl.sh

This is the main program file.  Have a look at it if you want to gaze in wonder at the insane beauty of Bash, but there is no need to edit it.  All the configuration stuff is now in…

pirpl_conf

Various settings for things like the names of files, the transmitter frequency and where you installed pirpl.  You probably want to change the transmitter frequency to somewhere empty on your radio’s dial.  You will also need to change PIFM_BASE to the directory where you untarred the files.  The web server port should not be accessible to the outside world.  Other than that, it’s probably best to leave everything else as it is unless you really like reading error messages.

pirpl_playlist.conf

This is where you tell pirpl all about your music.  Each line has the path to the playlist or directory containing MP3s, the displayed name of the playlist, and whether to shuffle it.  I’ve left all my playlists in as examples.  Actually, I forgot to delete them and now I can’t be bothered to take them out.  Sorry.  If you are using a playlist rather than a directory, the format is one path to an MP3 per line.

pirpl_playlist_template.html

Your browser will show this as a web page so open that link, right click and choose “View page source” to see what is in it.  You have probably worked out for yourself that this is a template file for showing the available playlists, as defined in pirpl_playlist.conf.  The bits in “@@”s are replaced with the information about playlists.  I’m sure you can work out what’s going on in that file.

pirpl_template.html

This is the template for showing information about the track that is playing.  It’s the usual stark functionality you get from me, simply because it works and I can’t be bothered to try and make it look nice.

pirpl_server.sh

This is the script that does the web server.  It doesn’t do much; it just outputs a file to the browser and filters commands out of the text sent by the browser, storing any it finds in a file which is picked up by pirpl.sh.

pifm and source/pifm.c

The program that does the transmitting.  It’s a barely modified version of this one and the source is included if you want to have a look and compile it yourself.

startwrapper.sh

The best way to start Pirpl is as a service, when the Pi boots up.  You don’t want to run it as root, so the easiest way to start it as a normal user is to put a command similar to this in your /etc/rc.local file:

sudo -u naich /home/naich/pirpl/startwrapper.sh

You could use sudo to start Pirpl directly but you end up with sudo hanging around like a bad smell in your process list.

In conclusion

Using this program without the proper license is probably illegal where you are, so don’t use it ever.

Pi-rate Radio Jukebox

p1070168Note: there is an update to this post.

There is a nice hack for a Raspberry Pi where you can turn it into an FM transmitter.  While this is illegal in most countries, the range is quite limited so it’s fairly unlikely you’ll go to prison. The only hardware needed is your Raspberry Pi and a piece of wire attached to pin 7 (GPIO 4) of the GPIO connector.  The length of the wire depends on the frequency you are transmitting on – roughly speaking, it should be 299/(frequency x 4) metres long.  So 103 MHz is 725 mm.  Or if you are using inches, 299/(frequency x 0.1016) inches.

It’s very easy to transmit internet radio using just one line of Bash but if, like me, you have a few thousand MP3s , there’s no quick and dirty way to pump them out to the transmitter.

Until now.  Behold the PIrate Radio Juke Box (pirjb). If you can think of a better name for it, please leave a comment.  A couple of Bash scripts, a minor alteration to the pifm code and a reckless disregard for radio licensing regulations is all that is needed to listen to your collection on any FM radio.   You can repeat and shuffle with either a playlist of MP3s in a file or point it to the directory the MP3s live in and it’ll scan them and make its own playlist.

Also included is a web server to show you the currently playing track.  Using your browser, you can skip to the next track or shut everything down and turn the transmitter off.  Note that you can’t turn it back on with the web interface yet.  That’s the next thing on the to do list.  You can get to the page by going to http://your_pi_address:8080/  The “8080” is set in the pirjb.sh file, at the top.

Note that I do not condone or encourage the use of transmitting equipment without the proper license.  This article is presented purely as an exercise in theoretical programming.  Your statutory rights are not affected.  Your home may be at risk if you set fire to the curtains.

Setting up

You need to have the following packages installed: sox, netcat, mp3info.  Use

sudo apt-get install sox netcat mp3info

to install them.

Copy the pirjb archive to an empty directory on your Pi and extract the files with

tar zxf pirjb.tgz

You need to edit pirjb.sh.  The top few lines are where things like the transmission frequency, path to the scripts and the port for the web server are defined.  There is also a line for the compander settings for sox in order to have an AGC.  If you didn’t understand that last sentence, don’t change that line.  I’ve also included the source for the pifm binary included in the archive.  There is a very minor change to it from this one – calling it with no parameters turns off the transmitter.  Please do compile it and use it instead of the binary I’ve put in the archive.  You shouldn’t really be running binaries from random geezers on the interwebs anyway.  And I am sometimes quite random.

You need to make pifm run as root using setuid in order for the transmitter to work.  Do this with:

sudo chown root:root pifm
sudo chmod 4755 pifm

To run it use:

pirjb.sh -d <directory name>  or
pirjb.sh -p <playlist>

Switches are -s to shuffle the track order, -r to repeat the playlist indefinitely.  The playlist file should have the full path of each mp3 you want to play per line, i.e.

/home/naich/music/Wombles Christmas Special/01 Wombling Christmas.mp3
/home/naich/music/Napalm Death/Scum/Human Garbage.mp3
… and so on.

Have fun playing with it and do not use it because it is illegal to do so.

Files included in the archive:

  • pifm : The transmitter binary
  • pirjb.sh : The jukebox script.  Edit the first few lines for your system.
  • pirjb_webserver.sh : The webserver script.  No need to edit it.
  • pirjb_template.html : The template for the web server page.  See pirjb_webserver.sh for information about using it.  Or just look at the file itself and have a guess.  It’s not hard to see what’s going on.
  • source/pifm.c : The source for pifm.  Compile with g++ -O3 -o pifm pifm.c then copy over the top of pifm.  Don’t forget to chown and chmod the compiled program.

Miscallaneous Wibble

This post is part of a short series of tutorials for people who are new to using their Raspberry Pi.  It will make more sense if you start at the beginning.

Continued from here.

First page here

12.  Some other useful bits and bobs

Firstly, let me say that Linux is a huge subject and I’m only scratching the surface here.  Also, my knowledge on the subject is not that great; I know enough to get by and Google for everything else.  Secondly, all this huge operating system is contained within the 2GB SD  card plugged into your Pi.  That’s about £30 of hardware to create what used to be called a mainframe computer, and if you aren’t impressed by that, you haven’t understood how much your Pi can do.  Here are some bits and bobs that you might find useful as you learn more.

12.1  Pipe to your grep

Pipes were briefly mentioned earlier, as a way to stop text whooshing off the top of your screen by appending |more to the end of a command.  Here is a brief, incomplete and misleading explanation of how they work.

It’s in the nature of computers that programs take something in, do something and then put something out.  A program with no inputs or outputs doesn’t do much, after all.  You might think that command line programs take their data in from the keyboard and put it out to the screen but they actually talk to the streams, stdin and stdout – which you can think of as being like a plug and socket, one at each end of the program, through which data is poured.  It is the shell (Raspbian uses “bash” by default) that acts as an interface between you and the computer, linking the keyboard to the stdin stream and the screen to the stdout stream.  Thanks to the standardised way data is pumped in and out of programs, you can join them together so the output of one program becomes the input of another.  This is done with a “pipe” – | which is simply placed between the programs so that the data flows from left to right.  Examples will probably make more sense than words.

grep” is a program which searches for words through whatever text is put into it.  There are many ways to use it; like searching through files for a word – let’s find lines containing the word “transmission” in the log file for dpkg (which is used by Apt):

naich@raspberrypi ~ $ grep transmission /var/log/dpkg.log
2012-08-06 12:39:49 install transmission-common:all <none> 2.52-3
2012-08-06 12:39:49 status half-installed transmission-common:all 2.52-3
2012-08-06 12:39:49 status half-installed transmission-common:all 2.52-3
... and so on ...

grep can also take its input from stdin (it automatically does this if you leave the filename off the end of the command), with a pipe.  In this example, “cat filename” prints the contents of the file “filename” which is then piped to grep which prints lines containing “transmission”:

naich@raspberrypi ~ $ cat /var/log/dpkg.log | grep transmission
2012-08-06 12:39:49 install transmission-common:all <none> 2.52-3
2012-08-06 12:39:49 status half-installed transmission-common:all 2.52-3
2012-08-06 12:39:49 status half-installed transmission-common:all 2.52-3
... the same stuff as above ...

But it’s still whooshing off the screen, so let’s take the output of “grep” and pipe it to “more” (no filename after the “more” command makes it read from stdin), which paginates it:

naich@raspberrypi ~ $ cat /var/log/dpkg.log | grep transmission | more
2012-08-06 12:39:49 install transmission-common:all <none> 2.52-3
2012-08-06 12:39:49 status half-installed transmission-common:all 2.52-3
...
2012-08-06 12:40:01 status unpacked transmission-daemon:armhf 2.52-3
--More--

Or we could use “wc” to count the number of times it appears.  As with “grep” and “more”, leaving off a filename makes wc read text from stdin rather than a file.  “wc -l” counts the number of lines stuffed into its stdin:

naich@raspberrypi ~ $ cat /var/log/dpkg.log | grep transmission | wc -l
31
naich@raspberrypi ~ $

All these programs have man page help, by the way.  grep is probably the most useful tool in the Linux toolbox so it’s worth finding out about it.  Also read up about redirection, which is a related subject.

12.2  Processes, and how to kill them

All programs that run on the Pi (known as “processes”) – autonomous daemons, interactive programs and even the program that boots it, have two things – a unique ID number (process ID or “pid”) and a user who owns it (user ID or “uid”).  Well, obviously they have more than two things, but these two are the most important.

The pid is a unique number between 1 and 32768.  Each process gets a pid when it starts which is one more than the previous one assigned, unless it’s already taken, in which case the next higher one is assigned.  The numbers wrap round to 2 (1 is always used by the “init” process) when they hit 32768.

The process also has a user ID (uid), the same as one of the users on the system, as if the user had started the process himself.  The process inherits the identity of the user, writing files in his name for example, and has the same permissions to read, write and execute files as that user.  So a process running as “root”, with a uid of 0 can do anything.  Processes that don’t need to run as root tend to run as their own user, in order to sand box them into their own little world.  You can see this, for example with Transmission, which runs under the uid of 106 – debian-transmission.

You can get a list of processes currently running on your Pi with the “ps” command:

naich@raspberrypi ~ $ ps -ef
UID        PID  PPID  C STIME TTY          TIME CMD
root         1     0  0 Aug20 ?        00:00:14 init [2]
root         2     0  0 Aug20 ?        00:00:00 [kthreadd]
root         3     2  0 Aug20 ?        00:00:09 [ksoftirqd/0]
... lots of processes ...
106       2382     1  0 Aug21 ?        00:22:56 /usr/bin/transmission-daemon --c
107       3527     1  0 Aug23 ?        00:13:52 /usr/bin/mediatomb -c /etc/media
root      3860  1949  0 11:35 ?        00:00:00 sshd: naich [priv]
naich     3867  3860  0 11:35 ?        00:00:00 sshd: naich@pts/0
naich     3868  3867  0 11:35 pts/0    00:00:01 -bash
naich     3941  3868  0 12:27 pts/0    00:00:00 ps -ef
naich@raspberrypi ~ $

This shows the user ID (UID), process ID (PID) the process ID of the process which started it (PPID), the start time (STIME), the amount of CPU time it has taken up (TIME) and the command that started it (CMD).  Another, more interactive way to show processes is with the “top” command:

naich@raspberrypi ~ $ top
top - 12:41:13 up 3 days, 16:25,  1 user,  load average: 0.00, 0.01, 0.05
Tasks:  57 total,   1 running,  56 sleeping,   0 stopped,   0 zombie
%Cpu(s):  1.3 us,  1.6 sy,  0.0 ni, 95.4 id,  0.0 wa,  0.0 hi,  1.6 si,  0.0 st
KiB Mem:    220592 total,   209612 used,    10980 free,     7192 buffers
KiB Swap:   102396 total,      568 used,   101828 free,   163588 cached

  PID USER      PR  NI  VIRT  RES  SHR S  %CPU %MEM    TIME+  COMMAND
 2382 debian-t  20   0 43732  11m  896 S   1.0  5.1  23:02.69 transmission-da
 3945 naich     20   0  4616 1348 1028 R   1.0  0.6   0:00.22 top
 3527 mediatom  20   0  152m 9.9m  800 S   0.3  4.6  13:53.06 mediatomb
 3867 naich     20   0 10524 1768 1056 S   0.3  0.8   0:01.54 sshd
... and so on ...

The “%CPU” and “%MEM” show the amount of CPU time and system memory each process is using at this moment and is useful in catching processes that are running out of control.  Press “H” to see the help page or “Q” to quit.  If you need to stop a process running and can’t find a way to do it nicely (with “service process stop”, for example), then you can kill it with kill.  Let’s make a process and kill it.

naich@raspberrypi ~ $ sleep 600 &
[1] 3984
naich@raspberrypi ~ $ ps -fu naich
UID        PID  PPID  C STIME TTY          TIME CMD
naich     3867  3860  0 11:35 ?        00:00:01 sshd: naich@pts/0
naich     3868  3867  0 11:35 pts/0    00:00:01 -bash
naich     3984  3868  0 12:47 pts/0    00:00:00 sleep 600
naich     3986  3868  0 12:47 pts/0    00:00:00 ps -fu naich

“sleep” is a program that does nothing for the number of seconds you tell it.  The “&” at the end means run it in the background, like a daemon, rather than interactively.  Here you tell it to do nothing for 10 minutes and then then you get a list of the processes you are running.  See the one with PID 3984 (your pid will be different)?  That’s the sleeping one we are going to creep up on and kill.  Brutal.

naich@raspberrypi ~ $ kill 3984
[1]+  Terminated              sleep 600
naich@raspberrypi ~ $ ps -fu naich
UID        PID  PPID  C STIME TTY          TIME CMD
naich     3867  3860  0 11:35 ?        00:00:01 sshd: naich@pts/0
naich     3868  3867  0 11:35 pts/0    00:00:02 -bash
naich     3985  3868  0 12:51 pts/0    00:00:00 ps -fu naich
naich@raspberrypi ~ $

RIP 3984.  Poor thing never knew what hit it.  If you are killing it because it has locked up, then you might need to use a bit more force.  If politely asking it to die with kill doesn’t work, use kill -9 to guarantee you’ll finish it off.

12.3  Symbolic links

Symbolic links allow more than one filename to point to the same file or directory.  Similar to (and naturally predating) the Windows “shortcut”, they allow you to use a filename to point to another file or directory in a different place.  They come in two types – hard links and soft links.  A hard link creates a filename that refers to the physical location of the data.  It will appear as a normal file but shares the same data as the file it is linked to.  The more common type is a soft link, which appears as “linkname -> original_file” in long listings.  Example:

naich@raspberrypi ~ $ mkdir wibble
naich@raspberrypi ~ $ echo hello >wibble/linktest.txt
naich@raspberrypi ~ $ ln -s wibble/linktest.txt softlink
naich@raspberrypi ~ $ ls -l
total 4
lrwxrwxrwx 1 naich naich   19 Aug 24 14:22 softlink -> wibble/linktest.txt
drwxr-xr-x 2 naich naich 4096 Aug 24 14:21 wibble
naich@raspberrypi ~ $ cat softlink
hello
naich@raspberrypi ~ $ rm softlink
naich@raspberrypi ~ $ ls -l wibble/
total 4
-rw-r--r-- 1 naich naich 6 Aug 24 14:21 linktest.txt
naich@raspberrypi ~ $

First we make a directory called “wibble”, then create a file in it (linktest.txt) with some text in it.  ln -s wibble/linktest.txt softlink creates a soft link to “wibble/linktest.txt” called “softlink”.  We demonstrate that “softlink” can be used as a real file by outputting the contents with cat softlink.  Then we remove the softlink with rm softlink and show that the original file remains.

Softlinks to directories can cause all sorts of hilarious confusion if you get a bit lost:

naich@raspberrypi ~ $ ln -s / subdirectory
naich@raspberrypi ~ $ cd subdirectory/home/naich/subdirectory/home/naich
naich@raspberrypi ~/subdirectory/home/naich/subdirectory/home/naich $ pwd
/home/naich/subdirectory/home/naich/subdirectory/home/naich
naich@raspberrypi ~/subdirectory/home/naich/subdirectory/home/naich $

Eek!

 12.4  Everything else

Some other other useful things to know about.

There is no on switch or reset button on the Pi, so we use the “shutdown” command to reboot or halt.  Options are “-r” to reboot or “-h” to halt before turning it off.  You also specify a time to do it at, or “now” to do it immediately.

naich@raspberrypi ~ $ sudo shutdown -r now

Broadcast message from root@raspberrypi (pts/1) (Fri Aug 24 14:02:39 2012):
The system is going down for reboot NOW!
naich@raspberrypi ~ $

You can also use the commands halt to halt and reboot to wipe the SD card clean.  Nah, just kidding.  It reboots the Pi.

For file manipulation (stop sniggering at the back), the commands are mv (move), cp (copy), rm (remove), mkdir (make directory), rmdir (remove directory).  This page explains them in english.

Get information about the filesystem with the commands df and du.  df shows how full the filesystems are:

naich@raspberrypi ~ $ df -h
Filesystem      Size  Used Avail Use% Mounted on
rootfs          3.6G  1.4G  2.1G  41% /
/dev/root       3.6G  1.4G  2.1G  41% /
tmpfs            22M  208K   22M   1% /run
tmpfs           5.0M     0  5.0M   0% /run/lock
tmpfs            44M     0   44M   0% /tmp
tmpfs            10M     0   10M   0% /dev
tmpfs            44M     0   44M   0% /run/shm
/dev/mmcblk0p1   56M   34M   23M  61% /boot
/dev/sda1       7.5G  2.0G  5.6G  27% /mnt/downloads

du shows the amount of hard disk space used in a directory and all those under it:

naich@raspberrypi ~ $ du -h /etc
132K    /etc/console-setup
8.0K    /etc/rc4.d
8.0K    /etc/dpkg/origins
... and on and on ...
24K     /etc/gconf
3.8M    /etc
naich@raspberrypi ~ $

Finally, for the moment, check out uptime.  This shows how long it has been since the last reboot.  This is the geek equivalent of comparing penis size, so make sure you have at least a month’s worth of uptime before even mentioning it to anyone, let alone bragging about it.

naich@raspberrypi ~ $ uptime
 15:24:09 up  1:21,  2 users,  load average: 0.00, 0.01, 0.05
naich@raspberrypi ~ $

Yeah, an hour and 21 minutes is not going to impress the ladies.  In my defense, I did have to reboot to get a screenshot earlier.  And it’s very cold in here.

12.4  Further reading

A streaming pile of Pi

Continued from here.

First page here.

11. Setting up your uPNP media server

A uPNP media server allows you to stream videos from your Pi to any device that can talk to it.  A lot of tellies do this these days, along with PS3s, XBoxs, iPads, tablets and your PC.  With a server on your Pi, you can watch what you have downloaded on any compatible device in your house without the hassle of moving files or memory sticks about.  Let’s rock.

You could try doing an apt-cache search for “upnp server” if you want the practice in finding suitable packages, or I could tell you that the one you want is Mediatomb.  So sudo apt-get install mediatomb

naich@raspberrypi ~ $ sudo apt-get install mediatomb
Reading package lists... Done
Building dependency tree 
Reading state information... Done
The following package was automatically installed and is no longer required:
 mtools
Use 'apt-get autoremove' to remove it.
The following extra packages will be installed:
 javascript-common libavcodec53 libavformat53 libavutil51 libdirac-encoder0
 libexif12 libffmpegthumbnailer4 libgsm1 libjs-prototype libmozjs185-1.0
 libmp3lame0 libmysqlclient16 libnspr4 libnspr4-0d libschroedinger-1.0-0
 libspeex1 libswscale2 libtag1-vanilla libtag1c2a libtheora0 libva1 libvpx1
 libx264-123 libxvidcore4 mediatomb-common mediatomb-daemon mysql-common
 wwwconfig-common
Suggested packages:
 apache2 httpd speex mysql-client postgresql-client
The following NEW packages will be installed:
 javascript-common libavcodec53 libavformat53 libavutil51 libdirac-encoder0
 libexif12 libffmpegthumbnailer4 libgsm1 libjs-prototype libmozjs185-1.0
 libmp3lame0 libmysqlclient16 libnspr4 libnspr4-0d libschroedinger-1.0-0
 libspeex1 libswscale2 libtag1-vanilla libtag1c2a libtheora0 libva1 libvpx1
 libx264-123 libxvidcore4 mediatomb mediatomb-common mediatomb-daemon
 mysql-common wwwconfig-common
0 upgraded, 29 newly installed, 0 to remove and 0 not upgraded.
Need to get 11.4 MB of archives.
After this operation, 25.2 MB of additional disk space will be used.
Do you want to continue [Y/n]?

It’s the same as when you installed Transmission.  Apt tells you what it is going to install and you say Yes.  It nips off, installs everything and sets it up.  It doesn’t need much configuring either.  It’ll work straight away but we’ll make a little adjustment or two.  Or three if you own a Samsung TV.  Our Samsung TV could connect to the server OK but wouldn’t play the videos.  If you have the same problem, the fix for it is here.  Read what it says and add the lines to the config file after you have made the following changes:

The configuration file for Mediatomb is /etc/mediatomb/config.xml (note that it’s in /etc, as usual) and is a bit unusual in that it’s an XML file.  Let’s not pussyfoot around here.  XML is a horrible way to present data and to use it in a configuration file is a crime against humanity.  I could rant on for a while but I will spare you that – you have enough problems, being faced with a configuration file in XML format.  So, open it up with sudo nano /etc/mediatomb/config.xml and let’s get started.  As you can see, it’s nice and easy to read – if you are a robot…

<?xml version="1.0" encoding="UTF-8"?>
<config version="2" xmlns="http://mediatomb.cc/config/2" xmlns:xsi="http://www.$
     Read /usr/share/doc/mediatomb-common/README.gz section 6 for more
     information on creating and using config.xml configration files.
    -->
  <server>
    <ui enabled="yes" show-tooltips="yes">
      <accounts enabled="yes" session-timeout="30">
        <account user="mediatomb" password="mediatomb"/>
      </accounts>
    </ui>
    <name>MediaTomb</name>
... and so on ...

Straight away, you should see something that needs changing.  The user interface web page has a default username and password, which is bad.  Change that user=”mediatomb” password=”mediatomb” to something else.  Or, if you are feeling brave, you can change “accounts enabled” to “no” and you won’t have to log on at all. This is a bad idea if you want to access it from outside your home network.

On the line after “<server>” add <port>49152</port> this forces it to use that port rather than pick one of its own choosing.  Done that?  CTRL-X, [Y]es you want to save, return to save it over the top of the original.

I’ve set up a download of a config.xml file with all those changes applied to it.  Feel free to replace yours with it.  The username is “mediatomb”, password is “wibble”.  Please change them on your system.

A quick sudo service mediatomb restart and you are done with the setting up.  To use the web interface, point your browser at http://your_pi_ip:49152 , log in (if you have to) and you should see this:

or something like that anyway.  To get it to index your media, click on the “Filesystem” tab (next to “Database”), then the cross next to “mnt” (to expand that branch) and “downloads” to highlight it.  Over on the right, there will appear a swirly cross which says “Add as autoscan dir” when you hover over it.  Click on it to select that directory as one you want Mediatomb to scan.  Choose “Inotify” for Scan mode, “Basic” for Initial scan and check “Recursive”.  Click on “Set”, it will perform a basic scan and then when you click on the “Database” tab on the left, all your stuff should appear under the “Video” branch.  Documentation for the user interface is available for those who want to tinker.

And that’s it.  Your Pi should appear  as  a media server when your TV/PS3/whatever does a scan.  Any new downloads should appear automatically but be aware that if you swap the external storage, it might not be rescanned when you plug it back in, so you will have get Mediatomb to do it manually.

Put the kettle on, make a cup of tea and enjoy your videos.  That’s pretty much it for now.  There’s one more chapter of useful things to know about Linux.

Continued here.

Memory sticks and torrents

Continued from here.

First page here.

9. Thanks for the memories

For this chapter you’ll need a memory stick or a pre-formatted external hard drive with a USB connection.  As we are going to be putting videos on it, the larger the better.  Got one?  Good.  Stuff it up your Pi’s USB port.  There should be whirrings and flashings (subject to lights or motors being present) as something happens. If we were using Windows, the external storage would appear as a drive letter.  Linux, however, lets you choose where to make it appear.  Linux has a single directory tree under which external storage and internal storage is placed, or “mounted” in Linux terminology.  Remember when I said to change the “Download to: ” directory setting in Transmission to /mnt/downloads”?  That’s where we will be mounting your external storage.  You might have questions at this point, but let’s get your external storage mounted before we come to them. A while ago I was blethering on about how bad it was to be root and how it was a good idea that you couldn’t log in as root.  Yes, well, I was probably slightly exaggerating to reinforce a point.  Sometimes you have to do lots of stuff as root and all that sudoing starts getting boring.  You can make yourself root until you exit, by doing sudo -s.  Try it:

naich@raspberrypi ~ $ sudo -s
root@raspberrypi:/home/naich#

Notice a few things here – the “$” has changed to “‘#” to indicate you are now root, the “~” has changed to “/home/your_name because it is no longer your home directory and you are now “root@raspberrypi”.  You now have absolute power over the entire operating system.  Let it go to your head for a while, cackle like Emperor Palpatine and let the hate flow through you. I like to do this occasionally when I become root and I find it best get it out of my system before I do anything else.  Back to normal again?  Good. First we need to create the directory to mount the external storage on.  The mount location has to already exist in order to mount something on it.  Type in the commands in bold:

root@raspberrypi:/home/naich# cd /mnt
root@raspberrypi:/mnt# ls -l
total 0
root@raspberrypi:/mnt# mkdir downloads
root@raspberrypi:/mnt# ls -l
total 4
drwxr-xr-x 2 root root 4096 Aug 21 13:24 downloads
root@raspberrypi:/mnt#

You change your working directory to /mnt (this is traditionally where you mount things), see what is already there (nothing), create a directory called “downloads” with “mkdir” and then you list it. Quick aside here – see that “drwxr-xr-x” bit?  That shows you what sort of file it is (“d” means directory) and the permissions for it, showing who is allowed to do what to it.  Read the this page up to and including section 2.1.1to understand permissions or try and battle through my very short explanation here:

There are 3 lots of “rwx”s, the first for the owner of the file, the second for the specified group (it is the second “root” in the illustration above, shown here in italics) and the third is for “others”, i.e. everyone else who is not the owner or a member of the group.  In each “rwx”, “r” means “read”, “w” means “write” and “x” means “execute” if it is a program or “enter” if it is a directory.  A dash (“-“) means a lack of permission for that function, so in the above example, the first 3 letters after “d” (“rwx”) mean the owner (root) can “r”ead, “w”rite and “x”enter the directory.  A member of the “root” group (the next 3 letters) can “r”ead and “x”enter the directory but not “w”rite any files to it, as the “w” is missing.  The same “r-x” permissions apply to everyone else, as shown in the last 3 letters.

Now we need to find the external storage.  The Linux kernal (the core of the operating system) will have interrogated your external storage to find out what it was when you plugged it in, and then set it up as a block device, making it available in the /dev directory as if it were a file.  As it is, it is an interface that you can read and write to it but not in any way that is useful to you.  It is now up to you to mount that block device on the filesystem so you can treat it as a branch on the directory tree.  Have a look in /dev and you’ll see a whole load of files that are interfaces to devices.  One of those files is your external storage, but which one?  There are a few ways to find it, but the easiest is with the command fdisk -l:

root@raspberrypi:/mnt# fdisk -l

Disk /dev/mmcblk0: 3965 MB, 3965190144 bytes
4 heads, 16 sectors/track, 121008 cylinders, total 7744512 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x000714e9

        Device Boot      Start         End      Blocks   Id  System
/dev/mmcblk0p1            8192      122879       57344    c  W95 FAT32 (LBA)
/dev/mmcblk0p2          122880     7744511     3810816   83  Linux

Disk /dev/sda: 8019 MB, 8019509248 bytes
20 heads, 16 sectors/track, 48947 cylinders, total 15663104 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x665e2cdf

   Device Boot      Start         End      Blocks   Id  System
/dev/sda1   *          80    15663103     7831512    b  W95 FAT32
root@raspberrypi:/mnt#

There’s a lot of information there, but the important bits are where it says “Disk /dev/…”, showing the size of the hardware and the column under “Device” which shows the names of the block devices each partition has been assigned. “Disk /dev/mmcblk0” is the SD card – see how it is split into two partitions, one large (3810816 blocks, each block being 1K making it about 3.8GB) and one small (57344 blocks)?  The other “Disk” (it will probably be “/dev/sda”) is your external storage, with its single partition appearing as “/dev/sda<number>”.  In my case it’s “sda1 “and 8019 MB big – it’s an 8GB memory stick with its partition having 7831512 1K blocks.  Yours might have a different number – “sda4”, for example, in which case use that rather than “sda1”.  Now let’s mount the /dev/sda1 device to /mnt/downloads with mount /dev/sda1 /mnt/downloads:

root@raspberrypi:/mnt# mount /dev/sda1 /mnt/downloads
root@raspberrypi:/mnt# ls -l downloads
total 188
drwxr-xr-x 3 root root   4096 Jul 12 17:07 Acad Course
-rwxr-xr-x 1 root root 181574 Jul 12 16:44 Chamber Assembly.wmv
drwxr-xr-x 2 root root   4096 Aug 15 19:31 vids
root@raspberrypi:/mnt#

The contents of the memory stick may vary.  Note how the owner and group are “root”?  That is because it was root who mounted the device.  Now we know it works, we can make it so the drive is automatically mounted at boot time, writeable by the user “debian-transmission”, who runs the transmission-daemon program. We need to find out his user ID and group ID though – type id -u debian-transmission and make a note of the user ID:

root@raspberrypi:/mnt# id -u debian-transmission
106
root@raspberrypi:/mnt#

It’s 106 for me.  Then do the same for the group ID with id -g debian-transmission and make a note of that number – 109 for me. We need to unmount it before we remount it for real.  This is the equivalent of safely removing it – unwritten data will be flushed and no more can be sent to it.  The command is umount /mnt/downloads – that’s umount, not unmount.  If you are doing this as a normal user later on, remember to sudo the command.

root@raspberrypi:/mnt# umount /mnt/downloads/
root@raspberrypi:/mnt# ls -l downloads/
total 0
root@raspberrypi:/mnt#

Never remove a storage device without unmounting it first.  If you do, a boxing glove on a spring will shoot out of the top of your Pi and punch you in the nose.  Well, it should.  You can lose data and corrupt the file system by yanking it out without unmounting.  You might also be wondering what would happen to anything that was already in the /mnt/downloads directory when your device was mounted.  The contents are preserved but are not accessible while the device is mounted over the top of them.

Now let’s automate the mounting of the external storage.  At boot time the file /etc/fstab is read to see what needs to be mounted.  Edit that file now with nano /etc/fstab and you will see this:

proc            /proc           proc    defaults          0       0
/dev/mmcblk0p1  /boot           vfat    defaults          0       0
/dev/mmcblk0p2  /               ext4    defaults,noatime  0       0
# a swapfile is not a swap partition, so no using swapon|off from here on, use $

Any line starting with “#” is a comment for the benefit of humans and ignored by the computer.  This goes for most configuration files.  Have a guess at what the first two columns are.  If you are really keen, try reading the man page for fstab with man fstab. The first is the block device name, the second is where it is mounted, the third is what sort of filesystem it is and the fourth is options.   The other two are used for maintenance and can be left out or set to 0.  You will want to add this line at the end in order to automatically mount your external storage:

/dev/sda1       /mnt/downloads  auto    defaults,uid=106,gid=109  0       0

Replace the “uid=106” and “gid=109” with the numbers you found earlier for user ID and group ID.  Save and exit with CTRL-X and then answering “Y” and hit return to save it with the same file name. Now mount the drive with mount -a. This mounts all the devices in /etc/fstab in the same manner as if it was booting up. Finally, check everything is hunky-dory:

root@raspberrypi:/mnt# mount -a
root@raspberrypi:/mnt# ls -l total 4
drwxr-xr-x 4 debian-transmission debian-transmission 4096 Jan  1  1970 downloads

Smashing.  I should also point out that Linux distributions like Ubuntu do all this automatically, popping up a file manager window showing the contents of the memory stick as soon as it is plugged in.  But we are operating at a lower level than that.

Now stop being root by tying exit:

root@raspberrypi:/mnt# exit
exit
naich@raspberrypi ~ $

Now we are back to normal.  You can stop cackling.  Your Pi is set up to mount the memory stick whenever it boots, so you don’t need to do anything else other than remember to sudo umount /mnt/downloads if you take the stick out and sudo mount -a when you put it back in.

10. Torrent something!

Now open up the Transmission web interface by pointing your browser at http://your_pi_ip_address:9091 and click on the “Open” icon.  Put this URL for a perfectly legal video torent in it:

http://www.frostclick.com/torrents/video/animation/Big_Buck_Bunny_1080p_surround_frostclick.com_frostwire.com.torrent

Put it in the “URL” box and click open.  Magnet links also work in this box. If you have found a Magnet link from a perfectly respectable web site, right click and choose “copy link location” and paste it into the “URL” box in Transmission.  If you have downloaded the .torrent file, upload it to Transmission.

You can check on the status of the torrent by clicking on it and then clicking the “i” icon for more info on it.  I got a “unregistered torrent” error, but DHT found enough peers to get it all.

Sometimes, with a popular torrent with lots of fast peers, the poor little Pi can get a bit overwhelmed with all the traffic hammering its ports.  It’s like a DOS attack and can bring down the Pi if it is bad enough.  So I like to limit the number of connections by going to the web panel, opening up settings by clicking on the spanner, going to the “Peers” tab and setting a limit of 20 peers per torrent and 100 peers overall.  I also set speed limits of 400kB/s for up and downloads in the “Speed” tab.

If you are having trouble connecting to any peers, make sure that “Use port forwarding from my router” is checked in “Network” tab of the settings.  This page gives some more info about setting up your router.  If your internet connection is fast you should have a high definition video file on your memory stick before you know it.  I’ll leave you to find out more about how Transmission works by the age-old method of clicking things to see what happens.

Most tellies these days have USB ports on them which you can lob a stick into.  If yours does, unmount and lob your stick.  Our telly also has an ethernet port on it, for streaming video from a uPNP media server.  Wouldn’t it be good to have a uPNP video server on the Pi?  I think we could probably manage that in the next chapter.

Continued here…

Torrents of Pi

Continued from here

First page here

8.  Installing a Bittorrent Client

I don’t know about you, but I want to install a Bittorrent client on your Pi, and I’ll tell you why.  If your PC uses a wireless router and you use Bittorrent, you will probably find that the Bittorrent traffic over your network utterly clobbers your PC’s connection, making the internet virtually unusable.  You also have to leave your PC on overnight when downloading large files, like Linux distributions or the many legal video torrents that exist.  Furthermore, once your torrent has finished, you have to leave the bandwidth-hogging Bittorrent program running in order to get any sort of honourable ratio.

Running a Bittorrent client on your Pi, plugged directly into the router, solves all these problems.  In fact, the whole setup is so unobtrusive that I’ve occasionally forgotten I’ve been seeding something and discovered I’ve worked up an enormous ratio.  Fnar fnar.  Sorry.  It also allows something else – you can log into your bittorrent client from any PC, even from outside your home network.  Say you are at work, browsing around at lunchtime, when you remember there is a perfectly legal film you want to watch this evening.  Logging in from your work’s PC, you can tell your Pi to start downloading it and by the time you get home, your film will be waiting for you.

So let’s find a Bittorrent client to install.  Shall we fire up Google?  No.  We don’t need to do that.  We can search the repository for Bittorrent clients using the “apt-cache” command like this: apt-cache search bittorrent client.  Note that you don’t need to sudo it because you aren’t installing anything yet.  The “apt-cache search” bit searches for whatever you put after it.

naich@raspberrypi ~ $ apt-cache search bittorrent client
apt-transport-debtorrent - an APT transport for communicating with DebTorrent
aria2 - High speed download utility
azureus - BitTorrent client
... loads and loads and loads ...
transmission - lightweight BitTorrent client
transmission-cli - lightweight BitTorrent client (command line programs)
transmission-common - lightweight BitTorrent client (common files)
transmission-daemon - lightweight BitTorrent client (daemon)
transmission-dbg - lightweight BitTorrent client (debug symbols)
transmission-gtk - lightweight BitTorrent client (GTK interface)
transmission-qt - lightweight BitTorrent client (Qt interface)
unworkable - efficient, simple and secure bittorrent client
vuze - Multimedia BitTorrent client
naich@raspberrypi ~ $

Spoiled for choice, aren’t we?  What we want is one that will happily do its own thing without any input from a human and doesn’t need a GUI.  In Linux, a program that runs in the background without requiring human interaction is called a “daemon”.  If you take a look at the list, two packages fit the bill – “deluged” and “transmission-daemon”.  We’ll use the latter.  Let’s download it, install it, set it up, and run it with 4 words: sudo apt-get install transmission-daemon.

naich@raspberrypi ~ $ sudo apt-get install transmission-daemon
Reading package lists... Done
Building dependency tree 
Reading state information... Done
The following extra packages will be installed:
 libcurl3-gnutls libminiupnpc5 libnatpmp1 minissdpd transmission-cli
 transmission-common
Suggested packages:
 natpmp-utils transmission-gtk
The following NEW packages will be installed:
 libcurl3-gnutls libminiupnpc5 libnatpmp1 minissdpd transmission-cli
 transmission-common transmission-daemon
0 upgraded, 7 newly installed, 0 to remove and 0 not upgraded.
Need to get 1,905 kB of archives.
After this operation, 4,173 kB of additional disk space will be used.
Do you want to continue [Y/n]?

Do you see all those dependencies that will be installed as well?  Apt is also suggesting other packages that aren’t needed but might be useful.  You want to continue.  Things going up the screen…  Done yet?  Did you notice this line?

[ ok ] Starting bittorrent daemon: transmission-daemon.

You are now running your bittorrent client.  It will automatically start up every time your Pi starts, so you don’t even have to remember to restart it when you reboot.  Isn’t that nice?  Come on – that is pretty cool isn’t it?

So let’s use it.  Transmission comes with a built in web server to use as an interface.  You use it by putting this into your browser: “http://your_pi’s_ip_address:9091″  – that’s a colon and 9091 after the address, no slashes.  You should see this:

403: Forbidden

Unauthorized IP Address.
Either disable the IP address whitelist or add your address to it.
If you’re editing settings.json, see the ‘rpc-whitelist’ and ‘rpc-whitelist-enabled’ entries.
If you’re still using ACLs, use a whitelist instead. See the transmission-daemon manpage for details.

This is correct.  As a general rule, installed packages will be set up in a safe way, so that nasty people (including you) can’t use it.  You will need to edit the configuration file to relax its security enough that you can use it.  Full instructions on how to do it are here: https://trac.transmissionbt.com/wiki/EditConfigFiles  but let’s just get it going quickly for now.  Transmission is a bit unusual in that it overwrites its configuration files when it exits.  This isn’t normal and caused me much confusion for a while because I’d edit the configuration, restart Transmission and it wouldn’t work because all my changes were overwritten.  So let’s stop Transmission before we edit the file with sudo service transmission-daemon stop:

naich@raspberrypi ~ $ sudo service transmission-daemon stop
[ ok ] Stopping bittorrent daemon: transmission-daemon.
naich@raspberrypi ~ $

You can probably work out what is going on there.  Now edit the configuration file.  It’s in the “/etc” directory, (along with all the other configuration files), in its own directory.  If you want to find a configuration file for a daemon, look in “/etc” – it’ll be there, either in its own directory or as a file.  Type sudo nano /etc/transmission-daemon/settings.json:

naich@raspberrypi ~ $ sudo nano /etc/transmission-daemon/settings.json

Now, move the cursor down until you find this part (without the numbers):

1 "rpc-authentication-required": true,
  "rpc-bind-address": "0.0.0.0",
  "rpc-enabled": true,
2 "rpc-password": "{1669ab9b7fdadc2a8a910abf75a60f6c584365e6oRs3weiW",
  "rpc-port": 9091,
  "rpc-url": "/transmission/",
3 "rpc-username": "transmission",
4 "rpc-whitelist": "127.0.0.1",
5 "rpc-whitelist-enabled": true,

“rpc” means “Remote Procedure Call” and refers to the web server.  Seems a bit odd to call it this as RPCs are generally from computers rather than humans, but what do I know?   When you make changes, make sure you preserve the punctuation: the quotes, colons and commas all need to be in their correct places.  Going through the numbers, leave the unmarked lines alone and change these ones to suit your preferred method of access:

  1. If this is “true” (note that there are no quotes round the word in the config file) then you will be asked for a username and password before you can use the web pages.
  2. This is the password you log in with if 1. is set to “true”.  The default is an impossible-to-guess huge random string.
  3. The username you log in with if 1. is set to “true”.  Default is “transmission” and you should change it if you plan to use a username/password – default usernames are bad.
  4. The comma-separated list of IP addresses that are allowed to use the web page.  A “*” means any number.  If your home network has addresses that all start “192.168…” then you could make this string “127.0.0.1,192.168.*.*” to make sure that only people in your home network can log in.  Leave the “127.0.0.1” in there, as this refers to the Pi itself.
  5. If you set this to “false” then 4 is ignored and anyone can connect from any PC.

I’d recommend either:

  • Set 1 to “false”, 5 to “true” and make sure that any PC you will access it from is included in the list at 4 or
  • Set 1 to “true”, set the name/password in 2/3 and set 5. to “false”

The first one doesn’t require a password, but you will be restricted to logging in from only the PCs whose IP numbers are specifically set in 4.  The second allows you to access it from any PC in the world (make sure you set your router’s port forwarding so connections to port 9091 are sent to your Pi’s IP), but you need to have a username/password to stop any Tom, Richard or Harry using it.

Then start it up again with  sudo service transmission-daemon start:

naich@raspberrypi ~ $ sudo service transmission-daemon start
[ ok ] Starting bittorrent daemon: transmission-daemon.
naich@raspberrypi ~ $

Point your web browser at http://your_pi’s_address:9091 and you should see something like this:

But probably not as squished.  I wanted to get all the icons in the screenshot.  But let’s not wander away from the point that you now have a working Bittorrent client on your Pi.  Give yourself a pat on the back and put the kettle on for a celebratory cup of tea.

But there is a slight problem.  Click on the spanner and look at “Download to:” to see where your torrents will be put.  It’s something like “/var/lib/transmission-daemon/download/buried/so/deep/youll/never/find/it/again/”.  Wouldn’t it be better to have it somewhere a bit more memorable, maybe even on a memory stick so you could take it out of your Pi and take it with you?  We can do both.  Change the “Download to: ” location to /mnt/downloads and continue to the next chapter, where we’ll be setting it all up…

Continued here.

Keeping it up to date (given up with the Pi puns)

Continuing from here

First page here

7.  Updating your system

We’ve just got a spot of housekeeping to do before installing some stuff to turn your pi into something useful.  We are going to do a system update to make sure we are running the latest version of everything.  And I mean everything.  The update will not only update the operating system, but all your installed software.  All your Pi’s software comes from a “repository” on the internet of pre-compiled software packages, created by the people who made the Raspbian distribution – over 35,000 packages in total, covering pretty much anything you might want your Pi to do: web server, media server, media streamer, torrent client, DNS, web browser (yes, a text only web browser) and so on.  Each package contains software, configuration files, manual pages, and scripts needed to set the software up after install.  You can install packages from outside the repository or compile your own software, but that is a bit more advanced and everything we need is included in the Raspbian repository.

Software is maintained on a your Pi’s Debian-based Linux system, Raspbian, with a set of utilities called Apt, which is short for “Advanced Package Tool”.  It keeps a track of all the installed software packages, what version they are, if they need updating, and other packages required by each package.  That last one is important.  Most packages will rely on other packages being installed on your Pi in order to work.  From a programmer’s point of view, there is no point in re-inventing the wheel if you want a feature in your program (let’s call your program “Program A”) that has already been created by someone else in Program B.  The programmer can tell program A to call up Program B when this feature is needed.  Then, when the repository maintainer creates Program A’s package for the Raspbian repository, the maintainer adds a specification to the package that tells Apt to check that the package containing Program B is already installed on the Pi.  If it is then that’s fine and dandy, but if it’s not, Apt will nip off and download Program B’s package too.  Of course, it then has to check if the Program B’s package needs any other packages to be installed on the Pi, download them if they aren’t installed, check those ones…, and so on until all the packages are happy.  Keeping track of all these interlinking packages, each depending on the other (package B is called a “dependency” of package A), would be a nightmare to do yourself, so thank goodness for Apt, which does it all for you.

You might think that it sounds a bit complicated, but it’s not.  You will soon see how easy it all is to use.  Then you might start feeling sorry for Windows users and the pain they have to go through – finding the software, downloading it (Windows downloads are usually bigger as they don’t have Linux’s dependency system), going through the install procedure and then finding that the installer just splatted a load of crapware all over their PC.  Do not pity them though.  They have chosen their path.  It’s quite similar (and predates by many years) the “App” system used by Apple, Android etc., except it is far more flexible and doesn’t restrict you to one source of packages.

But back to the updating… Let’s start off by getting a list of software that needs updating.  Type sudo apt-get update and you should see something like this:

naich@raspberrypi ~ $ sudo apt-get update 
Get:1 http://mirrordirector.raspbian.org wheezy InRelease [12.5 kB] 
Get:2 http://archive.raspberrypi.org wheezy InRelease [7,698 B] 
Get:3 http://mirrordirector.raspbian.org wheezy/main armhf Packages [7,296 kB] 
... and so on for a bit... 
Ign http://mirrordirector.raspbian.org wheezy/rpi Translation-en 
Fetched 7,388 kB in 48s (151 kB/s) 
Reading package lists... Done 
naich@raspberrypi ~ $

Lovely jubbly.  It’s got a list of all the latest packages.  Let’s process all the packages that need upgrading to a later version.  Type sudo apt-get upgrade:

naich@raspberrypi ~ $ sudo apt-get upgrade 
Reading package lists... Done 
Building dependency tree Reading state information... Done 

The following packages will be upgraded: 
bash dictionaries-common file idle3 krb5-locales libgssapi-krb5-2 
libk5crypto3 libkrb5-3 libkrb5support0 liblapack3 liblapack3gf 
libmagic1 libpulse0 libsystemd-login0 libtiff4 libxapian-dev libxapian22 
libxml2 libxml2-dev libxslt1-dev libxslt1.1 nfs-common omxplayer 
python3 python3-minimal tasksel tasksel-data udisks vim-common vim-tiny 
xserver-common xserver-xorg-core 

32 upgraded, 0 newly installed, 0 to remove and 0 not upgraded. 
Need to get 23.0 MB of archives. 
After this operation, 1,183 kB of additional disk space will be used. 
Do you want to continue [Y/n]?

Do you want to continue?  You do.  And away it goes, upgrading it’s little silicon heart out.  Very rarely, you might see something like this:

Configuration file `/etc/skel/.bashrc'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
 What would you like to do about it ? Your options are:
 Y or I : install the package maintainer's version
 N or O : keep your currently-installed version
 D : show the differences between the versions
 Z : start a shell to examine the situation
 The default action is to keep your current version.
*** .bashrc (Y/I/N/O/D/Z) [default=N] ?

This means that Apt has found a configuration file that been changed since the package was installed.  Unless you have made the change yourself, it’s safest to choose “Y” to install the new version which will be compatible with the updated software. A backup of the old config file will be saved in case the new one doesn’t work so you can examine them later to see the differences and fix them if necessary.

Warnings can generally be ignored.  Things like this probably don’t mean much to you:

insserv: warning: current start runlevel(s) (empty) of script `nfs-common' overwrites defaults (2 3 4 5 S).
insserv: warning: current stop runlevel(s) (0 1 2 3 4 5 6 S) of script `nfs-common' overwrites defaults (0 1 6).

And to be honest it doesn’t mean that much to me either.  It looks like it’s saying that the nfs server isn’t automatically started on runlevels 2-5 any more.  Possibly.  We aren’t using nfs so we don’t care; we’ll cross that bridge if we come to it.  My Pi seemed to work OK after those warnings, so I didn’t worry about them.  Make a note of warnings, just in case you need to find a problem later, but don’t worry about them unduly.  “warning: ” means something unexpected has happened but Apt can keep going.  Errors, however, can’t be ignored.  “error: ” means something so bad has happened that Apt can’t continue.  If you ever see an error, the best thing to do is to copy and paste it into Google to find someone else who has had the same problem and has hopefully fixed it.

You want to go through this procedure (“apt-get update” followed by “apt-get upgrade”) every now and again to make sure your system is up to date.  Most updates are due to bugs regarding security and are closing avenues of attack for hackers, so you want to install them.  I do it about once a week.

There is also another type of upgrade – apt-get dist-upgrade. This upgrades your system to the latest stable release.  This means that it won’t just upgrade your packages for bug fixes and security patches, it will upgrade all your software to the version included in the current stable release of your distribution, as if you downloaded and installed it from scratch.  This is a more serious upgrade and should only be undertaken if you’ve got a bit of spare time to fix anything that might get broken.  You are likely to see those messages about the configuration files and might have to edit upgraded ones to get things working again.  If you start seeing messages during your “apt-get upgrade” that packages have been “held back”, it means that you should probably start thinking about doing a “dist-upgrade”.

Continued here…