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