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