diff options
Diffstat (limited to 'usr.sbin/ntp/doc/ntp.conf.5')
| -rw-r--r-- | usr.sbin/ntp/doc/ntp.conf.5 | 504 |
1 files changed, 333 insertions, 171 deletions
diff --git a/usr.sbin/ntp/doc/ntp.conf.5 b/usr.sbin/ntp/doc/ntp.conf.5 index e1d5d7a..c1df2a2 100644 --- a/usr.sbin/ntp/doc/ntp.conf.5 +++ b/usr.sbin/ntp/doc/ntp.conf.5 @@ -271,7 +271,8 @@ described in .Sx Authentication Options . .It Cm burst when the server is reachable, send a burst of eight packets -instead of the usual one. The packet spacing is normally 2 s; +instead of the usual one. +The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the calldelay command to allow additional time for a modem or ISDN call to complete. @@ -281,7 +282,8 @@ with the command and s addresses. .It Cm iburst When the server is unreachable, send a burst of eight packets -instead of the usual one. The packet spacing is normally 2 s; +instead of the usual one. +The packet spacing is normally 2 s; however, the spacing between the first two packets can be changed with the calldelay command to allow additional time for a modem or ISDN call to complete. @@ -412,7 +414,8 @@ based on public key cryptography. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on a private value which is generated by each server and -never revealed. With Autokey all key distribution and +never revealed. +With Autokey all key distribution and management functions involve only public values, which considerably simplifies key distribution and storage. Public key management is based on X.509 certificates, @@ -423,7 +426,8 @@ or the NTPv4 distribution. While the algorithms for symmetric key cryptography are included in the NTPv4 distribution, public key cryptography requires the OpenSSL software library to be installed -before building the NTP distribution. Directions for doing that +before building the NTP distribution. +Directions for doing that are on the Building and Installing the Distribution page. .Pp Authentication is configured separately for each association @@ -447,12 +451,15 @@ and the interval between various operations, if other than default. .Pp Authentication is always enabled, although ineffective if not configured as -described below. If a NTP packet arrives +described below. +If a NTP packet arrives including a message authentication code (MAC), it is accepted only if it -passes all cryptographic checks. The +passes all cryptographic checks. +The checks require correct key ID, key value -and message digest. If the packet has +and message digest. +If the packet has been modified in any way or replayed by an intruder, it will fail one or more of these checks and be discarded. @@ -481,13 +488,15 @@ authenticated using either symmetric key or public key cryptography. If this flag is disabled, these operations are effective even if not cryptographic -authenticated. It should be understood +authenticated. +It should be understood that operating with the .Ic auth flag disabled invites a significant vulnerability where a rogue hacker can masquerade as a falseticker and seriously -disrupt system timekeeping. It is +disrupt system timekeeping. +It is important to note that this flag has no purpose other than to allow or disallow a new association in response to new broadcast @@ -522,7 +531,8 @@ The original RFC-1305 specification allows any one of possibly authenticate an association. The servers and clients involved must agree on the key and key identifier to -authenticate NTP packets. Keys and +authenticate NTP packets. +Keys and related information are specified in a key file, usually called .Pa ntp.keys , @@ -541,17 +551,20 @@ When is first started, it reads the key file specified in the .Ic keys configuration command and installs the keys -in the key cache. However, +in the key cache. +However, individual keys must be activated with the .Ic trusted -command before use. This +command before use. +This allows, for instance, the installation of possibly several batches of keys and then activating or deactivating each batch remotely using .Xr ntpdc 8 . This also provides a revocation capability that can be used -if a key becomes compromised. The +if a key becomes compromised. +The .Ic requestkey command selects the key used as the password for the .Xr ntpdc 8 @@ -574,15 +587,16 @@ are also available. Using all of these schemes provides strong security against replay with or without modification, spoofing, masquerade and most forms of clogging attacks. -.Pp -\." The cryptographic means necessary for all Autokey operations -\." is provided by the OpenSSL software library. -\." This library is available from http://www.openssl.org/ -\." and can be installed using the procedures outlined -\." in the Building and Installing the Distribution page. Once installed, -\." the configure and build -\." process automatically detects the library and links -\." the library routines required. +.\" .Pp +.\" The cryptographic means necessary for all Autokey operations +.\" is provided by the OpenSSL software library. +.\" This library is available from http://www.openssl.org/ +.\" and can be installed using the procedures outlined +.\" in the Building and Installing the Distribution page. +.\" Once installed, +.\" the configure and build +.\" process automatically detects the library and links +.\" the library routines required. .Pp The Autokey protocol has several modes of operation corresponding to the various NTP modes supported. @@ -601,23 +615,29 @@ The specific cryptographic environment used by Autokey servers and clients is determined by a set of files and soft links generated by the .Xr ntp-keygen 8 -program. This includes a required host key file, +program. +This includes a required host key file, required certificate file and optional sign key file, -leapsecond file and identity scheme files. The +leapsecond file and identity scheme files. +The digest/signature scheme is specified in the X.509 certificate -along with the matching sign key. There are several schemes +along with the matching sign key. +There are several schemes available in the OpenSSL software library, each identified by a specific string such as .Cm md5WithRSAEncryption , which stands for the MD5 message digest with RSA -encryption scheme. The current NTP distribution supports +encryption scheme. +The current NTP distribution supports all the schemes in the OpenSSL library, including those based on RSA and DSA digital signatures. .Pp NTP secure groups can be used to define cryptographic compartments -and security hierarchies. It is important that every host +and security hierarchies. +It is important that every host in the group be able to construct a certificate trail to one -or more trusted hosts in the same group. Each group +or more trusted hosts in the same group. +Each group host runs the Autokey protocol to obtain the certificates for all hosts along the trail to one or more trusted hosts. This requires the configuration file in all hosts to be @@ -638,7 +658,8 @@ DNS compromise is essential. By convention, the name of an Autokey host is the name returned by the Unix .Xr gethostname 2 -system call or equivalent in other systems. By the system design +system call or equivalent in other systems. +By the system design model, there are no provisions to allow alternate names or aliases. However, this is not to say that DNS aliases, different names for each interface, etc., are constrained in any way. @@ -646,10 +667,12 @@ for each interface, etc., are constrained in any way. It is also important to note that Autokey verifies authenticity using the host name, network address and public keys, all of which are bound together by the protocol specifically -to deflect masquerade attacks. For this reason Autokey +to deflect masquerade attacks. +For this reason Autokey includes the source and destinatino IP addresses in message digest computations and so the same addresses must be available -at both the server and client. For this reason operation +at both the server and client. +For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters. @@ -661,7 +684,8 @@ There may be management configurations where the clients, servers and peers may not all support the same cryptotypes. A secure NTPv4 subnet can be configured in many ways while keeping in mind the principles explained above and -in this section. Note however that some cryptotype +in this section. +Note however that some cryptotype combinations may successfully interoperate with each other, but may not represent good security practice. .Pp @@ -688,14 +712,16 @@ using Autokey. When multiple identity schemes are supported in the Autokey protocol, the first message exchange determines which one is used. The client request message contains bits corresponding -to which schemes it has available. The server response message +to which schemes it has available. +The server response message contains bits corresponding to which schemes it has available. Both server and client match the received bits with their own and select a common scheme. .Pp Following the principle that time is a public value, a server responds to any client packet that matches -its cryptotype capabilities. Thus, a server receiving +its cryptotype capabilities. +Thus, a server receiving an unauthenticated packet will respond with an unauthenticated packet, while the same server receiving a packet of a cryptotype it supports will respond with packets of that cryptotype. @@ -710,13 +736,17 @@ Some examples may help to reduce confusion. Client Alice has no specific cryptotype selected. Server Bob has both a symmetric key file and minimal Autokey files. Alice's unauthenticated messages arrive at Bob, who replies with -unauthenticated messages. Cathy has a copy of Bob's symmetric +unauthenticated messages. +Cathy has a copy of Bob's symmetric key file and has selected key ID 4 in messages to Bob. -Bob verifies the message with his key ID 4. If it's the +Bob verifies the message with his key ID 4. +If it's the same key and the message is verified, Bob sends Cathy a reply -authenticated with that key. If verification fails, +authenticated with that key. +If verification fails, Bob sends Cathy a thing called a crypto-NAK, which tells her -something broke. She can see the evidence using the ntpq program. +something broke. +She can see the evidence using the ntpq program. .Pp Denise has rolled her own host key and certificate. She also uses one of the identity schemes as Bob. @@ -739,22 +769,27 @@ incorporated as a set of files generated by the .Xr ntp-keygen 8 utility program, including symmetric key, host key and public certificate files, as well as sign key, identity parameters -and leapseconds files. Alternatively, host and sign keys and +and leapseconds files. +Alternatively, host and sign keys and certificate files can be generated by the OpenSSL utilities and certificates can be imported from public certificate -authorities. Note that symmetric keys are necessary for the +authorities. +Note that symmetric keys are necessary for the .Xr ntpq 8 and .Xr ntpdc 8 -utility programs. The remaining files are necessary only for the +utility programs. +The remaining files are necessary only for the Autokey protocol. .Pp Certificates imported from OpenSSL or public certificate authorities have certian limitations. The certificate should be in ASN.1 syntax, X.509 Version 3 format and encoded in PEM, which is the same format -used by OpenSSL. The overall length of the certificate encoded -in ASN.1 must not exceed 1024 bytes. The subject distinguished +used by OpenSSL. +The overall length of the certificate encoded +in ASN.1 must not exceed 1024 bytes. +The subject distinguished name field (CN) is the fully qualified name of the host on which it is used; the remaining subject fields are ignored. The certificate extension fields must not contain either @@ -797,10 +832,12 @@ range 1 to 65,534, inclusive. .Op Cm mvpar Ar file .Op Cm pw Ar password .Xc -This command requires the OpenSSL library. It activates public key +This command requires the OpenSSL library. +It activates public key cryptography, selects the message digest and signature encryption scheme and loads the required private and public -values described above. If one or more files are left unspecified, +values described above. +If one or more files are left unspecified, the default names are used as described above. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified @@ -816,12 +853,14 @@ This overrides the link .Pa ntpkey_cert_ Ns Ar hostname in the keys directory. .It Cm gqpar Ar file -Specifies the location of the optional GQ parameters file. This +Specifies the location of the optional GQ parameters file. +This overrides the link .Pa ntpkey_gq_ Ns Ar hostname in the keys directory. .It Cm host Ar file -Specifies the location of the required host key file. This overrides +Specifies the location of the required host key file. +This overrides the link .Pa ntpkey_key_ Ns Ar hostname in the keys directory. @@ -836,22 +875,27 @@ This overrides the link .Pa ntpkey_leap in the keys directory. .It Cm mvpar Ar file -Specifies the location of the optional MV parameters file. This +Specifies the location of the optional MV parameters file. +This overrides the link .Pa ntpkey_mv_ Ns Ar hostname in the keys directory. .It Cm pw Ar password Specifies the password to decrypt files containing private keys and -identity parameters. This is required only if these files have been +identity parameters. +This is required only if these files have been encrypted. .It Cm randfile Ar file Specifies the location of the random seed file used by the OpenSSL -library. The defaults are described in the main text above. +library. +The defaults are described in the main text above. .It Cm sign Ar file -Specifies the location of the optional sign key file. This overrides +Specifies the location of the optional sign key file. +This overrides the link .Pa ntpkey_sign_ Ns Ar hostname -in the keys directory. If this file is +in the keys directory. +If this file is not found, the host key is also the sign key. .El .It Ic keys Ar keyfile @@ -938,7 +982,8 @@ Not used. The signature length does not match the current public key. .It 108 .Pq signature not verified -The message fails the signature check. It could be bogus or signed by a +The message fails the signature check. +It could be bogus or signed by a different private key. .It 109 .Pq certificate not verified @@ -989,7 +1034,8 @@ Currently, four kinds of statistics are supported. .Bl -tag -width indent .It Cm clockstats -Enables recording of clock driver statistics information. Each update +Enables recording of clock driver statistics information. +Each update received from a clock driver appends a line of the following form to the file generation set named .Cm clockstats : @@ -998,14 +1044,19 @@ the file generation set named .Ed .Pp The first two fields show the date (Modified Julian Day) and time -(seconds and fraction past UTC midnight). The next field shows the -clock address in dotted-quad notation, The final field shows the last +(seconds and fraction past UTC midnight). +The next field shows the +clock address in dotted-quad notation. +The final field shows the last timecode received from the clock in decoded ASCII format, where -meaningful. In some clock drivers a good deal of additional information -can be gathered and displayed as well. See information specific to each +meaningful. +In some clock drivers a good deal of additional information +can be gathered and displayed as well. +See information specific to each clock for further details. .It Cm cryptostats -This option requires the OpenSSL cryptographic software library. It +This option requires the OpenSSL cryptographic software library. +It enables recording of cryptographic public key protocol information. Each message received by the protocol module appends a line of the following form to the file generation set named @@ -1015,9 +1066,11 @@ following form to the file generation set named .Ed .Pp The first two fields show the date (Modified Julian Day) and time -(seconds and fraction past UTC midnight). The next field shows the peer +(seconds and fraction past UTC midnight). +The next field shows the peer address in dotted-quad notation, The final message field includes the -message type and certain ancillary information. See the +message type and certain ancillary information. +See the .Sx Authentication Options section for further information. .It Cm loopstats @@ -1082,7 +1135,8 @@ The timestamp values are as received and before processing by the various data smoothing and mitigation algorithms. .It Cm sysstats -Enables recording of ntpd statistics counters on a periodic basis. Each +Enables recording of ntpd statistics counters on a periodic basis. +Each hour a line of the following form is appended to the file generation set named .Cm sysstats : @@ -1091,7 +1145,8 @@ set named .Ed .Pp The first two fields show the date (Modified Julian Day) and time -(seconds and fraction past UTC midnight). The remaining ten fields show +(seconds and fraction past UTC midnight). +The remaining ten fields show the statistics counter values accumulated since the last generated line. .Bl -tag -width indent @@ -1118,7 +1173,8 @@ Number of packets discarded due to rate limitation. .El .It Cm statsdir Ar directory_path Indicates the full path of a directory where statistics files -should be created (see below). This keyword allows +should be created (see below). +This keyword allows the (otherwise constant) .Cm filegen filename prefix to be modified for file generation sets, which @@ -1129,13 +1185,16 @@ is useful for handling statistics logs. .Op Cm link | nolink .Op Cm enable | disable .Xc -Configures setting of generation file set name. Generation +Configures setting of generation file set name. +Generation file sets provide a means for handling files that are continuously growing during the lifetime of a server. Server statistics are a typical example for such files. Generation file sets provide access to a set of files used -to store the actual data. At any time at most one element -of the set is being written to. The type given specifies +to store the actual data. +At any time at most one element +of the set is being written to. +The type given specifies when and how data will be directed to a new element of the set. This way, information stored in elements of a file set that are currently unused are available for administrational @@ -1152,7 +1211,8 @@ This is the type of the statistics records, as shown in the .Cm statistics command. .It Cm file Ar filename -This is the file name for the statistics records. Filenames of set +This is the file name for the statistics records. +Filenames of set members are built from three concatenated elements .Ar Cm prefix , .Ar Cm filename @@ -1160,13 +1220,17 @@ and .Ar Cm suffix : .Bl -tag -width indent .It Cm prefix -This is a constant filename path. It is not subject to +This is a constant filename path. +It is not subject to modifications via the .Ar filegen -option. It is defined by the -server, usually specified as a compile-time constant. It may, +option. +It is defined by the +server, usually specified as a compile-time constant. +It may, however, be configurable for individual file generation sets -via other commands. For example, the prefix used with +via other commands. +For example, the prefix used with .Ar loopstats and .Ar peerstats @@ -1180,27 +1244,34 @@ above (no intervening This can be modified using the file argument to the .Ar filegen -statement. No .. elements are +statement. +No +.Pa .. +elements are allowed in this component to prevent filenames referring to parts outside the filesystem hierarchy denoted by .Ar prefix . .It Cm suffix -This part is reflects individual elements of a file set. It is +This part is reflects individual elements of a file set. +It is generated according to the type of a file set. .El .It Cm type Ar typename -A file generation set is characterized by its type. The following +A file generation set is characterized by its type. +The following types are supported: .Bl -tag -width indent .It Cm none The file set is actually a single plain file. .It Cm pid One element of file set is used per incarnation of a ntpd -server. This type does not perform any changes to file set +server. +This type does not perform any changes to file set members during runtime, however it provides an easy way of separating files belonging to different .Xr ntpd 8 -server incarnations. The set member filename is built by appending a +server incarnations. +The set member filename is built by appending a .Ql \&. to concatenated .Ar prefix @@ -1211,8 +1282,10 @@ appending the decimal representation of the process ID of the .Xr ntpd 8 server process. .It Cm day -One file generation set element is created per day. A day is -defined as the period between 00:00 and 24:00 UTC. The file set +One file generation set element is created per day. +A day is +defined as the period between 00:00 and 24:00 UTC. +The file set member suffix consists of a .Ql \&. and a day specification in @@ -1230,24 +1303,30 @@ in a file named .Ar filename Ns .19921210 . .It Cm week Any file set member contains data related to a certain week of -a year. The term week is defined by computing day-of-year -modulo 7. Elements of such a file generation set are +a year. +The term week is defined by computing day-of-year +modulo 7. +Elements of such a file generation set are distinguished by appending the following suffix to the file set filename base: A dot, a 4-digit year number, the letter .Cm W , -and a 2-digit week number. For example, information from January, +and a 2-digit week number. +For example, information from January, 10th 1992 would end up in a file with suffix .No . Ns Ar 1992W1 . .It Cm month -One generation file set element is generated per month. The +One generation file set element is generated per month. +The file name suffix consists of a dot, a 4-digit year number, and a 2-digit month. .It Cm year -One generation file element is generated per year. The filename +One generation file element is generated per year. +The filename suffix consists of a dot and a 4 digit year number. .It Cm age This type of file generation sets changes to a new element of -the file set every 24 hours of server operation. The filename +the file set every 24 hours of server operation. +The filename suffix consists of a dot, the letter .Cm a , and an 8-digit number. @@ -1260,19 +1339,23 @@ output is prevented by specifying .El .It Cm link | nolink It is convenient to be able to access the current element of a file -generation set by a fixed name. This feature is enabled by +generation set by a fixed name. +This feature is enabled by specifying .Cm link and disabled using .Cm nolink . If link is specified, a hard link from the current file set element to a file without -suffix is created. When there is already a file with this name and +suffix is created. +When there is already a file with this name and the number of links of this file is one, it is renamed appending a dot, the letter .Cm C , -and the pid of the ntpd server process. When the -number of links is greater than one, the file is unlinked. This +and the pid of the ntpd server process. +When the +number of links is greater than one, the file is unlinked. +This allows the current file to be accessed by a constant name. .It Cm enable \&| Cm disable Enables or disables the recording function. @@ -1283,11 +1366,13 @@ Enables or disables the recording function. The .Xr ntpd 8 daemon implements a general purpose address/mask based restriction -list. The list contains address/match entries sorted first +list. +The list contains address/match entries sorted first by increasing address values and and then by increasing mask values. A match occurs when the bitwise AND of the mask and the packet source address is equal to the bitwise AND of the mask and -address in the list. The list is searched in order with the +address in the list. +The list is searched in order with the last match found defining the restriction flags associated with the entry. Additional information and examples can be found in the @@ -1299,8 +1384,10 @@ provided in .Pp The restriction facility was implemented in conformance with the access policies for the original NSFnet backbone -time servers. Later the facility was expanded to deflect -cryptographic and clogging attacks. While this facility may +time servers. +Later the facility was expanded to deflect +cryptographic and clogging attacks. +While this facility may be useful for keeping unwanted or broken or malicious clients from congesting innocent servers, it should not be considered an alternative to the NTP authentication facilities. @@ -1310,13 +1397,16 @@ by a determined cracker. Clients can be denied service because they are explicitly included in the restrict list created by the restrict command or implicitly as the result of cryptographic or rate limit -violations. Cryptographic violations include certificate +violations. +Cryptographic violations include certificate or identity verification failure; rate limit violations generally result from defective NTP implementations that send packets -at abusive rates. Some violations cause denied service +at abusive rates. +Some violations cause denied service only for the offending packet, others cause denied service for a timed period and others cause the denied service for -an indefinate period. When a client or network is denied access +an indefinate period. +When a client or network is denied access for an indefinate period, the only way at present to remove the restrictions is by restarting the server. .Ss The Kiss-of-Death Packet @@ -1346,10 +1436,12 @@ A client receiving a KoD performs a set of sanity checks to minimize security exposure, then updates the stratum and reference identifier peer variables, sets the access denied (TEST4) bit in the peer flash variable and sends -a message to the log. As long as the TEST4 bit is set, +a message to the log. +As long as the TEST4 bit is set, the client will send no further packets to the server. The only way at present to recover from this condition is -to restart the protocol at both the client and server. This +to restart the protocol at both the client and server. +This happens automatically at the client when the association times out. It will happen at the server only if the server operator cooperates. .Ss Access Control Commands @@ -1362,14 +1454,16 @@ It will happen at the server only if the server operator cooperates. Set the parameters of the .Cm limited facility which protects the server from -client abuse. The +client abuse. +The .Cm average subcommand specifies the minimum average packet spacing, while the .Cm minimum subcommand specifies the minimum packet spacing. Packets that violate these minima are discarded -and a kiss-o'-death packet returned if enabled. The default +and a kiss-o'-death packet returned if enabled. +The default minimum average and minimum are 5 and 2, respectively. The monitor subcommand specifies the probability of discard for packets that overflow the rate-control window. @@ -1383,7 +1477,8 @@ argument expressed in dotted-quad form is the address of a host or network. Alternatively, the .Ar address -argument can be a valid host DNS name. The +argument can be a valid host DNS name. +The .Ar mask argument expressed in dotted-quad form defaults to .Cm 255.255.255.255 , @@ -1422,12 +1517,15 @@ and queries. .It Cm kod If this flag is set when an access violation occurs, a kiss-o'-death -(KoD) packet is sent. KoD packets are rate limited to no more than one -per second. If another KoD packet occurs within one second after the +(KoD) packet is sent. +KoD packets are rate limited to no more than one +per second. +If another KoD packet occurs within one second after the last one, the packet is dropped. .It Cm limited Deny service if the packet spacing violates the lower limits specified -in the discard command. A history of clients is kept using the +in the discard command. +A history of clients is kept using the monitoring capability of .Xr ntpd 8 . Thus, monitoring is always active as @@ -1450,16 +1548,19 @@ Deny and .Xr ntpdc 8 queries which attempt to modify the state of the -server (i.e., run time reconfiguration). Queries which return +server (i.e., run time reconfiguration). +Queries which return information are permitted. .It Cm noquery Deny .Xr ntpq 8 and .Xr ntpdc 8 -queries. Time service is not affected. +queries. +Time service is not affected. .It Cm nopeer -Deny packets which would result in mobilizing a new association. This +Deny packets which would result in mobilizing a new association. +This includes broadcast and symmetric active packets when a configured association does not exist. .It Cm noserve @@ -1470,7 +1571,8 @@ and queries. .It Cm notrap Decline to provide mode 6 control message trap service to matching -hosts. The trap service is a subsystem of the ntpdq control message +hosts. +The trap service is a subsystem of the ntpdq control message protocol which is intended for use by remote event logging programs. .It Cm notrust Deny service unless the packet is cryptographically authenticated. @@ -1506,7 +1608,8 @@ NTP server is unrestricted). .Sh Automatic NTP Configuration Options .Ss Manycasting Manycasting is a automatic discovery and configuration paradigm -new to NTPv4. It is intended as a means for a multicast client +new to NTPv4. +It is intended as a means for a multicast client to troll the nearby network neighborhood to find cooperating manycast servers, validate them using cryptographic means and evaluate their time values with respect to other servers @@ -1524,7 +1627,8 @@ The manycast paradigm is designed to find a plurality of redundant servers satisfying defined optimality criteria. .Pp Manycasting can be used with either symmetric key -or public key cryptography. The public key infrastructure (PKI) +or public key cryptography. +The public key infrastructure (PKI) offers the best protection against compromised keys and is generally considered stronger, at least with relatively large key sizes. @@ -1540,7 +1644,8 @@ server command but with a multicast (IPv4 class .Cm D or IPv6 prefix .Cm FF ) -group address. The IANA has designated IPv4 address 224.1.1.1 +group address. +The IANA has designated IPv4 address 224.1.1.1 and IPv6 address FF05::101 (site local) for NTP. When more servers are needed, it broadcasts manycast client messages to this address at the minimum feasible rate @@ -1553,9 +1658,11 @@ for a future ephemeral unicast client/server association. Manycast servers configured with the .Ic manycastserver command listen on the specified group address for manycast -client messages. Note the distinction between manycast client, +client messages. +Note the distinction between manycast client, which actively broadcasts messages, and manycast server, -which passively responds to them. If a manycast server is +which passively responds to them. +If a manycast server is in scope of the current TTL and is itself synchronized to a valid source and operating at a stratum level equal to or lower than the manycast client, it replies to the @@ -1565,18 +1672,22 @@ The manycast client receiving this message mobilizes an ephemeral client/server association according to the matching manycast client template, but only if cryptographically authenticated and the server stratum is less than or equal -to the client stratum. Authentication is explicitly required +to the client stratum. +Authentication is explicitly required and either symmetric key or public key (Autokey) can be used. Then, the client polls the server at its unicast address in burst mode in order to reliably set the host clock -and validate the source. This normally results +and validate the source. +This normally results in a volley of eight client/server at 2-s intervals during which both the synchronization and cryptographic -protocols run concurrently. Following the volley, +protocols run concurrently. +Following the volley, the client runs the NTP intersection and clustering algorithms, which act to discard all but the "best" associations according to stratum and synchronization -distance. The surviving associations then continue +distance. +The surviving associations then continue in ordinary client/server mode. .Pp The manycast client polling strategy is designed to reduce @@ -1588,7 +1699,8 @@ The strategy is determined by the .Ic tos and .Ic ttl -configuration commands. The manycast poll interval is +configuration commands. +The manycast poll interval is normally eight times the system poll interval, which starts out at the .Cm minpoll @@ -1596,7 +1708,8 @@ value specified in the .Ic manycastclient , command and, under normal circumstances, increments to the .Cm maxpolll -value specified in this command. Initially, the TTL is +value specified in this command. +Initially, the TTL is set at the minimum hops specified by the ttl command. At each retransmission the TTL is increased until reaching the maximum hops specified by this command or a sufficient @@ -1611,7 +1724,8 @@ and .Cm minsane values specified in the .Ic tos -configuration command. At least +configuration command. +At least .Cm minsane candidate servers must be available and the mitigation algorithms produce at least @@ -1623,9 +1737,10 @@ For legacy purposes, .Cm minsane defaults to 1 and .Cm minclock -defaults to 3. For manycast service +defaults to 3. +For manycast service .Cm minsane -should be explicitly set to 4. assuming at least that +should be explicitly set to 4, assuming at least that number of servers are available. .Pp If at least @@ -1636,12 +1751,14 @@ set to eight times If less than .Cm minclock servers are found when the TTL has reached the maximum hops, -the manycast poll interval is doubled. For each transmission +the manycast poll interval is doubled. +For each transmission after that, the poll interval is doubled again until reaching the maximum of eight times .Cm maxpoll . Further transmissions use the same poll interval and -TTL values. Note that while all this is going on, +TTL values. +Note that while all this is going on, each client/server association found is operating normally it the system poll interval. .Pp @@ -1663,7 +1780,8 @@ in TTL range, which is probably the most common objective. However, unless configured otherwise, all manycast clients in TTL range will eventually find all primary servers in TTL range, which is probably not the most common -objective in large networks. The +objective in large networks. +The .Ic tos command can be used to modify this behavior. Servers with stratum below @@ -1688,7 +1806,8 @@ falls below .Cm minclock , all manycast client prototype associations are reset to the initial poll interval and TTL hops and operation -resumes from the beginning. It is important to avoid +resumes from the beginning. +It is important to avoid frequent manycast client messages, since each one requires all manycast servers in TTL range to respond. The result could well be an implosion, either minor or major, @@ -1702,15 +1821,18 @@ as both manycast client and manycast server. A number of hosts configured this way and sharing a common group address will automatically organize themselves in an optimum configuration based on stratum and -synchronization distance. For example, consider an NTP +synchronization distance. +For example, consider an NTP subnet of two primary servers and a hundred or more -dependent clients. With two exceptions, all servers +dependent clients. +With two exceptions, all servers and clients have identical configuration files including both .Ic multicastclient and .Ic multicastserver commands using, for instance, multicast group address -239.1.1.1. The only exception is that each primary server +239.1.1.1. +The only exception is that each primary server configuration file must include commands for the primary reference source such as a GPS receiver. .Pp @@ -1719,7 +1841,8 @@ servers and clients have the same contents, except for the .Ic tos command, which is specific for each stratum level. For stratum 1 and stratum 2 servers, that command is -not necessary. For stratum 3 and above servers the +not necessary. +For stratum 3 and above servers the .Cm floor value is set to the intended stratum number. Thus, all stratum 3 configuration files are identical, @@ -1729,7 +1852,8 @@ Once operations have stabilized in this scenario, the primary servers will find the primary reference source and each other, since they both operate at the same stratum (1), but not with any secondary server or client, -since these operate at a higher stratum. The secondary +since these operate at a higher stratum. +The secondary servers will find the servers at the same stratum level. If one of the primary servers loses its GPS receiver, it will continue to operate as a client and other clients @@ -1743,9 +1867,11 @@ continuously and run either or .Xr ntpd 8 .Fl q -as a cron job. In either case the servers must be +as a cron job. +In either case the servers must be configured in advance and the program fails if none are -available when the cron job runs. A really slick +available when the cron job runs. +A really slick application of manycast is with .Xr ntpd 8 .Fl q . @@ -1759,9 +1885,11 @@ configuration file. Each time a manycast client sends a client mode packet to a multicast group address, all manycast servers in scope generate a reply including the host name -and status word. The manycast clients then run +and status word. +The manycast clients then run the Autokey protocol, which collects and verifies -all certificates involved. Following the burst interval +all certificates involved. +Following the burst interval all but three survivors are cast off, but the certificates remain in the local cache. It often happens that several complete signing trails @@ -1772,12 +1900,14 @@ exceeds this, the client regenerates the Autokey key list. This is in general transparent in client/server mode. However, about once per day the server private value used to generate cookies is refreshed along with all -manycast client associations. In this case all +manycast client associations. +In this case all cryptographic values including certificates is refreshed. If a new certificate has been generated since the last refresh epoch, it will automatically revoke all prior certificates that happen to be in the -certificate cache. At the same time, the manycast +certificate cache. +At the same time, the manycast scheme starts all over from the beginning and the expanding ring shrinks to the minimum and increments from there while collecting all servers in scope. @@ -1793,9 +1923,11 @@ from there while collecting all servers in scope. .Oc .Xc This command affects the clock selection and clustering -algorithms. It can be used to select the quality and +algorithms. +It can be used to select the quality and quantity of peers used to synchronize the system clock -and is most useful in manycast mode. The variables operate +and is most useful in manycast mode. +The variables operate as follows: .Bl -tag -width indent .It Cm ceiling Ar ceiling @@ -1809,9 +1941,11 @@ to any number from 1 to 15. .It Cm cohort Bro 0 | 1 Brc This is a binary flag which enables (0) or disables (1) manycast server replies to manycast clients with the same -stratum level. This is useful to reduce implosions where +stratum level. +This is useful to reduce implosions where large numbers of clients with the same stratum level -are present. The default is to enable these replies. +are present. +The default is to enable these replies. .It Cm floor Ar floor Peers with strata below .Cm floor @@ -1824,7 +1958,8 @@ to any number from 1 to 15. The clustering algorithm repeatedly casts out outlyer associations until no more than .Cm minclock -associations remain. This value defaults to 3, +associations remain. +This value defaults to 3, but can be changed to any number from 1 to the number of configured sources. .It Cm minsane Ar minsane @@ -1832,8 +1967,10 @@ This is the minimum number of candidates available to the clock selection algorithm in order to produce one or more truechimers for the clustering algorithm. If fewer than this number are available, the clock is -undisciplined and allowed to run free. The default is 1 -for legacy purposes. However, according to principles of +undisciplined and allowed to run free. +The default is 1 +for legacy purposes. +However, according to principles of Byzantine agreement, .Cm minsane should be at least 4 in order to detect and discard @@ -1841,9 +1978,10 @@ a single falseticker. .El .It Cm ttl Ar hop ... This command specifies a list of TTL values in increasing -order. up to 8 values can be specified. +order, up to 8 values can be specified. In manycast mode these values are used in turn -in an expanding-ring search. The default is eight +in an expanding-ring search. +The default is eight multiples of 32 starting at 31. .El .Sh Reference Clock Support @@ -2183,12 +2321,15 @@ packets sent in burst or iburst mode to allow additional time for a modem or ISDN call to complete. .It Ic driftfile Ar driftfile This command specifies the complete path and name of the file used to -record the frequency of the local clock oscillator. This is the same +record the frequency of the local clock oscillator. +This is the same operation as the .Fl f -command linke option. If the file exists, it is read at +command linke option. +If the file exists, it is read at startup in order to set the initial frequency and then updated once per -hour with the current frequency computed by the daemon. If the file name is +hour with the current frequency computed by the daemon. +If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial @@ -2231,21 +2372,25 @@ utility program. .It Cm auth Enables the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using either public key or -private key cryptography. The default for this flag is +private key cryptography. +The default for this flag is .Ic enable . .It Cm bclient Enables the server to listen for a message from a broadcast or multicast server, as in the .Ic multicastclient command with default -address. The default for this flag is +address. +The default for this flag is .Ic disable . .It Cm calibrate -Enables the calibrate feature for reference clocks. The default for +Enables the calibrate feature for reference clocks. +The default for this flag is .Ic disable . .It Cm kernel -Enables the kernel time discipline, if available. The default for this +Enables the kernel time discipline, if available. +The default for this flag is .Ic enable if support is available, otherwise @@ -2262,13 +2407,16 @@ The default for this flag is .Ic enable . .It Cm ntp -Enables time and frequency discipline. In effect, this switch opens and -closes the feedback loop, which is useful for testing. The default for +Enables time and frequency discipline. +In effect, this switch opens and +closes the feedback loop, which is useful for testing. +The default for this flag is .Ic enable . .It Cm pps Enables the pulse-per-second (PPS) signal when frequency and time is -disciplined by the precision time kernel modifications. See the +disciplined by the precision time kernel modifications. +See the .Qq A Kernel Model for Precision Timekeeping (available as part of the HTML documentation provided in @@ -2286,10 +2434,12 @@ The default for this flag is .El .It Ic includefile Ar includefile This command allows additional configuration commands -to be included from a separate file. Include files may +to be included from a separate file. +Include files may be nested to a depth of five; upon reaching the end of any include file, command processing resumes in the previous -configuration file. This option is useful for sites that run +configuration file. +This option is useful for sites that run .Xr ntpd 8 on multiple hosts, with (mostly) common options (e.g., a restriction list). @@ -2348,9 +2498,11 @@ status messages .Pc . .Pp Configuration keywords are formed by concatenating the message class with -the event class. The +the event class. +The .Cm all -prefix can be used instead of a message class. A +prefix can be used instead of a message class. +A message class may also be followed by the .Cm all keyword to enable/disable all @@ -2377,7 +2529,8 @@ peers, system events and so on is suppressed. This command specifies the location of an alternate log file to be used instead of the default system .Xr syslog 3 -facility. This is the same operation as the -l command line option. +facility. +This is the same operation as the -l command line option. .It Ic setvar Ar variable Op Cm default This command adds an additional system variable. These @@ -2457,7 +2610,8 @@ The argument becomes the new value for the dispersion increase rate, normally .000015 s/s. .It Cm freq Ar freq The argument becomes the initial value of the frequency offset in -parts-per-million. This overrides the value in the frequency file, if +parts-per-million. +This overrides the value in the frequency file, if present, and avoids the initial training state if it is not. .It Cm huffpuff Ar huffpuff The argument becomes the new value for the experimental @@ -2469,18 +2623,24 @@ There is no default, since the filter is not enabled unless this command is given. .It Cm panic Ar panic -The argument is the panic threshold, normally 1000 s. If set to zero, +The argument is the panic threshold, normally 1000 s. +If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted. .It Cm step Ar step -The argument is the step threshold, which by default is 0.128 s. It can -be set to any positive number in seconds. If set to zero, step -adjustments will never occur. Note: The kernel time discipline is +The argument is the step threshold, which by default is 0.128 s. +It can +be set to any positive number in seconds. +If set to zero, step +adjustments will never occur. +Note: The kernel time discipline is disabled if the step threshold is set to zero or greater than the default. .It Cm stepout Ar stepout -The argument is the stepout timeout, which by default is 900 s. It can -be set to any positive number in seconds. If set to zero, the stepout +The argument is the stepout timeout, which by default is 900 s. +It can +be set to any positive number in seconds. +If set to zero, the stepout pulses will not be suppressed. .El .It Xo Ic trap Ar host_address @@ -2505,9 +2665,11 @@ programs may also request their own trap dynamically, configuring a trap receiver will ensure that no messages are lost when the server is started. .It Cm hop Ar ... -This command specifies a list of TTL values in increasing order. up to 8 -values can be specified. In manycast mode these values are used in turn in -an expanding-ring search. The default is eight multiples of 32 starting at +This command specifies a list of TTL values in increasing order, up to 8 +values can be specified. +In manycast mode these values are used in turn in +an expanding-ring search. +The default is eight multiples of 32 starting at 31. .El .Sh FILES |
