New User Experience Check-In

[Kenneth Finnegan]

Greetings,

I've been following the NTPsec project for a while now, since I find NTP
and timekeeping generally interesting, and have tried to use ntpd before
for my own projects (with what you might describe as a
knocking-rocks-together level of understanding). Add to that good timing
between the highly amusing temperature control posts on the NTPsec blog and
a $100 eBay giftcard from work, and I decided to sit down this evening and
pull the trigger on the required temperature control kit and spin up a
Raspberry Pi NTP server.

So here we go. A new user wanting to follow the microserver whitepaper for
the very first time working off of only a basic recollection of ntpd from
the last time he had to set up an NTP + GPS server for an amateur radio
event a few years ago. Documentation includes:

* https://www.ntpsec.org/white-papers/stratum-1-microserver-howto/
* https://blog.ntpsec.org/2016/12/19/ntpviz-intro.html since I also really
wanted pretty graphs.

Here's how my first time experience went, with the disclaimer that I also
try and support users installing my software on Raspberry Pis, so I feel
your pain trying to keep documentation up to date with Raspbian changing
fundamental parts of the game so regularly. I just thought some of you
would find my evening's narrative insightful:

* "Making a bootable SD" - I prefer to install Raspbian Lite from NOOBS, so
I skip the dd section. The comment about not using NOOBS seems to point to
this being written before Lite was available from the NOOBS index. Much
easier just copying the files onto a FAT SD card and picking Raspbian Lite
than all this dd action IMO.

* I didn't check this, but rumor has it Raspbian now defaults to ssh
disabled, so you have to change your password and then enable ssh from
raspi-config (or using unix commands).

* A bit odd talking about installing libnss-mdns since Lite still has
avahi...

* A bit confusing disabling the serial interface... we need that! Maybe it
means disable the serial console but leave the serial port enabled? (Of
course raspi-config has changed the behavior of this menu item in the last
month since I ran it last)

* Now we get to the clockmaker part of the whitepaper, which is my biggest
grip with the whitepaper: All this effort to make a super nice clean script
to save all this work for me, but I still needed to muddle through all the
detailed instructions and make sure they were all covered by just running
clockmaker a few times with different options. I could have gotten through
this how-to much faster if the documentation had skipped all the stuff I
didn't need to do myself anymore and was just "Run clockmaker --config as
root and pick your GPS hat, smoke-test the GPS hat, run clockmaker --build,
smoke-test ntpsec, run clockmaker --install, mask and secure, and here's
some advanced options for tuning and thinning.

It wasn't until I got down to the secure the machine section that I
realized what all the random {--verb} at the beginning of paragraphs were.
Oh! That means I could have skipped over that paragraph since it was
covered by that flag! Doh!

I just found it odd how the whitepaper didn't embrace the clockmaker script
to abstract anything away. I expected it to go "run clockmaker --build,
which does this, this, and this" but it instead went "run clockmaker
--build. {--build} do this thing, {--build} do this complicated thing.
{--build} do this other thing." and eventually paragraphs stop starting
with {--build} where I need to start typing again.  I think I remember
originally reading the whitepaper and not seeing this awesome clockmaker
script, so it seems like that came in later, and I totally understand the
reluctance of tearing out all that detailed documentation on how to do all
the work.


That being said, mainly just a documentation style gripe on how much you
hide from the new user. I read through it, it seemed longer than it needed
to be, I ended up with a running ntpsec server. Great! I ignored the GPS
sections since my GPS receiver hasn't arrived yet and the Motorola ones
I've got laying around have given me troubles before, but ntpmon and ntpq
-p are both showing encouraging things.


Now for those pretty graphs!
https://blog.ntpsec.org/2016/12/19/ntpviz-intro.html

"Clone the ntpsec repo" No problem, I've already got that in my home
directory from clockmaker. Skipped.

"Running" No problem, I just followed the whole whitepaper and got it
running. Skipped.

"Time out" Of course I'll need to wait for logs to collect. I'll give it 30
minutes, because that's almost a day, grab another beer, and see how it
goes then.

$ ntpviz @day/optionfile
ntpviz: WARNING: liberation truetype fonts not found
ntpviz: ERROR: /var/log/ntpstats is not a directory

Uhhh... how am I missing ntpstats? I just got ntpsec working! Much digging
later, I realize that the "Running" section mentions "[...], and logging
data" and the clockmaker script didn't do this. Fair to not default with
logging, for being on an SD card, but I kind of wish that this important
prereq for ntpviz was better documented than as half a sentence. It took
digging through the man pages (which aren't available on my pi - so
apparently clockmaker didn't pull in asciidoc maybe?) and the online
quickstart to figure out I wanted:

statsdir /var/log/ntpstats/

statistics loopstats peerstats clockstats
filegen loopstats file loopstats type day enable
filegen peerstats file peerstats type day enable
filegen clockstats file clockstats type day enable

logfile /var/log/ntpd.log
logconfig =syncall +clockall +peerall +sysall


Great. Drop those in the conf file, annnd... error messages that ntpstats
doesn't exist. sudo mkdir and restart ntpd, annnnd not writable by ntpd, so
ps -Af to figure out what ntpd is running as and sudo chown ntp:ntp
/var/log/ntpstats/ and restart ntpd.

Now I've got stats files showing up! Hopefully these don't grow towards
infinity? (best I can tell clockmaker didn't install the logrotate config,
and that config doesn't seem to include /var/log/ntpstats anyways)

$ ntpviz @day/optionfile
ntpviz: WARNING: liberation truetype fonts not found
ntpviz: WARNING: no temps to graph
ntpviz: WARNING: no temps to graph
ntpviz: ERROR: gnuplot not found in path

Well that's a problem... Hopefully gnuplot is packaged in something easy
like apt install gnuplot. Oh good, and now ntpviz runs, and now I see
pretty plots! Fantastic!


So in summary, my tripping points as a new user running through the
documentation:
* The microserver whitepaper didn't let me really enjoy the convenience of
the clockmaker script since I still needed to parse all the work it was
already doing for me to find the next step
* clockmaker installed ntpsec without even any framework (folders,
commented out conf lines, etc) to make it easy to turn on logging
* The ntpviz intro didn't tell me how to manually set up logging.
* The ntpviz intro didn't tell me gnuplot was a dependency

I've now got my Pi up and running, so the documentation is clearly
sufficient, but it has some sharp edges. The ntpviz issues are pretty
straight forward fixes, but I didn't want to open the topic by submitting a
patch stripping out documentation of everything clockmaker does without
sending up a test balloon here first on the matter.

--
Kenneth Finnegan
http://blog.thelifeofkenneth.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/devel/attachments/20170323/7383d0b6/attachment.html>