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