Raspberry Pi Setup


This page describes the basic steps I take when setting up a Raspberry Pi for use on my model railroad, before doing any application-specific configurations. There are many, many, similar guides online, and many other ways to do this. I don’t claim this is the best, but it works for me. And for anyone trying to replicate what I’m doing with a Pi, this is a good place to start.


Versions


I use the Raspberry Pi model 2 B unless otherwise noted. And at present, I’m using the Raspbian operating system, version “Jessie”, as downloaded from the Raspberry Pi Foundation site.

Although the model 3 B has some nice features, like WiFi, it also presents some challenges. Some external hardware has compatibility issues, although I haven’t run into that with anything that I need for layout use, and these may simply be software library problems that will be fixed over time. And while it has more processing power, actually trying to use that will likely run into overheating problems. That’s not a big issues, since it will just slow down to compensate, but then you don’t have the added capacity. And I don’t want to be adding fans to Pi’s used on the layout. So, for now at least, my focus remains on the model 2, although that may change.

Note: I use the basic version of Raspbian Jessie, rather than NOOBS, because I know I'm only using Raspbian on my Pi and don't need the ability to load multiple operating systems, so I'm saving some space. But you can use either. As long as you end up booting up Raspbian, it doesn't matter how you got there. In fact, you don't even need to use Raspbian if you don't want to. There are other Linux's out there, and most are probably compatible with JMRI. But the instructions I've seen online are for Raspbian, and that is the official OS so it probably has the greatest compatibility with hardware, software and accessories, another reason I’m using it.

Fair warning: Because Jessie does things related to starting system-level programs very differently from the previous version (Wheezy), some of the older instructions on the net aren't correct for Jessie if you're trying to do other customizations. And some of what I describe here won't work on Wheezy.


Getting Started


When you start unboxing things, keep in mind that both the Pi and any add on “Hat” boards are sensitive electronic circuit boards. You don't need a grounded wrist-strap; this stuff is designed for kids to work with after all, so it's somewhat hardy. But it can’t hurt. At the least, take these basic precautions to avoid damage: Work on an insulated surface (a wooden table is good), avoid things that create static electricity (like fuzzy sweaters, or walking across carpet in socks) and handle the board by the edges to the extent you can. Putting the Pi in a protective case is also a good idea.

There are lots of online sites and videos describing initial setup, and places you can go for help. A good place to start is with either the official Quick Start Guide or AdaFruit's Getting Started tutorial. Note: despite comments about smaller cards, get at least an 8 GB card so you'll have plenty of room to work. A 4 GB card with the Jessie OS on it has very little free space left.

I use 16 GB microSDHC memory cards. Paying extra for faster cards won’t affect the Pi’s performance, as those speeds mainly apply to the kind of use made by cameras, and computers work differently. On the other hand, paying for a brand name may well be worth it in terms of reliability.

The AdaFruit tutorial has a lot of very useful detail for a new user about how to do things like load a downloaded image onto a memory card. I’m not going to repeat that here. I’m going to assume you have a card with the OS installed on it, either purchased or made yourself. I’ll also assume that you’ve maximized the partition size (but see the backup discussion below for more about sizing partitions) and have localized your keyboard (the default is UK, which works poorly with U.S. keyboards). These can all be done via “sudo raspi-config” from the command line and are usually covered in initial setup instructions.

Once you have a memory card, first you need to take the Raspberry Pi, hook up the keyboard, mouse and monitor, put in the memory card with the operating system, and plug in the power (never change the card with power connected!). This will boot it up to the login prompt. Enter the username “pi” (without the quotes) and password “raspberry”.

It is very important to shut down before unplugging power, and to unplug power before removing the memory card. Otherwise the card may become corrupt and you’d have to restore it from a backup. If for some reason you can’t shut down, wait for the green activity light (next to the red light near the memory card) to go out before unplugging the power.


Starting Up


Booting from a memory card will get you to either a command-line prompt or a desktop GUI screen (what you get depends on whose version of the OS you use). If you end up at the command line, type “startx” (without the quotes) to get to the GUI.

From the GUI, if you need to type command-line commands, click on the icon of a computer monitor on the left side of the top bar. That launches the terminal emulator (you can have more than one open to do different things). Commands entered there are done as your user (that's "pi" for now), unless you use the "sudo" command to give them extra abilities to modify the system. Don't use "sudo" unless you need to though; it has no checks on it to prevent it from modifying things that normally shouldn't be modified, so you can wipe out all your work with one careless command. Treat "sudo" commands like a power tool: pay close attention to what you're doing and don't rush and you'll be fine.

If you need to edit files, the usual way is to type the word "nano" followed by the file name (or the full file path) at a command line prompt. This is a "text editor", meaning that it edits the simple files used to configure computers, without any of the frills (like fonts, or type size) used in word processing. There's a very nice guide to how to use it on this site. To edit protected system files, use "sudo" in front of the command (e.g., "sudo nano /etc/iptables/rules.v4" is used to directly edit firewall rules if you have iptables-persistent installed and aren't using a front-end program like ufw to handle that). Think carefully before using "sudo nano", as most things you need that to edit are things you probably don't want to change lightly.

When you get a fresh image of the OS, it comes with one pre-configured username: "pi", which has the password "raspberry”, as you just used when logging in the first time. The first thing you should do is change the password to something 8-10 characters long that you can remember, by typing the "passwd" command at the command line or using the configuration menu. Write the new password down somewhere, but change it from the default.

I’ll talk more about security below, but it’s a good idea to take some basic precautions no matter how unlikely it is that anyone else would access your Pi, and changing the password is the most basic one.

Each time you start a Pi, the internal time-of-day/date clock will be wrong. This doesn’t really matter for most uses. If you have a network connection, it will eventually correct itself, but this takes a while. Pi’s do not have a hardware clock, so they do not track the current time when powered off. The current version does have a “fake hardware clock” software system that resets the time after a boot to the time of the last shutdown, so the clock may be close if the Pi was not powered off for an extended period.


Avoid the Temptation to Edit Everything


You can find a lot of guides online that tell you how to do things to “make it better” in one way or another. And it’s very tempting to try to apply these, both because it’s fun to make simple improvements and because it helps familiarize you with the way things work. But exercise self-restraint: does this “better” really mean anything to how you’ll use it? Any time you change something, you have to deal with two potential negatives: first, that the change may silently go away in some future system update, and second that it may get in the way of some future capability, and you’ll have a real headache figuring out why things don’t work when you’ve long since forgotten what you changed.

I’m an inveterate tinkerer, and I think I know “computers” fairly well, so I’ve managed to hurt myself this way on the Pi several times. I now keep a list of critical system files I’ve modified that I need to check after any update, and backup copies of my modified versions in a directory on the “pi” account, so I can compare files with “diff”. Of course when I find something changed, I then have to spend time determining if this change is compatible with my earlier change and I can merge the two into one copy of the file, or if I have to choose one or the other. I’m trying to reduce the number of modified files now…


Security Threats and Securing the Pi


A Pi needs a network connection to update software, and likely also to allow you to work on it once it’s installed on the layout. For the latter, you’ll need to enable remote access via SSH (it’s normally off by default). And this potentially makes the Pi vulnerable.

Now in a typical home network, nobody outside your home should be able to access a Pi inside because home Internet connections typically use Network Address Translation (NAT), and NAT prevents access unless you’ve taken steps to map external “ports” to internal devices. But this may not be true of all home network connections. Or someone else in your household may have done something that does make it accessible. And if you use Wi-Fi, there are many ways that can accidentally be made less secure.

WiFi is less secure than a user password. I’d recommend 12-14 characters for the WiFi password (the “previously shared key”), and even that could probably be broken by a highly motivated attacker, although the probability of that is low and 12 ought to be “secure enough” for most people today.

My general approach is to assume someone can access anything on my network, even though I think it’s well-protected. So I always change default passwords for usernames to something 8-10 characters long that won’t be easily guessed. That includes never using words that would appear in a dictionary, dates, or the names of characters from books, several common mistakes (all of those are found in many word lists used by would-be attackers). Adding in numbers or one or more punctuation symbols can help, but don’t use a word and change the letter “oh” to a zero, or “s” to a dollar sign. And don’t use a date, there are only 365 days in a year, and few years most people care about. Dates are much weaker than an equivalent number of arbitrary digits.

Lest you think I exaggerate the risk of weak user passwords: a Pi put on the network with a fixed address and running some services that make it more readily visible will sustain over 100,000 attempted logins per day (per one person who did just that). Another person noted that even after taking steps to make their accessible Pi less obvious, and blocking each new attack source after the first attack, they were still being accessed by one new attacker per day on average. There are a lot of automated systems out there trying to find computers to break into, so they can either steal useful information or use them as launching points for attacks on others (making you look like the source of the attack, rather than them).

You can, of course, run your Pi without a network connection after it is set up. That’s very secure. But it also makes it much harder to deal with any problems once the Pi is installed on the layout, and you can’t keep the clock accurate (that uses the network) or update software.

I’ll note below some of the things you can do to improve security, but these aren’t required for the Pi to work.


Network Connections and Initial Setup


During setup, you need an Ethernet connection for downloading software. You can use either the built in wired Ethernet, or add a wi-fi USB interface. The latter are really cheap (US$12 or so) and free on the model 3B, but setting them up takes a little work. Also, your wi-fi coverage may be poor in a Pi mounted underneath a layout, so while running wires may be a nuisance, it's probably worth the effort. Just get a small Ethernet switch for the layout room, wire the Pi's (and any local computer) to it, and run a wire from it to your Internet connection (most of those today have several interfaces for home systems).

If you want to use Wi-Fi, instructions are here.

Once the Pi is connected to the network, enter the two following commands at the command-line prompt to update your software with any recent bug fixes or other updates. The first time you run this it can take quite a while to download files.

sudo apt-get update
sudo apt-get upgrade


An alternative form of the second of those two is:

sudo apt-get dist-upgrade


The difference between “upgrade” and “dist-upgrade” is that the latter will apply more substantial changes, things that the Pi foundation puts out every few months that could change the behavior of the Pi. This can include new OS kernels that could break existing libraries, or new features affecting the user environment (the GUI changes of September 2016, for example). I normally use “upgrade”, but will do “dist-upgrade” once or twice a year, working on a test copy of the config for a specific Pi. In either case I never modify the running one, just in case something breaks, I use a copy on a second card and swap that into the Pi (or work on a test Pi on my desk if appropriate).

Either will stop part-way through and tell you what it's about to do. Type Y followed by return and wait for it to finish and display the command-line prompt.

Note: a number of online sites tell you to also type "sudo rpi-update". DO NOT DO THAT. It probably won't cause any trouble, but it downloads software that is still undergoing testing and may not be stable. It can be handy if you know you need something to fix a problem, but if you don't it's more likely to create a problem than fix one.

You can run these two commands again at any time to update the software. On the other hand, once you have things working, running them could update something that causes a problem, so you may want to stop doing updates once the Pi is working as desired.


Backup, Backup, Backup


No, really, once you have a working memory card, BACK IT UP!

In fact, back it up fairly often and keep a couple of backups in case one of them gets damaged. I do it at the end of every work session until I've got the configuration working the way I want it to, then I save the last one (or a couple) for future use.

SD memory cards can and do fail. I’ve had good ones used in cameras fail on me. Good ones don't fail often, but even the best will someday fail, and when it inevitably does all your hard work is gone if you didn't have a recent backup. Once you have a backup, you can write it to another card to create clones of the first Pi without going through all the work to make the whole thing from scratch (some customization of the new card will likely be needed).

How do you back it up? That depends if you have a Windows or Mac/Linux computer (under the covers, the Mac's Unix works much like Linux in some ways). What you need to do is create an "image" from the SD memory card. This requires another computer (you can't do it on the Pi) with an external SD-card reader. Note that the built-in readers on some Macs are known to have problems doing this, and shouldn't be used.

Here are instructions for Windows, Linux and Mac. I use a Mac, and the one caution is that the "dd" command will cheerfully destroy your Mac's operating system if you give it the wrong disk name (it's running sudo and there are no safety checks anywhere; it's not going to stop and ask "Are you sure?"). So, be really careful you know what you are typing before you press Enter (Return).

For Mac users there's a nice GUI application available that does this safely (well, I haven't tried it, but others like it): PiWriter (successor to an earlier program called PiCloner).

Actually, it is possible to write an image from the Pi itself; you'll still need a USB card reader though. This is really more complicated than using another computer, and I don't really recommend it (and I have not tried this method), but if you want to do it, there are instructions here.

The actual backup takes some time, around 20 minutes for a 16 MB card in my experience, but actual time will depend on the speed of your card reader and USB bus.

Restoring or duplicating a card will sometimes create a non-working card if the new card is slightly smaller than the old one (this happens with SD memory cards; they're never exactly the same size because of the way they work). Solving that problem is beyond this discussion, but it involves making the partition smaller using a linux utility called "gparted" (on another computer) or similar tools. Search if you need it, but there's some helpful information here (in particular see the section on Gparted Live).


Basic Remote Access and Securing SSH


I do recommend turning on SSH (but only after you change the Pi password), as that provides a way to work on the Pi from another computer if there's a problem or you want to update it. But you could always just shutdown and power off the Pi and move the memory card to a second Pi connected to a normal monitor.

SSH should be off by default, but is easily enabled just by selecting it in the Pi's configuration settings: Menu / Settings / Raspberry Pi Configuration in the GUI or "sudo raspi-config" from the command line. I prefer the command line, because sometimes changes made in the GUI configuration don't "stick".

With SSH you can get basic command-line access, but you can also set up a remote desktop application that will let you work on the Pi's GUI desktop from another computer.

With SSH there are several typical security enhancements you can make.

- Change the default "port" to something other than 22.
- Use certificates rather than passwords when logging in via SSH.
- Install fail2ban to block people trying to guess the password.

Changing the default port makes other things that need to access the Pi a bit more complicated, as you have to tell them the new port number. I don't make my Pi visible outside of my home, so I stick with the default port, but use the other precautions just in case. If you do plan to make a Pi externally visible, changing the port number will prevent a lot of failed login attempts by automated systems.

Some basic info on SSH is available from the Raspberry Pi Foundation, but for a tutorial on setting up and using SSH safely, see here (it's Mac/Linux-specific, but the Pi portion is the same for a Windows user, only the access commands differ; Windows users should download the Putty client to permit access via SSH; for information about that, as well as about how to use certificates on Windows, see this site).

Note: skip the "port forwarding" portion of the tutorial unless you want to make the Pi accessible from outside your home.

The default setting for fail2ban only bans a failed login attempt for 10 minutes. That’s enough to discourage automated systems, and to permit you to log in again soon if you typo your own password enough times to get banned. But if you are using certificates you won’t have to worry about typo’ing your own password, so you can make this longer.

You can test SSH by attempting to connect from another computer. If you’ve set up certificate-based access, the command to use (from a terminal window) is the same on both Mac and Linux (Windows users should use Putty as described at the link above):

ssh pi@192.168.0.xxx


This assumes you are connecting as user “pi” and the Pi’s address is 192.168.0.xxx.

If you changed the default port from 22 (let’s say to 2100), then the command to use is:

ssh -p 2100 pi@192.168.0.xxx




Remote Desktop


Once you have SSH working, you can set up the remote desktop software to allow remote access. This is surprisingly easy, and any modern computer supports accessing another computer remotely. On Windows you'll need to download a free VNC client, on Linux you have to install one package with a client, but on the Mac everything you need is built-in, although you can download a more user-friendly client if you wish (see below for details).

Note: as of September 2016 this section is somewhat obsolete. It will still work, but there’s now a standard VNC solution, so you should probably use that. I’ll leave this here for reference.

Note: you don’t have to use SSH, but it’s very good to do from a security perspective. Without it, sensitive information like passwords may be intercepted by another computer on the same network. And since it’s really easy to use, I always use it for remote access.

I use the tightvnc application on the Pi (there are others). First set up the VNC server on the Pi, following these instructions.

Although not mentioned in those instructions, you can also set one or two passwords on VNC using the “vncpasswd” command. Run this from the username being used for VNC (that’s configured in the init.d script and is “pi” in the example given at the link above, on the line “su - pi -c…”). It will prompt for two passwords, which must be at least 5 and at most 8 characters long. You only need to set the first one (the second one is a separate password if you only want some people to have read-only access).

Note that the example uses ":0" on the command. This is the "display number". The built-in display (HDMI or the touch-panel if you use that) is actually display 0, so when using VNC with a Pi that has one of those, you should use ":1" as the display number so you can have a separate remote display (you can also use 2 or whatever, but 1 is fine even if you have multiple remotely-accessed Pis). I always configure the VNC server as display 1 so I can move the memory card to a machine with a normal monitor for maintenance without any conflicts, so my examples will all assume display 1. Remember this display number, as we'll use it again.

To access it remotely, see these instructions for Windows or Linux. You can also get a remote viewer app for the Mac, which makes configuration simpler in some ways, but I prefer to do it using the built-in commands.

In all of these, use the display number (also called screen number) you put on the VNC server on the Pi (e.g., the ":1").

On the Mac, you can access VNC without downloading a viewer, just by typing an SSH command in a Terminal window and using a Finder menu. First go to the Utilities folder (inside Applications) and launch Terminal to get a command line window. Then enter the following command to set up an SSH link to the Pi:

ssh -N -L 5901:127.0.0.1:5901 pi@192.168.0.xxx


where 192.168.0.xxx is the address of your Pi. Notice the number 5901 written twice here? The first is a local screen identification. If you have more than one VNC connection active at a time, each will need a different number (e.g., 5901, 5902, etc). The second is the display number on the Pi added to 5900, so this should be 5901 for all of your Pis (assuming you used ":1" as described above). Also notice the "pi@" portion, that's the username on the Pi that we're connecting to. If you set up a separate account on the Pi, such as “jmri”, and want to connect to it, substitute that name here.

With the link created, use the Finder's "Go" menu and select "Connect to Server...", and in the Server address field enter the command:

vnc://localhost:5901


The 5901 here is the local one, not the one on the Pi, so if you used 5902 above, use that here. Now you should have a window open to the Pi's desktop.

One problem is that all of these commands use the Pi's address, but how do you know it? The Pi by default gets a fresh address every time it boots up. It may often be the same one, but you can't be certain. If you have a monitor on the Pi (including the touch panel if it is displaying the desktop) you can hover the mouse over the icon of two computers at the top right of the menu bar to see the current IP address of the Pi.

Another solution is to assign a static address (one that doesn't change). This requires some additional setup, but it makes remote management much easier. However, there are ways to locate and access a Pi using its name, and that’s preferable to use of a static address for most things.


SSH to Dynamically-Addressed Pi


First things first: I strongly recommend NOT using static addresses for your Pi. There are some exceptions, such as servers that need to be used from “dumb” devices that can’t use multicast DNS. And there may be times where it’s simpler to use static addressing. But in general static addressing of simple systems is “old school” networking, and something to avoid with modern systems.

Note: I’m about as old-school as you can get, I’ve been configuring things with static addresses for over three decades now. But times have changed, and while old habits die hard, I’m shifting to use dynamic addressing, because it comes with more flexible service discovery and less work to configure things, even if it is sometimes more complicated to set up initially.

By default, a Pi advertises its hostname (the one you configured in the setup menu) as a name in the “.local” domain using multicast DNS (also known as Zeroconf or Bonjour). As long as the client system supports this, you should be able to connect that way. In other words, if you gave your Pi the hostname of “ApplePi”, you could change “pi@192.168.0.xxx” in the example above to “pi@ApplePi.local”. This should work with Linux and Mac clients without any extra work. For Windows, it may get more complicated, as not all Windows systems support use of “.local” with Zeroconf.

See here for some slightly dated instructions for Windows (note that avahi is standard on the Pi now).

Note: don’t put the .local in the hostname on the Pi; that gets added automatically. You just need to use it on other systems (the “.local” part essentially means “use multicast DNS to find the name in front of the period”).

And if you’ve added a firewall to your Pi, you’ll need to allow use of inbound and outbound Zeroconf (port UDP 5353) on both IPv4 and IPv6, even if all you use locally are IPv4 addresses, as other computers may default to use of IPv6 link-local addressing for Zeroconf).

The above won’t work if you want your Pi to be accessed from outside your home. To do that, you have to have your home router map a port number to the address and port on your Pi, and then connect to your home router’s external address (which itself changes periodically). You can use dynamic DNS services to map a name to your home router’s changing address. But the home router would need to somehow update its mapping of its fixed port number to the changing address and fixed port of the internal Pi. I don’t have any present need to do this, so I haven’t researched it. It’s probably possible with some of the third-party software available for better home routers (OpenWRT, ASUS Merlin, etc), but I don’t know. This is a case where using a static address may simplify things greatly.


Static IP Addresses


Normally a Pi will request an IP address each time it boots up. It will try to re-use the last one it had, but those can expire and be used by someone else, so over time it will almost certainly change. This address comes from your router, cable modem, wifi hub or other device used to connect to the Internet, and it’s normally one of the 192.168.0.xxx (or sometimes 192.168.1.xxx) addresses that are used with NAT systems. The program that gets these (and the server it gets them from) use the Dynamic Host Configuration Protocol, or DHCP, which on the Pi is implemented in the avahi program (named “avahi-daemon”). You can see the current address by clicking on the icon with two screens on the top right of the Pi’s GUI; this displays the current address set via DHCP.

If you want the Pi to always use the same address, to make it easier to connect remotely, you have to do two things:

- Reserve some addresses on your network so DHCP won’t hand them out.
- Configure the Pi to use one of them.

Note: many documents talk about “static addresses” meaning external ones, addresses visible on the Internet (also called WAN addresses). I’m talking about static addresses within your home LAN network behind a NAT router, which I’ll call “internal” static addresses. Don’t get confused when configuring your router or modem and try to change the external WAN address.

A typical home network using 192.168.0.xxx has 256 addresses it can use, 192.168.0.0 to 192.168.0.255, but 0 and 255 are “reserved” and can’t be used, and 192.168.0.1 is usually the internal address of the router itself, so you really have 253 available addresses.

How you reserve some depends on what you have for your home network. If you have a typical home router or modem that lets you manage it (possibly via an “advanced configuration” screen), you should be able to configure DHCP so it only uses some of the 253 addresses available by default (if the third number is something other than 0, use that in the setup described below). You’ll need to consult the appropriate documentation for your Internet connection device (router or modem) to do that.

So, if you configure it to hand out 63 addresses starting at 192.168.0.2 it will only hand out 192.168.0.2 to 192.168.0.64, and you can use 192.168.0.65 and above (up to .254) for internal static addresses.

Note: if you use wifi on the Pi, you’ll need to set this up for the wifi network, which may have a different configuration screen from the wired Ethernet connections or it may simply “bridge” the two networks, and leave the assignments to the router (i.e., use the router configuration screen). The latter is probably more common, but it depends on your WiFi access point and router’s configurations.

How you set up a static address on the Pi changed with Raspbian Jessie. There are many older guides telling you to edit the “interfaces” file, but that’s just going to cause problems now. If you are running Jessie (i.e., any current version of Raspbian) then use the new method.

The new way to do it is to edit the DHCP configuration file:

sudo nano /etc/dhcpcd.conf

Go down to the end and add the following lines (use eth0 for wired Ethernet, wlan0 for wireless, you can add sections for both):

interface eth0
static ip_address=192.168.0.65
static routers=192.168.0.1
static domain_name_servers=192.168.0.1


Where 192.168.0.1 is the address of your network access device (router, etc). You can also provide a different address for the domain_name_servers if you have one.

This will configure the Pi to use DHCP for other things (like finding DNS servers) but force the Pi to always use address 192.168.0.65 (chose an appropriate address from the ones you set aside for static use). Reboot the Pi for this to take effect. Now you can connect via SSH using this address as the target and know that it will never change.