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