ntpd.man.in revision 293894
190075Sobrien.de1 NOP 2117395Skan. it 1 an-trap 3169689Skan. if \\n[.$] \,\\$*\/ 418334Speter.. 590075Sobrien.ie t \ 618334Speter.ds B-Font [CB] 790075Sobrien.ds I-Font [CI] 890075Sobrien.ds R-Font [CR] 990075Sobrien.el \ 1090075Sobrien.ds B-Font B 1118334Speter.ds I-Font I 1290075Sobrien.ds R-Font R 1390075Sobrien.TH ntpd @NTPD_MS@ "07 Jan 2016" "4.2.8p5" "User Commands" 1490075Sobrien.\" 1590075Sobrien.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-KDaWJq/ag-WDaOIq) 1618334Speter.\" 1718334Speter.\" It has been AutoGen-ed January 7, 2016 at 11:30:44 PM by AutoGen 5.18.5 1890075Sobrien.\" From the definitions ntpd-opts.def 19169689Skan.\" and the template file agman-cmd.tpl 20169689Skan.SH NAME 2118334Speter\f\*[B-Font]ntpd\fP 22169689Skan\- NTP daemon program 23169689Skan.SH SYNOPSIS 24169689Skan\f\*[B-Font]ntpd\fP 25169689Skan.\" Mixture of short (flag) options and long options 26169689Skan[\f\*[B-Font]\-flags\f[]] 2718334Speter[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]] 28169689Skan[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]] 29169689Skan[ <server1> ... <serverN> ] 3050397Sobrien.sp \n(Ppu 31132718Skan.ne 2 32132718Skan 3318334Speter.SH DESCRIPTION 3418334SpeterThe 3590075Sobrien\f\*[B-Font]ntpd\fP 36169689Skanutility is an operating system daemon which sets 37169689Skanand maintains the system time of day in synchronism with Internet 38169689Skanstandard time servers. 39169689SkanIt is a complete implementation of the 40169689SkanNetwork Time Protocol (NTP) version 4, as defined by RFC-5905, 4118334Speterbut also retains compatibility with 4290075Sobrienversion 3, as defined by RFC-1305, and versions 1 4318334Speterand 2, as defined by RFC-1059 and RFC-1119, respectively. 4490075Sobrien.sp \n(Ppu 4518334Speter.ne 2 4690075Sobrien 4718334SpeterThe 4890075Sobrien\f\*[B-Font]ntpd\fP 4990075Sobrienutility does most computations in 64-bit floating point 5090075Sobrienarithmetic and does relatively clumsy 64-bit fixed point operations 5190075Sobrienonly when necessary to preserve the ultimate precision, about 232 5290075Sobrienpicoseconds. 5390075SobrienWhile the ultimate precision is not achievable with 5418334Speterordinary workstations and networks of today, it may be required 5518334Speterwith future gigahertz CPU clocks and gigabit LANs. 5618334Speter.sp \n(Ppu 5718334Speter.ne 2 5890075Sobrien 5918334SpeterOrdinarily, 6018334Speter\f\*[B-Font]ntpd\fP 6118334Speterreads the 6218334Speter\fCntp.conf\f[]\fR(5)\f[] 6318334Speterconfiguration file at startup time in order to determine the 6418334Spetersynchronization sources and operating modes. 6518334SpeterIt is also possible to 6618334Speterspecify a working, although limited, configuration entirely on the 6718334Spetercommand line, obviating the need for a configuration file. 6890075SobrienThis may 6918334Speterbe particularly useful when the local host is to be configured as a 7018334Speterbroadcast/multicast client, with all peers being determined by 7118334Speterlistening to broadcasts at run time. 7218334Speter.sp \n(Ppu 7318334Speter.ne 2 7418334Speter 7518334SpeterIf NetInfo support is built into 7618334Speter\f\*[B-Font]ntpd\fP, 7718334Speterthen 7818334Speter\f\*[B-Font]ntpd\fP 7918334Speterwill attempt to read its configuration from the 8018334SpeterNetInfo if the default 8118334Speter\fCntp.conf\f[]\fR(5)\f[] 8290075Sobrienfile cannot be read and no file is 8390075Sobrienspecified by the 8418334Speter\f\*[B-Font]\-c\f[] 8518334Speteroption. 8618334Speter.sp \n(Ppu 8718334Speter.ne 2 8818334Speter 8918334SpeterVarious internal 9018334Speter\f\*[B-Font]ntpd\fP 9150397Sobrienvariables can be displayed and 9250397Sobrienconfiguration options altered while the 93117395Skan\f\*[B-Font]ntpd\fP 9490075Sobrienis running 9518334Speterusing the 9618334Speter\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 9718334Speterand 9818334Speter\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 9918334Speterutility programs. 10018334Speter.sp \n(Ppu 10118334Speter.ne 2 10218334Speter 10318334SpeterWhen 104169689Skan\f\*[B-Font]ntpd\fP 10590075Sobrienstarts it looks at the value of 10618334Speter\fCumask\f[]\fR(2)\f[], 10718334Speterand if zero 10818334Speter\f\*[B-Font]ntpd\fP 10918334Speterwill set the 110132718Skan\fCumask\f[]\fR(2)\f[] 111132718Skanto 022. 112169689Skan.SH "OPTIONS" 113132718Skan.TP 114132718Skan.NOP \f\*[B-Font]\-4\f[], \f\*[B-Font]\-\-ipv4\f[] 115132718SkanForce IPv4 DNS name resolution. 116132718SkanThis option must not appear in combination with any of the following options: 117132718Skanipv6. 118132718Skan.sp 119132718SkanForce DNS resolution of following host names on the command line 120132718Skanto the IPv4 namespace. 121132718Skan.TP 122169689Skan.NOP \f\*[B-Font]\-6\f[], \f\*[B-Font]\-\-ipv6\f[] 123169689SkanForce IPv6 DNS name resolution. 124169689SkanThis option must not appear in combination with any of the following options: 125169689Skanipv4. 12618334Speter.sp 12718334SpeterForce DNS resolution of following host names on the command line 12890075Sobriento the IPv6 namespace. 12990075Sobrien.TP 130169689Skan.NOP \f\*[B-Font]\-a\f[], \f\*[B-Font]\-\-authreq\f[] 131169689SkanRequire crypto authentication. 132169689SkanThis option must not appear in combination with any of the following options: 133169689Skanauthnoreq. 13490075Sobrien.sp 13518334SpeterRequire cryptographic authentication for broadcast client, 136169689Skanmulticast client and symmetric passive associations. 13790075SobrienThis is the default. 138169689Skan.TP 139169689Skan.NOP \f\*[B-Font]\-A\f[], \f\*[B-Font]\-\-authnoreq\f[] 140169689SkanDo not require crypto authentication. 14190075SobrienThis option must not appear in combination with any of the following options: 14218334Speterauthreq. 143132718Skan.sp 144132718SkanDo not require cryptographic authentication for broadcast client, 145132718Skanmulticast client and symmetric passive associations. 146132718SkanThis is almost never a good idea. 147132718Skan.TP 148132718Skan.NOP \f\*[B-Font]\-b\f[], \f\*[B-Font]\-\-bcastsync\f[] 149132718SkanAllow us to sync to broadcast servers. 15050397Sobrien.sp 15118334Speter.TP 15218334Speter.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-configfile\f[]=\f\*[I-Font]string\f[] 15318334Speterconfiguration file name. 15418334Speter.sp 155132718SkanThe name and path of the configuration file, 15618334Speter\fI/etc/ntp.conf\fP 15718334Speterby default. 15818334Speter.TP 15990075Sobrien.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[] 160169689SkanIncrease debug verbosity level. 16190075SobrienThis option may appear an unlimited number of times. 16218334Speter.sp 16350397Sobrien.TP 164132718Skan.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[] 165132718SkanSet the debug verbosity level. 166132718SkanThis option may appear an unlimited number of times. 167132718SkanThis option takes an integer number as its argument. 168132718Skan.sp 169132718Skan.TP 17018334Speter.NOP \f\*[B-Font]\-f\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-driftfile\f[]=\f\*[I-Font]string\f[] 17118334Speterfrequency drift file name. 17218334Speter.sp 173169689SkanThe name and path of the frequency file, 174169689Skan\fI/etc/ntp.drift\fP 175169689Skanby default. 176169689SkanThis is the same operation as the 177169689Skan\fBdriftfile\fP \fIdriftfile\fP 178169689Skanconfiguration specification in the 179169689Skan\fI/etc/ntp.conf\fP 180169689Skanfile. 181169689Skan.TP 182169689Skan.NOP \f\*[B-Font]\-g\f[], \f\*[B-Font]\-\-panicgate\f[] 18318334SpeterAllow the first adjustment to be Big. 18418334SpeterThis option may appear an unlimited number of times. 18518334Speter.sp 18618334SpeterNormally, 187169689Skan\fBntpd\fP 18818334Speterexits 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, 18918334Speter\fBntpd\fP 19018334Speterwill exit with a message to the system log. This option can be used with the 191169689Skan\fB-q\fP 19218334Speterand 19390075Sobrien\fB-x\fP 19490075Sobrienoptions. 19590075SobrienSee the 19618334Speter\fBtinker\fP 197132718Skanconfiguration file directive for other options. 19818334Speter.TP 199132718Skan.NOP \f\*[B-Font]\-G\f[], \f\*[B-Font]\-\-force\-step\-once\f[] 200132718SkanStep any initial offset correction.. 201132718Skan.sp 202169689SkanNormally, 203132718Skan\fBntpd\fP 204132718Skansteps the time if the time offset exceeds the step threshold, 20518334Speterwhich is 128 ms by default, and otherwise slews the time. 20618334SpeterThis option forces the initial offset correction to be stepped, 20718334Speterso the highest time accuracy can be achieved quickly. 20818334SpeterHowever, this may also cause the time to be stepped back 20918334Speterso this option must not be used if 21018334Speterapplications requiring monotonic time are running. 21118334SpeterSee the \fBtinker\fP configuration file directive for other options. 21218334Speter.TP 21318334Speter.NOP \f\*[B-Font]\-i\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-jaildir\f[]=\f\*[I-Font]string\f[] 214132718SkanJail directory. 21518334Speter.sp 21690075SobrienChroot the server to the directory 21790075Sobrien\fIjaildir\fP 21890075Sobrien. 21990075SobrienThis option also implies that the server attempts to drop root privileges at startup. 22018334SpeterYou may need to also specify a 22118334Speter\fB-u\fP 22218334Speteroption. 22318334SpeterThis option is only available if the OS supports adjusting the clock 22418334Speterwithout full root privileges. 22518334SpeterThis option is supported under NetBSD (configure with 22618334Speter\fB--enable-clockctl\fP) or Linux (configure with 22718334Speter\fB--enable-linuxcaps\fP) or Solaris (configure with \fB--enable-solarisprivs\fP). 22896263Sobrien.TP 22918334Speter.NOP \f\*[B-Font]\-I\f[] \f\*[I-Font]iface\f[], \f\*[B-Font]\-\-interface\f[]=\f\*[I-Font]iface\f[] 23018334SpeterListen on an interface name or address. 23118334SpeterThis option may appear an unlimited number of times. 23218334Speter.sp 23318334SpeterOpen the network address given, or all the addresses associated with the 23450397Sobriengiven interface name. This option may appear multiple times. This option 23518334Speteralso implies not opening other addresses, except wildcard and localhost. 236169689SkanThis option is deprecated. Please consider using the configuration file 237169689Skan\fBinterface\fP command, which is more versatile. 238169689Skan.TP 239169689Skan.NOP \f\*[B-Font]\-k\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-keyfile\f[]=\f\*[I-Font]string\f[] 24018334Speterpath to symmetric keys. 24118334Speter.sp 24218334SpeterSpecify the name and path of the symmetric key file. 24318334Speter\fI/etc/ntp.keys\fP 24418334Speteris the default. 24518334SpeterThis is the same operation as the 24618334Speter\fBkeys\fP \fIkeyfile\fP 24718334Speterconfiguration file directive. 24818334Speter.TP 24918334Speter.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]string\f[] 25018334Speterpath to the log file. 25118334Speter.sp 25218334SpeterSpecify the name and path of the log file. 25318334SpeterThe default is the system log file. 25450397SobrienThis is the same operation as the 25550397Sobrien\fBlogfile\fP \fIlogfile\fP 25650397Sobrienconfiguration file directive. 25718334Speter.TP 25818334Speter.NOP \f\*[B-Font]\-L\f[], \f\*[B-Font]\-\-novirtualips\f[] 259169689SkanDo not listen to virtual interfaces. 260169689Skan.sp 26152284SobrienDo not listen to virtual interfaces, defined as those with 26252284Sobriennames containing a colon. This option is deprecated. Please 263169689Skanconsider using the configuration file \fBinterface\fP command, which 26452284Sobrienis more versatile. 26552284Sobrien.TP 26652284Sobrien.NOP \f\*[B-Font]\-M\f[], \f\*[B-Font]\-\-modifymmtimer\f[] 267117395SkanModify Multimedia Timer (Windows only). 26852284Sobrien.sp 26990075SobrienSet the Windows Multimedia Timer to highest resolution. This 270169689Skanensures the resolution does not change while ntpd is running, 271117395Skanavoiding timekeeping glitches associated with changes. 272117395Skan.TP 273117395Skan.NOP \f\*[B-Font]\-n\f[], \f\*[B-Font]\-\-nofork\f[] 27490075SobrienDo not fork. 27518334SpeterThis option must not appear in combination with any of the following options: 27618334Speterwait-sync. 27718334Speter.sp 278169689Skan.TP 279169689Skan.NOP \f\*[B-Font]\-N\f[], \f\*[B-Font]\-\-nice\f[] 280169689SkanRun at high priority. 281169689Skan.sp 282169689SkanTo the extent permitted by the operating system, run 283169689Skan\fBntpd\fP 28418334Speterat the highest priority. 285169689Skan.TP 286169689Skan.NOP \f\*[B-Font]\-p\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-pidfile\f[]=\f\*[I-Font]string\f[] 287169689Skanpath to the PID file. 288169689Skan.sp 289169689SkanSpecify the name and path of the file used to record 290169689Skan\fBntpd\fP's 291169689Skanprocess ID. 292169689SkanThis is the same operation as the 293169689Skan\fBpidfile\fP \fIpidfile\fP 29418334Speterconfiguration file directive. 295169689Skan.TP 296169689Skan.NOP \f\*[B-Font]\-P\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-priority\f[]=\f\*[I-Font]number\f[] 297169689SkanProcess priority. 298169689SkanThis option takes an integer number as its argument. 299169689Skan.sp 300169689SkanTo the extent permitted by the operating system, run 301169689Skan\fBntpd\fP 302169689Skanat the specified 303169689Skan\fBsched_setscheduler(SCHED_FIFO)\fP 304169689Skanpriority. 305169689Skan.TP 30618334Speter.NOP \f\*[B-Font]\-q\f[], \f\*[B-Font]\-\-quit\f[] 307169689SkanSet the time and quit. 308169689SkanThis option must not appear in combination with any of the following options: 309169689Skansaveconfigquit, wait-sync. 31018334Speter.sp 31118334Speter\fBntpd\fP 31218334Speterwill not daemonize and will exit after the clock is first 31352284Sobriensynchronized. This behavior mimics that of the 31490075Sobrien\fBntpdate\fP 31552284Sobrienprogram, which will soon be replaced with a shell script. 316169689SkanThe 31752284Sobrien\fB-g\fP 318169689Skanand 319132718Skan\fB-x\fP 32052284Sobrienoptions can be used with this option. 321169689SkanNote: The kernel time discipline is disabled with this option. 322169689Skan.TP 323169689Skan.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-propagationdelay\f[]=\f\*[I-Font]string\f[] 32452284SobrienBroadcast/propagation delay. 32552284Sobrien.sp 32690075SobrienSpecify 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. 32790075Sobrien.TP 32890075Sobrien.NOP \f\*[B-Font]\-\-saveconfigquit\f[]=\f\*[I-Font]string\f[] 329169689SkanSave parsed configuration and quit. 330169689SkanThis option must not appear in combination with any of the following options: 331169689Skanquit, wait-sync. 332169689Skan.sp 33390075SobrienCause \fBntpd\fP to parse its startup configuration file and save an 33490075Sobrienequivalent to the given filename and exit. This option was 33590075Sobriendesigned for automated testing. 33618334Speter.TP 33718334Speter.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-statsdir\f[]=\f\*[I-Font]string\f[] 338132718SkanStatistics file location. 33918334Speter.sp 34090075SobrienSpecify the directory path for files created by the statistics facility. 34190075SobrienThis is the same operation as the 34290075Sobrien\fBstatsdir\fP \fIstatsdir\fP 34390075Sobrienconfiguration file directive. 34418334Speter.TP 34590075Sobrien.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]tkey\f[], \f\*[B-Font]\-\-trustedkey\f[]=\f\*[I-Font]tkey\f[] 34690075SobrienTrusted key number. 34790075SobrienThis option may appear an unlimited number of times. 34890075Sobrien.sp 34918334SpeterAdd the specified key number to the trusted key list. 35090075Sobrien.TP 35190075Sobrien.NOP \f\*[B-Font]\-u\f[] \f\*[I-Font]string\f[], \f\*[B-Font]\-\-user\f[]=\f\*[I-Font]string\f[] 35290075SobrienRun as userid (or userid:groupid). 35390075Sobrien.sp 35418334SpeterSpecify a user, and optionally a group, to switch to. 35590075SobrienThis option is only available if the OS supports adjusting the clock 35690075Sobrienwithout full root privileges. 35718334SpeterThis option is supported under NetBSD (configure with 35890075Sobrien\fB--enable-clockctl\fP) or Linux (configure with 35990075Sobrien\fB--enable-linuxcaps\fP) or Solaris (configure with \fB--enable-solarisprivs\fP). 36018334Speter.TP 36190075Sobrien.NOP \f\*[B-Font]\-U\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-updateinterval\f[]=\f\*[I-Font]number\f[] 36290075Sobrieninterval in seconds between scans for new or dropped interfaces. 36350397SobrienThis option takes an integer number as its argument. 36490075Sobrien.sp 365169689SkanGive the time in seconds between two scans for new or dropped interfaces. 36650397SobrienFor systems with routing socket support the scans will be performed shortly after the interface change 36790075Sobrienhas been detected by the system. 36890075SobrienUse 0 to disable scanning. 60 seconds is the minimum time between scans. 36950397Sobrien.TP 37090075Sobrien.NOP \f\*[B-Font]\-\-var\f[]=\f\*[I-Font]nvar\f[] 37190075Sobrienmake ARG an ntp variable (RW). 37218334SpeterThis option may appear an unlimited number of times. 37390075Sobrien.sp 37490075Sobrien.TP 37590075Sobrien.NOP \f\*[B-Font]\-\-dvar\f[]=\f\*[I-Font]ndvar\f[] 37690075Sobrienmake ARG an ntp variable (RW|DEF). 37718334SpeterThis option may appear an unlimited number of times. 37890075Sobrien.sp 37990075Sobrien.TP 38090075Sobrien.NOP \f\*[B-Font]\-w\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-wait\-sync\f[]=\f\*[I-Font]number\f[] 38118334SpeterSeconds to wait for first clock sync. 38290075SobrienThis option must not appear in combination with any of the following options: 383132718Skannofork, quit, saveconfigquit. 38418334SpeterThis option takes an integer number as its argument. 38590075Sobrien.sp 38690075SobrienIf greater than zero, alters \fBntpd\fP's behavior when forking to 38718334Speterdaemonize. Instead of exiting with status 0 immediately after 38890075Sobrienthe fork, the parent waits up to the specified number of 38918334Speterseconds for the child to first synchronize the clock. The exit 39090075Sobrienstatus is zero (success) if the clock was synchronized, 39190075Sobrienotherwise it is \fBETIMEDOUT\fP. 39290075SobrienThis provides the option for a script starting \fBntpd\fP to easily 39318334Speterwait for the first set of the clock before proceeding. 39418334Speter.TP 39590075Sobrien.NOP \f\*[B-Font]\-x\f[], \f\*[B-Font]\-\-slew\f[] 39690075SobrienSlew up to 600 seconds. 39790075Sobrien.sp 39890075SobrienNormally, 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. 39990075SobrienThis option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. 40018334SpeterNote: 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. 40190075SobrienThus, an adjustment as much as 600 s will take almost 14 days to complete. 40290075SobrienThis option can be used with the 40390075Sobrien\fB-g\fP 40490075Sobrienand 40590075Sobrien\fB-q\fP 40618334Speteroptions. 40790075SobrienSee the 40890075Sobrien\fBtinker\fP 40990075Sobrienconfiguration file directive for other options. 41090075SobrienNote: The kernel time discipline is disabled with this option. 41118334Speter.TP 41218334Speter.NOP \f\*[B-Font]\-\-usepcc\f[] 41390075SobrienUse CPU cycle counter (Windows only). 41490075Sobrien.sp 41590075SobrienAttempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. 41690075SobrienThe CPU counter and \fBQueryPerformanceCounter\fP are compared, and if 41718334Speterthey have the same frequency, the CPU counter (RDTSC on x86) is 41890075Sobrienused directly, saving the overhead of a system call. 41990075Sobrien.TP 42090075Sobrien.NOP \f\*[B-Font]\-\-pccfreq\f[]=\f\*[I-Font]string\f[] 42190075SobrienForce CPU cycle counter use (Windows only). 42290075Sobrien.sp 42390075SobrienForce substitution the CPU counter for \fBQueryPerformanceCounter\fP. 42490075SobrienThe CPU counter (RDTSC on x86) is used unconditionally with the 42518334Spetergiven frequency (in Hz). 42690075Sobrien.TP 42790075Sobrien.NOP \f\*[B-Font]\-m\f[], \f\*[B-Font]\-\-mdns\f[] 42890075SobrienRegister with mDNS as a NTP server. 42918334Speter.sp 43090075SobrienRegisters as an NTP server with the local mDNS server which allows 43190075Sobrienthe server to be discovered via mDNS client lookup. 43290075Sobrien.TP 43318334Speter.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[] 43490075SobrienDisplay usage information and exit. 43590075Sobrien.TP 43690075Sobrien.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[] 43790075SobrienPass the extended usage information through a pager. 438169689Skan.TP 43918334Speter.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 44090075SobrienOutput version of program and exit. The default mode is `v', a simple 44190075Sobrienversion. The `c' mode will print copyright information and `n' will 44218334Speterprint the full copyright notice. 443132718Skan.PP 444169689Skan.SH "OPTION PRESETS" 445169689SkanAny option that is not marked as \fInot presettable\fP may be preset 446132718Skanby loading values from environment variables named: 447132718Skan.nf 448132718Skan \fBNTPD_<option-name>\fP or \fBNTPD\fP 449132718Skan.fi 450132718Skan.ad 451132718Skan.SH USAGE 452132718Skan.SS "How NTP Operates" 453132718SkanThe 454132718Skan\f\*[B-Font]ntpd\fP 455132718Skanutility operates by exchanging messages with 456132718Skanone or more configured servers over a range of designated poll intervals. 457132718SkanWhen 458132718Skanstarted, whether for the first or subsequent times, the program 459132718Skanrequires several exchanges from the majority of these servers so 460132718Skanthe signal processing and mitigation algorithms can accumulate and 461132718Skangroom the data and set the clock. 462132718SkanIn order to protect the network 463132718Skanfrom bursts, the initial poll interval for each server is delayed 464132718Skanan interval randomized over a few seconds. 465132718SkanAt the default initial poll 466132718Skaninterval of 64s, several minutes can elapse before the clock is 467132718Skanset. 468132718SkanThis initial delay to set the clock 469132718Skancan be safely and dramatically reduced using the 470132718Skan\f\*[B-Font]iburst\f[] 471132718Skankeyword with the 472132718Skan\f\*[B-Font]server\f[] 473132718Skanconfiguration 47418334Spetercommand, as described in 47590075Sobrien\fCntp.conf\f[]\fR(5)\f[]. 47690075Sobrien.sp \n(Ppu 477132718Skan.ne 2 478132718Skan 47990075SobrienMost operating systems and hardware of today incorporate a 48090075Sobrientime-of-year (TOY) chip to maintain the time during periods when 481169689Skanthe power is off. 48290075SobrienWhen the machine is booted, the chip is used to 48390075Sobrieninitialize the operating system time. 48490075SobrienAfter the machine has 48518334Spetersynchronized to a NTP server, the operating system corrects the 48618334Speterchip from time to time. 487132718SkanIn the default case, if 488132718Skan\f\*[B-Font]ntpd\fP 48918334Speterdetects that the time on the host 49090075Sobrienis more than 1000s from the server time, 49190075Sobrien\f\*[B-Font]ntpd\fP 49290075Sobrienassumes something must be terribly wrong and the only 49390075Sobrienreliable action is for the operator to intervene and set the clock 49490075Sobrienby hand. 49518334Speter(Reasons for this include there is no TOY chip, 49690075Sobrienor its battery is dead, or that the TOY chip is just of poor quality.) 497132718SkanThis causes 498132718Skan\f\*[B-Font]ntpd\fP 49990075Sobriento exit with a panic message to 50090075Sobrienthe system log. 50190075SobrienThe 50290075Sobrien\f\*[B-Font]\-g\f[] 50390075Sobrienoption overrides this check and the 50490075Sobrienclock will be set to the server time regardless of the chip time 50518334Speter(up to 68 years in the past or future \(em 50690075Sobrienthis is a limitation of the NTPv4 protocol). 507132718SkanHowever, and to protect against broken hardware, such as when the 508132718SkanCMOS battery fails or the clock counter becomes defective, once the 50990075Sobrienclock has been set an error greater than 1000s will cause 510169689Skan\f\*[B-Font]ntpd\fP 51190075Sobriento exit anyway. 51290075Sobrien.sp \n(Ppu 51390075Sobrien.ne 2 51418334Speter 51590075SobrienUnder ordinary conditions, 516132718Skan\f\*[B-Font]ntpd\fP 517132718Skanadjusts the clock in 51890075Sobriensmall steps so that the timescale is effectively continuous and 51990075Sobrienwithout discontinuities. 520169689SkanUnder conditions of extreme network 52190075Sobriencongestion, the roundtrip delay jitter can exceed three seconds and 52290075Sobrienthe synchronization distance, which is equal to one-half the 52390075Sobrienroundtrip delay plus error budget terms, can become very large. 52418334SpeterThe 525169689Skan\f\*[B-Font]ntpd\fP 526169689Skanalgorithms discard sample offsets exceeding 128 ms, 527169689Skanunless the interval during which no sample offset is less than 128 528169689Skanms exceeds 900s. 529169689SkanThe first sample after that, no matter what the 530169689Skanoffset, steps the clock to the indicated time. 531169689SkanIn practice this 532169689Skanreduces the false alarm rate where the clock is stepped in error to 533169689Skana vanishingly low incidence. 534169689Skan.sp \n(Ppu 535169689Skan.ne 2 536169689Skan 537169689SkanAs the result of this behavior, once the clock has been set it 538169689Skanvery rarely strays more than 128 ms even under extreme cases of 539169689Skannetwork path congestion and jitter. 540169689SkanSometimes, in particular when 541169689Skan\f\*[B-Font]ntpd\fP 542169689Skanis first started without a valid drift file 543169689Skanon a system with a large intrinsic drift 544169689Skanthe error might grow to exceed 128 ms, 545169689Skanwhich would cause the clock to be set backwards 546169689Skanif the local clock time is more than 128 s 547169689Skanin the future relative to the server. 548169689SkanIn some applications, this behavior may be unacceptable. 549169689SkanThere are several solutions, however. 550169689SkanIf the 55190075Sobrien\f\*[B-Font]\-x\f[] 55290075Sobrienoption is included on the command line, the clock will 553132718Skannever be stepped and only slew corrections will be used. 554132718SkanBut this choice comes with a cost that 55590075Sobrienshould be carefully explored before deciding to use 55690075Sobrienthe 55790075Sobrien\f\*[B-Font]\-x\f[] 55890075Sobrienoption. 55918334SpeterThe maximum slew rate possible is limited 56090075Sobriento 500 parts-per-million (PPM) as a consequence of the correctness 561117395Skanprinciples on which the NTP protocol and algorithm design are 562117395Skanbased. 563117395SkanAs a result, the local clock can take a long time to 564132718Skanconverge to an acceptable offset, about 2,000 s for each second the 565132718Skanclock is outside the acceptable range. 566117395SkanDuring this interval the 567117395Skanlocal clock will not be consistent with any other network clock and 568169689Skanthe system cannot be used for distributed applications that require 569117395Skancorrectly synchronized network time. 570117395Skan.sp \n(Ppu 571117395Skan.ne 2 572 573In spite of the above precautions, sometimes when large 574frequency errors are present the resulting time offsets stray 575outside the 128-ms range and an eventual step or slew time 576correction is required. 577If following such a correction the 578frequency error is so large that the first sample is outside the 579acceptable range, 580\f\*[B-Font]ntpd\fP 581enters the same state as when the 582\fIntp.drift\f[] 583file is not present. 584The intent of this behavior 585is to quickly correct the frequency and restore operation to the 586normal tracking mode. 587In the most extreme cases 588(the host 589\f\*[B-Font]time.ien.it\f[] 590comes to mind), there may be occasional 591step/slew corrections and subsequent frequency corrections. 592It 593helps in these cases to use the 594\f\*[B-Font]burst\f[] 595keyword when 596configuring the server, but 597ONLY 598when you have permission to do so from the owner of the target host. 599.sp \n(Ppu 600.ne 2 601 602Finally, 603in the past many startup scripts would run 604\fCntpdate\f[]\fR(@NTPDATE_MS@)\f[] 605or 606\fCsntp\f[]\fR(@SNTP_MS@)\f[] 607to get the system clock close to correct before starting 608\fCntpd\f[]\fR(@NTPD_MS@)\f[], 609but this was never more than a mediocre hack and is no longer needed. 610If you are following the instructions in 611\fIStarting NTP (Best Current Practice)\f[] 612and you still need to set the system time before starting 613\f\*[B-Font]ntpd\fP, 614please open a bug report and document what is going on, 615and then look at using 616\fCsntp\f[]\fR(@SNTP_MS@)\f[] 617if you really need to set the clock before starting 618\f\*[B-Font]ntpd\fP. 619.sp \n(Ppu 620.ne 2 621 622There is a way to start 623\fCntpd\f[]\fR(@NTPD_MS@)\f[] 624that often addresses all of the problems mentioned above. 625.SS "Starting NTP (Best Current Practice)" 626First, use the 627\f\*[B-Font]iburst\f[] 628option on your 629\f\*[B-Font]server\f[] 630entries. 631.sp \n(Ppu 632.ne 2 633 634If you can also keep a good 635\fIntp.drift\f[] 636file then 637\fCntpd\f[]\fR(@NTPD_MS@)\f[] 638will effectively "warm-start" and your system's clock will 639be stable in under 11 seconds' time. 640.sp \n(Ppu 641.ne 2 642 643As soon as possible in the startup sequence, start 644\fCntpd\f[]\fR(@NTPD_MS@)\f[] 645with at least the 646\f\*[B-Font]\-g\f[] 647and perhaps the 648\f\*[B-Font]\-N\f[] 649options. 650Then, 651start the rest of your "normal" processes. 652This will give 653\fCntpd\f[]\fR(@NTPD_MS@)\f[] 654as much time as possible to get the system's clock synchronized and stable. 655.sp \n(Ppu 656.ne 2 657 658Finally, 659if you have processes like 660\f\*[B-Font]dovecot\f[] 661or database servers 662that require 663monotonically-increasing time, 664run 665\fCntp-wait\f[]\fR(@NTP_WAIT_MS@)\f[] 666as late as possible in the boot sequence 667(perhaps with the 668\f\*[B-Font]\-v\f[] 669flag) 670and after 671\fCntp-wait\f[]\fR(@NTP_WAIT_MS@)\f[] 672exits successfully 673it is as safe as it will ever be to start any process that require 674stable time. 675.SS "Frequency Discipline" 676The 677\f\*[B-Font]ntpd\fP 678behavior at startup depends on whether the 679frequency file, usually 680\fIntp.drift\f[], 681exists. 682This file 683contains the latest estimate of clock frequency error. 684When the 685\f\*[B-Font]ntpd\fP 686is started and the file does not exist, the 687\f\*[B-Font]ntpd\fP 688enters a special mode designed to quickly adapt to 689the particular system clock oscillator time and frequency error. 690This takes approximately 15 minutes, after which the time and 691frequency are set to nominal values and the 692\f\*[B-Font]ntpd\fP 693enters 694normal mode, where the time and frequency are continuously tracked 695relative to the server. 696After one hour the frequency file is 697created and the current frequency offset written to it. 698When the 699\f\*[B-Font]ntpd\fP 700is started and the file does exist, the 701\f\*[B-Font]ntpd\fP 702frequency is initialized from the file and enters normal mode 703immediately. 704After that the current frequency offset is written to 705the file at hourly intervals. 706.SS "Operating Modes" 707The 708\f\*[B-Font]ntpd\fP 709utility can operate in any of several modes, including 710symmetric active/passive, client/server broadcast/multicast and 711manycast, as described in the 712"Association Management" 713page 714(available as part of the HTML documentation 715provided in 716\fI/usr/share/doc/ntp\f[]). 717It normally operates continuously while 718monitoring for small changes in frequency and trimming the clock 719for the ultimate precision. 720However, it can operate in a one-time 721mode where the time is set from an external server and frequency is 722set from a previously recorded frequency file. 723A 724broadcast/multicast or manycast client can discover remote servers, 725compute server-client propagation delay correction factors and 726configure itself automatically. 727This makes it possible to deploy a 728fleet of workstations without specifying configuration details 729specific to the local environment. 730.sp \n(Ppu 731.ne 2 732 733By default, 734\f\*[B-Font]ntpd\fP 735runs in continuous mode where each of 736possibly several external servers is polled at intervals determined 737by an intricate state machine. 738The state machine measures the 739incidental roundtrip delay jitter and oscillator frequency wander 740and determines the best poll interval using a heuristic algorithm. 741Ordinarily, and in most operating environments, the state machine 742will start with 64s intervals and eventually increase in steps to 7431024s. 744A small amount of random variation is introduced in order to 745avoid bunching at the servers. 746In addition, should a server become 747unreachable for some time, the poll interval is increased in steps 748to 1024s in order to reduce network overhead. 749.sp \n(Ppu 750.ne 2 751 752In some cases it may not be practical for 753\f\*[B-Font]ntpd\fP 754to run continuously. 755A common workaround has been to run the 756\fCntpdate\f[]\fR(@NTPDATE_MS@)\f[] 757or 758\fCsntp\f[]\fR(@SNTP_MS@)\f[] 759programs from a 760\fCcron\f[]\fR(8)\f[] 761job at designated 762times. 763However, these programs do not have the crafted signal 764processing, error checking or mitigation algorithms of 765\f\*[B-Font]ntpd\fP. 766The 767\f\*[B-Font]\-q\f[] 768option is intended for this purpose. 769Setting this option will cause 770\f\*[B-Font]ntpd\fP 771to exit just after 772setting the clock for the first time. 773The procedure for initially 774setting the clock is the same as in continuous mode; most 775applications will probably want to specify the 776\f\*[B-Font]iburst\f[] 777keyword with the 778\f\*[B-Font]server\f[] 779configuration command. 780With this 781keyword a volley of messages are exchanged to groom the data and 782the clock is set in about 10 s. 783If nothing is heard after a 784couple of minutes, the daemon times out and exits. 785After a suitable 786period of mourning, the 787\fCntpdate\f[]\fR(@NTPDATE_MS@)\f[] 788program will be 789retired. 790.sp \n(Ppu 791.ne 2 792 793When kernel support is available to discipline the clock 794frequency, which is the case for stock Solaris, Tru64, Linux and 795FreeBSD, 796a useful feature is available to discipline the clock 797frequency. 798First, 799\f\*[B-Font]ntpd\fP 800is run in continuous mode with 801selected servers in order to measure and record the intrinsic clock 802frequency offset in the frequency file. 803It may take some hours for 804the frequency and offset to settle down. 805Then the 806\f\*[B-Font]ntpd\fP 807is 808stopped and run in one-time mode as required. 809At each startup, the 810frequency is read from the file and initializes the kernel 811frequency. 812.SS "Poll Interval Control" 813This version of NTP includes an intricate state machine to 814reduce the network load while maintaining a quality of 815synchronization consistent with the observed jitter and wander. 816There are a number of ways to tailor the operation in order enhance 817accuracy by reducing the interval or to reduce network overhead by 818increasing it. 819However, the user is advised to carefully consider 820the consequences of changing the poll adjustment range from the 821default minimum of 64 s to the default maximum of 1,024 s. 822The 823default minimum can be changed with the 824\f\*[B-Font]tinker\f[] 825\f\*[B-Font]minpoll\f[] 826command to a value not less than 16 s. 827This value is used for all 828configured associations, unless overridden by the 829\f\*[B-Font]minpoll\f[] 830option on the configuration command. 831Note that most device drivers 832will not operate properly if the poll interval is less than 64 s 833and that the broadcast server and manycast client associations will 834also use the default, unless overridden. 835.sp \n(Ppu 836.ne 2 837 838In some cases involving dial up or toll services, it may be 839useful to increase the minimum interval to a few tens of minutes 840and maximum interval to a day or so. 841Under normal operation 842conditions, once the clock discipline loop has stabilized the 843interval will be increased in steps from the minimum to the 844maximum. 845However, this assumes the intrinsic clock frequency error 846is small enough for the discipline loop correct it. 847The capture 848range of the loop is 500 PPM at an interval of 64s decreasing by a 849factor of two for each doubling of interval. 850At a minimum of 1,024 851s, for example, the capture range is only 31 PPM. 852If the intrinsic 853error is greater than this, the drift file 854\fIntp.drift\f[] 855will 856have to be specially tailored to reduce the residual error below 857this limit. 858Once this is done, the drift file is automatically 859updated once per hour and is available to initialize the frequency 860on subsequent daemon restarts. 861.SS "The huff-n'-puff Filter" 862In scenarios where a considerable amount of data are to be 863downloaded or uploaded over telephone modems, timekeeping quality 864can be seriously degraded. 865This occurs because the differential 866delays on the two directions of transmission can be quite large. 867In 868many cases the apparent time errors are so large as to exceed the 869step threshold and a step correction can occur during and after the 870data transfer is in progress. 871.sp \n(Ppu 872.ne 2 873 874The huff-n'-puff filter is designed to correct the apparent time 875offset in these cases. 876It depends on knowledge of the propagation 877delay when no other traffic is present. 878In common scenarios this 879occurs during other than work hours. 880The filter maintains a shift 881register that remembers the minimum delay over the most recent 882interval measured usually in hours. 883Under conditions of severe 884delay, the filter corrects the apparent offset using the sign of 885the offset and the difference between the apparent delay and 886minimum delay. 887The name of the filter reflects the negative (huff) 888and positive (puff) correction, which depends on the sign of the 889offset. 890.sp \n(Ppu 891.ne 2 892 893The filter is activated by the 894\f\*[B-Font]tinker\f[] 895command and 896\f\*[B-Font]huffpuff\f[] 897keyword, as described in 898\fCntp.conf\f[]\fR(5)\f[]. 899.SH "ENVIRONMENT" 900See \fBOPTION PRESETS\fP for configuration environment variables. 901.SH FILES 902.TP 15 903.NOP \fI/etc/ntp.conf\f[] 904the default name of the configuration file 905.br 906.ns 907.TP 15 908.NOP \fI/etc/ntp.drift\f[] 909the default name of the drift file 910.br 911.ns 912.TP 15 913.NOP \fI/etc/ntp.keys\f[] 914the default name of the key file 915.PP 916.SH "EXIT STATUS" 917One of the following exit values will be returned: 918.TP 919.NOP 0 " (EXIT_SUCCESS)" 920Successful program execution. 921.TP 922.NOP 1 " (EXIT_FAILURE)" 923The operation failed or the command syntax was not valid. 924.TP 925.NOP 70 " (EX_SOFTWARE)" 926libopts had an internal operational error. Please report 927it to autogen-users@lists.sourceforge.net. Thank you. 928.PP 929.SH "SEE ALSO" 930\fCntp.conf\f[]\fR(5)\f[], 931\fCntpdate\f[]\fR(@NTPDATE_MS@)\f[], 932\fCntpdc\f[]\fR(@NTPDC_MS@)\f[], 933\fCntpq\f[]\fR(@NTPQ_MS@)\f[], 934\fCsntp\f[]\fR(@SNTP_MS@)\f[] 935.sp \n(Ppu 936.ne 2 937 938In addition to the manual pages provided, 939comprehensive documentation is available on the world wide web 940at 941\f[C]http://www.ntp.org/\f[]. 942A snapshot of this documentation is available in HTML format in 943\fI/usr/share/doc/ntp\f[]. 944David L. Mills, 945\fINetwork Time Protocol (Version 1)\fR, 946RFC1059 947.PP 948 949David L. Mills, 950\fINetwork Time Protocol (Version 2)\fR, 951RFC1119 952.PP 953 954David L. Mills, 955\fINetwork Time Protocol (Version 3)\fR, 956RFC1305 957.PP 958 959David L. Mills and J. Martin, Ed. and J. Burbank and W. Kasch, 960\fINetwork Time Protocol Version 4: Protocol and Algorithms Specification\fR, 961RFC5905 962.PP 963 964David L. Mills and B. Haberman, Ed., 965\fINetwork Time Protocol Version 4: Autokey Specification\fR, 966RFC5906 967.PP 968 969H. Gerstung and C. Elliott and B. Haberman, Ed., 970\fIDefinitions of Managed Objects for Network Time Protocol Version 4: (NTPv4)\fR, 971RFC5907 972.PP 973 974R. Gayraud and B. Lourdelet, 975\fINetwork Time Protocol (NTP) Server Option for DHCPv6\fR, 976RFC5908 977.PP 978 979.SH "AUTHORS" 980The University of Delaware and Network Time Foundation 981.SH "COPYRIGHT" 982Copyright (C) 1992-2015 The University of Delaware and Network Time Foundation all rights reserved. 983This program is released under the terms of the NTP license, <http://ntp.org/license>. 984.SH BUGS 985The 986\f\*[B-Font]ntpd\fP 987utility has gotten rather fat. 988While not huge, it has gotten 989larger than might be desirable for an elevated-priority 990\f\*[B-Font]ntpd\fP 991running on a workstation, particularly since many of 992the fancy features which consume the space were designed more with 993a busy primary server, rather than a high stratum workstation in 994mind. 995.sp \n(Ppu 996.ne 2 997 998Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 999.SH NOTES 1000Portions of this document came from FreeBSD. 1001.sp \n(Ppu 1002.ne 2 1003 1004This manual page was \fIAutoGen\fP-erated from the \fBntpd\fP 1005option definitions. 1006