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