docs/113228: Incorrect and misleading ntp.conf "restrict" example in the ntpd chapter of the handbook

[Remko Lodder]

The following reply was made to PR docs/113228; it has been noted by GNATS.

From: Remko Lodder <remko at elvandar.org>
To: Keve Nagy <keve at safe-mail.net>
Cc: bug-followup at FreeBSD.org
Subject: Re: docs/113228: Incorrect and misleading ntp.conf "restrict" example
 in the ntpd chapter of the handbook
Date: Sun, 03 Jun 2007 20:23:54 +0200

 Keve Nagy wrote:
 > 
 > From remko at elvandar.org Sat, 2 Jun 2007 16:34:31 -0400
 > 
 >> So, you knew that a difference of 5 to 10 minutes will
 >> never ever sync with ntpd?
 > 
 > Incorrect.
 > Using the -g parameter when calling ntpd, or having
 > ntpd_sync_on_start="YES" in rc.conf is supposed to do exactly that.
 > And it not only supposes to do so but it also DOES SO, as long as your
 > ntp.conf file is not crippled by the "restrict default ignore" line or
 > something else.
 > Please read the "How-To-Repeat:" section of my PR and study the ntpd(8)
 > manual in FreeBSD 6.2 with special attention to parameters -q, -g and -x !
 > 
 >> The clock can only be updated
 >> if it is within a little timewindow from the original
 >> since it adjusts the clockspeed to get to the proper time.
 > 
 > If you read my summary I posted on the web at the URL also provided in
 > the "Fix:" section of my PR you will see that I completely understand
 > that. However, this is only the general operation of the FreeBSD
 > implementation of ntpd. And even in that mode you can use the -x option
 > to override the slew/step limit, which on FreeBSD 6.2 is supposed to
 > increase to 600s from 128ms while on MacOSX/Darwin -x simply removes any
 > such slew/step limit. Again, please read the current manuals!
 > 
 >> What is mostly done is to use ntpdate FIRST and then start
 >> ntpd so that the time difference is just small.
 >>
 >> If you do that, what happends then?
 > 
 > And we are back again to the good old RTFM advice. When was the last
 > time you read the ntpdate(8) manual?
 > Or the contents of my PR for that matter? With special interest on the
 > very last sentence of the "Description:" section, which actually has its
 > own paragraph! Did you read that at all, Remko?
 > You are telling me on what is mostly done by running ntpdate(8) before
 > starting ntpd(8); which is exactly what section 27.10 "Clock
 > Synchronization with NTP" (more precisely 27.10.3.1"Basic
 > Configuration") of the handbook tells to our usergroup. The secondary
 > key point of my PR was exactly this being obsolete and inappropriate!!!
 > Why are you telling me to run ntpdate(8) and why is the handbook telling
 > the entire FreeBSD user group to run ntpdate(8), if the very first thing
 > the ntpdate(8) manual says is a warning on not to use ntpdate(8) any
 > more but use ntpd(8) instead with the appropriate parameters? Just for
 > clarity: my point is that the handbook and the ntpdate(8) manual
 > contradict each-other, therefore chapter 27.10 of the handbook should be
 > updated with new guidance showing the use of ntpd[1] in place of ntpdate.
 > 
 > [1] either by calling "ntpd -qg" from crontab/the command line OR by
 > setting ntpd_sync_on_start="YES" in rc.conf
 > 
 > Please also note that the main point of this PR was/is not about ntpd(8)
 > or ntp.conf(5) or a bug related to them! I leave that to somebody
 > smarter than me.
 > This PR is about a problem with the handbook, chapter "27.10 Clock
 > Synchronization with NTP", more precisely NTP subchapter "27.10.3.3
 > Controlling Access to Your Server", which tells the FreeBSD usergroup to
 > add "restrict default ignore" to their ntp.conf file and that will deny
 > all other machines from accessing and using this machine as an NTP
 > server (which is what most of the individual and SOHO users want). But
 > this is not quite what this line will do! On the contrary! The "restrict
 > default ignore" line will not stop ntpd(8) to act as a server, although
 > this is what most people would have expected from it based on the
 > current contents of the handbook. Running "sockstat -4l" shows that even
 > with the "restrict default ignore" line in ntp.conf (and ntpd being
 > restarted of course) ntpd will still be listening on port 123. So the
 > "restrict default ignore" line does not bring the desired result.
 > Instead, it causes serious problems elsewhere which nobody would have
 > expected. These are:
 > 1., ntpd will not be able to sync the local clock to an accurate time
 > fetched from any timeserver.
 > It just doesn't work. Never happens, if the "restrict default ignore"
 > line is present in ntp.conf.
 > What this means in effect is that "ntpd -qg" and
 > ntpd_sync_on_start="YES" will never work as long as this line is active
 > in ntp.conf. Once this line is removed or commented out however, calling
 > "ntpd -qg" works and does exactly what ntpdate does. Also,
 > ntpd_sync_on_start="YES" will behave as if ntpdate would have been run
 > before starting ntpd, once the restrict line is disabled in ntp.conf.
 > 2., ntpq(8) and ntpdc(8) is rendered useless.
 > While "restrict default ignore" is enabled in ntp.conf, no connection to
 > the running ntpd server gets accepted. This also means that query
 > attempts from ntpq(8) and ntpdc(8) on our own machine will be rejected
 > by ntpd(8), so there is no way left to check the status of the running
 > ntpd server. Now, because of unexpected problem #1, people will want to
 > investigate what is going wrong with their ntpd. If they are not
 > qualified to do it by themselves, they will most certainly ask help from
 > smarter people. Either way, things will come back to the point where the
 > user runs ntpq(8) or ntpdc(8), something like "ntpq -p" for instance,
 > all by herself/himself or because he/she was told so by somebody smarter
 > in order to get more details about the possible origin of unexpected
 > problem #1. Unfortunately, as unexpected sideeffect #2, user will not be
 > able to use ntpq(8) or ntpdc(8) because it does not work with "restrict
 > default ignore", consequently has no chance of identifying the source of
 > problem #1. Neither does he/she have the chance to provide additional
 > details to any smarter people, so they will not be able to help him/her.
 > Thus, once the "restrict default ignore" line is activated, initial time
 > sync will never work and the user is ulimately doomed with a non-working
 > and uninvestigatable ntpd which is still listening on port 123 (most
 > probably against the user's will).
 > 
 > For these reasons, I filed the PR suggesting that the part of the
 > handbook should be removed or corrected which recommends the use of
 > "restrict default ignore" in the config file.
 > The more people read this chapter of the handbook in its current state,
 > the more people will cripple their ntpd instead of stopping it to listen.
 > So, this PR is about the handbook issue only! Regardless of what is
 > wrong with ntpd, ntpd.conf or their manual pages, the handbook should be
 > changed urgently, avoiding the misleading of more FreeBSD users.
 > 
 > To answer your question: running ntpdate does work and it immediately
 > sets the accurate time as long as ntpd is not running. So you are
 > completely right with that.
 > But the issue here is to avoid the use of ntpdate. That is, stop using
 > ntpdate and try to use ntpd for the old ntpdate functionality too. That
 > is exactly what running "ntpd -qg" does before starting the generic
 > "slowly adjusting your clock" ntpd daemon, but it only works if
 > "restrict default ignore" is not active in ntp.conf. Hence I submitted
 > this PR.
 > 
 > 
 >> Cheers,
 >> remko
 >> -- 
 >> Kind regards,
 >>
 >>      Remko Lodder               ** remko at elvandar.org
 >>      FreeBSD                    ** remko at FreeBSD.org
 >>
 >>      /* Quis custodiet ipsos custodes */
 > 
 > 
 > Dear Remko,
 > 
 > NO FLAMES INTENDED, but your reply surprised me very much, because it
 > gives the assumption that whoever wrote that response is entirely
 > incompetent with respect to the status of ntpd in FreeBSD 6.2-RELEASE.
 > I am no expert and I am definitely not trying to appear like one here,
 > but I only file a PR when I am confident about what I do. Otherwise I
 > wouldn't be able to provide help or feedback to the FreeBSD people
 > investigating my report and there was no point in filing the PR in the
 > first place. Based on that, responding to a PR by somebody who is
 > officially representing the FreeBSD team therefore expected to be an
 > expert of the topic, but instead showing proof of not being up-to-date
 > in the subject is seriously disappointing and creates a very bad
 > reputation to FreeBSD, the team, and the community as well.
 > That being said --and still no flames intended!-- I don't believe that
 > you are incompetent. I just believe you were negligent in taking the
 > time for reading and understanding the PR I filed. Please read the filed
 > PR again carefully this time, and pay more attention to this in the
 > future because not doing so before publishing a response is still a
 > shame on the FreeBSD team, regardless of your actual proficiency!
 > 
 > Don't get me wrong, please! I really appreciate that somebody is taking
 > the time and effort on behalf of the FreeBSD team to make some progress
 > in this PR and I personally have really no problems with you being that
 > somebody. All I am trying to say is only that by not being up-to-date in
 > a particular field or not being the right person in that particular
 > field and by not recognizing or ignoring this fact early on time, or
 > regardless of these by not really reading what the PR submitter is
 > telling you and still taking over the PR and start acting, you can
 > actually do more damage than good. Such communications lead nowhere but
 > repeating what has already been said, making a fool of both submitter
 > and responder and wasting valuable time on both sides. If both the PR
 > submitters and FreeBSD responders pay a little attention to these things
 > we can all benefit from an efficient workflow, which is what I am sure
 > we all want.
 > 
 > Best Regards,
 > Keve
 > 
 
 Listen dude, I was trying to do some basic checks to see what
 might be wrong. I see many many PR's each day and I do not own
 100% knowledge of any command in our system, I just wanted to
 make sure that you are aware of this and get one point further
 in the line.
 
 The way you put the text (Eventhough your last paragraph says
 dont get me wrong) is not the recipe for a good result. If you
 think you can handle these things better, deliver PATCHES, keep
 track of the items that you are OK in and 'take over' my role
 in this. Till that time I wish you goodluck resolving this.
 
 --
 remko