1.\"
2.\" $FreeBSD: head/usr.sbin/ntp/doc/ntp.conf.5 108470 2002-12-30 21:18:15Z schweikh $
3.\"
4.Dd January 13, 2000
5.Dt NTP.CONF 5
6.Os
7.Sh NAME
8.Nm ntp.conf
9.Nd Network Time Protocol (NTP) daemon configuration file
10.Sh SYNOPSIS
11.Nm /etc/ntp.conf
12.Sh DESCRIPTION
13The
14.Nm
15configuration file is read at initial startup by the
16.Xr ntpd 8
17daemon in order to specify the synchronization sources,
18modes and other related information.
19Usually, it is installed in the
20.Pa /etc
21directory,
22but could be installed elsewhere
23(see the daemon's
24.Fl c
25command line option).
26.Pp
27The file format is similar to other
28.Ux
29configuration files.
30Comments begin with a
31.Ql #
32character and extend to the end of the line;
33blank lines are ignored.
34Configuration commands consist of an initial keyword
35followed by a list of arguments,
36some of which may be optional, separated by whitespace.
37Commands may not be continued over multiple lines.
38Arguments may be host names,
39host addresses written in numeric, dotted-quad form,
40integers, floating point numbers (when specifying times in seconds)
41and text strings.
42.Pp
43The rest of this page describes the configuration and control options.
44The
45.Qq "Notes on Configuring NTP and Setting up a NTP Subnet"
46page
47(available as part of the HTML documentation
48provided in
49.Pa /usr/share/doc/ntp )
50contains an extended discussion of these options.
51In addition to the discussion of general
52.Sx Configuration Options ,
53there are sections describing the following supported functionality
54and the options used to control it:
55.Bl -bullet -offset indent
56.It
57.Sx Authentication Support
58.It
59.Sx Monitoring Support
60.It
61.Sx Access Control Support
62.It
63.Sx Reference Clock Support
64.El
65.Pp
66Following these is a section describing
67.Sx Miscellaneous Options .
68While there is a rich set of options available,
69the only required option is one or more
70.Ic server ,
71.Ic peer ,
72.Ic broadcast
73or
74.Ic manycastclient
75commands.
76.Sh Configuration Support
77Following is a description of the configuration commands in
78NTPv4.
79These commands have the same basic functions as in NTPv3 and
80in some cases new functions and new arguments.
81There are two
82classes of commands, configuration commands that configure a
83persistent association with a remote server or peer or reference
84clock, and auxiliary commands that specify environmental variables
85that control various related operations.
86.Ss Configuration Commands
87The various modes are determined by the command keyword and the
88type of the required IP address.
89Addresses are classed by type as
90(s) a remote server or peer (IP class A, B and C), (b) the
91broadcast address of a local interface, (m) a multicast address (IP
92class D), or (r) a reference clock address (127.127.x.x).
93Note that
94only those options applicable to each command are listed below.
95Use
96of options not listed may not be caught as an error, but may result
97in some weird and even destructive behavior.
98.Bl -tag -width indent
99.It Xo Ic server Ar address
100.Op Cm key Ar key \&| Cm autokey
101.Op Cm burst
102.Op Cm iburst
103.Op Cm version Ar version
104.Op Cm prefer
105.Op Cm minpoll Ar minpoll
106.Op Cm maxpoll Ar maxpoll
107.Xc
108.It Xo Ic peer Ar address
109.Op Cm key Ar key \&| Cm autokey
110.Op Cm version Ar version
111.Op Cm prefer
112.Op Cm minpoll Ar minpoll
113.Op Cm maxpoll Ar maxpoll
114.Xc
115.It Xo Ic broadcast Ar address
116.Op Cm key Ar key \&| Cm autokey
117.Op Cm version Ar version
118.Op Cm prefer
119.Op Cm minpoll Ar minpoll
120.Op Cm ttl Ar ttl
121.Xc
122.It Xo Ic manycastclient Ar address
123.Op Cm key Ar key \&| Cm autokey
124.Op Cm version Ar version
125.Op Cm prefer
126.Op Cm minpoll Ar minpoll
127.Op Cm maxpoll Ar maxpoll
128.Op Cm ttl Ar ttl
129.Xc
130.El
131.Pp
132These four commands specify the time server name or address to
133be used and the mode in which to operate.
134The
135.Ar address
136can be
137either a DNS name or a IP address in dotted-quad notation.
138Additional information on association behavior can be found in the
139.Qq "Association Management"
140page.
141.Bl -tag -width indent
142.It Ic server
143For type s and r addresses, this command mobilizes a persistent
144client mode association with the specified remote server or local
145radio clock.
146In this mode the local clock can synchronized to the
147remote server, but the remote server can never be synchronized to
148the local clock.
149This command should
150.Em not
151be used for type
152b or m addresses.
153.It Ic peer
154For type s addresses (only), this command mobilizes a
155persistent symmetric-active mode association with the specified
156remote peer.
157In this mode the local clock can be synchronized to
158the remote peer or the remote peer can be synchronized to the local
159clock.
160This is useful in a network of servers where, depending on
161various failure scenarios, either the local or remote peer may be
162the better source of time.
163This command should NOT be used for type
164b, m or r addresses.
165.It Ic broadcast
166For type b and m addresses (only), this
167command mobilizes a persistent broadcast mode association.
168Multiple
169commands can be used to specify multiple local broadcast interfaces
170(subnets) and/or multiple multicast groups.
171Note that local
172broadcast messages go only to the interface associated with the
173subnet specified, but multicast messages go to all interfaces.
174In broadcast mode the local server sends periodic broadcast
175messages to a client population at the
176.Ar address
177specified, which is usually the broadcast address on (one of) the
178local network(s) or a multicast address assigned to NTP.
179The IANA
180has assigned the multicast group address 224.0.1.1 exclusively to
181NTP, but other nonconflicting addresses can be used to contain the
182messages within administrative boundaries.
183Ordinarily, this
184specification applies only to the local server operating as a
185sender; for operation as a broadcast client, see the
186.Ic broadcastclient
187or
188.Ic multicastclient
189commands
190below.
191.It Ic manycastclient
192For type m addresses (only), this command mobilizes a
193manycast client mode association for the multicast address
194specified.
195In this case a specific address must be supplied which
196matches the address used on the
197.Ic manycastserver
198command for
199the designated manycast servers.
200The NTP multicast address
201224.0.1.1 assigned by the IANA should NOT be used, unless specific
202means are taken to avoid spraying large areas of the Internet with
203these messages and causing a possibly massive implosion of replies
204at the sender.
205The
206.Ic manycastserver
207command specifies that the local server
208is to operate in client mode with the remote servers that are
209discovered as the result of broadcast/multicast messages.
210The
211client broadcasts a request message to the group address associated
212with the specified
213.Ar address
214and specifically enabled
215servers respond to these messages.
216The client selects the servers
217providing the best time and continues as with the
218.Ic server
219command.
220The remaining servers are discarded as if never
221heard.
222.El
223.Pp
224Options:
225.Bl -tag -width indent
226.It Cm autokey
227All packets sent to and received from the server or peer are to
228include authentication fields encrypted using the autokey scheme
229described in
230.Sx Authentication Options .
231.It Cm burst
232when the server is reachable and at each poll interval, send a
233burst of eight packets instead of the usual one packet.
234The spacing
235between the first and the second packets is about 16s to allow a
236modem call to complete, while the spacing between the remaining
237packets is about 2s.
238This is designed to improve timekeeping
239quality with the
240.Ic server
241command and s
242addresses.
243.It Cm iburst
244When the server is unreachable and at each poll interval, send
245a burst of eight packets instead of the usual one.
246As long as the
247server is unreachable, the spacing between packets is about 16s to
248allow a modem call to complete.
249Once the server is reachable, the
250spacing between packets is about 2s.
251This is designed to speed the
252initial synchronization acquisition with the
253.Ic server
254command and s addresses and when
255.Xr ntpd 8
256is started
257with the
258.Fl q
259option.
260.It Cm key Ar key
261All packets sent to and received from the server or peer are to
262include authentication fields encrypted using the specified
263.Ar key
264identifier with values from 1 to 65534, inclusive.
265The
266default is to include no encryption field.
267.It Cm minpoll Ar minpoll
268.It Cm maxpoll Ar maxpoll
269These options specify the minimum and maximum poll intervals
270for NTP messages, in seconds to the power of two.
271The maximum poll
272interval defaults to 10 (1,024 s), but can be increased by the
273.Cm maxpoll
274option to an upper limit of 17 (36.4 h).
275The
276minimum poll interval defaults to 6 (64 s), but can be decreased by
277the
278.Cm minpoll
279option to a lower limit of 4 (16 s).
280.It Cm prefer
281Marks the server as preferred.
282All other things being equal,
283this host will be chosen for synchronization among a set of
284correctly operating hosts.
285See the
286.Qq "Mitigation Rules and the prefer Keyword"
287page for further
288information.
289.It Cm ttl Ar ttl
290This option is used only with broadcast server and manycast
291client modes.
292It specifies the time-to-live
293.Cm ttl
294to
295use on broadcast server and multicast server and the maximum
296.Cm ttl
297for the expanding ring search with manycast
298client packets.
299Selection of the proper value, which defaults to
300127, is something of a black art and should be coordinated with the
301network administrator.
302.It Cm version Ar version
303Specifies the version number to be used for outgoing NTP
304packets.
305Versions 1-4 are the choices, with version 4 the
306default.
307.El
308.Ss Auxiliary Commands
309.Bl -tag -width indent
310.It Ic broadcastclient
311This command enables reception of broadcast server messages to
312any local interface (type b) address.
313Upon receiving a message for
314the first time, the broadcast client measures the nominal server
315propagation delay using a brief client/server exchange with the
316server, then enters the broadcast client mode, in which it
317synchronizes to succeeding broadcast messages.
318Note that, in order
319to avoid accidental or malicious disruption in this mode, both the
320server and client should operate using symmetric-key or public-key
321authentication as described in
322.Sx Authentication Options .
323.It Ic manycastserver Ar address ...
324This command enables reception of manycast client messages to
325the multicast group address(es) (type m) specified.
326At least one
327address is required, but the NTP multicast address 224.0.1.1
328assigned by the IANA should NOT be used, unless specific means are
329taken to limit the span of the reply and avoid a possibly massive
330implosion at the original sender.
331Note that, in order to avoid
332accidental or malicious disruption in this mode, both the server
333and client should operate using symmetric-key or public-key
334authentication as described in
335.Sx Authentication Options .
336.It Ic multicastclient Ar address ...
337This command enables reception of multicast server messages to
338the multicast group address(es) (type m) specified.
339Upon receiving
340a message for the first time, the multicast client measures the
341nominal server propagation delay using a brief client/server
342exchange with the server, then enters the broadcast client mode, in
343which it synchronizes to succeeding multicast messages.
344Note that,
345in order to avoid accidental or malicious disruption in this mode,
346both the server and client should operate using symmetric-key or
347public-key authentication as described in
348.Sx Authentication Options .
349.El
350.Sh Authentication Support
351Authentication support allows the NTP client to verify that the
352server is in fact known and trusted and not an intruder intending
353accidentally or on purpose to masquerade as that server.
354The NTPv3
355specification RFC-1305 defines a scheme which provides
356cryptographic authentication of received NTP packets.
357Originally,
358this was done using the Data Encryption Standard (DES) algorithm
359operating in Cipher Block Chaining (CBC) mode, commonly called
360DES-CBC.
361Subsequently, this was augmented by the RSA Message Digest
3625 (MD5) algorithm using a private key, commonly called keyed-MD5.
363Either algorithm computes a message digest, or one-way hash, which
364can be used to verify the server has the correct private key and
365key identifier.
366.Pp
367NTPv4 retains the NTPv3 schemes, properly described as
368symmetric-key cryptography and, in addition, provides a new Autokey
369scheme based on public-key cryptography.
370Public-key cryptography is
371generally considered more secure than symmetric-key cryptography,
372since the security is based on a private value which is generated
373by each server and never revealed.
374With Autokey all key
375distribution and management functions involve only public values,
376which considerably simplifies key distribution and storage.
377.Pp
378Authentication is configured separately for each association
379using the
380.Cm key
381or
382.Cm autokey
383subcommands on the
384.Ic peer ,
385.Ic server ,
386.Ic broadcast
387and
388.Ic manycastclient
389commands as described in
390.Sx Configuration Options .
391The authentication
392options described below specify the suite of keys, select the key
393for each configured association and manage the configuration
394operations.
395.Pp
396The
397.Cm auth
398flag controls whether new associations or
399remote configuration commands require cryptographic authentication.
400This flag can be set or reset by the
401.Ic enable
402and
403.Ic disable
404configuration commands and also by remote
405configuration commands sent by a
406.Xr ntpdc 8
407program running in
408another machine.
409If this flag is enabled, which is the default
410case, new broadcast client and symmetric passive associations and
411remote configuration commands must be cryptographically
412authenticated using either symmetric-key or public-key schemes.
413If
414this flag is disabled, these operations are effective even if not
415cryptographic authenticated.
416It should be understood that operating
417in the latter mode invites a significant vulnerability where a
418rogue hacker can seriously disrupt client timekeeping.
419.Pp
420In networks with firewalls and large numbers of broadcast
421clients it may be acceptable to disable authentication, since that
422avoids key distribution and simplifies network maintenance.
423However, when the configuration file contains host names, or when a
424server or client is configured remotely, host names are resolved
425using the DNS and a separate name resolution process.
426In order to
427protect against bogus name server messages, name resolution
428messages are authenticated using an internally generated key which
429is normally invisible to the user.
430However, if cryptographic
431support is disabled, the name resolution process will fail.
432This
433can be avoided either by specifying IP addresses instead of host
434names, which is generally inadvisable, or by enabling the flag for
435name resolution and disabled it once the name resolution process is
436complete.
437.Pp
438An attractive alternative where multicast support is available
439is manycast mode, in which clients periodically troll for servers.
440Cryptographic authentication in this mode uses public-key schemes
441as described below.
442The principle advantage of this manycast mode
443is that potential servers need not be configured in advance, since
444the client finds them during regular operation, and the
445configuration files for all clients can be identical.
446.Pp
447In addition to the default symmetric-key cryptographic support,
448support for public-key cryptography is available if the requisite
449.Sy rsaref20
450software distribution has been installed before
451building the distribution.
452Public-key cryptography provides secure
453authentication of servers without compromising accuracy and
454stability.
455The security model and protocol schemes for both
456symmetric-key and public-key cryptography are described below.
457.Ss Symmetric-Key Scheme
458The original RFC-1305 specification allows any one of possibly
45965,534 keys, each distinguished by a 32-bit key identifier, to
460authenticate an association.
461The servers and clients involved must
462agree on the key and key identifier to authenticate their messages.
463Keys and related information are specified in a key file, usually
464called
465.Pa ntp.keys ,
466which should be exchanged and stored
467using secure procedures beyond the scope of the NTP protocol
468itself.
469Besides the keys used for ordinary NTP associations,
470additional keys can be used as passwords for the
471.Xr ntpq 8
472and
473.Xr ntpdc 8
474utility programs.
475.Pp
476When
477.Xr ntpd 8
478is first started, it reads the key file
479specified in the
480.Ic keys
481command and installs the keys in the
482key cache.
483However, the keys must be activated with the
484.Ic trusted
485command before use.
486This allows, for instance, the
487installation of possibly several batches of keys and then
488activating or deactivating each batch remotely using
489.Xr ntpdc 8 .
490This also provides a revocation capability that can
491be used if a key becomes compromised.
492The
493.Ic requestkey
494command selects the key used as the password for the
495.Xr ntpdc 8
496utility, while the
497.Ic controlkey
498command selects the key used
499as the password for the
500.Xr ntpq 8
501utility.
502.Ss Public-Key Scheme
503The original NTPv3 authentication scheme described in RFC-1305
504continues to be supported; however, in NTPv4 an additional
505authentication scheme called Autokey is available.
506It uses MD5
507message digest, RSA public-key signature and Diffie-Hellman key
508agreement algorithms available from several sources, but not
509included in the NTPv4 software distribution.
510In order to be
511effective, the
512.Sy rsaref20
513package must be installed as
514described in the
515.Pa README.rsa
516file.
517Once installed, the
518configure and build process automatically detects it and compiles
519the routines required.
520The Autokey scheme has several modes of
521operation corresponding to the various NTP modes supported.
522RSA
523signatures with timestamps are used in all modes to verify the
524source of cryptographic values.
525All modes use a special cookie
526which can be computed independently by the client and server.
527In
528symmetric modes the cookie is constructed using the Diffie-Hellman
529key agreement algorithm.
530In other modes the cookie is constructed
531from the IP addresses and a private value known only to the server.
532All modes use in addition a variant of the S-KEY scheme, in which a
533pseudo-random key list is generated and used in reverse order.
534These schemes are described along with an executive summary,
535current status, briefing slides and reading list, in the
536.Qq "Autonomous Authentication"
537page.
538.Pp
539The cryptographic values used by the Autokey scheme are
540incorporated as a set of files generated by the
541.Xr ntp-genkeys 8
542program, including the
543symmetric private keys, public/private key pair, and the agreement
544parameters.
545See the
546.Xr ntp.keys 5
547page for a description of
548the formats of these files.
549They contain cryptographic values
550generated by the algorithms of the
551.Sy rsaref20
552package and
553are in printable ASCII format.
554All file names include the
555timestamp, in NTP seconds, following the default names given below.
556Since the file data are derived from random values seeded by the
557system clock and the file name includes the timestamp, every
558generation produces a different file and different file name.
559.Pp
560The
561.Pa ntp.keys
562file contains the DES/MD5 private keys.
563It
564must be distributed by secure means to other servers and clients
565sharing the same security compartment and made visible only to
566root.
567While this file is not used with the Autokey scheme, it is
568needed to authenticate some remote configuration commands used by
569the
570.Xr ntpdc 8 ,
571.Xr ntpq 8
572utilities.
573The
574.Pa ntpkey
575file
576contains the RSA private key.
577It is useful only to the machine that
578generated it and never shared with any other daemon or application
579program, so must be made visible only to root.
580.Pp
581The
582.Pa ntp_dh
583file contains the agreement parameters,
584which are used only in symmetric (active and passive) modes.
585It is
586necessary that both peers beginning a symmetric-mode association
587share the same parameters, but it does not matter which
588.Pa ntp_dh
589file generates them.
590If one of the peers contains
591the parameters, the other peer obtains them using the Autokey
592protocol.
593If both peers contain the parameters, the most recent
594copy is used by both peers.
595If a peer does not have the parameters,
596they will be requested by all associations, either configured or
597not; but, none of the associations can proceed until one of them
598has received the parameters.
599Once loaded, the parameters can be
600provided on request to other clients and servers.
601The
602.Pa ntp_dh
603file can be also be distributed using insecure
604means, since the data are public values.
605.Pp
606The
607.Pa ntpkey_ Ns Ar host
608file contains the RSA public
609key, where
610.Ar host
611is the name of the host.
612Each host
613must have its own
614.Pa ntpkey_ Ns Ar host
615file, which is
616normally provided to other hosts using the Autokey protocol.
617Each
618.Ic server
619or
620.Ic peer
621association requires the public
622key associated with the particular server or peer to be loaded
623either directly from a local file or indirectly from the server
624using the Autokey protocol.
625These files can be widely distributed
626and stored using insecure means, since the data are public
627values.
628.Pp
629The optional
630.Pa ntpkey_certif_ Ns Ar host
631file contains
632the PKI certificate for the host.
633This provides a binding between
634the host hame and RSA public key.
635In the current implementation the
636certificate is obtained by a client, if present, but the contents
637are ignored.
638.Pp
639Due to the widespread use of interface-specific naming, the host
640names used in configured and mobilized associations are determined
641by the
642.Ux
643.Xr gethostname 3
644library routine.
645Both the
646.Xr ntp-genkeys 8
647program and the Autokey protocol derive the
648name of the public key file using the name returned by this
649routine.
650While every server and client is required to load their
651own public and private keys, the public keys for each client or
652peer association can be obtained from the server or peer using the
653Autokey protocol.
654Note however, that at the current stage of
655development the authenticity of the server or peer and the
656cryptographic binding of the server name, address and public key is
657not yet established by a certificate authority or web of trust.
658.Ss Leapseconds Table
659The NIST provides a table showing the epoch for all historic
660occasions of leap second insertion since 1972.
661The leapsecond table
662shows each epoch of insertion along with the offset of
663International Atomic Time (TAI) with respect to Coordinated
664Universal Time (UTC), as disseminated by NTP.
665The table can be
666obtained directly from NIST national time servers using
667FTP as the ASCII file
668.Pa pub/leap-seconds .
669.Pp
670While not strictly a security function, the Autokey scheme
671provides means to securely retrieve the leapsecond table from a
672server or peer.
673Servers load the leapsecond table directly from the
674file specified in the
675.Ic crypto
676command, while clients can
677load the table indirectly from the servers using the Autokey
678protocol.
679Once loaded, the table can be provided on request to
680other clients and servers.
681.Ss Key Management
682All key files are installed by default in
683.Pa /usr/local/etc ,
684which is normally in a shared file system
685in NFS-mounted networks and avoids installing them in each machine
686separately.
687The default can be overridden by the
688.Ic keysdir
689configuration command.
690However, this is not a good place to install
691the private key file, since each machine needs its own file.
692A
693suitable place to install it is in
694.Pa /etc ,
695which is normally
696not in a shared file system.
697.Pp
698The recommended practice is to keep the timestamp extensions
699when installing a file and to install a link from the default name
700(without the timestamp extension) to the actual file.
701This allows
702new file generations to be activated simply by changing the link.
703However,
704.Xr ntpd 8
705parses the link name when present to extract
706the extension value and sends it along with the public key and host
707name when requested.
708This allows clients to verify that the file
709and generation time are always current.
710However, the actual
711location of each file can be overridden by the
712.Ic crypto
713configuration command.
714.Pp
715All cryptographic keys and related parameters should be
716regenerated on a periodic and automatic basis, like once per month.
717The
718.Xr ntp-genkeys 8
719program uses the same timestamp extension
720for all files generated at one time, so each generation is distinct
721and can be readily recognized in monitoring data.
722While a
723public/private key pair must be generated by every server and
724client, the public keys and agreement parameters do not need to be
725explicitly copied to all machines in the same security compartment,
726since they can be obtained automatically using the Autokey
727protocol.
728However, it is necessary that all primary servers have
729the same agreement parameter file.
730The recommended way to do this
731is for one of the primary servers to generate that file and then
732copy it to the other primary servers in the same compartment using
733the
734.Ux
735.Xr rdist 1
736command.
737Future versions of the Autokey
738protocol are to contain provisions for an agreement protocol to do
739this automatically.
740.Pp
741Servers and clients can make a new generation in the following
742way.
743All machines have loaded the old generation at startup and are
744operating normally.
745At designated intervals, each machine generates
746a new public/private key pair and makes links from the default file
747names to the new file names.
748The
749.Xr ntpd 8
750is then restarted
751and loads the new generation, with result clients no longer can
752authenticate correctly.
753The Autokey protocol is designed so that
754after a few minutes the clients time out and restart the protocol
755from the beginning, with result the new generation is loaded and
756operation continues as before.
757A similar procedure can be used for
758the agreement parameter file, but in this case precautions must be
759take to be sure that all machines with this file have the same
760copy.
761.Ss Authentication Commands
762.Bl -tag -width indent
763.It Ic autokey Op Ar logsec
764Specifies the interval between regenerations of the session key
765list used with the Autokey protocol.
766Note that the size of the key
767list for each association depends on this interval and the current
768poll interval.
769The default value is 12 (4096 s or about 1.1 hours).
770For poll intervals above the specified interval, a session key list
771with a single entry will be regenerated for every message
772sent.
773.It Ic controlkey Ar key
774Specifies the key identifier to use with the
775.Xr ntpq 8
776utility, which uses the standard
777protocol defined in RFC-1305.
778The
779.Ar key
780argument is
781the key identifier for a trusted key, where the value can be in the
782range 1 to 65534, inclusive.
783.It Xo Ic crypto
784.Op Cm flags Ar flags
785.Op Cm privatekey Ar file
786.Op Cm publickey Ar file
787.Op Cm dhparms Ar file
788.Op Cm leap Ar file
789.Xc
790This command requires the NTP daemon build process be
791configured with the RSA library.
792This command activates public-key
793cryptography and loads the required RSA private and public key
794files and the optional Diffie-Hellman agreement parameter file, if
795present.
796If one or more files are left unspecified, the default
797names are used as described below.
798Following are the
799subcommands:
800.Bl -tag -width indent
801.It Cm privatekey Ar file
802Specifies the location of the RSA private key file, which
803otherwise defaults to
804.Pa /usr/local/etc/ntpkey .
805.It Cm publickey Ar file
806Specifies the location of the RSA public key file, which
807otherwise defaults to
808.Pa /usr/local/etc/ntpkey_ Ns Ar host ,
809where
810.Ar host
811is the name of the generating machine.
812.It Cm dhparms Ar file
813Specifies the location of the Diffie-Hellman parameters file,
814which otherwise defaults to
815.Pa /usr/local/etc/ntpkey_dh .
816.It Cm leap Ar file
817Specifies the location of the leapsecond table file, which
818otherwise defaults to
819.Pa /usr/local/etc/ntpkey_leap .
820.El
821.It Ic keys Ar keyfile
822Specifies the location of the DES/MD5 private key file
823containing the keys and key identifiers used by
824.Xr ntpd 8 ,
825.Xr ntpq 8
826and
827.Xr ntpdc 8
828when operating in symmetric-key
829mode.
830.It Ic keysdir Ar path
831This command requires the NTP daemon build process be
832configured with the RSA library.
833It specifies the default directory
834path for the private key file, agreement parameters file and one or
835more public key files.
836The default when this command does not
837appear in the configuration file is
838.Pa /usr/local/etc .
839.It Ic requestkey Ar key
840Specifies the key identifier to use with the
841.Xr ntpdc 8
842utility program, which uses a
843proprietary protocol specific to this implementation of
844.Xr ntpd 8 .
845The
846.Ar key
847argument is a key identifier
848for the trusted key, where the value can be in the range 1 to
84965534, inclusive.
850.It Ic revoke Ar logsec
851Specifies the interval between re-randomization of certain
852cryptographic values used by the Autokey scheme, as a power of 2 in
853seconds.
854These values need to be updated frequently in order to
855deflect brute-force attacks on the algorithms of the scheme;
856however, updating some values is a relatively expensive operation.
857The default interval is 16 (65,536 s or about 18 hours).
858For poll
859intervals above the specified interval, the values will be updated
860for every message sent.
861.It Ic trustedkey Ar key ...
862Specifies the key identifiers which are trusted for the
863purposes of authenticating peers with symmetric-key cryptography,
864as well as keys used by the
865.Xr ntpq 8
866and
867.Xr ntpdc 8
868programs.
869The authentication procedures require that both the local
870and remote servers share the same key and key identifier for this
871purpose, although different keys can be used with different
872servers.
873The
874.Ar key
875arguments are 32-bit unsigned
876integers with values from 1 to 65,534.
877.El
878.Sh Monitoring Support
879.Xr ntpd 8
880includes a comprehensive monitoring facility suitable
881for continuous, long term recording of server and client
882timekeeping performance.
883See the
884.Ic statistics
885command below
886for a listing and example of each type of statistics currently
887supported.
888Statistic files are managed using file generation sets
889and scripts in the
890.Pa ./scripts
891directory of this distribution.
892Using
893these facilities and
894.Ux
895.Xr cron 8
896jobs, the data can be
897automatically summarized and archived for retrospective analysis.
898.Ss Monitoring Commands
899.Bl -tag -width indent
900.It Ic statistics Ar name ...
901Enables writing of statistics records.
902Currently, four kinds of
903.Ar name
904statistics are supported.
905.Bl -tag -width indent
906.It Cm loopstats
907Enables recording of loop filter statistics information.
908Each
909update of the local clock outputs a line of the following form to
910the file generation set named loopstats:
911.Bd -literal
91250935 75440.031 0.000006019 13.778190 0.000351733 0.013380 6
913.Ed
914.Pp
915The first two fields show the date (Modified Julian Day) and
916time (seconds and fraction past UTC midnight).
917The next five fields
918show time offset (seconds), frequency offset (parts per million -
919PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
920discipline time constant.
921.It Cm peerstats
922Enables recording of peer statistics information.
923This includes
924statistics records of all peers of a NTP server and of special
925signals, where present and configured.
926Each valid update appends a
927line of the following form to the current element of a file
928generation set named peerstats:
929.Bd -literal
93048773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142
931.Ed
932.Pp
933The first two fields show the date (Modified Julian Day) and
934time (seconds and fraction past UTC midnight).
935The next two fields
936show the peer address in dotted-quad notation and status,
937respectively.
938The status field is encoded in hex in the format
939described in Appendix A of the NTP specification RFC 1305.
940The
941final three fields show the offset, delay and RMS jitter, all in
942seconds.
943.It Cm clockstats
944Enables recording of clock driver statistics information.
945Each
946update received from a clock driver appends a line of the following
947form to the file generation set named clockstats:
948.Bd -literal
94949213 525.624 127.127.4.1 93 226 00:08:29.606 D
950.Ed
951.Pp
952The first two fields show the date (Modified Julian Day) and
953time (seconds and fraction past UTC midnight).
954The next field shows
955the clock address in dotted-quad notation.
956The final field shows
957the last timecode received from the clock in decoded ASCII format,
958where meaningful.
959In some clock drivers a good deal of additional
960information can be gathered and displayed as well.
961See information
962specific to each clock for further details.
963.It Cm rawstats
964Enables recording of raw-timestamp statistics information.
965This
966includes statistics records of all peers of a NTP server and of
967special signals, where present and configured.
968Each NTP message
969received from a peer or clock driver appends a line of the
970following form to the file generation set named rawstats:
971.Bd -literal
97250928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
973.Ed
974The first two fields show the date (Modified Julian Day) and
975time (seconds and fraction past UTC midnight).
976The next two fields
977show the remote peer or clock address followed by the local address
978in dotted-quad notation.
979The final four fields show the originate,
980receive, transmit and final NTP timestamps in order.
981The timestamp
982values are as received and before processing by the various data
983smoothing and mitigation algorithms.
984.El
985.It Ic statsdir Ar directory_path
986Indicates the full path of a directory where statistics files
987should be created (see below).
988This keyword allows the (otherwise
989constant)
990.Ic filegen
991filename prefix to be modified for file
992generation sets, which is useful for handling statistics logs.
993.It Xo Ic filegen Ar name
994.Op Cm file Ar filename
995.Op Cm type Ar typename
996.Op Cm link \&| Cm nolink
997.Op Cm enable \&| Cm disable
998.Xc
999Configures setting of generation file set
1000.Ar name .
1001Generation file sets provide a means for handling files that are
1002continuously growing during the lifetime of a server.
1003Server
1004statistics are a typical example for such files.
1005Generation file
1006sets provide access to a set of files used to store the actual
1007data.
1008At any time at most one element of the set is being written
1009to.
1010The type given specifies when and how data will be directed to
1011a new element of the set.
1012This way, information stored in elements
1013of a file set that are currently unused are available for
1014administrational operations without the risk of disturbing the
1015operation of
1016.Xr ntpd 8 .
1017(Most important: they can be removed to
1018free space for new data produced.)
1019Note that this command can be sent from the
1020.Xr ntpdc 8
1021program running at a remote location.
1022.Bl -tag -width indent
1023.It Ar name
1024This is the type of the statistics records, as shown in the
1025.Ic statistics
1026command.
1027.It Cm file Ar filename
1028This is the file name for the statistics records.
1029Filenames of
1030set members are built from three concatenated elements
1031prefix, filename and
1032suffix:
1033.Bl -tag -width indent
1034.It prefix
1035This is a constant filename path.
1036It is not subject to
1037modifications via the
1038.Ic filegen
1039option.
1040It is defined by the
1041server, usually specified as a compile-time constant.
1042It may,
1043however, be configurable for individual file generation sets via
1044other commands.
1045For example, the prefix used with
1046.Cm loopstats
1047and
1048.Cm peerstats
1049generation can be
1050configured using the
1051.Ic statsdir
1052option explained above.
1053.It filename
1054This string is directly concatenated to the prefix mentioned
1055above (no intervening
1056.Ql /
1057(slash)).
1058This can be modified
1059using the
1060.Ar file
1061argument to the
1062.Ic filegen
1063statement.
1064No
1065.Ql \&..
1066elements are allowed in this component to prevent
1067filenames referring to parts outside the file system hierarchy
1068denoted by prefix.
1069.It suffix
1070This part is reflects individual elements of a file set.
1071It is
1072generated according to the type of a file set.
1073.El
1074.It Cm type Ar typename
1075A file generation set is characterized by its type.
1076The
1077following types are supported:
1078.Bl -tag -width indent
1079.It none
1080The file set is actually a single plain file.
1081.It pid
1082One element of file set is used per incarnation of a
1083.Xr ntpd 8
1084server.
1085This type does not perform any changes to
1086file set members during runtime, however it provides an easy way of
1087separating files belonging to different
1088.Xr ntpd 8
1089server
1090incarnations.
1091The set member filename is built by appending a
1092.Ql \&.
1093(dot) to concatenated prefix and filename
1094strings, and appending the decimal representation of the process ID
1095of the
1096.Xr ntpd 8
1097server process.
1098.It day
1099One file generation set element is created per day.
1100A day is
1101defined as the period between 00:00 and 24:00 UTC.
1102The file set
1103member suffix consists of a
1104.Ql \&.
1105(dot) and a day
1106specification in the form
1107.Ar YYYYMMdd .
1108.Ar YYYY
1109is a 4-digit year
1110number (e.g., 1992).
1111.Ar MM
1112is a two digit month number.
1113.Ar dd
1114is a two digit day number.
1115Thus, all information
1116written at 10 December 1992 would end up in a file named
1117.Sm off
1118.Pa Ar prefix / Ar filename / 19921210 .
1119.Sm on
1120.It week
1121Any file set member contains data related to a certain week of
1122a year.
1123The term week is defined by computing day-of-year modulo 7.
1124Elements of such a file generation set are distinguished by
1125appending the following suffix to the file set filename base: A
1126dot, a 4-digit year number, the letter
1127Ql W ,
1128and a 2-digit
1129week number.
1130For example, information from January, 10th 1992 would
1131end up in a file with suffix
1132.Pa .1992W1 .
1133.It month
1134One generation file set element is generated per month.
1135The
1136file name suffix consists of a dot, a 4-digit year number, and a
11372-digit month.
1138.It year
1139One generation file element is generated per year.
1140The filename
1141suffix consists of a dot and a 4 digit year number.
1142.It age
1143This type of file generation sets changes to a new element of
1144the file set every 24 hours of server operation.
1145The filename
1146suffix consists of a dot, the letter
1147.Ql a ,
1148and an 8-digit
1149number.
1150This number is taken to be the number of seconds the server
1151is running at the start of the corresponding 24-hour period.
1152Information is only written to a file generation by specifying
1153.Ic enable ;
1154output is prevented by specifying
1155.Ic disable .
1156.El
1157.It Cm link \&| Cm nolink
1158It is convenient to be able to access the current element of a
1159file generation set by a fixed name.
1160This feature is enabled by
1161specifying
1162.Cm link
1163and disabled using
1164.Cm nolink .
1165If
1166.Cm link
1167is specified, a hard link from the current file set
1168element to a file without suffix is created.
1169When there is already
1170a file with this name and the number of links of this file is one,
1171it is renamed appending a dot, the letter
1172.Ql C ,
1173and the pid
1174of the
1175.Xr ntpd 8
1176server process.
1177When the number of links is
1178greater than one, the file is unlinked.
1179This allows the current
1180file to be accessed by a constant name.
1181.It Cm enable \&| Cm disable
1182Enables or disables the recording function.
1183.El
1184.El
1185.Sh Access Control Support
1186.Xr ntpd 8
1187implements a general purpose address-and-mask based
1188restriction list.
1189The list is sorted by address and by mask, and
1190the list is searched in this order for matches, with the last match
1191found defining the restriction flags associated with the incoming
1192packets.
1193The source address of incoming packets is used for the
1194match, with the 32- bit address being and'ed with the mask
1195associated with the restriction entry and then compared with the
1196entry's address (which has also been and'ed with the mask) to look
1197for a match.
1198Additional information and examples can be found in the
1199.Qq "Notes on Configuring NTP and Setting up a NTP Subnet"
1200page.
1201.Pp
1202The restriction facility was implemented in conformance with the
1203access policies for the original NSFnet backbone time servers.
1204While this facility may be otherwise useful for keeping unwanted or
1205broken remote time servers from affecting your own, it should not
1206be considered an alternative to the standard NTP authentication
1207facility.
1208Source address based restrictions are easily circumvented
1209by a determined cracker.
1210.Ss The Kiss-of-Death Packet
1211Ordinarily, packets denied service are simply dropped with no
1212further action except incrementing statistics counters.
1213Sometimes a
1214more proactive response is needed, such as a server message that
1215explicitly requests the client to stop sending and leave a message
1216for the system operator.
1217A special packet format has been created
1218for this purpose called the kiss-of-death packet.
1219If the
1220.Cm kod
1221flag is set and either service is denied or the client
1222limit is exceeded, the server returns the packet and sets the
1223leap bits unsynchronized, stratum zero and the ASCII string "DENY"
1224in the reference source identifier field.
1225If the
1226.Cm kod
1227flag
1228is not set, the server simply drops the packet.
1229.Pp
1230A client or peer receiving a kiss-of-death packet performs a set
1231of sanity checks to minimize security exposure.
1232If this is the
1233first packet received from the server, the client assumes an access
1234denied condition at the server.
1235It updates the stratum and
1236reference identifier peer variables and sets the access denied
1237(test 4) bit in the peer flash variable.
1238If this bit is set, the
1239client sends no packets to the server.
1240If this is not the first
1241packet, the client assumes a client limit condition at the server,
1242but does not update the peer variables.
1243In either case, a message
1244is sent to the system log.
1245.Ss Access Control Commands
1246.Bl -tag -width indent
1247.It Xo Ic restrict numeric_address
1248.Op Cm mask Ar numeric_mask
1249.Op Ar flag ...
1250.Xc
1251The
1252.Ar numeric_address
1253argument, expressed in
1254dotted-quad form, is the address of a host or network.
1255The
1256.Cm mask ,
1257also expressed in dotted-quad form,
1258defaults to 255.255.255.255, meaning that the
1259.Ar numeric_address
1260is treated as the address of an
1261individual host.
1262A default entry (address 0.0.0.0, mask
12630.0.0.0) is always included and, given the sort algorithm,
1264is always the first entry in the list.
1265Note that, while
1266.Ar numeric_address
1267is normally given in dotted-quad
1268format, the text string
1269.Ql default ,
1270with no mask option, may
1271be used to indicate the default entry.
1272In the current implementation,
1273.Cm flag
1274always
1275restricts access, i.e., an entry with no flags indicates that free
1276access to the server is to be given.
1277The flags are not orthogonal,
1278in that more restrictive flags will often make less restrictive
1279ones redundant.
1280The flags can generally be classed into two
1281categories, those which restrict time service and those which
1282restrict informational queries and attempts to do run-time
1283reconfiguration of the server.
1284One or more of the following flags
1285may be specified:
1286.Bl -tag -width indent
1287.It Cm kod
1288If access is denied, send a kiss-of-death packet.
1289.It Cm ignore
1290Ignore all packets from hosts which match this entry.
1291If this
1292flag is specified neither queries nor time server polls will be
1293responded to.
1294.It Cm noquery
1295Ignore all NTP mode 6 and 7 packets (i.e. information queries
1296and configuration requests) from the source.
1297Time service is not
1298affected.
1299.It Cm nomodify
1300Ignore all NTP mode 6 and 7 packets which attempt to modify the
1301state of the server (i.e. run time reconfiguration).
1302Queries which
1303return information are permitted.
1304.It Cm notrap
1305Decline to provide mode 6 control message trap service to
1306matching hosts.
1307The trap service is a subsystem of the mode 6
1308control message protocol which is intended for use by remote event
1309logging programs.
1310.It Cm lowpriotrap
1311Declare traps set by matching hosts to be low priority.
1312The
1313number of traps a server can maintain is limited (the current limit
1314is 3).
1315Traps are usually assigned on a first come, first served
1316basis, with later trap requestors being denied service.
1317This flag
1318modifies the assignment algorithm by allowing low priority traps to
1319be overridden by later requests for normal priority traps.
1320.It Cm noserve
1321Ignore NTP packets whose mode is other than 6 or 7.
1322In effect,
1323time service is denied, though queries may still be permitted.
1324.It Cm nopeer
1325Provide stateless time service to polling hosts, but do not
1326allocate peer memory resources to these hosts even if they
1327otherwise might be considered useful as future synchronization
1328partners.
1329.It Cm notrust
1330Treat these hosts normally in other respects, but never use
1331them as synchronization sources.
1332.It Cm limited
1333These hosts are subject to limitation of number of clients from
1334the same net.
1335Net in this context refers to the IP notion of net
1336(class A, class B, class C, etc.).
1337Only the first
1338.Va client_limit
1339hosts that have shown up at the server and
1340that have been active during the last
1341.Va client_limit_period
1342seconds are accepted.
1343Requests from other clients from the same net
1344are rejected.
1345Only time request packets are taken into account.
1346Query packets sent by the
1347.Xr ntpq 8
1348and
1349.Xr ntpdc 8
1350programs
1351are not subject to these limits.
1352A history of clients is kept using
1353the monitoring capability of
1354.Xr ntpd 8 .
1355Thus, monitoring is
1356always active as long as there is a restriction entry with the
1357.Cm limited
1358flag.
1359.It Cm ntpport
1360This is actually a match algorithm modifier, rather than a
1361restriction flag.
1362Its presence causes the restriction entry to be
1363matched only if the source port in the packet is the standard NTP
1364UDP port (123).
1365Both
1366.Cm ntpport
1367and
1368.Cm non-ntpport
1369may
1370be specified.
1371The
1372.Cm ntpport
1373is considered more specific and
1374is sorted later in the list.
1375.It Cm version
1376Ignore these hosts if not the current NTP version.
1377.El
1378.Pp
1379Default restriction list entries, with the flags
1380.Cm ignore ,
1381.Cm interface ,
1382.Cm ntpport ,
1383for each of the local host's interface
1384addresses are inserted into the table at startup to prevent the
1385server from attempting to synchronize to its own time.
1386A default
1387entry is also always present, though if it is otherwise
1388unconfigured; no flags are associated with the default entry (i.e.,
1389everything besides your own NTP server is unrestricted).
1390.It Ic clientlimit Ar limit
1391Set the
1392.Va client_limit
1393variable, which limits the number
1394of simultaneous access-controlled clients.
1395The default value for
1396this variable is 3.
1397.It Ic clientperiod Ar period
1398Set the
1399.Va client_limit_period
1400variable, which specifies
1401the number of seconds after which a client is considered inactive
1402and thus no longer is counted for client limit restriction.
1403The
1404default value for this variable is 3600 seconds.
1405.El
1406.Sh Reference Clock Support
1407The NTP Version 4 daemon supports some three dozen different radio,
1408satellite and modem reference clocks plus a special pseudo-clock
1409used for backup or when no other clock source is available.
1410Detailed descriptions of individual device drivers and options can
1411be found in the
1412.Qq "Reference Clock Drivers"
1413page
1414(available as part of the HTML documentation
1415provided in
1416.Pa /usr/share/doc/ntp ) .
1417Additional information can be found in the pages linked
1418there, including the
1419.Qq "Debugging Hints for Reference Clock Drivers"
1420and
1421.Qq "How To Write a Reference Clock Driver"
1422pages.
1423In addition, support for a PPS
1424signal is available as described in the
1425.Qq "Pulse-per-second (PPS) Signal Interfacing"
1426page.
1427Many
1428drivers support special line discipline/streams modules which can
1429significantly improve the accuracy using the driver.
1430These are
1431described in the
1432.Qq "Line Disciplines and Streams Drivers"
1433page.
1434.Pp
1435A reference clock will generally (though not always) be a radio
1436timecode receiver which is synchronized to a source of standard
1437time such as the services offered by the NRC in Canada and NIST and
1438USNO in the US.
1439The interface between the computer and the timecode
1440receiver is device dependent, but is usually a serial port.
1441A
1442device driver specific to each reference clock must be selected and
1443compiled in the distribution; however, most common radio, satellite
1444and modem clocks are included by default.
1445Note that an attempt to
1446configure a reference clock when the driver has not been compiled
1447or the hardware port has not been appropriately configured results
1448in a scalding remark to the system log file, but is otherwise non
1449hazardous.
1450.Pp
1451For the purposes of configuration,
1452.Xr ntpd 8
1453treats
1454reference clocks in a manner analogous to normal NTP peers as much
1455as possible.
1456Reference clocks are identified by a syntactically
1457correct but invalid IP address, in order to distinguish them from
1458normal NTP peers.
1459Reference clock addresses are of the form
1460.Sm off
1461.Li 127.127. Ar t . Ar u ,
1462.Sm on
1463where
1464.Ar t
1465is an integer
1466denoting the clock type and
1467.Ar u
1468indicates the unit
1469number in the range 0-3.
1470While it may seem overkill, it is in fact
1471sometimes useful to configure multiple reference clocks of the same
1472type, in which case the unit numbers must be unique.
1473.Pp
1474The
1475.Ic server
1476command is used to configure a reference
1477clock, where the
1478.Ar address
1479argument in that command
1480is the clock address.
1481The
1482.Cm key ,
1483.Cm version
1484and
1485.Cm ttl
1486options are not used for reference clock support.
1487The
1488.Cm mode
1489option is added for reference clock support, as
1490described below.
1491The
1492.Cm prefer
1493option can be useful to
1494persuade the server to cherish a reference clock with somewhat more
1495enthusiasm than other reference clocks or peers.
1496Further
1497information on this option can be found in the
1498.Qq "Mitigation Rules and the prefer Keyword"
1499page.
1500The
1501.Cm minpoll
1502and
1503.Cm maxpoll
1504options have
1505meaning only for selected clock drivers.
1506See the individual clock
1507driver document pages for additional information.
1508.Pp
1509The
1510.Ic fudge
1511command is used to provide additional
1512information for individual clock drivers and normally follows
1513immediately after the
1514.Ic server
1515command.
1516The
1517.Ar address
1518argument specifies the clock address.
1519The
1520.Cm refid
1521and
1522.Cm stratum
1523options can be used to
1524override the defaults for the device.
1525There are two optional
1526device-dependent time offsets and four flags that can be included
1527in the
1528.Ic fudge
1529command as well.
1530.Pp
1531The stratum number of a reference clock is by default zero.
1532Since the
1533.Xr ntpd 8
1534daemon adds one to the stratum of each
1535peer, a primary server ordinarily displays an external stratum of
1536one.
1537In order to provide engineered backups, it is often useful to
1538specify the reference clock stratum as greater than zero.
1539The
1540.Cm stratum
1541option is used for this purpose.
1542Also, in cases
1543involving both a reference clock and a pulse-per-second (PPS)
1544discipline signal, it is useful to specify the reference clock
1545identifier as other than the default, depending on the driver.
1546The
1547.Cm refid
1548option is used for this purpose.
1549Except where noted,
1550these options apply to all clock drivers.
1551.Ss Reference Clock Commands
1552.Bl -tag -width indent
1553.It Xo Ic server
1554.Sm off
1555.Li 127.127. Ar t . Ar u
1556.Sm on
1557.Op Cm prefer
1558.Op Cm mode Ar int
1559.Op Cm minpoll Ar int
1560.Op Cm maxpoll Ar int
1561.Xc
1562This command can be used to configure reference clocks in
1563special ways.
1564The options are interpreted as follows:
1565.Bl -tag -width indent
1566.It Cm prefer
1567Marks the reference clock as preferred.
1568All other things being
1569equal, this host will be chosen for synchronization among a set of
1570correctly operating hosts.
1571See the
1572.Qq "Mitigation Rules and the prefer Keyword"
1573page for further
1574information.
1575.It Cm mode Ar int
1576Specifies a mode number which is interpreted in a
1577device-specific fashion.
1578For instance, it selects a dialing
1579protocol in the ACTS driver and a device subtype in the
1580parse
1581drivers.
1582.It Cm minpoll Ar int
1583.It Cm maxpoll Ar int
1584These options specify the minimum and maximum polling interval
1585for reference clock messages, in seconds to the power of two.
1586For
1587most directly connected reference clocks, both
1588.Cm minpoll
1589and
1590.Cm maxpoll
1591default to 6 (64 s).
1592For modem reference clocks,
1593.Cm minpoll
1594defaults to 10 (17.1 m) and
1595.Cm maxpoll
1596defaults to 14 (4.5 h).
1597The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
1598.El
1599.It Xo Ic fudge
1600.Sm off
1601.Li 127.127. Ar t . Ar u
1602.Sm on
1603.Op Cm time1 Ar sec
1604.Op Cm time2 Ar sec
1605.Op Cm stratum Ar int
1606.Op Cm refid Ar string
1607.Op Cm mode Ar int
1608.Op Cm flag1 Cm 0 \&| Cm 1
1609.Op Cm flag2 Cm 0 \&| Cm 1
1610.Op Cm flag3 Cm 0 \&| Cm 1
1611.Op Cm flag4 Cm 0 \&| Cm 1
1612.Xc
1613This command can be used to configure reference clocks in
1614special ways.
1615It must immediately follow the
1616.Ic server
1617command which configures the driver.
1618Note that the same capability
1619is possible at run time using the
1620.Xr ntpdc 8
1621program.
1622The options are interpreted as
1623follows:
1624.Bl -tag -width indent
1625.It Cm time1 Ar sec
1626Specifies a constant to be added to the time offset produced by
1627the driver, a fixed-point decimal number in seconds.
1628This is used
1629as a calibration constant to adjust the nominal time offset of a
1630particular clock to agree with an external standard, such as a
1631precision PPS signal.
1632It also provides a way to correct a
1633systematic error or bias due to serial port or operating system
1634latencies, different cable lengths or receiver internal delay.
1635The
1636specified offset is in addition to the propagation delay provided
1637by other means, such as internal DIPswitches.
1638Where a calibration
1639for an individual system and driver is available, an approximate
1640correction is noted in the driver documentation pages.
1641Note: in order to facilitate calibration when more than one
1642radio clock or PPS signal is supported, a special calibration
1643feature is available.
1644It takes the form of an argument to the
1645.Ic enable
1646command described in
1647.Sx Miscellaneous Options
1648page and operates as described in the
1649.Qq "Reference Clock Drivers"
1650page.
1651.It Cm time2 Ar secs
1652Specifies a fixed-point decimal number in seconds, which is
1653interpreted in a driver-dependent way.
1654See the descriptions of
1655specific drivers in the
1656.Qq "reference clock drivers"
1657page.
1658.It Cm stratum Ar int
1659Specifies the stratum number assigned to the driver, an integer
1660between 0 and 15.
1661This number overrides the default stratum number
1662ordinarily assigned by the driver itself, usually zero.
1663.It Cm refid Ar string
1664Specifies an ASCII string of from one to four characters which
1665defines the reference identifier used by the driver.
1666This string
1667overrides the default identifier ordinarily assigned by the driver
1668itself.
1669.It Cm mode Ar int
1670Specifies a mode number which is interpreted in a
1671device-specific fashion.
1672For instance, it selects a dialing
1673protocol in the ACTS driver and a device subtype in the
1674parse
1675drivers.
1676.It Cm flag1 Cm 0 \&| Cm 1
1677.It Cm flag2 Cm 0 \&| Cm 1
1678.It Cm flag3 Cm 0 \&| Cm 1
1679.It Cm flag4 Cm 0 \&| Cm 1
1680These four flags are used for customizing the clock driver.
1681The
1682interpretation of these values, and whether they are used at all,
1683is a function of the particular clock driver.
1684However, by
1685convention
1686.Cm flag4
1687is used to enable recording monitoring
1688data to the
1689.Cm clockstats
1690file configured with the
1691.Ic filegen
1692command.
1693Further information on the
1694.Ic filegen
1695command can be found in
1696.Sx Monitoring Options .
1697.El
1698.El
1699.Sh Miscellaneous Options
1700.Bl -tag -width indent
1701.It Ic broadcastdelay Ar seconds
1702The broadcast and multicast modes require a special calibration
1703to determine the network delay between the local and remote
1704servers.
1705Ordinarily, this is done automatically by the initial
1706protocol exchanges between the client and server.
1707In some cases,
1708the calibration procedure may fail due to network or server access
1709controls, for example.
1710This command specifies the default delay to
1711be used under these circumstances.
1712Typically (for Ethernet), a
1713number between 0.003 and 0.007 seconds is appropriate.
1714The default
1715when this command is not used is 0.004 seconds.
1716.It Ic driftfile Ar driftfile
1717This command specifies the name of the file used to record the
1718frequency offset of the local clock oscillator.
1719If the file exists,
1720it is read at startup in order to set the initial frequency offset
1721and then updated once per hour with the current frequency offset
1722computed by the daemon.
1723If the file does not exist or this command
1724is not given, the initial frequency offset is assumed zero.
1725In this
1726case, it may take some hours for the frequency to stabilize and the
1727residual timing errors to subside.
1728.Pp
1729The file format consists of a single line containing a single
1730floating point number, which records the frequency offset measured
1731in parts-per-million (PPM).
1732The file is updated by first writing
1733the current drift value into a temporary file and then renaming
1734this file to replace the old version.
1735This implies that
1736.Xr ntpd 8
1737must have write permission for the directory the
1738drift file is located in, and that file system links, symbolic or
1739otherwise, should be avoided.
1740.It Xo Ic enable
1741.Oo
1742.Cm auth | Cm bclient |
1743.Cm calibrate | Cm kernel |
1744.Cm monitor | Cm ntp |
1745.Cm stats
1746.Oc
1747.Xc
1748.It Xo Ic disable
1749.Oo
1750.Cm auth | Cm bclient |
1751.Cm calibrate | Cm kernel |
1752.Cm monitor | Cm ntp |
1753.Cm stats
1754.Oc
1755.Xc
1756Provides a way to enable or disable various server options.
1757Flags not mentioned are unaffected.
1758Note that all of these flags
1759can be controlled remotely using the
1760.Xr ntpdc 8
1761utility program.
1762.Bl -tag -width indent
1763.It Cm bclient
1764When enabled, this is identical to the
1765.Ic broadcastclient
1766command.
1767The default for this flag is
1768.Ic disable .
1769.It Cm calibrate
1770Enables the calibration facility, which automatically adjusts
1771the
1772.Ic time1
1773values for each clock driver to display the same
1774offset as the currently selected source or kernel discipline
1775signal.
1776See the
1777.Qq "Reference Clock Drivers"
1778page
1779for further information.
1780The default for this flag is
1781.Ic disable .
1782.It Cm kernel
1783Enables the precision-time kernel support for the
1784.Xr adjtime 2
1785system call, if implemented.
1786Ordinarily,
1787support for this routine is detected automatically when the NTP
1788daemon is compiled, so it is not necessary for the user to worry
1789about this flag.
1790It is provided primarily so that this support
1791can be disabled during kernel development.
1792The default for this
1793flag is
1794.Ic enable .
1795.It Cm monitor
1796Enables the monitoring facility.
1797See the
1798.Xr ntpdc 8
1799program
1800and the
1801.Ic monlist
1802command or further information.
1803The
1804default for this flag is
1805.Ic enable .
1806.It Cm ntp
1807Enables the server to adjust its local clock by means of NTP.
1808If disabled, the local clock free-runs at its intrinsic time and
1809frequency offset.
1810This flag is useful in case the local clock is
1811controlled by some other device or protocol and NTP is used only to
1812provide synchronization to other clients.
1813In this case, the local
1814clock driver can be used to provide this function and also certain
1815time variables for error estimates and leap-indicators.
1816See the
1817.Qq "Reference Clock Drivers"
1818page for further
1819information.
1820The default for this flag is
1821.Ic enable .
1822.It Cm stats
1823Enables the statistics facility.
1824See the
1825.Qq "Monitoring Options"
1826page for further information.
1827The default for this flag is
1828.Ic enable .
1829.El
1830.It Ic logconfig Ar configkeyword
1831This command controls the amount and type of output written to
1832the system
1833.Xr syslog 3
1834facility or the alternate
1835.Ic logfile
1836log file.
1837By default, all output is turned on.
1838All
1839.Ar configkeyword
1840keywords can be prefixed with
1841.Ql = ,
1842.Ql +
1843and
1844.Ql - ,
1845where
1846.Ql =
1847sets the
1848.Xr syslog 3
1849priority mask,
1850.Ql +
1851adds and
1852.Ql -
1853removes
1854messages.
1855.Xr syslog 3
1856messages can be controlled in four
1857classes
1858.Po
1859.Cm clock ,
1860.Cm peer ,
1861.Cm sys
1862and
1863.Cm sync
1864.Pc .
1865Within these classes four types of messages can be
1866controlled.
1867Informational messages
1868.Pq Cm info
1869control configuration
1870information.
1871Event messages
1872.Pq Cm events
1873control logging of
1874events (reachability, synchronization, alarm conditions).
1875Statistical output is controlled with the
1876.Cm statistics
1877keyword.
1878The final message group is the status messages.
1879This
1880describes mainly the synchronizations status.
1881Configuration
1882keywords are formed by concatenating the message class with the
1883event class.
1884The
1885.Cm all
1886prefix can be used instead of a
1887message class.
1888A message class may also be followed by the
1889.Cm all
1890keyword to enable/disable all messages of the
1891respective message class.
1892Thus, a minimal log configuration could look like this:
1893.Bd -literal
1894logconfig=syncstatus +sysevents
1895.Ed
1896.Pp
1897This would just list the synchronizations state of
1898.Xr ntpd 8
1899and the major system events.
1900For a simple reference server, the
1901following minimum message configuration could be useful:
1902.Bd -literal
1903logconfig=syncall +clockall
1904.Ed
1905.Pp
1906This configuration will list all clock information and
1907synchronization information.
1908All other events and messages about
1909peers, system events and so on is suppressed.
1910.It Ic logfile Ar logfile
1911This command specifies the location of an alternate log file to
1912be used instead of the default system
1913.Xr syslog 3
1914facility.
1915.It Ic setvar Ar variable Op Cm default
1916This command adds an additional system variable.
1917These
1918variables can be used to distribute additional information such as
1919the access policy.
1920If the variable of the form
1921.Sm off
1922.Va name = Ar value
1923.Sm on
1924is followed by the
1925.Cm default
1926keyword, the
1927variable will be listed as part of the default system variables
1928.Po
1929.Xr ntpq 8
1930.Ic rv
1931command
1932.Pc ) .
1933These additional variables serve
1934informational purposes only.
1935They are not related to the protocol
1936other that they can be listed.
1937The known protocol variables will
1938always override any variables defined via the
1939.Ic setvar
1940mechanism.
1941There are three special variables that contain the names
1942of all variable of the same group.
1943The
1944.Va sys_var_list
1945holds
1946the names of all system variables.
1947The
1948.Va peer_var_list
1949holds
1950the names of all peer variables and the
1951.Va clock_var_list
1952holds the names of the reference clock variables.
1953.It Xo Ic tinker
1954.Oo
1955.Cm step Ar step |
1956.Cm panic Ar panic |
1957.Cm dispersion Ar dispersion |
1958.Cm stepout Ar stepout |
1959.Cm minpoll Ar minpoll |
1960.Cm allan Ar allan |
1961.Cm huffpuff Ar huffpuff
1962.Oc
1963.Xc
1964This command can be used to alter several system variables in
1965very exceptional circumstances.
1966It should occur in the
1967configuration file before any other configuration options.
1968The
1969default values of these variables have been carefully optimized for
1970a wide range of network speeds and reliability expectations.
1971In
1972general, they interact in intricate ways that are hard to predict
1973and some combinations can result in some very nasty behavior.
1974Very
1975rarely is it necessary to change the default values; but, some
1976folks can't resist twisting the knobs anyway and this command is
1977for them.
1978Emphasis added: twisters are on their own and can expect
1979no help from the support group.
1980.Pp
1981All arguments are in floating point seconds or seconds per
1982second.
1983The
1984.Ar minpoll
1985argument is an integer in seconds to
1986the power of two.
1987The variables operate as follows:
1988.Bl -tag -width indent
1989.It Cm step Ar step
1990The argument becomes the new value for the step threshold,
1991normally 0.128 s.
1992If set to zero, step adjustments will never
1993occur.
1994In general, if the intent is only to avoid step adjustments,
1995the step threshold should be left alone and the
1996.Fl x
1997command
1998line option be used instead.
1999.It Cm panic Ar panic
2000The argument becomes the new value for the panic threshold,
2001normally 1000 s.
2002If set to zero, the panic sanity check is disabled
2003and a clock offset of any value will be accepted.
2004.It Cm dispersion Ar dispersion
2005The argument becomes the new value for the dispersion increase
2006rate, normally .000015.
2007.It Cm stepout Ar stepout
2008The argument becomes the new value for the watchdog timeout,
2009normally 900 s.
2010.It Cm minpoll Ar minpoll
2011The argument becomes the new value for the minimum poll
2012interval used when configuring multicast client, manycast client
2013and , symmetric passive mode association.
2014The value defaults to 6
2015(64 s) and has a lower limit of 4 (16 s).
2016.It Cm allan Ar allan
2017The argument becomes the new value for the minimum Allan
2018intercept, which is a parameter of the PLL/FLL clock discipline
2019algorithm.
2020The value defaults to 1024 s, which is also the lower
2021limit.
2022.It Cm huffpuff Ar huffpuff
2023The argument becomes the new value for the experimental
2024huff-n'-puff filter span, which determines the most recent interval
2025the algorithm will search for a minimum delay.
2026The lower limit is
2027900 s (15 m), but a more reasonable value is 7200 (2 hours).
2028There
2029is no default, since the filter is not enabled unless this command
2030is given.
2031.El
2032.It Xo Ic trap Ar host_address
2033.Op Cm port Ar port_number
2034.Op Cm interface Ar interface_address
2035.Xc
2036This command configures a trap receiver at the given host
2037address and port number for sending messages with the specified
2038local interface address.
2039If the port number is unspecified, a value
2040of 18447 is used.
2041If the interface address is not specified, the
2042message is sent with a source address of the local interface the
2043message is sent through.
2044Note that on a multihomed host the
2045interface used may vary from time to time with routing changes.
2046.Pp
2047The trap receiver will generally log event messages and other
2048information from the server in a log file.
2049While such monitor
2050programs may also request their own trap dynamically, configuring a
2051trap receiver will ensure that no messages are lost when the server
2052is started.
2053.El
2054.Sh FILES
2055.Bl -tag -width /etc/ntp.drift -compact
2056.It Pa /etc/ntp.conf
2057the default name of the configuration file
2058.It Pa ntp.keys
2059private MD5 keys
2060.It Pa ntpkey
2061RSA private key
2062.It Pa ntpkey_ Ns Ar host
2063RSA public key
2064.It Pa ntp_dh
2065Diffie-Hellman agreement parameters
2066.El
2067.Sh SEE ALSO
2068.Xr ntpd 8 ,
2069.Xr ntpdc 8 ,
2070.Xr ntpq 8
2071.Pp
2072In addition to the manual pages provided,
2073comprehensive documentation is available on the world wide web
2074at
2075.Li http://www.ntp.org/ .
2076A snapshot of this documentation is available in HTML format in
2077.Pa /usr/share/doc/ntp .
2078.Rs
2079.%A David L. Mills
2080.%T Network Time Protocol (Version 3)
2081.%O RFC1305
2082.Re
2083.Sh BUGS
2084The syntax checking is not picky; some combinations of
2085ridiculous and even hilarious options and modes may not be
2086detected.
2087.Pp
2088The
2089.Pa ntpkey_ Ns Ar host
2090files are really digital
2091certificates.
2092These should be obtained via secure directory
2093services when they become universally available.