1.\" 2.\" $FreeBSD$ 3.\" 4.Dd January 6, 2000 5.Dt NTPDATE 8 6.Os 7.Sh NAME 8.Nm ntpdate 9.Nd set the date and time via NTP 10.Sh SYNOPSIS 11.Nm 12.Op Fl bBdoqsuv 13.Op Fl a Ar key 14.Op Fl e Ar authdelay 15.Op Fl k Ar keyfile 16.Op Fl o Ar version 17.Op Fl p Ar samples 18.Op Fl t Ar timeout 19.Ar server ... 20.Sh DESCRIPTION 21.Pp 22.Em Note : 23The functionality of this program is now available 24in the 25.Xr ntpd 8 26program. 27See the 28.Fl q 29command line 30option in the 31.Xr ntpd 8 32page. 33After a suitable period of 34mourning, the 35.Nm 36utility is to be retired from this 37distribution. 38.Pp 39The 40.Nm 41utility sets the local date and time by polling the 42Network Time Protocol (NTP) server(s) given as the 43.Ar server 44arguments to determine the correct time. 45It must be run as root on 46the local host. 47A number of samples are obtained from each of the 48servers specified and a subset of the NTP clock filter and 49selection algorithms are applied to select the best of these. 50Note 51that the accuracy and reliability of 52.Nm 53depends on 54the number of servers, the number of polls each time it is run and 55the interval between runs. 56.Pp 57The following options are available: 58.Bl -tag -width indent 59.It Fl a Ar key 60Enable the authentication function and specify the key 61identifier to be used for authentication as the argument 62.Ar key . 63The keys and key identifiers must match 64in both the client and server key files. 65The default is to disable 66the authentication function. 67.It Fl B 68Force the time to always be slewed using the 69.Xr adjtime 2 70system 71call, even if the measured offset is greater than +-128 ms. 72The 73default is to step the time using 74.Xr settimeofday 2 75if the offset is 76greater than +-128 ms. 77Note that, if the offset is much greater 78than +-128 ms in this case, it can take a long time (hours) to 79slew the clock to the correct value. 80During this time, the host 81should not be used to synchronize clients. 82.It Fl b 83Force the time to be stepped using the 84.Xr settimeofday 2 85system 86call, rather than slewed (default) using the 87.Xr adjtime 2 88system call. 89This option should be used when called from a startup file at boot 90time. 91.It Fl d 92Enable the debugging mode, in which 93.Nm 94will go 95through all the steps, but not adjust the local clock. 96Information 97useful for general debugging will also be printed. 98.It Fl e Ar authdelay 99Specify the processing delay to perform an authentication 100function as the value 101.Ar authdelay , 102in seconds and fraction 103(see 104.Xr ntpd 8 105for details). 106This number is usually small 107enough to be negligible for most purposes, though specifying a 108value may improve timekeeping on very slow CPU's. 109.It Fl k Ar keyfile 110Specify the path for the authentication key file as the string 111.Ar keyfile . 112The default is 113.Pa /etc/ntp.keys . 114This file 115should be in the format described in 116.Xr ntpd 8 . 117.It Fl o Ar version 118Specify the NTP version for outgoint packets as the integer 119.Ar version , 120which can be 1 or 2. 121The default is 3. 122This allows 123.Nm 124to be used with older NTP versions. 125.It Fl p Ar samples 126Specify the number of samples to be acquired from each server 127as the integer 128.Ar samples , 129with values from 1 to 8 inclusive. 130The default is 4. 131.It Fl q 132Query only - don't set the clock. 133.It Fl s 134Divert logging output from the standard output (default) to the 135system 136.Xr syslog 3 137facility. 138This is designed primarily for 139convenience of 140.Xr cron 8 141scripts. 142.It Fl t Ar timeout 143Specify the maximum time waiting for a server response as the 144value 145.Ar timeout , 146in seconds and fraction. 147The value is 148rounded to a multiple of 0.2 seconds. 149The default is 1 second, a 150value suitable for polling across a LAN. 151.It Fl u 152Direct 153.Nm 154to use an unprivileged port for outgoing 155packets. 156This is most useful when behind a firewall that blocks 157incoming traffic to privileged ports, and you want to synchronise 158with hosts beyond the firewall. 159Note that the 160.Fl d 161option 162always uses unprivileged ports. 163.It Fl v 164Be verbose. 165This option will cause 166.Nm Ns 's 167version 168identification string to be logged. 169.El 170.Pp 171The 172.Nm 173utility can be run manually as necessary to set the 174host clock, or it can be run from the host startup script to set 175the clock at boot time. 176This is useful in some cases to set the 177clock initially before starting the NTP daemon 178.Xr ntpd 8 . 179It is 180also possible to run 181.Nm 182from a 183.Xr cron 8 184script. 185However, it is important to note that 186.Nm 187with 188contrived 189.Xr cron 8 190scripts is no substitute for the NTP 191daemon, which uses sophisticated algorithms to maximize accuracy 192and reliability while minimizing resource use. 193Finally, since 194.Nm 195does not discipline the host clock frequency as 196does 197.Xr ntpd 8 , 198the accuracy using 199.Nm 200is 201limited. 202.Pp 203Time adjustments are made by 204.Nm 205in one of two 206ways. 207If 208.Nm 209determines the clock is in error more 210than 0.5 second it will simply step the time by calling the system 211.Xr settimeofday 2 212routine. 213If the error is less than 0.5 214seconds, it will slew the time by calling the system 215.Xr adjtime 2 216routine. 217The latter technique is less disruptive 218and more accurate when the error is small, and works quite well 219when 220.Nm 221is run by 222.Xr cron 8 223every hour or 224two. 225.Pp 226The 227.Nm 228utility will decline to set the date if an NTP server 229daemon (e.g., 230.Xr ntpd 8 ) 231is running on the same host. 232When 233running 234.Nm 235on a regular basis from 236.Xr cron 8 237as 238an alternative to running a daemon, doing so once every hour or two 239will result in precise enough timekeeping to avoid stepping the 240clock. 241.Pp 242If NetInfo support is compiled into 243.Nm , 244then the 245.Ic server 246argument is optional if 247.Nm 248can find a 249time server in the NetInfo configuration for 250.Xr ntpd 8 . 251.Sh FILES 252.Bl -tag -width /etc/ntp.keys -compact 253.It Pa /etc/ntp.keys 254contains the encryption keys used by 255.Nm . 256.El 257.Sh SEE ALSO 258.Xr ntpd 8 259.Sh BUGS 260The slew adjustment is actually 50% larger than the measured 261offset, since this (it is argued) will tend to keep a badly 262drifting clock more accurate. 263This is probably not a good idea and 264may cause a troubling hunt for some values of the kernel variables 265.Va kern.clockrate.tick 266and 267.Va kern.clockrate.tickadj . 268