Raspberry Pi How-To: Basic Networking

This guide is intended to give you a basic guide to getting your R-Pi connected to a local network, configuring it to access services on that local network, and also to act as a server in it's own right where appropriate. It is assumed that if you have a local network, you already know enough about TCP/IP to know whether you have a DHCP server, and what IP address and subnet masks are and how they work.

The physical connection of your R-Pi to your local network can take one of two forms. Wired, or wireless. Both methods have advantages and disadvantages, but as a general rule of thumb, always use a wired connection where possible. Generally speaking, it will be faster. It will always be more secure. And it also leaves one of your USB ports free for other things. Of course, if you have a Model A R-Pi, the choice will be made for you - it will have to be wireless.

This is easy. Get a straight-through ethernet cable (cat-5 is adequate) and connect it from the ethernet port to a spare port on your hub/router. In theory, this cable can be up to 100M long. The only environmental concern here is that you don't run the cable too close to any source of electro-magnetic interference - being an electrical interface, any EMI can induce currents in the cores of the ethernet cable, which at best will give you an unreliable connection.

This is slightly more complex. As the R-Pi comes with no onboard wireless capability, you need to do it through the USB port. The device used to do this is commonly called a dongle, which is the convention I'll stick with here. There are many dongles available, and tested ones are constantly being added to at the e-linux R-Pi wiki. For this article, however, we'll be using the Tenda Wireless-N150 USB Network Adapter.

Firstly, we need to install the driver. But before we can do this, check that your /etc/apt/sources.list file contains a 'non-free' component:

root@raspberrypi:~# grep non-free /etc/apt/sources.list
deb http://ftp.uk.debian.org/debian/ squeeze main non-free

If not, you'll need to add it. In this example, I'm using the uk mirror (ftp.uk.debian.org). You may need to change this to your local country.

Once this is done, install the drivers:

root@raspberrypi:/etc/apt# apt-get install firmware-ralink

(Please note in the above two samples I'm logged on as root. This is purely to avoid having to keep typing “sudo” at the beginning of every command. Logging on as root is bad practise, and should be avoided really. I'm just being lazy. And if I enter 'rm -rf /*' then it's entirely my fault, and I can't complain to anyone).

Now that the driver is installed, plug the dongle into a spare USB slot. You should then be able to query it with the lsusb command:

root@raspberrypi:/etc/apt# lsusb
Bus 001 Device 005: ID 148f:3070 Ralink Technology, Corp. RT2870/RT3070 Wireless Adapter
<snip>

Now, use the dmesg command to check the system log. You should see something like this, among all sorts of other stuff:

<snip>
usb 1-1.3: new high speed USB device number 5 using dwc_otg
usb 1-1.3: New USB device found, idVendor=148f, idProduct=3070
usb 1-1.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 1-1.3: Product: 802.11 n WLAN
usb 1-1.3: Manufacturer: Ralink
usb 1-1.3: SerialNumber: 1.0
cfg80211: Calling CRDA to update world regulatory domain
usb 1-1.3: reset high speed USB device number 5 using dwc_otg
ieee80211 phy0: Selected rate control algorithm 'minstrel_ht'
Registered led device: rt2800usb-phy0::radio
Registered led device: rt2800usb-phy0::assoc
Registered led device: rt2800usb-phy0::quality
usbcore: registered new interface driver rt2800usb
<snip>

Cool. It's there. That's the tough part over with - the dongle is now recognised as a locally attached USB device. We can now move onto configuring it with an IP address.

The logical connection is simply the bit of TCP/IP configuration that you need to enable your R-Pi to talk to the rest of the devices on the network. In order to do this, you'll need to know whether you're using a static, or DHCP assigned address for your R-Pi. If you're using a static address, you need to know the following:

• IP address
• Subnet mask
• If you're going to be accessing networks other than your local network (including the Internet), your default gateway
• Broadcast address. Although this can be calculated from the IP address and subnet mask.

This is the default configuration, and as such, you shouldn't need to change anything. However, defaults change with time, so in order to make sure of things, you need to look in your /etc/network/interfaces file. It should look like this:

root@raspberrypi:/etc/network# cat interfaces
# Used by ifup(8) and ifdown(8). See the interfaces(5) manpage or
# /usr/share/doc/ifupdown/examples for more information.

auto lo
auto eth0

iface lo inet loopback
iface eth0 inet dhcp

The important thing to note is the settings for the eth0 interface. If you're using a USB dongle to give you a wifi connection, the interface name will change, to wlan0.

If you're using a static IP address, things get a little more complex. That said, if you're playing around with what is essentially a pre-production development device, this really shouldn't present too much of a technical challenge. Again, the details are in /etc/network/interfaces:

root@raspberrypi:/etc/network# cat interfaces
# Used by ifup(8) and ifdown(8). See the interfaces(5) manpage or
# /usr/share/doc/ifupdown/examples for more information.

auto lo
auto eth0

iface lo inet loopback
#iface eth0 inet dhcp
iface eth0 inet static
address 10.0.0.9
netmask 255.255.255.0
network 10.0.0.0
broadcast 10.0.0.255
gateway 10.0.0.2
up route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0

All of the above lines in the file should be self explanatory (with the exception of the last line, which is not strictly necessary, and I've only got it there for something legacy involving multicasting, which completely escapes me now.

The quick and dirty way to apply any changes that you make to this file is by simply restarting the networking services:

root@raspberrypi:/etc/network# /etc/init.d/networking restart
Running /etc/init.d/networking restart is deprecated because it may not enable again some interfaces ... (warning).
Reconfiguring network interfaces...done.

Be warned: If there are any interfaces that are not marked as auto in the interfaces file, but have been previously brought up manually (to be fair, this is extremely unlikely on a device with only one fixed network interface…) they will not be re-enabled with this method, and you'll need to use ifdown and ifup to bring them up again.

Depending on the type of encryption you have set up on your wireless access-point, you'll need to add some lines to your /etc/network/interfaces file. The simplest option is if you have an open access-point. If this is the case, add the following lines to the end of your /etc/network/interfaces file:

wireless-essid <your SSID>
wireless-mode managed

The sequencing of lines is critical - the authentication must go after the addressing, whether you're using DHCP or static addressing. If you're using WPA, then you'll need to enter something like this:

wpa-driver wext
wpa-ap-scan 1
wpa-proto WPA
wpa-pairwise TKIP
wpa-group TKIP
wpa-key-mgmt WPA-PSK
wpa-ssid <your SSID>
wpa-psk <your key>

To generate the key, use the wpa_passphrase command. This takes two parameters; your SSID and WPA key. Say, for example, your SSID is 'wireless' and your WPA key is 'password' you'll need to do this:

pi@raspberrypi:~$ wpa_passphrase wireless password
network={
	ssid="wireless"
	#psk="password"
	psk=f62419193b79abeee24eed0d63ace2d6b9b2a47bd081f5fd400add12fd187b0b
}

Grab the text in the 'psk' phrase, and use that as <your key> in your /etc/network/interfaces file.

If you're using WPA2, the config is the same as for WPA, but replace TKIP with CCMP:

wpa-driver wext
wpa-ap-scan 1
wpa-proto WPA
wpa-pairwise CCMP
wpa-group CCMP
wpa-key-mgmt WPA-PSK
wpa-ssid <your SSID>
wpa-psk <your key>

If you're using WEP, something like this will do the trick:

wireless-essid <your SSID>
wireless-key <your WEP key>

If all has gone well, bring the wlan0 interface down and up again with the ifdown and ifup commands. You should now see the interface associated with your access-point:

pi@raspberrypi:~$ iwconfig
lo        no wireless extensions.

eth0      no wireless extensions.

wlan0     IEEE 802.11bgn  ESSID:"SSID"  
          Mode:Managed  Frequency:2.412 GHz  Access Point: 00:23:F8:8D:EC:69   
          Bit Rate=54 Mb/s   Tx-Power=20 dBm   
          Retry  long limit:7   RTS thr:off   Fragment thr:off
          Power Management:on
          Link Quality=70/70  Signal level=-29 dBm  
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:0   Missed beacon:0

ifconfig should show you an IP address:

pi@raspberrypi:~$ ifconfig wlan0
wlan0     Link encap:Ethernet  HWaddr c8:3a:35:cc:7c:7f  
          inet addr:10.0.0.10  Bcast:10.0.0.255  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:1112 errors:0 dropped:0 overruns:0 frame:0
          TX packets:755 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:109377 (106.8 KiB)  TX bytes:117032 (114.2 KiB)

Finally, a ping to the access-point:

pi@raspberrypi:~$ ping 10.0.0.2
PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.
64 bytes from 10.0.0.2: icmp_req=1 ttl=254 time=1.88 ms
64 bytes from 10.0.0.2: icmp_req=2 ttl=254 time=6.05 ms
64 bytes from 10.0.0.2: icmp_req=3 ttl=254 time=5.59 ms
^C

shows that you've now got a physical, and logical connection, and all is well with the world. If not, check your typing carefully. It's very easy to make a mistake in the /etc/network/interfaces file, and everything is case sensitive, sensitive to white space, and sequencing.

If all this sounds complicated, well, it is - there's no getting away from it, that no matter how many plug&play protocols are invented, networking is a complicated subject. However, as always, an example can be dead helpful, so here is my /etc/network/interfaces file:

pi@raspberrypi:~$ cat /etc/network/interfaces 
# Used by ifup(8) and ifdown(8). See the interfaces(5) manpage or
# /usr/share/doc/ifupdown/examples for more information.

auto lo
#auto eth0
auto wlan0

iface lo inet loopback
#iface eth0 inet dhcp
#iface wlan0 inet dhcp

#iface eth0 inet static
#address 10.0.0.9
#netmask 255.255.255.0
#network 10.0.0.0
#broadcast 10.0.0.255
#gateway 10.0.0.2
#up route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0

iface wlan0 inet static
address 10.0.0.10
netmask 255.255.255.0
network 10.0.0.0
broadcast 10.0.0.255
gateway 10.0.0.2
up route add -net 224.0.0.0 netmask 240.0.0.0 dev wlan0

wpa-driver wext
wpa-ap-scan 1
wpa-proto WPA
wpa-pairwise TKIP
wpa-group TKIP
wpa-key-mgmt WPA-PSK
wpa-ssid <my SSID>
wpa-psk <my key>

As you can see, I have commented out the eth0 entries, as I am just using wireless on this machine. If I ever go back to using a wired connection, I just need to go in and uncomment the eth0 entries. Also, note the order of entries - the authentication section comes after the addressing section. This is vital.

If you have a small network, you can probably remember the IP addresses of each machine. Indeed, I find it easy to remember IP addresses, but frequently forget my wife's birthday. This probably says more about me than the size of my local network, but it's a cautionary tale. So, to get around this particular problem, you can assign names to each device in your network. Without doubt, the best, most flexible and extensible way to do this is to use DNS and BIND, and the O'Reilly guide to DNS and BIND is essential reading if you want to go down this route. However, for this article, we'll use static mappings rather than the distributed database method used by BIND. The file that you need to edit to tie an IP address to a hostname is /etc/hosts. By default, there's only going to be one IPv4 address defined here. The reserved hostname 'localhost' is bound to 127.0.0.1:

root@raspbian:~# cat /etc/hosts
127.0.0.1       localhost

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
ff02::3 ip6-allhosts

(we'll not worry about IPv6 here. It's unlikely that your local network has enough hosts to require it). The syntax should be obvious - just add a line for each host in the network in the format <address> <hostname>. As already stated, I seem to have an unfortunate ability to remember IPv4 addresses instead of genuinely useful information, so I don't have a practical example to show you. For the sake of explanation, it could look something like this:

<snip>
10.0.0.8 bungo
10.0.0.9 orinoco
10.0.0.10 tobermory
10.0.0.11 tomsk
<snip>

Always, remember you're a womble.

Now that you've got your R-Pi talking on the local network, one of the first things to do is to allow remote logins. There are several options here, but the one we're going to concentrate on SSH, as it's well supported, secure, and easy to set up. There are two parts to worry about here. The server, which will run on the R-Pi itself, and the client, which will run on the machine that you want to perform the remote login from.

This is included in the default distribution of Debian, and to enable it, you just need to rename one file, in the /boot directory:

sudo mv /boot/boot_enable_ssh.rc /boot/boot.rc

Once this is done, next time the R-Pi is rebooted, you should see something like this on startup:

Starting OpenBSD Secure Shell server: sshd

On the Raspian distro, you don't need to do anything - it's enabled by default.

So, now you've got your R-Pi running an SSH server, you need to connect to it. From another unix machine (another R-Pi for example if you're lucky enough to have two of them!) just use the SSH command from a command line:

ssh <user>@<nnn.nnn.nnn.nnn>

where <user> is the user ID that you want to login with (if this is omitted, the user ID that you used to log onto the local machine is assumed) and <nnn.nnn.nnn.nnn> is the IP address of the R-Pi that is running the server. If you're using a static IP address, this is easy, as it will never change. If you're using a DHCP server to obtain an IP address for the server, you need to know that that address is. ifconfig is your friend here:

root@raspbian:~# ifconfig
eth0      Link encap:Ethernet  HWaddr b8:27:eb:ab:14:98
          inet addr:10.0.0.8  Bcast:10.0.0.255  Mask:255.255.255.0
<snip>

From a Windows machine, you'll need an SSH client, as Windows doesn't ship with a command line SSH client. Putty is such a client, and works nicely. I won't go into details here of how to set it up, as there's plenty of help text with the package.

If you're using a Mac, I'm not totally sure really - it's been a while since I've used one. The last time I used a Mac I used something called Fugu, which may still be around, and worth investigating.

The R-Pi can be used to share files, or can access files that are shared by another machine in your network. What protocol you use for this depends on the mix of machines in your network and operating systems. Generally speaking, Windows machines speak SMB, unix machines speak NFS. Macs do something else entirely, and as mentioned above, this isn't my area of expertise, so I'll leave that subject for now.

Now, you'll probably have spotted the potential problem right away if you want to share files with Windows machines, or use files located on Windows servers - unix and Windows use different protocols. Luckily, there is a simple answer, and it's called Samba. This is a suite of programs that enable the R-Pi to speak SMB, and to administer these resources. If you're just going to use unix devices in your network, NFS will work nicely. If you have, or think that you ever will have, Windows machines in there too, you'll need Samba. So, without further ado…

If you're going to be a client:

sudo apt-get install cifs-utils

If you're going to be a server:

sudo apt-get install samba samba-doc swat

samba-doc and swat are optional - you only need swat if you want to administer your samba configuration via a web interface. I'm not going to go into details here of how to do this - there are many guides out there on setting up Samba already!

If you're going to be a client:

apt-get install nfs-common portmap

If you're going to be a server, well, it's not good news. The current kernel version doesn't support NFS, so there's no path here at the moment. This will, I'm sure change in future, so watch this space! There is a userspace NFS server option available at http://unfs3.sourceforge.net/ but until kernel support for NFS is built-in, it's probably best just to use Samba.

This is as simple as passing the '-t cifs' option to the mount command:

pi@raspberrypi:~$ sudo mount -t cifs //10.0.0.8/usbdisk /mnt/usbdisk

In this example, a share called 'usbdisk' is mounted from device 10.0.0.8 to mountpoint /mnt/usbdisk on the local machine. Please note, that in this example I have deliberately not gone into setting up any authentication - this is another topic entirely, and outside the scope of a simple networking how-to guide.

Using NFS to mount remote shares is as easy as using the mount command. As long as the server has the shares defined in the /etc/exports file, and the mountd process is allowed in the /etc/hosts.allow file

~/#mount -t nfs 10.0.0.8:/home /mnt/nfs/home

This will mount the share /home from machine 10.0.0.8 at the mountpoint /mnt/nfs/home. As with any file system, this can be mounted at boot time by editing the /etc/fstab file.

Once samba is installed, you need to modify the file /etc/samba/smb.conf, either using a text editor (vi is my particular favourite) or using swat and pointing a web browser at port 901 on the server. Again, I don't want to go into details here about the syntax and structure of the smb.conf file, as there are a lot of options, and plenty of good help text already out there.

As mentioned, NFS support currently isn't included in the Debian kernel, so for now, this isn't an option. Well, you can probably recompile the kernel with the NFS extensions built in, but if you're messing around with that kind of thing, you won't be reading a beginners guide to file sharing anyway.