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

[Keve Nagy]

>Number:         113228
>Category:       docs
>Synopsis:       Incorrect and misleading ntp.conf "restrict" example in the ntpd chapter of the handbook
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jun 01 16:40:10 GMT 2007
>Closed-Date:
>Last-Modified:
>Originator:     Keve Nagy
>Release:        FreeBSD/i386 6.2-RELEASE-p4
>Organization:
>Environment:
FreeBSD/i386 6.2-RELEASE-p4
>Description:
Chapter 27.10.3.3 "Controlling Access to Your Server" of the FreeBSD handbook (network-ntp.html) is flawed. It suggests that by adding a "restrict default ignore" line to /etc/ntp.conf, other computers will not be able to connect to and use our system as a time server. Most users wish to set up their ntpd to only fetch time from a remote system but not to provide time service to other hosts. All these users (including me) are fooled by this chapter, and mislead to believe that by adding the above line their system will use ntpd in a "client only" mode, reading the time from the internet and syncing local clock to it.
In practice however, this is almost the other way around!
With the "restrict default ignore" line included in ntp.conf, ntpd is not able to sync local time to that of the referenced time servers.
Therefore this chapter of the handbook should be urgently revised, and at least the "restrict default ignore" example removed. Also, a warning should be placed there explaining the problem this line have caused.
It should also be highlighted, that by adding the "restrict default ignore" line, nothing will be able to connect to one's running ntpd. Therefore not even ntpq(8) or ntpdc(8) can be used to track the operation of ntpd, so once that line is added the user is ultimately screwed (ntpd doesn't set the accurate time, and user has no way to check whats happening or provide details to anyone he/she asks help from).

Another thing to the ntp chapter: it still guides people on the use of ntpdate, although the ntpdate manual page warns people in the very beginning that its use is discouraged and ntpd -q should be used instead (which fails with the above restrict line in the cfg).
>How-To-Repeat:
1., create an /etc/ntp.conf as described by Chapter 27.10.3.3 "Controlling Access to Your Server" of the handbook, something like this:
server 0.pool.ntp.org  iburst
server 1.pool.ntp.org  iburst
server 2.pool.ntp.org  iburst
server 3.pool.ntp.org  iburst
server pool.ntp.org  iburst
driftfile /var/db/ntp.drift
restrict default ignore

2., set your system clock manually to an inaccurate time (e.g. by 5-10 minutes late or forward, using "date YYYYMMDDHHMM")

3A., Simply run "ntpd -qg" from the command line and see that it DOES NOT SET the correct time, although that is what is expected.

3B., You can also try adding ntpd_enable="YES" and ntpd_sync_on_start="YES" to rc.conf, and then start ntpd by "/etc/rc.d/ntpd start". Check your system clock regularly and you will see that your time is not corrected, even after a few hours! Stop ntpd by "/etc/rc.d/ntpd stop".

4., Remove or comment out the "restrict default ignore" line from the end of the ntp.conf file.

5., Run step#3A again and see that this time your system clock is almost immediately synced to the correct time.

6., Repeat step#2 to manually set an inaccurate time again.

7., Try step#3B again, and you will see that almost immediately after starting ntpd the time is nicely synced to the correct time.
>Fix:
I am unable to identify if this is due to a bug in ntpd, handling incorrectly the "restrict default ignore" line, or if it is an error in the ntpd documentation not defining clearly the meaning and function of this line or the elements of this line.
In the meantime, the handbook should be urgently updated to avoid other people running to the same trouble.
I posted a note on this at http://keve.maclab.org/freebsd/ntp which you are welcome to use to rewrite this part of the handbook.
Let me know if you need manpower to rewrite this part of the handbook, as I might be able to do that. (or at least try :-)

>Release-Note:
>Audit-Trail:
>Unformatted: