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

Sun Jun 3 18:50:11 UTC 2007

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

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

  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

 -- 
 Keve Nagy * Debrecen * Hungary