usr.sbin/ntp/doc/ntpdate.8

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