diff options
Diffstat (limited to 'ntpd/ntpd.man.in')
| -rw-r--r-- | ntpd/ntpd.man.in | 987 |
1 files changed, 987 insertions, 0 deletions
diff --git a/ntpd/ntpd.man.in b/ntpd/ntpd.man.in new file mode 100644 index 0000000..a6824ca --- /dev/null +++ b/ntpd/ntpd.man.in @@ -0,0 +1,987 @@ +.de1 NOP +. it 1 an-trap +. if \\n[.$] \,\\$*\/ +.. +.ie t \ +.ds B-Font [CB] +.ds I-Font [CI] +.ds R-Font [CR] +.el \ +.ds B-Font B +.ds I-Font I +.ds R-Font R +.TH ntpd @NTPD_MS@ "02 Dec 2014" "4.2.7p482" "User Commands" +.\" +.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-AtaWSL/ag-MtaORL) +.\" +.\" It has been AutoGen-ed December 2, 2014 at 08:56:46 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntpd-opts.def +.\" and the template file agman-cmd.tpl +.SH NAME +\f\*[B-Font]ntpd\fP +\- NTP daemon program +.SH SYNOPSIS +\f\*[B-Font]ntpd\fP +.\" Mixture of short (flag) options and long options +[\f\*[B-Font]\-flags\f[]] +[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]] +[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]] +[ <server1> ... <serverN> ] +.sp \n(Ppu +.ne 2 + +.SH DESCRIPTION +The +\f\*[B-Font]ntpd\fP +utility is an operating system daemon which sets +and maintains the system time of day in synchronism with Internet +standard time servers. +It is a complete implementation of the +Network Time Protocol (NTP) version 4, as defined by RFC-5905, +but also retains compatibility with +version 3, as defined by RFC-1305, and versions 1 +and 2, as defined by RFC-1059 and RFC-1119, respectively. +.sp \n(Ppu +.ne 2 + +The +\f\*[B-Font]ntpd\fP +utility does most computations in 64-bit floating point +arithmetic and does relatively clumsy 64-bit fixed point operations +only when necessary to preserve the ultimate precision, about 232 +picoseconds. +While the ultimate precision is not achievable with +ordinary workstations and networks of today, it may be required +with future gigahertz CPU clocks and gigabit LANs. +.sp \n(Ppu +.ne 2 + +Ordinarily, +\f\*[B-Font]ntpd\fP +reads the +\fCntp.conf\fR(5)\f[] +configuration file at startup time in order to determine the +synchronization sources and operating modes. +It is also possible to +specify a working, although limited, configuration entirely on the +command line, obviating the need for a configuration file. +This may +be particularly useful when the local host is to be configured as a +broadcast/multicast client, with all peers being determined by +listening to broadcasts at run time. +.sp \n(Ppu +.ne 2 + +If NetInfo support is built into +\f\*[B-Font]ntpd\fP, +then +\f\*[B-Font]ntpd\fP +will attempt to read its configuration from the +NetInfo if the default +\fCntp.conf\fR(5)\f[] +file cannot be read and no file is +specified by the +\f\*[B-Font]\-c\f[] +option. +.sp \n(Ppu +.ne 2 + +Various internal +\f\*[B-Font]ntpd\fP +variables can be displayed and +configuration options altered while the +\f\*[B-Font]ntpd\fP +is running +using the +\fCntpq\fR(@NTPQ_MS@)\f[] +and +\fCntpdc\fR(@NTPDC_MS@)\f[] +utility programs. +.sp \n(Ppu +.ne 2 + +When +\f\*[B-Font]ntpd\fP +starts it looks at the value of +\fCumask\fR(2)\f[], +and if zero +\f\*[B-Font]ntpd\fP +will set the +\fCumask\fR(2)\f[] +to 022. +.SH "OPTIONS" +.TP +.NOP \f\*[B-Font]\-4\f[], \f\*[B-Font]\-\-ipv4\f[] +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.TP +.NOP \f\*[B-Font]\-6\f[], \f\*[B-Font]\-\-ipv6\f[] +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.TP +.NOP \f\*[B-Font]\-a\f[], \f\*[B-Font]\-\-authreq\f[] +Require crypto authentication. +This option must not appear in combination with any of the following options: +authnoreq. +.sp +Require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is the default. +.TP +.NOP \f\*[B-Font]\-A\f[], \f\*[B-Font]\-\-authnoreq\f[] +Do not require crypto authentication. +This option must not appear in combination with any of the following options: +authreq. +.sp +Do not require cryptographic authentication for broadcast client, +multicast client and symmetric passive associations. +This is almost never a good idea. +.TP +.NOP \f\*[B-Font]\-b\f[], \f\*[B-Font]\-\-bcastsync\f[] +Allow us to sync to broadcast servers. +.sp +.TP +.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-configfile\f[]=\f\*[I-Font]string\f[] +configuration file name. +.sp +The name and path of the configuration file, +\fI/etc/ntp.conf\fP +by default. +.TP +.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[] +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.TP +.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[] +Set the debug verbosity level. +This option may appear an unlimited number of times. +This option takes an integer number as its argument. +.sp +.TP +.NOP \f\*[B-Font]\-f\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-driftfile\f[]=\f\*[I-Font]string\f[] +frequency drift file name. +.sp +The name and path of the frequency file, +\fI/etc/ntp.drift\fP +by default. +This is the same operation as the +\fBdriftfile\fP \fIdriftfile\fP +configuration specification in the +\fI/etc/ntp.conf\fP +file. +.TP +.NOP \f\*[B-Font]\-g\f[], \f\*[B-Font]\-\-panicgate\f[] +Allow the first adjustment to be Big. +This option may appear an unlimited number of times. +.sp +Normally, +\fBntpd\fP +exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that, +\fBntpd\fP +will exit with a message to the system log. This option can be used with the +\fB-q\fP +and +\fB-x\fP +options. +See the +\fBtinker\fP +configuration file directive for other options. +.TP +.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-jaildir\f[]=\f\*[I-Font]string\f[] +Jail directory. +.sp +Chroot the server to the directory +\fIjaildir\fP +. +This option also implies that the server attempts to drop root privileges at startup. +You may need to also specify a +\fB-u\fP +option. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +\fB--enable-clockctl\fP) or Linux (configure with +\fB--enable-linuxcaps\fP) or Solaris (configure with \fB--enable-solarisprivs\fP). +.TP +.NOP \f\*[B-Font]\-I\f[] \f\*[I-Font]iface\f[], \f\*[B-Font]\-\-interface\f[]=\f\*[I-Font]iface\f[] +Listen on an interface name or address. +This option may appear an unlimited number of times. +.sp +Open the network address given, or all the addresses associated with the +given interface name. This option may appear multiple times. This option +also implies not opening other addresses, except wildcard and localhost. +This option is deprecated. Please consider using the configuration file +\fBinterface\fP command, which is more versatile. +.TP +.NOP \f\*[B-Font]\-k\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-keyfile\f[]=\f\*[I-Font]string\f[] +path to symmetric keys. +.sp +Specify the name and path of the symmetric key file. +\fI/etc/ntp.keys\fP +is the default. +This is the same operation as the +\fBkeys\fP \fIkeyfile\fP +configuration file directive. +.TP +.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]string\f[] +path to the log file. +.sp +Specify the name and path of the log file. +The default is the system log file. +This is the same operation as the +\fBlogfile\fP \fIlogfile\fP +configuration file directive. +.TP +.NOP \f\*[B-Font]\-L\f[], \f\*[B-Font]\-\-novirtualips\f[] +Do not listen to virtual interfaces. +.sp +Do not listen to virtual interfaces, defined as those with +names containing a colon. This option is deprecated. Please +consider using the configuration file \fBinterface\fP command, which +is more versatile. +.TP +.NOP \f\*[B-Font]\-M\f[], \f\*[B-Font]\-\-modifymmtimer\f[] +Modify Multimedia Timer (Windows only). +.sp +Set the Windows Multimedia Timer to highest resolution. This +ensures the resolution does not change while ntpd is running, +avoiding timekeeping glitches associated with changes. +.TP +.NOP \f\*[B-Font]\-n\f[], \f\*[B-Font]\-\-nofork\f[] +Do not fork. +This option must not appear in combination with any of the following options: +wait-sync. +.sp +.TP +.NOP \f\*[B-Font]\-N\f[], \f\*[B-Font]\-\-nice\f[] +Run at high priority. +.sp +To the extent permitted by the operating system, run +\fBntpd\fP +at the highest priority. +.TP +.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-pidfile\f[]=\f\*[I-Font]string\f[] +path to the PID file. +.sp +Specify the name and path of the file used to record +\fBntpd\fP's +process ID. +This is the same operation as the +\fBpidfile\fP \fIpidfile\fP +configuration file directive. +.TP +.NOP \f\*[B-Font]\-P\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-priority\f[]=\f\*[I-Font]number\f[] +Process priority. +This option takes an integer number as its argument. +.sp +To the extent permitted by the operating system, run +\fBntpd\fP +at the specified +\fBsched_setscheduler(SCHED_FIFO)\fP +priority. +.TP +.NOP \f\*[B-Font]\-q\f[], \f\*[B-Font]\-\-quit\f[] +Set the time and quit. +This option must not appear in combination with any of the following options: +saveconfigquit, wait-sync. +.sp +\fBntpd\fP +will not daemonize and will exit after the clock is first +synchronized. This behavior mimics that of the +\fBntpdate\fP +program, which will soon be replaced with a shell script. +The +\fB-g\fP +and +\fB-x\fP +options can be used with this option. +Note: The kernel time discipline is disabled with this option. +.TP +.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-propagationdelay\f[]=\f\*[I-Font]string\f[] +Broadcast/propagation delay. +.sp +Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol. +.TP +.NOP \f\*[B-Font]\-\-saveconfigquit\f[]=\f\*[I-Font]string\f[] +Save parsed configuration and quit. +This option must not appear in combination with any of the following options: +quit, wait-sync. +.sp +Cause \fBntpd\fP to parse its startup configuration file and save an +equivalent to the given filename and exit. This option was +designed for automated testing. +.TP +.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-statsdir\f[]=\f\*[I-Font]string\f[] +Statistics file location. +.sp +Specify the directory path for files created by the statistics facility. +This is the same operation as the +\fBstatsdir\fP \fIstatsdir\fP +configuration file directive. +.TP +.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]tkey\f[], \f\*[B-Font]\-\-trustedkey\f[]=\f\*[I-Font]tkey\f[] +Trusted key number. +This option may appear an unlimited number of times. +.sp +Add the specified key number to the trusted key list. +.TP +.NOP \f\*[B-Font]\-u\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-user\f[]=\f\*[I-Font]string\f[] +Run as userid (or userid:groupid). +.sp +Specify a user, and optionally a group, to switch to. +This option is only available if the OS supports adjusting the clock +without full root privileges. +This option is supported under NetBSD (configure with +\fB--enable-clockctl\fP) or Linux (configure with +\fB--enable-linuxcaps\fP) or Solaris (configure with \fB--enable-solarisprivs\fP). +.TP +.NOP \f\*[B-Font]\-U\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-updateinterval\f[]=\f\*[I-Font]number\f[] +interval in seconds between scans for new or dropped interfaces. +This option takes an integer number as its argument. +.sp +Give the time in seconds between two scans for new or dropped interfaces. +For systems with routing socket support the scans will be performed shortly after the interface change +has been detected by the system. +Use 0 to disable scanning. 60 seconds is the minimum time between scans. +.TP +.NOP \f\*[B-Font]\-\-var\f[]=\f\*[I-Font]nvar\f[] +make ARG an ntp variable (RW). +This option may appear an unlimited number of times. +.sp +.TP +.NOP \f\*[B-Font]\-\-dvar\f[]=\f\*[I-Font]ndvar\f[] +make ARG an ntp variable (RW|DEF). +This option may appear an unlimited number of times. +.sp +.TP +.NOP \f\*[B-Font]\-w\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-wait\-sync\f[]=\f\*[I-Font]number\f[] +Seconds to wait for first clock sync. +This option must not appear in combination with any of the following options: +nofork, quit, saveconfigquit. +This option takes an integer number as its argument. +.sp +If greater than zero, alters \fBntpd\fP's behavior when forking to +daemonize. Instead of exiting with status 0 immediately after +the fork, the parent waits up to the specified number of +seconds for the child to first synchronize the clock. The exit +status is zero (success) if the clock was synchronized, +otherwise it is \fBETIMEDOUT\fP. +This provides the option for a script starting \fBntpd\fP to easily +wait for the first set of the clock before proceeding. +.TP +.NOP \f\*[B-Font]\-x\f[], \f\*[B-Font]\-\-slew\f[] +Slew up to 600 seconds. +.sp +Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold. +This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. +Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. +Thus, an adjustment as much as 600 s will take almost 14 days to complete. +This option can be used with the +\fB-g\fP +and +\fB-q\fP +options. +See the +\fBtinker\fP +configuration file directive for other options. +Note: The kernel time discipline is disabled with this option. +.TP +.NOP \f\*[B-Font]\-\-usepcc\f[] +Use CPU cycle counter (Windows only). +.sp +Attempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. +The CPU counter and \fBQueryPerformanceCounter\fP are compared, and if +they have the same frequency, the CPU counter (RDTSC on x86) is +used directly, saving the overhead of a system call. +.TP +.NOP \f\*[B-Font]\-\-pccfreq\f[]=\f\*[I-Font]string\f[] +Force CPU cycle counter use (Windows only). +.sp +Force substitution the CPU counter for \fBQueryPerformanceCounter\fP. +The CPU counter (RDTSC on x86) is used unconditionally with the +given frequency (in Hz). +.TP +.NOP \f\*[B-Font]\-m\f[], \f\*[B-Font]\-\-mdns\f[] +Register with mDNS as a NTP server. +.sp +Registers as an NTP server with the local mDNS server which allows +the server to be discovered via mDNS client lookup. +.TP +.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] +Display usage information and exit. +.TP +.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] +Pass the extended usage information through a pager. +.TP +.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.PP +.SH "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTPD_<option-name>\fP or \fBNTPD\fP +.fi +.ad +.SH USAGE +.SS "How NTP Operates" +The +\f\*[B-Font]ntpd\fP +utility operates by exchanging messages with +one or more configured servers over a range of designated poll intervals. +When +started, whether for the first or subsequent times, the program +requires several exchanges from the majority of these servers so +the signal processing and mitigation algorithms can accumulate and +groom the data and set the clock. +In order to protect the network +from bursts, the initial poll interval for each server is delayed +an interval randomized over a few seconds. +At the default initial poll +interval of 64s, several minutes can elapse before the clock is +set. +This initial delay to set the clock +can be safely and dramatically reduced using the +\f\*[B-Font]iburst\f[] +keyword with the +\f\*[B-Font]server\f[] +configuration +command, as described in +\fCntp.conf\fR(5)\f[]. +.sp \n(Ppu +.ne 2 + +Most operating systems and hardware of today incorporate a +time-of-year (TOY) chip to maintain the time during periods when +the power is off. +When the machine is booted, the chip is used to +initialize the operating system time. +After the machine has +synchronized to a NTP server, the operating system corrects the +chip from time to time. +In the default case, if +\f\*[B-Font]ntpd\fP +detects that the time on the host +is more than 1000s from the server time, +\f\*[B-Font]ntpd\fP +assumes something must be terribly wrong and the only +reliable action is for the operator to intervene and set the clock +by hand. +(Reasons for this include there is no TOY chip, +or its battery is dead, or that the TOY chip is just of poor quality.) +This causes +\f\*[B-Font]ntpd\fP +to exit with a panic message to +the system log. +The +\f\*[B-Font]\-g\f[] +option overrides this check and the +clock will be set to the server time regardless of the chip time +(up to 68 years in the past or future \(em +this is a limitation of the NTPv4 protocol). +However, and to protect against broken hardware, such as when the +CMOS battery fails or the clock counter becomes defective, once the +clock has been set an error greater than 1000s will cause +\f\*[B-Font]ntpd\fP +to exit anyway. +.sp \n(Ppu +.ne 2 + +Under ordinary conditions, +\f\*[B-Font]ntpd\fP +adjusts the clock in +small steps so that the timescale is effectively continuous and +without discontinuities. +Under conditions of extreme network +congestion, the roundtrip delay jitter can exceed three seconds and +the synchronization distance, which is equal to one-half the +roundtrip delay plus error budget terms, can become very large. +The +\f\*[B-Font]ntpd\fP +algorithms discard sample offsets exceeding 128 ms, +unless the interval during which no sample offset is less than 128 +ms exceeds 900s. +The first sample after that, no matter what the +offset, steps the clock to the indicated time. +In practice this +reduces the false alarm rate where the clock is stepped in error to +a vanishingly low incidence. +.sp \n(Ppu +.ne 2 + +As the result of this behavior, once the clock has been set it +very rarely strays more than 128 ms even under extreme cases of +network path congestion and jitter. +Sometimes, in particular when +\f\*[B-Font]ntpd\fP +is first started without a valid drift file +on a system with a large intrinsic drift +the error might grow to exceed 128 ms, +which would cause the clock to be set backwards +if the local clock time is more than 128 s +in the future relative to the server. +In some applications, this behavior may be unacceptable. +There are several solutions, however. +If the +\f\*[B-Font]\-x\f[] +option is included on the command line, the clock will +never be stepped and only slew corrections will be used. +But this choice comes with a cost that +should be carefully explored before deciding to use +the +\f\*[B-Font]\-x\f[] +option. +The maximum slew rate possible is limited +to 500 parts-per-million (PPM) as a consequence of the correctness +principles on which the NTP protocol and algorithm design are +based. +As a result, the local clock can take a long time to +converge to an acceptable offset, about 2,000 s for each second the +clock is outside the acceptable range. +During this interval the +local clock will not be consistent with any other network clock and +the system cannot be used for distributed applications that require +correctly synchronized network time. +.sp \n(Ppu +.ne 2 + +In spite of the above precautions, sometimes when large +frequency errors are present the resulting time offsets stray +outside the 128-ms range and an eventual step or slew time +correction is required. +If following such a correction the +frequency error is so large that the first sample is outside the +acceptable range, +\f\*[B-Font]ntpd\fP +enters the same state as when the +\fIntp.drift\f[] +file is not present. +The intent of this behavior +is to quickly correct the frequency and restore operation to the +normal tracking mode. +In the most extreme cases +(the host +\f\*[B-Font]time.ien.it\f[] +comes to mind), there may be occasional +step/slew corrections and subsequent frequency corrections. +It +helps in these cases to use the +\f\*[B-Font]burst\f[] +keyword when +configuring the server, but +ONLY +when you have permission to do so from the owner of the target host. +.sp \n(Ppu +.ne 2 + +Finally, +in the past many startup scripts would run +\fCntpdate\fR(@NTPDATE_MS@)\f[] +to get the system clock close to correct before starting +\fCntpd\fR(@NTPD_MS@)\f[], +but this was never more than a mediocre hack and is no longer needed. +If you are following the instructions in +\fIStarting NTP (Best Current Practice)\f[] +and you still need to set the system time before starting +\f\*[B-Font]ntpd\fP, +please open a bug report and document what is going on, +and then look at using +\fCsntp\fR(@SNTP_MS@)\f[]. +.sp \n(Ppu +.ne 2 + +There is a way to start +\fCntpd\fR(@NTPD_MS@)\f[] +that often addresses all of the problems mentioned above. +.SS "Starting NTP (Best Current Practice)" +First, use the +\f\*[B-Font]iburst\f[] +option on your +\f\*[B-Font]server\f[] +entries. +.sp \n(Ppu +.ne 2 + +If you can also keep a good +\fIntp.drift\f[] +file then +\fCntpd\fR(@NTPD_MS@)\f[] +will effectively "warm-start" and your system's clock will +be stable in under 11 seconds' time. +.sp \n(Ppu +.ne 2 + +As soon as possible in the startup sequence, start +\fCntpd\fR(@NTPD_MS@)\f[] +with at least the +\f\*[B-Font]\-g\f[] +and perhaps the +\f\*[B-Font]\-N\f[] +options. +Then, +start the rest of your "normal" processes. +This will give +\fCntpd\fR(@NTPD_MS@)\f[] +as much time as possible to get the system's clock synchronized and stable. +.sp \n(Ppu +.ne 2 + +Finally, +if you have processes like +\f\*[B-Font]dovecot\f[] +or database servers +that require +monotonically-increasing time, +run +\fCntp-wait\fR(@NTP_WAIT_MS@)\f[] +as late as possible in the boot sequence +(perhaps with the +\f\*[B-Font]\-v\f[] +flag) +and after +\fCntp-wait\fR(@NTP_WAIT_MS@)\f[] +exits successfully +it is as safe as it will ever be to start any process that require +stable time. +.SS "Frequency Discipline" +The +\f\*[B-Font]ntpd\fP +behavior at startup depends on whether the +frequency file, usually +\fIntp.drift\f[], +exists. +This file +contains the latest estimate of clock frequency error. +When the +\f\*[B-Font]ntpd\fP +is started and the file does not exist, the +\f\*[B-Font]ntpd\fP +enters a special mode designed to quickly adapt to +the particular system clock oscillator time and frequency error. +This takes approximately 15 minutes, after which the time and +frequency are set to nominal values and the +\f\*[B-Font]ntpd\fP +enters +normal mode, where the time and frequency are continuously tracked +relative to the server. +After one hour the frequency file is +created and the current frequency offset written to it. +When the +\f\*[B-Font]ntpd\fP +is started and the file does exist, the +\f\*[B-Font]ntpd\fP +frequency is initialized from the file and enters normal mode +immediately. +After that the current frequency offset is written to +the file at hourly intervals. +.SS "Operating Modes" +The +\f\*[B-Font]ntpd\fP +utility can operate in any of several modes, including +symmetric active/passive, client/server broadcast/multicast and +manycast, as described in the +"Association Management" +page +(available as part of the HTML documentation +provided in +\fI/usr/share/doc/ntp\f[]). +It normally operates continuously while +monitoring for small changes in frequency and trimming the clock +for the ultimate precision. +However, it can operate in a one-time +mode where the time is set from an external server and frequency is +set from a previously recorded frequency file. +A +broadcast/multicast or manycast client can discover remote servers, +compute server-client propagation delay correction factors and +configure itself automatically. +This makes it possible to deploy a +fleet of workstations without specifying configuration details +specific to the local environment. +.sp \n(Ppu +.ne 2 + +By default, +\f\*[B-Font]ntpd\fP +runs in continuous mode where each of +possibly several external servers is polled at intervals determined +by an intricate state machine. +The state machine measures the +incidental roundtrip delay jitter and oscillator frequency wander +and determines the best poll interval using a heuristic algorithm. +Ordinarily, and in most operating environments, the state machine +will start with 64s intervals and eventually increase in steps to +1024s. +A small amount of random variation is introduced in order to +avoid bunching at the servers. +In addition, should a server become +unreachable for some time, the poll interval is increased in steps +to 1024s in order to reduce network overhead. +.sp \n(Ppu +.ne 2 + +In some cases it may not be practical for +\f\*[B-Font]ntpd\fP +to run continuously. +A common workaround has been to run the +\fCntpdate\fR(@NTPDATE_MS@)\f[] +or +\fCsntp\fR(@SNTP_MS@)\f[] +programs from a +\fCcron\fR(8)\f[] +job at designated +times. +However, these programs do not have the crafted signal +processing, error checking or mitigation algorithms of +\f\*[B-Font]ntpd\fP. +The +\f\*[B-Font]\-q\f[] +option is intended for this purpose. +Setting this option will cause +\f\*[B-Font]ntpd\fP +to exit just after +setting the clock for the first time. +The procedure for initially +setting the clock is the same as in continuous mode; most +applications will probably want to specify the +\f\*[B-Font]iburst\f[] +keyword with the +\f\*[B-Font]server\f[] +configuration command. +With this +keyword a volley of messages are exchanged to groom the data and +the clock is set in about 10 s. +If nothing is heard after a +couple of minutes, the daemon times out and exits. +After a suitable +period of mourning, the +\fCntpdate\fR(@NTPDATE_MS@)\f[] +program will be +retired. +.sp \n(Ppu +.ne 2 + +When kernel support is available to discipline the clock +frequency, which is the case for stock Solaris, Tru64, Linux and +FreeBSD, +a useful feature is available to discipline the clock +frequency. +First, +\f\*[B-Font]ntpd\fP +is run in continuous mode with +selected servers in order to measure and record the intrinsic clock +frequency offset in the frequency file. +It may take some hours for +the frequency and offset to settle down. +Then the +\f\*[B-Font]ntpd\fP +is +stopped and run in one-time mode as required. +At each startup, the +frequency is read from the file and initializes the kernel +frequency. +.SS "Poll Interval Control" +This version of NTP includes an intricate state machine to +reduce the network load while maintaining a quality of +synchronization consistent with the observed jitter and wander. +There are a number of ways to tailor the operation in order enhance +accuracy by reducing the interval or to reduce network overhead by +increasing it. +However, the user is advised to carefully consider +the consequences of changing the poll adjustment range from the +default minimum of 64 s to the default maximum of 1,024 s. +The +default minimum can be changed with the +\f\*[B-Font]tinker\f[] +\f\*[B-Font]minpoll\f[] +command to a value not less than 16 s. +This value is used for all +configured associations, unless overridden by the +\f\*[B-Font]minpoll\f[] +option on the configuration command. +Note that most device drivers +will not operate properly if the poll interval is less than 64 s +and that the broadcast server and manycast client associations will +also use the default, unless overridden. +.sp \n(Ppu +.ne 2 + +In some cases involving dial up or toll services, it may be +useful to increase the minimum interval to a few tens of minutes +and maximum interval to a day or so. +Under normal operation +conditions, once the clock discipline loop has stabilized the +interval will be increased in steps from the minimum to the +maximum. +However, this assumes the intrinsic clock frequency error +is small enough for the discipline loop correct it. +The capture +range of the loop is 500 PPM at an interval of 64s decreasing by a +factor of two for each doubling of interval. +At a minimum of 1,024 +s, for example, the capture range is only 31 PPM. +If the intrinsic +error is greater than this, the drift file +\fIntp.drift\f[] +will +have to be specially tailored to reduce the residual error below +this limit. +Once this is done, the drift file is automatically +updated once per hour and is available to initialize the frequency +on subsequent daemon restarts. +.SS "The huff-n'-puff Filter" +In scenarios where a considerable amount of data are to be +downloaded or uploaded over telephone modems, timekeeping quality +can be seriously degraded. +This occurs because the differential +delays on the two directions of transmission can be quite large. +In +many cases the apparent time errors are so large as to exceed the +step threshold and a step correction can occur during and after the +data transfer is in progress. +.sp \n(Ppu +.ne 2 + +The huff-n'-puff filter is designed to correct the apparent time +offset in these cases. +It depends on knowledge of the propagation +delay when no other traffic is present. +In common scenarios this +occurs during other than work hours. +The filter maintains a shift +register that remembers the minimum delay over the most recent +interval measured usually in hours. +Under conditions of severe +delay, the filter corrects the apparent offset using the sign of +the offset and the difference between the apparent delay and +minimum delay. +The name of the filter reflects the negative (huff) +and positive (puff) correction, which depends on the sign of the +offset. +.sp \n(Ppu +.ne 2 + +The filter is activated by the +\f\*[B-Font]tinker\f[] +command and +\f\*[B-Font]huffpuff\f[] +keyword, as described in +\fCntp.conf\fR(5)\f[]. +.SH "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.SH FILES +.TP 15 +.NOP \fI/etc/ntp.conf\f[] +the default name of the configuration file +.br +.ns +.TP 15 +.NOP \fI/etc/ntp.drift\f[] +the default name of the drift file +.br +.ns +.TP 15 +.NOP \fI/etc/ntp.keys\f[] +the default name of the key file +.PP +.SH "EXIT STATUS" +One of the following exit values will be returned: +.TP +.NOP 0 " (EXIT_SUCCESS)" +Successful program execution. +.TP +.NOP 1 " (EXIT_FAILURE)" +The operation failed or the command syntax was not valid. +.TP +.NOP 70 " (EX_SOFTWARE)" +libopts had an internal operational error. Please report +it to autogen-users@lists.sourceforge.net. Thank you. +.PP +.SH "SEE ALSO" +\fCntp.conf\fR(5)\f[], +\fCntpdate\fR(@NTPDATE_MS@)\f[], +\fCntpdc\fR(@NTPDC_MS@)\f[], +\fCntpq\fR(@NTPQ_MS@)\f[], +\fCsntp\fR(@SNTP_MS@)\f[] +.sp \n(Ppu +.ne 2 + +In addition to the manual pages provided, +comprehensive documentation is available on the world wide web +at +\f[C]http://www.ntp.org/\f[]. +A snapshot of this documentation is available in HTML format in +\fI/usr/share/doc/ntp\f[]. +David L. Mills, +\fINetwork Time Protocol (Version 1)\fR, +RFC1059 +.PP + +David L. Mills, +\fINetwork Time Protocol (Version 2)\fR, +RFC1119 +.PP + +David L. Mills, +\fINetwork Time Protocol (Version 3)\fR, +RFC1305 +.PP + +David L. Mills and J. Martin, Ed. and J. Burbank and W. Kasch, +\fINetwork Time Protocol Version 4: Protocol and Algorithms Specification\fR, +RFC5905 +.PP + +David L. Mills and B. Haberman, Ed., +\fINetwork Time Protocol Version 4: Autokey Specification\fR, +RFC5906 +.PP + +H. Gerstung and C. Elliott and B. Haberman, Ed., +\fIDefinitions of Managed Objects for Network Time Protocol Version 4: (NTPv4)\fR, +RFC5907 +.PP + +R. Gayraud and B. Lourdelet, +\fINetwork Time Protocol (NTP) Server Option for DHCPv6\fR, +RFC5908 +.PP + +.SH "AUTHORS" +The University of Delaware +.SH "COPYRIGHT" +Copyright (C) 1970-2014 The University of Delaware all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.SH BUGS +The +\f\*[B-Font]ntpd\fP +utility has gotten rather fat. +While not huge, it has gotten +larger than might be desirable for an elevated-priority +\f\*[B-Font]ntpd\fP +running on a workstation, particularly since many of +the fancy features which consume the space were designed more with +a busy primary server, rather than a high stratum workstation in +mind. +.sp \n(Ppu +.ne 2 + +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.SH NOTES +Portions of this document came from FreeBSD. +.sp \n(Ppu +.ne 2 + +This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP +option definitions. |