'\" te

.\" CDDL HEADER START

.\"

.\" The contents of this file are subject to the terms of the

.\" Common Development and Distribution License (the "License").

.\" You may not use this file except in compliance with the License.

.\"

.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

.\" or http://www.opensolaris.org/os/licensing.

.\" See the License for the specific language governing permissions

.\" and limitations under the License.

.\"

.\" When distributing Covered Code, include this CDDL HEADER in each

.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.

.\" If applicable, add the following below this CDDL HEADER, with the

.\" fields enclosed by brackets "[]" replaced with your own identifying

.\" information: Portions Copyright [yyyy] [name of copyright owner]

.\"

.\" CDDL HEADER END

.\"

.\" Use is subject to license terms.

.\"

.\"

.TH "ntp.conf" "4" "" "" "File Formats"

.SH NAME

ntp.conf \- Configuration file for the NTP Daemon.

.SH DESCRIPTION

.LP

The \fB\&ntp.conf\fR file contains the directives used by the \fBntpd\fR to

configure itself. 

.SS "Configuration Commands"

.sp 1.5

.ne 2

.mk

.na

\fBserver \fIaddress\fP \fR[options ...]\fP\fR

.br

\fBpeer \fIaddress\fP \fR[options ...]\fP\fR

.br

\fBbroadcast \fIaddress\fP \fR[options ...]\fP\fR

.br

\fBmanycastclient \fIaddress\fP \fR[options ...]\fP\fR

.br

\fR\fBpool \fIaddress\fP \fR[options ...]\fP\fR

.ad

.sp .25

.RS 4n

These commands specify the time server name or address to be used and the mode in which to operate. The \fIaddress\fP can be either a DNS name or a IPv4 or IPv6 address in standard notation. In general, multiple commands of each type can be used for different server and peer addresses or multicast groups.

.RE

.sp .3

.ne 2

.mk

.na

\fBserver\fR

.ad

.sp .25

.RS 4n

For type s and r addresses (only), this command mobilizes a persistent client mode association with the specified remote server or local reference clock. If the \fBpreempt\fR flag is specified, a preemptable client mode association is mobilized instead.

.RE

.sp .3

.ne 2

.mk

.na

\fBpeer\fR

.ad

.sp .25

.RS 4n

For type s addresses (only), this command mobilizes a persistent symmetric-active mode association with the specified remote peer.

.RE

.sp .3

.ne 2

.mk

.na

\fBbroadcast\fR

.ad

.sp .25

.RS 4n

For type b and m ddresses (only), this command mobilizes a persistent broadcast or multicast server mode association. Note that type b messages go only to the interface specified, but type m messages go to all interfaces.

.RE

.sp .3

.ne 2

.mk

.na

\fBmanycastclient\fR

.ad

.sp .25

.RS 4n

For type m addresses (only), this command mobilizes a manycast client mode association for the multicast group address specified. In this mode the address must match the address specified on the \fBmanycastserver\fR command of one or more designated manycast servers.

.RE

.sp .3

.ne 2

.mk

.na

\fBpool\fR

.ad

.sp .25

.RS 4n

For type s messages (only) this command mobilizes a client mode association for servers implementing the pool automatic server discovery scheme described on the Association Management page at file:///usr/share/doc/ntp/assoc.html. The address is a DNS name in the form \fB\fIarea\fP.pool.ntp.org\fR, where \fB\fIarea\fP\fR is a qualifier designating the server geographic area such as \fBus\fR or \fBeurope\fR.

.SS "Command Options"

Each of the above configuation commands takes zero or more options from the list below:

.sp .3

.ne 2

.mk

.na

\fBautokey\fR

.ad

.sp .25

.RS 4n

Send and receive packets authenticated by the autokey scheme described in the Authentication Options page at file:///usr/share/doc/ntp/authopt.html. This option is valid only with \fBserver\fR and \fBpeer\fR commands and type s addresses. It is incompatible with the \fBkey\fR option.

.RE

.sp .3

.ne 2

.mk

.na

\fBburst\fR

.ad

.sp .25

.RS 4n

When the server is reachable, send a burst of six packets instead of the usual one. The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the fBcalldelay\fR command to allow additional time for a modem or ISDN call to complete. This option is valid only with only the \fBserver\fR command and type s addressesa. It is a recommended option when the \fBmaxpoll\fR option is greater than 10 (1024 s).

.RE

.sp .3

.ne 2

.mk

.na

\fBiburst\fR

.ad

.sp .25

.RS 4n

When the server is unreachable, send a burst of eight packets instead of the usual one. The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the \fBcalldelay\fR command to allow additional time for a modem or ISDN call to complete. This option is valid only with the \fBserver\fR command and type s addresses. It is a recommended option with this command.

.RE

.sp .3

.ne 2

.mk

.na

\fBkey\fR \fIkey\fP\fR

.ad

.sp .25

.RS 4n

Send and receive packets authenticated by the symmetric key scheme described in the Authentication Options page at file:///usr/share/doc/ntp/authopt.html. This option is valid only with \fBserver\fR and \fBpeer\fR commands and type s addresses. The \fIkey\fP specifies the key identifier with values from 1 to 65534, inclusive. This option is incompatible with the \fBautokey\fR option.

.RE

.sp .3

.ne 2

.mk

.na

\fBminpoll \fIminpoll

.br

\fP\fR\fBmaxpoll \fImaxpoll\fP\fR

.ad

.sp .25

.RS 4n

These options specify the minimum and maximum poll intervals for NTP messages, in seconds as a power of two. The maximum poll interval defaults to 10 (1024 s), but can be increased by the \fBmaxpoll\fR option to an upper limit of 17 (36 h). The minimum poll interval defaults to 6 (64 s), but can be decreased by the \fBminpoll\fR option to a lower limit of 4 (16 s). These option are valid only with the \fBserver\fR and \fBpeer\fR commands and type s addresses.

.RE

.sp .3

.ne 2

.mk

.na

\fBmode \fIoption\fP\fR

.ad

.sp .25

.RS 4n

Pass the \fB\fIoption\fP\fR to a reference clock driver, where \fB\fIoption\fP\fR is an integer in the range from 0 to 255, inclusive. This option is valid only with the \fBserver\fR command and type r addresses.

.RE

.sp .3

.ne 2

.mk

.na

\fBnoselect\fR

.ad

.sp .25

.RS 4n

Marks the server or peer to be ignored by the selection algorithm but visible to the monitoring program. This option is ignored with the \fBbroadcast\fR command.

.RE

.sp .3

.ne 2

.mk

.na

\fBpreempt\fR

.ad

.sp .25

.RS 4n

Specifies the association as preemptable rather than the default persistent. This option is ignored with the  \fBbroadcast\fR command and is most useful with the \fBmanycastclient\fR and \fBpool\fR commands.

.RE

.sp .3

.ne 2

.mk

.na

\fBprefer\fR

.ad

.sp .25

.RS 4n

Mark the server as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts. See the Mitigation Rules page at file:///usr/share/doc/ntp/prefer.html for further information. This option is valid only with the \fBserver\fR and \fBpeer\fR commands.

.RE

.sp .3

.ne 2

.mk

.na

\fBtrue\fR

.ad

.sp .25

.RS 4n

Mark the association to assume truechimer status; that is, always survive the selection and clustering algorithms. This option can be used with any association, but is most useful for reference clocks with large jitter on the serial port and precision pulse-per-second (PPS) signals. Caution: this option defeats the algorithms designed to cast out falsetickers and can allow these sources to set the system clock. This option is valid only with the \fBserver\fR and \fBpeer\fR commands.

.RE

.sp .3

.ne 2

.mk

.na

\fBttl \fIttl\fP\fR

.ad

.sp .25

.RS 4n

This option specifies the time-to-live \fIttl\fP for the \fBbroadcast\fR commmand and the maximum \fIttl\fP for the expanding ring search used by the \fBmanycastclient\fR command. Selection of the proper value, which defaults to 127, is something of a black art and should be coordinated with the network administrator.

.RE

.sp .3

.ne 2

.mk

.na

\fBversion \fIversion\fP\fR

.ad

.sp .25

.RS 4n

Specifies the version number to be used for outgoing NTP packets. Versions 1-4 are the choices, with version 4 the default.

.RE

.SS "Auxilliary Commands"

.sp .3

.ne 2

.mk

.na

\fBbroadcastclient [novolley]\fR

.ad

.sp .25

.RS 4n

Enable reception of broadcast server messages to any local interface (type b address). Ordinarily, upon receiving a message for the first time, the broadcast client measures the nominal server propagation delay using a brief client/server exchange, after which it continues in listen-only mode. If the \fBnovolley\fR keyword is present, the exchange is not used and the value specified in the \fBbroadcastdelay\fR command is used or, if the \fBbroadcastdelay\fR command is not used, the default 4.0 ms. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the Authentication Options page at file:///usr/share/doc/ntp/authopt.html. Note that the \fBnovolley\fR keyword is incompatible with public key authentication.

.RE

.sp .3

.ne 2

.mk

.na

\fBmanycastserver \fIaddress\fP [...]\fR

.ad

.sp .25

.RS 4n

Enable reception of manycast client messages (type m)to the multicast group address(es) (type m) specified. At least one address is required. Note that, in order to avoid accidental or malicious disruption, both the server and client should operate using symmetric key or public key authentication as described in the Authentication Options page at file:///usr/share/doc/ntp/authopt.html.

.RE

.sp .3

.ne 2

.mk

.na

\fBmulticastclient \fIaddress\fP [...]\fR

.ad

.sp .25

.RS 4n

Enable reception of multicast server messages to the multicast group address(es) (type m) specified. Upon receiving a message for the first time, the multicast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding multicast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the Authentication Options page at file:///usr/share/doc/ntp/authopt.html.

.RE

.SS "Reference Clock Commands"

.sp .3

.ne 2

.mk

.na

\fBserver 127.127.\fIt.u\fP [prefer] [mode \fIint\fP] [minpoll \fIint\fP] [maxpoll \fIint\fP]\fR

.ad

.sp .25

.RS 4n

This command can be used to configure reference clocks in special ways. The options are interpreted as follows:

.RE

.sp .3

.ne 2

.mk

.na

\fBprefer\fR

.ad

.sp .25

.RS 4n

Marks the reference clock as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts. See the Mitigation Rules page at file:///usr/share/doc/ntp/prefer.html for further information.

.RE

.sp .3

.ne 2

.mk

.na

\fBmode \fIint\fP\fR

.ad

.sp .25

.RS 4n

Specifies a mode number which is interpreted in a device-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the \fBparse\fR drivers.

.RE

.sp .3

.ne 2

.mk

.na

\fBminpoll \fIint\fP\fR

.RE

.sp .3

.ne 2

.mk

.na

\fBmaxpoll \fIint\fP\fR

.ad

.sp .25

.RS 4n

These options specify the minimum and maximum polling interval for reference clock messages in seconds, interpreted as dual logarithms (2 ^ x). For most directly connected reference clocks, both \fBminpoll\fR and \fBmaxpoll\fR default to 6 (2^16 = 64 s). For modem reference clocks, \fBminpoll\fR defaults to 10 (2^10 = 1024 s = 17.1 m) and \fBmaxpoll\fR defaults to 14 (2^14 = 16384 s = 4.25 h). The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.

.RE

.sp .3

.ne 2

.mk

.na

\fBfudge 127.127.\fIt.u\fP [time1 \fIsec\fP] [time2 \fIsec\fP] [stratum \fIint\fP] [refid \fIstring\fP] [mode \fIint\fP] [flag1 0|1] [flag2 0|1] [flag3 0|1] [flag4 0|1]\fR

.ad

.sp .25

.RS 4n

This command can be used to configure reference clocks in special ways. It must immediately follow the \fBserver\fR command which configures the driver. Note that the same capability is possible at run time using the \fBntpdc\fR program. The options are interpreted as follows:

.RE

.sp .3

.ne 2

.mk

.na

\fBtime1 \fIsec\fP\fR

.ad

.sp .25

.RS 4n

Specifies a constant to be added to the time offset produced by the driver, a fixed-point decimal number in seconds. This is used as a calibration constant to adjust the nominal time offset of a particular clock to agree with an external standard, such as a precision PPS signal. It also provides a way to correct a systematic error or bias due to serial port or operating system latencies, different cable lengths or receiver internal delay. The specified offset is in addition to the propagation delay provided by other means, such as internal DIPswitches. Where a calibration for an individual system and driver is available, an approximate correction is noted in the driver documentation pages.

.LP

Note: in order to facilitate calibration when more than one radio clock or PPS signal is supported, a special calibration feature is available. It takes the form of an argument to the \fBenable\fR command and operates as described in the Reference Clock Drivers page at file:///usr/share/doc/ntp/refclock.html.

.RE

.sp .3

.ne 2

.mk

.na

\fBtime2 \fIsecs\fP\fR

.ad

.sp .25

.RS 4n

Specifies a fixed-point decimal number in seconds, which is interpreted in a driver-dependent way. See the descriptions of specific drivers in the Reference Clock Drivers page at file:///usr/share/doc/ntp/refclock.html.

.RE

.sp .3

.ne 2

.mk

.na

\fBstratum \fIint\fP\fR

.ad

.sp .25

.RS 4n

Specifies the stratum number assigned to the driver, an integer between 0 and 15. This number overrides the default stratum number ordinarily assigned by the driver itself, usually zero.

.RE

.sp .3

.ne 2

.mk

.na

\fBrefid \fIstring\fP\fR

.ad

.sp .25

.RS 4n

Specifies an ASCII string of from one to four characters which defines the reference identifier used by the driver. This string overrides the default identifier ordinarily assigned by the driver itself.

.RE

.sp .3

.ne 2

.mk

.na

\fBmode \fIint\fP\fR

.ad

.sp .25

.RS 4n

Specifies a mode number which is interpreted in a device-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the \fBparse\fR drivers.

.RE

.sp .3

.ne 2

.mk

.na

\fBflag1 flag2 flag3 flag4\fR

.ad

.sp .25

.RS 4n

These four flags are used for customizing the clock driver. The interpretation of these values, and whether they are used at all, is a function of the particular clock driver. However, by convention \fBflag4\fR is used to enable recording monitoring data to the \fBclockstats\fR file configured with the \fBfilegen\fR command. 

.RE

.SS "Authentication Commands"

.sp .3

.ne 2

.mk

.na

\fBautokey [\fIlogsec\fP]\fR

.ad

.sp .25

.RS 4n

Specifies the interval between regenerations of the session key list used with the Autokey protocol. Note that the size of the key list for each association depends on this interval and the current poll interval. The default value is 12 (4096 s or about 1.1 hours). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent.

.RE

.sp .3

.ne 2

.mk

.na

\fBcontrolkey \fIkey\fP\fR

.ad

.sp .25

.RS 4n

Specifies the key identifier to use with the \fBntpq\fR utility, which uses the standard protocol defined in RFC-1305. The \fB\fIkey\fP\fR argument is the key identifier for a trusted key, where the value can be in the range 1 to 65,534, inclusive.

.RE

.sp .3

.ne 2

.mk

.na

\fBcrypto [randfile \fIfile\fP] [host \fIname\fP] [ident \fIname\fP] [pw \fIpassword\fP]\fR

.ad

.sp .25

.RS 4n

This command requires the OpenSSL library. It activates public key cryptography and loads the required public/private encryption and sign kyes and public certificat. If one or more files are left unspecified, the default names are used as described below. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified in the \fBkeysdir\fR command or default \fB/etc/inet\fR. Following are the subcommands.

.RE

.sp .3

.ne 2

.mk

.na

\fBhost \fIname\fP\fR

.ad

.sp .25

.RS 4n

Specifies the host name used in the host key link \fBntpkey_host_\fIname\fP\fR, sign key link \fBntpkey_sign_\fIname\fP\fR and certificate link \fBntpkey_cert_\fIname\fP\fR. The \fBntp-keygen\fR program automatically installs these links to the most recently generated files.

.RE

.sp .3

.ne 2

.mk

.na

\fBident \fIname\fP\fR

.ad

.sp .25

.RS 4n

Specifies the group name used in the identity key link \fBntpkey_\fIkey\fP_\fIname\fP\fR, where \fB\fIkey\fP\fR identifies the key type described on the \fBntp-keygen\fR page. The \fBntp-keygen\fR program automatically installs these links to the most recently generated files.

.RE

.sp .3

.ne 2

.mk

.na

\fBpw \fIpassword\fP\fR

.ad

.sp .25

.RS 4n

Specifies the password to decrypt files previously encrypted by the \fBntp-keygen\fR program.

.RE

.sp .3

.ne 2

.mk

.na

\fBrandfile \fIfile\fP\fR

.ad

.sp .25

.RS 4n

Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the \fBntp-keygen(1m)\fR man page.

.RE

.sp .3

.ne 2

.mk

.na

\fBkeys \fIkeyfile\fP\fR

.ad

.sp .25

.RS 4n

Specifies the complete path to the MD5 key file containing the keys and key identifiers used by \fBntpd\fR, \fBntpq\fR and \fBntpdc\fR when operating with symmetric key cryptography. This is the same operation as the \fB-k \fRcommand line option.

.RE

.sp .3

.ne 2

.mk

.na

\fBkeysdir \fIpath\fP\fR

.ad

.sp .25

.RS 4n

This command specifies the default directory path for cryptographic keys, parameters and certificates. The default is \fB/etc/inet/\fR.

.RE

.sp .3

.ne 2

.mk

.na

\fBrequestkey \fIkey\fP\fR

.ad

.sp .25

.RS 4n

Specifies the key identifier to use with the \fBntpdc\fR utility program, which uses a proprietary protocol specific to this implementation of \fBntpd\fR. The \fB\fIkey\fP\fR argument is a key identifier for the trusted key, where the value can be in the range 1 to 65,534, inclusive.

.RE

.sp .3

.ne 2

.mk

.na

\fBrevoke [\fIlogsec\fP]\fR

.ad

.sp .25

.RS 4n

Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms; however, updating some values is a relatively expensive operation. The default interval is 16 (65,536 s or about 18 hours). For poll intervals above the specified interval, the values will be updated for every message sent.

.RE

.sp .3

.ne 2

.mk

.na

\fBtrustedkey \fIkey\fP [...]\fR

.ad

.sp .25

.RS 4n

Specifies the key identifiers which are trusted for the purposes of authenticating peers with symmetric key cryptography, as well as keys used by the \fBntpq\fR and \fBntpdc\fR programs. The authentication procedures require that both the local and remote servers share the same key and key identifier for this purpose, although different keys can be used with different servers. The \fB\fIkey\fP\fR arguments are 32-bit unsigned integers with values from 1 to 65,534.

.RE

.SS "Access Control Commands"

.sp .3

.ne 2

.mk

.na

\fBdiscard [ average \fIavg\fP ][ minimum \fImin\fP ] [ monitor \fIprob\fP ]\fR

.ad

.sp .25

.RS 4n

Set the parameters of the \fBlimited\fR facility which protects the server from client abuse. The \fBaverage\fR subcommand specifies the minimum average packet spacing, while the \fBminimum\fR subcommand specifies the minimum packet spacing. Packets that violate these minima are discarded and a kiss-o'-death packet returned if enabled. The default minimum average and minimum are 5 and 2, respectively. The monitor subcommand specifies the probability of discard for packets that overflow the rate-control window.

.RE

.sp .3

.ne 2

.mk

.na

\fBrestrict \fIaddress\fP [mask \fImask\fP] [\fIflag\fP][...]\fR

.ad

.sp .25

.RS 4n

The \fIaddress\fP argument expressed in dotted-quad form is the address of a host or network. Alternatively, the \fB\fIaddress\fP\fR argument can be a valid host DNS name. The \fImask\fP argument expressed in dotted-quad form defaults to \fB255.255.255.255\fR, meaning that the \fIaddress\fP is treated as the address of an individual host. A default entry (address \fB0.0.0.0\fR, mask \fB0.0.0.0\fR) is always included and is always the first entry in the list. Note that text string \fBdefault\fR, with no mask option, may be used to indicate the default entry.

.LP

In the current implementation, \fIflag\fP always restricts access, i.e., an entry with no flags indicates that free access to the server is to be given. The flags are not orthogonal, in that more restrictive flags will often make less restrictive ones redundant. The flags can generally be classed into two catagories, those which restrict time service and those which restrict informational queries and attempts to do run-time reconfiguration of the server. One or more of the following flags may be specified:

.RE

.sp .3

.ne 2

.mk

.na

\fBignore\fR

.ad

.sp .25

.RS 4n

Deny packets of all kinds, including \fBntpq\fR and \fBntpdc\fR queries.

.RE