usr.sbin/ntp/ntpdate/ntpdate.8

   1 .\"     $NetBSD: ntpdate.8,v 1.8 2002/12/21 12:32:24 wiz Exp $
   2 .\" Converted from HTML to mandoc by ntp-html2mdoc.pl
   3 .\"
   4 .Dd March 29, 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 .Op Ar server ...
  20 .Sh DESCRIPTION
  21 .Nm
  22 sets the local date and time by polling the Network Time
  23 Protocol (NTP) server(s) given as the
  24 .Ar server
  25 arguments to determine
  26 the correct time. It must be run as root on the local host. A number of
  27 samples are obtained from each of the servers specified and a subset of
  28 the NTP clock filter and selection algorithms are applied to select the
  29 best of these. Note that the accuracy and reliability of
  30 .Nm
  31 depends on the number of servers, the number of polls each time it is run
  32 and the interval between runs.
  33 .Pp
  34 .Nm
  35 can be run manually as necessary to set the host clock,
  36 or it can be run from the host startup script to set the clock at boot
  37 time. This is useful in some cases to set the clock initially before starting
  38 the NTP daemon
  39 .Pa ntpd .
  40 It is also possible to run
  41 .Nm
  42 from a
  43 .Pa cron
  44 script. However, it is important to note that
  45 .Nm
  46 with contrived
  47 .Pa cron
  48 scripts is no substitute for the NTP daemon,
  49 which uses sophisticated algorithms to maximize accuracy and reliability
  50 while minimizing resource use. Finally, since
  51 .Nm
  52 does not
  53 discipline the host clock frequency as does
  54 .Pa ntpd ,
  55 the accuracy
  56 using
  57 .Nm
  58 is limited.
  59 .Pp
  60 Time adjustments are made by
  61 .Nm
  62 in one of two ways. If
  63 .Nm
  64 determines the clock is in error more than 0.5 second
  65 it will simply step the time by calling the system
  66 .Xr settimeofday 2
  67 routine. If the error is less than 0.5 seconds, it will slew the time by
  68 calling the system
  69 .Xr adjtime 2
  70 routine. The latter technique is
  71 less disruptive and more accurate when the error is small, and works quite
  72 well when
  73 .Nm
  74 is run by
  75 .Pa cron
  76 every hour or two.
  77 .Pp
  78 .Nm
  79 will decline to set the date if an NTP server daemon
  80 (e.g.,
  81 .Pa ntpd
  82 ) is running on the same host. When running
  83 .Nm
  84 on a regular basis from
  85 .Pa cron
  86 as an alternative to running a daemon,
  87 doing so once every hour or two will result in precise enough timekeeping
  88 to avoid stepping the clock.
  89 .Pp
  90 If NetInfo support is compiled into
  91 .Nm ,
  92 then the
  93 .Pa server
  94 argument is optional if
  95 .Nm
  96 can find a time
  97 server in the NetInfo configuration for
  98 .Pa ntpd
  99 .
 100 .Sh COMMAND LINE OPTIONS
 101 .Bl -tag -width indent
 102 .It Fl a Ar key
 103 Enable the authentication function and specify the key identifier to be
 104 used for authentication as the argument
 105 .Ar key
 106 .Nm .
 107 The
 108 keys and key identifiers must match in both the client and server key files.
 109 The default is to disable the authentication function.
 110 .It Fl B
 111 Force the time to always be slewed using the adjtime() system call, even
 112 if the measured offset is greater than +-128 ms. The default is to step
 113 the time using settimeofday() if the offset is greater than +-128 ms. Note
 114 that, if the offset is much greater than +-128 ms in this case, that it
 115 can take a long time (hours) to slew the clock to the correct value. During
 116 this time. the host should not be used to synchronize clients.
 117 .It Fl b
 118 Force the time to be stepped using the settimeofday() system call, rather
 119 than slewed (default) using the adjtime() system call. This option should
 120 be used when called from a startup file at boot time.
 121 .It Fl d
 122 Enable the debugging mode, in which
 123 .Nm
 124 will go through all
 125 the steps, but not adjust the local clock. Information useful for general
 126 debugging will also be printed.
 127 .It Fl e Ar authdelay
 128 Specify the processing delay to perform an authentication function as the
 129 value
 130 .Ar authdelay
 131 , in seconds and fraction (see
 132 .Pa ntpd
 133 for
 134 details). This number is usually small enough to be negligible for most
 135 purposes, though specifying a value may improve timekeeping on very slow
 136 CPU's.
 137 .It Fl k Ar keyfile
 138 Specify the path for the authentication key file as the string
 139 .Ar keyfile
 140 .
 141 The default is
 142 .Pa /etc/ntp.keys .
 143 This file should be in the format
 144 described in
 145 .Pa ntpd
 146 .
 147 .It Fl o Ar version
 148 Specify the NTP version for outgoing packets as the integer
 149 .Ar version
 150 ,
 151 which can be 1 or 2. The default is 3. This allows
 152 .Nm
 153 to
 154 be used with older NTP versions.
 155 .It Fl p Ar samples
 156 Specify the number of samples to be acquired from each server as the integer
 157 .Ar samples
 158 , with values from 1 to 8 inclusive. The default is 4.
 159 .It Fl q
 160 Query only - don't set the clock.
 161 .It Fl s
 162 Divert logging output from the standard output (default) to the system
 163 .Pa syslog
 164 facility. This is designed primarily for convenience of
 165 .Pa cron
 166 scripts.
 167 .It Fl t Ar timeout
 168 Specify the maximum time waiting for a server response as the value
 169 .Ar timeout
 170 ,
 171 in seconds and fraction. The value is is rounded to a multiple of 0.2 seconds.
 172 The default is 1 second, a value suitable for polling across a LAN.
 173 .It Fl u
 174 Direct
 175 .Nm
 176 to use an unprivileged port for outgoing packets.
 177 This is most useful when behind a firewall that blocks incoming traffic
 178 to privileged ports, and you want to synchronise with hosts beyond the
 179 firewall. Note that the
 180 .Fl d
 181 option always uses unprivileged ports.
 182 .It Fl v
 183 Be verbose. This option will cause
 184 .Nm
 185 's version identification
 186 string to be logged.
 187 .El
 188 .Sh FILES
 189 .Bl -tag -width /etc/ntp.keys -compact
 190 .It Pa /etc/ntp.keys
 191 encryption keys used by
 192 .Nm .
 193 .El
 194 .Sh AUTHORS
 195 David L. Mills (mills@udel.edu)
 196 .Sh BUGS
 197 The slew adjustment is actually 50% larger than the measured offset, since
 198 this (it is argued) will tend to keep a badly drifting clock more accurate.
 199 This is probably not a good idea and may cause a troubling hunt for some
 200 values of the kernel variables
 201 .Pa tick
 202 and
 203 .Pa tickadj .