usr.sbin/ntp/doc/ntpdate.8

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