[ntpsec commit] Refactoring of configuration docs is finished with miscellaneous options.
Eric S. Raymond
esr at ntpsec.org
Tue Oct 13 00:44:53 UTC 2015
Module: ntpsec
Branch: master
Commit: b7a0cd89e5b8ca48de401c9d8e6fc19028ea5895
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=b7a0cd89e5b8ca48de401c9d8e6fc19028ea5895
Author: Eric S. Raymond <esr at thyrsus.com>
Date: Mon Oct 12 20:24:58 2015 -0400
Refactoring of configuration docs is finished with miscellaneous options.
---
devel-docs/TODO | 32 ++---
docs/includes/misc-options.txt | 313 +++++++++++++++++++++++++++++++++++++++++
docs/miscopt.txt | 262 +---------------------------------
ntpd/ntp.conf.txt | 219 +---------------------------
4 files changed, 325 insertions(+), 501 deletions(-)
diff --git a/devel-docs/TODO b/devel-docs/TODO
index 2ec3a98..daeba65 100644
--- a/devel-docs/TODO
+++ b/devel-docs/TODO
@@ -95,23 +95,16 @@ is not yet tested anywhere but in ntpd itself.
* Run everything through a spell checker.
-* man pages outside of docs/ need to be merged with the
- Mills manpages inside it, with duplications removed. In the
- list below, the original docs content is on the left and
- the external man pages are on the right.
-+
-[options="header"]
-|===========================================================
-| Inside docs | Outside docs
-| docs/ntp_conf.txt | ntpd/ntp.conf.txt
-| docs/ntpdsim.txt | docs/ntpdsim_new.txt
-| - | ntpd/ntp.keys.txt
-| - | scripts/calc_tickadj/calc_tickadj.txt
-| - | scripts/summary.txt
-| - | scripts/ntpsweep/ntpsweep.txt
-| - | scripts/plot_summary.txt
-| - | scripts/update-leap/update-leap.txt
-|===========================================================
+* docs/ntpdsim.txt and docs/ntpdsim_new.txt need to be merged.
+
+* These manpages have no corresponding material inside docs/. Is that OK?
+
+ ntpd/ntp.keys.txt,
+ scripts/calc_tickadj/calc_tickadj.txt,
+ scripts/summary.txt,
+ scripts/ntpsweep/ntpsweep.txt,
+ scripts/plot_summary.txt,
+ scripts/update-leap/update-leap.txt,
* In the docs subdirectory, include/command.txt is an HTML passthrough
in a not entirely successful attempt to emulate the look of the
@@ -132,11 +125,6 @@ is not yet tested anywhere but in ntpd itself.
* Website needs to be integrated (with a contacts and services page,
among other things) and published.
-* The man page for ntp.conf contains a lot of descriptive text that
- should be split out. 3 examples: Autokey, contents of log files,
- multicast/broadcase/manycast.
-
-
=== Remaining procedural issues ===
* The dev changes need to be fed through through Phabricator,
diff --git a/docs/includes/misc-options.txt b/docs/includes/misc-options.txt
new file mode 100644
index 0000000..691c5d0
--- /dev/null
+++ b/docs/includes/misc-options.txt
@@ -0,0 +1,313 @@
+// Miscellaneous options. Gets included twice.
+
+`broadcastdelay` _seconds_::
+ The broadcast and multicast modes require a special calibration to
+ determine the network delay between the local and remote servers.
+ Ordinarily, this is done automatically by the initial protocol
+ exchanges between the client and server. In some cases, the
+ calibration procedure may fail due to network or server access
+ controls, for example. This command specifies the default delay to be
+ used under these circumstances. Typically (for Ethernet), a number
+ between 0.003 and 0.007 seconds is appropriate. The default when this
+ command is not used is 0.004 seconds.
+
+`calldelay` _delay_::
+ This option controls the delay in seconds between the first and second
+ packets sent in burst or iburst mode to allow additional time for a
+ modem or ISDN call to complete.
+
+`driftfile` _driftfile_::
+ This command specifies the complete path and name of the file used to
+ record the frequency of the local clock oscillator. This is the same
+ operation as the `-f` command line option. If the file exists, it is
+ read at startup in order to set the initial frequency and then updated
+ once per hour with the current frequency computed by the daemon. If
+ the file name is specified, but the file itself does not exist, the
+ starts with an initial frequency of zero and creates the file when
+ writing it for the first time. If this command is not given, the
+ daemon will always start with an initial frequency of zero.
++
+The file format consists of a single line containing a single floating
+point number, which records the frequency offset measured in
+parts-per-million (PPM). The file is updated by first writing the
+current drift value into a temporary file and then renaming this file
+to replace the old version. This implies that {ntpdman} must
+have write permission for the directory the drift file is located in,
+and that file system links, symbolic or otherwise, should be avoided.
+
+`enable` [`auth` | `bclient` | `calibrate` | `kernel` | `monitor` | `ntp` | `stats`]; `disable` [`auth` | `bclient` | `calibrate` | `kernel` | `monitor` | `ntp` | `stats`]::
+ Provides a way to enable or disable various server options. Flags not
+ mentioned are unaffected. Note that all of these flags can be
+ controlled remotely using the {ntpqman} utility program.
+
+ `auth`;;
+ Enables the server to synchronize with unconfigured peers only if
+ the peer has been correctly authenticated using either public key or
+ private key cryptography. The default for this flag is `enable`.
+ `bclient`;;
+ Enables the server to listen for a message from a broadcast or
+ multicast server, as in the `multicastclient` command with default
+ address. The default for this flag is `disable`.
+ `calibrate`;;
+ Enables the calibrate feature for reference clocks. The default for
+ this flag is `disable`.
+ `kernel`;;
+ Enables the kernel time discipline, if available. The default for
+ this flag is `enable` if support is available, otherwise `disable`.
+ `monitor`;;
+ Enables the monitoring facility. See the {ntpqman} program
+ and the monlist command for further information. The default for this
+ flag is `enable`.
+ `ntp`;;
+ Enables time and frequency discipline. In effect, this switch opens
+ and closes the feedback loop, which is useful for testing. The
+ default for this flag is `enable`.
+ `stats`;;
+ Enables the statistics facility. See the "Monitoring Options"
+ section for further information. The default for this flag is
+ `disable`.
+
+`includefile` _includefile_::
+ This command allows additional configuration commands to be included
+ from a separate file. Include files may be nested to a depth of five;
+ upon reaching the end of any include file, command processing resumes
+ in the previous configuration file. This option is useful for sites
+ that run {ntpdman} on multiple hosts, with (mostly) common
+ options (e.g., a restriction list).
+
+`interface` [`listen` | `ignore` | `drop`] [`all` | `ipv4` | `ipv6` | `wildcard` | 'name' | 'address'[/'prefixlen']]::
+ This command controls which network addresses `{ntpd}` opens, and
+ whether input is dropped without processing. The first parameter
+ determines the action for addresses which match the second parameter.
+ That parameter specifies a class of addresses, or a specific interface
+ name, or an address. In the address case, _`prefixlen`_ determines how
+ many bits must match for this rule to apply. `ignore` prevents opening
+ matching addresses, `drop` causes `{ntpd}` to open the address and drop
+ all received packets without examination. Multiple `interface`
+ commands can be used. The last rule which matches a particular address
+ determines the action for it. `interface` commands are disabled if any
+ of the `-I`, `--interface`,`-L`, or `--novirtualips` command-line options
+ are used. If none of those options are used and no `interface` actions
+ are specified in the configuration file, all available network
+ addresses are opened. The `nic` command is an alias for `interface`.
+
+`leapfile` 'leapfile'::
+ This command loads the NIST leapseconds file and initializes the
+ leapsecond values for the next leapsecond time, expiration time and
+ TAI offset. The file can be obtained directly from NIST national time
+ servers using `ftp` as the ASCII file `pub/leap-seconds`.
++
+The _leapfile_ is scanned when `{ntpd}` processes the `leapfile`
+directive or when `{ntpd}` detects that _leapfile_ has changed. `{ntpd}`
+checks once a day to see if the _leapfile_ has changed.
++
+While not strictly a security function, the Autokey protocol provides
+means to securely retrieve the current or updated leapsecond values
+from a server.
+
+`logconfig` _configkeyword_::
+ This command controls the amount and type of output written to the
+ system _syslog(3)_ facility or the alternate log file. By
+ default, all output is turned on. All _configkeyword_ keywords can be
+ prefixed with ‘=’, ‘+’ and ‘-’, where ‘=’ sets the syslog(3) priority
+ mask, ‘+’ adds and ‘-’ removes messages. syslog(3) messages can be
+ controlled in four classes (clock,peer,sys and sync). Within these
+ classes four types of messages can be controlled: informational
+ messages (info), event messages (events), statistics messages
+ (statistics) and status messages (status).
++
+Configuration keywords are formed by concatenating the message class
+with the event class. The _all_ prefix can be used instead of a
+message class. A message class may also be followed by the _all_
+keyword to enable/disable all messages of the respective message
+class. Thus, a minimal log configuration could look like this:
++
+--------------------------------
+logconfig =syncstatus +sysevents
+--------------------------------
++
+This would just list the synchronizations state of
+{ntpdman} and the major system events. For a simple reference
+server, the following minimum message configuration could be useful:_
++
+----------------------------
+logconfig =syncall +clockall
+----------------------------
++
+This configuration will list all clock information and synchronization
+information. All other events and messages about peers, system events
+and so on is suppressed.
+
+`logfile` _logfile_::
+ This command specifies the location of an alternate log file to be
+ used instead of the default system _syslog_(3)_ facility. This is the
+ same operation as the -l command line option.
+
+`mru` [`maxdepth` 'count' | `maxmem` 'kilobytes' | `mindepth` 'count' | `maxage` 'se
+conds' | `initalloc` 'count' | `initmem` 'kilobytes' | `incalloc` 'count' | `incmem`
+ 'kilobytes']::
+ Controls size limits of the monitoring facility Most Recently Used
+ (MRU) list of client addresses, which is also
+ used by the rate control facility.
+ `maxdepth` 'count';;
+ `maxmem` 'kilobytes';;
+ Equivalent upper limits on the size of the MRU list, in terms of
+ entries or kilobytes. The actual limit will be up to `incalloc`
+ entries or `incmem` kilobytes larger. As with all of the `mru`
+ options offered in units of entries or kilobytes, if both `maxdepth`
+ and `maxmem` are used, the last one used controls. The default is
+ 1024 kilobytes.
+ `mindepth` 'count';;
+ Lower limit on the MRU list size. When the MRU list has fewer than
+ `mindepth` entries, existing entries are never removed to make room
+ for newer ones, regardless of their age. The default is 600 entries.
+ `maxage` 'seconds';;
+ Once the MRU list has `mindepth` entries and an additional client
+ address is to be added to the list, if the oldest entry was updated
+ more than `maxage` seconds ago, that entry is removed and its
+ storage reused. If the oldest entry was updated more recently, the
+ MRU list is grown, subject to `maxdepth`/`maxmem`. The default is 64
+ seconds.
+ `initalloc` 'count';;
+ `initmem` 'kilobytes';;
+ Initial memory allocation at the time the monitoring facility is
+ first enabled, in terms of entries or kilobytes. The default is 4
+ kilobytes.
+ `incalloc` 'count';;
+ `incmem` 'kilobytes';;
+ Size of additional memory allocations when growing the MRU list, in
+ entries or kilobytes. The default is 4 kilobytes.
+
+`nonvolatile` 'threshold'::
+ Specify the _`threshold`_ in seconds to write the frequency file, with
+ default of 1e-7 (0.1 PPM). The frequency file is inspected each hour.
+ If the difference between the current frequency and the last value
+ written exceeds the threshold, the file is written and the `threshold`
+ becomes the new threshold value. If the threshold is not exceeded, it
+ is reduced by half. This is intended to reduce the frequency of
+ unnecessary file writes for embedded systems with nonvolatile memory.
+
+`phone` 'dial ...'::
+ This command is used in conjunction with the ACTS modem driver (type
+ 18). The arguments consist of a maximum of 10 telephone numbers used
+ to dial USNO, NIST or European time services. The Hayes command
+ ATDT is normally prepended to the number, which can contain other
+ modem control codes as well.
+
+`reset [allpeers] [auth] [ctl] [io] [mem] [sys] [timer]`::
+ Reset one or more groups of counters maintained by {ntpd} and exposed by
+ `{ntpq}`.
+
+`saveconfigdir` 'directory_path'::
+ Specify the directory in which to write configuration snapshots
+ requested with `{ntpq}`'s 'saveconfig' command. If `saveconfigdir`
+ does not appear in the configuration file, saveconfig requests are
+ rejected by {ntpd}.
+
+`setvar` _variable_ [_default_]::
+ This command adds an additional system variable. These variables can
+ be used to distribute additional information such as the access
+ policy. If the variable of the form _name=value_ is followed by the
+ `default` keyword, the variable will be listed as part of the default
+ system variables ({ntpqman} rv command). These additional
+ variables serve informational purposes only. They are not related to
+ the protocol other that they can be listed. The known protocol
+ variables will always override any variables defined via
+ the `setvar` mechanism. There are three special variables that contain the
+ names of all variable of the same group. The `sys_var_list` holds the
+ names of all system variables. The `peer_var_list` holds the names of all
+ peer variables and the `clock_var_list` holds the names of the reference
+ clock variables.
+
+`tinker` [`allan` _allan_ | `dispersion` _dispersion_ | `freq` _freq_ | `huffpuff` _huffpuff_ | `panic` _panic_ | `step` _step_ | `stepback` _stepback_ | `stepfwd` _stepfwd_ | `stepout` _stepout_]::
+ This command can be used to alter several system variables in very
+ exceptional circumstances. It should occur in the configuration file
+ before any other configuration options. The default values of these
+ variables have been carefully optimized for a wide range of network
+ speeds and reliability expectations. In general, they interact in
+ intricate ways that are hard to predict and some combinations can
+ result in some very nasty behavior. Very rarely is it necessary to
+ change the default values; but, some folks cannot resist twisting the
+ knobs anyway and this command is for them. Emphasis added: twisters
+ are on their own and can expect no help from the support group.
++
+The variables operate as follows:
++
+`allan` _allan_;;
+ The argument becomes the new value for the minimum Allan intercept,
+ which is a parameter of the PLL/FLL clock discipline algorithm. The
+ value in log2 seconds defaults to 7 (1024 s), which is also the
+ lower limit.
+ `dispersion` _dispersion_;;
+ The argument becomes the new value for the dispersion increase rate,
+ normally .000015 s/s.
+ `freq` _freq_;;
+ The argument becomes the initial value of the frequency offset in
+ parts-per-million. This overrides the value in the frequency file,
+ if present, and avoids the initial training state if it is not.
+ `huffpuff` _huffpuff_;;
+ The argument becomes the new value for the experimental huff-n'-puff
+ filter span, which determines the most recent interval the algorithm
+ will search for a minimum delay. The lower limit is 900 s (15 m),
+ but a more reasonable value is 7200 (2 hours). There is no default,
+ since the filter is not enabled unless this command is given.
+ `panic` _panic_;;
+ The argument is the panic threshold, normally 1000 s. If set to
+ zero, the panic sanity check is disabled and a clock offset of any
+ value will be accepted.
+ `step` _step_;;
+ The argument is the step threshold, which by default is 0.128 sec. It
+ can be set to any positive number in seconds. If set to zero, step
+ adjustments will never occur. Note: The kernel time discipline is
+ disabled if the step threshold is set to zero or greater than the
+ default.
+ `stepback` _stepback_;;
+ The argument is the step threshold for the backward direction, which
+ by default is 0.128 sec. It can be set to any positive number in
+ seconds. If both the forward and backward step thresholds are set to
+ zero, step adjustments will never occur. Note: The kernel time
+ discipline is disabled if each direction of step threshold are
+ either set to zero or greater than .5 second.
+ `stepfwd` _stepfwd_;;
+ As for stepback, but for the forward direction.
+ `stepout` _stepout_;;
+ The argument is the stepout timeout, which by default is 900 s. It
+ can be set to any positive number in seconds. If set to zero, the
+ stepout pulses will not be suppressed.
+
+`rlimit` [`memlock` _megabytes_ | `stacksize` _4kPages_ | `filenum` _filedescriptors_]::
+
+ `memlock` _megabytes_;;
+ Specify the number of megabytes of memory that can be allocated.
+ Probably only available under Linux, this option is useful when
+ dropping root (the `-i` option). The default is 32 megabytes.
+ Setting this to zero will prevent any attemp to lock memory.
+ `stacksize` _4kPages_;;
+ Specifies the maximum size of the process stack on systems with the
+ mlockall()_function. Defaults to 50 4k pages (200 4k pages in OpenBSD).
+ `filenum` _filedescriptors_;;
+ Specifies the maximum number of file descriptors {ntpd} may have open
+ at once. Defaults to the system default.
+
+`trap` _host_address_ [`port` _port_number_] [`interface` _interface_address_]::
+ This command configures a trap receiver at the given host address and
+ port number for sending messages with the specified local interface
+ address. If the port number is unspecified, a value of 18447 is used.
+ If the interface address is not specified, the message is sent with a
+ source address of the local interface the message is sent through.
+ Note that on a multihomed host the interface used may vary from time
+ to time with routing changes.
++
+The trap receiver will generally log event messages and other
+information from the server in a log file. While such monitor programs
+may also request their own trap dynamically, configuring a trap
+receiver will ensure that no messages are lost when the server is
+started.
+
+`hop` `...`::
+ This command specifies a list of TTL values in increasing order, up to
+ 8 values can be specified. In manycast mode these values are used in
+ turn in an expanding-ring search. The default is eight multiples of 32
+ starting at 31.
+
+// end
diff --git a/docs/miscopt.txt b/docs/miscopt.txt
index 0e99c19..7b18764 100644
--- a/docs/miscopt.txt
+++ b/docs/miscopt.txt
@@ -18,267 +18,7 @@ include::includes/miscopt.txt[]
== Commands and Options ==
-`broadcastdelay` 'delay'::
- In broadcast and multicast modes, means are required to determine the
- network delay between the server and client. Ordinarily, this is done
- automatically by the initial calibration exchanges between the client
- and server. In some cases, the exchange might not be possible due to
- network or server access controls. The value of _`delay`_ is by
- default zero, in which case the exchange is enabled. If _`delay`_ is
- greater than zero, it becomes the roundtrip delay (s), as measured by
- the Unix `ping` program, and the exchange is disabled.
-`driftfile` 'driftfile'::
- This command specifies the complete path and name of the file used to
- record the frequency of the local clock oscillator. This is the same
- operation as the `-f` command line option. This command is mutually
- exclusive with the `freq` option of the `tinker` command.
-+
-If the file exists, it is read at startup in order to set the initial
-frequency and then updated once per hour or more with the current
-frequency computed by the daemon. If the file name is specified, but
-the file itself does not exist, the starts with an initial frequency
-of zero and creates the file when writing it for the first time. If
-this command is not given, the daemon will always start with an
-initial frequency of zero.
-+
-The file format consists of a single line containing a single floating
-point number, which records the frequency offset measured in
-parts-per-million (PPM). The file is updated by first writing the
-current drift value into a temporary file and then renaming this file
-to replace the old version.
-
-`enable [auth | bclient | calibrate | kernel | monitor | ntp | stats]`::
-
-`disable [auth | bclient | calibrate | kernel | monitor | ntp | stats]`::
- Provides a way to enable or disable various system options. Flags not
- mentioned are unaffected. Note that most of these flags can be
- modified remotely using link:ntpq.html[`{ntpq}`] utility program's
- `:config` and `config-from-file` commands.
- `auth`;;
- Enables the server to synchronize with unconfigured peers only if
- the peer has been correctly authenticated using either public key or
- private key cryptography. The default for this flag is enable.
- `bclient`;;
- Enables the server to listen for a message from a broadcast or
- multicast server, as in the `multicastclient` command with default
- address. The default for this flag is disable.
- `calibrate`;;
- Enables the calibrate feature for reference clocks. The default for
- this flag is disable.
- `kernel`;;
- Enables the kernel time discipline, if available. The default for
- this flag is enable if support is available, otherwise disable.
- `monitor`;;
- Enables the monitoring facility. See the link:ntpq.html[`{ntpq}`
- program] and the `monstats` and `mrulist` commands, as well as the
- link:accopt.html#discard[Access Control Options] for details. The
- monitoring facility is also enabled by the presence of
- link:accopt.html#limited[`limited`] in any `restrict` commands. The
- default for this flag is enable.
- `ntp`;;
- Enables time and frequency discipline. In effect, this switch opens
- and closes the feedback loop, which is useful for testing. The
- default for this flag is enable.
- `stats`;;
- Enables the statistics facility. See the link:monopt.html[Monitoring
- Options] page for further information. The default for this flag is
- enabled. This flag is excluded from runtime configuration using
- `{ntpq}`.
-`includefile` 'includefile'::
- This command allows additional configuration commands to be included
- from a separate file. Include files may be nested to a depth of five;
- upon reaching the end of any include file, command processing resumes
- in the previous configuration file. This option is useful for sites
- that run `{ntpd}` on multiple hosts, with (mostly) common options (e.g.,
- a restriction list).
-`interface` [`listen | ignore | drop] [all | ipv4 | ipv6 | wildcard` | 'name' | 'address'[/'prefixlen']]::
- This command controls which network addresses `{ntpd}` opens, and
- whether input is dropped without processing. The first parameter
- determines the action for addresses which match the second parameter.
- That parameter specifies a class of addresses, or a specific interface
- name, or an address. In the address case, _`prefixlen`_ determines how
- many bits must match for this rule to apply. `ignore` prevents opening
- matching addresses, `drop` causes `{ntpd}` to open the address and drop
- all received packets without examination. Multiple `interface`
- commands can be used. The last rule which matches a particular address
- determines the action for it. `interface` commands are disabled if any
- link:ntpd.html#--interface[`-I`],
- link:ntpd.html#--interface[`--interface`],
- link:ntpd.html#--novirtualips[`-L`], or
- link:ntpd.html#--novirtualips[`--novirtualips`] command-line options
- are used. If none of those options are used and no `interface` actions
- are specified in the configuration file, all available network
- addresses are opened. The `nic` command is an alias for `interface`.
-`leapfile` 'leapfile'::
- This command loads the NIST leapseconds file and initializes the
- leapsecond values for the next leapsecond time, expiration time and
- TAI offset. The file can be obtained directly from NIST national time
- servers using `ftp` as the ASCII file `pub/leap-seconds`.
-+
-The _leapfile_ is scanned when `{ntpd}` processes the `leapfile`
-directive or when `{ntpd}` detects that _leapfile_ has changed. `{ntpd}`
-checks once a day to see if the _leapfile_ has changed.
-+
-While not strictly a security function, the Autokey protocol provides
-means to securely retrieve the current or updated leapsecond values
-from a server.
-
-`logconfig` 'configkeyword'::
- This command controls the amount and type of output written to the
- system `syslog` facility or the alternate `logfile` log file. All
- _`configkeyword`_ keywords can be prefixed with `=`, `+` and `-`,
- where `=` sets the `syslogmask`, `+` adds and `-` removes messages.
- `syslog messages` can be controlled in four classes (`clock`, `peer`,
- `sys` and `sync`). Within these classes four types of messages can be
- controlled: informational messages (`info`), event messages
- (`events`), statistics messages (`statistics`) and status messages
- (`status`).
-+
-Configuration keywords are formed by concatenating the message class
-with the event class. The `all` prefix can be used instead of a
-message class. A message class may also be followed by the `all`
-keyword to enable/disable all messages of the respective message
-class. By default, `logconfig` output is set to `allsync`.
-+
-Thus, a minimal log configuration could look like this:
-+
-`logconfig=syncstatus +sysevents`
-+
-This would just list the synchronizations state of `{ntpd}` and the
-major system events. For a simple reference server, the following
-minimum message configuration could be useful:
-+
-`logconfig=syncall +clockall`
-+
-This configuration will list all clock information and synchronization
-information. All other events and messages about peers, system events
-and so on is suppressed.
-
-`logfile` 'logfile'::
- This command specifies the location of an alternate log file to be
- used instead of the default system `syslog` facility. This is the same
- operation as the `-l` command line option.
-`mru` [`maxdepth` 'count' | `maxmem` 'kilobytes' | `mindepth` 'count' | `maxage` 'seconds' | `initalloc` 'count' | `initmem` 'kilobytes' | `incalloc` 'count' | `incmem` 'kilobytes']::
- Controls size limits of the monitoring facility Most Recently Used
- link:ntpq.html#mrulist[(MRU) list] of client addresses, which is also
- used by the link:accopt.html#discard[rate control facility].
- `maxdepth` 'count';;
- `maxmem` 'kilobytes';;
- Equivalent upper limits on the size of the MRU list, in terms of
- entries or kilobytes. The actual limit will be up to `incalloc`
- entries or `incmem` kilobytes larger. As with all of the `mru`
- options offered in units of entries or kilobytes, if both `maxdepth`
- and `maxmem` are used, the last one used controls. The default is
- 1024 kilobytes.
- `mindepth` 'count';;
- Lower limit on the MRU list size. When the MRU list has fewer than
- `mindepth` entries, existing entries are never removed to make room
- for newer ones, regardless of their age. The default is 600 entries.
- `maxage` 'seconds';;
- Once the MRU list has `mindepth` entries and an additional client
- address is to be added to the list, if the oldest entry was updated
- more than `maxage` seconds ago, that entry is removed and its
- storage reused. If the oldest entry was updated more recently, the
- MRU list is grown, subject to `maxdepth`/`maxmem`. The default is 64
- seconds.
- `initalloc` 'count';;
- `initmem` 'kilobytes';;
- Initial memory allocation at the time the monitoring facility is
- first enabled, in terms of entries or kilobytes. The default is 4
- kilobytes.
- `incalloc` 'count';;
- `incmem` 'kilobytes';;
- Size of additional memory allocations when growing the MRU list, in
- entries or kilobytes. The default is 4 kilobytes.
-`nonvolatile` 'threshold'::
- Specify the _`threshold`_ in seconds to write the frequency file, with
- default of 1e-7 (0.1 PPM). The frequency file is inspected each hour.
- If the difference between the current frequency and the last value
- written exceeds the threshold, the file is written and the `threshold`
- becomes the new threshold value. If the threshold is not exceeded, it
- is reduced by half. This is intended to reduce the frequency of
- unnecessary file writes for embedded systems with nonvolatile memory.
-`phone` 'dial ...'::
- This command is used in conjunction with the ACTS modem driver (type
- 18). The arguments consist of a maximum of 10 telephone numbers used
- to dial USNO, NIST or European time services. The Hayes command
- ATDT is normally prepended to the number, which can contain other
- modem control codes as well.
-`reset [allpeers] [auth] [ctl] [io] [mem] [sys] [timer]`::
- Reset one or more groups of counters maintained by {ntpd} and exposed by
- `{ntpq}`.
-`saveconfigdir` 'directory_path'::
- Specify the directory in which to write configuration snapshots
- requested with `{ntpq}`'s link:ntpq.html#saveconfig[saveconfig] command.
- If `saveconfigdir` does not appear in the configuration file,
- saveconfig requests are rejected by {ntpd}.
-`setvar` 'variable' [`default`]::
- This command adds an additional system variable. These variables can
- be used to distribute additional information such as the access
- policy. If the variable of the form `name = value` is followed by the
- `default` keyword, the variable will be listed as part of the default
- system variables (`{ntpq} rv` command). These additional variables serve
- informational purposes only. They are not related to the protocol
- other that they can be listed. The known protocol variables will
- always override any variables defined via the `setvar` mechanism.
- There are three special variables that contain the names of all
- variable of the same group. The `sys_var_list` holds the names of all
- system variables. The `peer_var_list` holds the names of all peer
- variables and the `clock_var_list` holds the names of the reference
- clock variables.
-`tinker` [`allan` 'allan' | `dispersion` 'dispersion' | `freq` 'freq' | `huffpuff` 'huffpuff' | `panic` 'panic' | `step` 'step' | `stepout` 'stepout']::
- This command alters certain system variables used by the clock
- discipline algorithm. The default values of these variables have been
- carefully optimized for a wide range of network speeds and reliability
- expectations. Very rarely is it necessary to change the default
- values; but, some folks can't resist twisting the knobs. Options are
- as follows:
- `allan` 'allan';;
- Specifies the Allan intercept, which is a parameter of the PLL/FLL
- clock discipline algorithm, in seconds with default 1500 s.
- `dispersion` 'dispersion';;
- Specifies the dispersion increase rate in parts-per-million (PPM)
- with default 15 PPM.
- `freq` 'freq';;
- Specifies the frequency offset in parts-per-million (PPM). This
- option is mutually exclusive with the driftfile command.
- `huffpuff` 'huffpuff';;
- Specifies the huff-n'-puff filter span, which determines the most
- recent interval the algorithm will search for a minimum delay. The
- lower limit is 900 s (15 min), but a more reasonable value is 7200
- (2 hours).See the link:huffpuff.html[Huff-n'-Puff Filter] page for
- further information.
- `panic` 'panic';;
- Specifies the panic threshold in seconds with default 1000 s. If set
- to zero, the panic sanity check is disabled and a clock offset of
- any value will be accepted.
- `step` 'step';;
- Specifies the step threshold in seconds. The default without this
- command is 0.128 s. If set to zero, step adjustments will never
- occur. Note: The kernel time discipline is disabled if the step
- threshold is set to zero or greater than 0.5 s. Further details are
- on the link:clock.html[Clock State Machine] page.
- `stepout` 'stepout';;
- Specifies the stepout threshold in seconds. The default without this
- command is 300 s. Since this option also affects the training and
- startup intervals, it should not be set less than the default.
- Further details are on the link:clock.html[Clock State Machine]
- page.
-`rlimit` [`memlock` 'Nmegabytes' | `stacksize` 'N4kPages' | `filenum` 'Nfiledescriptors']::
- This command alters certain process storage allocation limits, and is
- only available on some operating systems. Options are as follows:
- `memlock` 'Nmegabytes';;
- Specify the number of megabytes of memory that can be allocated.
- Probably only available under Linux, this option is useful when
- dropping root (the `-i` option). The default is 32 megabytes.
- Setting this to zero will prevent any attemp to lock memory.
- `stacksize` 'N4kPages';;
- Specifies the maximum size of the process stack on systems with the
- `mlockall()` function. Defaults to 50 4k pages (200 4k pages in
- OpenBSD).
- `filenum` 'Nfiledescriptors';;
- Specifies the maximum number of file descriptors {ntpd} may have open
- at the same time. Defaults to system default.
+include::includes/misc-opts.txt[]
// A subset of the tos options is described on the ntp.conf manual page.
// If you change this, be very sure to keep that syncronized.
diff --git a/ntpd/ntp.conf.txt b/ntpd/ntp.conf.txt
index 71753a9..feab0c6 100644
--- a/ntpd/ntp.conf.txt
+++ b/ntpd/ntp.conf.txt
@@ -239,224 +239,7 @@ include::../docs/includes/clock-options.txt[]
== Miscellaneous Options ==
-`broadcastdelay` _seconds_::
- The broadcast and multicast modes require a special calibration to
- determine the network delay between the local and remote servers.
- Ordinarily, this is done automatically by the initial protocol
- exchanges between the client and server. In some cases, the
- calibration procedure may fail due to network or server access
- controls, for example. This command specifies the default delay to be
- used under these circumstances. Typically (for Ethernet), a number
- between 0.003 and 0.007 seconds is appropriate. The default when this
- command is not used is 0.004 seconds.
-
-`calldelay` _delay_::
- This option controls the delay in seconds between the first and second
- packets sent in burst or iburst mode to allow additional time for a
- modem or ISDN call to complete.
-
-`driftfile` _driftfile_::
- This command specifies the complete path and name of the file used to
- record the frequency of the local clock oscillator. This is the same
- operation as the `-f` command line option. If the file exists, it is
- read at startup in order to set the initial frequency and then updated
- once per hour with the current frequency computed by the daemon. If
- the file name is specified, but the file itself does not exist, the
- starts with an initial frequency of zero and creates the file when
- writing it for the first time. If this command is not given, the
- daemon will always start with an initial frequency of zero.
-+
-The file format consists of a single line containing a single floating
-point number, which records the frequency offset measured in
-parts-per-million (PPM). The file is updated by first writing the
-current drift value into a temporary file and then renaming this file
-to replace the old version. This implies that {ntpdman} must
-have write permission for the directory the drift file is located in,
-and that file system links, symbolic or otherwise, should be avoided.
-
-`enable` [`auth` | `bclient` | `calibrate` | `kernel` | `monitor` | `ntp` | `stats`]; `disable` [`auth` | `bclient` | `calibrate` | `kernel` | `monitor` | `ntp` | `stats`]::
- Provides a way to enable or disable various server options. Flags not
- mentioned are unaffected. Note that all of these flags can be
- controlled remotely using the {ntpqman} utility program.
-
- `auth`;;
- Enables the server to synchronize with unconfigured peers only if
- the peer has been correctly authenticated using either public key or
- private key cryptography. The default for this flag is `enable`.
- `bclient`;;
- Enables the server to listen for a message from a broadcast or
- multicast server, as in the `multicastclient` command with default
- address. The default for this flag is `disable`.
- `calibrate`;;
- Enables the calibrate feature for reference clocks. The default for
- this flag is `disable`.
- `kernel`;;
- Enables the kernel time discipline, if available. The default for
- this flag is `enable` if support is available, otherwise `disable`.
- `monitor`;;
- Enables the monitoring facility. See the {ntpqman} program
- and the monlist command for further information. The default for this
- flag is `enable`.
- `ntp`;;
- Enables time and frequency discipline. In effect, this switch opens
- and closes the feedback loop, which is useful for testing. The
- default for this flag is `enable`.
- `stats`;;
- Enables the statistics facility. See the "Monitoring Options"
- section for further information. The default for this flag is
- `disable`.
-
-`includefile` _includefile_::
- This command allows additional configuration commands to be included
- from a separate file. Include files may be nested to a depth of five;
- upon reaching the end of any include file, command processing resumes
- in the previous configuration file. This option is useful for sites
- that run {ntpdman} on multiple hosts, with (mostly) common
- options (e.g., a restriction list).
-
-`logconfig` _configkeyword_::
- This command controls the amount and type of output written to the
- system _syslog(3)_ facility or the alternate log file. By
- default, all output is turned on. All _configkeyword_ keywords can be
- prefixed with ‘=’, ‘+’ and ‘-’, where ‘=’ sets the syslog(3) priority
- mask, ‘+’ adds and ‘-’ removes messages. syslog(3) messages can be
- controlled in four classes (clock,peer,sys and sync). Within these
- classes four types of messages can be controlled: informational
- messages (info), event messages (events), statistics messages
- (statistics) and status messages (status).
-+
-Configuration keywords are formed by concatenating the message class
-with the event class. The _all_ prefix can be used instead of a
-message class. A message class may also be followed by the _all_
-keyword to enable/disable all messages of the respective message
-class. Thus, a minimal log configuration could look like this:
-+
---------------------------------
-logconfig =syncstatus +sysevents
---------------------------------
-+
-This would just list the synchronizations state of
-{ntpdman} and the major system events. For a simple reference
-server, the following minimum message configuration could be useful:_
-+
-----------------------------
-logconfig =syncall +clockall
-----------------------------
-+
-This configuration will list all clock information and synchronization
-information. All other events and messages about peers, system events
-and so on is suppressed.
-
-`logfile` _logfile_::
- This command specifies the location of an alternate log file to be
- used instead of the default system _syslog_(3)_ facility. This is the
- same operation as the -l command line option.
-
-`setvar` _variable_ [_default_]::
- This command adds an additional system variable. These variables can
- be used to distribute additional information such as the access
- policy. If the variable of the form _name=value_ is followed by the
- `default` keyword, the variable will be listed as part of the default
- system variables ({ntpqman} rv command). These additional
- variables serve informational purposes only. They are not related to
- the protocol other that they can be listed. The known protocol
- variables will always override any variables defined via
- the `setvar` mechanism. There are three special variables that contain the
- names of all variable of the same group. The `sys_var_list` holds the
- names of all system variables. The `peer_var_list` holds the names of all
- peer variables and the `clock_var_list` holds the names of the reference
- clock variables.
-
-`tinker` [`allan` _allan_ | `dispersion` _dispersion_ | `freq` _freq_ | `huffpuff` _huffpuff_ | `panic` _panic_ | `step` _step_ | `stepback` _stepback_ | `stepfwd` _stepfwd_ | `stepout` _stepout_]::
- This command can be used to alter several system variables in very
- exceptional circumstances. It should occur in the configuration file
- before any other configuration options. The default values of these
- variables have been carefully optimized for a wide range of network
- speeds and reliability expectations. In general, they interact in
- intricate ways that are hard to predict and some combinations can
- result in some very nasty behavior. Very rarely is it necessary to
- change the default values; but, some folks cannot resist twisting the
- knobs anyway and this command is for them. Emphasis added: twisters
- are on their own and can expect no help from the support group.
-+
-The variables operate as follows:
-+
-`allan` _allan_;;
- The argument becomes the new value for the minimum Allan intercept,
- which is a parameter of the PLL/FLL clock discipline algorithm. The
- value in log2 seconds defaults to 7 (1024 s), which is also the
- lower limit.
- `dispersion` _dispersion_;;
- The argument becomes the new value for the dispersion increase rate,
- normally .000015 s/s.
- `freq` _freq_;;
- The argument becomes the initial value of the frequency offset in
- parts-per-million. This overrides the value in the frequency file,
- if present, and avoids the initial training state if it is not.
- `huffpuff` _huffpuff_;;
- The argument becomes the new value for the experimental huff-n'-puff
- filter span, which determines the most recent interval the algorithm
- will search for a minimum delay. The lower limit is 900 s (15 m),
- but a more reasonable value is 7200 (2 hours). There is no default,
- since the filter is not enabled unless this command is given.
- `panic` _panic_;;
- The argument is the panic threshold, normally 1000 s. If set to
- zero, the panic sanity check is disabled and a clock offset of any
- value will be accepted.
- `step` _step_;;
- The argument is the step threshold, which by default is 0.128 s. It
- can be set to any positive number in seconds. If set to zero, step
- adjustments will never occur. Note: The kernel time discipline is
- disabled if the step threshold is set to zero or greater than the
- default.
- `stepback` _stepback_;;
- The argument is the step threshold for the backward direction, which
- by default is 0.128 s. It can be set to any positive number in
- seconds. If both the forward and backward step thresholds are set to
- zero, step adjustments will never occur. Note: The kernel time
- discipline is disabled if each direction of step threshold are
- either set to zero or greater than .5 second.
- `stepfwd` _stepfwd_;;
- As for stepback, but for the forward direction.
- `stepout` _stepout_;;
- The argument is the stepout timeout, which by default is 900 s. It
- can be set to any positive number in seconds. If set to zero, the
- stepout pulses will not be suppressed.
-
-`rlimit` [`memlock` _megabytes_ | `stacksize` _4kPages_ | `filenum` _filedescriptors_]::
-
- `memlock` _megabytes_;;
- Specify the number of megabytes of memory that can be allocated.
- Probably only available under Linux, this option is useful when
- dropping root (the `-i` option). The default is 32 megabytes.
- Setting this to zero will prevent any attemp to lock memory.
- `stacksize` _4kPages_;;
- Specifies the maximum size of the process stack on systems with the
- mlockall()_function. Defaults to 50 4k pages (200 4k pages in OpenBSD).
- `filenum` _filedescriptors_;;
- Specifies the maximum number of file descriptors {ntpd} may have open
- at once. Defaults to the system default.
-
-`trap` _host_address_ [`port` _port_number_] [`interface` _interface_address_]::
- This command configures a trap receiver at the given host address and
- port number for sending messages with the specified local interface
- address. If the port number is unspecified, a value of 18447 is used.
- If the interface address is not specified, the message is sent with a
- source address of the local interface the message is sent through.
- Note that on a multihomed host the interface used may vary from time
- to time with routing changes.
-+
-The trap receiver will generally log event messages and other
-information from the server in a log file. While such monitor programs
-may also request their own trap dynamically, configuring a trap
-receiver will ensure that no messages are lost when the server is
-started.
-
-`hop` `...`::
- This command specifies a list of TTL values in increasing order, up to
- 8 values can be specified. In manycast mode these values are used in
- turn in an expanding-ring search. The default is eight multiples of 32
- starting at 31.
+include::../docs/includes/misc-options.txt[]
== FILES ==
More information about the vc
mailing list