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