128221Smsmith.Dd November 21 2016 293021Snsouch.Dt NTP_CONF 5 File Formats 371622Snsouch.Os 428221Smsmith.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) 528221Smsmith.\" 628221Smsmith.\" It has been AutoGen-ed November 21, 2016 at 08:02:03 AM by AutoGen 5.18.5 728221Smsmith.\" From the definitions ntp.conf.def 828221Smsmith.\" and the template file agmdoc-cmd.tpl 928221Smsmith.Sh NAME 1028221Smsmith.Nm ntp.conf 1128221Smsmith.Nd Network Time Protocol (NTP) daemon configuration file format 1228221Smsmith.Sh SYNOPSIS 1328221Smsmith.Nm 1428221Smsmith.Op Fl \-option\-name 1528221Smsmith.Op Fl \-option\-name Ar value 1628221Smsmith.Pp 1728221SmsmithAll arguments must be options. 1828221Smsmith.Pp 1928221Smsmith.Sh DESCRIPTION 2028221SmsmithThe 2128221Smsmith.Nm 2228221Smsmithconfiguration file is read at initial startup by the 2328221Smsmith.Xr ntpd @NTPD_MS@ 2428221Smsmithdaemon in order to specify the synchronization sources, 2528221Smsmithmodes and other related information. 2628221SmsmithUsually, it is installed in the 2728221Smsmith.Pa /etc 28116181Sobriendirectory, 29116181Sobrienbut could be installed elsewhere 30116181Sobrien(see the daemon's 3155939Snsouch.Fl c 3255939Snsouchcommand line option). 3328221Smsmith.Pp 3428221SmsmithThe file format is similar to other 35183053Sjhb.Ux 3655939Snsouchconfiguration files. 37187576SjhbComments begin with a 38183053Sjhb.Ql # 39129879Sphkcharacter and extend to the end of the line; 4028221Smsmithblank lines are ignored. 41187576SjhbConfiguration commands consist of an initial keyword 42183053Sjhbfollowed by a list of arguments, 43185003Sjhbsome of which may be optional, separated by whitespace. 4455939SnsouchCommands may not be continued over multiple lines. 4555939SnsouchArguments may be host names, 4655939Snsouchhost addresses written in numeric, dotted\-quad form, 4728221Smsmithintegers, floating point numbers (when specifying times in seconds) 48158005Smarceland text strings. 49158005Smarcel.Pp 50158005SmarcelThe rest of this page describes the configuration and control options. 51158005SmarcelThe 52158005Smarcel.Qq Notes on Configuring NTP and Setting up an NTP Subnet 5328221Smsmithpage 5428221Smsmith(available as part of the HTML documentation 5538061Smsmithprovided in 5638061Smsmith.Pa /usr/share/doc/ntp ) 57118292Sambriskocontains an extended discussion of these options. 58118292SambriskoIn addition to the discussion of general 5928221Smsmith.Sx Configuration Options , 6055939Snsouchthere are sections describing the following supported functionality 6142475Snsouchand the options used to control it: 62118292Sambrisko.Bl -bullet -offset indent 63118292Sambrisko.It 64158005Smarcel.Sx Authentication Support 65158005Smarcel.It 66158005Smarcel.Sx Monitoring Support 6742475Snsouch.It 6842475Snsouch.Sx Access Control Support 6942475Snsouch.It 70158005Smarcel.Sx Automatic NTP Configuration Options 71158005Smarcel.It 72158005Smarcel.Sx Reference Clock Support 73158005Smarcel.It 7428221Smsmith.Sx Miscellaneous Options 7555939Snsouch.El 76118292Sambrisko.Pp 77247066SimpFollowing these is a section describing 78247094Sglebius.Sx Miscellaneous Options . 79247066SimpWhile there is a rich set of options available, 80247066Simpthe only required option is one or more 81247066Simp.Ic pool , 82247066Simp.Ic server , 83247066Simp.Ic peer , 84247066Simp.Ic broadcast 85247066Simpor 86247066Simp.Ic manycastclient 87247066Simpcommands. 88247066Simp.Sh Configuration Support 89247066SimpFollowing is a description of the configuration commands in 90247066SimpNTPv4. 91247094SglebiusThese commands have the same basic functions as in NTPv3 and 92247066Simpin some cases new functions and new arguments. 93118292SambriskoThere are two 94166933Sjhbclasses of commands, configuration commands that configure a 9555939Snsouchpersistent association with a remote server or peer or reference 9655939Snsouchclock, and auxiliary commands that specify environmental variables 9738061Smsmiththat control various related operations. 9863403Sdfr.Ss Configuration Commands 9963624SdfrThe various modes are determined by the command keyword and the 10028221Smsmithtype of the required IP address. 10128221SmsmithAddresses are classed by type as 10238061Smsmith(s) a remote server or peer (IPv4 class A, B and C), (b) the 10338061Smsmithbroadcast address of a local interface, (m) a multicast address (IPv4 10438061Smsmithclass D), or (r) a reference clock address (127.127.x.x). 10538061SmsmithNote that 10638061Smsmithonly those options applicable to each command are listed below. 10738061SmsmithUse 10838061Smsmithof options not listed may not be caught as an error, but may result 10938061Smsmithin some weird and even destructive behavior. 11038061Smsmith.Pp 11138061SmsmithIf the Basic Socket Interface Extensions for IPv6 (RFC\-2553) 11238061Smsmithis detected, support for the IPv6 address family is generated 11328221Smsmithin addition to the default support of the IPv4 address family. 11438061SmsmithIn a few cases, including the 11538061Smsmith.Cm reslist 11638061Smsmithbillboard generated 11738061Smsmithby 11828221Smsmith.Xr ntpq @NTPQ_MS@ 11928221Smsmithor 12028221Smsmith.Xr ntpdc @NTPDC_MS@ , 12128221SmsmithIPv6 addresses are automatically generated. 12256617SdfrIPv6 addresses can be identified by the presence of colons 12328221Smsmith.Dq \&: 12428221Smsmithin the address field. 12528221SmsmithIPv6 addresses can be used almost everywhere where 12628221SmsmithIPv4 addresses can be used, 12728221Smsmithwith the exception of reference clock addresses, 12828221Smsmithwhich are always IPv4. 12956617Sdfr.Pp 13028221SmsmithNote that in contexts where a host name is expected, a 13128221Smsmith.Fl 4 13228221Smsmithqualifier preceding 13328221Smsmiththe host name forces DNS resolution to the IPv4 namespace, 134188173Simpwhile a 135185003Sjhb.Fl 6 136185003Sjhbqualifier forces DNS resolution to the IPv6 namespace. 13728221SmsmithSee IPv6 references for the 13855939Snsouchequivalent classes for that address family. 13928221Smsmith.Bl -tag -width indent 140187576Sjhb.It Xo Ic pool Ar address 14171622Snsouch.Op Cm burst 142188173Simp.Op Cm iburst 14342475Snsouch.Op Cm version Ar version 14428221Smsmith.Op Cm prefer 14542475Snsouch.Op Cm minpoll Ar minpoll 146188173Simp.Op Cm maxpoll Ar maxpoll 14728221Smsmith.Xc 14828221Smsmith.It Xo Ic server Ar address 14928221Smsmith.Op Cm key Ar key \&| Cm autokey 15028221Smsmith.Op Cm burst 151188173Simp.Op Cm iburst 15228221Smsmith.Op Cm version Ar version 15328221Smsmith.Op Cm prefer 15428221Smsmith.Op Cm minpoll Ar minpoll 155184130Sjhb.Op Cm maxpoll Ar maxpoll 15628221Smsmith.Op Cm true 157188173Simp.Xc 15828221Smsmith.It Xo Ic peer Ar address 15928221Smsmith.Op Cm key Ar key \&| Cm autokey 16042475Snsouch.Op Cm version Ar version 16142475Snsouch.Op Cm prefer 16242475Snsouch.Op Cm minpoll Ar minpoll 16342475Snsouch.Op Cm maxpoll Ar maxpoll 16442475Snsouch.Op Cm true 16542475Snsouch.Op Cm xleave 16642475Snsouch.Xc 16728221Smsmith.It Xo Ic broadcast Ar address 16842475Snsouch.Op Cm key Ar key \&| Cm autokey 16942475Snsouch.Op Cm version Ar version 17042475Snsouch.Op Cm prefer 171185003Sjhb.Op Cm minpoll Ar minpoll 17242475Snsouch.Op Cm ttl Ar ttl 17342475Snsouch.Op Cm xleave 17442475Snsouch.Xc 17528221Smsmith.It Xo Ic manycastclient Ar address 17642475Snsouch.Op Cm key Ar key \&| Cm autokey 17742475Snsouch.Op Cm version Ar version 17842475Snsouch.Op Cm prefer 17942475Snsouch.Op Cm minpoll Ar minpoll 18042475Snsouch.Op Cm maxpoll Ar maxpoll 18142475Snsouch.Op Cm ttl Ar ttl 18242475Snsouch.Xc 18342475Snsouch.El 18487599Sobrien.Pp 18542475SnsouchThese five commands specify the time server name or address to 18642475Snsouchbe used and the mode in which to operate. 18742475SnsouchThe 18842475Snsouch.Ar address 18942475Snsouchcan be 19042475Snsoucheither a DNS name or an IP address in dotted\-quad notation. 19142475SnsouchAdditional information on association behavior can be found in the 19242475Snsouch.Qq Association Management 19342475Snsouchpage 19442475Snsouch(available as part of the HTML documentation 19542475Snsouchprovided in 19642475Snsouch.Pa /usr/share/doc/ntp ) . 19742475Snsouch.Bl -tag -width indent 19842475Snsouch.It Ic pool 19942475SnsouchFor type s addresses, this command mobilizes a persistent 20042475Snsouchclient mode association with a number of remote servers. 20142475SnsouchIn this mode the local clock can synchronized to the 20242475Snsouchremote server, but the remote server can never be synchronized to 20387599Sobrienthe local clock. 20442475Snsouch.It Ic server 20542475SnsouchFor type s and r addresses, this command mobilizes a persistent 20642475Snsouchclient mode association with the specified remote server or local 20742475Snsouchradio clock. 20842475SnsouchIn this mode the local clock can synchronized to the 20942475Snsouchremote server, but the remote server can never be synchronized to 21042475Snsouchthe local clock. 21142475SnsouchThis command should 21242475Snsouch.Em not 21342475Snsouchbe used for type 21442475Snsouchb or m addresses. 21542475Snsouch.It Ic peer 21642475SnsouchFor type s addresses (only), this command mobilizes a 21742475Snsouchpersistent symmetric\-active mode association with the specified 21842475Snsouchremote peer. 21942475SnsouchIn this mode the local clock can be synchronized to 22042475Snsouchthe remote peer or the remote peer can be synchronized to the local 22142475Snsouchclock. 22242475SnsouchThis is useful in a network of servers where, depending on 22342475Snsouchvarious failure scenarios, either the local or remote peer may be 22442475Snsouchthe better source of time. 22542475SnsouchThis command should NOT be used for type 22687599Sobrienb, m or r addresses. 22742475Snsouch.It Ic broadcast 22842475SnsouchFor type b and m addresses (only), this 22942475Snsouchcommand mobilizes a persistent broadcast mode association. 23042475SnsouchMultiple 23142475Snsouchcommands can be used to specify multiple local broadcast interfaces 23242475Snsouch(subnets) and/or multiple multicast groups. 23342475SnsouchNote that local 23442475Snsouchbroadcast messages go only to the interface associated with the 23542475Snsouchsubnet specified, but multicast messages go to all interfaces. 23642475SnsouchIn broadcast mode the local server sends periodic broadcast 23742475Snsouchmessages to a client population at the 23842475Snsouch.Ar address 23987599Sobrienspecified, which is usually the broadcast address on (one of) the 24042475Snsouchlocal network(s) or a multicast address assigned to NTP. 24142475SnsouchThe IANA 24242475Snsouchhas assigned the multicast group address IPv4 224.0.1.1 and 24342475SnsouchIPv6 ff05::101 (site local) exclusively to 24442475SnsouchNTP, but other nonconflicting addresses can be used to contain the 24542475Snsouchmessages within administrative boundaries. 24642475SnsouchOrdinarily, this 24742475Snsouchspecification applies only to the local server operating as a 24887599Sobriensender; for operation as a broadcast client, see the 24942475Snsouch.Ic broadcastclient 25042475Snsouchor 25142475Snsouch.Ic multicastclient 25242475Snsouchcommands 25342475Snsouchbelow. 25442475Snsouch.It Ic manycastclient 25587599SobrienFor type m addresses (only), this command mobilizes a 25642475Snsouchmanycast client mode association for the multicast address 25742475Snsouchspecified. 258185003SjhbIn this case a specific address must be supplied which 25942475Snsouchmatches the address used on the 26042475Snsouch.Ic manycastserver 26142475Snsouchcommand for 26242475Snsouchthe designated manycast servers. 26342475SnsouchThe NTP multicast address 26442475Snsouch224.0.1.1 assigned by the IANA should NOT be used, unless specific 26542475Snsouchmeans are taken to avoid spraying large areas of the Internet with 26642475Snsouchthese messages and causing a possibly massive implosion of replies 26742475Snsouchat the sender. 26842475SnsouchThe 26928221Smsmith.Ic manycastserver 27028221Smsmithcommand specifies that the local server 27138061Smsmithis to operate in client mode with the remote servers that are 27238061Smsmithdiscovered as the result of broadcast/multicast messages. 27338061SmsmithThe 27438061Smsmithclient broadcasts a request message to the group address associated 27538061Smsmithwith the specified 27638061Smsmith.Ar address 27742482Snsouchand specifically enabled 27838061Smsmithservers respond to these messages. 27938061SmsmithThe client selects the servers 28038061Smsmithproviding the best time and continues as with the 28138061Smsmith.Ic server 28238061Smsmithcommand. 28328221SmsmithThe remaining servers are discarded as if never 28455939Snsouchheard. 28555939Snsouch.El 28655939Snsouch.Pp 28755939SnsouchOptions: 28855939Snsouch.Bl -tag -width indent 28955939Snsouch.It Cm autokey 29055939SnsouchAll packets sent to and received from the server or peer are to 29155939Snsouchinclude authentication fields encrypted using the autokey scheme 29255939Snsouchdescribed in 29355939Snsouch.Sx Authentication Options . 29455939Snsouch.It Cm burst 29555939Snsouchwhen the server is reachable, send a burst of eight packets 29655939Snsouchinstead of the usual one. 29755939SnsouchThe packet spacing is normally 2 s; 29855939Snsouchhowever, the spacing between the first and second packets 29955939Snsouchcan be changed with the 30055939Snsouch.Ic calldelay 30155939Snsouchcommand to allow 30255939Snsouchadditional time for a modem or ISDN call to complete. 30355939SnsouchThis is designed to improve timekeeping quality 30455939Snsouchwith the 30555939Snsouch.Ic server 30655939Snsouchcommand and s addresses. 30755939Snsouch.It Cm iburst 30855939SnsouchWhen the server is unreachable, send a burst of eight packets 30955939Snsouchinstead of the usual one. 31055939SnsouchThe packet spacing is normally 2 s; 31155939Snsouchhowever, the spacing between the first two packets can be 31255939Snsouchchanged with the 31355939Snsouch.Ic calldelay 31455939Snsouchcommand to allow 31555939Snsouchadditional time for a modem or ISDN call to complete. 31655939SnsouchThis is designed to speed the initial synchronization 31755939Snsouchacquisition with the 31855939Snsouch.Ic server 31955939Snsouchcommand and s addresses and when 32055939Snsouch.Xr ntpd @NTPD_MS@ 32155939Snsouchis started with the 32255939Snsouch.Fl q 32371622Snsouchoption. 32455939Snsouch.It Cm key Ar key 32555939SnsouchAll packets sent to and received from the server or peer are to 32655939Snsouchinclude authentication fields encrypted using the specified 32755939Snsouch.Ar key 32855939Snsouchidentifier with values from 1 to 65534, inclusive. 32955939SnsouchThe 33055939Snsouchdefault is to include no encryption field. 33155939Snsouch.It Cm minpoll Ar minpoll 33255939Snsouch.It Cm maxpoll Ar maxpoll 33355939SnsouchThese options specify the minimum and maximum poll intervals 33455939Snsouchfor NTP messages, as a power of 2 in seconds 33555939SnsouchThe maximum poll 33655939Snsouchinterval defaults to 10 (1,024 s), but can be increased by the 33755939Snsouch.Cm maxpoll 33855939Snsouchoption to an upper limit of 17 (36.4 h). 33955939SnsouchThe 34055939Snsouchminimum poll interval defaults to 6 (64 s), but can be decreased by 34155939Snsouchthe 34255939Snsouch.Cm minpoll 34355939Snsouchoption to a lower limit of 4 (16 s). 34455939Snsouch.It Cm noselect 34555939SnsouchMarks the server as unused, except for display purposes. 34655939SnsouchThe server is discarded by the selection algroithm. 34755939Snsouch.It Cm preempt 34855939SnsouchSays the association can be preempted. 34955939Snsouch.It Cm true 35055939SnsouchMarks the server as a truechimer. 35155939SnsouchUse this option only for testing. 35255939Snsouch.It Cm prefer 35355939SnsouchMarks the server as preferred. 35455939SnsouchAll other things being equal, 35555939Snsouchthis host will be chosen for synchronization among a set of 35655939Snsouchcorrectly operating hosts. 35755939SnsouchSee the 35855939Snsouch.Qq Mitigation Rules and the prefer Keyword 35955939Snsouchpage 36055939Snsouch(available as part of the HTML documentation 36155939Snsouchprovided in 36255939Snsouch.Pa /usr/share/doc/ntp ) 36355939Snsouchfor further information. 36455939Snsouch.It Cm true 36555939SnsouchForces the association to always survive the selection and clustering algorithms. 36655939SnsouchThis option should almost certainly 36755939Snsouch.Em only 36871622Snsouchbe used while testing an association. 36955939Snsouch.It Cm ttl Ar ttl 37055939SnsouchThis option is used only with broadcast server and manycast 37155939Snsouchclient modes. 37255939SnsouchIt specifies the time\-to\-live 37355939Snsouch.Ar ttl 37455939Snsouchto 37555939Snsouchuse on broadcast server and multicast server and the maximum 37655939Snsouch.Ar ttl 37755939Snsouchfor the expanding ring search with manycast 37855939Snsouchclient packets. 37955939SnsouchSelection of the proper value, which defaults to 38055939Snsouch127, is something of a black art and should be coordinated with the 38155939Snsouchnetwork administrator. 38255939Snsouch.It Cm version Ar version 38355939SnsouchSpecifies the version number to be used for outgoing NTP 38455939Snsouchpackets. 38555939SnsouchVersions 1\-4 are the choices, with version 4 the 38655939Snsouchdefault. 38755939Snsouch.It Cm xleave 38855939SnsouchValid in 38955939Snsouch.Cm peer 39055939Snsouchand 39155939Snsouch.Cm broadcast 39255939Snsouchmodes only, this flag enables interleave mode. 39355939Snsouch.El 39455939Snsouch.Ss Auxiliary Commands 39555939Snsouch.Bl -tag -width indent 39655939Snsouch.It Ic broadcastclient 39755939SnsouchThis command enables reception of broadcast server messages to 39855939Snsouchany local interface (type b) address. 39928221SmsmithUpon receiving a message for 40028221Smsmiththe first time, the broadcast client measures the nominal server 40128221Smsmithpropagation delay using a brief client/server exchange with the 40228221Smsmithserver, then enters the broadcast client mode, in which it 40328221Smsmithsynchronizes to succeeding broadcast messages. 40428221SmsmithNote that, in order 40528221Smsmithto avoid accidental or malicious disruption in this mode, both the 40628221Smsmithserver and client should operate using symmetric\-key or public\-key 40728221Smsmithauthentication as described in 40840784Snsouch.Sx Authentication Options . 40928221Smsmith.It Ic manycastserver Ar address ... 41040784SnsouchThis command enables reception of manycast client messages to 41140784Snsouchthe multicast group address(es) (type m) specified. 41240784SnsouchAt least one 41340784Snsouchaddress is required, but the NTP multicast address 224.0.1.1 41440784Snsouchassigned by the IANA should NOT be used, unless specific means are 41540784Snsouchtaken to limit the span of the reply and avoid a possibly massive 41640784Snsouchimplosion at the original sender. 41740784SnsouchNote that, in order to avoid 41840784Snsouchaccidental or malicious disruption in this mode, both the server 41940784Snsouchand client should operate using symmetric\-key or public\-key 42040784Snsouchauthentication as described in 42140784Snsouch.Sx Authentication Options . 42240784Snsouch.It Ic multicastclient Ar address ... 42328221SmsmithThis command enables reception of multicast server messages to 42438061Smsmiththe multicast group address(es) (type m) specified. 42528221SmsmithUpon receiving 42628221Smsmitha message for the first time, the multicast client measures the 42741591Sarchienominal server propagation delay using a brief client/server 42840784Snsouchexchange with the server, then enters the broadcast client mode, in 429185003Sjhbwhich it synchronizes to succeeding multicast messages. 43028221SmsmithNote that, 431185003Sjhbin order to avoid accidental or malicious disruption in this mode, 43228221Smsmithboth the server and client should operate using symmetric\-key or 43328221Smsmithpublic\-key authentication as described in 43428221Smsmith.Sx Authentication Options . 43540784Snsouch.It Ic mdnstries Ar number 43640784SnsouchIf we are participating in mDNS, 43740784Snsouchafter we have synched for the first time 43828221Smsmithwe attempt to register with the mDNS system. 43940784SnsouchIf that registration attempt fails, 44040784Snsouchwe try again at one minute intervals for up to 44128221Smsmith.Ic mdnstries 44228221Smsmithtimes. 44328221SmsmithAfter all, 44428221Smsmith.Ic ntpd 44540784Snsouchmay be starting before mDNS. 44628221SmsmithThe default value for 44728221Smsmith.Ic mdnstries 44863624Sdfris 5. 44928221Smsmith.El 45028221Smsmith.Sh Authentication Support 45128221SmsmithAuthentication support allows the NTP client to verify that the 45228221Smsmithserver is in fact known and trusted and not an intruder intending 45355939Snsouchaccidentally or on purpose to masquerade as that server. 45428221SmsmithThe NTPv3 45555939Snsouchspecification RFC\-1305 defines a scheme which provides 45640784Snsouchcryptographic authentication of received NTP packets. 45755939SnsouchOriginally, 45863624Sdfrthis was done using the Data Encryption Standard (DES) algorithm 45963624Sdfroperating in Cipher Block Chaining (CBC) mode, commonly called 46063624SdfrDES\-CBC. 46163624SdfrSubsequently, this was replaced by the RSA Message Digest 46228221Smsmith5 (MD5) algorithm using a private key, commonly called keyed\-MD5. 46328221SmsmithEither algorithm computes a message digest, or one\-way hash, which 46428221Smsmithcan be used to verify the server has the correct private key and 46528221Smsmithkey identifier. 46628221Smsmith.Pp 46740784SnsouchNTPv4 retains the NTPv3 scheme, properly described as symmetric key 46840784Snsouchcryptography and, in addition, provides a new Autokey scheme 46940784Snsouchbased on public key cryptography. 47040784SnsouchPublic key cryptography is generally considered more secure 47140784Snsouchthan symmetric key cryptography, since the security is based 47240784Snsouchon a private value which is generated by each server and 47340784Snsouchnever revealed. 47440784SnsouchWith Autokey all key distribution and 47540784Snsouchmanagement functions involve only public values, which 47640784Snsouchconsiderably simplifies key distribution and storage. 47740784SnsouchPublic key management is based on X.509 certificates, 478185003Sjhbwhich can be provided by commercial services or 47928221Smsmithproduced by utility programs in the OpenSSL software library 48040784Snsouchor the NTPv4 distribution. 48128221Smsmith.Pp 48228221SmsmithWhile the algorithms for symmetric key cryptography are 48328221Smsmithincluded in the NTPv4 distribution, public key cryptography 48428221Smsmithrequires the OpenSSL software library to be installed 48528221Smsmithbefore building the NTP distribution. 48628221SmsmithDirections for doing that 48728221Smsmithare on the Building and Installing the Distribution page. 48828221Smsmith.Pp 48928221SmsmithAuthentication is configured separately for each association 49063624Sdfrusing the 49128221Smsmith.Cm key 49263624Sdfror 49363624Sdfr.Cm autokey 49463624Sdfrsubcommand on the 49563624Sdfr.Ic peer , 496187576Sjhb.Ic server , 49763624Sdfr.Ic broadcast 49863624Sdfrand 49963624Sdfr.Ic manycastclient 50063624Sdfrconfiguration commands as described in 50163624Sdfr.Sx Configuration Options 50263624Sdfrpage. 50363624SdfrThe authentication 50463624Sdfroptions described below specify the locations of the key files, 50563624Sdfrif other than default, which symmetric keys are trusted 50663624Sdfrand the interval between various operations, if other than default. 50763624Sdfr.Pp 50863624SdfrAuthentication is always enabled, 50963624Sdfralthough ineffective if not configured as 51063624Sdfrdescribed below. 51163624SdfrIf a NTP packet arrives 51263624Sdfrincluding a message authentication 51363624Sdfrcode (MAC), it is accepted only if it 51463624Sdfrpasses all cryptographic checks. 51563624SdfrThe 51663624Sdfrchecks require correct key ID, key value 51763624Sdfrand message digest. 51863624SdfrIf the packet has 51963624Sdfrbeen modified in any way or replayed 52063624Sdfrby an intruder, it will fail one or more 52163624Sdfrof these checks and be discarded. 52263624SdfrFurthermore, the Autokey scheme requires a 52363624Sdfrpreliminary protocol exchange to obtain 52463624Sdfrthe server certificate, verify its 52563624Sdfrcredentials and initialize the protocol 52663624Sdfr.Pp 52763624SdfrThe 52863624Sdfr.Cm auth 52963624Sdfrflag controls whether new associations or 53063624Sdfrremote configuration commands require cryptographic authentication. 53128221SmsmithThis flag can be set or reset by the 53228221Smsmith.Ic enable 53340784Snsouchand 53440784Snsouch.Ic disable 535185003Sjhbcommands and also by remote 53640784Snsouchconfiguration commands sent by a 53740784Snsouch.Xr ntpdc @NTPDC_MS@ 53840784Snsouchprogram running on 53940784Snsouchanother machine. 54040784SnsouchIf this flag is enabled, which is the default 54140784Snsouchcase, new broadcast client and symmetric passive associations and 54240784Snsouchremote configuration commands must be cryptographically 54340784Snsouchauthenticated using either symmetric key or public key cryptography. 54440784SnsouchIf this 545185003Sjhbflag is disabled, these operations are effective 54640784Snsoucheven if not cryptographic 54740784Snsouchauthenticated. 54828221SmsmithIt should be understood 54940784Snsouchthat operating with the 55040784Snsouch.Ic auth 55140784Snsouchflag disabled invites a significant vulnerability 55240784Snsouchwhere a rogue hacker can 55340784Snsouchmasquerade as a falseticker and seriously 55440784Snsouchdisrupt system timekeeping. 55540784SnsouchIt is 55640784Snsouchimportant to note that this flag has no purpose 55740784Snsouchother than to allow or disallow 55840784Snsoucha new association in response to new broadcast 55940784Snsouchand symmetric active messages 56040784Snsouchand remote configuration commands and, in particular, 56140784Snsouchthe flag has no effect on 56240784Snsouchthe authentication process itself. 56340784Snsouch.Pp 56440784SnsouchAn attractive alternative where multicast support is available 56540784Snsouchis manycast mode, in which clients periodically troll 56640784Snsouchfor servers as described in the 56728221Smsmith.Sx Automatic NTP Configuration Options 56828221Smsmithpage. 56940784SnsouchEither symmetric key or public key 57040784Snsouchcryptographic authentication can be used in this mode. 57140784SnsouchThe principle advantage 57240784Snsouchof manycast mode is that potential servers need not be 57340784Snsouchconfigured in advance, 57440784Snsouchsince the client finds them during regular operation, 575185003Sjhband the configuration 57640784Snsouchfiles for all clients can be identical. 57728221Smsmith.Pp 57840784SnsouchThe security model and protocol schemes for 57928221Smsmithboth symmetric key and public key 58040784Snsouchcryptography are summarized below; 58140784Snsouchfurther details are in the briefings, papers 58240784Snsouchand reports at the NTP project page linked from 58340784Snsouch.Li http://www.ntp.org/ . 58440784Snsouch.Ss Symmetric\-Key Cryptography 585185003SjhbThe original RFC\-1305 specification allows any one of possibly 58640784Snsouch65,534 keys, each distinguished by a 32\-bit key identifier, to 58728221Smsmithauthenticate an association. 58840784SnsouchThe servers and clients involved must 58928221Smsmithagree on the key and key identifier to 59040784Snsouchauthenticate NTP packets. 59140784SnsouchKeys and 59240784Snsouchrelated information are specified in a key 59340784Snsouchfile, usually called 59440784Snsouch.Pa ntp.keys , 59555939Snsouchwhich must be distributed and stored using 59640784Snsouchsecure means beyond the scope of the NTP protocol itself. 59740784SnsouchBesides the keys used 59840784Snsouchfor ordinary NTP associations, 59940784Snsouchadditional keys can be used as passwords for the 60040784Snsouch.Xr ntpq @NTPQ_MS@ 60140784Snsouchand 60240784Snsouch.Xr ntpdc @NTPDC_MS@ 60340784Snsouchutility programs. 60440784Snsouch.Pp 60528221SmsmithWhen 60640784Snsouch.Xr ntpd @NTPD_MS@ 60728221Smsmithis first started, it reads the key file specified in the 60840784Snsouch.Ic keys 60940784Snsouchconfiguration command and installs the keys 61040784Snsouchin the key cache. 61140784SnsouchHowever, 61240784Snsouchindividual keys must be activated with the 61340784Snsouch.Ic trusted 61428221Smsmithcommand before use. 61540784SnsouchThis 61640784Snsouchallows, for instance, the installation of possibly 61740784Snsouchseveral batches of keys and 618185003Sjhbthen activating or deactivating each batch 619185003Sjhbremotely using 62040784Snsouch.Xr ntpdc @NTPDC_MS@ . 62140784SnsouchThis also provides a revocation capability that can be used 62240784Snsouchif a key becomes compromised. 62328221SmsmithThe 62440784Snsouch.Ic requestkey 62528221Smsmithcommand selects the key used as the password for the 62640784Snsouch.Xr ntpdc @NTPDC_MS@ 62740784Snsouchutility, while the 62840784Snsouch.Ic controlkey 62940784Snsouchcommand selects the key used as the password for the 63040784Snsouch.Xr ntpq @NTPQ_MS@ 63140784Snsouchutility. 63240784Snsouch.Ss Public Key Cryptography 63340784SnsouchNTPv4 supports the original NTPv3 symmetric key scheme 63440784Snsouchdescribed in RFC\-1305 and in addition the Autokey protocol, 63540784Snsouchwhich is based on public key cryptography. 63640784SnsouchThe Autokey Version 2 protocol described on the Autokey Protocol 63740784Snsouchpage verifies packet integrity using MD5 message digests 63840784Snsouchand verifies the source with digital signatures and any of several 63940784Snsouchdigest/signature schemes. 64040784SnsouchOptional identity schemes described on the Identity Schemes 64140784Snsouchpage and based on cryptographic challenge/response algorithms 64240784Snsouchare also available. 64340784SnsouchUsing all of these schemes provides strong security against 64440784Snsouchreplay with or without modification, spoofing, masquerade 64540784Snsouchand most forms of clogging attacks. 64640784Snsouch.\" .Pp 64740784Snsouch.\" The cryptographic means necessary for all Autokey operations 64840784Snsouch.\" is provided by the OpenSSL software library. 64940784Snsouch.\" This library is available from http://www.openssl.org/ 65055939Snsouch.\" and can be installed using the procedures outlined 65140784Snsouch.\" in the Building and Installing the Distribution page. 65240784Snsouch.\" Once installed, 65340784Snsouch.\" the configure and build 65440784Snsouch.\" process automatically detects the library and links 65540784Snsouch.\" the library routines required. 65640784Snsouch.Pp 65740784SnsouchThe Autokey protocol has several modes of operation 65840784Snsouchcorresponding to the various NTP modes supported. 65940784SnsouchMost modes use a special cookie which can be 66040784Snsouchcomputed independently by the client and server, 66140784Snsouchbut encrypted in transmission. 66240784SnsouchAll modes use in addition a variant of the S\-KEY scheme, 66340784Snsouchin which a pseudo\-random key list is generated and used 66440784Snsouchin reverse order. 66540784SnsouchThese schemes are described along with an executive summary, 66640784Snsouchcurrent status, briefing slides and reading list on the 66740784Snsouch.Sx Autonomous Authentication 66840784Snsouchpage. 66940784Snsouch.Pp 67040784SnsouchThe specific cryptographic environment used by Autokey servers 67140784Snsouchand clients is determined by a set of files 67240784Snsouchand soft links generated by the 67340784Snsouch.Xr ntp\-keygen 1ntpkeygenmdoc 674185003Sjhbprogram. 67540784SnsouchThis includes a required host key file, 67640784Snsouchrequired certificate file and optional sign key file, 67740784Snsouchleapsecond file and identity scheme files. 67840784SnsouchThe 67940784Snsouchdigest/signature scheme is specified in the X.509 certificate 68040784Snsouchalong with the matching sign key. 68140784SnsouchThere are several schemes 68240784Snsouchavailable in the OpenSSL software library, each identified 68340784Snsouchby a specific string such as 68440784Snsouch.Cm md5WithRSAEncryption , 68540784Snsouchwhich stands for the MD5 message digest with RSA 68640784Snsouchencryption scheme. 68728221SmsmithThe current NTP distribution supports 68838061Smsmithall the schemes in the OpenSSL library, including 68940784Snsouchthose based on RSA and DSA digital signatures. 69040784Snsouch.Pp 69140784SnsouchNTP secure groups can be used to define cryptographic compartments 69255939Snsouchand security hierarchies. 69355939SnsouchIt is important that every host 69440784Snsouchin the group be able to construct a certificate trail to one 69538061Smsmithor more trusted hosts in the same group. 69628221SmsmithEach group 69738061Smsmithhost runs the Autokey protocol to obtain the certificates 69828221Smsmithfor all hosts along the trail to one or more trusted hosts. 69928221SmsmithThis requires the configuration file in all hosts to be 70028221Smsmithengineered so that, even under anticipated failure conditions, 70128221Smsmiththe NTP subnet will form such that every group host can find 70228221Smsmitha trail to at least one trusted host. 70328221Smsmith.Ss Naming and Addressing 70428221SmsmithIt is important to note that Autokey does not use DNS to 70528221Smsmithresolve addresses, since DNS can't be completely trusted 70638061Smsmithuntil the name servers have synchronized clocks. 70728221SmsmithThe cryptographic name used by Autokey to bind the host identity 708247066Simpcredentials and cryptographic values must be independent 70943460Snsouchof interface, network and any other naming convention. 71028221SmsmithThe name appears in the host certificate in either or both 71128221Smsmiththe subject and issuer fields, so protection against 71228221SmsmithDNS compromise is essential. 71328221Smsmith.Pp 71428221SmsmithBy convention, the name of an Autokey host is the name returned 71528221Smsmithby the Unix 71628221Smsmith.Xr gethostname 2 71728221Smsmithsystem call or equivalent in other systems. 71828221SmsmithBy the system design 71928221Smsmithmodel, there are no provisions to allow alternate names or aliases. 72028221SmsmithHowever, this is not to say that DNS aliases, different names 721247066Simpfor each interface, etc., are constrained in any way. 72228221Smsmith.Pp 72328221SmsmithIt is also important to note that Autokey verifies authenticity 724247066Simpusing the host name, network address and public keys, 72528221Smsmithall of which are bound together by the protocol specifically 72628221Smsmithto deflect masquerade attacks. 72728221SmsmithFor this reason Autokey 72828221Smsmithincludes the source and destination IP addresses in message digest 72928221Smsmithcomputations and so the same addresses must be available 73028221Smsmithat both the server and client. 73128221SmsmithFor this reason operation 73228221Smsmithwith network address translation schemes is not possible. 733247066SimpThis reflects the intended robust security model where government 73428221Smsmithand corporate NTP servers are operated outside firewall perimeters. 73528221Smsmith.Ss Operation 736247066SimpA specific combination of authentication scheme (none, 73728221Smsmithsymmetric key, public key) and identity scheme is called 73828221Smsmitha cryptotype, although not all combinations are compatible. 73928221SmsmithThere may be management configurations where the clients, 74028221Smsmithservers and peers may not all support the same cryptotypes. 74128221SmsmithA secure NTPv4 subnet can be configured in many ways while 74228221Smsmithkeeping in mind the principles explained above and 74328221Smsmithin this section. 74428221SmsmithNote however that some cryptotype 74528221Smsmithcombinations may successfully interoperate with each other, 74628221Smsmithbut may not represent good security practice. 74728221Smsmith.Pp 74828221SmsmithThe cryptotype of an association is determined at the time 74928221Smsmithof mobilization, either at configuration time or some time 75028221Smsmithlater when a message of appropriate cryptotype arrives. 75128221SmsmithWhen mobilized by a 752247066Simp.Ic server 753247066Simpor 75438061Smsmith.Ic peer 755247066Simpconfiguration command and no 75628221Smsmith.Ic key 75728221Smsmithor 75828221Smsmith.Ic autokey 75928221Smsmithsubcommands are present, the association is not 76028221Smsmithauthenticated; if the 76128221Smsmith.Ic key 762247066Simpsubcommand is present, the association is authenticated 763247066Simpusing the symmetric key ID specified; if the 76438061Smsmith.Ic autokey 765247066Simpsubcommand is present, the association is authenticated 76628221Smsmithusing Autokey. 76755939Snsouch.Pp 76828221SmsmithWhen multiple identity schemes are supported in the Autokey 76928221Smsmithprotocol, the first message exchange determines which one is used. 77028221SmsmithThe client request message contains bits corresponding 77138061Smsmithto which schemes it has available. 77228221SmsmithThe server response message 77328221Smsmithcontains bits corresponding to which schemes it has available. 77438061SmsmithBoth server and client match the received bits with their own 77538061Smsmithand select a common scheme. 776184176Sjhb.Pp 777184176SjhbFollowing the principle that time is a public value, 77838061Smsmitha server responds to any client packet that matches 77938061Smsmithits cryptotype capabilities. 78038061SmsmithThus, a server receiving 78138061Smsmithan unauthenticated packet will respond with an unauthenticated 78238061Smsmithpacket, while the same server receiving a packet of a cryptotype 78338061Smsmithit supports will respond with packets of that cryptotype. 78428221SmsmithHowever, unconfigured broadcast or manycast client 78528221Smsmithassociations or symmetric passive associations will not be 78638061Smsmithmobilized unless the server supports a cryptotype compatible 78728221Smsmithwith the first packet received. 78828221SmsmithBy default, unauthenticated associations will not be mobilized 78938061Smsmithunless overridden in a decidedly dangerous way. 79038061Smsmith.Pp 79138061SmsmithSome examples may help to reduce confusion. 79238761SnsouchClient Alice has no specific cryptotype selected. 79338761SnsouchServer Bob has both a symmetric key file and minimal Autokey files. 79438761SnsouchAlice's unauthenticated messages arrive at Bob, who replies with 79528221Smsmithunauthenticated messages. 79638061SmsmithCathy has a copy of Bob's symmetric 79738061Smsmithkey file and has selected key ID 4 in messages to Bob. 79828221SmsmithBob verifies the message with his key ID 4. 79928221SmsmithIf it's the 80028221Smsmithsame key and the message is verified, Bob sends Cathy a reply 80128221Smsmithauthenticated with that key. 80228221SmsmithIf verification fails, 80328221SmsmithBob sends Cathy a thing called a crypto\-NAK, which tells her 80438061Smsmithsomething broke. 80538761SnsouchShe can see the evidence using the 80638761Snsouch.Xr ntpq @NTPQ_MS@ 80728221Smsmithprogram. 80828221Smsmith.Pp 80928221SmsmithDenise has rolled her own host key and certificate. 81038061SmsmithShe also uses one of the identity schemes as Bob. 81138761SnsouchShe sends the first Autokey message to Bob and they 81238761Snsouchboth dance the protocol authentication and identity steps. 81328221SmsmithIf all comes out okay, Denise and Bob continue as described above. 81428221Smsmith.Pp 81528221SmsmithIt should be clear from the above that Bob can support 81638061Smsmithall the girls at the same time, as long as he has compatible 81738761Snsouchauthentication and identity credentials. 81838761SnsouchNow, Bob can act just like the girls in his own choice of servers; 81928221Smsmithhe can run multiple configured associations with multiple different 82028221Smsmithservers (or the same server, although that might not be useful). 82128221SmsmithBut, wise security policy might preclude some cryptotype 82238061Smsmithcombinations; for instance, running an identity scheme 82338761Snsouchwith one server and no authentication with another might not be wise. 82438761Snsouch.Ss Key Management 82528221SmsmithThe cryptographic values used by the Autokey protocol are 82628221Smsmithincorporated as a set of files generated by the 82738061Smsmith.Xr ntp\-keygen 1ntpkeygenmdoc 82838061Smsmithutility program, including symmetric key, host key and 82938061Smsmithpublic certificate files, as well as sign key, identity parameters 83038761Snsouchand leapseconds files. 83138761SnsouchAlternatively, host and sign keys and 83238061Smsmithcertificate files can be generated by the OpenSSL utilities 83338061Smsmithand certificates can be imported from public certificate 83428221Smsmithauthorities. 83528221SmsmithNote that symmetric keys are necessary for the 83639135Snsouch.Xr ntpq @NTPQ_MS@ 83728221Smsmithand 83838061Smsmith.Xr ntpdc @NTPDC_MS@ 83928221Smsmithutility programs. 84028221SmsmithThe remaining files are necessary only for the 84128221SmsmithAutokey protocol. 84228221Smsmith.Pp 84338061SmsmithCertificates imported from OpenSSL or public certificate 84438061Smsmithauthorities have certian limitations. 84528221SmsmithThe certificate should be in ASN.1 syntax, X.509 Version 3 84638761Snsouchformat and encoded in PEM, which is the same format 84738761Snsouchused by OpenSSL. 84828221SmsmithThe overall length of the certificate encoded 84928221Smsmithin ASN.1 must not exceed 1024 bytes. 85028221SmsmithThe subject distinguished 85128221Smsmithname field (CN) is the fully qualified name of the host 85228221Smsmithon which it is used; the remaining subject fields are ignored. 85328221SmsmithThe certificate extension fields must not contain either 85428221Smsmitha subject key identifier or a issuer key identifier field; 85528221Smsmithhowever, an extended key usage field for a trusted host must 85638061Smsmithcontain the value 85738061Smsmith.Cm trustRoot ; . 85838061SmsmithOther extension fields are ignored. 85938761Snsouch.Ss Authentication Commands 86038761Snsouch.Bl -tag -width indent 86138061Smsmith.It Ic autokey Op Ar logsec 86238061SmsmithSpecifies the interval between regenerations of the session key 86338761Snsouchlist used with the Autokey protocol. 86438761SnsouchNote that the size of the key 86538061Smsmithlist for each association depends on this interval and the current 86638061Smsmithpoll interval. 86738061SmsmithThe default value is 12 (4096 s or about 1.1 hours). 86828221SmsmithFor poll intervals above the specified interval, a session key list 86938761Snsouchwith a single entry will be regenerated for every message 87038761Snsouchsent. 87128221Smsmith.It Ic controlkey Ar key 87228221SmsmithSpecifies the key identifier to use with the 87338061Smsmith.Xr ntpq @NTPQ_MS@ 87428221Smsmithutility, which uses the standard 87528221Smsmithprotocol defined in RFC\-1305. 87642475SnsouchThe 87742475Snsouch.Ar key 87842475Snsouchargument is 87942475Snsouchthe key identifier for a trusted key, where the value can be in the 88042475Snsouchrange 1 to 65,534, inclusive. 88142475Snsouch.It Xo Ic crypto 88242475Snsouch.Op Cm cert Ar file 88328221Smsmith.Op Cm leap Ar file 88438061Smsmith.Op Cm randfile Ar file 88538061Smsmith.Op Cm host Ar file 88638061Smsmith.Op Cm sign Ar file 88738061Smsmith.Op Cm gq Ar file 88839135Snsouch.Op Cm gqpar Ar file 88928221Smsmith.Op Cm iffpar Ar file 89028221Smsmith.Op Cm mvpar Ar file 89128221Smsmith.Op Cm pw Ar password 89228221Smsmith.Xc 89328221SmsmithThis command requires the OpenSSL library. 89428221SmsmithIt activates public key 89528221Smsmithcryptography, selects the message digest and signature 89628221Smsmithencryption scheme and loads the required private and public 89728221Smsmithvalues described above. 89828221SmsmithIf one or more files are left unspecified, 89928221Smsmiththe default names are used as described above. 90028221SmsmithUnless the complete path and name of the file are specified, the 90128221Smsmithlocation of a file is relative to the keys directory specified 90228221Smsmithin the 903247066Simp.Ic keysdir 90428221Smsmithcommand or default 90555939Snsouch.Pa /usr/local/etc . 90655939SnsouchFollowing are the subcommands: 90728221Smsmith.Bl -tag -width indent 90838061Smsmith.It Cm cert Ar file 90938061SmsmithSpecifies the location of the required host public certificate file. 91028221SmsmithThis overrides the link 91138061Smsmith.Pa ntpkey_cert_ Ns Ar hostname 91263403Sdfrin the keys directory. 91363403Sdfr.It Cm gqpar Ar file 91463403SdfrSpecifies the location of the optional GQ parameters file. 91563403SdfrThis 91663403Sdfroverrides the link 91763403Sdfr.Pa ntpkey_gq_ Ns Ar hostname 91863403Sdfrin the keys directory. 91963403Sdfr.It Cm host Ar file 920247066SimpSpecifies the location of the required host key file. 92163403SdfrThis overrides 92263403Sdfrthe link 923247066Simp.Pa ntpkey_key_ Ns Ar hostname 92463403Sdfrin the keys directory. 92563403Sdfr.It Cm iffpar Ar file 92663403SdfrSpecifies the location of the optional IFF parameters file. 92763403SdfrThis overrides the link 92863403Sdfr.Pa ntpkey_iff_ Ns Ar hostname 92963403Sdfrin the keys directory. 93063403Sdfr.It Cm leap Ar file 93163403SdfrSpecifies the location of the optional leapsecond file. 93263403SdfrThis overrides the link 93363403Sdfr.Pa ntpkey_leap 93463403Sdfrin the keys directory. 93563403Sdfr.It Cm mvpar Ar file 93663403SdfrSpecifies the location of the optional MV parameters file. 937185003SjhbThis overrides the link 93863403Sdfr.Pa ntpkey_mv_ Ns Ar hostname 93963403Sdfrin the keys directory. 94063403Sdfr.It Cm pw Ar password 94163403SdfrSpecifies the password to decrypt files containing private keys and 94263403Sdfridentity parameters. 94363403SdfrThis is required only if these files have been 94463403Sdfrencrypted. 94563403Sdfr.It Cm randfile Ar file 94663403SdfrSpecifies the location of the random seed file used by the OpenSSL 94763403Sdfrlibrary. 94863403SdfrThe defaults are described in the main text above. 94963403Sdfr.It Cm sign Ar file 95063403SdfrSpecifies the location of the optional sign key file. 95163403SdfrThis overrides 95263403Sdfrthe link 95363403Sdfr.Pa ntpkey_sign_ Ns Ar hostname 95463403Sdfrin the keys directory. 95563403SdfrIf this file is 95663403Sdfrnot found, the host key is also the sign key. 95763403Sdfr.El 95863403Sdfr.It Ic keys Ar keyfile 95963403SdfrSpecifies the complete path and location of the MD5 key file 96063403Sdfrcontaining the keys and key identifiers used by 96163403Sdfr.Xr ntpd @NTPD_MS@ , 96263403Sdfr.Xr ntpq @NTPQ_MS@ 96363403Sdfrand 96463403Sdfr.Xr ntpdc @NTPDC_MS@ 96563403Sdfrwhen operating with symmetric key cryptography. 96663403SdfrThis is the same operation as the 96763403Sdfr.Fl k 96863403Sdfrcommand line option. 96963403Sdfr.It Ic keysdir Ar path 97063403SdfrThis command specifies the default directory path for 97163403Sdfrcryptographic keys, parameters and certificates. 97263403SdfrThe default is 97363403Sdfr.Pa /usr/local/etc/ . 97463403Sdfr.It Ic requestkey Ar key 97563403SdfrSpecifies the key identifier to use with the 97663403Sdfr.Xr ntpdc @NTPDC_MS@ 97763403Sdfrutility program, which uses a 97863403Sdfrproprietary protocol specific to this implementation of 97963403Sdfr.Xr ntpd @NTPD_MS@ . 98063403SdfrThe 98163403Sdfr.Ar key 98263403Sdfrargument is a key identifier 98363403Sdfrfor the trusted key, where the value can be in the range 1 to 98463403Sdfr65,534, inclusive. 98563403Sdfr.It Ic revoke Ar logsec 98663403SdfrSpecifies the interval between re\-randomization of certain 98763403Sdfrcryptographic values used by the Autokey scheme, as a power of 2 in 98863403Sdfrseconds. 98963403SdfrThese values need to be updated frequently in order to 99063403Sdfrdeflect brute\-force attacks on the algorithms of the scheme; 99163403Sdfrhowever, updating some values is a relatively expensive operation. 99263403SdfrThe default interval is 16 (65,536 s or about 18 hours). 99363403SdfrFor poll 99463403Sdfrintervals above the specified interval, the values will be updated 99563403Sdfrfor every message sent. 99638061Smsmith.It Ic trustedkey Ar key ... 99738061SmsmithSpecifies the key identifiers which are trusted for the 99838061Smsmithpurposes of authenticating peers with symmetric key cryptography, 99938061Smsmithas well as keys used by the 100038061Smsmith.Xr ntpq @NTPQ_MS@ 100138061Smsmithand 100238061Smsmith.Xr ntpdc @NTPDC_MS@ 100338061Smsmithprograms. 100438061SmsmithThe authentication procedures require that both the local 100538061Smsmithand remote servers share the same key and key identifier for this 1006185003Sjhbpurpose, although different keys can be used with different 100738061Smsmithservers. 100838061SmsmithThe 100938061Smsmith.Ar key 101038061Smsmitharguments are 32\-bit unsigned 101138061Smsmithintegers with values from 1 to 65,534. 101238061Smsmith.El 101341591Sarchie.Ss Error Codes 101438061SmsmithThe following error codes are reported via the NTP control 101538061Smsmithand monitoring protocol trap mechanism. 101638061Smsmith.Bl -tag -width indent 101738061Smsmith.It 101 101838061Smsmith.Pq bad field format or length 101938061SmsmithThe packet has invalid version, length or format. 102038061Smsmith.It 102 102138061Smsmith.Pq bad timestamp 102238061SmsmithThe packet timestamp is the same or older than the most recent received. 102338061SmsmithThis could be due to a replay or a server clock time step. 102438061Smsmith.It 103 102538061Smsmith.Pq bad filestamp 102638061SmsmithThe packet filestamp is the same or older than the most recent received. 102738061SmsmithThis could be due to a replay or a key file generation error. 102838061Smsmith.It 104 102938061Smsmith.Pq bad or missing public key 103038061SmsmithThe public key is missing, has incorrect format or is an unsupported type. 103128221Smsmith.It 105 103238061Smsmith.Pq unsupported digest type 103338061SmsmithThe server requires an unsupported digest/signature scheme. 103438061Smsmith.It 106 103538061Smsmith.Pq mismatched digest types 103638061SmsmithNot used. 103728221Smsmith.It 107 103838061Smsmith.Pq bad signature length 103938061SmsmithThe signature length does not match the current public key. 104038061Smsmith.It 108 104128221Smsmith.Pq signature not verified 104238061SmsmithThe message fails the signature check. 104338061SmsmithIt could be bogus or signed by a 104438061Smsmithdifferent private key. 104538061Smsmith.It 109 104638061Smsmith.Pq certificate not verified 104738061SmsmithThe certificate is invalid or signed with the wrong key. 104838061Smsmith.It 110 104938061Smsmith.Pq certificate not verified 105038061SmsmithThe certificate is not yet valid or has expired or the signature could not 105138061Smsmithbe verified. 105238061Smsmith.It 111 105338061Smsmith.Pq bad or missing cookie 105438061SmsmithThe cookie is missing, corrupted or bogus. 105555939Snsouch.It 112 105638061Smsmith.Pq bad or missing leapseconds table 105738061SmsmithThe leapseconds table is missing, corrupted or bogus. 105838061Smsmith.It 113 105955939Snsouch.Pq bad or missing certificate 106038061SmsmithThe certificate is missing, corrupted or bogus. 106138061Smsmith.It 114 106238061Smsmith.Pq bad or missing identity 106355939SnsouchThe identity key is missing, corrupt or bogus. 106428221Smsmith.El 106528221Smsmith.Sh Monitoring Support 106638061Smsmith.Xr ntpd @NTPD_MS@ 106738061Smsmithincludes a comprehensive monitoring facility suitable 1068184176Sjhbfor continuous, long term recording of server and client 106938061Smsmithtimekeeping performance. 107038061SmsmithSee the 107138061Smsmith.Ic statistics 107238061Smsmithcommand below 107338061Smsmithfor a listing and example of each type of statistics currently 107438061Smsmithsupported. 107538061SmsmithStatistic files are managed using file generation sets 107638061Smsmithand scripts in the 107738061Smsmith.Pa ./scripts 107838061Smsmithdirectory of the source code distribution. 107938061SmsmithUsing 108038061Smsmiththese facilities and 108138061Smsmith.Ux 108238061Smsmith.Xr cron 8 108338061Smsmithjobs, the data can be 108438061Smsmithautomatically summarized and archived for retrospective analysis. 108528221Smsmith.Ss Monitoring Commands 108655939Snsouch.Bl -tag -width indent 108738761Snsouch.It Ic statistics Ar name ... 108838061SmsmithEnables writing of statistics records. 108938061SmsmithCurrently, eight kinds of 109028221Smsmith.Ar name 109138061Smsmithstatistics are supported. 109238061Smsmith.Bl -tag -width indent 109338061Smsmith.It Cm clockstats 109428221SmsmithEnables recording of clock driver statistics information. 109538061SmsmithEach update 109638061Smsmithreceived from a clock driver appends a line of the following form to 109738061Smsmiththe file generation set named 109838061Smsmith.Cm clockstats : 109938061Smsmith.Bd -literal 110038061Smsmith49213 525.624 127.127.4.1 93 226 00:08:29.606 D 110138061Smsmith.Ed 1102184176Sjhb.Pp 1103184176SjhbThe first two fields show the date (Modified Julian Day) and time 110438061Smsmith(seconds and fraction past UTC midnight). 110538061SmsmithThe next field shows the 110638061Smsmithclock address in dotted\-quad notation. 110738061SmsmithThe final field shows the last 110838061Smsmithtimecode received from the clock in decoded ASCII format, where 110938061Smsmithmeaningful. 111038061SmsmithIn some clock drivers a good deal of additional information 1111184176Sjhbcan be gathered and displayed as well. 1112184130SjhbSee information specific to each 111338061Smsmithclock for further details. 111438061Smsmith.It Cm cryptostats 111538061SmsmithThis option requires the OpenSSL cryptographic software library. 111638061SmsmithIt 111738761Snsouchenables recording of cryptographic public key protocol information. 1118184176SjhbEach message received by the protocol module appends a line of the 111938061Smsmithfollowing form to the file generation set named 112038061Smsmith.Cm cryptostats : 112138061Smsmith.Bd -literal 112238061Smsmith49213 525.624 127.127.4.1 message 112338761Snsouch.Ed 1124184176Sjhb.Pp 112538061SmsmithThe first two fields show the date (Modified Julian Day) and time 112638061Smsmith(seconds and fraction past UTC midnight). 112738061SmsmithThe next field shows the peer 112838061Smsmithaddress in dotted\-quad notation, The final message field includes the 112955939Snsouchmessage type and certain ancillary information. 113038761SnsouchSee the 113138761Snsouch.Sx Authentication Options 1132184176Sjhbsection for further information. 113338061Smsmith.It Cm loopstats 113438061SmsmithEnables recording of loop filter statistics information. 113587599SobrienEach 113638061Smsmithupdate of the local clock outputs a line of the following form to 113738061Smsmiththe file generation set named 113838061Smsmith.Cm loopstats : 113938061Smsmith.Bd -literal 114038061Smsmith50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 114138061Smsmith.Ed 114238061Smsmith.Pp 114338061SmsmithThe first two fields show the date (Modified Julian Day) and 114438061Smsmithtime (seconds and fraction past UTC midnight). 114538061SmsmithThe next five fields 114638061Smsmithshow time offset (seconds), frequency offset (parts per million \- 114738061SmsmithPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 114838061Smsmithdiscipline time constant. 114938061Smsmith.It Cm peerstats 115038761SnsouchEnables recording of peer statistics information. 115138061SmsmithThis includes 115238761Snsouchstatistics records of all peers of a NTP server and of special 1153184176Sjhbsignals, where present and configured. 1154184176SjhbEach valid update appends a 115538761Snsouchline of the following form to the current element of a file 115655939Snsouchgeneration set named 115738761Snsouch.Cm peerstats : 115838761Snsouch.Bd -literal 115938061Smsmith48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674 116038761Snsouch.Ed 1161184176Sjhb.Pp 116238761SnsouchThe first two fields show the date (Modified Julian Day) and 116338061Smsmithtime (seconds and fraction past UTC midnight). 116438061SmsmithThe next two fields 116538061Smsmithshow the peer address in dotted\-quad notation and status, 116638761Snsouchrespectively. 1167184176SjhbThe status field is encoded in hex in the format 116838061Smsmithdescribed in Appendix A of the NTP specification RFC 1305. 116938061SmsmithThe final four fields show the offset, 117028221Smsmithdelay, dispersion and RMS jitter, all in seconds. 117138761Snsouch.It Cm rawstats 117238061SmsmithEnables recording of raw\-timestamp statistics information. 117338061SmsmithThis 117428221Smsmithincludes statistics records of all peers of a NTP server and of 117555939Snsouchspecial signals, where present and configured. 117655939SnsouchEach NTP message 117755939Snsouchreceived from a peer or clock driver appends a line of the 117855939Snsouchfollowing form to the file generation set named 117955939Snsouch.Cm rawstats : 118055939Snsouch.Bd -literal 118155939Snsouch50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 118255939Snsouch.Ed 118328221Smsmith.Pp 118438061SmsmithThe first two fields show the date (Modified Julian Day) and 118528221Smsmithtime (seconds and fraction past UTC midnight). 118655939SnsouchThe next two fields 118728221Smsmithshow the remote peer or clock address followed by the local address 118828221Smsmithin dotted\-quad notation. 118928221SmsmithThe final four fields show the originate, 119028221Smsmithreceive, transmit and final NTP timestamps in order. 119128221SmsmithThe timestamp 119238061Smsmithvalues are as received and before processing by the various data 119328221Smsmithsmoothing and mitigation algorithms. 119438761Snsouch.It Cm sysstats 119555939SnsouchEnables recording of ntpd statistics counters on a periodic basis. 119638761SnsouchEach 119738761Snsouchhour a line of the following form is appended to the file generation 1198184130Sjhbset named 119938761Snsouch.Cm sysstats : 120071622Snsouch.Bd -literal 120171622Snsouch50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 120271622Snsouch.Ed 120371622Snsouch.Pp 120471622SnsouchThe first two fields show the date (Modified Julian Day) and time 1205184130Sjhb(seconds and fraction past UTC midnight). 120628221SmsmithThe remaining ten fields show 120771622Snsouchthe statistics counter values accumulated since the last generated 120871622Snsouchline. 120971622Snsouch.Bl -tag -width indent 121028221Smsmith.It Time since restart Cm 36000 121171622SnsouchTime in hours since the system was last rebooted. 121271622Snsouch.It Packets received Cm 81965 121371622SnsouchTotal number of packets received. 121428221Smsmith.It Packets processed Cm 0 121571622SnsouchNumber of packets received in response to previous packets sent 121671622Snsouch.It Current version Cm 9546 121771622SnsouchNumber of packets matching the current NTP version. 121871622Snsouch.It Previous version Cm 56 121938761SnsouchNumber of packets matching the previous NTP version. 122071622Snsouch.It Bad version Cm 71793 122171622SnsouchNumber of packets matching neither NTP version. 122238761Snsouch.It Access denied Cm 512 122371622SnsouchNumber of packets denied access for any reason. 122471622Snsouch.It Bad length or format Cm 540 122538061SmsmithNumber of packets with invalid length, format or port number. 122671622Snsouch.It Bad authentication Cm 10 122771622SnsouchNumber of packets not verified as authentic. 122871622Snsouch.It Rate exceeded Cm 147 122971622SnsouchNumber of packets discarded due to rate limitation. 123028221Smsmith.El 123171622Snsouch.It Cm statsdir Ar directory_path 123271622SnsouchIndicates the full path of a directory where statistics files 123328221Smsmithshould be created (see below). 123471622SnsouchThis keyword allows 123538061Smsmiththe (otherwise constant) 123671622Snsouch.Cm filegen 123771622Snsouchfilename prefix to be modified for file generation sets, which 123838061Smsmithis useful for handling statistics logs. 123938761Snsouch.It Cm filegen Ar name Xo 124038761Snsouch.Op Cm file Ar filename 124138061Smsmith.Op Cm type Ar typename 124255939Snsouch.Op Cm link | nolink 124355939Snsouch.Op Cm enable | disable 124455939Snsouch.Xc 124555939SnsouchConfigures setting of generation file set name. 124655939SnsouchGeneration 124755939Snsouchfile sets provide a means for handling files that are 124855939Snsouchcontinuously growing during the lifetime of a server. 124955939SnsouchServer statistics are a typical example for such files. 125038761SnsouchGeneration file sets provide access to a set of files used 125138061Smsmithto store the actual data. 125228221SmsmithAt any time at most one element 125328221Smsmithof the set is being written to. 125428221SmsmithThe type given specifies 125528221Smsmithwhen and how data will be directed to a new element of the set. 125628221SmsmithThis way, information stored in elements of a file set 125728221Smsmiththat are currently unused are available for administrational 125828221Smsmithoperations without the risk of disturbing the operation of ntpd. 125928221Smsmith(Most important: they can be removed to free space for new data 126038061Smsmithproduced.) 126128221Smsmith.Pp 126255939SnsouchNote that this command can be sent from the 126338061Smsmith.Xr ntpdc @NTPDC_MS@ 126428221Smsmithprogram running at a remote location. 126538061Smsmith.Bl -tag -width indent 126638061Smsmith.It Cm name 126738061SmsmithThis is the type of the statistics records, as shown in the 126838061Smsmith.Cm statistics 126938061Smsmithcommand. 127063403Sdfr.It Cm file Ar filename 127138061SmsmithThis is the file name for the statistics records. 127238061SmsmithFilenames of set 127338061Smsmithmembers are built from three concatenated elements 127455939Snsouch.Ar Cm prefix , 127528221Smsmith.Ar Cm filename 127638061Smsmithand 127738061Smsmith.Ar Cm suffix : 127838061Smsmith.Bl -tag -width indent 127928221Smsmith.It Cm prefix 128038061SmsmithThis is a constant filename path. 128138061SmsmithIt is not subject to 128228221Smsmithmodifications via the 128355939Snsouch.Ar filegen 128438061Smsmithoption. 128538061SmsmithIt is defined by the 128638061Smsmithserver, usually specified as a compile\-time constant. 128738061SmsmithIt may, 128838061Smsmithhowever, be configurable for individual file generation sets 128940784Snsouchvia other commands. 129040784SnsouchFor example, the prefix used with 129140784Snsouch.Ar loopstats 129255939Snsouchand 129340784Snsouch.Ar peerstats 129440784Snsouchgeneration can be configured using the 129540784Snsouch.Ar statsdir 129655939Snsouchoption explained above. 129740784Snsouch.It Cm filename 129840784SnsouchThis string is directly concatenated to the prefix mentioned 129940784Snsouchabove (no intervening 130040784Snsouch.Ql / ) . 130140784SnsouchThis can be modified using 130240784Snsouchthe file argument to the 130338061Smsmith.Ar filegen 130438061Smsmithstatement. 130555939SnsouchNo 130628221Smsmith.Pa .. 130742475Snsouchelements are 130842475Snsouchallowed in this component to prevent filenames referring to 130942475Snsouchparts outside the filesystem hierarchy denoted by 131042475Snsouch.Ar prefix . 131128221Smsmith.It Cm suffix 131228221SmsmithThis part is reflects individual elements of a file set. 131328221SmsmithIt is 131428221Smsmithgenerated according to the type of a file set. 131538061Smsmith.El 131638061Smsmith.It Cm type Ar typename 131738061SmsmithA file generation set is characterized by its type. 131838061SmsmithThe following 131938061Smsmithtypes are supported: 1320118292Sambrisko.Bl -tag -width indent 132155939Snsouch.It Cm none 132238061SmsmithThe file set is actually a single plain file. 132355939Snsouch.It Cm pid 132439521SnsouchOne element of file set is used per incarnation of a ntpd 132538061Smsmithserver. 132639135SnsouchThis type does not perform any changes to file set 132738061Smsmithmembers during runtime, however it provides an easy way of 132838061Smsmithseparating files belonging to different 132939135Snsouch.Xr ntpd @NTPD_MS@ 133039135Snsouchserver incarnations. 133139135SnsouchThe set member filename is built by appending a 133239135Snsouch.Ql \&. 133338061Smsmithto concatenated 133439521Snsouch.Ar prefix 133538061Smsmithand 133638061Smsmith.Ar filename 133738061Smsmithstrings, and 1338182016Sjhbappending the decimal representation of the process ID of the 1339182016Sjhb.Xr ntpd @NTPD_MS@ 134078646Snsouchserver process. 134139521Snsouch.It Cm day 134238061SmsmithOne file generation set element is created per day. 1343187576SjhbA day is 134439521Snsouchdefined as the period between 00:00 and 24:00 UTC. 134538061SmsmithThe file set 1346185003Sjhbmember suffix consists of a 134738061Smsmith.Ql \&. 134838061Smsmithand a day specification in 134939135Snsouchthe form 135039135Snsouch.Cm YYYYMMdd . 1351185003Sjhb.Cm YYYY 135238061Smsmithis a 4\-digit year number (e.g., 1992). 1353185003Sjhb.Cm MM 135438061Smsmithis a two digit month number. 135538061Smsmith.Cm dd 135639135Snsouchis a two digit day number. 135739135SnsouchThus, all information written at 10 December 1992 would end up 135839135Snsouchin a file named 135939135Snsouch.Ar prefix 136039135Snsouch.Ar filename Ns .19921210 . 136139135Snsouch.It Cm week 136239135SnsouchAny file set member contains data related to a certain week of 136339135Snsoucha year. 136439135SnsouchThe term week is defined by computing day\-of\-year 136539135Snsouchmodulo 7. 136639135SnsouchElements of such a file generation set are 136739135Snsouchdistinguished by appending the following suffix to the file set 136839135Snsouchfilename base: A dot, a 4\-digit year number, the letter 136938061Smsmith.Cm W , 137038061Smsmithand a 2\-digit week number. 137138061SmsmithFor example, information from January, 1372185003Sjhb10th 1992 would end up in a file with suffix 137339135Snsouch.No . Ns Ar 1992W1 . 137439135Snsouch.It Cm month 137539135SnsouchOne generation file set element is generated per month. 137639135SnsouchThe 137739135Snsouchfile name suffix consists of a dot, a 4\-digit year number, and 137839135Snsoucha 2\-digit month. 137939135Snsouch.It Cm year 138039135SnsouchOne generation file element is generated per year. 138139135SnsouchThe filename 138239135Snsouchsuffix consists of a dot and a 4 digit year number. 138339135Snsouch.It Cm age 138439135SnsouchThis type of file generation sets changes to a new element of 138539135Snsouchthe file set every 24 hours of server operation. 138639135SnsouchThe filename 138738061Smsmithsuffix consists of a dot, the letter 1388185003Sjhb.Cm a , 138938061Smsmithand an 8\-digit number. 1390185003SjhbThis number is taken to be the number of seconds the server is 139138061Smsmithrunning at the start of the corresponding 24\-hour period. 139239135SnsouchInformation is only written to a file generation by specifying 139338061Smsmith.Cm enable ; 1394185003Sjhboutput is prevented by specifying 139538061Smsmith.Cm disable . 139638061Smsmith.El 1397185003Sjhb.It Cm link | nolink 1398185003SjhbIt is convenient to be able to access the current element of a file 139938061Smsmithgeneration set by a fixed name. 140038061SmsmithThis feature is enabled by 140138061Smsmithspecifying 140239135Snsouch.Cm link 140338061Smsmithand disabled using 140438061Smsmith.Cm nolink . 140538061SmsmithIf link is specified, a 140638061Smsmithhard link from the current file set element to a file without 140738061Smsmithsuffix is created. 140838061SmsmithWhen there is already a file with this name and 140938061Smsmiththe number of links of this file is one, it is renamed appending a 141038061Smsmithdot, the letter 141139135Snsouch.Cm C , 1412187576Sjhband the pid of the 1413187576Sjhb.Xr ntpd @NTPD_MS@ 1414166909Sjhbserver process. 1415187576SjhbWhen the 1416187576Sjhbnumber of links is greater than one, the file is unlinked. 141738061SmsmithThis 141839135Snsouchallows the current file to be accessed by a constant name. 141938061Smsmith.It Cm enable \&| Cm disable 142038061SmsmithEnables or disables the recording function. 142138061Smsmith.El 142238061Smsmith.El 142338061Smsmith.El 142438061Smsmith.Sh Access Control Support 142539135SnsouchThe 142638061Smsmith.Xr ntpd @NTPD_MS@ 142738061Smsmithdaemon implements a general purpose address/mask based restriction 142838061Smsmithlist. 142938061SmsmithThe list contains address/match entries sorted first 143038061Smsmithby increasing address values and and then by increasing mask values. 143138061SmsmithA match occurs when the bitwise AND of the mask and the packet 143238061Smsmithsource address is equal to the bitwise AND of the mask and 1433185003Sjhbaddress in the list. 1434185003SjhbThe list is searched in order with the 143538061Smsmithlast match found defining the restriction flags associated 1436185003Sjhbwith the entry. 143738061SmsmithAdditional information and examples can be found in the 1438185003Sjhb.Qq Notes on Configuring NTP and Setting up a NTP Subnet 1439185003Sjhbpage 1440185003Sjhb(available as part of the HTML documentation 144143433Snsouchprovided in 1442185003Sjhb.Pa /usr/share/doc/ntp ) . 144338061Smsmith.Pp 1444185003SjhbThe restriction facility was implemented in conformance 1445185003Sjhbwith the access policies for the original NSFnet backbone 1446185003Sjhbtime servers. 1447185003SjhbLater the facility was expanded to deflect 144843433Snsouchcryptographic and clogging attacks. 1449185003SjhbWhile this facility may 145038061Smsmithbe useful for keeping unwanted or broken or malicious clients 1451185003Sjhbfrom congesting innocent servers, it should not be considered 1452185003Sjhban alternative to the NTP authentication facilities. 1453185003SjhbSource address based restrictions are easily circumvented 1454185003Sjhbby a determined cracker. 145543433Snsouch.Pp 1456185003SjhbClients can be denied service because they are explicitly 145738061Smsmithincluded in the restrict list created by the 145839135Snsouch.Ic restrict 145939135Snsouchcommand 146039135Snsouchor implicitly as the result of cryptographic or rate limit 146139135Snsouchviolations. 146239521SnsouchCryptographic violations include certificate 146343433Snsouchor identity verification failure; rate limit violations generally 146439135Snsouchresult from defective NTP implementations that send packets 146539135Snsouchat abusive rates. 146638061SmsmithSome violations cause denied service 146738061Smsmithonly for the offending packet, others cause denied service 146838061Smsmithfor a timed period and others cause the denied service for 146938061Smsmithan indefinite period. 147038061SmsmithWhen a client or network is denied access 147139135Snsouchfor an indefinite period, the only way at present to remove 147238061Smsmiththe restrictions is by restarting the server. 147338061Smsmith.Ss The Kiss\-of\-Death Packet 147438061SmsmithOrdinarily, packets denied service are simply dropped with no 147538061Smsmithfurther action except incrementing statistics counters. 147638061SmsmithSometimes a 147738061Smsmithmore proactive response is needed, such as a server message that 147839135Snsouchexplicitly requests the client to stop sending and leave a message 147938061Smsmithfor the system operator. 148038061SmsmithA special packet format has been created 148138061Smsmithfor this purpose called the "kiss\-of\-death" (KoD) packet. 148238061SmsmithKoD packets have the leap bits set unsynchronized and stratum set 148339521Snsouchto zero and the reference identifier field set to a four\-byte 148487599SobrienASCII code. 148538061SmsmithIf the 148638061Smsmith.Cm noserve 148738061Smsmithor 148838061Smsmith.Cm notrust 148938061Smsmithflag of the matching restrict list entry is set, 149039521Snsouchthe code is "DENY"; if the 149138061Smsmith.Cm limited 149238061Smsmithflag is set and the rate limit 149339521Snsouchis exceeded, the code is "RATE". 149438061SmsmithFinally, if a cryptographic violation occurs, the code is "CRYP". 149538061Smsmith.Pp 149638061SmsmithA client receiving a KoD performs a set of sanity checks to 149738061Smsmithminimize security exposure, then updates the stratum and 149838061Smsmithreference identifier peer variables, sets the access 149938061Smsmithdenied (TEST4) bit in the peer flash variable and sends 150038061Smsmitha message to the log. 150139521SnsouchAs long as the TEST4 bit is set, 150238061Smsmiththe client will send no further packets to the server. 150338061SmsmithThe only way at present to recover from this condition is 150439521Snsouchto restart the protocol at both the client and server. 150538061SmsmithThis 150638061Smsmithhappens automatically at the client when the association times out. 150738061SmsmithIt will happen at the server only if the server operator cooperates. 150838061Smsmith.Ss Access Control Commands 150938061Smsmith.Bl -tag -width indent 151038061Smsmith.It Xo Ic discard 1511185003Sjhb.Op Cm average Ar avg 1512185003Sjhb.Op Cm minimum Ar min 1513185003Sjhb.Op Cm monitor Ar prob 151438061Smsmith.Xc 151538061SmsmithSet the parameters of the 151639521Snsouch.Cm limited 151738061Smsmithfacility which protects the server from 151887599Sobrienclient abuse. 151938061SmsmithThe 152038061Smsmith.Cm average 152139521Snsouchsubcommand specifies the minimum average packet 152238061Smsmithspacing, while the 152338061Smsmith.Cm minimum 152438061Smsmithsubcommand specifies the minimum packet spacing. 152538061SmsmithPackets that violate these minima are discarded 1526185003Sjhband a kiss\-o'\-death packet returned if enabled. 1527185003SjhbThe default 1528185003Sjhbminimum average and minimum are 5 and 2, respectively. 1529185003SjhbThe 153038061Smsmith.Ic monitor 153138061Smsmithsubcommand specifies the probability of discard 153238061Smsmithfor packets that overflow the rate\-control window. 153338061Smsmith.It Xo Ic restrict address 153438061Smsmith.Op Cm mask Ar mask 153542475Snsouch.Op Ar flag ... 153655939Snsouch.Xc 153742475SnsouchThe 1538183053Sjhb.Ar address 153943990Snsouchargument expressed in 154042475Snsouchdotted\-quad form is the address of a host or network. 1541183053SjhbAlternatively, the 1542183053Sjhb.Ar address 1543183053Sjhbargument can be a valid host DNS name. 1544183053SjhbThe 1545183053Sjhb.Ar mask 1546183053Sjhbargument expressed in dotted\-quad form defaults to 1547183053Sjhb.Cm 255.255.255.255 , 1548187576Sjhbmeaning that the 1549187576Sjhb.Ar address 1550187576Sjhbis treated as the address of an individual host. 1551187576SjhbA default entry (address 1552183053Sjhb.Cm 0.0.0.0 , 1553183053Sjhbmask 1554183053Sjhb.Cm 0.0.0.0 ) 155543990Snsouchis always included and is always the first entry in the list. 155642475SnsouchNote that text string 155742475Snsouch.Cm default , 155842475Snsouchwith no mask option, may 1559153072Srube used to indicate the default entry. 156043990SnsouchIn the current implementation, 156142475Snsouch.Cm flag 156242475Snsouchalways 156342475Snsouchrestricts access, i.e., an entry with no flags indicates that free 156442475Snsouchaccess to the server is to be given. 1565187576SjhbThe flags are not orthogonal, 156642475Snsouchin that more restrictive flags will often make less restrictive 156742475Snsouchones redundant. 156842475SnsouchThe flags can generally be classed into two 156943990Snsouchcategories, those which restrict time service and those which 157043990Snsouchrestrict informational queries and attempts to do run\-time 157143990Snsouchreconfiguration of the server. 157243990SnsouchOne or more of the following flags 157343990Snsouchmay be specified: 157442475Snsouch.Bl -tag -width indent 157542475Snsouch.It Cm ignore 157642475SnsouchDeny packets of all kinds, including 157742475Snsouch.Xr ntpq @NTPQ_MS@ 157842475Snsouchand 157955939Snsouch.Xr ntpdc @NTPDC_MS@ 1580187576Sjhbqueries. 158142475Snsouch.It Cm kod 158242475SnsouchIf this flag is set when an access violation occurs, a kiss\-o'\-death 158342475Snsouch(KoD) packet is sent. 158442475SnsouchKoD packets are rate limited to no more than one 158542475Snsouchper second. 158642475SnsouchIf another KoD packet occurs within one second after the 158742475Snsouchlast one, the packet is dropped. 158842475Snsouch.It Cm limited 158942475SnsouchDeny service if the packet spacing violates the lower limits specified 159042475Snsouchin the 159142475Snsouch.Ic discard 159242475Snsouchcommand. 159342475SnsouchA history of clients is kept using the 159442475Snsouchmonitoring capability of 159542475Snsouch.Xr ntpd @NTPD_MS@ . 159642475SnsouchThus, monitoring is always active as 159742475Snsouchlong as there is a restriction entry with the 159842475Snsouch.Cm limited 159942475Snsouchflag. 160042475Snsouch.It Cm lowpriotrap 160142475SnsouchDeclare traps set by matching hosts to be low priority. 160242475SnsouchThe 160342475Snsouchnumber of traps a server can maintain is limited (the current limit 1604158005Smarcelis 3). 160542475SnsouchTraps are usually assigned on a first come, first served 160642475Snsouchbasis, with later trap requestors being denied service. 160742475SnsouchThis flag 1608111748Sdesmodifies the assignment algorithm by allowing low priority traps to 160942475Snsouchbe overridden by later requests for normal priority traps. 161042475Snsouch.It Cm nomodify 161142475SnsouchDeny 161242475Snsouch.Xr ntpq @NTPQ_MS@ 161342475Snsouchand 161442475Snsouch.Xr ntpdc @NTPDC_MS@ 161542475Snsouchqueries which attempt to modify the state of the 1616187576Sjhbserver (i.e., run time reconfiguration). 161742475SnsouchQueries which return 161842475Snsouchinformation are permitted. 161942475Snsouch.It Cm noquery 162042475SnsouchDeny 1621118292Sambrisko.Xr ntpq @NTPQ_MS@ 162255939Snsouchand 162342475Snsouch.Xr ntpdc @NTPDC_MS@ 162442475Snsouchqueries. 162542475SnsouchTime service is not affected. 162642475Snsouch.It Cm nopeer 1627118292SambriskoDeny packets which would result in mobilizing a new association. 162855939SnsouchThis 162942475Snsouchincludes broadcast and symmetric active packets when a configured 1630158005Smarcelassociation does not exist. 163142475SnsouchIt also includes 163242475Snsouch.Cm pool 1633188173Simpassociations, so if you want to use servers from a 163455939Snsouch.Cm pool 163538061Smsmithdirective and also want to use 163655939Snsouch.Cm nopeer 1637185003Sjhbby default, you'll want a 1638187576Sjhb.Cm "restrict source ..." line as well that does 163955939Snsouch.It not 164038061Smsmithinclude the 1641188173Simp.Cm nopeer 164255939Snsouchdirective. 164338061Smsmith.It Cm noserve 1644118292SambriskoDeny all packets except 164555939Snsouch.Xr ntpq @NTPQ_MS@ 164655939Snsouchand 164755939Snsouch.Xr ntpdc @NTPDC_MS@ 164838061Smsmithqueries. 1649187576Sjhb.It Cm notrap 165055939SnsouchDecline to provide mode 6 control message trap service to matching 165155939Snsouchhosts. 165255939SnsouchThe trap service is a subsystem of the 165355939Snsouch.Xr ntpq @NTPQ_MS@ 165442475Snsouchcontrol message 165555939Snsouchprotocol which is intended for use by remote event logging programs. 165655939Snsouch.It Cm notrust 165755939SnsouchDeny service unless the packet is cryptographically authenticated. 165855939Snsouch.It Cm ntpport 165938761SnsouchThis is actually a match algorithm modifier, rather than a 166038761Snsouchrestriction flag. 166155939SnsouchIts presence causes the restriction entry to be 166255939Snsouchmatched only if the source port in the packet is the standard NTP 166338061SmsmithUDP port (123). 166438061SmsmithBoth 1665118292Sambrisko.Cm ntpport 1666158005Smarceland 1667118292Sambrisko.Cm non\-ntpport 1668118292Sambriskomay 1669118292Sambriskobe specified. 1670158005SmarcelThe 1671158005Smarcel.Cm ntpport 1672158005Smarcelis considered more specific and 1673118292Sambriskois sorted later in the list. 1674158005Smarcel.It Cm version 1675118292SambriskoDeny packets that do not match the current NTP version. 1676118292Sambrisko.El 1677118292Sambrisko.Pp 1678118292SambriskoDefault restriction list entries with the flags ignore, interface, 167955939Snsouchntpport, for each of the local host's interface addresses are 168055939Snsouchinserted into the table at startup to prevent the server 168155939Snsouchfrom attempting to synchronize to its own time. 168255939SnsouchA default entry is also always present, though if it is 168355939Snsouchotherwise unconfigured; no flags are associated 168438761Snsouchwith the default entry (i.e., everything besides your own 1685158005SmarcelNTP server is unrestricted). 168638761Snsouch.El 168755939Snsouch.Sh Automatic NTP Configuration Options 1688158005Smarcel.Ss Manycasting 168938761SnsouchManycasting is a automatic discovery and configuration paradigm 169056617Sdfrnew to NTPv4. 169128221SmsmithIt is intended as a means for a multicast client 169228221Smsmithto troll the nearby network neighborhood to find cooperating 169328221Smsmithmanycast servers, validate them using cryptographic means 169456617Sdfrand evaluate their time values with respect to other servers 1695158005Smarcelthat might be lurking in the vicinity. 1696158005SmarcelThe intended result is that each manycast client mobilizes 1697158005Smarcelclient associations with some number of the "best" 1698158005Smarcelof the nearby manycast servers, yet automatically reconfigures 1699158005Smarcelto sustain this number of servers should one or another fail. 1700158005Smarcel.Pp 1701158005SmarcelNote that the manycasting paradigm does not coincide 1702185003Sjhbwith the anycast paradigm described in RFC\-1546, 1703158005Smarcelwhich is designed to find a single server from a clique 1704158005Smarcelof servers providing the same service. 1705185003SjhbThe manycast paradigm is designed to find a plurality 1706185003Sjhbof redundant servers satisfying defined optimality criteria. 1707185003Sjhb.Pp 170842475SnsouchManycasting can be used with either symmetric key 1709185003Sjhbor public key cryptography. 1710185003SjhbThe public key infrastructure (PKI) 171155939Snsouchoffers the best protection against compromised keys 171255939Snsouchand is generally considered stronger, at least with relatively 1713185003Sjhblarge key sizes. 171455939SnsouchIt is implemented using the Autokey protocol and 1715158005Smarcelthe OpenSSL cryptographic library available from 1716158005Smarcel.Li http://www.openssl.org/ . 171763403SdfrThe library can also be used with other NTPv4 modes 171828221Smsmithas well and is highly recommended, especially for broadcast modes. 171956617Sdfr.Pp 172028221SmsmithA persistent manycast client association is configured 172155939Snsouchusing the 172263403Sdfr.Ic manycastclient 172363403Sdfrcommand, which is similar to the 172455939Snsouch.Ic server 172556617Sdfrcommand but with a multicast (IPv4 class 172663403Sdfr.Cm D 172728221Smsmithor IPv6 prefix 172863403Sdfr.Cm FF ) 172962061Sdfrgroup address. 173063403SdfrThe IANA has designated IPv4 address 224.1.1.1 173163403Sdfrand IPv6 address FF05::101 (site local) for NTP. 173263403SdfrWhen more servers are needed, it broadcasts manycast 173363403Sdfrclient messages to this address at the minimum feasible rate 173463403Sdfrand minimum feasible time\-to\-live (TTL) hops, depending 173563403Sdfron how many servers have already been found. 173663403SdfrThere can be as many manycast client associations 173763403Sdfras different group address, each one serving as a template 173863403Sdfrfor a future ephemeral unicast client/server association. 173963403Sdfr.Pp 174063403SdfrManycast servers configured with the 174163403Sdfr.Ic manycastserver 174263403Sdfrcommand listen on the specified group address for manycast 174363403Sdfrclient messages. 174462061SdfrNote the distinction between manycast client, 174560544Sdfrwhich actively broadcasts messages, and manycast server, 174660544Sdfrwhich passively responds to them. 174760544SdfrIf a manycast server is 174855939Snsouchin scope of the current TTL and is itself synchronized 174928221Smsmithto a valid source and operating at a stratum level equal 175055939Snsouchto or lower than the manycast client, it replies to the 1751127135Snjlmanycast client message with an ordinary unicast server message. 1752127135Snjl.Pp 1753127135SnjlThe manycast client receiving this message mobilizes 1754127135Snjlan ephemeral client/server association according to the 1755127135Snjlmatching manycast client template, but only if cryptographically 1756127135Snjlauthenticated and the server stratum is less than or equal 175755939Snsouchto the client stratum. 175840784SnsouchAuthentication is explicitly required 175955939Snsouchand either symmetric key or public key (Autokey) can be used. 176056617SdfrThen, the client polls the server at its unicast address 176155939Snsouchin burst mode in order to reliably set the host clock 176256617Sdfrand validate the source. 176328221SmsmithThis normally results 1764184130Sjhbin a volley of eight client/server at 2\-s intervals 176555939Snsouchduring which both the synchronization and cryptographic 176628221Smsmithprotocols run concurrently. 176755939SnsouchFollowing the volley, 176855939Snsouchthe client runs the NTP intersection and clustering 176942475Snsouchalgorithms, which act to discard all but the "best" 177055939Snsouchassociations according to stratum and synchronization 177128221Smsmithdistance. 1772158005SmarcelThe surviving associations then continue 177328221Smsmithin ordinary client/server mode. 1774158005Smarcel.Pp 1775158005SmarcelThe manycast client polling strategy is designed to reduce 1776158005Smarcelas much as possible the volume of manycast client messages 1777158005Smarceland the effects of implosion due to near\-simultaneous 1778158005Smarcelarrival of manycast server messages. 1779158005SmarcelThe strategy is determined by the 1780158005Smarcel.Ic manycastclient , 1781158005Smarcel.Ic tos 1782158005Smarceland 1783158005Smarcel.Ic ttl 1784158005Smarcelconfiguration commands. 1785158005SmarcelThe manycast poll interval is 1786158005Smarcelnormally eight times the system poll interval, 1787158005Smarcelwhich starts out at the 1788158005Smarcel.Cm minpoll 1789158005Smarcelvalue specified in the 1790158005Smarcel.Ic manycastclient , 1791158005Smarcelcommand and, under normal circumstances, increments to the 1792158005Smarcel.Cm maxpolll 1793158005Smarcelvalue specified in this command. 1794158005SmarcelInitially, the TTL is 1795158005Smarcelset at the minimum hops specified by the 1796158005Smarcel.Ic ttl 179735256Sdescommand. 179828221SmsmithAt each retransmission the TTL is increased until reaching 179955939Snsouchthe maximum hops specified by this command or a sufficient 180028221Smsmithnumber client associations have been found. 180128221SmsmithFurther retransmissions use the same TTL. 180255939Snsouch.Pp 180328221SmsmithThe quality and reliability of the suite of associations 180428221Smsmithdiscovered by the manycast client is determined by the NTP 1805158005Smarcelmitigation algorithms and the 1806158005Smarcel.Cm minclock 1807158005Smarceland 1808158005Smarcel.Cm minsane 1809158005Smarcelvalues specified in the 1810158005Smarcel.Ic tos 181155939Snsouchconfiguration command. 181255939SnsouchAt least 181355939Snsouch.Cm minsane 181455939Snsouchcandidate servers must be available and the mitigation 181555939Snsouchalgorithms produce at least 181655939Snsouch.Cm minclock 181755939Snsouchsurvivors in order to synchronize the clock. 181855939SnsouchByzantine agreement principles require at least four 181955939Snsouchcandidates in order to correctly discard a single falseticker. 182055939SnsouchFor legacy purposes, 182155939Snsouch.Cm minsane 182255939Snsouchdefaults to 1 and 182355939Snsouch.Cm minclock 182428221Smsmithdefaults to 3. 182528221SmsmithFor manycast service 1826118292Sambrisko.Cm minsane 182755939Snsouchshould be explicitly set to 4, assuming at least that 182828221Smsmithnumber of servers are available. 182955939Snsouch.Pp 1830183053SjhbIf at least 183128221Smsmith.Cm minclock 1832187576Sjhbservers are found, the manycast poll interval is immediately 1833187576Sjhbset to eight times 183455939Snsouch.Cm maxpoll . 183555939SnsouchIf less than 183655939Snsouch.Cm minclock 183755939Snsouchservers are found when the TTL has reached the maximum hops, 1838185003Sjhbthe manycast poll interval is doubled. 183942475SnsouchFor each transmission 184055939Snsouchafter that, the poll interval is doubled again until 184155939Snsouchreaching the maximum of eight times 184242475Snsouch.Cm maxpoll . 1843183053SjhbFurther transmissions use the same poll interval and 1844183053SjhbTTL values. 1845187576SjhbNote that while all this is going on, 1846187576Sjhbeach client/server association found is operating normally 1847183053Sjhbit the system poll interval. 1848183053Sjhb.Pp 1849183053SjhbAdministratively scoped multicast boundaries are normally 1850183053Sjhbspecified by the network router configuration and, 1851187576Sjhbin the case of IPv6, the link/site scope prefix. 1852183053SjhbBy default, the increment for TTL hops is 32 starting 1853183053Sjhbfrom 31; however, the 1854183053Sjhb.Ic ttl 1855183053Sjhbconfiguration command can be 185655939Snsouchused to modify the values to match the scope rules. 1857187576Sjhb.Pp 185855939SnsouchIt is often useful to narrow the range of acceptable 185928221Smsmithservers which can be found by manycast client associations. 186055939SnsouchBecause manycast servers respond only when the client 186128221Smsmithstratum is equal to or greater than the server stratum, 1862187576Sjhbprimary (stratum 1) servers fill find only primary servers 186328221Smsmithin TTL range, which is probably the most common objective. 186455939SnsouchHowever, unless configured otherwise, all manycast clients 186555939Snsouchin TTL range will eventually find all primary servers 186642475Snsouchin TTL range, which is probably not the most common 1867157774Siwasakiobjective in large networks. 1868157774SiwasakiThe 1869157774Siwasaki.Ic tos 1870157774Siwasakicommand can be used to modify this behavior. 1871157774SiwasakiServers with stratum below 1872157774Siwasaki.Cm floor 1873157774Siwasakior above 1874157774Siwasaki.Cm ceiling 1875157774Siwasakispecified in the 1876157774Siwasaki.Ic tos 1877227849Shselaskycommand are strongly discouraged during the selection 1878157774Siwasakiprocess; however, these servers may be temporally 1879157774Siwasakiaccepted if the number of servers within TTL range is 1880157774Siwasakiless than 1881157774Siwasaki.Cm minclock . 1882157774Siwasaki.Pp 1883157774SiwasakiThe above actions occur for each manycast client message, 1884157774Siwasakiwhich repeats at the designated poll interval. 1885157774SiwasakiHowever, once the ephemeral client association is mobilized, 1886157774Siwasakisubsequent manycast server replies are discarded, 1887157774Siwasakisince that would result in a duplicate association. 1888157774SiwasakiIf during a poll interval the number of client associations 1889157774Siwasakifalls below 1890157774Siwasaki.Cm minclock , 1891157774Siwasakiall manycast client prototype associations are reset 1892157774Siwasakito the initial poll interval and TTL hops and operation 1893187576Sjhbresumes from the beginning. 1894187576SjhbIt is important to avoid 1895157774Siwasakifrequent manycast client messages, since each one requires 1896157774Siwasakiall manycast servers in TTL range to respond. 1897157774SiwasakiThe result could well be an implosion, either minor or major, 1898118292Sambriskodepending on the number of servers in range. 189955939SnsouchThe recommended value for 190055939Snsouch.Cm maxpoll 190155939Snsouchis 12 (4,096 s). 1902185003Sjhb.Pp 1903187576SjhbIt is possible and frequently useful to configure a host 190455939Snsouchas both manycast client and manycast server. 190555939SnsouchA number of hosts configured this way and sharing a common 1906182016Sjhbgroup address will automatically organize themselves 190755939Snsouchin an optimum configuration based on stratum and 190855939Snsouchsynchronization distance. 1909182016SjhbFor example, consider an NTP 191055939Snsouchsubnet of two primary servers and a hundred or more 191155939Snsouchdependent clients. 1912182016SjhbWith two exceptions, all servers 191355939Snsouchand clients have identical configuration files including both 191455939Snsouch.Ic multicastclient 1915182016Sjhband 191655939Snsouch.Ic multicastserver 191755939Snsouchcommands using, for instance, multicast group address 1918182016Sjhb239.1.1.1. 191955939SnsouchThe only exception is that each primary server 192055939Snsouchconfiguration file must include commands for the primary 1921182016Sjhbreference source such as a GPS receiver. 192255939Snsouch.Pp 192355939SnsouchThe remaining configuration files for all secondary 192455939Snsouchservers and clients have the same contents, except for the 192555939Snsouch.Ic tos 192655939Snsouchcommand, which is specific for each stratum level. 192755939SnsouchFor stratum 1 and stratum 2 servers, that command is 192855939Snsouchnot necessary. 192955939SnsouchFor stratum 3 and above servers the 193055939Snsouch.Cm floor 193155939Snsouchvalue is set to the intended stratum number. 193255939SnsouchThus, all stratum 3 configuration files are identical, 193355939Snsouchall stratum 4 files are identical and so forth. 193455939Snsouch.Pp 193555939SnsouchOnce operations have stabilized in this scenario, 193655939Snsouchthe primary servers will find the primary reference source 193755939Snsouchand each other, since they both operate at the same 193855939Snsouchstratum (1), but not with any secondary server or client, 193955939Snsouchsince these operate at a higher stratum. 194055939SnsouchThe secondary 194155939Snsouchservers will find the servers at the same stratum level. 194255939SnsouchIf one of the primary servers loses its GPS receiver, 194355939Snsouchit will continue to operate as a client and other clients 194455939Snsouchwill time out the corresponding association and 194555939Snsouchre\-associate accordingly. 194655939Snsouch.Pp 194755939SnsouchSome administrators prefer to avoid running 194855939Snsouch.Xr ntpd @NTPD_MS@ 194955939Snsouchcontinuously and run either 195055939Snsouch.Xr sntp @SNTP_MS@ 195155939Snsouchor 195255939Snsouch.Xr ntpd @NTPD_MS@ 195355939Snsouch.Fl q 195455939Snsouchas a cron job. 195555939SnsouchIn either case the servers must be 195655939Snsouchconfigured in advance and the program fails if none are 195755939Snsouchavailable when the cron job runs. 195855939SnsouchA really slick 195987599Sobrienapplication of manycast is with 196055939Snsouch.Xr ntpd @NTPD_MS@ 196142475Snsouch.Fl q . 196242475SnsouchThe program wakes up, scans the local landscape looking 196355939Snsouchfor the usual suspects, selects the best from among 196455939Snsouchthe rascals, sets the clock and then departs. 196528221SmsmithServers do not have to be configured in advance and 1966118292Sambriskoall clients throughout the network can have the same 196755939Snsouchconfiguration file. 196855939Snsouch.Ss Manycast Interactions with Autokey 196955939SnsouchEach time a manycast client sends a client mode packet 197055939Snsouchto a multicast group address, all manycast servers 197155939Snsouchin scope generate a reply including the host name 197255939Snsouchand status word. 1973187576SjhbThe manycast clients then run 197455939Snsouchthe Autokey protocol, which collects and verifies 197555939Snsouchall certificates involved. 1976187576SjhbFollowing the burst interval 1977187576Sjhball but three survivors are cast off, 1978187576Sjhbbut the certificates remain in the local cache. 197955939SnsouchIt often happens that several complete signing trails 198055939Snsouchfrom the client to the primary servers are collected in this way. 198155939Snsouch.Pp 198255939SnsouchAbout once an hour or less often if the poll interval 198355939Snsouchexceeds this, the client regenerates the Autokey key list. 198428221SmsmithThis is in general transparent in client/server mode. 198555939SnsouchHowever, about once per day the server private value 1986187576Sjhbused to generate cookies is refreshed along with all 1987187576Sjhbmanycast client associations. 1988187576SjhbIn this case all 1989187576Sjhbcryptographic values including certificates is refreshed. 1990187576SjhbIf a new certificate has been generated since 1991187576Sjhbthe last refresh epoch, it will automatically revoke 1992187576Sjhball prior certificates that happen to be in the 1993187576Sjhbcertificate cache. 1994187576SjhbAt the same time, the manycast 1995187576Sjhbscheme starts all over from the beginning and 1996187576Sjhbthe expanding ring shrinks to the minimum and increments 1997187576Sjhbfrom there while collecting all servers in scope. 1998187576Sjhb.Ss Broadcast Options 1999187576Sjhb.Bl -tag -width indent 2000187576Sjhb.It Xo Ic tos 2001187576Sjhb.Oo 2002187576Sjhb.Cm bcpollbstep Ar gate 2003187576Sjhb.Oc 2004187576Sjhb.Xc 2005187576SjhbThis command provides a way to delay, 2006187576Sjhbby the specified number of broadcast poll intervals, 2007187576Sjhbbelieving backward time steps from a broadcast server. 2008187576SjhbBroadcast time networks are expected to be trusted. 2009187576SjhbIn the event a broadcast server's time is stepped backwards, 2010187576Sjhbthere is clear benefit to having the clients notice this change 2011187576Sjhbas soon as possible. 201255939SnsouchAttacks such as replay attacks can happen, however, 2013183053Sjhband even though there are a number of protections built in to 2014183053Sjhbbroadcast mode, attempts to perform a replay attack are possible. 201555939SnsouchThis value defaults to 0, but can be changed 2016183053Sjhbto any number of poll intervals between 0 and 4. 2017183053Sjhb.Ss Manycast Options 2018183053Sjhb.Bl -tag -width indent 201955939Snsouch.It Xo Ic tos 202055939Snsouch.Oo 202155939Snsouch.Cm ceiling Ar ceiling | 2022183053Sjhb.Cm cohort { 0 | 1 } | 2023183053Sjhb.Cm floor Ar floor | 2024183053Sjhb.Cm minclock Ar minclock | 2025183053Sjhb.Cm minsane Ar minsane 2026183053Sjhb.Oc 2027183053Sjhb.Xc 2028183053SjhbThis command affects the clock selection and clustering 2029183053Sjhbalgorithms. 203055939SnsouchIt can be used to select the quality and 2031183053Sjhbquantity of peers used to synchronize the system clock 2032183053Sjhband is most useful in manycast mode. 2033183053SjhbThe variables operate 2034183053Sjhbas follows: 2035183053Sjhb.Bl -tag -width indent 2036183053Sjhb.It Cm ceiling Ar ceiling 2037183053SjhbPeers with strata above 203855939Snsouch.Cm ceiling 2039183053Sjhbwill be discarded if there are at least 2040183053Sjhb.Cm minclock 2041183053Sjhbpeers remaining. 2042183053SjhbThis value defaults to 15, but can be changed 2043183053Sjhbto any number from 1 to 15. 2044183053Sjhb.It Cm cohort Bro 0 | 1 Brc 2045183053SjhbThis is a binary flag which enables (0) or disables (1) 2046183053Sjhbmanycast server replies to manycast clients with the same 204755939Snsouchstratum level. 2048183053SjhbThis is useful to reduce implosions where 204955939Snsouchlarge numbers of clients with the same stratum level 205055939Snsouchare present. 2051153610SruThe default is to enable these replies. 2052.It Cm floor Ar floor 2053Peers with strata below 2054.Cm floor 2055will be discarded if there are at least 2056.Cm minclock 2057peers remaining. 2058This value defaults to 1, but can be changed 2059to any number from 1 to 15. 2060.It Cm minclock Ar minclock 2061The clustering algorithm repeatedly casts out outlier 2062associations until no more than 2063.Cm minclock 2064associations remain. 2065This value defaults to 3, 2066but can be changed to any number from 1 to the number of 2067configured sources. 2068.It Cm minsane Ar minsane 2069This is the minimum number of candidates available 2070to the clock selection algorithm in order to produce 2071one or more truechimers for the clustering algorithm. 2072If fewer than this number are available, the clock is 2073undisciplined and allowed to run free. 2074The default is 1 2075for legacy purposes. 2076However, according to principles of 2077Byzantine agreement, 2078.Cm minsane 2079should be at least 4 in order to detect and discard 2080a single falseticker. 2081.El 2082.It Cm ttl Ar hop ... 2083This command specifies a list of TTL values in increasing 2084order, up to 8 values can be specified. 2085In manycast mode these values are used in turn 2086in an expanding\-ring search. 2087The default is eight 2088multiples of 32 starting at 31. 2089.El 2090.Sh Reference Clock Support 2091The NTP Version 4 daemon supports some three dozen different radio, 2092satellite and modem reference clocks plus a special pseudo\-clock 2093used for backup or when no other clock source is available. 2094Detailed descriptions of individual device drivers and options can 2095be found in the 2096.Qq Reference Clock Drivers 2097page 2098(available as part of the HTML documentation 2099provided in 2100.Pa /usr/share/doc/ntp ) . 2101Additional information can be found in the pages linked 2102there, including the 2103.Qq Debugging Hints for Reference Clock Drivers 2104and 2105.Qq How To Write a Reference Clock Driver 2106pages 2107(available as part of the HTML documentation 2108provided in 2109.Pa /usr/share/doc/ntp ) . 2110In addition, support for a PPS 2111signal is available as described in the 2112.Qq Pulse\-per\-second (PPS) Signal Interfacing 2113page 2114(available as part of the HTML documentation 2115provided in 2116.Pa /usr/share/doc/ntp ) . 2117Many 2118drivers support special line discipline/streams modules which can 2119significantly improve the accuracy using the driver. 2120These are 2121described in the 2122.Qq Line Disciplines and Streams Drivers 2123page 2124(available as part of the HTML documentation 2125provided in 2126.Pa /usr/share/doc/ntp ) . 2127.Pp 2128A reference clock will generally (though not always) be a radio 2129timecode receiver which is synchronized to a source of standard 2130time such as the services offered by the NRC in Canada and NIST and 2131USNO in the US. 2132The interface between the computer and the timecode 2133receiver is device dependent, but is usually a serial port. 2134A 2135device driver specific to each reference clock must be selected and 2136compiled in the distribution; however, most common radio, satellite 2137and modem clocks are included by default. 2138Note that an attempt to 2139configure a reference clock when the driver has not been compiled 2140or the hardware port has not been appropriately configured results 2141in a scalding remark to the system log file, but is otherwise non 2142hazardous. 2143.Pp 2144For the purposes of configuration, 2145.Xr ntpd @NTPD_MS@ 2146treats 2147reference clocks in a manner analogous to normal NTP peers as much 2148as possible. 2149Reference clocks are identified by a syntactically 2150correct but invalid IP address, in order to distinguish them from 2151normal NTP peers. 2152Reference clock addresses are of the form 2153.Sm off 2154.Li 127.127. Ar t . Ar u , 2155.Sm on 2156where 2157.Ar t 2158is an integer 2159denoting the clock type and 2160.Ar u 2161indicates the unit 2162number in the range 0\-3. 2163While it may seem overkill, it is in fact 2164sometimes useful to configure multiple reference clocks of the same 2165type, in which case the unit numbers must be unique. 2166.Pp 2167The 2168.Ic server 2169command is used to configure a reference 2170clock, where the 2171.Ar address 2172argument in that command 2173is the clock address. 2174The 2175.Cm key , 2176.Cm version 2177and 2178.Cm ttl 2179options are not used for reference clock support. 2180The 2181.Cm mode 2182option is added for reference clock support, as 2183described below. 2184The 2185.Cm prefer 2186option can be useful to 2187persuade the server to cherish a reference clock with somewhat more 2188enthusiasm than other reference clocks or peers. 2189Further 2190information on this option can be found in the 2191.Qq Mitigation Rules and the prefer Keyword 2192(available as part of the HTML documentation 2193provided in 2194.Pa /usr/share/doc/ntp ) 2195page. 2196The 2197.Cm minpoll 2198and 2199.Cm maxpoll 2200options have 2201meaning only for selected clock drivers. 2202See the individual clock 2203driver document pages for additional information. 2204.Pp 2205The 2206.Ic fudge 2207command is used to provide additional 2208information for individual clock drivers and normally follows 2209immediately after the 2210.Ic server 2211command. 2212The 2213.Ar address 2214argument specifies the clock address. 2215The 2216.Cm refid 2217and 2218.Cm stratum 2219options can be used to 2220override the defaults for the device. 2221There are two optional 2222device\-dependent time offsets and four flags that can be included 2223in the 2224.Ic fudge 2225command as well. 2226.Pp 2227The stratum number of a reference clock is by default zero. 2228Since the 2229.Xr ntpd @NTPD_MS@ 2230daemon adds one to the stratum of each 2231peer, a primary server ordinarily displays an external stratum of 2232one. 2233In order to provide engineered backups, it is often useful to 2234specify the reference clock stratum as greater than zero. 2235The 2236.Cm stratum 2237option is used for this purpose. 2238Also, in cases 2239involving both a reference clock and a pulse\-per\-second (PPS) 2240discipline signal, it is useful to specify the reference clock 2241identifier as other than the default, depending on the driver. 2242The 2243.Cm refid 2244option is used for this purpose. 2245Except where noted, 2246these options apply to all clock drivers. 2247.Ss Reference Clock Commands 2248.Bl -tag -width indent 2249.It Xo Ic server 2250.Sm off 2251.Li 127.127. Ar t . Ar u 2252.Sm on 2253.Op Cm prefer 2254.Op Cm mode Ar int 2255.Op Cm minpoll Ar int 2256.Op Cm maxpoll Ar int 2257.Xc 2258This command can be used to configure reference clocks in 2259special ways. 2260The options are interpreted as follows: 2261.Bl -tag -width indent 2262.It Cm prefer 2263Marks the reference clock as preferred. 2264All other things being 2265equal, this host will be chosen for synchronization among a set of 2266correctly operating hosts. 2267See the 2268.Qq Mitigation Rules and the prefer Keyword 2269page 2270(available as part of the HTML documentation 2271provided in 2272.Pa /usr/share/doc/ntp ) 2273for further information. 2274.It Cm mode Ar int 2275Specifies a mode number which is interpreted in a 2276device\-specific fashion. 2277For instance, it selects a dialing 2278protocol in the ACTS driver and a device subtype in the 2279parse 2280drivers. 2281.It Cm minpoll Ar int 2282.It Cm maxpoll Ar int 2283These options specify the minimum and maximum polling interval 2284for reference clock messages, as a power of 2 in seconds 2285For 2286most directly connected reference clocks, both 2287.Cm minpoll 2288and 2289.Cm maxpoll 2290default to 6 (64 s). 2291For modem reference clocks, 2292.Cm minpoll 2293defaults to 10 (17.1 m) and 2294.Cm maxpoll 2295defaults to 14 (4.5 h). 2296The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2297.El 2298.It Xo Ic fudge 2299.Sm off 2300.Li 127.127. Ar t . Ar u 2301.Sm on 2302.Op Cm time1 Ar sec 2303.Op Cm time2 Ar sec 2304.Op Cm stratum Ar int 2305.Op Cm refid Ar string 2306.Op Cm mode Ar int 2307.Op Cm flag1 Cm 0 \&| Cm 1 2308.Op Cm flag2 Cm 0 \&| Cm 1 2309.Op Cm flag3 Cm 0 \&| Cm 1 2310.Op Cm flag4 Cm 0 \&| Cm 1 2311.Xc 2312This command can be used to configure reference clocks in 2313special ways. 2314It must immediately follow the 2315.Ic server 2316command which configures the driver. 2317Note that the same capability 2318is possible at run time using the 2319.Xr ntpdc @NTPDC_MS@ 2320program. 2321The options are interpreted as 2322follows: 2323.Bl -tag -width indent 2324.It Cm time1 Ar sec 2325Specifies a constant to be added to the time offset produced by 2326the driver, a fixed\-point decimal number in seconds. 2327This is used 2328as a calibration constant to adjust the nominal time offset of a 2329particular clock to agree with an external standard, such as a 2330precision PPS signal. 2331It also provides a way to correct a 2332systematic error or bias due to serial port or operating system 2333latencies, different cable lengths or receiver internal delay. 2334The 2335specified offset is in addition to the propagation delay provided 2336by other means, such as internal DIPswitches. 2337Where a calibration 2338for an individual system and driver is available, an approximate 2339correction is noted in the driver documentation pages. 2340Note: in order to facilitate calibration when more than one 2341radio clock or PPS signal is supported, a special calibration 2342feature is available. 2343It takes the form of an argument to the 2344.Ic enable 2345command described in 2346.Sx Miscellaneous Options 2347page and operates as described in the 2348.Qq Reference Clock Drivers 2349page 2350(available as part of the HTML documentation 2351provided in 2352.Pa /usr/share/doc/ntp ) . 2353.It Cm time2 Ar secs 2354Specifies a fixed\-point decimal number in seconds, which is 2355interpreted in a driver\-dependent way. 2356See the descriptions of 2357specific drivers in the 2358.Qq Reference Clock Drivers 2359page 2360(available as part of the HTML documentation 2361provided in 2362.Pa /usr/share/doc/ntp ) . 2363.It Cm stratum Ar int 2364Specifies the stratum number assigned to the driver, an integer 2365between 0 and 15. 2366This number overrides the default stratum number 2367ordinarily assigned by the driver itself, usually zero. 2368.It Cm refid Ar string 2369Specifies an ASCII string of from one to four characters which 2370defines the reference identifier used by the driver. 2371This string 2372overrides the default identifier ordinarily assigned by the driver 2373itself. 2374.It Cm mode Ar int 2375Specifies a mode number which is interpreted in a 2376device\-specific fashion. 2377For instance, it selects a dialing 2378protocol in the ACTS driver and a device subtype in the 2379parse 2380drivers. 2381.It Cm flag1 Cm 0 \&| Cm 1 2382.It Cm flag2 Cm 0 \&| Cm 1 2383.It Cm flag3 Cm 0 \&| Cm 1 2384.It Cm flag4 Cm 0 \&| Cm 1 2385These four flags are used for customizing the clock driver. 2386The 2387interpretation of these values, and whether they are used at all, 2388is a function of the particular clock driver. 2389However, by 2390convention 2391.Cm flag4 2392is used to enable recording monitoring 2393data to the 2394.Cm clockstats 2395file configured with the 2396.Ic filegen 2397command. 2398Further information on the 2399.Ic filegen 2400command can be found in 2401.Sx Monitoring Options . 2402.El 2403.El 2404.Sh Miscellaneous Options 2405.Bl -tag -width indent 2406.It Ic broadcastdelay Ar seconds 2407The broadcast and multicast modes require a special calibration 2408to determine the network delay between the local and remote 2409servers. 2410Ordinarily, this is done automatically by the initial 2411protocol exchanges between the client and server. 2412In some cases, 2413the calibration procedure may fail due to network or server access 2414controls, for example. 2415This command specifies the default delay to 2416be used under these circumstances. 2417Typically (for Ethernet), a 2418number between 0.003 and 0.007 seconds is appropriate. 2419The default 2420when this command is not used is 0.004 seconds. 2421.It Ic calldelay Ar delay 2422This option controls the delay in seconds between the first and second 2423packets sent in burst or iburst mode to allow additional time for a modem 2424or ISDN call to complete. 2425.It Ic driftfile Ar driftfile 2426This command specifies the complete path and name of the file used to 2427record the frequency of the local clock oscillator. 2428This is the same 2429operation as the 2430.Fl f 2431command line option. 2432If the file exists, it is read at 2433startup in order to set the initial frequency and then updated once per 2434hour with the current frequency computed by the daemon. 2435If the file name is 2436specified, but the file itself does not exist, the starts with an initial 2437frequency of zero and creates the file when writing it for the first time. 2438If this command is not given, the daemon will always start with an initial 2439frequency of zero. 2440.Pp 2441The file format consists of a single line containing a single 2442floating point number, which records the frequency offset measured 2443in parts\-per\-million (PPM). 2444The file is updated by first writing 2445the current drift value into a temporary file and then renaming 2446this file to replace the old version. 2447This implies that 2448.Xr ntpd @NTPD_MS@ 2449must have write permission for the directory the 2450drift file is located in, and that file system links, symbolic or 2451otherwise, should be avoided. 2452.It Ic dscp Ar value 2453This option specifies the Differentiated Services Control Point (DSCP) value, 2454a 6\-bit code. 2455The default value is 46, signifying Expedited Forwarding. 2456.It Xo Ic enable 2457.Oo 2458.Cm auth | Cm bclient | 2459.Cm calibrate | Cm kernel | 2460.Cm mode7 | Cm monitor | 2461.Cm ntp | Cm stats | 2462.Cm peer_clear_digest_early | 2463.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early 2464.Oc 2465.Xc 2466.It Xo Ic disable 2467.Oo 2468.Cm auth | Cm bclient | 2469.Cm calibrate | Cm kernel | 2470.Cm mode7 | Cm monitor | 2471.Cm ntp | Cm stats | 2472.Cm peer_clear_digest_early | 2473.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early 2474.Oc 2475.Xc 2476Provides a way to enable or disable various server options. 2477Flags not mentioned are unaffected. 2478Note that all of these flags 2479can be controlled remotely using the 2480.Xr ntpdc @NTPDC_MS@ 2481utility program. 2482.Bl -tag -width indent 2483.It Cm auth 2484Enables the server to synchronize with unconfigured peers only if the 2485peer has been correctly authenticated using either public key or 2486private key cryptography. 2487The default for this flag is 2488.Ic enable . 2489.It Cm bclient 2490Enables the server to listen for a message from a broadcast or 2491multicast server, as in the 2492.Ic multicastclient 2493command with default 2494address. 2495The default for this flag is 2496.Ic disable . 2497.It Cm calibrate 2498Enables the calibrate feature for reference clocks. 2499The default for 2500this flag is 2501.Ic disable . 2502.It Cm kernel 2503Enables the kernel time discipline, if available. 2504The default for this 2505flag is 2506.Ic enable 2507if support is available, otherwise 2508.Ic disable . 2509.It Cm mode7 2510Enables processing of NTP mode 7 implementation\-specific requests 2511which are used by the deprecated 2512.Xr ntpdc @NTPDC_MS@ 2513program. 2514The default for this flag is disable. 2515This flag is excluded from runtime configuration using 2516.Xr ntpq @NTPQ_MS@ . 2517The 2518.Xr ntpq @NTPQ_MS@ 2519program provides the same capabilities as 2520.Xr ntpdc @NTPDC_MS@ 2521using standard mode 6 requests. 2522.It Cm monitor 2523Enables the monitoring facility. 2524See the 2525.Xr ntpdc @NTPDC_MS@ 2526program 2527and the 2528.Ic monlist 2529command or further information. 2530The 2531default for this flag is 2532.Ic enable . 2533.It Cm ntp 2534Enables time and frequency discipline. 2535In effect, this switch opens and 2536closes the feedback loop, which is useful for testing. 2537The default for 2538this flag is 2539.Ic enable . 2540.It Cm peer_clear_digest_early 2541By default, if 2542.Xr ntpd @NTPD_MS@ 2543is using autokey and it 2544receives a crypto\-NAK packet that 2545passes the duplicate packet and origin timestamp checks 2546the peer variables are immediately cleared. 2547While this is generally a feature 2548as it allows for quick recovery if a server key has changed, 2549a properly forged and appropriately delivered crypto\-NAK packet 2550can be used in a DoS attack. 2551If you have active noticable problems with this type of DoS attack 2552then you should consider 2553disabling this option. 2554You can check your 2555.Cm peerstats 2556file for evidence of any of these attacks. 2557The 2558default for this flag is 2559.Ic enable . 2560.It Cm stats 2561Enables the statistics facility. 2562See the 2563.Sx Monitoring Options 2564section for further information. 2565The default for this flag is 2566.Ic disable . 2567.It Cm unpeer_crypto_early 2568By default, if 2569.Xr ntpd @NTPD_MS@ 2570receives an autokey packet that fails TEST9, 2571a crypto failure, 2572the association is immediately cleared. 2573This is almost certainly a feature, 2574but if, in spite of the current recommendation of not using autokey, 2575you are 2576.B still 2577using autokey 2578.B and 2579you are seeing this sort of DoS attack 2580disabling this flag will delay 2581tearing down the association until the reachability counter 2582becomes zero. 2583You can check your 2584.Cm peerstats 2585file for evidence of any of these attacks. 2586The 2587default for this flag is 2588.Ic enable . 2589.It Cm unpeer_crypto_nak_early 2590By default, if 2591.Xr ntpd @NTPD_MS@ 2592receives a crypto\-NAK packet that 2593passes the duplicate packet and origin timestamp checks 2594the association is immediately cleared. 2595While this is generally a feature 2596as it allows for quick recovery if a server key has changed, 2597a properly forged and appropriately delivered crypto\-NAK packet 2598can be used in a DoS attack. 2599If you have active noticable problems with this type of DoS attack 2600then you should consider 2601disabling this option. 2602You can check your 2603.Cm peerstats 2604file for evidence of any of these attacks. 2605The 2606default for this flag is 2607.Ic enable . 2608.It Cm unpeer_digest_early 2609By default, if 2610.Xr ntpd @NTPD_MS@ 2611receives what should be an authenticated packet 2612that passes other packet sanity checks but 2613contains an invalid digest 2614the association is immediately cleared. 2615While this is generally a feature 2616as it allows for quick recovery, 2617if this type of packet is carefully forged and sent 2618during an appropriate window it can be used for a DoS attack. 2619If you have active noticable problems with this type of DoS attack 2620then you should consider 2621disabling this option. 2622You can check your 2623.Cm peerstats 2624file for evidence of any of these attacks. 2625The 2626default for this flag is 2627.Ic enable . 2628.El 2629.It Ic includefile Ar includefile 2630This command allows additional configuration commands 2631to be included from a separate file. 2632Include files may 2633be nested to a depth of five; upon reaching the end of any 2634include file, command processing resumes in the previous 2635configuration file. 2636This option is useful for sites that run 2637.Xr ntpd @NTPD_MS@ 2638on multiple hosts, with (mostly) common options (e.g., a 2639restriction list). 2640.It Ic leapsmearinterval Ar seconds 2641This EXPERIMENTAL option is only available if 2642.Xr ntpd @NTPD_MS@ 2643was built with the 2644.Cm \-\-enable\-leap\-smear 2645option to the 2646.Cm configure 2647script. 2648It specifies the interval over which a leap second correction will be applied. 2649Recommended values for this option are between 26507200 (2 hours) and 86400 (24 hours). 2651.Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS! 2652See http://bugs.ntp.org/2855 for more information. 2653.It Ic logconfig Ar configkeyword 2654This command controls the amount and type of output written to 2655the system 2656.Xr syslog 3 2657facility or the alternate 2658.Ic logfile 2659log file. 2660By default, all output is turned on. 2661All 2662.Ar configkeyword 2663keywords can be prefixed with 2664.Ql = , 2665.Ql + 2666and 2667.Ql \- , 2668where 2669.Ql = 2670sets the 2671.Xr syslog 3 2672priority mask, 2673.Ql + 2674adds and 2675.Ql \- 2676removes 2677messages. 2678.Xr syslog 3 2679messages can be controlled in four 2680classes 2681.Po 2682.Cm clock , 2683.Cm peer , 2684.Cm sys 2685and 2686.Cm sync 2687.Pc . 2688Within these classes four types of messages can be 2689controlled: informational messages 2690.Po 2691.Cm info 2692.Pc , 2693event messages 2694.Po 2695.Cm events 2696.Pc , 2697statistics messages 2698.Po 2699.Cm statistics 2700.Pc 2701and 2702status messages 2703.Po 2704.Cm status 2705.Pc . 2706.Pp 2707Configuration keywords are formed by concatenating the message class with 2708the event class. 2709The 2710.Cm all 2711prefix can be used instead of a message class. 2712A 2713message class may also be followed by the 2714.Cm all 2715keyword to enable/disable all 2716messages of the respective message class. 2717Thus, a minimal log configuration 2718could look like this: 2719.Bd -literal 2720logconfig =syncstatus +sysevents 2721.Ed 2722.Pp 2723This would just list the synchronizations state of 2724.Xr ntpd @NTPD_MS@ 2725and the major system events. 2726For a simple reference server, the 2727following minimum message configuration could be useful: 2728.Bd -literal 2729logconfig =syncall +clockall 2730.Ed 2731.Pp 2732This configuration will list all clock information and 2733synchronization information. 2734All other events and messages about 2735peers, system events and so on is suppressed. 2736.It Ic logfile Ar logfile 2737This command specifies the location of an alternate log file to 2738be used instead of the default system 2739.Xr syslog 3 2740facility. 2741This is the same operation as the 2742.Fl l 2743command line option. 2744.It Ic setvar Ar variable Op Cm default 2745This command adds an additional system variable. 2746These 2747variables can be used to distribute additional information such as 2748the access policy. 2749If the variable of the form 2750.Sm off 2751.Va name = Ar value 2752.Sm on 2753is followed by the 2754.Cm default 2755keyword, the 2756variable will be listed as part of the default system variables 2757.Po 2758.Xr ntpq @NTPQ_MS@ 2759.Ic rv 2760command 2761.Pc ) . 2762These additional variables serve 2763informational purposes only. 2764They are not related to the protocol 2765other that they can be listed. 2766The known protocol variables will 2767always override any variables defined via the 2768.Ic setvar 2769mechanism. 2770There are three special variables that contain the names 2771of all variable of the same group. 2772The 2773.Va sys_var_list 2774holds 2775the names of all system variables. 2776The 2777.Va peer_var_list 2778holds 2779the names of all peer variables and the 2780.Va clock_var_list 2781holds the names of the reference clock variables. 2782.It Xo Ic tinker 2783.Oo 2784.Cm allan Ar allan | 2785.Cm dispersion Ar dispersion | 2786.Cm freq Ar freq | 2787.Cm huffpuff Ar huffpuff | 2788.Cm panic Ar panic | 2789.Cm step Ar step | 2790.Cm stepback Ar stepback | 2791.Cm stepfwd Ar stepfwd | 2792.Cm stepout Ar stepout 2793.Oc 2794.Xc 2795This command can be used to alter several system variables in 2796very exceptional circumstances. 2797It should occur in the 2798configuration file before any other configuration options. 2799The 2800default values of these variables have been carefully optimized for 2801a wide range of network speeds and reliability expectations. 2802In 2803general, they interact in intricate ways that are hard to predict 2804and some combinations can result in some very nasty behavior. 2805Very 2806rarely is it necessary to change the default values; but, some 2807folks cannot resist twisting the knobs anyway and this command is 2808for them. 2809Emphasis added: twisters are on their own and can expect 2810no help from the support group. 2811.Pp 2812The variables operate as follows: 2813.Bl -tag -width indent 2814.It Cm allan Ar allan 2815The argument becomes the new value for the minimum Allan 2816intercept, which is a parameter of the PLL/FLL clock discipline 2817algorithm. 2818The value in log2 seconds defaults to 7 (1024 s), which is also the lower 2819limit. 2820.It Cm dispersion Ar dispersion 2821The argument becomes the new value for the dispersion increase rate, 2822normally .000015 s/s. 2823.It Cm freq Ar freq 2824The argument becomes the initial value of the frequency offset in 2825parts\-per\-million. 2826This overrides the value in the frequency file, if 2827present, and avoids the initial training state if it is not. 2828.It Cm huffpuff Ar huffpuff 2829The argument becomes the new value for the experimental 2830huff\-n'\-puff filter span, which determines the most recent interval 2831the algorithm will search for a minimum delay. 2832The lower limit is 2833900 s (15 m), but a more reasonable value is 7200 (2 hours). 2834There 2835is no default, since the filter is not enabled unless this command 2836is given. 2837.It Cm panic Ar panic 2838The argument is the panic threshold, normally 1000 s. 2839If set to zero, 2840the panic sanity check is disabled and a clock offset of any value will 2841be accepted. 2842.It Cm step Ar step 2843The argument is the step threshold, which by default is 0.128 s. 2844It can 2845be set to any positive number in seconds. 2846If set to zero, step 2847adjustments will never occur. 2848Note: The kernel time discipline is 2849disabled if the step threshold is set to zero or greater than the 2850default. 2851.It Cm stepback Ar stepback 2852The argument is the step threshold for the backward direction, 2853which by default is 0.128 s. 2854It can 2855be set to any positive number in seconds. 2856If both the forward and backward step thresholds are set to zero, step 2857adjustments will never occur. 2858Note: The kernel time discipline is 2859disabled if 2860each direction of step threshold are either 2861set to zero or greater than .5 second. 2862.It Cm stepfwd Ar stepfwd 2863As for stepback, but for the forward direction. 2864.It Cm stepout Ar stepout 2865The argument is the stepout timeout, which by default is 900 s. 2866It can 2867be set to any positive number in seconds. 2868If set to zero, the stepout 2869pulses will not be suppressed. 2870.El 2871.It Xo Ic rlimit 2872.Oo 2873.Cm memlock Ar Nmegabytes | 2874.Cm stacksize Ar N4kPages 2875.Cm filenum Ar Nfiledescriptors 2876.Oc 2877.Xc 2878.Bl -tag -width indent 2879.It Cm memlock Ar Nmegabytes 2880Specify the number of megabytes of memory that should be 2881allocated and locked. 2882Probably only available under Linux, this option may be useful 2883when dropping root (the 2884.Fl i 2885option). 2886The default is 32 megabytes on non\-Linux machines, and \-1 under Linux. 2887-1 means "do not lock the process into memory". 28880 means "lock whatever memory the process wants into memory". 2889.It Cm stacksize Ar N4kPages 2890Specifies the maximum size of the process stack on systems with the 2891.Fn mlockall 2892function. 2893Defaults to 50 4k pages (200 4k pages in OpenBSD). 2894.It Cm filenum Ar Nfiledescriptors 2895Specifies the maximum number of file descriptors ntpd may have open at once. 2896Defaults to the system default. 2897.El 2898.It Xo Ic trap Ar host_address 2899.Op Cm port Ar port_number 2900.Op Cm interface Ar interface_address 2901.Xc 2902This command configures a trap receiver at the given host 2903address and port number for sending messages with the specified 2904local interface address. 2905If the port number is unspecified, a value 2906of 18447 is used. 2907If the interface address is not specified, the 2908message is sent with a source address of the local interface the 2909message is sent through. 2910Note that on a multihomed host the 2911interface used may vary from time to time with routing changes. 2912.Pp 2913The trap receiver will generally log event messages and other 2914information from the server in a log file. 2915While such monitor 2916programs may also request their own trap dynamically, configuring a 2917trap receiver will ensure that no messages are lost when the server 2918is started. 2919.It Cm hop Ar ... 2920This command specifies a list of TTL values in increasing order, up to 8 2921values can be specified. 2922In manycast mode these values are used in turn in 2923an expanding\-ring search. 2924The default is eight multiples of 32 starting at 292531. 2926.El 2927.Sh "OPTIONS" 2928.Bl -tag 2929.It Fl \-help 2930Display usage information and exit. 2931.It Fl \-more\-help 2932Pass the extended usage information through a pager. 2933.It Fl \-version Op Brq Ar v|c|n 2934Output version of program and exit. The default mode is `v', a simple 2935version. The `c' mode will print copyright information and `n' will 2936print the full copyright notice. 2937.El 2938.Sh "OPTION PRESETS" 2939Any option that is not marked as \fInot presettable\fP may be preset 2940by loading values from environment variables named: 2941.nf 2942 \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP 2943.fi 2944.ad 2945.Sh "ENVIRONMENT" 2946See \fBOPTION PRESETS\fP for configuration environment variables. 2947.Sh FILES 2948.Bl -tag -width /etc/ntp.drift -compact 2949.It Pa /etc/ntp.conf 2950the default name of the configuration file 2951.It Pa ntp.keys 2952private MD5 keys 2953.It Pa ntpkey 2954RSA private key 2955.It Pa ntpkey_ Ns Ar host 2956RSA public key 2957.It Pa ntp_dh 2958Diffie\-Hellman agreement parameters 2959.El 2960.Sh "EXIT STATUS" 2961One of the following exit values will be returned: 2962.Bl -tag 2963.It 0 " (EXIT_SUCCESS)" 2964Successful program execution. 2965.It 1 " (EXIT_FAILURE)" 2966The operation failed or the command syntax was not valid. 2967.It 70 " (EX_SOFTWARE)" 2968libopts had an internal operational error. Please report 2969it to autogen\-users@lists.sourceforge.net. Thank you. 2970.El 2971.Sh "SEE ALSO" 2972.Xr ntpd @NTPD_MS@ , 2973.Xr ntpdc @NTPDC_MS@ , 2974.Xr ntpq @NTPQ_MS@ 2975.Pp 2976In addition to the manual pages provided, 2977comprehensive documentation is available on the world wide web 2978at 2979.Li http://www.ntp.org/ . 2980A snapshot of this documentation is available in HTML format in 2981.Pa /usr/share/doc/ntp . 2982.Rs 2983.%A David L. Mills 2984.%T Network Time Protocol (Version 4) 2985.%O RFC5905 2986.Re 2987.Sh "AUTHORS" 2988The University of Delaware and Network Time Foundation 2989.Sh "COPYRIGHT" 2990Copyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved. 2991This program is released under the terms of the NTP license, <http://ntp.org/license>. 2992.Sh BUGS 2993The syntax checking is not picky; some combinations of 2994ridiculous and even hilarious options and modes may not be 2995detected. 2996.Pp 2997The 2998.Pa ntpkey_ Ns Ar host 2999files are really digital 3000certificates. 3001These should be obtained via secure directory 3002services when they become universally available. 3003.Pp 3004Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 3005.Sh NOTES 3006This document was derived from FreeBSD. 3007.Pp 3008This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP 3009option definitions. 3010