Draft Stratum 1 Microserver HOWTO is up

[Eric S. Raymond]

Hal Murray <hmurray at megapathdsl.net>:
> I think it needs an introductory paragraph with a date-stamp explaining that 
> the PI-3 is new and still under active development and don't be surprised 
> if/when things break.

I'm not really happy about the fact that we're presently stuck with
one image - I'd rather we solved the UART-mode problem - but one side
effect is that we presently dodge a lot of that kernel-level
instability.  Yes, we apt-get upgrade, but the risks associated with
that are decoupled from the moving-target nature of the 3.

I'll set a bit to add a 'graf like this when we're hugging the leading
edge again.  For now, given the HOWTO's relatively tenderfoot target
audience, I'd prefer not to make them more nervous than I think they
have to be.

> > lithium button cell (except the SKU 424254, which is powered by an on-board supercap
> Their web page says:
>   XH414H-IV01E backup battery for more of time keeping ...

You're quite right about what it says, but that's a documentation
error.  There's a different reference that describes it as a
supercap, and if you search the part number you'll find it's a
capacitor made by Seiko Instruments.

(My suspicions were aroused when I noticed that the type designation
didn't match the CRxxyy format used for lithium coin cells.)

> > A micro-SD card. 1GB is minimal. 4GB is plenty.
> 
> I decided 4 GB wasn't big enough, but I build gpsd, NTPsec, and NTP classic, 
> and keep lots of log files.  It felt like builds were slowing down, but maybe 
> I was just getting impatient.  I don't have hard numbers.  I think SD cards 
> work better if they are not close to full.

OK, following this and Clark Wierda's report I'll change it to 4 and 8.  4 is
the smallest size I have; in saying 1GB I was going by a claim in the Raspbian
docs which you two persuade me is obsolete.

> You describe assembling the board and HAT before inserting it into the case.  
> Have you tried that?  I don't think it will work.  The board has to go in 
> tilted, HMDI side first.  The HAT gets in the way of the tilt.

Unintentional. Now reads "Optional: fit the SBC into a case bottom before
plugging in the HAT."

> You might mention the DogBone case.

Not familar...(searches) Oh, so *that's* what Clark's Beowulf stack was 
wearing at Penguicon.

I'm not a fan. It makes sense for a multi-SBC stack that you might want to sit
in front of a fan, but for a single SBC/HAT pair it seems more like an
aesthetic statement than practical protection.  (The threat model for my
setup has to include curious-cat paws.)

> > SBC's primary or P1 GPIO
> 
> It seems unlikely that other SBCs will call that connector P1.  Maybe Pi 
> clones do.

I'm going to drop all that stuff about the secondary connector. I did some
looking and it seems to only exist on older Pi2s, where it's a pad array
just inboard of the primary connector.

> > device will likely be /dev/sdd
> 
> Mine works out to be sdd, but I think that depends on several things.  I have 
> a second hard disk that gets sdb, and I use a multi-slot USB to small-card 
> adapter that sets up sdc, sdd, sde, and sdf.  The SD slot just happens to be 
> sdd.

This is also what you'll get on a 2-disk system with sdc mapped to a DVD
reader, which is a pretty normal configuration for a tower PC.  I think all
we can do here is pick a "likely" target and note there is variability.

(I'd worry more about this if ddimage didn't check for
device-mountable-but-unmounted status.  That's the main reason I wrote
it.)

> > We provide a script, ddimage, to semi-automate
> 
> I think you need a few more words here.

Along what lines? That is, what could I say that's not conveyed by the
example session?

> > ssh pi at raspberrypi.local
> 
> That assumes your Linux box supports the client side of mDNS, or something 
> like that.  It may be common on desktop setups that are trying to do 
> everything for everybody but I'm not sure it is universal.

The actual precondition is that your desktop has to be running
avahi-daemon, or some other zeroconf implementation, so it will do
mutual discovery with the avahi-daemon instance on the Pi.

I'm not sure this is universal either, but (a) "active by default in
any desktop or general-purpose Linux" seems to be true, and (b) where
it isn't true, life gets more complicated than a HOWTO at this level
can disentangle.  IP discovery without zeroconf is tricky.

Added: "Another possibility is that your host doesn't have a zeroconf
implementation like Linux's 'avahi-daemon' installed.  Try to fix
that.  If you can't, your host setup is outside the scope of what
this HOWTO can handle; get expert help."

> > Call sudo raspi-config on the Pi.
> 
> Up to now, you have been using $ and #.  Why shift to "call"?

Command example added.

> > # apt-get dist-upgrade
> 
> If that gets a new kernel, you want to reboot.

clockmaker normally calls reboot at the end of the --config phase, anyway.

> > commenting out the dtoverlay and force_turbo lines.
> 
> Where did force_turbo come from?

Good catch.  It's a fossil from an older version. Removed.

> > labeled, near the north end of the connector
> 
> On the Adafruit HAT.  Have you checked the others?

This is an invariant of the HAT specification.  The 1PPS pin wanders around,
the TX/RX pins don't.

> > There is a different, non-HAT Adafruit product, the "Ultimate GPS Breakout
> > Board", that also uses GPIO18/P1-12. This may be a source of confusion if
> > you read some of the references in this document.
> 
> The breakout board doesn't know anything about GPIO pins.  You are probably 
> thinking of some writeup that cloned the Uputronics pins.

I'm confused.  Are you telling me that the breakout board doesn't connect to
the GPIO?

> > # Known Stratum 1 servers with excellent quality and connectivity.
> > server 199.102.46.72 iburst     # tock.usshc.com
> > server 149.20.64.28 iburst      # clock.isc.org
> > server 17.254.0.49 iburst       # tick.apple.com
> 
> This gets complicated.  It's also important.
> 
> In general, you don't want to wire a name or address into gear that you don't 
> directly control without the owner's permission.  If you do get their 
> permission, you want to set things up so that they can easily and cleanly 
> revoke that permission.  This holds for things like anti-spam black lists as 
> well as NTP servers.
> 
> One way to revoke permission is to insert a layer of indirection in the DNS, 
> a cname.  Deleting that cname (or the landing name) breaks things and stops 
> the traffic.  (It may shift the load to the DNS servers.)
> 
> The wikipedia page on NTP abuse is very good.
>   https://en.wikipedia.org/wiki/NTP_server_misuse_and_abuse
> I think Dave Plonka's writeup should be required reading for any computer 
> science degree.
> 
> On top of all that, the connectivity is only good if you are located near the 
> servers.

I understand you, and I want us to be good citizens, but reality seems to be
backing us into a corner here.  Gary has strongly advised against using
general pool servers. His reasons seem cogent, especially if our Pis are
going to be used, as intended, to *feed* the pool. We don't want our Pis
to create a GIGO loop that indiscriminately boosts the signal of crappy
servers.

I'd prefer not to use check servers at all and supply only the GPS time
after sanity-filtering it locally.  But I've been too busy to follow up
on the discussion of whether they're actually required (I badly want
to, but my mailbox keeps getting flooded...)

Until that issue is resolved, I don't see that I have any alternative
but to default to a fixed set of known-good servers that implicitly
hold themselves forward as public utilities.  You going to tell me
that a hostname like 'clock.isc.org' isn't doing that? :-)

I want to put a hold on this part of the discussion until I can reply to
your mail on the requirement(?) for three check servers.  I agree
it's important, but I don't see any gain in trying to resolve this
issue without getting the other right first.

> > GPS Serial data reference (NTP0) [Second one]
>   NTP0 => NTP1
> 
> > Internet time servers 
> 
> There is no section of the ntp.conf labeled "Internet time servers"

Fixed.

> Your ntp.conf doesn't enable any logging.

That's deliberate avoidance of complications I don't want to have to
try to explain at this point.  It belongs in a section under "Advanced
Topics" and I don't have a clue how to write it - my outside-in view
is still deficient there.  I'd take a patch.

> > # ntpsec/build/main/ntpq/ntpq -p
> 
> The printout doesn't match the ntp.conf you just described.  It's still using 
> 4 pool servers.

Shall fix.

> > # cp pinup /usr/local/bin
> What's "pinup"?  Where did it come from?

clockmaker --build installs it.

> > Install this text as the file /etc/init.d/timeservice and make it executable:
> How do you expect "this text" to magically turn into a file?

I do note that I expect the uset to be able to use a text editor.  In fact,
clockmaker --install does this; thus, I expect by hand installs to be unusual
and confined to people who know whatbthey're doing.

> > RUNASUSER=nobody
> That's fine for gpsd which doesn't do any logging.
> ntpd usually runs as user ntp to get access to /var/log/ntpstats
> Most (many, several) distros setup /var/log/ntpstats
> (I use /var/log/ntp rather than /var/log/ntpstats)
> Debian has a cron job that compresses and prunes them.

This goes under "Advanced topics: logging".  I think you are almost certainly
the best-qualified person we have to write that.

> > can mame a link to it from
> 
>   mame => make  ??

Fixed.

> > using adduser run as root.
> 
> I think adduser needs a few flags.  I normally forget them and have to go 
> back and patch things up.

The Linux versions prompt you for fields you don't specify.

> > machine to the build account
> 
> How did "me" turn into "the build account"?

Fixed.  The term "build account" was used in older versions, this is a remnant.

> > You will probably want to re-fetch clockmaker and do a
> > "clockmaker --build" in your home directory.
> 
> I would reorder things so that happens naturally.  Just do the security stuff 
> first.

I used to sequence it that way.  I changed it deliberately, not
without hesitation.  I might change it back, and take your objection
seriously towards that end.

The problem is that I have a clash of conflicting objectives.  Securing
the machine and switching the action to a non-root build account first
is, as you say, more natural.  

Two considerations cut the other way.  One is minimizing therbligs.  I
elected to reduce the amount of handwork between start and the GPS/HAT
smoke test as much as possible, in case it fails and the user has to
restart.  If the basic system integration no workee, the security stuff
is irritating waste motion.

The other is that securing the machine is a policy step, implictly
optional.  It's a good general rule of documentation in cases where
you have to explain both that the required mechanism steps should
come first.

For the moment I'll leave it as is.  But your point has weight;
I might change my mind.

> > WiFi is deliberately not removed, in order to give you a
> > fallback TCP/IP access when a cable is inconvenient.
> 
> The recipe for removing WiFi would be convenient.  Or a pointer to one.

I don't actually know it.

> > Configuring for a static IP address ==
> 
> Trailing ==

Fixed.

> > wonder why this recipe uses gpsd through SHM rather than ntpd's native
> 
> Mumble.  That's worth another message.

I know.  We need to have a serious discussion about alternate, and possibly
better, configurations.  So much to do...

> > Edge-detection issues and new HATs
> 
> Mumble.  That's long and complicated.  I would simplify things greatly.  Drop 
> the ppio detects column until we get an example that is different.

It's possible we already have one.  I expect to have access to a scope
later today to cceck.

> > Odroid C2
> 
> Looks like a link didn't make it.

Added.

> I agree with most of Gary's comments.  I only skimmed them.

I probably will, too, once I translate then out of Garyese.:-)

> Typos:

All fixed.

Thanks for the excellent critique.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>