usr.sbin/ntp/doc/ntpdate.8

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