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