Stratum-1-Microserver HOWTO

Download the latest Raspbian Stretch Lite from [RASPBIAN] to your host.

Use sha256sum to verify the correctness of the image. Remember to substitute the name of the current image zip file. For example:

The hex string this command returns should match the checksum on the Raspbian download page. If it doesn’t, you have a corrupted image and should re-fetch it.

Note that this is not the regular NOOBS image, but a light one specifically designed to boot the Pi as a headless server, communicated with only by Ethernet. By going this route we get to avoid some hardware prerequisites that would never be used after install, and skip a bunch of steps in removing unnecessary desktop software.

sudo to root and install dcfldd on your host machine:

Insert an SD card into the reader and, if it’s a USB reader, plug the other end into a USB port on your host.

Note: your host may automount the card if it has been set up for Linux before - whether this happens depends on what distribution and desktop environment you are using. If your window manager pops up a file-browser view of the device, you should unmount it through that GUI.

You can use the older dd if you do the next step manually, but dfcldd is better about giving you progress messages during the operation.

Better yet, we provide a script, ddimage, to semi-automate the next step of the process; it’s safer to use that, because it performs some sanity checks that should prevent you from scribbling on your disks. ddimage instructions are further below.

Either way, automatic or manual, you’ll need to know the device name of your SD card reader. On a host running Debian or Ubuntu, the USB device will most likely be /dev/sdd, but could have a different last letter depending on how many hard drives you have and how your reader firmware is set up. If you’re using a built-in SD reader port, e.g. on a laptop, the devicename might be something like /dev/mmcblk0

First, unpack the zip file to get an img file (remember to substitute the name of the current image zip file):

To proceed manually, follow the directions at [INSTALLATION], using dfcldd. Your command will look something like this - again, using the current image name:

For safety’s sake, force pending I/O to the SD card before removing it.

To use ddimage, first download it:

Now read it. You should always read any script that will run with root permissions, to check that it doesn’t do anything nefarious. Give it the basename of your SD reader (usually "sdd"). It will do some safety checks, then generate a dcfldd command like the above.

You should make it executable so you can run it as a script:

Your ddimage command execution should look roughly like this:

with an animated progress line in the middle.

Note: this can take a while, with lag between the "records out" line and the "Done". Many USB SD readers have an activity light that blinks while accesses are going on; if yours does, watch for it to stop blinking.

Take the card out of the SD reader and insert it into your SBC. Ethernet should not be plugged in! Attach the keyboard and display. Power up.

Log in as the default user, with the default password. (On the Raspberry Pi this is pi and raspberry.)

Now run "sudo raspi-config". Choose "Interfacing options"->"SSH" and enable it. Without this step (not required on previous Raspbian releases) you will not be able to ssh into the device.

Use passwd to change the password of the default user. Don’t use anything obvious or cute. Remember the password until, later in this process, the default user account is removed.

The reason this step had to be done off-net is because there are attack bots on the public Internet dedicated to using the combination of a known login and known password to try to subvert machines before they can be secured. To see those hunting for Raspberry Pis, for example, do this on any Internet-facing machine:

You can’t use anything obvious or cute as a password because those bots could very well run a specialized dictionary attack if they find a passworded SBC with one of the names they’re expecting.

You can skip the re-passwording step only if your network lives behind a firewall with both IPv4 and IPv6 forwarding rules. If anyone on the public Internet can reach your SBC via ssh before you either change the default-account password or remove the default account altogether, your Pi could be enslaved by an attack bot within minutes.

Next, make sure your SBC has a live Ethernet cable plugged in and connected to the same network as your host (because it will also need to see the general Internet, direct-connecting to your PC is insufficient). Power it up and wait about 60 seconds (or, if you can see the Ethernet-port LEDs, wait for them to start flashing) then use the default machine name and login to ssh from your host. For a Raspberry Pi, that looks like this:

You may see some warnings from ssh about an unknown host; tell it yes, you want to connect. Then you should be asked for a login password.

If ssh tells you it can’t see any host with the expected name, either the SBC hasn’t yet booted or your network can’t see it. Don’t panic. Check for a green light on the Pi’s Ethernet port to be sure it’s plugged in properly. Make sure your SD card is electrode-side-up (unplugging the power before removing it, if you have to) and properly seated. Wait 30 seconds and try again.

Another possibility is that your host doesn’t have a zeroconf implementation like Linux’s avahi-daemon installed. Try to fix that. This may work:

If that doesn’t work, check the display connected to the SBC and figure out the assigned address with the "ip a" command. If the output of "ip a" doesn’t list "eth0", something else is wrong, which is outside the scope of this HOWTO; please investigate the many resources on the Internet that are available. If "ip a" lists "eth0", ensure that the word "UP" is listed in the bracketed text immediately to the right of "eth0", and that the "inet" line lists a dotted-quad IP address. If either or both are missing, this is also outside the scope of this HOWTO. Try rebooting the Pi; it can’t hurt.

Persistent failure after you’ve tried these things mean you need to rebuild the SD card image. Try with a different SD card, as sometimes older ones go flaky.

The hardest part is done; you may remove the keyboard and display now - you won’t need them any more!

Most of the remaining instructions do not have to be done by hand. You can download clockmaker, a Python script which does much of this recipe for you. Here’s how to use it:

Some further uses of clockmaker are discussed in later steps.

The clockmaker script is intelligent about not redoing steps it has already done; it is safe to run each stage multiple times. Redoing the --build step re-pulls from the software repositories.

In the recipe that follows, steps marked "{--config}" or "{--build}" are parts clockmaker will do for you if you run it. It is recommended that you read the steps to understand the process, then use clockmaker to avoid most of the typing.

At this point the steps you can automate with clockmaker begin. If you have not downloaded clockmaker, refer to "Using Clockmaker" above.

{--config} Fully update the Linux on your SBC. The easiest way to do this is with these commands:

These changes are not reversible, but you’d want them for any other use of the SBC anyway. You always want to be updated with security patches and other fixes.

{--config} Edit the file /boot/cmdline.txt, and remove the following from the single line in the file:

This prevents it from spawning a login shell on the serial port that your GPS needs to use. Ensure that the text remain a single line.

{--config} Edit the file /boot/config.txt, and add this line to the end of the file:

The Raspberry Pi Foundation made a design decision on the Raspberry Pi 3 that ties the serial baud rate to the CPU clock rate (by default). This was done because the normal lines that fed the serial port were used for the built-in Bluetooth. This does not affect any other Pi variant.

Your timeserver is not going to need Bluetooth, so you should disable it and remap the devices. Our instructions come from [DOREY], which explains the problem in more detail. We don’t use some of his steps because this build is designed to run headless.

{--config} Edit the file /boot/config.txt again, and add these lines to the end of the file:

This change restores the behavior to that of the Pi2 and earlier, in which the serial device attached to the UART is /dev/ttyAMA0 rather than /dev/ttyS0.

This change can effectively be reversed by commenting out the dtoverlay line.

{--config} To disable the Bluetooth daemon, since we’ve disabled the driver, enter this:

{--config} Create a symlink to the GPS device to make it easier to refer to. Put the following in a new file /etc/udev/rules.d/10-pps.rules to accomplish this.

You’ll need NTPsec to be able to see the high-precision PPS (pulse-per-second) signal from the GPS. But the serial interface from a HAT only supplies TX/RX; the PPS signal is shipped on a different pin of the GPIO connector.

The RX/TX signals are always expected on the same two pins of the GPIO (P8 and P10) which connect to the SBC’s UART. You can see them, labeled, near the north end of the connector. Most other GPIO pins can be interpreted by the Pi in different ways, configured by software. Which pin is used for 1PPS is a variable of the HAT design. Here is a table:

A handy resource with a display of the pin locations and ID’s for the Adafruit and Uputronics HATs can be found here: pinout.xyz

There is a Linux kernel driver called pps-gpio which, given one of these pins, uses the signal from it to support an RFC2783 interface to PPS that NTPsec (and GPSD) can use. To see 1PPS, you need to ensure that this driver is loaded and monitoring the correct logical pin.

The procedure for declaring the GPIO pin varies by Raspbian version. We only give the formula for the current Raspbian here; you can find details about older versions at [TAYLOR];

{--config} Edit /boot/config.txt and add these lines to the end of the file, replacing 4 with the logical pin number for your HAT if it’s not an Adafruit:

The clockmaker script will do this for you, but not before installing some packages needed for the next step.

A small optimization can be added to the /boot/config.txt file that will make more memory available to your Pi, since you are running headless. Add the following to the end of the file:

Once you have fully configured, the last few lines of your /boot/config.txt file should look rather like this:

The number after "gpiopin=" may be different. The order of the lines is not important.

To test 1PPS, use ppstest from the pps-tools package.

If you are doing these steps by hand rather than with clockmaker, prepare with this step {--config}:

Then run this test:

You should see repeated lines somewhat resembling this, one per second, until you interrupt:

Note, this will produce a false negative for PPS if the GPS has no fix yet - if you have not had your SBC powered-up for very long, that is not unusual. Don’t worry overly if you do not have PPS output yet.

Sudo to root and turn off the default Rasbian timesyncd service:

Note: As of the 2018-06-27 Raspian image, a bug may cause the following error output when you try to stop timesyncd -

If so, just do as the warning states - type systemctl daemon-reload, then run the systemctl stop and disable again.

Because Raspbian no longer includes ntpd, we need to add a user for ntpd to run as, and create a couple of directories ntpd needs in place before running.

Run gpsd, telling it to look at the GPS device. Since gpsd may still be running from the Live test above which was done as user pi, we issue a "pkill" just for good measure.

Run your newly built ntpd, telling it to step time if required:

Run ntpq -p, and look for ntpd to begin using your PPS as its reference. Be patient, it can sometimes take a few minutes to complete. Simply run it repeatedly to watch it update.

You’re hoping for a display similar to the above, with two local devices and three check sources. A nonzero "reach" column on a source line indicates that your ntp is getting time notifications from that source. You want your SHM(1) to have an asterisk next to it, meaning that it is the current timesource of your server.

If the value under "reach" for the SHM lines remains zero, check again that gpsd is running and ntpshmmon reports fix lines. Run through the live test steps again if necessary.

This step can be automated with "./clockmaker --install" done as root.

Change to the directory your gpsd and ntpsec repository clones live in and install both suites:

Install the pinup script:

Copy the following block of text into the file timeservice; copy it to /etc/init.d/timeservice and make it executable:

The commands to do this are:

Copy the following block of text to the file timeservice.service, then install it in the directory /etc/systemd/system/:

The command to do this is:

Enable startup at boot with:

What’s going on here: the file /etc/init.d/timeservice is a System V init script conforming to LSB conventions. If you decide to ditch systemd you can make a link to it from, e.g. /etc/rc3.d and the right thing will happen. The file /etc/systemd/system/timeservice.service is a systemd unit file that will call the System V init script to do the real work.

Reboot. Check that gpsd and ntpd are running, and watch ntpq -p to verify that you can see time samples coming in.

Final parts of this step can be automated with "./clockmaker --mask" and "clockmaker --secure", both done as root.

The fact that your SBC has a known default name and default user means that it is very vulnerable to being attacked and exploited by anyone who gets access to your network. Here’s how to fix this:

The Raspbian default is to install a lot of background processes that exist to support a graphical desktop. Installing from the Lite image eliminates most of these. This reduces load variability on the processor, which will decrease your time jitter. It will also cut your power draw and heat dissipation, increasing the Pi’s expected lifetime. Most importantly, it will reduce the number of ways for things to go wrong.

You can strip down a bit further with these commands:

This step can be done conveniently with "clockmaker --strip" run as root.

The resulting configuration is pretty minimal, as you can verify by running "pstree -paul" (or the older-school "ps ax") and noticing that most of the background processes are kernel threads.

Note that triggerhappy is required for raspi-config; after you remove it, apt autoremove will remove raspi-config. This is easily reversed by reinstalling raspi-config.

WiFi is deliberately not removed, in order to give you a fallback TCP/IP access when a cable is inconvenient. If you want to banish WiFi, this will do:

If you’re only going to use the SBC as a time service for your local network, you can cite its zeroconf (.local) address in other ntp.conf files. If you want to expose it as a public server you’ll need to configure the SBC to use a fixed, static IP address. That process is described in [EAT-STATIC].

If you do this, and verify that it works, you can remove avahi-daemon and dhcpd5, further cutting the number of service processes running.

Once you do this, the SBC will no longer be accessible at a ".local" address.

After first configuring and building your server software, you can use the --update mode of clockmaker to update your software without re-generating ntp.conf (this replaces --build). This may be useful if you have put local customizations in ntp.conf.

If you are already familiar with ntpd and wonder why this recipe uses gpsd through SHM rather than ntpd’s native refclock 20 GPS driver, the answer is this: when refclock 20 is configured to use 1PPS, it mixes in-band time data with 1PPS in a way that causes it to behave badly, and possibly get rejected as a falseticker, when 1PPS is only occasionally available.

The pps-gpio module as of April 2016 has a flaw. It catches only one edge of the PPS. You have a 50/50 chance you are seeing the falling edge rather than the assert edge (which is the actual top of second). A patch to fix this has been submitted to the Linux kernel maintainers but not merged.

Which edge the kernel will see, and the pulse width, are constant depending on the GPS type and firmware (and if you can find a real datasheet for the GPS engine it will tell you the pulse width). If the kernel sees the falling edge, the width of the pulse emitted by your GPS will introduce a fixed lag from top of second to the time when you actually see the PPS.

Pulse widths (and the induced lag) range from so fast the serial driver can’t see them to, worst case, 0.5s. The worst case is rare; typical pulse widths are 50 to 200ms. Because the error is constant, you can compensate it out with an offset if you know what it is. HATs marked "assert edge" below do not require compensation.

These details will become relevant whenever we qualify a new HAT for coverage in this HOWTO. The important thing to check is whether the pps-gpio driver triggers on assert or falling edge.