xref: /freebsd/contrib/ntp/ntpd/ntp.conf.def (revision 277fbb92d5e4cd0938c67f77b08d9ba4ac9d54a6)
1/* -*- Mode: Text -*- */
2
3autogen definitions options;
4
5#include copyright.def
6
7// We want the synopsis to be "/etc/ntp.conf" but we need the prog-name
8// to be ntp.conf - the latter is also how autogen produces the output
9// file name.
10prog-name	= "ntp.conf";
11file-path	= "/etc/ntp.conf";
12prog-title	= "Network Time Protocol (NTP) daemon configuration file format";
13
14/* explain: Additional information whenever the usage routine is invoked */
15explain = <<- _END_EXPLAIN
16	_END_EXPLAIN;
17
18doc-section	= {
19  ds-type	= 'DESCRIPTION';
20  ds-format	= 'mdoc';
21  ds-text	= <<- _END_PROG_MDOC_DESCRIP
22The
23.Nm
24configuration file is read at initial startup by the
25.Xr ntpd 1ntpdmdoc
26daemon in order to specify the synchronization sources,
27modes and other related information.
28Usually, it is installed in the
29.Pa /etc
30directory,
31but could be installed elsewhere
32(see the daemon's
33.Fl c
34command line option).
35.Pp
36The file format is similar to other
37.Ux
38configuration files.
39Comments begin with a
40.Ql #
41character and extend to the end of the line;
42blank lines are ignored.
43Configuration commands consist of an initial keyword
44followed by a list of arguments,
45some of which may be optional, separated by whitespace.
46Commands may not be continued over multiple lines.
47Arguments may be host names,
48host addresses written in numeric, dotted-quad form,
49integers, floating point numbers (when specifying times in seconds)
50and text strings.
51.Pp
52The rest of this page describes the configuration and control options.
53The
54.Qq Notes on Configuring NTP and Setting up an NTP Subnet
55page
56(available as part of the HTML documentation
57provided in
58.Pa /usr/share/doc/ntp )
59contains an extended discussion of these options.
60In addition to the discussion of general
61.Sx Configuration Options ,
62there are sections describing the following supported functionality
63and the options used to control it:
64.Bl -bullet -offset indent
65.It
66.Sx Authentication Support
67.It
68.Sx Monitoring Support
69.It
70.Sx Access Control Support
71.It
72.Sx Automatic NTP Configuration Options
73.It
74.Sx Reference Clock Support
75.It
76.Sx Miscellaneous Options
77.El
78.Pp
79Following these is a section describing
80.Sx Miscellaneous Options .
81While there is a rich set of options available,
82the only required option is one or more
83.Ic pool ,
84.Ic server ,
85.Ic peer ,
86.Ic broadcast
87or
88.Ic manycastclient
89commands.
90.Sh Configuration Support
91Following is a description of the configuration commands in
92NTPv4.
93These commands have the same basic functions as in NTPv3 and
94in some cases new functions and new arguments.
95There are two
96classes of commands, configuration commands that configure a
97persistent association with a remote server or peer or reference
98clock, and auxiliary commands that specify environmental variables
99that control various related operations.
100.Ss Configuration Commands
101The various modes are determined by the command keyword and the
102type of the required IP address.
103Addresses are classed by type as
104(s) a remote server or peer (IPv4 class A, B and C), (b) the
105broadcast address of a local interface, (m) a multicast address (IPv4
106class D), or (r) a reference clock address (127.127.x.x).
107Note that
108only those options applicable to each command are listed below.
109Use
110of options not listed may not be caught as an error, but may result
111in some weird and even destructive behavior.
112.Pp
113If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
114is detected, support for the IPv6 address family is generated
115in addition to the default support of the IPv4 address family.
116In a few cases, including the reslist billboard generated
117by ntpdc, IPv6 addresses are automatically generated.
118IPv6 addresses can be identified by the presence of colons
119.Dq \&:
120in the address field.
121IPv6 addresses can be used almost everywhere where
122IPv4 addresses can be used,
123with the exception of reference clock addresses,
124which are always IPv4.
125.Pp
126Note that in contexts where a host name is expected, a
127.Fl 4
128qualifier preceding
129the host name forces DNS resolution to the IPv4 namespace,
130while a
131.Fl 6
132qualifier forces DNS resolution to the IPv6 namespace.
133See IPv6 references for the
134equivalent classes for that address family.
135.Bl -tag -width indent
136.It Xo Ic pool Ar address
137.Op Cm burst
138.Op Cm iburst
139.Op Cm version Ar version
140.Op Cm prefer
141.Op Cm minpoll Ar minpoll
142.Op Cm maxpoll Ar maxpoll
143.Xc
144.It Xo Ic server Ar address
145.Op Cm key Ar key \&| Cm autokey
146.Op Cm burst
147.Op Cm iburst
148.Op Cm version Ar version
149.Op Cm prefer
150.Op Cm minpoll Ar minpoll
151.Op Cm maxpoll Ar maxpoll
152.Xc
153.It Xo Ic peer Ar address
154.Op Cm key Ar key \&| Cm autokey
155.Op Cm version Ar version
156.Op Cm prefer
157.Op Cm minpoll Ar minpoll
158.Op Cm maxpoll Ar maxpoll
159.Xc
160.It Xo Ic broadcast Ar address
161.Op Cm key Ar key \&| Cm autokey
162.Op Cm version Ar version
163.Op Cm prefer
164.Op Cm minpoll Ar minpoll
165.Op Cm ttl Ar ttl
166.Xc
167.It Xo Ic manycastclient Ar address
168.Op Cm key Ar key \&| Cm autokey
169.Op Cm version Ar version
170.Op Cm prefer
171.Op Cm minpoll Ar minpoll
172.Op Cm maxpoll Ar maxpoll
173.Op Cm ttl Ar ttl
174.Xc
175.El
176.Pp
177These five commands specify the time server name or address to
178be used and the mode in which to operate.
179The
180.Ar address
181can be
182either a DNS name or an IP address in dotted-quad notation.
183Additional information on association behavior can be found in the
184.Qq Association Management
185page
186(available as part of the HTML documentation
187provided in
188.Pa /usr/share/doc/ntp ) .
189.Bl -tag -width indent
190.It Ic pool
191For type s addresses, this command mobilizes a persistent
192client mode association with a number of remote servers.
193In this mode the local clock can synchronized to the
194remote server, but the remote server can never be synchronized to
195the local clock.
196.It Ic server
197For type s and r addresses, this command mobilizes a persistent
198client mode association with the specified remote server or local
199radio clock.
200In this mode the local clock can synchronized to the
201remote server, but the remote server can never be synchronized to
202the local clock.
203This command should
204.Em not
205be used for type
206b or m addresses.
207.It Ic peer
208For type s addresses (only), this command mobilizes a
209persistent symmetric-active mode association with the specified
210remote peer.
211In this mode the local clock can be synchronized to
212the remote peer or the remote peer can be synchronized to the local
213clock.
214This is useful in a network of servers where, depending on
215various failure scenarios, either the local or remote peer may be
216the better source of time.
217This command should NOT be used for type
218b, m or r addresses.
219.It Ic broadcast
220For type b and m addresses (only), this
221command mobilizes a persistent broadcast mode association.
222Multiple
223commands can be used to specify multiple local broadcast interfaces
224(subnets) and/or multiple multicast groups.
225Note that local
226broadcast messages go only to the interface associated with the
227subnet specified, but multicast messages go to all interfaces.
228In broadcast mode the local server sends periodic broadcast
229messages to a client population at the
230.Ar address
231specified, which is usually the broadcast address on (one of) the
232local network(s) or a multicast address assigned to NTP.
233The IANA
234has assigned the multicast group address IPv4 224.0.1.1 and
235IPv6 ff05::101 (site local) exclusively to
236NTP, but other nonconflicting addresses can be used to contain the
237messages within administrative boundaries.
238Ordinarily, this
239specification applies only to the local server operating as a
240sender; for operation as a broadcast client, see the
241.Ic broadcastclient
242or
243.Ic multicastclient
244commands
245below.
246.It Ic manycastclient
247For type m addresses (only), this command mobilizes a
248manycast client mode association for the multicast address
249specified.
250In this case a specific address must be supplied which
251matches the address used on the
252.Ic manycastserver
253command for
254the designated manycast servers.
255The NTP multicast address
256224.0.1.1 assigned by the IANA should NOT be used, unless specific
257means are taken to avoid spraying large areas of the Internet with
258these messages and causing a possibly massive implosion of replies
259at the sender.
260The
261.Ic manycastserver
262command specifies that the local server
263is to operate in client mode with the remote servers that are
264discovered as the result of broadcast/multicast messages.
265The
266client broadcasts a request message to the group address associated
267with the specified
268.Ar address
269and specifically enabled
270servers respond to these messages.
271The client selects the servers
272providing the best time and continues as with the
273.Ic server
274command.
275The remaining servers are discarded as if never
276heard.
277.El
278.Pp
279Options:
280.Bl -tag -width indent
281.It Cm autokey
282All packets sent to and received from the server or peer are to
283include authentication fields encrypted using the autokey scheme
284described in
285.Sx Authentication Options .
286.It Cm burst
287when the server is reachable, send a burst of eight packets
288instead of the usual one.
289The packet spacing is normally 2 s;
290however, the spacing between the first and second packets
291can be changed with the calldelay command to allow
292additional time for a modem or ISDN call to complete.
293This is designed to improve timekeeping quality
294with the
295.Ic server
296command and s addresses.
297.It Cm iburst
298When the server is unreachable, send a burst of eight packets
299instead of the usual one.
300The packet spacing is normally 2 s;
301however, the spacing between the first two packets can be
302changed with the calldelay command to allow
303additional time for a modem or ISDN call to complete.
304This is designed to speed the initial synchronization
305acquisition with the
306.Ic server
307command and s addresses and when
308.Xr ntpd 1ntpdmdoc
309is started with the
310.Fl q
311option.
312.It Cm key Ar key
313All packets sent to and received from the server or peer are to
314include authentication fields encrypted using the specified
315.Ar key
316identifier with values from 1 to 65534, inclusive.
317The
318default is to include no encryption field.
319.It Cm minpoll Ar minpoll
320.It Cm maxpoll Ar maxpoll
321These options specify the minimum and maximum poll intervals
322for NTP messages, as a power of 2 in seconds
323The maximum poll
324interval defaults to 10 (1,024 s), but can be increased by the
325.Cm maxpoll
326option to an upper limit of 17 (36.4 h).
327The
328minimum poll interval defaults to 6 (64 s), but can be decreased by
329the
330.Cm minpoll
331option to a lower limit of 4 (16 s).
332.It Cm noselect
333Marks the server as unused, except for display purposes.
334The server is discarded by the selection algroithm.
335.It Cm prefer
336Marks the server as preferred.
337All other things being equal,
338this host will be chosen for synchronization among a set of
339correctly operating hosts.
340See the
341.Qq Mitigation Rules and the prefer Keyword
342page
343(available as part of the HTML documentation
344provided in
345.Pa /usr/share/doc/ntp )
346for further information.
347.It Cm ttl Ar ttl
348This option is used only with broadcast server and manycast
349client modes.
350It specifies the time-to-live
351.Ar ttl
352to
353use on broadcast server and multicast server and the maximum
354.Ar ttl
355for the expanding ring search with manycast
356client packets.
357Selection of the proper value, which defaults to
358127, is something of a black art and should be coordinated with the
359network administrator.
360.It Cm version Ar version
361Specifies the version number to be used for outgoing NTP
362packets.
363Versions 1-4 are the choices, with version 4 the
364default.
365.El
366.Ss Auxiliary Commands
367.Bl -tag -width indent
368.It Ic broadcastclient
369This command enables reception of broadcast server messages to
370any local interface (type b) address.
371Upon receiving a message for
372the first time, the broadcast client measures the nominal server
373propagation delay using a brief client/server exchange with the
374server, then enters the broadcast client mode, in which it
375synchronizes to succeeding broadcast messages.
376Note that, in order
377to avoid accidental or malicious disruption in this mode, both the
378server and client should operate using symmetric-key or public-key
379authentication as described in
380.Sx Authentication Options .
381.It Ic manycastserver Ar address ...
382This command enables reception of manycast client messages to
383the multicast group address(es) (type m) specified.
384At least one
385address is required, but the NTP multicast address 224.0.1.1
386assigned by the IANA should NOT be used, unless specific means are
387taken to limit the span of the reply and avoid a possibly massive
388implosion at the original sender.
389Note that, in order to avoid
390accidental or malicious disruption in this mode, both the server
391and client should operate using symmetric-key or public-key
392authentication as described in
393.Sx Authentication Options .
394.It Ic multicastclient Ar address ...
395This command enables reception of multicast server messages to
396the multicast group address(es) (type m) specified.
397Upon receiving
398a message for the first time, the multicast client measures the
399nominal server propagation delay using a brief client/server
400exchange with the server, then enters the broadcast client mode, in
401which it synchronizes to succeeding multicast messages.
402Note that,
403in order to avoid accidental or malicious disruption in this mode,
404both the server and client should operate using symmetric-key or
405public-key authentication as described in
406.Sx Authentication Options .
407.It Ic mdnstries Ar number
408If we are participating in mDNS,
409after we have synched for the first time
410we attempt to register with the mDNS system.
411If that registration attempt fails,
412we try again at one minute intervals for up to
413.Ic mdnstries
414times.
415After all,
416.Ic ntpd
417may be starting before mDNS.
418The default value for
419.Ic mdnstries
420is 5.
421.El
422.Sh Authentication Support
423Authentication support allows the NTP client to verify that the
424server is in fact known and trusted and not an intruder intending
425accidentally or on purpose to masquerade as that server.
426The NTPv3
427specification RFC-1305 defines a scheme which provides
428cryptographic authentication of received NTP packets.
429Originally,
430this was done using the Data Encryption Standard (DES) algorithm
431operating in Cipher Block Chaining (CBC) mode, commonly called
432DES-CBC.
433Subsequently, this was replaced by the RSA Message Digest
4345 (MD5) algorithm using a private key, commonly called keyed-MD5.
435Either algorithm computes a message digest, or one-way hash, which
436can be used to verify the server has the correct private key and
437key identifier.
438.Pp
439NTPv4 retains the NTPv3 scheme, properly described as symmetric key
440cryptography and, in addition, provides a new Autokey scheme
441based on public key cryptography.
442Public key cryptography is generally considered more secure
443than symmetric key cryptography, since the security is based
444on a private value which is generated by each server and
445never revealed.
446With Autokey all key distribution and
447management functions involve only public values, which
448considerably simplifies key distribution and storage.
449Public key management is based on X.509 certificates,
450which can be provided by commercial services or
451produced by utility programs in the OpenSSL software library
452or the NTPv4 distribution.
453.Pp
454While the algorithms for symmetric key cryptography are
455included in the NTPv4 distribution, public key cryptography
456requires the OpenSSL software library to be installed
457before building the NTP distribution.
458Directions for doing that
459are on the Building and Installing the Distribution page.
460.Pp
461Authentication is configured separately for each association
462using the
463.Cm key
464or
465.Cm autokey
466subcommand on the
467.Ic peer ,
468.Ic server ,
469.Ic broadcast
470and
471.Ic manycastclient
472configuration commands as described in
473.Sx Configuration Options
474page.
475The authentication
476options described below specify the locations of the key files,
477if other than default, which symmetric keys are trusted
478and the interval between various operations, if other than default.
479.Pp
480Authentication is always enabled,
481although ineffective if not configured as
482described below.
483If a NTP packet arrives
484including a message authentication
485code (MAC), it is accepted only if it
486passes all cryptographic checks.
487The
488checks require correct key ID, key value
489and message digest.
490If the packet has
491been modified in any way or replayed
492by an intruder, it will fail one or more
493of these checks and be discarded.
494Furthermore, the Autokey scheme requires a
495preliminary protocol exchange to obtain
496the server certificate, verify its
497credentials and initialize the protocol
498.Pp
499The
500.Cm auth
501flag controls whether new associations or
502remote configuration commands require cryptographic authentication.
503This flag can be set or reset by the
504.Ic enable
505and
506.Ic disable
507commands and also by remote
508configuration commands sent by a
509.Xr ntpdc 1ntpdcmdoc
510program running in
511another machine.
512If this flag is enabled, which is the default
513case, new broadcast client and symmetric passive associations and
514remote configuration commands must be cryptographically
515authenticated using either symmetric key or public key cryptography.
516If this
517flag is disabled, these operations are effective
518even if not cryptographic
519authenticated.
520It should be understood
521that operating with the
522.Ic auth
523flag disabled invites a significant vulnerability
524where a rogue hacker can
525masquerade as a falseticker and seriously
526disrupt system timekeeping.
527It is
528important to note that this flag has no purpose
529other than to allow or disallow
530a new association in response to new broadcast
531and symmetric active messages
532and remote configuration commands and, in particular,
533the flag has no effect on
534the authentication process itself.
535.Pp
536An attractive alternative where multicast support is available
537is manycast mode, in which clients periodically troll
538for servers as described in the
539.Sx Automatic NTP Configuration Options
540page.
541Either symmetric key or public key
542cryptographic authentication can be used in this mode.
543The principle advantage
544of manycast mode is that potential servers need not be
545configured in advance,
546since the client finds them during regular operation,
547and the configuration
548files for all clients can be identical.
549.Pp
550The security model and protocol schemes for
551both symmetric key and public key
552cryptography are summarized below;
553further details are in the briefings, papers
554and reports at the NTP project page linked from
555.Li http://www.ntp.org/ .
556.Ss Symmetric-Key Cryptography
557The original RFC-1305 specification allows any one of possibly
55865,534 keys, each distinguished by a 32-bit key identifier, to
559authenticate an association.
560The servers and clients involved must
561agree on the key and key identifier to
562authenticate NTP packets.
563Keys and
564related information are specified in a key
565file, usually called
566.Pa ntp.keys ,
567which must be distributed and stored using
568secure means beyond the scope of the NTP protocol itself.
569Besides the keys used
570for ordinary NTP associations,
571additional keys can be used as passwords for the
572.Xr ntpq 1ntpqmdoc
573and
574.Xr ntpdc 1ntpdcmdoc
575utility programs.
576.Pp
577When
578.Xr ntpd 1ntpdmdoc
579is first started, it reads the key file specified in the
580.Ic keys
581configuration command and installs the keys
582in the key cache.
583However,
584individual keys must be activated with the
585.Ic trusted
586command before use.
587This
588allows, for instance, the installation of possibly
589several batches of keys and
590then activating or deactivating each batch
591remotely using
592.Xr ntpdc 1ntpdcmdoc .
593This also provides a revocation capability that can be used
594if a key becomes compromised.
595The
596.Ic requestkey
597command selects the key used as the password for the
598.Xr ntpdc 1ntpdcmdoc
599utility, while the
600.Ic controlkey
601command selects the key used as the password for the
602.Xr ntpq 1ntpqmdoc
603utility.
604.Ss Public Key Cryptography
605NTPv4 supports the original NTPv3 symmetric key scheme
606described in RFC-1305 and in addition the Autokey protocol,
607which is based on public key cryptography.
608The Autokey Version 2 protocol described on the Autokey Protocol
609page verifies packet integrity using MD5 message digests
610and verifies the source with digital signatures and any of several
611digest/signature schemes.
612Optional identity schemes described on the Identity Schemes
613page and based on cryptographic challenge/response algorithms
614are also available.
615Using all of these schemes provides strong security against
616replay with or without modification, spoofing, masquerade
617and most forms of clogging attacks.
618.\" .Pp
619.\" The cryptographic means necessary for all Autokey operations
620.\" is provided by the OpenSSL software library.
621.\" This library is available from http://www.openssl.org/
622.\" and can be installed using the procedures outlined
623.\" in the Building and Installing the Distribution page.
624.\" Once installed,
625.\" the configure and build
626.\" process automatically detects the library and links
627.\" the library routines required.
628.Pp
629The Autokey protocol has several modes of operation
630corresponding to the various NTP modes supported.
631Most modes use a special cookie which can be
632computed independently by the client and server,
633but encrypted in transmission.
634All modes use in addition a variant of the S-KEY scheme,
635in which a pseudo-random key list is generated and used
636in reverse order.
637These schemes are described along with an executive summary,
638current status, briefing slides and reading list on the
639.Sx Autonomous Authentication
640page.
641.Pp
642The specific cryptographic environment used by Autokey servers
643and clients is determined by a set of files
644and soft links generated by the
645.Xr ntp-keygen 1ntpkeygenmdoc
646program.
647This includes a required host key file,
648required certificate file and optional sign key file,
649leapsecond file and identity scheme files.
650The
651digest/signature scheme is specified in the X.509 certificate
652along with the matching sign key.
653There are several schemes
654available in the OpenSSL software library, each identified
655by a specific string such as
656.Cm md5WithRSAEncryption ,
657which stands for the MD5 message digest with RSA
658encryption scheme.
659The current NTP distribution supports
660all the schemes in the OpenSSL library, including
661those based on RSA and DSA digital signatures.
662.Pp
663NTP secure groups can be used to define cryptographic compartments
664and security hierarchies.
665It is important that every host
666in the group be able to construct a certificate trail to one
667or more trusted hosts in the same group.
668Each group
669host runs the Autokey protocol to obtain the certificates
670for all hosts along the trail to one or more trusted hosts.
671This requires the configuration file in all hosts to be
672engineered so that, even under anticipated failure conditions,
673the NTP subnet will form such that every group host can find
674a trail to at least one trusted host.
675.Ss Naming and Addressing
676It is important to note that Autokey does not use DNS to
677resolve addresses, since DNS can't be completely trusted
678until the name servers have synchronized clocks.
679The cryptographic name used by Autokey to bind the host identity
680credentials and cryptographic values must be independent
681of interface, network and any other naming convention.
682The name appears in the host certificate in either or both
683the subject and issuer fields, so protection against
684DNS compromise is essential.
685.Pp
686By convention, the name of an Autokey host is the name returned
687by the Unix
688.Xr gethostname 2
689system call or equivalent in other systems.
690By the system design
691model, there are no provisions to allow alternate names or aliases.
692However, this is not to say that DNS aliases, different names
693for each interface, etc., are constrained in any way.
694.Pp
695It is also important to note that Autokey verifies authenticity
696using the host name, network address and public keys,
697all of which are bound together by the protocol specifically
698to deflect masquerade attacks.
699For this reason Autokey
700includes the source and destinatino IP addresses in message digest
701computations and so the same addresses must be available
702at both the server and client.
703For this reason operation
704with network address translation schemes is not possible.
705This reflects the intended robust security model where government
706and corporate NTP servers are operated outside firewall perimeters.
707.Ss Operation
708A specific combination of authentication scheme (none,
709symmetric key, public key) and identity scheme is called
710a cryptotype, although not all combinations are compatible.
711There may be management configurations where the clients,
712servers and peers may not all support the same cryptotypes.
713A secure NTPv4 subnet can be configured in many ways while
714keeping in mind the principles explained above and
715in this section.
716Note however that some cryptotype
717combinations may successfully interoperate with each other,
718but may not represent good security practice.
719.Pp
720The cryptotype of an association is determined at the time
721of mobilization, either at configuration time or some time
722later when a message of appropriate cryptotype arrives.
723When mobilized by a
724.Ic server
725or
726.Ic peer
727configuration command and no
728.Ic key
729or
730.Ic autokey
731subcommands are present, the association is not
732authenticated; if the
733.Ic key
734subcommand is present, the association is authenticated
735using the symmetric key ID specified; if the
736.Ic autokey
737subcommand is present, the association is authenticated
738using Autokey.
739.Pp
740When multiple identity schemes are supported in the Autokey
741protocol, the first message exchange determines which one is used.
742The client request message contains bits corresponding
743to which schemes it has available.
744The server response message
745contains bits corresponding to which schemes it has available.
746Both server and client match the received bits with their own
747and select a common scheme.
748.Pp
749Following the principle that time is a public value,
750a server responds to any client packet that matches
751its cryptotype capabilities.
752Thus, a server receiving
753an unauthenticated packet will respond with an unauthenticated
754packet, while the same server receiving a packet of a cryptotype
755it supports will respond with packets of that cryptotype.
756However, unconfigured broadcast or manycast client
757associations or symmetric passive associations will not be
758mobilized unless the server supports a cryptotype compatible
759with the first packet received.
760By default, unauthenticated associations will not be mobilized
761unless overridden in a decidedly dangerous way.
762.Pp
763Some examples may help to reduce confusion.
764Client Alice has no specific cryptotype selected.
765Server Bob has both a symmetric key file and minimal Autokey files.
766Alice's unauthenticated messages arrive at Bob, who replies with
767unauthenticated messages.
768Cathy has a copy of Bob's symmetric
769key file and has selected key ID 4 in messages to Bob.
770Bob verifies the message with his key ID 4.
771If it's the
772same key and the message is verified, Bob sends Cathy a reply
773authenticated with that key.
774If verification fails,
775Bob sends Cathy a thing called a crypto-NAK, which tells her
776something broke.
777She can see the evidence using the
778.Xr ntpq 1ntpqmdoc
779program.
780.Pp
781Denise has rolled her own host key and certificate.
782She also uses one of the identity schemes as Bob.
783She sends the first Autokey message to Bob and they
784both dance the protocol authentication and identity steps.
785If all comes out okay, Denise and Bob continue as described above.
786.Pp
787It should be clear from the above that Bob can support
788all the girls at the same time, as long as he has compatible
789authentication and identity credentials.
790Now, Bob can act just like the girls in his own choice of servers;
791he can run multiple configured associations with multiple different
792servers (or the same server, although that might not be useful).
793But, wise security policy might preclude some cryptotype
794combinations; for instance, running an identity scheme
795with one server and no authentication with another might not be wise.
796.Ss Key Management
797The cryptographic values used by the Autokey protocol are
798incorporated as a set of files generated by the
799.Xr ntp-keygen 1ntpkeygenmdoc
800utility program, including symmetric key, host key and
801public certificate files, as well as sign key, identity parameters
802and leapseconds files.
803Alternatively, host and sign keys and
804certificate files can be generated by the OpenSSL utilities
805and certificates can be imported from public certificate
806authorities.
807Note that symmetric keys are necessary for the
808.Xr ntpq 1ntpqmdoc
809and
810.Xr ntpdc 1ntpdcmdoc
811utility programs.
812The remaining files are necessary only for the
813Autokey protocol.
814.Pp
815Certificates imported from OpenSSL or public certificate
816authorities have certian limitations.
817The certificate should be in ASN.1 syntax, X.509 Version 3
818format and encoded in PEM, which is the same format
819used by OpenSSL.
820The overall length of the certificate encoded
821in ASN.1 must not exceed 1024 bytes.
822The subject distinguished
823name field (CN) is the fully qualified name of the host
824on which it is used; the remaining subject fields are ignored.
825The certificate extension fields must not contain either
826a subject key identifier or a issuer key identifier field;
827however, an extended key usage field for a trusted host must
828contain the value
829.Cm trustRoot ; .
830Other extension fields are ignored.
831.Ss Authentication Commands
832.Bl -tag -width indent
833.It Ic autokey Op Ar logsec
834Specifies the interval between regenerations of the session key
835list used with the Autokey protocol.
836Note that the size of the key
837list for each association depends on this interval and the current
838poll interval.
839The default value is 12 (4096 s or about 1.1 hours).
840For poll intervals above the specified interval, a session key list
841with a single entry will be regenerated for every message
842sent.
843.It Ic controlkey Ar key
844Specifies the key identifier to use with the
845.Xr ntpq 1ntpqmdoc
846utility, which uses the standard
847protocol defined in RFC-1305.
848The
849.Ar key
850argument is
851the key identifier for a trusted key, where the value can be in the
852range 1 to 65,534, inclusive.
853.It Xo Ic crypto
854.Op Cm cert Ar file
855.Op Cm leap Ar file
856.Op Cm randfile Ar file
857.Op Cm host Ar file
858.Op Cm sign Ar file
859.Op Cm gq Ar file
860.Op Cm gqpar Ar file
861.Op Cm iffpar Ar file
862.Op Cm mvpar Ar file
863.Op Cm pw Ar password
864.Xc
865This command requires the OpenSSL library.
866It activates public key
867cryptography, selects the message digest and signature
868encryption scheme and loads the required private and public
869values described above.
870If one or more files are left unspecified,
871the default names are used as described above.
872Unless the complete path and name of the file are specified, the
873location of a file is relative to the keys directory specified
874in the
875.Ic keysdir
876command or default
877.Pa /usr/local/etc .
878Following are the subcommands:
879.Bl -tag -width indent
880.It Cm cert Ar file
881Specifies the location of the required host public certificate file.
882This overrides the link
883.Pa ntpkey_cert_ Ns Ar hostname
884in the keys directory.
885.It Cm gqpar Ar file
886Specifies the location of the optional GQ parameters file.
887This
888overrides the link
889.Pa ntpkey_gq_ Ns Ar hostname
890in the keys directory.
891.It Cm host Ar file
892Specifies the location of the required host key file.
893This overrides
894the link
895.Pa ntpkey_key_ Ns Ar hostname
896in the keys directory.
897.It Cm iffpar Ar file
898Specifies the location of the optional IFF parameters file.This
899overrides the link
900.Pa ntpkey_iff_ Ns Ar hostname
901in the keys directory.
902.It Cm leap Ar file
903Specifies the location of the optional leapsecond file.
904This overrides the link
905.Pa ntpkey_leap
906in the keys directory.
907.It Cm mvpar Ar file
908Specifies the location of the optional MV parameters file.
909This
910overrides the link
911.Pa ntpkey_mv_ Ns Ar hostname
912in the keys directory.
913.It Cm pw Ar password
914Specifies the password to decrypt files containing private keys and
915identity parameters.
916This is required only if these files have been
917encrypted.
918.It Cm randfile Ar file
919Specifies the location of the random seed file used by the OpenSSL
920library.
921The defaults are described in the main text above.
922.It Cm sign Ar file
923Specifies the location of the optional sign key file.
924This overrides
925the link
926.Pa ntpkey_sign_ Ns Ar hostname
927in the keys directory.
928If this file is
929not found, the host key is also the sign key.
930.El
931.It Ic keys Ar keyfile
932Specifies the complete path and location of the MD5 key file
933containing the keys and key identifiers used by
934.Xr ntpd 1ntpdmdoc ,
935.Xr ntpq 1ntpqmdoc
936and
937.Xr ntpdc 1ntpdcmdoc
938when operating with symmetric key cryptography.
939This is the same operation as the
940.Fl k
941command line option.
942.It Ic keysdir Ar path
943This command specifies the default directory path for
944cryptographic keys, parameters and certificates.
945The default is
946.Pa /usr/local/etc/ .
947.It Ic requestkey Ar key
948Specifies the key identifier to use with the
949.Xr ntpdc 1ntpdcmdoc
950utility program, which uses a
951proprietary protocol specific to this implementation of
952.Xr ntpd 1ntpdmdoc .
953The
954.Ar key
955argument is a key identifier
956for the trusted key, where the value can be in the range 1 to
95765,534, inclusive.
958.It Ic revoke Ar logsec
959Specifies the interval between re-randomization of certain
960cryptographic values used by the Autokey scheme, as a power of 2 in
961seconds.
962These values need to be updated frequently in order to
963deflect brute-force attacks on the algorithms of the scheme;
964however, updating some values is a relatively expensive operation.
965The default interval is 16 (65,536 s or about 18 hours).
966For poll
967intervals above the specified interval, the values will be updated
968for every message sent.
969.It Ic trustedkey Ar key ...
970Specifies the key identifiers which are trusted for the
971purposes of authenticating peers with symmetric key cryptography,
972as well as keys used by the
973.Xr ntpq 1ntpqmdoc
974and
975.Xr ntpdc 1ntpdcmdoc
976programs.
977The authentication procedures require that both the local
978and remote servers share the same key and key identifier for this
979purpose, although different keys can be used with different
980servers.
981The
982.Ar key
983arguments are 32-bit unsigned
984integers with values from 1 to 65,534.
985.El
986.Ss Error Codes
987The following error codes are reported via the NTP control
988and monitoring protocol trap mechanism.
989.Bl -tag -width indent
990.It 101
991.Pq bad field format or length
992The packet has invalid version, length or format.
993.It 102
994.Pq bad timestamp
995The packet timestamp is the same or older than the most recent received.
996This could be due to a replay or a server clock time step.
997.It 103
998.Pq bad filestamp
999The packet filestamp is the same or older than the most recent received.
1000This could be due to a replay or a key file generation error.
1001.It 104
1002.Pq bad or missing public key
1003The public key is missing, has incorrect format or is an unsupported type.
1004.It 105
1005.Pq unsupported digest type
1006The server requires an unsupported digest/signature scheme.
1007.It 106
1008.Pq mismatched digest types
1009Not used.
1010.It 107
1011.Pq bad signature length
1012The signature length does not match the current public key.
1013.It 108
1014.Pq signature not verified
1015The message fails the signature check.
1016It could be bogus or signed by a
1017different private key.
1018.It 109
1019.Pq certificate not verified
1020The certificate is invalid or signed with the wrong key.
1021.It 110
1022.Pq certificate not verified
1023The certificate is not yet valid or has expired or the signature could not
1024be verified.
1025.It 111
1026.Pq bad or missing cookie
1027The cookie is missing, corrupted or bogus.
1028.It 112
1029.Pq bad or missing leapseconds table
1030The leapseconds table is missing, corrupted or bogus.
1031.It 113
1032.Pq bad or missing certificate
1033The certificate is missing, corrupted or bogus.
1034.It 114
1035.Pq bad or missing identity
1036The identity key is missing, corrupt or bogus.
1037.El
1038.Sh Monitoring Support
1039.Xr ntpd 1ntpdmdoc
1040includes a comprehensive monitoring facility suitable
1041for continuous, long term recording of server and client
1042timekeeping performance.
1043See the
1044.Ic statistics
1045command below
1046for a listing and example of each type of statistics currently
1047supported.
1048Statistic files are managed using file generation sets
1049and scripts in the
1050.Pa ./scripts
1051directory of this distribution.
1052Using
1053these facilities and
1054.Ux
1055.Xr cron 8
1056jobs, the data can be
1057automatically summarized and archived for retrospective analysis.
1058.Ss Monitoring Commands
1059.Bl -tag -width indent
1060.It Ic statistics Ar name ...
1061Enables writing of statistics records.
1062Currently, eight kinds of
1063.Ar name
1064statistics are supported.
1065.Bl -tag -width indent
1066.It Cm clockstats
1067Enables recording of clock driver statistics information.
1068Each update
1069received from a clock driver appends a line of the following form to
1070the file generation set named
1071.Cm clockstats :
1072.Bd -literal
107349213 525.624 127.127.4.1 93 226 00:08:29.606 D
1074.Ed
1075.Pp
1076The first two fields show the date (Modified Julian Day) and time
1077(seconds and fraction past UTC midnight).
1078The next field shows the
1079clock address in dotted-quad notation.
1080The final field shows the last
1081timecode received from the clock in decoded ASCII format, where
1082meaningful.
1083In some clock drivers a good deal of additional information
1084can be gathered and displayed as well.
1085See information specific to each
1086clock for further details.
1087.It Cm cryptostats
1088This option requires the OpenSSL cryptographic software library.
1089It
1090enables recording of cryptographic public key protocol information.
1091Each message received by the protocol module appends a line of the
1092following form to the file generation set named
1093.Cm cryptostats :
1094.Bd -literal
109549213 525.624 127.127.4.1 message
1096.Ed
1097.Pp
1098The first two fields show the date (Modified Julian Day) and time
1099(seconds and fraction past UTC midnight).
1100The next field shows the peer
1101address in dotted-quad notation, The final message field includes the
1102message type and certain ancillary information.
1103See the
1104.Sx Authentication Options
1105section for further information.
1106.It Cm loopstats
1107Enables recording of loop filter statistics information.
1108Each
1109update of the local clock outputs a line of the following form to
1110the file generation set named
1111.Cm loopstats :
1112.Bd -literal
111350935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1114.Ed
1115.Pp
1116The first two fields show the date (Modified Julian Day) and
1117time (seconds and fraction past UTC midnight).
1118The next five fields
1119show time offset (seconds), frequency offset (parts per million -
1120PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1121discipline time constant.
1122.It Cm peerstats
1123Enables recording of peer statistics information.
1124This includes
1125statistics records of all peers of a NTP server and of special
1126signals, where present and configured.
1127Each valid update appends a
1128line of the following form to the current element of a file
1129generation set named
1130.Cm peerstats :
1131.Bd -literal
113248773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
1133.Ed
1134.Pp
1135The first two fields show the date (Modified Julian Day) and
1136time (seconds and fraction past UTC midnight).
1137The next two fields
1138show the peer address in dotted-quad notation and status,
1139respectively.
1140The status field is encoded in hex in the format
1141described in Appendix A of the NTP specification RFC 1305.
1142The final four fields show the offset,
1143delay, dispersion and RMS jitter, all in seconds.
1144.It Cm rawstats
1145Enables recording of raw-timestamp statistics information.
1146This
1147includes statistics records of all peers of a NTP server and of
1148special signals, where present and configured.
1149Each NTP message
1150received from a peer or clock driver appends a line of the
1151following form to the file generation set named
1152.Cm rawstats :
1153.Bd -literal
115450928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1155.Ed
1156.Pp
1157The first two fields show the date (Modified Julian Day) and
1158time (seconds and fraction past UTC midnight).
1159The next two fields
1160show the remote peer or clock address followed by the local address
1161in dotted-quad notation.
1162The final four fields show the originate,
1163receive, transmit and final NTP timestamps in order.
1164The timestamp
1165values are as received and before processing by the various data
1166smoothing and mitigation algorithms.
1167.It Cm sysstats
1168Enables recording of ntpd statistics counters on a periodic basis.
1169Each
1170hour a line of the following form is appended to the file generation
1171set named
1172.Cm sysstats :
1173.Bd -literal
117450928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1175.Ed
1176.Pp
1177The first two fields show the date (Modified Julian Day) and time
1178(seconds and fraction past UTC midnight).
1179The remaining ten fields show
1180the statistics counter values accumulated since the last generated
1181line.
1182.Bl -tag -width indent
1183.It Time since restart Cm 36000
1184Time in hours since the system was last rebooted.
1185.It Packets received Cm 81965
1186Total number of packets received.
1187.It Packets processed Cm 0
1188Number of packets received in response to previous packets sent
1189.It Current version Cm 9546
1190Number of packets matching the current NTP version.
1191.It Previous version Cm 56
1192Number of packets matching the previous NTP version.
1193.It Bad version Cm 71793
1194Number of packets matching neither NTP version.
1195.It Access denied Cm 512
1196Number of packets denied access for any reason.
1197.It Bad length or format Cm 540
1198Number of packets with invalid length, format or port number.
1199.It Bad authentication Cm 10
1200Number of packets not verified as authentic.
1201.It Rate exceeded Cm 147
1202Number of packets discarded due to rate limitation.
1203.El
1204.It Cm statsdir Ar directory_path
1205Indicates the full path of a directory where statistics files
1206should be created (see below).
1207This keyword allows
1208the (otherwise constant)
1209.Cm filegen
1210filename prefix to be modified for file generation sets, which
1211is useful for handling statistics logs.
1212.It Cm filegen Ar name Xo
1213.Op Cm file Ar filename
1214.Op Cm type Ar typename
1215.Op Cm link | nolink
1216.Op Cm enable | disable
1217.Xc
1218Configures setting of generation file set name.
1219Generation
1220file sets provide a means for handling files that are
1221continuously growing during the lifetime of a server.
1222Server statistics are a typical example for such files.
1223Generation file sets provide access to a set of files used
1224to store the actual data.
1225At any time at most one element
1226of the set is being written to.
1227The type given specifies
1228when and how data will be directed to a new element of the set.
1229This way, information stored in elements of a file set
1230that are currently unused are available for administrational
1231operations without the risk of disturbing the operation of ntpd.
1232(Most important: they can be removed to free space for new data
1233produced.)
1234.Pp
1235Note that this command can be sent from the
1236.Xr ntpdc 1ntpdcmdoc
1237program running at a remote location.
1238.Bl -tag -width indent
1239.It Cm name
1240This is the type of the statistics records, as shown in the
1241.Cm statistics
1242command.
1243.It Cm file Ar filename
1244This is the file name for the statistics records.
1245Filenames of set
1246members are built from three concatenated elements
1247.Ar Cm prefix ,
1248.Ar Cm filename
1249and
1250.Ar Cm suffix :
1251.Bl -tag -width indent
1252.It Cm prefix
1253This is a constant filename path.
1254It is not subject to
1255modifications via the
1256.Ar filegen
1257option.
1258It is defined by the
1259server, usually specified as a compile-time constant.
1260It may,
1261however, be configurable for individual file generation sets
1262via other commands.
1263For example, the prefix used with
1264.Ar loopstats
1265and
1266.Ar peerstats
1267generation can be configured using the
1268.Ar statsdir
1269option explained above.
1270.It Cm filename
1271This string is directly concatenated to the prefix mentioned
1272above (no intervening
1273.Ql / ) .
1274This can be modified using
1275the file argument to the
1276.Ar filegen
1277statement.
1278No
1279.Pa ..
1280elements are
1281allowed in this component to prevent filenames referring to
1282parts outside the filesystem hierarchy denoted by
1283.Ar prefix .
1284.It Cm suffix
1285This part is reflects individual elements of a file set.
1286It is
1287generated according to the type of a file set.
1288.El
1289.It Cm type Ar typename
1290A file generation set is characterized by its type.
1291The following
1292types are supported:
1293.Bl -tag -width indent
1294.It Cm none
1295The file set is actually a single plain file.
1296.It Cm pid
1297One element of file set is used per incarnation of a ntpd
1298server.
1299This type does not perform any changes to file set
1300members during runtime, however it provides an easy way of
1301separating files belonging to different
1302.Xr ntpd 1ntpdmdoc
1303server incarnations.
1304The set member filename is built by appending a
1305.Ql \&.
1306to concatenated
1307.Ar prefix
1308and
1309.Ar filename
1310strings, and
1311appending the decimal representation of the process ID of the
1312.Xr ntpd 1ntpdmdoc
1313server process.
1314.It Cm day
1315One file generation set element is created per day.
1316A day is
1317defined as the period between 00:00 and 24:00 UTC.
1318The file set
1319member suffix consists of a
1320.Ql \&.
1321and a day specification in
1322the form
1323.Cm YYYYMMdd .
1324.Cm YYYY
1325is a 4-digit year number (e.g., 1992).
1326.Cm MM
1327is a two digit month number.
1328.Cm dd
1329is a two digit day number.
1330Thus, all information written at 10 December 1992 would end up
1331in a file named
1332.Ar prefix
1333.Ar filename Ns .19921210 .
1334.It Cm week
1335Any file set member contains data related to a certain week of
1336a year.
1337The term week is defined by computing day-of-year
1338modulo 7.
1339Elements of such a file generation set are
1340distinguished by appending the following suffix to the file set
1341filename base: A dot, a 4-digit year number, the letter
1342.Cm W ,
1343and a 2-digit week number.
1344For example, information from January,
134510th 1992 would end up in a file with suffix
1346.No . Ns Ar 1992W1 .
1347.It Cm month
1348One generation file set element is generated per month.
1349The
1350file name suffix consists of a dot, a 4-digit year number, and
1351a 2-digit month.
1352.It Cm year
1353One generation file element is generated per year.
1354The filename
1355suffix consists of a dot and a 4 digit year number.
1356.It Cm age
1357This type of file generation sets changes to a new element of
1358the file set every 24 hours of server operation.
1359The filename
1360suffix consists of a dot, the letter
1361.Cm a ,
1362and an 8-digit number.
1363This number is taken to be the number of seconds the server is
1364running at the start of the corresponding 24-hour period.
1365Information is only written to a file generation by specifying
1366.Cm enable ;
1367output is prevented by specifying
1368.Cm disable .
1369.El
1370.It Cm link | nolink
1371It is convenient to be able to access the current element of a file
1372generation set by a fixed name.
1373This feature is enabled by
1374specifying
1375.Cm link
1376and disabled using
1377.Cm nolink .
1378If link is specified, a
1379hard link from the current file set element to a file without
1380suffix is created.
1381When there is already a file with this name and
1382the number of links of this file is one, it is renamed appending a
1383dot, the letter
1384.Cm C ,
1385and the pid of the ntpd server process.
1386When the
1387number of links is greater than one, the file is unlinked.
1388This
1389allows the current file to be accessed by a constant name.
1390.It Cm enable \&| Cm disable
1391Enables or disables the recording function.
1392.El
1393.El
1394.El
1395.Sh Access Control Support
1396The
1397.Xr ntpd 1ntpdmdoc
1398daemon implements a general purpose address/mask based restriction
1399list.
1400The list contains address/match entries sorted first
1401by increasing address values and and then by increasing mask values.
1402A match occurs when the bitwise AND of the mask and the packet
1403source address is equal to the bitwise AND of the mask and
1404address in the list.
1405The list is searched in order with the
1406last match found defining the restriction flags associated
1407with the entry.
1408Additional information and examples can be found in the
1409.Qq Notes on Configuring NTP and Setting up a NTP Subnet
1410page
1411(available as part of the HTML documentation
1412provided in
1413.Pa /usr/share/doc/ntp ) .
1414.Pp
1415The restriction facility was implemented in conformance
1416with the access policies for the original NSFnet backbone
1417time servers.
1418Later the facility was expanded to deflect
1419cryptographic and clogging attacks.
1420While this facility may
1421be useful for keeping unwanted or broken or malicious clients
1422from congesting innocent servers, it should not be considered
1423an alternative to the NTP authentication facilities.
1424Source address based restrictions are easily circumvented
1425by a determined cracker.
1426.Pp
1427Clients can be denied service because they are explicitly
1428included in the restrict list created by the restrict command
1429or implicitly as the result of cryptographic or rate limit
1430violations.
1431Cryptographic violations include certificate
1432or identity verification failure; rate limit violations generally
1433result from defective NTP implementations that send packets
1434at abusive rates.
1435Some violations cause denied service
1436only for the offending packet, others cause denied service
1437for a timed period and others cause the denied service for
1438an indefinate period.
1439When a client or network is denied access
1440for an indefinate period, the only way at present to remove
1441the restrictions is by restarting the server.
1442.Ss The Kiss-of-Death Packet
1443Ordinarily, packets denied service are simply dropped with no
1444further action except incrementing statistics counters.
1445Sometimes a
1446more proactive response is needed, such as a server message that
1447explicitly requests the client to stop sending and leave a message
1448for the system operator.
1449A special packet format has been created
1450for this purpose called the "kiss-of-death" (KoD) packet.
1451KoD packets have the leap bits set unsynchronized and stratum set
1452to zero and the reference identifier field set to a four-byte
1453ASCII code.
1454If the
1455.Cm noserve
1456or
1457.Cm notrust
1458flag of the matching restrict list entry is set,
1459the code is "DENY"; if the
1460.Cm limited
1461flag is set and the rate limit
1462is exceeded, the code is "RATE".
1463Finally, if a cryptographic violation occurs, the code is "CRYP".
1464.Pp
1465A client receiving a KoD performs a set of sanity checks to
1466minimize security exposure, then updates the stratum and
1467reference identifier peer variables, sets the access
1468denied (TEST4) bit in the peer flash variable and sends
1469a message to the log.
1470As long as the TEST4 bit is set,
1471the client will send no further packets to the server.
1472The only way at present to recover from this condition is
1473to restart the protocol at both the client and server.
1474This
1475happens automatically at the client when the association times out.
1476It will happen at the server only if the server operator cooperates.
1477.Ss Access Control Commands
1478.Bl -tag -width indent
1479.It Xo Ic discard
1480.Op Cm average Ar avg
1481.Op Cm minimum Ar min
1482.Op Cm monitor Ar prob
1483.Xc
1484Set the parameters of the
1485.Cm limited
1486facility which protects the server from
1487client abuse.
1488The
1489.Cm average
1490subcommand specifies the minimum average packet
1491spacing, while the
1492.Cm minimum
1493subcommand specifies the minimum packet spacing.
1494Packets that violate these minima are discarded
1495and a kiss-o'-death packet returned if enabled.
1496The default
1497minimum average and minimum are 5 and 2, respectively.
1498The monitor subcommand specifies the probability of discard
1499for packets that overflow the rate-control window.
1500.It Xo Ic restrict address
1501.Op Cm mask Ar mask
1502.Op Ar flag ...
1503.Xc
1504The
1505.Ar address
1506argument expressed in
1507dotted-quad form is the address of a host or network.
1508Alternatively, the
1509.Ar address
1510argument can be a valid host DNS name.
1511The
1512.Ar mask
1513argument expressed in dotted-quad form defaults to
1514.Cm 255.255.255.255 ,
1515meaning that the
1516.Ar address
1517is treated as the address of an individual host.
1518A default entry (address
1519.Cm 0.0.0.0 ,
1520mask
1521.Cm 0.0.0.0 )
1522is always included and is always the first entry in the list.
1523Note that text string
1524.Cm default ,
1525with no mask option, may
1526be used to indicate the default entry.
1527In the current implementation,
1528.Cm flag
1529always
1530restricts access, i.e., an entry with no flags indicates that free
1531access to the server is to be given.
1532The flags are not orthogonal,
1533in that more restrictive flags will often make less restrictive
1534ones redundant.
1535The flags can generally be classed into two
1536categories, those which restrict time service and those which
1537restrict informational queries and attempts to do run-time
1538reconfiguration of the server.
1539One or more of the following flags
1540may be specified:
1541.Bl -tag -width indent
1542.It Cm ignore
1543Deny packets of all kinds, including
1544.Xr ntpq 1ntpqmdoc
1545and
1546.Xr ntpdc 1ntpdcmdoc
1547queries.
1548.It Cm kod
1549If this flag is set when an access violation occurs, a kiss-o'-death
1550(KoD) packet is sent.
1551KoD packets are rate limited to no more than one
1552per second.
1553If another KoD packet occurs within one second after the
1554last one, the packet is dropped.
1555.It Cm limited
1556Deny service if the packet spacing violates the lower limits specified
1557in the discard command.
1558A history of clients is kept using the
1559monitoring capability of
1560.Xr ntpd 1ntpdmdoc .
1561Thus, monitoring is always active as
1562long as there is a restriction entry with the
1563.Cm limited
1564flag.
1565.It Cm lowpriotrap
1566Declare traps set by matching hosts to be low priority.
1567The
1568number of traps a server can maintain is limited (the current limit
1569is 3).
1570Traps are usually assigned on a first come, first served
1571basis, with later trap requestors being denied service.
1572This flag
1573modifies the assignment algorithm by allowing low priority traps to
1574be overridden by later requests for normal priority traps.
1575.It Cm nomodify
1576Deny
1577.Xr ntpq 1ntpqmdoc
1578and
1579.Xr ntpdc 1ntpdcmdoc
1580queries which attempt to modify the state of the
1581server (i.e., run time reconfiguration).
1582Queries which return
1583information are permitted.
1584.It Cm noquery
1585Deny
1586.Xr ntpq 1ntpqmdoc
1587and
1588.Xr ntpdc 1ntpdcmdoc
1589queries.
1590Time service is not affected.
1591.It Cm nopeer
1592Deny packets which would result in mobilizing a new association.
1593This
1594includes broadcast and symmetric active packets when a configured
1595association does not exist.
1596It also includes
1597.Cm pool
1598associations, so if you want to use servers from a
1599.Cm pool
1600directive and also want to use
1601.Cm nopeer
1602by default, you'll want a
1603.Cm "restrict source ..." line as well that does
1604.It not
1605include the
1606.Cm nopeer
1607directive.
1608.It Cm noserve
1609Deny all packets except
1610.Xr ntpq 1ntpqmdoc
1611and
1612.Xr ntpdc 1ntpdcmdoc
1613queries.
1614.It Cm notrap
1615Decline to provide mode 6 control message trap service to matching
1616hosts.
1617The trap service is a subsystem of the ntpdq control message
1618protocol which is intended for use by remote event logging programs.
1619.It Cm notrust
1620Deny service unless the packet is cryptographically authenticated.
1621.It Cm ntpport
1622This is actually a match algorithm modifier, rather than a
1623restriction flag.
1624Its presence causes the restriction entry to be
1625matched only if the source port in the packet is the standard NTP
1626UDP port (123).
1627Both
1628.Cm ntpport
1629and
1630.Cm non-ntpport
1631may
1632be specified.
1633The
1634.Cm ntpport
1635is considered more specific and
1636is sorted later in the list.
1637.It Cm version
1638Deny packets that do not match the current NTP version.
1639.El
1640.Pp
1641Default restriction list entries with the flags ignore, interface,
1642ntpport, for each of the local host's interface addresses are
1643inserted into the table at startup to prevent the server
1644from attempting to synchronize to its own time.
1645A default entry is also always present, though if it is
1646otherwise unconfigured; no flags are associated
1647with the default entry (i.e., everything besides your own
1648NTP server is unrestricted).
1649.El
1650.Sh Automatic NTP Configuration Options
1651.Ss Manycasting
1652Manycasting is a automatic discovery and configuration paradigm
1653new to NTPv4.
1654It is intended as a means for a multicast client
1655to troll the nearby network neighborhood to find cooperating
1656manycast servers, validate them using cryptographic means
1657and evaluate their time values with respect to other servers
1658that might be lurking in the vicinity.
1659The intended result is that each manycast client mobilizes
1660client associations with some number of the "best"
1661of the nearby manycast servers, yet automatically reconfigures
1662to sustain this number of servers should one or another fail.
1663.Pp
1664Note that the manycasting paradigm does not coincide
1665with the anycast paradigm described in RFC-1546,
1666which is designed to find a single server from a clique
1667of servers providing the same service.
1668The manycast paradigm is designed to find a plurality
1669of redundant servers satisfying defined optimality criteria.
1670.Pp
1671Manycasting can be used with either symmetric key
1672or public key cryptography.
1673The public key infrastructure (PKI)
1674offers the best protection against compromised keys
1675and is generally considered stronger, at least with relatively
1676large key sizes.
1677It is implemented using the Autokey protocol and
1678the OpenSSL cryptographic library available from
1679.Li http://www.openssl.org/ .
1680The library can also be used with other NTPv4 modes
1681as well and is highly recommended, especially for broadcast modes.
1682.Pp
1683A persistent manycast client association is configured
1684using the manycastclient command, which is similar to the
1685server command but with a multicast (IPv4 class
1686.Cm D
1687or IPv6 prefix
1688.Cm FF )
1689group address.
1690The IANA has designated IPv4 address 224.1.1.1
1691and IPv6 address FF05::101 (site local) for NTP.
1692When more servers are needed, it broadcasts manycast
1693client messages to this address at the minimum feasible rate
1694and minimum feasible time-to-live (TTL) hops, depending
1695on how many servers have already been found.
1696There can be as many manycast client associations
1697as different group address, each one serving as a template
1698for a future ephemeral unicast client/server association.
1699.Pp
1700Manycast servers configured with the
1701.Ic manycastserver
1702command listen on the specified group address for manycast
1703client messages.
1704Note the distinction between manycast client,
1705which actively broadcasts messages, and manycast server,
1706which passively responds to them.
1707If a manycast server is
1708in scope of the current TTL and is itself synchronized
1709to a valid source and operating at a stratum level equal
1710to or lower than the manycast client, it replies to the
1711manycast client message with an ordinary unicast server message.
1712.Pp
1713The manycast client receiving this message mobilizes
1714an ephemeral client/server association according to the
1715matching manycast client template, but only if cryptographically
1716authenticated and the server stratum is less than or equal
1717to the client stratum.
1718Authentication is explicitly required
1719and either symmetric key or public key (Autokey) can be used.
1720Then, the client polls the server at its unicast address
1721in burst mode in order to reliably set the host clock
1722and validate the source.
1723This normally results
1724in a volley of eight client/server at 2-s intervals
1725during which both the synchronization and cryptographic
1726protocols run concurrently.
1727Following the volley,
1728the client runs the NTP intersection and clustering
1729algorithms, which act to discard all but the "best"
1730associations according to stratum and synchronization
1731distance.
1732The surviving associations then continue
1733in ordinary client/server mode.
1734.Pp
1735The manycast client polling strategy is designed to reduce
1736as much as possible the volume of manycast client messages
1737and the effects of implosion due to near-simultaneous
1738arrival of manycast server messages.
1739The strategy is determined by the
1740.Ic manycastclient ,
1741.Ic tos
1742and
1743.Ic ttl
1744configuration commands.
1745The manycast poll interval is
1746normally eight times the system poll interval,
1747which starts out at the
1748.Cm minpoll
1749value specified in the
1750.Ic manycastclient ,
1751command and, under normal circumstances, increments to the
1752.Cm maxpolll
1753value specified in this command.
1754Initially, the TTL is
1755set at the minimum hops specified by the ttl command.
1756At each retransmission the TTL is increased until reaching
1757the maximum hops specified by this command or a sufficient
1758number client associations have been found.
1759Further retransmissions use the same TTL.
1760.Pp
1761The quality and reliability of the suite of associations
1762discovered by the manycast client is determined by the NTP
1763mitigation algorithms and the
1764.Cm minclock
1765and
1766.Cm minsane
1767values specified in the
1768.Ic tos
1769configuration command.
1770At least
1771.Cm minsane
1772candidate servers must be available and the mitigation
1773algorithms produce at least
1774.Cm minclock
1775survivors in order to synchronize the clock.
1776Byzantine agreement principles require at least four
1777candidates in order to correctly discard a single falseticker.
1778For legacy purposes,
1779.Cm minsane
1780defaults to 1 and
1781.Cm minclock
1782defaults to 3.
1783For manycast service
1784.Cm minsane
1785should be explicitly set to 4, assuming at least that
1786number of servers are available.
1787.Pp
1788If at least
1789.Cm minclock
1790servers are found, the manycast poll interval is immediately
1791set to eight times
1792.Cm maxpoll .
1793If less than
1794.Cm minclock
1795servers are found when the TTL has reached the maximum hops,
1796the manycast poll interval is doubled.
1797For each transmission
1798after that, the poll interval is doubled again until
1799reaching the maximum of eight times
1800.Cm maxpoll .
1801Further transmissions use the same poll interval and
1802TTL values.
1803Note that while all this is going on,
1804each client/server association found is operating normally
1805it the system poll interval.
1806.Pp
1807Administratively scoped multicast boundaries are normally
1808specified by the network router configuration and,
1809in the case of IPv6, the link/site scope prefix.
1810By default, the increment for TTL hops is 32 starting
1811from 31; however, the
1812.Ic ttl
1813configuration command can be
1814used to modify the values to match the scope rules.
1815.Pp
1816It is often useful to narrow the range of acceptable
1817servers which can be found by manycast client associations.
1818Because manycast servers respond only when the client
1819stratum is equal to or greater than the server stratum,
1820primary (stratum 1) servers fill find only primary servers
1821in TTL range, which is probably the most common objective.
1822However, unless configured otherwise, all manycast clients
1823in TTL range will eventually find all primary servers
1824in TTL range, which is probably not the most common
1825objective in large networks.
1826The
1827.Ic tos
1828command can be used to modify this behavior.
1829Servers with stratum below
1830.Cm floor
1831or above
1832.Cm ceiling
1833specified in the
1834.Ic tos
1835command are strongly discouraged during the selection
1836process; however, these servers may be temporally
1837accepted if the number of servers within TTL range is
1838less than
1839.Cm minclock .
1840.Pp
1841The above actions occur for each manycast client message,
1842which repeats at the designated poll interval.
1843However, once the ephemeral client association is mobilized,
1844subsequent manycast server replies are discarded,
1845since that would result in a duplicate association.
1846If during a poll interval the number of client associations
1847falls below
1848.Cm minclock ,
1849all manycast client prototype associations are reset
1850to the initial poll interval and TTL hops and operation
1851resumes from the beginning.
1852It is important to avoid
1853frequent manycast client messages, since each one requires
1854all manycast servers in TTL range to respond.
1855The result could well be an implosion, either minor or major,
1856depending on the number of servers in range.
1857The recommended value for
1858.Cm maxpoll
1859is 12 (4,096 s).
1860.Pp
1861It is possible and frequently useful to configure a host
1862as both manycast client and manycast server.
1863A number of hosts configured this way and sharing a common
1864group address will automatically organize themselves
1865in an optimum configuration based on stratum and
1866synchronization distance.
1867For example, consider an NTP
1868subnet of two primary servers and a hundred or more
1869dependent clients.
1870With two exceptions, all servers
1871and clients have identical configuration files including both
1872.Ic multicastclient
1873and
1874.Ic multicastserver
1875commands using, for instance, multicast group address
1876239.1.1.1.
1877The only exception is that each primary server
1878configuration file must include commands for the primary
1879reference source such as a GPS receiver.
1880.Pp
1881The remaining configuration files for all secondary
1882servers and clients have the same contents, except for the
1883.Ic tos
1884command, which is specific for each stratum level.
1885For stratum 1 and stratum 2 servers, that command is
1886not necessary.
1887For stratum 3 and above servers the
1888.Cm floor
1889value is set to the intended stratum number.
1890Thus, all stratum 3 configuration files are identical,
1891all stratum 4 files are identical and so forth.
1892.Pp
1893Once operations have stabilized in this scenario,
1894the primary servers will find the primary reference source
1895and each other, since they both operate at the same
1896stratum (1), but not with any secondary server or client,
1897since these operate at a higher stratum.
1898The secondary
1899servers will find the servers at the same stratum level.
1900If one of the primary servers loses its GPS receiver,
1901it will continue to operate as a client and other clients
1902will time out the corresponding association and
1903re-associate accordingly.
1904.Pp
1905Some administrators prefer to avoid running
1906.Xr ntpd 1ntpdmdoc
1907continuously and run either
1908.Xr sntp 1sntpmdoc
1909or
1910.Xr ntpd 1ntpdmdoc
1911.Fl q
1912as a cron job.
1913In either case the servers must be
1914configured in advance and the program fails if none are
1915available when the cron job runs.
1916A really slick
1917application of manycast is with
1918.Xr ntpd 1ntpdmdoc
1919.Fl q .
1920The program wakes up, scans the local landscape looking
1921for the usual suspects, selects the best from among
1922the rascals, sets the clock and then departs.
1923Servers do not have to be configured in advance and
1924all clients throughout the network can have the same
1925configuration file.
1926.Ss Manycast Interactions with Autokey
1927Each time a manycast client sends a client mode packet
1928to a multicast group address, all manycast servers
1929in scope generate a reply including the host name
1930and status word.
1931The manycast clients then run
1932the Autokey protocol, which collects and verifies
1933all certificates involved.
1934Following the burst interval
1935all but three survivors are cast off,
1936but the certificates remain in the local cache.
1937It often happens that several complete signing trails
1938from the client to the primary servers are collected in this way.
1939.Pp
1940About once an hour or less often if the poll interval
1941exceeds this, the client regenerates the Autokey key list.
1942This is in general transparent in client/server mode.
1943However, about once per day the server private value
1944used to generate cookies is refreshed along with all
1945manycast client associations.
1946In this case all
1947cryptographic values including certificates is refreshed.
1948If a new certificate has been generated since
1949the last refresh epoch, it will automatically revoke
1950all prior certificates that happen to be in the
1951certificate cache.
1952At the same time, the manycast
1953scheme starts all over from the beginning and
1954the expanding ring shrinks to the minimum and increments
1955from there while collecting all servers in scope.
1956.Ss Manycast Options
1957.Bl -tag -width indent
1958.It Xo Ic tos
1959.Oo
1960.Cm ceiling Ar ceiling |
1961.Cm cohort { 0 | 1 } |
1962.Cm floor Ar floor |
1963.Cm minclock Ar minclock |
1964.Cm minsane Ar minsane
1965.Oc
1966.Xc
1967This command affects the clock selection and clustering
1968algorithms.
1969It can be used to select the quality and
1970quantity of peers used to synchronize the system clock
1971and is most useful in manycast mode.
1972The variables operate
1973as follows:
1974.Bl -tag -width indent
1975.It Cm ceiling Ar ceiling
1976Peers with strata above
1977.Cm ceiling
1978will be discarded if there are at least
1979.Cm minclock
1980peers remaining.
1981This value defaults to 15, but can be changed
1982to any number from 1 to 15.
1983.It Cm cohort Bro 0 | 1 Brc
1984This is a binary flag which enables (0) or disables (1)
1985manycast server replies to manycast clients with the same
1986stratum level.
1987This is useful to reduce implosions where
1988large numbers of clients with the same stratum level
1989are present.
1990The default is to enable these replies.
1991.It Cm floor Ar floor
1992Peers with strata below
1993.Cm floor
1994will be discarded if there are at least
1995.Cm minclock
1996peers remaining.
1997This value defaults to 1, but can be changed
1998to any number from 1 to 15.
1999.It Cm minclock Ar minclock
2000The clustering algorithm repeatedly casts out outlier
2001associations until no more than
2002.Cm minclock
2003associations remain.
2004This value defaults to 3,
2005but can be changed to any number from 1 to the number of
2006configured sources.
2007.It Cm minsane Ar minsane
2008This is the minimum number of candidates available
2009to the clock selection algorithm in order to produce
2010one or more truechimers for the clustering algorithm.
2011If fewer than this number are available, the clock is
2012undisciplined and allowed to run free.
2013The default is 1
2014for legacy purposes.
2015However, according to principles of
2016Byzantine agreement,
2017.Cm minsane
2018should be at least 4 in order to detect and discard
2019a single falseticker.
2020.El
2021.It Cm ttl Ar hop ...
2022This command specifies a list of TTL values in increasing
2023order, up to 8 values can be specified.
2024In manycast mode these values are used in turn
2025in an expanding-ring search.
2026The default is eight
2027multiples of 32 starting at 31.
2028.El
2029.Sh Reference Clock Support
2030The NTP Version 4 daemon supports some three dozen different radio,
2031satellite and modem reference clocks plus a special pseudo-clock
2032used for backup or when no other clock source is available.
2033Detailed descriptions of individual device drivers and options can
2034be found in the
2035.Qq Reference Clock Drivers
2036page
2037(available as part of the HTML documentation
2038provided in
2039.Pa /usr/share/doc/ntp ) .
2040Additional information can be found in the pages linked
2041there, including the
2042.Qq Debugging Hints for Reference Clock Drivers
2043and
2044.Qq How To Write a Reference Clock Driver
2045pages
2046(available as part of the HTML documentation
2047provided in
2048.Pa /usr/share/doc/ntp ) .
2049In addition, support for a PPS
2050signal is available as described in the
2051.Qq Pulse-per-second (PPS) Signal Interfacing
2052page
2053(available as part of the HTML documentation
2054provided in
2055.Pa /usr/share/doc/ntp ) .
2056Many
2057drivers support special line discipline/streams modules which can
2058significantly improve the accuracy using the driver.
2059These are
2060described in the
2061.Qq Line Disciplines and Streams Drivers
2062page
2063(available as part of the HTML documentation
2064provided in
2065.Pa /usr/share/doc/ntp ) .
2066.Pp
2067A reference clock will generally (though not always) be a radio
2068timecode receiver which is synchronized to a source of standard
2069time such as the services offered by the NRC in Canada and NIST and
2070USNO in the US.
2071The interface between the computer and the timecode
2072receiver is device dependent, but is usually a serial port.
2073A
2074device driver specific to each reference clock must be selected and
2075compiled in the distribution; however, most common radio, satellite
2076and modem clocks are included by default.
2077Note that an attempt to
2078configure a reference clock when the driver has not been compiled
2079or the hardware port has not been appropriately configured results
2080in a scalding remark to the system log file, but is otherwise non
2081hazardous.
2082.Pp
2083For the purposes of configuration,
2084.Xr ntpd 1ntpdmdoc
2085treats
2086reference clocks in a manner analogous to normal NTP peers as much
2087as possible.
2088Reference clocks are identified by a syntactically
2089correct but invalid IP address, in order to distinguish them from
2090normal NTP peers.
2091Reference clock addresses are of the form
2092.Sm off
2093.Li 127.127. Ar t . Ar u ,
2094.Sm on
2095where
2096.Ar t
2097is an integer
2098denoting the clock type and
2099.Ar u
2100indicates the unit
2101number in the range 0-3.
2102While it may seem overkill, it is in fact
2103sometimes useful to configure multiple reference clocks of the same
2104type, in which case the unit numbers must be unique.
2105.Pp
2106The
2107.Ic server
2108command is used to configure a reference
2109clock, where the
2110.Ar address
2111argument in that command
2112is the clock address.
2113The
2114.Cm key ,
2115.Cm version
2116and
2117.Cm ttl
2118options are not used for reference clock support.
2119The
2120.Cm mode
2121option is added for reference clock support, as
2122described below.
2123The
2124.Cm prefer
2125option can be useful to
2126persuade the server to cherish a reference clock with somewhat more
2127enthusiasm than other reference clocks or peers.
2128Further
2129information on this option can be found in the
2130.Qq Mitigation Rules and the prefer Keyword
2131(available as part of the HTML documentation
2132provided in
2133.Pa /usr/share/doc/ntp )
2134page.
2135The
2136.Cm minpoll
2137and
2138.Cm maxpoll
2139options have
2140meaning only for selected clock drivers.
2141See the individual clock
2142driver document pages for additional information.
2143.Pp
2144The
2145.Ic fudge
2146command is used to provide additional
2147information for individual clock drivers and normally follows
2148immediately after the
2149.Ic server
2150command.
2151The
2152.Ar address
2153argument specifies the clock address.
2154The
2155.Cm refid
2156and
2157.Cm stratum
2158options can be used to
2159override the defaults for the device.
2160There are two optional
2161device-dependent time offsets and four flags that can be included
2162in the
2163.Ic fudge
2164command as well.
2165.Pp
2166The stratum number of a reference clock is by default zero.
2167Since the
2168.Xr ntpd 1ntpdmdoc
2169daemon adds one to the stratum of each
2170peer, a primary server ordinarily displays an external stratum of
2171one.
2172In order to provide engineered backups, it is often useful to
2173specify the reference clock stratum as greater than zero.
2174The
2175.Cm stratum
2176option is used for this purpose.
2177Also, in cases
2178involving both a reference clock and a pulse-per-second (PPS)
2179discipline signal, it is useful to specify the reference clock
2180identifier as other than the default, depending on the driver.
2181The
2182.Cm refid
2183option is used for this purpose.
2184Except where noted,
2185these options apply to all clock drivers.
2186.Ss Reference Clock Commands
2187.Bl -tag -width indent
2188.It Xo Ic server
2189.Sm off
2190.Li 127.127. Ar t . Ar u
2191.Sm on
2192.Op Cm prefer
2193.Op Cm mode Ar int
2194.Op Cm minpoll Ar int
2195.Op Cm maxpoll Ar int
2196.Xc
2197This command can be used to configure reference clocks in
2198special ways.
2199The options are interpreted as follows:
2200.Bl -tag -width indent
2201.It Cm prefer
2202Marks the reference clock as preferred.
2203All other things being
2204equal, this host will be chosen for synchronization among a set of
2205correctly operating hosts.
2206See the
2207.Qq Mitigation Rules and the prefer Keyword
2208page
2209(available as part of the HTML documentation
2210provided in
2211.Pa /usr/share/doc/ntp )
2212for further information.
2213.It Cm mode Ar int
2214Specifies a mode number which is interpreted in a
2215device-specific fashion.
2216For instance, it selects a dialing
2217protocol in the ACTS driver and a device subtype in the
2218parse
2219drivers.
2220.It Cm minpoll Ar int
2221.It Cm maxpoll Ar int
2222These options specify the minimum and maximum polling interval
2223for reference clock messages, as a power of 2 in seconds
2224For
2225most directly connected reference clocks, both
2226.Cm minpoll
2227and
2228.Cm maxpoll
2229default to 6 (64 s).
2230For modem reference clocks,
2231.Cm minpoll
2232defaults to 10 (17.1 m) and
2233.Cm maxpoll
2234defaults to 14 (4.5 h).
2235The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2236.El
2237.It Xo Ic fudge
2238.Sm off
2239.Li 127.127. Ar t . Ar u
2240.Sm on
2241.Op Cm time1 Ar sec
2242.Op Cm time2 Ar sec
2243.Op Cm stratum Ar int
2244.Op Cm refid Ar string
2245.Op Cm mode Ar int
2246.Op Cm flag1 Cm 0 \&| Cm 1
2247.Op Cm flag2 Cm 0 \&| Cm 1
2248.Op Cm flag3 Cm 0 \&| Cm 1
2249.Op Cm flag4 Cm 0 \&| Cm 1
2250.Xc
2251This command can be used to configure reference clocks in
2252special ways.
2253It must immediately follow the
2254.Ic server
2255command which configures the driver.
2256Note that the same capability
2257is possible at run time using the
2258.Xr ntpdc 1ntpdcmdoc
2259program.
2260The options are interpreted as
2261follows:
2262.Bl -tag -width indent
2263.It Cm time1 Ar sec
2264Specifies a constant to be added to the time offset produced by
2265the driver, a fixed-point decimal number in seconds.
2266This is used
2267as a calibration constant to adjust the nominal time offset of a
2268particular clock to agree with an external standard, such as a
2269precision PPS signal.
2270It also provides a way to correct a
2271systematic error or bias due to serial port or operating system
2272latencies, different cable lengths or receiver internal delay.
2273The
2274specified offset is in addition to the propagation delay provided
2275by other means, such as internal DIPswitches.
2276Where a calibration
2277for an individual system and driver is available, an approximate
2278correction is noted in the driver documentation pages.
2279Note: in order to facilitate calibration when more than one
2280radio clock or PPS signal is supported, a special calibration
2281feature is available.
2282It takes the form of an argument to the
2283.Ic enable
2284command described in
2285.Sx Miscellaneous Options
2286page and operates as described in the
2287.Qq Reference Clock Drivers
2288page
2289(available as part of the HTML documentation
2290provided in
2291.Pa /usr/share/doc/ntp ) .
2292.It Cm time2 Ar secs
2293Specifies a fixed-point decimal number in seconds, which is
2294interpreted in a driver-dependent way.
2295See the descriptions of
2296specific drivers in the
2297.Qq Reference Clock Drivers
2298page
2299(available as part of the HTML documentation
2300provided in
2301.Pa /usr/share/doc/ntp ) .
2302.It Cm stratum Ar int
2303Specifies the stratum number assigned to the driver, an integer
2304between 0 and 15.
2305This number overrides the default stratum number
2306ordinarily assigned by the driver itself, usually zero.
2307.It Cm refid Ar string
2308Specifies an ASCII string of from one to four characters which
2309defines the reference identifier used by the driver.
2310This string
2311overrides the default identifier ordinarily assigned by the driver
2312itself.
2313.It Cm mode Ar int
2314Specifies a mode number which is interpreted in a
2315device-specific fashion.
2316For instance, it selects a dialing
2317protocol in the ACTS driver and a device subtype in the
2318parse
2319drivers.
2320.It Cm flag1 Cm 0 \&| Cm 1
2321.It Cm flag2 Cm 0 \&| Cm 1
2322.It Cm flag3 Cm 0 \&| Cm 1
2323.It Cm flag4 Cm 0 \&| Cm 1
2324These four flags are used for customizing the clock driver.
2325The
2326interpretation of these values, and whether they are used at all,
2327is a function of the particular clock driver.
2328However, by
2329convention
2330.Cm flag4
2331is used to enable recording monitoring
2332data to the
2333.Cm clockstats
2334file configured with the
2335.Ic filegen
2336command.
2337Further information on the
2338.Ic filegen
2339command can be found in
2340.Sx Monitoring Options .
2341.El
2342.El
2343.Sh Miscellaneous Options
2344.Bl -tag -width indent
2345.It Ic broadcastdelay Ar seconds
2346The broadcast and multicast modes require a special calibration
2347to determine the network delay between the local and remote
2348servers.
2349Ordinarily, this is done automatically by the initial
2350protocol exchanges between the client and server.
2351In some cases,
2352the calibration procedure may fail due to network or server access
2353controls, for example.
2354This command specifies the default delay to
2355be used under these circumstances.
2356Typically (for Ethernet), a
2357number between 0.003 and 0.007 seconds is appropriate.
2358The default
2359when this command is not used is 0.004 seconds.
2360.It Ic calldelay Ar delay
2361This option controls the delay in seconds between the first and second
2362packets sent in burst or iburst mode to allow additional time for a modem
2363or ISDN call to complete.
2364.It Ic driftfile Ar driftfile
2365This command specifies the complete path and name of the file used to
2366record the frequency of the local clock oscillator.
2367This is the same
2368operation as the
2369.Fl f
2370command line option.
2371If the file exists, it is read at
2372startup in order to set the initial frequency and then updated once per
2373hour with the current frequency computed by the daemon.
2374If the file name is
2375specified, but the file itself does not exist, the starts with an initial
2376frequency of zero and creates the file when writing it for the first time.
2377If this command is not given, the daemon will always start with an initial
2378frequency of zero.
2379.Pp
2380The file format consists of a single line containing a single
2381floating point number, which records the frequency offset measured
2382in parts-per-million (PPM).
2383The file is updated by first writing
2384the current drift value into a temporary file and then renaming
2385this file to replace the old version.
2386This implies that
2387.Xr ntpd 1ntpdmdoc
2388must have write permission for the directory the
2389drift file is located in, and that file system links, symbolic or
2390otherwise, should be avoided.
2391.It Ic dscp Ar value
2392This option specifies the Differentiated Services Control Point (DSCP) value,
2393a 6-bit code.  The default value is 46, signifying Expedited Forwarding.
2394.It Xo Ic enable
2395.Oo
2396.Cm auth | Cm bclient |
2397.Cm calibrate | Cm kernel |
2398.Cm mode7 | monitor |
2399.Cm ntp | Cm stats
2400.Oc
2401.Xc
2402.It Xo Ic disable
2403.Oo
2404.Cm auth | Cm bclient |
2405.Cm calibrate | Cm kernel |
2406.Cm mode7 | monitor |
2407.Cm ntp | Cm stats
2408.Oc
2409.Xc
2410Provides a way to enable or disable various server options.
2411Flags not mentioned are unaffected.
2412Note that all of these flags
2413can be controlled remotely using the
2414.Xr ntpdc 1ntpdcmdoc
2415utility program.
2416.Bl -tag -width indent
2417.It Cm auth
2418Enables the server to synchronize with unconfigured peers only if the
2419peer has been correctly authenticated using either public key or
2420private key cryptography.
2421The default for this flag is
2422.Ic enable .
2423.It Cm bclient
2424Enables the server to listen for a message from a broadcast or
2425multicast server, as in the
2426.Ic multicastclient
2427command with default
2428address.
2429The default for this flag is
2430.Ic disable .
2431.It Cm calibrate
2432Enables the calibrate feature for reference clocks.
2433The default for
2434this flag is
2435.Ic disable .
2436.It Cm kernel
2437Enables the kernel time discipline, if available.
2438The default for this
2439flag is
2440.Ic enable
2441if support is available, otherwise
2442.Ic disable .
2443.It Cm mode7
2444Enables processing of NTP mode 7 implementation-specific requests
2445which are used by the deprecated
2446.Xr ntpdc 1ntpdcmdoc
2447program.
2448The default for this flag is disable.
2449This flag is excluded from runtime configuration using
2450.Xr ntpq 1ntpqmdoc .
2451The
2452.Xr ntpq 1ntpqmdoc
2453program provides the same capabilities as
2454.Xr ntpdc 1ntpdcmdoc
2455using standard mode 6 requests.
2456.It Cm monitor
2457Enables the monitoring facility.
2458See the
2459.Xr ntpdc 1ntpdcmdoc
2460program
2461and the
2462.Ic monlist
2463command or further information.
2464The
2465default for this flag is
2466.Ic enable .
2467.It Cm ntp
2468Enables time and frequency discipline.
2469In effect, this switch opens and
2470closes the feedback loop, which is useful for testing.
2471The default for
2472this flag is
2473.Ic enable .
2474.It Cm stats
2475Enables the statistics facility.
2476See the
2477.Sx Monitoring Options
2478section for further information.
2479The default for this flag is
2480.Ic disable .
2481.El
2482.It Ic includefile Ar includefile
2483This command allows additional configuration commands
2484to be included from a separate file.
2485Include files may
2486be nested to a depth of five; upon reaching the end of any
2487include file, command processing resumes in the previous
2488configuration file.
2489This option is useful for sites that run
2490.Xr ntpd 1ntpdmdoc
2491on multiple hosts, with (mostly) common options (e.g., a
2492restriction list).
2493.It Ic leapsmearinterval Ar seconds
2494This EXPERIMENTAL option is only available if
2495.Xr ntpd 1ntpdmdoc
2496was built with the
2497.Cm --enable-leap-smear
2498option to the
2499.Cm configure
2500script.
2501It specifies the interval over which a leap second correction will be applied.
2502Recommended values for this option are between
25037200 (2 hours) and 86400 (24 hours).
2504.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS!
2505See http://bugs.ntp.org/2855 for more information.
2506.It Ic logconfig Ar configkeyword
2507This command controls the amount and type of output written to
2508the system
2509.Xr syslog 3
2510facility or the alternate
2511.Ic logfile
2512log file.
2513By default, all output is turned on.
2514All
2515.Ar configkeyword
2516keywords can be prefixed with
2517.Ql = ,
2518.Ql +
2519and
2520.Ql - ,
2521where
2522.Ql =
2523sets the
2524.Xr syslog 3
2525priority mask,
2526.Ql +
2527adds and
2528.Ql -
2529removes
2530messages.
2531.Xr syslog 3
2532messages can be controlled in four
2533classes
2534.Po
2535.Cm clock ,
2536.Cm peer ,
2537.Cm sys
2538and
2539.Cm sync
2540.Pc .
2541Within these classes four types of messages can be
2542controlled: informational messages
2543.Po
2544.Cm info
2545.Pc ,
2546event messages
2547.Po
2548.Cm events
2549.Pc ,
2550statistics messages
2551.Po
2552.Cm statistics
2553.Pc
2554and
2555status messages
2556.Po
2557.Cm status
2558.Pc .
2559.Pp
2560Configuration keywords are formed by concatenating the message class with
2561the event class.
2562The
2563.Cm all
2564prefix can be used instead of a message class.
2565A
2566message class may also be followed by the
2567.Cm all
2568keyword to enable/disable all
2569messages of the respective message class.Thus, a minimal log configuration
2570could look like this:
2571.Bd -literal
2572logconfig =syncstatus +sysevents
2573.Ed
2574.Pp
2575This would just list the synchronizations state of
2576.Xr ntpd 1ntpdmdoc
2577and the major system events.
2578For a simple reference server, the
2579following minimum message configuration could be useful:
2580.Bd -literal
2581logconfig =syncall +clockall
2582.Ed
2583.Pp
2584This configuration will list all clock information and
2585synchronization information.
2586All other events and messages about
2587peers, system events and so on is suppressed.
2588.It Ic logfile Ar logfile
2589This command specifies the location of an alternate log file to
2590be used instead of the default system
2591.Xr syslog 3
2592facility.
2593This is the same operation as the -l command line option.
2594.It Ic setvar Ar variable Op Cm default
2595This command adds an additional system variable.
2596These
2597variables can be used to distribute additional information such as
2598the access policy.
2599If the variable of the form
2600.Sm off
2601.Va name = Ar value
2602.Sm on
2603is followed by the
2604.Cm default
2605keyword, the
2606variable will be listed as part of the default system variables
2607.Po
2608.Xr ntpq 1ntpqmdoc
2609.Ic rv
2610command
2611.Pc ) .
2612These additional variables serve
2613informational purposes only.
2614They are not related to the protocol
2615other that they can be listed.
2616The known protocol variables will
2617always override any variables defined via the
2618.Ic setvar
2619mechanism.
2620There are three special variables that contain the names
2621of all variable of the same group.
2622The
2623.Va sys_var_list
2624holds
2625the names of all system variables.
2626The
2627.Va peer_var_list
2628holds
2629the names of all peer variables and the
2630.Va clock_var_list
2631holds the names of the reference clock variables.
2632.It Xo Ic tinker
2633.Oo
2634.Cm allan Ar allan |
2635.Cm dispersion Ar dispersion |
2636.Cm freq Ar freq |
2637.Cm huffpuff Ar huffpuff |
2638.Cm panic Ar panic |
2639.Cm step Ar step |
2640.Cm stepback Ar stepback |
2641.Cm stepfwd Ar stepfwd |
2642.Cm stepout Ar stepout
2643.Oc
2644.Xc
2645This command can be used to alter several system variables in
2646very exceptional circumstances.
2647It should occur in the
2648configuration file before any other configuration options.
2649The
2650default values of these variables have been carefully optimized for
2651a wide range of network speeds and reliability expectations.
2652In
2653general, they interact in intricate ways that are hard to predict
2654and some combinations can result in some very nasty behavior.
2655Very
2656rarely is it necessary to change the default values; but, some
2657folks cannot resist twisting the knobs anyway and this command is
2658for them.
2659Emphasis added: twisters are on their own and can expect
2660no help from the support group.
2661.Pp
2662The variables operate as follows:
2663.Bl -tag -width indent
2664.It Cm allan Ar allan
2665The argument becomes the new value for the minimum Allan
2666intercept, which is a parameter of the PLL/FLL clock discipline
2667algorithm.
2668The value in log2 seconds defaults to 7 (1024 s), which is also the lower
2669limit.
2670.It Cm dispersion Ar dispersion
2671The argument becomes the new value for the dispersion increase rate,
2672normally .000015 s/s.
2673.It Cm freq Ar freq
2674The argument becomes the initial value of the frequency offset in
2675parts-per-million.
2676This overrides the value in the frequency file, if
2677present, and avoids the initial training state if it is not.
2678.It Cm huffpuff Ar huffpuff
2679The argument becomes the new value for the experimental
2680huff-n'-puff filter span, which determines the most recent interval
2681the algorithm will search for a minimum delay.
2682The lower limit is
2683900 s (15 m), but a more reasonable value is 7200 (2 hours).
2684There
2685is no default, since the filter is not enabled unless this command
2686is given.
2687.It Cm panic Ar panic
2688The argument is the panic threshold, normally 1000 s.
2689If set to zero,
2690the panic sanity check is disabled and a clock offset of any value will
2691be accepted.
2692.It Cm step Ar step
2693The argument is the step threshold, which by default is 0.128 s.
2694It can
2695be set to any positive number in seconds.
2696If set to zero, step
2697adjustments will never occur.
2698Note: The kernel time discipline is
2699disabled if the step threshold is set to zero or greater than the
2700default.
2701.It Cm stepback Ar stepback
2702The argument is the step threshold for the backward direction,
2703which by default is 0.128 s.
2704It can
2705be set to any positive number in seconds.
2706If both the forward and backward step thresholds are set to zero, step
2707adjustments will never occur.
2708Note: The kernel time discipline is
2709disabled if
2710each direction of step threshold are either
2711set to zero or greater than .5 second.
2712.It Cm stepfwd Ar stepfwd
2713As for stepback, but for the forward direction.
2714.It Cm stepout Ar stepout
2715The argument is the stepout timeout, which by default is 900 s.
2716It can
2717be set to any positive number in seconds.
2718If set to zero, the stepout
2719pulses will not be suppressed.
2720.El
2721.It Xo Ic rlimit
2722.Oo
2723.Cm memlock Ar Nmegabytes |
2724.Cm stacksize Ar N4kPages
2725.Cm filenum Ar Nfiledescriptors
2726.Oc
2727.Xc
2728.Bl -tag -width indent
2729.It Cm memlock Ar Nmegabytes
2730Specify the number of megabytes of memory that should be
2731allocated and locked.
2732Probably only available under Linux, this option may be useful
2733when dropping root (the
2734.Fl i
2735option).
2736The default is 32 megabytes on non-Linux machines, and -1 under Linux.
2737-1 means "do not lock the process into memory".
27380 means "lock whatever memory the process wants into memory".
2739.It Cm stacksize Ar N4kPages
2740Specifies the maximum size of the process stack on systems with the
2741.Fn mlockall
2742function.
2743Defaults to 50 4k pages (200 4k pages in OpenBSD).
2744.It Cm filenum Ar Nfiledescriptors
2745Specifies the maximum number of file descriptors ntpd may have open at once. Defaults to the system default.
2746.El
2747.It Xo Ic trap Ar host_address
2748.Op Cm port Ar port_number
2749.Op Cm interface Ar interface_address
2750.Xc
2751This command configures a trap receiver at the given host
2752address and port number for sending messages with the specified
2753local interface address.
2754If the port number is unspecified, a value
2755of 18447 is used.
2756If the interface address is not specified, the
2757message is sent with a source address of the local interface the
2758message is sent through.
2759Note that on a multihomed host the
2760interface used may vary from time to time with routing changes.
2761.Pp
2762The trap receiver will generally log event messages and other
2763information from the server in a log file.
2764While such monitor
2765programs may also request their own trap dynamically, configuring a
2766trap receiver will ensure that no messages are lost when the server
2767is started.
2768.It Cm hop Ar ...
2769This command specifies a list of TTL values in increasing order, up to 8
2770values can be specified.
2771In manycast mode these values are used in turn in
2772an expanding-ring search.
2773The default is eight multiples of 32 starting at
277431.
2775.El
2776	_END_PROG_MDOC_DESCRIP;
2777};
2778
2779doc-section	= {
2780  ds-type	= 'FILES';
2781  ds-format	= 'mdoc';
2782  ds-text	= <<- _END_MDOC_FILES
2783.Bl -tag -width /etc/ntp.drift -compact
2784.It Pa /etc/ntp.conf
2785the default name of the configuration file
2786.It Pa ntp.keys
2787private MD5 keys
2788.It Pa ntpkey
2789RSA private key
2790.It Pa ntpkey_ Ns Ar host
2791RSA public key
2792.It Pa ntp_dh
2793Diffie-Hellman agreement parameters
2794.El
2795	_END_MDOC_FILES;
2796};
2797
2798doc-section	= {
2799  ds-type	= 'SEE ALSO';
2800  ds-format	= 'mdoc';
2801  ds-text	= <<- _END_MDOC_SEE_ALSO
2802.Xr ntpd 1ntpdmdoc ,
2803.Xr ntpdc 1ntpdcmdoc ,
2804.Xr ntpq 1ntpqmdoc
2805.Pp
2806In addition to the manual pages provided,
2807comprehensive documentation is available on the world wide web
2808at
2809.Li http://www.ntp.org/ .
2810A snapshot of this documentation is available in HTML format in
2811.Pa /usr/share/doc/ntp .
2812.Rs
2813.%A David L. Mills
2814.%T Network Time Protocol (Version 4)
2815.%O RFC5905
2816.Re
2817	_END_MDOC_SEE_ALSO;
2818};
2819
2820doc-section	= {
2821  ds-type	= 'BUGS';
2822  ds-format	= 'mdoc';
2823  ds-text	= <<- _END_MDOC_BUGS
2824The syntax checking is not picky; some combinations of
2825ridiculous and even hilarious options and modes may not be
2826detected.
2827.Pp
2828The
2829.Pa ntpkey_ Ns Ar host
2830files are really digital
2831certificates.
2832These should be obtained via secure directory
2833services when they become universally available.
2834	_END_MDOC_BUGS;
2835};
2836
2837doc-section	= {
2838  ds-type	= 'NOTES';
2839  ds-format	= 'mdoc';
2840  ds-text	= <<- _END_MDOC_NOTES
2841This document was derived from FreeBSD.
2842	_END_MDOC_NOTES;
2843};
2844