ntpd.8 revision 294905
1251188Smarcel.Dd January 20 2016 229088Smarkm.Dt NTPD 8 User Commands 329088Smarkm.Os 429088Smarkm.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) 529088Smarkm.\" 629088Smarkm.\" $FreeBSD: releng/9.3/usr.sbin/ntp/doc/ntpd.8 294905 2016-01-27 07:42:11Z delphij $ 729088Smarkm.\" 829088Smarkm.\" It has been AutoGen-ed January 20, 2016 at 04:18:12 AM by AutoGen 5.18.5 929088Smarkm.\" From the definitions ntpd-opts.def 1029088Smarkm.\" and the template file agmdoc-cmd.tpl 1129088Smarkm.Sh NAME 1229088Smarkm.Nm ntpd 1329088Smarkm.Nd NTP daemon program 1429088Smarkm.Sh SYNOPSIS 1529088Smarkm.Nm 1629088Smarkm.\" Mixture of short (flag) options and long options 1729088Smarkm.Op Fl flags 1829088Smarkm.Op Fl flag Op Ar value 1929088Smarkm.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 2029088Smarkm[ <server1> ... <serverN> ] 2129088Smarkm.Pp 2229088Smarkm.Sh DESCRIPTION 2329088SmarkmThe 2429088Smarkm.Nm 2529088Smarkmutility is an operating system daemon which sets 2629088Smarkmand maintains the system time of day in synchronism with Internet 2729088Smarkmstandard time servers. 2829088SmarkmIt is a complete implementation of the 2929088SmarkmNetwork Time Protocol (NTP) version 4, as defined by RFC\-5905, 3029088Smarkmbut also retains compatibility with 3129088Smarkmversion 3, as defined by RFC\-1305, and versions 1 3229088Smarkmand 2, as defined by RFC\-1059 and RFC\-1119, respectively. 3329088Smarkm.Pp 34114630SobrienThe 3529088Smarkm.Nm 3629181Smarkmutility does most computations in 64\-bit floating point 3731622Scharnierarithmetic and does relatively clumsy 64\-bit fixed point operations 38114630Sobrienonly when necessary to preserve the ultimate precision, about 232 39114630Sobrienpicoseconds. 40114630SobrienWhile the ultimate precision is not achievable with 4129088Smarkmordinary workstations and networks of today, it may be required 4287139Smarkmwith future gigahertz CPU clocks and gigabit LANs. 4387139Smarkm.Pp 4487139SmarkmOrdinarily, 4587139Smarkm.Nm 4687139Smarkmreads the 4729088Smarkm.Xr ntp.conf 5 4829088Smarkmconfiguration file at startup time in order to determine the 4929088Smarkmsynchronization sources and operating modes. 5087139SmarkmIt is also possible to 5129088Smarkmspecify a working, although limited, configuration entirely on the 5229088Smarkmcommand line, obviating the need for a configuration file. 5329088SmarkmThis may 5487139Smarkmbe particularly useful when the local host is to be configured as a 5529181Smarkmbroadcast/multicast client, with all peers being determined by 5629181Smarkmlistening to broadcasts at run time. 5787139Smarkm.Pp 5887139SmarkmIf NetInfo support is built into 5929181Smarkm.Nm , 6029088Smarkmthen 6129088Smarkm.Nm 6229088Smarkmwill attempt to read its configuration from the 6329088SmarkmNetInfo if the default 6429088Smarkm.Xr ntp.conf 5 6529088Smarkmfile cannot be read and no file is 6629088Smarkmspecified by the 6729088Smarkm.Fl c 6829088Smarkmoption. 6929088Smarkm.Pp 7029088SmarkmVarious internal 7129088Smarkm.Nm 7229088Smarkmvariables can be displayed and 7329088Smarkmconfiguration options altered while the 7429088Smarkm.Nm 7529088Smarkmis running 7629088Smarkmusing the 7729088Smarkm.Xr ntpq 8 7829088Smarkmand 7929088Smarkm.Xr ntpdc 8 8029088Smarkmutility programs. 8129088Smarkm.Pp 8229088SmarkmWhen 8329088Smarkm.Nm 8429088Smarkmstarts it looks at the value of 8529088Smarkm.Xr umask 2 , 8629088Smarkmand if zero 8729088Smarkm.Nm 8829088Smarkmwill set the 8929088Smarkm.Xr umask 2 9029088Smarkmto 022. 9129088Smarkm.Sh "OPTIONS" 9229088Smarkm.Bl -tag 9329088Smarkm.It Fl 4 , Fl \-ipv4 9429088SmarkmForce IPv4 DNS name resolution. 9529088SmarkmThis option must not appear in combination with any of the following options: 9629088Smarkmipv6. 9729088Smarkm.sp 9829088SmarkmForce DNS resolution of following host names on the command line 9929088Smarkmto the IPv4 namespace. 10029088Smarkm.It Fl 6 , Fl \-ipv6 10129088SmarkmForce IPv6 DNS name resolution. 10229088SmarkmThis option must not appear in combination with any of the following options: 10329088Smarkmipv4. 10429088Smarkm.sp 10529088SmarkmForce DNS resolution of following host names on the command line 10629088Smarkmto the IPv6 namespace. 10729088Smarkm.It Fl a , Fl \-authreq 10829088SmarkmRequire crypto authentication. 10929088SmarkmThis option must not appear in combination with any of the following options: 11029088Smarkmauthnoreq. 11129088Smarkm.sp 11229088SmarkmRequire cryptographic authentication for broadcast client, 11329088Smarkmmulticast client and symmetric passive associations. 11429088SmarkmThis is the default. 11529088Smarkm.It Fl A , Fl \-authnoreq 11629088SmarkmDo not require crypto authentication. 11729088SmarkmThis option must not appear in combination with any of the following options: 11829088Smarkmauthreq. 11929088Smarkm.sp 12029088SmarkmDo not require cryptographic authentication for broadcast client, 12129088Smarkmmulticast client and symmetric passive associations. 12229088SmarkmThis is almost never a good idea. 12329088Smarkm.It Fl b , Fl \-bcastsync 12429088SmarkmAllow us to sync to broadcast servers. 12529088Smarkm.sp 12631622Scharnier.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string 12731622Scharnierconfiguration file name. 12831622Scharnier.sp 12987155SmarkmThe name and path of the configuration file, 13087155Smarkm\fI/etc/ntp.conf\fP 13187155Smarkmby default. 13231622Scharnier.It Fl d , Fl \-debug\-level 13329088SmarkmIncrease debug verbosity level. 13429088SmarkmThis option may appear an unlimited number of times. 13529088Smarkm.sp 13629088Smarkm.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 13729088SmarkmSet the debug verbosity level. 13829088SmarkmThis option may appear an unlimited number of times. 13929088SmarkmThis option takes an integer number as its argument. 14029088Smarkm.sp 14129088Smarkm.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string 14229088Smarkmfrequency drift file name. 14329088Smarkm.sp 14487139SmarkmThe name and path of the frequency file, 14587139Smarkm\fI/etc/ntp.drift\fP 14629088Smarkmby default. 14729088SmarkmThis is the same operation as the 14829088Smarkm\fBdriftfile\fP \fIdriftfile\fP 14929088Smarkmconfiguration specification in the 15029088Smarkm\fI/etc/ntp.conf\fP 15129088Smarkmfile. 15229088Smarkm.It Fl g , Fl \-panicgate 15329088SmarkmAllow the first adjustment to be Big. 15429088SmarkmThis option may appear an unlimited number of times. 15529088Smarkm.sp 15629088SmarkmNormally, 15729088Smarkm\fBntpd\fP 15829088Smarkmexits 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, 15929088Smarkm\fBntpd\fP 16029088Smarkmwill exit with a message to the system log. This option can be used with the 16187139Smarkm\fB\-q\fP 16287139Smarkmand 16329088Smarkm\fB\-x\fP 16429088Smarkmoptions. 16529088SmarkmSee the 16629088Smarkm\fBtinker\fP 16729088Smarkmconfiguration file directive for other options. 16829088Smarkm.It Fl G , Fl \-force\-step\-once 16929088SmarkmStep any initial offset correction.. 17029088Smarkm.sp 17187139SmarkmNormally, 17287139Smarkm\fBntpd\fP 17329088Smarkmsteps the time if the time offset exceeds the step threshold, 17429088Smarkmwhich is 128 ms by default, and otherwise slews the time. 17529088SmarkmThis option forces the initial offset correction to be stepped, 17629088Smarkmso the highest time accuracy can be achieved quickly. 17729088SmarkmHowever, this may also cause the time to be stepped back 17829088Smarkmso this option must not be used if 17929088Smarkmapplications requiring monotonic time are running. 18029088SmarkmSee the \fBtinker\fP configuration file directive for other options. 18129088Smarkm.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string 18229088SmarkmJail directory. 18329088Smarkm.sp 18429088SmarkmChroot the server to the directory 18529088Smarkm\fIjaildir\fP 18629088Smarkm. 18729088SmarkmThis option also implies that the server attempts to drop root privileges at startup. 18829088SmarkmYou may need to also specify a 18929088Smarkm\fB\-u\fP 19029088Smarkmoption. 19129088SmarkmThis option is only available if the OS supports adjusting the clock 19229088Smarkmwithout full root privileges. 19329088SmarkmThis option is supported under NetBSD (configure with 19429088Smarkm\fB\-\-enable\-clockctl\fP) or Linux (configure with 19529088Smarkm\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 19629088Smarkm.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface 19729088SmarkmListen on an interface name or address. 19829088SmarkmThis option may appear an unlimited number of times. 19929088Smarkm.sp 20029088SmarkmOpen the network address given, or all the addresses associated with the 20129088Smarkmgiven interface name. This option may appear multiple times. This option 20229088Smarkmalso implies not opening other addresses, except wildcard and localhost. 20329088SmarkmThis option is deprecated. Please consider using the configuration file 20429088Smarkm\fBinterface\fP command, which is more versatile. 20529088Smarkm.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string 20629088Smarkmpath to symmetric keys. 20729088Smarkm.sp 20887139SmarkmSpecify the name and path of the symmetric key file. 20987139Smarkm\fI/etc/ntp.keys\fP 21029088Smarkmis the default. 21129088SmarkmThis is the same operation as the 21229088Smarkm\fBkeys\fP \fIkeyfile\fP 21329088Smarkmconfiguration file directive. 21429088Smarkm.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string 21529088Smarkmpath to the log file. 21629088Smarkm.sp 21729088SmarkmSpecify the name and path of the log file. 21829088SmarkmThe default is the system log file. 21929088SmarkmThis is the same operation as the 22029088Smarkm\fBlogfile\fP \fIlogfile\fP 22129088Smarkmconfiguration file directive. 22229088Smarkm.It Fl L , Fl \-novirtualips 22329088SmarkmDo not listen to virtual interfaces. 22429088Smarkm.sp 22529088SmarkmDo not listen to virtual interfaces, defined as those with 22629088Smarkmnames containing a colon. This option is deprecated. Please 22729088Smarkmconsider using the configuration file \fBinterface\fP command, which 22829088Smarkmis more versatile. 22929088Smarkm.It Fl M , Fl \-modifymmtimer 23029088SmarkmModify Multimedia Timer (Windows only). 23129088Smarkm.sp 23229088SmarkmSet the Windows Multimedia Timer to highest resolution. This 23329088Smarkmensures the resolution does not change while ntpd is running, 23429088Smarkmavoiding timekeeping glitches associated with changes. 23529088Smarkm.It Fl n , Fl \-nofork 23629088SmarkmDo not fork. 23729088SmarkmThis option must not appear in combination with any of the following options: 23829088Smarkmwait\-sync. 23929088Smarkm.sp 24029088Smarkm.It Fl N , Fl \-nice 24129088SmarkmRun at high priority. 24229088Smarkm.sp 24329088SmarkmTo the extent permitted by the operating system, run 24429088Smarkm\fBntpd\fP 24529088Smarkmat the highest priority. 24629088Smarkm.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string 24729088Smarkmpath to the PID file. 24829088Smarkm.sp 24929088SmarkmSpecify the name and path of the file used to record 25029088Smarkm\fBntpd\fP's 25129088Smarkmprocess ID. 25229088SmarkmThis is the same operation as the 25329088Smarkm\fBpidfile\fP \fIpidfile\fP 25429088Smarkmconfiguration file directive. 25529088Smarkm.It Fl P Ar number , Fl \-priority Ns = Ns Ar number 25629088SmarkmProcess priority. 25729088SmarkmThis option takes an integer number as its argument. 25829088Smarkm.sp 25929088SmarkmTo the extent permitted by the operating system, run 26029088Smarkm\fBntpd\fP 26129088Smarkmat the specified 26229088Smarkm\fBsched_setscheduler(SCHED_FIFO)\fP 26329088Smarkmpriority. 26429088Smarkm.It Fl q , Fl \-quit 26529088SmarkmSet the time and quit. 26629088SmarkmThis option must not appear in combination with any of the following options: 26729088Smarkmsaveconfigquit, wait\-sync. 26829088Smarkm.sp 26929088Smarkm\fBntpd\fP 27029088Smarkmwill not daemonize and will exit after the clock is first 27129088Smarkmsynchronized. This behavior mimics that of the 27229088Smarkm\fBntpdate\fP 27329088Smarkmprogram, which will soon be replaced with a shell script. 27429088SmarkmThe 27529088Smarkm\fB\-g\fP 27629088Smarkmand 27729088Smarkm\fB\-x\fP 27829088Smarkmoptions can be used with this option. 27929088SmarkmNote: The kernel time discipline is disabled with this option. 28029088Smarkm.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string 28129088SmarkmBroadcast/propagation delay. 28229088Smarkm.sp 28329088SmarkmSpecify 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. 28429088Smarkm.It Fl \-saveconfigquit Ns = Ns Ar string 28529088SmarkmSave parsed configuration and quit. 28687139SmarkmThis option must not appear in combination with any of the following options: 28787139Smarkmquit, wait\-sync. 28887139Smarkm.sp 28929088SmarkmCause \fBntpd\fP to parse its startup configuration file and save an 29029088Smarkmequivalent to the given filename and exit. This option was 29129088Smarkmdesigned for automated testing. 29229088Smarkm.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string 29329088SmarkmStatistics file location. 29429088Smarkm.sp 29529088SmarkmSpecify the directory path for files created by the statistics facility. 29629088SmarkmThis is the same operation as the 29729088Smarkm\fBstatsdir\fP \fIstatsdir\fP 29829088Smarkmconfiguration file directive. 29929088Smarkm.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey 30029088SmarkmTrusted key number. 30129088SmarkmThis option may appear an unlimited number of times. 30229088Smarkm.sp 30329088SmarkmAdd the specified key number to the trusted key list. 30429088Smarkm.It Fl u Ar string , Fl \-user Ns = Ns Ar string 30529088SmarkmRun as userid (or userid:groupid). 30629088Smarkm.sp 30729088SmarkmSpecify a user, and optionally a group, to switch to. 30829088SmarkmThis option is only available if the OS supports adjusting the clock 30929088Smarkmwithout full root privileges. 31029088SmarkmThis option is supported under NetBSD (configure with 31129088Smarkm\fB\-\-enable\-clockctl\fP) or Linux (configure with 31229088Smarkm\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). 31329088Smarkm.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number 31429088Smarkminterval in seconds between scans for new or dropped interfaces. 31529088SmarkmThis option takes an integer number as its argument. 31629088Smarkm.sp 31729088SmarkmGive the time in seconds between two scans for new or dropped interfaces. 31829088SmarkmFor systems with routing socket support the scans will be performed shortly after the interface change 31929088Smarkmhas been detected by the system. 32029088SmarkmUse 0 to disable scanning. 60 seconds is the minimum time between scans. 32129088Smarkm.It Fl \-var Ns = Ns Ar nvar 32229088Smarkmmake ARG an ntp variable (RW). 32329088SmarkmThis option may appear an unlimited number of times. 32429088Smarkm.sp 32529088Smarkm.It Fl \-dvar Ns = Ns Ar ndvar 32629088Smarkmmake ARG an ntp variable (RW|DEF). 32729088SmarkmThis option may appear an unlimited number of times. 32829088Smarkm.sp 32929088Smarkm.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number 33029088SmarkmSeconds to wait for first clock sync. 33129088SmarkmThis option must not appear in combination with any of the following options: 33229088Smarkmnofork, quit, saveconfigquit. 33329088SmarkmThis option takes an integer number as its argument. 33429088Smarkm.sp 33529088SmarkmIf greater than zero, alters \fBntpd\fP's behavior when forking to 33629088Smarkmdaemonize. Instead of exiting with status 0 immediately after 33729088Smarkmthe fork, the parent waits up to the specified number of 33829088Smarkmseconds for the child to first synchronize the clock. The exit 33929088Smarkmstatus is zero (success) if the clock was synchronized, 34029088Smarkmotherwise it is \fBETIMEDOUT\fP. 34129088SmarkmThis provides the option for a script starting \fBntpd\fP to easily 34229088Smarkmwait for the first set of the clock before proceeding. 34329088Smarkm.It Fl x , Fl \-slew 34429088SmarkmSlew up to 600 seconds. 34529088Smarkm.sp 34629088SmarkmNormally, 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. 34729088SmarkmThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 34829088SmarkmNote: 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. 34929088SmarkmThus, an adjustment as much as 600 s will take almost 14 days to complete. 35029088SmarkmThis option can be used with the 35129088Smarkm\fB\-g\fP 35229088Smarkmand 35329088Smarkm\fB\-q\fP 35429088Smarkmoptions. 35529088SmarkmSee the 35629088Smarkm\fBtinker\fP 35729088Smarkmconfiguration file directive for other options. 35829088SmarkmNote: The kernel time discipline is disabled with this option. 35929088Smarkm.It Fl \-usepcc 36029088SmarkmUse CPU cycle counter (Windows only). 36129088Smarkm.sp 36229088SmarkmAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 36329088SmarkmThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 36429088Smarkmthey have the same frequency, the CPU counter (RDTSC on x86) is 36529088Smarkmused directly, saving the overhead of a system call. 36629088Smarkm.It Fl \-pccfreq Ns = Ns Ar string 36729088SmarkmForce CPU cycle counter use (Windows only). 36829088Smarkm.sp 36929088SmarkmForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 37029088SmarkmThe CPU counter (RDTSC on x86) is used unconditionally with the 37129088Smarkmgiven frequency (in Hz). 37229088Smarkm.It Fl m , Fl \-mdns 37329088SmarkmRegister with mDNS as a NTP server. 37429088Smarkm.sp 37529088SmarkmRegisters as an NTP server with the local mDNS server which allows 37629088Smarkmthe server to be discovered via mDNS client lookup. 37729088Smarkm.It Fl \&? , Fl \-help 37829088SmarkmDisplay usage information and exit. 37929088Smarkm.It Fl \&! , Fl \-more\-help 38029088SmarkmPass the extended usage information through a pager. 381184935Sed.It Fl \-version Op Brq Ar v|c|n 38229088SmarkmOutput version of program and exit. The default mode is `v', a simple 38387139Smarkmversion. The `c' mode will print copyright information and `n' will 38487139Smarkmprint the full copyright notice. 38529088Smarkm.El 38687139Smarkm.Sh "OPTION PRESETS" 387184935SedAny option that is not marked as \fInot presettable\fP may be preset 38829088Smarkmby loading values from environment variables named: 389184935Sed.nf 390184935Sed \fBNTPD_<option\-name>\fP or \fBNTPD\fP 391184935Sed.fi 392184935Sed.ad 393184935Sed.Sh USAGE 394184935Sed.Ss "How NTP Operates" 39529088SmarkmThe 396184935Sed.Nm 397184935Sedutility operates by exchanging messages with 398184935Sedone or more configured servers over a range of designated poll intervals. 399184935SedWhen 400184935Sedstarted, whether for the first or subsequent times, the program 401184935Sedrequires several exchanges from the majority of these servers so 402184935Sedthe signal processing and mitigation algorithms can accumulate and 403184938Sedgroom the data and set the clock. 404184938SedIn order to protect the network 40529088Smarkmfrom bursts, the initial poll interval for each server is delayed 406184935Sedan interval randomized over a few seconds. 40729088SmarkmAt the default initial poll 40829088Smarkminterval of 64s, several minutes can elapse before the clock is 40929088Smarkmset. 41029088SmarkmThis initial delay to set the clock 41129088Smarkmcan be safely and dramatically reduced using the 41229088Smarkm.Cm iburst 41329088Smarkmkeyword with the 41429088Smarkm.Ic server 41529088Smarkmconfiguration 41629088Smarkmcommand, as described in 41729088Smarkm.Xr ntp.conf 5 . 41829088Smarkm.Pp 41929088SmarkmMost operating systems and hardware of today incorporate a 42029088Smarkmtime\-of\-year (TOY) chip to maintain the time during periods when 42129088Smarkmthe power is off. 42229088SmarkmWhen the machine is booted, the chip is used to 42329088Smarkminitialize the operating system time. 42429088SmarkmAfter the machine has 42529088Smarkmsynchronized to a NTP server, the operating system corrects the 42629088Smarkmchip from time to time. 42729088SmarkmIn the default case, if 42829088Smarkm.Nm 42929088Smarkmdetects that the time on the host 43029088Smarkmis more than 1000s from the server time, 43129088Smarkm.Nm 43287139Smarkmassumes something must be terribly wrong and the only 43387139Smarkmreliable action is for the operator to intervene and set the clock 43429088Smarkmby hand. 43529088Smarkm(Reasons for this include there is no TOY chip, 43629088Smarkmor its battery is dead, or that the TOY chip is just of poor quality.) 43729088SmarkmThis causes 43829088Smarkm.Nm 43929088Smarkmto exit with a panic message to 44029088Smarkmthe system log. 44129088SmarkmThe 44287139Smarkm.Fl g 44387139Smarkmoption overrides this check and the 44429088Smarkmclock will be set to the server time regardless of the chip time 44529088Smarkm(up to 68 years in the past or future \(em 44629088Smarkmthis is a limitation of the NTPv4 protocol). 44729088SmarkmHowever, and to protect against broken hardware, such as when the 44829088SmarkmCMOS battery fails or the clock counter becomes defective, once the 44929088Smarkmclock has been set an error greater than 1000s will cause 45029088Smarkm.Nm 45129088Smarkmto exit anyway. 45229088Smarkm.Pp 45329088SmarkmUnder ordinary conditions, 45429088Smarkm.Nm 45529088Smarkmadjusts the clock in 45629088Smarkmsmall steps so that the timescale is effectively continuous and 45729088Smarkmwithout discontinuities. 45829088SmarkmUnder conditions of extreme network 45929088Smarkmcongestion, the roundtrip delay jitter can exceed three seconds and 46087139Smarkmthe synchronization distance, which is equal to one\-half the 46187139Smarkmroundtrip delay plus error budget terms, can become very large. 46229088SmarkmThe 46329088Smarkm.Nm 46429088Smarkmalgorithms discard sample offsets exceeding 128 ms, 46529088Smarkmunless the interval during which no sample offset is less than 128 46629088Smarkmms exceeds 900s. 46729088SmarkmThe first sample after that, no matter what the 46829088Smarkmoffset, steps the clock to the indicated time. 46929088SmarkmIn practice this 47087139Smarkmreduces the false alarm rate where the clock is stepped in error to 47187139Smarkma vanishingly low incidence. 47229088Smarkm.Pp 47329088SmarkmAs the result of this behavior, once the clock has been set it 47429088Smarkmvery rarely strays more than 128 ms even under extreme cases of 47529088Smarkmnetwork path congestion and jitter. 47629088SmarkmSometimes, in particular when 47729088Smarkm.Nm 47829088Smarkmis first started without a valid drift file 47929088Smarkmon a system with a large intrinsic drift 48087139Smarkmthe error might grow to exceed 128 ms, 48187139Smarkmwhich would cause the clock to be set backwards 48229088Smarkmif the local clock time is more than 128 s 48329088Smarkmin the future relative to the server. 48429088SmarkmIn some applications, this behavior may be unacceptable. 48529088SmarkmThere are several solutions, however. 48629088SmarkmIf the 48729088Smarkm.Fl x 48829088Smarkmoption is included on the command line, the clock will 48929088Smarkmnever be stepped and only slew corrections will be used. 49029088SmarkmBut this choice comes with a cost that 49129088Smarkmshould be carefully explored before deciding to use 49229088Smarkmthe 49329088Smarkm.Fl x 49487139Smarkmoption. 49587139SmarkmThe maximum slew rate possible is limited 49629088Smarkmto 500 parts\-per\-million (PPM) as a consequence of the correctness 49729088Smarkmprinciples on which the NTP protocol and algorithm design are 49829088Smarkmbased. 49929088SmarkmAs a result, the local clock can take a long time to 50029088Smarkmconverge to an acceptable offset, about 2,000 s for each second the 50129088Smarkmclock is outside the acceptable range. 50229088SmarkmDuring this interval the 50329088Smarkmlocal clock will not be consistent with any other network clock and 50429088Smarkmthe system cannot be used for distributed applications that require 50529088Smarkmcorrectly synchronized network time. 50629088Smarkm.Pp 50729088SmarkmIn spite of the above precautions, sometimes when large 50829088Smarkmfrequency errors are present the resulting time offsets stray 50929088Smarkmoutside the 128\-ms range and an eventual step or slew time 51087139Smarkmcorrection is required. 51187139SmarkmIf following such a correction the 51229088Smarkmfrequency error is so large that the first sample is outside the 51329088Smarkmacceptable range, 51429088Smarkm.Nm 51529088Smarkmenters the same state as when the 51629088Smarkm.Pa ntp.drift 51729088Smarkmfile is not present. 51829088SmarkmThe intent of this behavior 51929088Smarkmis to quickly correct the frequency and restore operation to the 52087139Smarkmnormal tracking mode. 52187139SmarkmIn the most extreme cases 52287139Smarkm(the host 52387139Smarkm.Cm time.ien.it 52429088Smarkmcomes to mind), there may be occasional 52529088Smarkmstep/slew corrections and subsequent frequency corrections. 52629088SmarkmIt 52729088Smarkmhelps in these cases to use the 52829088Smarkm.Cm burst 52929088Smarkmkeyword when 53029088Smarkmconfiguring the server, but 53129088SmarkmONLY 53229088Smarkmwhen you have permission to do so from the owner of the target host. 53329088Smarkm.Pp 53429088SmarkmFinally, 53529088Smarkmin the past many startup scripts would run 53629088Smarkm.Xr ntpdate 8 53729088Smarkmor 53887139Smarkm.Xr sntp 8 53929088Smarkmto get the system clock close to correct before starting 54087139Smarkm.Xr ntpd 8 , 54187139Smarkmbut this was never more than a mediocre hack and is no longer needed. 54229088SmarkmIf you are following the instructions in 54329088Smarkm.Sx "Starting NTP (Best Current Practice)" 54429088Smarkmand you still need to set the system time before starting 54529088Smarkm.Nm , 54629088Smarkmplease open a bug report and document what is going on, 54729088Smarkmand then look at using 54829088Smarkm.Xr sntp 8 54929088Smarkmif you really need to set the clock before starting 55029088Smarkm.Nm . 55129088Smarkm.Pp 55229088SmarkmThere is a way to start 55329088Smarkm.Xr ntpd 8 55429088Smarkmthat often addresses all of the problems mentioned above. 55529088Smarkm.Ss "Starting NTP (Best Current Practice)" 55629088SmarkmFirst, use the 55787139Smarkm.Cm iburst 55887139Smarkmoption on your 55929088Smarkm.Cm server 56029088Smarkmentries. 56129088Smarkm.Pp 56229088SmarkmIf you can also keep a good 56329088Smarkm.Pa ntp.drift 56429088Smarkmfile then 56529088Smarkm.Xr ntpd 8 56629088Smarkmwill effectively "warm\-start" and your system's clock will 56729088Smarkmbe stable in under 11 seconds' time. 56829088Smarkm.Pp 56929088SmarkmAs soon as possible in the startup sequence, start 57029088Smarkm.Xr ntpd 8 57129088Smarkmwith at least the 57229088Smarkm.Fl g 57329088Smarkmand perhaps the 57429088Smarkm.Fl N 57529088Smarkmoptions. 57629088SmarkmThen, 57729088Smarkmstart the rest of your "normal" processes. 57887139SmarkmThis will give 57987139Smarkm.Xr ntpd 8 58029088Smarkmas much time as possible to get the system's clock synchronized and stable. 58129088Smarkm.Pp 58229088SmarkmFinally, 58329088Smarkmif you have processes like 58429088Smarkm.Cm dovecot 58529088Smarkmor database servers 58629088Smarkmthat require 58729088Smarkmmonotonically\-increasing time, 58887139Smarkmrun 58987139Smarkm.Xr ntp\-wait 1ntp\-waitmdoc 59029088Smarkmas late as possible in the boot sequence 59129088Smarkm(perhaps with the 59229088Smarkm.Fl v 59329088Smarkmflag) 59429088Smarkmand after 59529088Smarkm.Xr ntp\-wait 1ntp\-waitmdoc 59629088Smarkmexits successfully 59729088Smarkmit is as safe as it will ever be to start any process that require 59829088Smarkmstable time. 59987139Smarkm.Ss "Frequency Discipline" 60087139SmarkmThe 60129088Smarkm.Nm 60229088Smarkmbehavior at startup depends on whether the 60329088Smarkmfrequency file, usually 60429088Smarkm.Pa ntp.drift , 60529088Smarkmexists. 60629088SmarkmThis file 60729088Smarkmcontains the latest estimate of clock frequency error. 60829088SmarkmWhen the 60987139Smarkm.Nm 61087139Smarkmis started and the file does not exist, the 61129088Smarkm.Nm 61229088Smarkmenters a special mode designed to quickly adapt to 61329088Smarkmthe particular system clock oscillator time and frequency error. 61429088SmarkmThis takes approximately 15 minutes, after which the time and 61529088Smarkmfrequency are set to nominal values and the 61629088Smarkm.Nm 61729088Smarkmenters 61829088Smarkmnormal mode, where the time and frequency are continuously tracked 61987139Smarkmrelative to the server. 62087139SmarkmAfter one hour the frequency file is 62129088Smarkmcreated and the current frequency offset written to it. 62229088SmarkmWhen the 62329088Smarkm.Nm 62429088Smarkmis started and the file does exist, the 62529088Smarkm.Nm 62629088Smarkmfrequency is initialized from the file and enters normal mode 62729088Smarkmimmediately. 62829088SmarkmAfter that the current frequency offset is written to 62929088Smarkmthe file at hourly intervals. 63029088Smarkm.Ss "Operating Modes" 63129088SmarkmThe 63229088Smarkm.Nm 63329088Smarkmutility can operate in any of several modes, including 63429088Smarkmsymmetric active/passive, client/server broadcast/multicast and 63587139Smarkmmanycast, as described in the 63687139Smarkm.Qq Association Management 63729088Smarkmpage 63829088Smarkm(available as part of the HTML documentation 63929088Smarkmprovided in 64029088Smarkm.Pa /usr/share/doc/ntp ) . 64129088SmarkmIt normally operates continuously while 64229088Smarkmmonitoring for small changes in frequency and trimming the clock 64329088Smarkmfor the ultimate precision. 64429088SmarkmHowever, it can operate in a one\-time 64529088Smarkmmode where the time is set from an external server and frequency is 64629088Smarkmset from a previously recorded frequency file. 64729088SmarkmA 64829088Smarkmbroadcast/multicast or manycast client can discover remote servers, 64929088Smarkmcompute server\-client propagation delay correction factors and 65087139Smarkmconfigure itself automatically. 65187139SmarkmThis makes it possible to deploy a 65229088Smarkmfleet of workstations without specifying configuration details 65329088Smarkmspecific to the local environment. 65429088Smarkm.Pp 65529088SmarkmBy default, 65629088Smarkm.Nm 65729088Smarkmruns in continuous mode where each of 65829088Smarkmpossibly several external servers is polled at intervals determined 65929088Smarkmby an intricate state machine. 66029088SmarkmThe state machine measures the 66129088Smarkmincidental roundtrip delay jitter and oscillator frequency wander 66229088Smarkmand determines the best poll interval using a heuristic algorithm. 66329088SmarkmOrdinarily, and in most operating environments, the state machine 66429088Smarkmwill start with 64s intervals and eventually increase in steps to 66587139Smarkm1024s. 66687139SmarkmA small amount of random variation is introduced in order to 66729088Smarkmavoid bunching at the servers. 66829088SmarkmIn addition, should a server become 66929088Smarkmunreachable for some time, the poll interval is increased in steps 67029088Smarkmto 1024s in order to reduce network overhead. 67129088Smarkm.Pp 67229088SmarkmIn some cases it may not be practical for 67329088Smarkm.Nm 67429088Smarkmto run continuously. 67529088SmarkmA common workaround has been to run the 67629088Smarkm.Xr ntpdate 8 67729088Smarkmor 67829088Smarkm.Xr sntp 8 67929088Smarkmprograms from a 68029088Smarkm.Xr cron 8 68129088Smarkmjob at designated 68229088Smarkmtimes. 68329088SmarkmHowever, these programs do not have the crafted signal 68429088Smarkmprocessing, error checking or mitigation algorithms of 68529088Smarkm.Nm . 68629088SmarkmThe 68729088Smarkm.Fl q 68829088Smarkmoption is intended for this purpose. 68929088SmarkmSetting this option will cause 69029088Smarkm.Nm 69129088Smarkmto exit just after 69229088Smarkmsetting the clock for the first time. 69329088SmarkmThe procedure for initially 69487139Smarkmsetting the clock is the same as in continuous mode; most 69587139Smarkmapplications will probably want to specify the 69629088Smarkm.Cm iburst 69729088Smarkmkeyword with the 69829088Smarkm.Ic server 69929088Smarkmconfiguration command. 70029088SmarkmWith this 70129088Smarkmkeyword a volley of messages are exchanged to groom the data and 70229088Smarkmthe clock is set in about 10 s. 70329088SmarkmIf nothing is heard after a 70429088Smarkmcouple of minutes, the daemon times out and exits. 70529088SmarkmAfter a suitable 70629088Smarkmperiod of mourning, the 70729088Smarkm.Xr ntpdate 8 70829088Smarkmprogram will be 70929088Smarkmretired. 71029088Smarkm.Pp 71129088SmarkmWhen kernel support is available to discipline the clock 71287139Smarkmfrequency, which is the case for stock Solaris, Tru64, Linux and 71387139Smarkm.Fx , 71429088Smarkma useful feature is available to discipline the clock 71529088Smarkmfrequency. 71629088SmarkmFirst, 71729088Smarkm.Nm 71829088Smarkmis run in continuous mode with 71929088Smarkmselected servers in order to measure and record the intrinsic clock 72029088Smarkmfrequency offset in the frequency file. 72129088SmarkmIt may take some hours for 72229088Smarkmthe frequency and offset to settle down. 72329088SmarkmThen the 72429088Smarkm.Nm 72529088Smarkmis 72629088Smarkmstopped and run in one\-time mode as required. 72729088SmarkmAt each startup, the 72829088Smarkmfrequency is read from the file and initializes the kernel 72929088Smarkmfrequency. 73029088Smarkm.Ss "Poll Interval Control" 73129088SmarkmThis version of NTP includes an intricate state machine to 73229088Smarkmreduce the network load while maintaining a quality of 73329088Smarkmsynchronization consistent with the observed jitter and wander. 73429088SmarkmThere are a number of ways to tailor the operation in order enhance 73529088Smarkmaccuracy by reducing the interval or to reduce network overhead by 73687139Smarkmincreasing it. 73787139SmarkmHowever, the user is advised to carefully consider 73829088Smarkmthe consequences of changing the poll adjustment range from the 73929088Smarkmdefault minimum of 64 s to the default maximum of 1,024 s. 74029088SmarkmThe 74129088Smarkmdefault minimum can be changed with the 74229088Smarkm.Ic tinker 74329088Smarkm.Cm minpoll 74429088Smarkmcommand to a value not less than 16 s. 74529088SmarkmThis value is used for all 74629088Smarkmconfigured associations, unless overridden by the 74729088Smarkm.Cm minpoll 74829088Smarkmoption on the configuration command. 74929088SmarkmNote that most device drivers 75029088Smarkmwill not operate properly if the poll interval is less than 64 s 75129088Smarkmand that the broadcast server and manycast client associations will 75229088Smarkmalso use the default, unless overridden. 75329088Smarkm.Pp 75429088SmarkmIn some cases involving dial up or toll services, it may be 75529088Smarkmuseful to increase the minimum interval to a few tens of minutes 75629088Smarkmand maximum interval to a day or so. 75729088SmarkmUnder normal operation 75829088Smarkmconditions, once the clock discipline loop has stabilized the 75929088Smarkminterval will be increased in steps from the minimum to the 76029088Smarkmmaximum. 76129088SmarkmHowever, this assumes the intrinsic clock frequency error 76229088Smarkmis small enough for the discipline loop correct it. 76329088SmarkmThe capture 76429088Smarkmrange of the loop is 500 PPM at an interval of 64s decreasing by a 76529088Smarkmfactor of two for each doubling of interval. 76629088SmarkmAt a minimum of 1,024 76729088Smarkms, for example, the capture range is only 31 PPM. 76829088SmarkmIf the intrinsic 76929088Smarkmerror is greater than this, the drift file 77029088Smarkm.Pa ntp.drift 77129088Smarkmwill 77229088Smarkmhave to be specially tailored to reduce the residual error below 77329088Smarkmthis limit. 77429088SmarkmOnce this is done, the drift file is automatically 77529088Smarkmupdated once per hour and is available to initialize the frequency 77629088Smarkmon subsequent daemon restarts. 77729088Smarkm.Ss "The huff\-n'\-puff Filter" 77829088SmarkmIn scenarios where a considerable amount of data are to be 77929088Smarkmdownloaded or uploaded over telephone modems, timekeeping quality 78029088Smarkmcan be seriously degraded. 78129088SmarkmThis occurs because the differential 78229088Smarkmdelays on the two directions of transmission can be quite large. 78329088SmarkmIn 78429088Smarkmmany cases the apparent time errors are so large as to exceed the 78529088Smarkmstep threshold and a step correction can occur during and after the 78629088Smarkmdata transfer is in progress. 78729088Smarkm.Pp 78829088SmarkmThe huff\-n'\-puff filter is designed to correct the apparent time 78929088Smarkmoffset in these cases. 79029088SmarkmIt depends on knowledge of the propagation 79129088Smarkmdelay when no other traffic is present. 79229088SmarkmIn common scenarios this 79329088Smarkmoccurs during other than work hours. 79431622ScharnierThe filter maintains a shift 79529088Smarkmregister that remembers the minimum delay over the most recent 79687139Smarkminterval measured usually in hours. 79787139SmarkmUnder conditions of severe 79829088Smarkmdelay, the filter corrects the apparent offset using the sign of 79929088Smarkmthe offset and the difference between the apparent delay and 80087139Smarkmminimum delay. 80129088SmarkmThe name of the filter reflects the negative (huff) 80229088Smarkmand positive (puff) correction, which depends on the sign of the 80329088Smarkmoffset. 80429088Smarkm.Pp 80529088SmarkmThe filter is activated by the 80629088Smarkm.Ic tinker 80731622Scharniercommand and 80829088Smarkm.Cm huffpuff 80931622Scharnierkeyword, as described in 81029088Smarkm.Xr ntp.conf 5 . 81129088Smarkm.Sh "ENVIRONMENT" 81287139SmarkmSee \fBOPTION PRESETS\fP for configuration environment variables. 81387139Smarkm.Sh FILES 81429088Smarkm.Bl -tag -width /etc/ntp.drift -compact 81529088Smarkm.It Pa /etc/ntp.conf 81687139Smarkmthe default name of the configuration file 81729088Smarkm.It Pa /etc/ntp.drift 81829088Smarkmthe default name of the drift file 81929088Smarkm.It Pa /etc/ntp.keys 82029088Smarkmthe default name of the key file 82129088Smarkm.El 82229088Smarkm.Sh "EXIT STATUS" 82329088SmarkmOne of the following exit values will be returned: 82429088Smarkm.Bl -tag 82529088Smarkm.It 0 " (EXIT_SUCCESS)" 82629088SmarkmSuccessful program execution. 82729088Smarkm.It 1 " (EXIT_FAILURE)" 82829088SmarkmThe operation failed or the command syntax was not valid. 82929088Smarkm.It 70 " (EX_SOFTWARE)" 83029088Smarkmlibopts had an internal operational error. Please report 83129088Smarkmit to autogen\-users@lists.sourceforge.net. Thank you. 83231622Scharnier.El 83329088Smarkm.Sh "SEE ALSO" 83487139Smarkm.Xr ntp.conf 5 , 83587139Smarkm.Xr ntpdate 8 , 83629088Smarkm.Xr ntpdc 8 , 83787139Smarkm.Xr ntpq 8 , 83829181Smarkm.Xr sntp 8 83929088Smarkm.Pp 84029088SmarkmIn addition to the manual pages provided, 84129088Smarkmcomprehensive documentation is available on the world wide web 84229088Smarkmat 84329088Smarkm.Li http://www.ntp.org/ . 84429088SmarkmA snapshot of this documentation is available in HTML format in 84529088Smarkm.Pa /usr/share/doc/ntp . 84629088Smarkm.Rs 84729088Smarkm.%A David L. Mills 84829088Smarkm.%T Network Time Protocol (Version 1) 84929088Smarkm.%O RFC1059 85029088Smarkm.Re 85129088Smarkm.Rs 85229088Smarkm.%A David L. Mills 85329088Smarkm.%T Network Time Protocol (Version 2) 85429181Smarkm.%O RFC1119 85529088Smarkm.Re 85629088Smarkm.Rs 85729088Smarkm.%A David L. Mills 85829088Smarkm.%T Network Time Protocol (Version 3) 85929088Smarkm.%O RFC1305 86029181Smarkm.Re 86129088Smarkm.Rs 86229088Smarkm.%A David L. Mills 86329088Smarkm.%A J. Martin, Ed. 86429088Smarkm.%A J. Burbank 86529088Smarkm.%A W. Kasch 86629088Smarkm.%T Network Time Protocol Version 4: Protocol and Algorithms Specification 86729088Smarkm.%O RFC5905 86829088Smarkm.Re 86929088Smarkm.Rs 87029088Smarkm.%A David L. Mills 87129088Smarkm.%A B. Haberman, Ed. 87229088Smarkm.%T Network Time Protocol Version 4: Autokey Specification 87329088Smarkm.%O RFC5906 87429088Smarkm.Re 87529088Smarkm.Rs 87629088Smarkm.%A H. Gerstung 87729088Smarkm.%A C. Elliott 87829088Smarkm.%A B. Haberman, Ed. 87929088Smarkm.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) 88029088Smarkm.%O RFC5907 88129088Smarkm.Re 88229088Smarkm.Rs 88329088Smarkm.%A R. Gayraud 88429088Smarkm.%A B. Lourdelet 88529088Smarkm.%T Network Time Protocol (NTP) Server Option for DHCPv6 88629088Smarkm.%O RFC5908 88729088Smarkm.Re 88829088Smarkm.Sh "AUTHORS" 88929088SmarkmThe University of Delaware and Network Time Foundation 89029088Smarkm.Sh "COPYRIGHT" 89129088SmarkmCopyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved. 89229088SmarkmThis program is released under the terms of the NTP license, <http://ntp.org/license>. 89329088Smarkm.Sh BUGS 89429088SmarkmThe 89529088Smarkm.Nm 89629088Smarkmutility has gotten rather fat. 89729088SmarkmWhile not huge, it has gotten 89829088Smarkmlarger than might be desirable for an elevated\-priority 89929088Smarkm.Nm 90029088Smarkmrunning on a workstation, particularly since many of 90129088Smarkmthe fancy features which consume the space were designed more with 90229088Smarkma busy primary server, rather than a high stratum workstation in 90329088Smarkmmind. 90429088Smarkm.Pp 90529088SmarkmPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 90629181Smarkm.Sh NOTES 90729181SmarkmPortions of this document came from FreeBSD. 90829088Smarkm.Pp 90929088SmarkmThis manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP 91029088Smarkmoption definitions. 91129088Smarkm