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