17603117 ntpd(8) is not helpful if I need to know how to quickly set up NTP
authorBrian Utterback <brian.utterback@oracle.com>
Mon, 28 Nov 2016 19:00:18 -0800
changeset 7418 13f198c70f3c
parent 7417 799c7022804e
child 7420 a5a56b02087b
17603117 ntpd(8) is not helpful if I need to know how to quickly set up NTP
components/ntp/manpages/ntp.conf.5
components/ntp/manpages/ntpd.8
--- a/components/ntp/manpages/ntp.conf.5	Mon Nov 28 19:00:01 2016 -0800
+++ b/components/ntp/manpages/ntp.conf.5	Mon Nov 28 19:00:18 2016 -0800
@@ -18,7 +18,7 @@
 .\"
 .\" CDDL HEADER END
 .\"
-.\" Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved.
+.\" Copyright (c) 2009, 2016, Oracle and/or its affiliates. All rights reserved.
 .\"
 .TH "ntp.conf" "5" "" "" "File Formats"
 .SH NAME
@@ -219,7 +219,7 @@
 .RS 4n
 Specifies the version number to be used for outgoing NTP packets. Versions 1-4 are the choices, with version 4 the default.
 .RE
-.SS "Auxilliary Commands"
+.SS "Auxiliary Commands"
 .sp .3
 .ne 2
 .mk
@@ -796,7 +796,7 @@
 .ad
 .sp .25
 .RS 4n
-Indicates the full path of a directory where statistics files should be created (see below). This keyword allows the (otherwise constant) \fBfilegen\fR filename prefix to be modified for file generation sets, which is useful for handling statistics logs.
+Indicates the full path of a directory where statistics files should be created (see below). This keyword allows the (otherwise constant) \fBfilegen\fR filename prefix to be modified for file generation sets, which is useful for handling statistics logs. This directory must be writable by the user "daemon" and all files in it must be writable by that user.
 .RE
 .sp .3
 .ne 2
@@ -894,7 +894,7 @@
 .ad
 .sp .25
 .RS 4n
-This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the \fB-f\fR command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero.
+This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the \fB-f\fR command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero. This file must be in a directory writable by the user "daemon".
 .LP
 The file format consists of a single line containing a single floating point number, which records the frequency offset measured in parts-per-million (PPM). The file is updated by first writing the current drift value into a temporary file and then renaming this file to replace the old version. This implies that \fBntpd\fR must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should be avoided.
 .LP
@@ -1000,7 +1000,7 @@
 .ad
 .sp .25
 .RS 4n
-This command allows additional configuration commands to be included from a separate file. Include files may be nested to a depth of five; upon reaching the end of any include file, command processing resumes in the previous configuration file. This option is useful for sites that run \fBntpd\fR on multiple hosts, with (mostly) common options (e.g., a restriction list).
+This command allows additional configuration commands to be included from a separate file. Include files may be nested to a depth of five; upon reaching the end of any include file, command processing resumes in the previous configuration file. This option is useful for sites that run \fBntpd\fR on multiple hosts, with (mostly) common options (e.g., a restriction list). The include file must be in a file readable by the user "daemon". 
 .RE
 .sp .3
 .ne 2
@@ -1033,7 +1033,7 @@
 .sp .25
 .RS 4n
 .LP
-This command specifies the location of an alternate log file to be used instead of the default system \fBsyslog\fR facility. This is the same operation as the \fB-l \fRcommand line option.
+This command specifies the location of an alternate log file to be used instead of the default system \fBsyslog\fR facility. This is the same operation as the \fB-l \fRcommand line option. This file must be writable by the user "daemon" and be in a directory writable by that user.
 .RE
 .sp .3
 .ne 2
--- a/components/ntp/manpages/ntpd.8	Mon Nov 28 19:00:01 2016 -0800
+++ b/components/ntp/manpages/ntpd.8	Mon Nov 28 19:00:18 2016 -0800
@@ -1,3 +1,4 @@
+config/ignore_time_adjustment_errors
 '\" te
 .\" CDDL HEADER START
 .\"
@@ -18,7 +19,7 @@
 .\"
 .\" CDDL HEADER END
 .\"
-.\" Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved.
+.\" Copyright (c) 2009, 2016, Oracle and/or its affiliates. All rights reserved.
 .\"
 .TH "ntpd" "8" "" "" "System Administration Commands"
 .SH NAME
@@ -104,7 +105,8 @@
 .TP
 .BR \-c " \fIstring\fP, " \--configfile "=" \fIstring\fP
 The name and path of the configuration file,
-/etc/inet/ntp.conf by default.
+/etc/inet/ntp.conf by default. This file must be readable by the user "daemon".
+If the file does not exist the \fBNTP\fP service will not start.
 .TP
 .BR \-d ", " \--debug-level
 Increase output debug message level.
@@ -141,7 +143,9 @@
 .TP
 .BR \-l " \fIstring\fP, " \--logfile "=" \fIstring\fP
 Specify the name and path of the log file.
-The default is the system log file.
+The default is the system log file. If logging is enabled to the logfile, the
+logfile must be in a directory that is writable by the user "daemon" and if the
+file already exists, it also must be writeable by the user "daemon".
 .TP
 .BR \-L ", " \--novirtualips
 Do not listen to virtual IPs. The default is to listen.
@@ -271,7 +275,8 @@
 An integer specifying the level of debugging requested. A zero means no debugging. The default is zero.
 .TP
 .BR config/logfile
-A string specifying the location of the file used for log output. The default is /var/ntp/ntp.log
+A string specifying the location of the file used for log output. The default is /var/ntp/ntp.log. The
+log file must be writable by the user "daemon" andmust be in a directory writeable by that user.
 .TP
 .BR config/no_auth_required
 A boolean which when true, specifies that anonymous servers such as broadcast, multicast and active peers 
@@ -295,6 +300,10 @@
 time the system clock is synchronized. This can potetially delay the system start up by a significant amount. The
 default is false.
 .TP
+.BR config/ignore_time_adjustment_errors
+A boolean which when true, causes the \fBNTP\fP service to skip checking for the privileges that allow it to 
+adjust the system clock. The default is false. 
+.TP
 .BR config/mdnsregister
 A boolean which when true, will cause the daemon to register with the network mDNS system. The default is false.
 .TP
@@ -320,9 +329,36 @@
 .LP
 When \fBntpd\fR starts it looks at the value of umask, and if zero \fBntpd\fR will set the umask to 022.
 .LP
-The documentation available at /usr/share/doc/ntp is provided as is from the 
-\fBNTP\fR distribution and may contain information that is not applicable to 
+The documentation available at /usr/share/doc/ntp is provided as is from the
+\fBNTP\fR distribution and may contain information that is not applicable to
 the software as provided in this particular distribution.
+.LP
+The ntpd daemon now runs as the user "daemon". Care must be taken if it is
+configured to read or write files other than in the directories /etc/inet and
+/var/ntp. Any other locations will require that the user daemon have the proper
+permissions to access the files. 
+.LP
+There are two example configuration files provided, /etc/inet/ntp.client and
+/etc/inet/ntp.server. The first provides examples and some discussion around
+the configuration information that goes into the /etc/inet/ntp.conf file. The
+second focuses exclusively on the configuration of hardware clocks for stratum
+zero servers and can be ignored by most users.
+.PP
+.SH EXAMPLES
+.LP
+The simplest way to start using the \fBNTP\fP service on a new host is to run
+the command:
+.sp
+.in +2
+.nf
+echo 'server hostname iburst' > /etc/inet/ntp.conf
+.fi
+.in -2
+.LP
+and then start the service. Replace 'hostname' with the actual hostname of an
+NTP server. You can add more lines like this one with the hostnames of more
+NTP servers, but do not configure exactly two. Four servers is optimal, but
+never use two.
 .PP
 .SH SEE ALSO
 .LP