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