contrib/ntp/html/miscopt.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
   2 <html>
   3 <head>
   4 <meta name="generator" content="HTML Tidy, see www.w3.org">
   5 <title>Miscellaneous Options</title>
   6 </head>
   7 <body>
   8 <h3>Miscellaneous Options</h3>
   9
  10 <img align="left" src="pic/boom3.gif" alt="gif"><a href=
  11 "http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>,
  12 Walt Kelly</a>
  13
  14 <p>We have three, now looking for more.<br clear="left">
  15 </p>
  16
  17 <hr>
  18 <dl>
  19 <dt><tt>broadcastdelay <i>seconds</i></tt></dt>
  20
  21 <dd>The broadcast and multicast modes require a special calibration
  22 to determine the network delay between the local and remote
  23 servers. Ordinarily, this is done automatically by the initial
  24 protocol exchanges between the client and server. In some cases,
  25 the calibration procedure may fail due to network or server access
  26 controls, for example. This command specifies the default delay to
  27 be used under these circumstances. Typically (for Ethernet), a
  28 number between 0.003 and 0.007 seconds is appropriate. The default
  29 when this command is not used is 0.004 seconds.</dd>
  30
  31 <dt><tt>driftfile <i>driftfile</i></tt></dt>
  32
  33 <dd>This command specifies the name of the file used to record the
  34 frequency offset of the local clock oscillator. If the file exists,
  35 it is read at startup in order to set the initial frequency offset
  36 and then updated once per hour with the current frequency offset
  37 computed by the daemon. If the file does not exist or this command
  38 is not given, the initial frequency offset is assumed zero. In this
  39 case, it may take some hours for the frequency to stabilize and the
  40 residual timing errors to subside.
  41
  42 <p>The file format consists of a single line containing a single
  43 floating point number, which records the frequency offset measured
  44 in parts-per-million (PPM). The file is updated by first writing
  45 the current drift value into a temporary file and then renaming
  46 this file to replace the old version. This implies that <tt>
  47 ntpd</tt> must have write permission for the directory the drift
  48 file is located in, and that file system links, symbolic or
  49 otherwise, should be avoided.</p>
  50 </dd>
  51
  52 <dt><tt>enable [auth | bclient | calibrate | kernel | monitor | ntp
  53 | stats]</tt><br>
  54 <tt>disable [auth | bclient | calibrate | kernel | monitor | ntp |
  55 stats</tt></dt>
  56
  57 <dd>Provides a way to enable or disable various server options.
  58 Flags not mentioned are unaffected. Note that all of these flags
  59 can be controlled remotely using the <a href="ntpdc.htm"><tt>
  60 ntpdc</tt></a> utility program.</dd>
  61
  62 <dd>
  63 <dl>
  64 <dt><tt>bclient</tt></dt>
  65
  66 <dd>When enabled, this is identical to the <tt>broadcastclient</tt>
  67 command. The default for this flag is <tt>disable</tt>.</dd>
  68
  69 <dt><tt>calibrate</tt></dt>
  70
  71 <dd>Enables the calibration facility, which automatically adjusts
  72 the <tt>time1</tt> values for each clock driver to display the same
  73 offset as the currently selected source or kernel discipline
  74 signal. See the <a href="refclock.htm">Reference Clock Drivers</a>
  75 for further information. The default for this flag is <tt>
  76 disable</tt>.</dd>
  77
  78 <dt><tt>kernel</tt></dt>
  79
  80 <dd>Enables the precision-time kernel support for the <tt>
  81 ntp_adjtime()</tt> system call, if implemented. Ordinarily, support
  82 for this routine is detected automatically when the NTP daemon is
  83 compiled, so it is not necessary for the user to worry about this
  84 flag. It flag is provided primarily so that this support can be
  85 disabled during kernel development. The default for this flag is
  86 <tt>enable</tt>.</dd>
  87
  88 <dt><tt>monitor</tt></dt>
  89
  90 <dd>Enables the monitoring facility. See the <tt>ntpdc</tt> program
  91 and the <tt>monlist</tt> command or further information. The
  92 default for this flag is <tt>enable</tt>.</dd>
  93
  94 <dt><tt>ntp</tt></dt>
  95
  96 <dd>Enables the server to adjust its local clock by means of NTP.
  97 If disabled, the local clock free-runs at its intrinsic time and
  98 frequency offset. This flag is useful in case the local clock is
  99 controlled by some other device or protocol and NTP is used only to
 100 provide synchronization to other clients. In this case, the local
 101 clock driver can be used to provide this function and also certain
 102 time variables for error estimates and leap-indicators. See the <a
 103 href="refclock.htm">Reference Clock Drivers</a> page for further
 104 information. The default for this flag is <tt>enable</tt>.</dd>
 105
 106 <dt><tt>stats</tt></dt>
 107
 108 <dd>Enables the statistics facility. See the <a href="monopt.htm">
 109 Monitoring Options</a> page for further information. The default
 110 for this flag is <tt>enable</tt>.</dd>
 111 </dl>
 112 </dd>
 113
 114 <dt><tt>logconfig <i>configkeyword</i></tt></dt>
 115
 116 <dd>This command controls the amount and type of output written to
 117 the system <tt>syslog</tt> facility or the alternate <tt>
 118 logfile</tt> log file. By default, all output is turned on. All <i>
 119 <tt>configkeyword</tt></i> keywords can be prefixed with <tt>
 120 =</tt>, <tt>+</tt> and <tt>-</tt>, where <tt>=</tt> sets the <tt>
 121 syslogmask</tt>, <tt>+</tt> adds and <tt>-</tt> removes messages.
 122 <tt>syslog messages</tt> can be controlled in four classes
 123 (<tt>clock</tt>, <tt>peer</tt>, <tt>sys</tt> and <tt>sync</tt>).
 124 Within these classes four types of messages can be controlled.</dd>
 125
 126 <dd>Informational messages (<tt>info</tt>) control configuration
 127 information. Event messages (<tt>events</tt>) control logging of
 128 events (reachability, synchronization, alarm conditions).
 129 Statistical output is controlled with the <tt>statistics</tt>
 130 keyword. The final message group is the status messages. This
 131 describes mainly the synchronizations status. Configuration
 132 keywords are formed by concatenating the message class with the
 133 event class. The <tt>all</tt> prefix can be used instead of a
 134 message class. A message class may also be followed by the <tt>
 135 all</tt> keyword to enable/disable all messages of the respective
 136 message class.</dd>
 137
 138 <dd>Thus, a minimal log configuration could look like this:
 139
 140 <p><tt>logconfig=syncstatus +sysevents</tt></p>
 141
 142 <p>This would just list the synchronizations state of <tt>ntpd</tt>
 143 and the major system events. For a simple reference server, the
 144 following minimum message configuration could be useful:</p>
 145
 146 <p><tt>logconfig=syncall +clockall</tt></p>
 147
 148 <p>This configuration will list all clock information and
 149 synchronization information. All other events and messages about
 150 peers, system events and so on is suppressed.</p>
 151 </dd>
 152
 153 <dt><tt>logfile <i>logfile</i></tt></dt>
 154
 155 <dd>This command specifies the location of an alternate log file to
 156 be used instead of the default system <tt>syslog</tt>
 157 facility.</dd>
 158
 159 <dt><tt>setvar <i>variable</i> [default]</tt></dt>
 160
 161 <dd>This command adds an additional system variable. These
 162 variables can be used to distribute additional information such as
 163 the access policy. If the variable of the form <tt><i>name</i> =
 164 <i>value</i></tt> is followed by the <tt>default</tt> keyword, the
 165 variable will be listed as part of the default system variables
 166 (<tt>ntpq rv</tt> command). These additional variables serve
 167 informational purposes only. They are not related to the protocol
 168 other that they can be listed. The known protocol variables will
 169 always override any variables defined via the <tt>setvar</tt>
 170 mechanism. There are three special variables that contain the names
 171 of all variable of the same group. The <tt>sys_var_list</tt> holds
 172 the names of all system variables. The <tt>peer_var_list</tt> holds
 173 the names of all peer variables and the <tt>clock_var_list</tt>
 174 holds the names of the reference clock variables.</dd>
 175
 176 <dt><tt>tinker [ step <i>step</i> | panic <i>panic</i> | dispersion
 177 <i>dispersion</i> | stepout <i>stepout</i> | minpoll <i>minpoll</i>
 178 ]</tt></dt>
 179
 180 <dd>This command can be used to alter several system variables in
 181 very exceptional circumstances. It should occur in the
 182 configuration file before any other configuration options. The
 183 default values of these variables have been carefully optimized for
 184 a wide range of network speeds and reliability expectations. In
 185 general, they interact in intricate ways that are hard to predict
 186 and some combinations can result in some very nasty behavior. Very
 187 rarely is it necessary to change the default values; but, some
 188 folks can't resist twisting the knobs anyway and this command is
 189 for them. Emphasis added: twisters are on their own and can expect
 190 no help from the support group.
 191
 192 <p>All arguments are in floating point seconds or seconds per
 193 second. The <tt>minpoll</tt> argument is an integer in seconds to
 194 the power of two. The variables operate as follows:</p>
 195 </dd>
 196
 197 <dd>
 198 <dl>
 199 <dt><tt>step <i>step</i></tt></dt>
 200
 201 <dd>The argument becomes the new value for the step threshold,
 202 normally 0.128 s. If set to zero, step adjustments will never
 203 occur. In general, if the intent is only to avoid step adjustments,
 204 the step threshold should be left alone and the <tt>-x</tt> command
 205 line option be used instead.</dd>
 206
 207 <dt><tt>panic <i>panic</i></tt></dt>
 208
 209 <dd>The argument becomes the new value for the panic threshold,
 210 normally 1000 s. If set to zero, the panic sanity check is disabled
 211 and a clock offset of any value will be accepted.</dd>
 212
 213 <dt><tt>dispersion <i>dispersion</i></tt></dt>
 214
 215 <dd>The argument becomes the new value for the dispersion increase
 216 rate, normally .000015.</dd>
 217
 218 <dt><tt>stepout <i>stepout</i></tt></dt>
 219
 220 <dd>The argument becomes the new value for the watchdog timeout,
 221 normally 900 s.</dd>
 222
 223 <dt><tt>minpoll <i>minpoll</i></tt></dt>
 224
 225 <dd>The argument becomes the new value for the minimum poll
 226 interval used when configuring multicast client, manycast client
 227 and , symmetric passive mode association. The value defaults to 6
 228 (64 s) and has a lower limit of 4 (16 s).</dd>
 229
 230 <dt><tt>allan <i>allan</i></tt></dt>
 231
 232 <dd>The argument becomes the new value for the minimum Allan
 233 intercept, which is a parameter of the PLL/FLL clock discipline
 234 algorithm. The value defaults to 1024 s, which is also the lower
 235 limit.</dd>
 236
 237 <dt><tt>huffpuff <i>huffpuff</i></tt></dt>
 238
 239 <dd>The argument becomes the new value for the experimental
 240 huff-n'-puff filter span, which determines the most recent interval
 241 the algorithm will search for a minimum delay. The lower limit is
 242 900 s (15 m), but a more reasonable value is 7200 (2 hours). There
 243 is no default, since the filter is not enabled unless this command
 244 is given.</dd>
 245 </dl>
 246 </dd>
 247
 248 <dt><tt>trap <i>host_address</i> [port <i>port_number</i>]
 249 [interface <i>interface_address</i>]</tt></dt>
 250
 251 <dd>This command configures a trap receiver at the given host
 252 address and port number for sending messages with the specified
 253 local interface address. If the port number is unspecified, a value
 254 of 18447 is used. If the interface address is not specified, the
 255 message is sent with a source address of the local interface the
 256 message is sent through. Note that on a multihomed host the
 257 interface used may vary from time to time with routing changes.
 258
 259 <p>The trap receiver will generally log event messages and other
 260 information from the server in a log file. While such monitor
 261 programs may also request their own trap dynamically, configuring a
 262 trap receiver will ensure that no messages are lost when the server
 263 is started.</p>
 264 </dd>
 265 </dl>
 266
 267 <h4>Files</h4>
 268
 269 <tt>ntp.drift</tt> frequency compensation (PPM)
 270
 271 <hr>
 272 <a href="index.htm"><img align="left" src="pic/home.gif" alt=
 273 "gif"></a>
 274
 275 <address><a href="mailto:mills@udel.edu">David L. Mills
 276 &lt;mills@udel.edu&gt;</a></address>
 277 </body>
 278 </html>
 279