unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



ntp.conf(4)							  ntp.conf(4)



NAME

  ntp.conf - Network Time Protocol (NTP) configuration file

DESCRIPTION

  The xntpd configuration file,	/etc/ntp.conf, is read by xntpd	at startup.

  The xntpd configuration file is relatively free of formatting.  Comments,
  which	may be freely inserted,	begin with a # character and extend to the
  end of the line.  Blank lines	are ignored.  Configuration commands consist
  of an	initial	keyword	followed by a list of arguments, separated by white
  space.  Configuration	commands may not be continued over multiple lines.
  Arguments may	be host	names, host addresses written in numeric, dotted-quad
  form,	integers, floating point numbers (when specifying times	in seconds)
  and text strings.  Optional arguments	are delimited by "[]" in the follow-
  ing descriptions, while alternatives are separated by	"|".

  The /etc/ntp.conf file is defined as a Context-Dependent Symbolic Link
  (CDSL), and must be maintained as such.  See the System Administration
  manual for more information.

  Configuration	Options


  peer host_address [key #] [version #]	[burst]	[prefer] [minpoll #] [maxpoll
  #]
  server host_address [key #] [burst] [version #] [prefer] [mode #] [minpoll
  #] [maxpoll #]
  broadcast host_address [key #] [burst] [version #] [minpoll #] [maxpoll #]
  [ttl #]
  manycastclient host_address [key #] [burst] [version #] [minpoll #] [max-
  poll #] [ttl #]

  The following	commands specify various time servers to be used or time ser-
  vices	to be provided:

  peer
      This command specifies that the local server is to operate in "sym-
      metric active" mode with the remote server host_address.	In this	mode,
      the local	server can be synchronized to the remote server	and, in	addi-
      tion, the	remote server can be synchronized by the local server.	This
      is useful	in a network of	servers	where, depending on various failure
      scenarios, either	the local or remote server host	may be the better
      source of	time.

  server
      This command specifies that the local server is to operate in "client"
      mode with	the remote server named	in the command.	 In this mode, the
      local server can be synchronized to the remote server, but the remote
      server can never be synchronized to the local server.

  broadcast
      This command specifies that the local server is to operate in broadcast
      mode where the local server sends	periodic broadcast messages to a
      client population	at the broadcast or multicast address named in the
      command.	Ordinarily, this specification applies only to the local
      server operating as a transmitter; for operation as a broadcast client,
      see the broadcastclient or multicastclient commands.  In this mode, the
      host_address is usually the broadcast address on one of the local	net-
      works or a multicast address assigned to NTP.  Address 224.0.1.1 is
      assigned to NTP; this is presently the only number that should be	used.

  manycastclient
      This command specifies that the local server is to operate in client
      mode with	the remote servers that	are discovered as a result of
      broadcast/multicast messages.  The client	broadcasts a request message
      to the specified group address and specifically-enabled servers respond
      to these messages. The client selects the	servers	providing the best
      time and continues as with the server command. The remaining servers
      are discarded as if never	heard.	In this	mode, the supplied
      host_address must	match the address used on the manycastserver command
      for the designated manycast servers. The NTP multicast address
      (224.0.1.1) should not be	used, unless specific means are	taken to
      avoid spraying large areas of the	Internet with these messages and
      causing a	possibly massive implosion of replies at the sender.

  The following	options	can be specified with these commands:

  burst
      Indicates	that, at each poll interval, the server	is to send a burst of
      eight packets instead of one.  This option is useful for maintaining
      accuracy over the	intermittent connections that are typical of PPP and
      ISDN services.

  key #
      Indicates	that all packets sent to the address are to include authenti-
      cation fields encrypted using the	specified key number (the range	of
      which is that of an unsigned 32 bit integer).  The default is to not
      include an encryption field.

  version #
      Allows you to specify the	version	number to be used for outgoing NTP
      packets.	Versions 1, 2, and 3 are the choices; version 3	is the
      default.	Version	1 must be used for hosts running the University	of
      Maryland ntpd daemon.

  minpoll #

  maxpoll #
      Specify the minimum and maximum polling interval for NTP messages, in
      seconds to the power of two.  The	default	range is 6 (64 seconds)	to 10
      (1024 seconds).  The allowable range is 4	(16 seconds) to	17 (36.4 h)
      inclusive.

  prefer
      Marks the	host as	a preferred host.  All other things being equal, this
      host will	be chosen for synchronization among a set of correctly
      operating	hosts.

  ttl #
      Specifies	the time-to-live (TTL) to use on multicast packets (broadcast
      mode only).  Selection of	the proper value, which	defaults to 127, must
      be coordinated with the network administrator(s).

  Additional Configuration Options



  broadcastclient
      Directs the local	server to listen for broadcast messages	on the local
      network, in order	to discover other servers on the same subnet.  Upon
      hearing a	broadcast message for the first	time, the local	server meas-
      ures the nominal network delay using a brief client/server exchange
      with the remote server, then enters the broadcastclient mode, in which
      it listens for and synchronizes to succeeding broadcast messages.	 Note
      that, in order to	avoid accidental or malicious disruption in this
      mode, both the local and remote servers must operate using authentica-
      tion and the same	trusted	key and	key identifier.

  disable auth|bclient|pll|monitor|stats [...]
      Provides a way to	disable	various	server options.	 Flags not mentioned
      are unaffected.  The flags presently available are described under the
      enable command.

  driftfile filename
      Specifies	the name of the	file used to record the	frequency offset of
      the local	clock oscillator.  If the file exists on startup, it is	read
      and the value used to set	the initial frequency offset and then updated
      once every hour with the current offset computed by xntpd.  If the file
      does not exist or	this command is	not given, the initial frequency
      offset is	assumed	zero.  In this case, it	may take some hours for	the
      frequency	to stabilize and the residual timing errors to subside.	 The
      file contains a single floating point value equal	to the offset in
      parts-per-million	(ppm).

				       Note

	   The file is updated by writing the current drift value into a
	   temporary file and then using rename	to replace the old ver-
	   sion.  Therefore, xntpd must	have write permission for the
	   directory the drift file is located in, and file system
	   links, symbolic or otherwise, should	be avoided.


  enable auth|bclient|pll|monitor|stats	[...]
      Provides a way to	enable various server options.	Flags not mentioned
      are unaffected.

      auth
	  Causes the server to synchronize with	unconfigured peers only	if
	  the peer has been correctly authenticated using a trusted key	and
	  key identifier.  The default for this	flag is	disable	(off).

      bclient
	  Causes the server to listen for a message from a broadcast or	mul-
	  ticast server, following which an association	is automatically
	  instantiated for that	server.	 The default for this flag is disable
	  (off).

      pll Enables the server to	adjust its local clock,	with default enable
	  (on).	 If not	set, the local clock free-runs at its intrinsic	time
	  and frequency	offset.	 This flag is useful in	case the local clock
	  is controlled	by some	other device or	protocol and NTP is used only
	  to provide synchronization to	other clients.

      monitor
	  Enables the monitoring facility (see "Monitoring Options"), with
	  default enable (on).

      stats
	  Enables statistics facility filegen, with default enable (on).

  logconfig configkeyword
      This command controls the	amount and type	of output written to the
      system syslog facility or	the alternate logfile log file.	By default,
      only minimal output is written.

      All configkeyword	keywords can be	prefixed with =, + and -, where	=
      sets the syslogmask, + adds and -	removes	messages. The syslog messages
      can be controlled	in four	classes: clock,	peer, sys and sync. Within
      these classes, four types	of messages can	be controlled: info, events,
      statistics, and status.

      Informational messages (info) control configuration information. Event
      messages (events)	control	logging	of events (reachability, synchroniza-
      tion, alarm conditions).	Statistical output is controlled with the
      statistics keyword. The final message group is for status	messages,
      which mainly describe the	synchronization	status.

      Configuration keywords are formed	by concatenating the message class
      with the event class. The	all prefix can be used instead of a message
      class. A message class may also be followed by the all keyword to
      enable/disable all messages of the respective message class.  Thus, a
      minimal log configuration	could look like	this:
	   logconfig = syncstatus +sysevents

      This configuration, the default for the operating	system,	lists only
      the synchronization state	of xntpd and major system events.

      For a simple reference server, the following minimum message configura-
      tion could be useful:
	   logconfig = syncall +clockall

      This configuration lists all clock information and synchronization
      information. All other events and	messages about peers, system events
      and so on	are suppressed.

  logfile filename
      This command specifies the location of an	alternate log file to be used
      instead of the default system syslog facility.

  manycastserver [IP address ...]
      This command directs the local server to listen for and respond to
      broadcast	messages received on any local interface, and in addition
      enables the server to respond to client mode messages sent to the	mul-
      ticast group address(es) specified. At least one address is required,
      but the NTP multicast address (224.0.1.1)	should NOT be used, unless
      specific means are taken to limit	the span of the	reply and avoid	a
      possibly massive implosion at the	original sender.

  multicastclient [IP address ...]
      This command is used in the same way as the broadcastclient command,
      but operates using IP multicasting.  Support for this function requires
      a	multicast kernel and the use of	authentication.	 If one	or more	IP
      addresses	are given, the server joins the	respective multicast
      group(s).	 If none are given, the	IP address assigned to NTP
      (224.0.1.1) is assumed.

  Authentication Options


  controlkey #
      Specifies	the key	identifier to use with the ntpq	program, which is
      useful to	diagnose and repair problems that affect xntpd operation.
      The operation of the ntpq	program	and xntpd conform to those specified
      in RFC 1305.  Requests from a remote ntpq	program	that affect the	state
      of the local server must be authenticated, which requires	both the
      remote program and local server share a common key and key identifier.
      The argument to this command is a	32-bit unsigned	integer.  If no
      requestkey command is included in	the configuration file,	or if the
      keys do not match, such requests are ignored.

  keys filename
      Specifies	the name of a file that	contains the encryption	keys and key
      identifiers used by xntpd	when operating in authenticated	mode.  See
      ntp.keys(4) for description of the key file format.

  requestkey #
      Specifies	the key	identifier to use with the xntpdc program, which is
      useful to	diagnose and repair problems that affect xntpd operation.
      The operation of the xntpdc program are specific to this particular
      implementation of	xntpd and can be expected to work only with this and
      previous versions	of the daemon.	Requests from a	remote xntpdc program
      that affect the state of the local server	must be	authenticated, which
      requires both the	remote program and local server	share a	common key
      and key identifier.  The argument	to this	command	is a 32-bit unsigned
      integer.	If no requestkey command is included in	the configuration
      file, or if the keys do not match, such requests are ignored.

  trustedkey # [# ...]
      Specifies	the encryption key identifiers that are	trusted	for the	pur-
      poses of authenticating peers suitable for synchronization.  The
      authentication procedures	require	that both the local and	remote
      servers share the	same key and key identifier for	this purpose,
      although different keys can be used with different servers.  The argu-
      ments are	32-bit unsigned	integers.  Note, however, that NTP key 0 is
      fixed and	globally known.	 If meaningful authentication is to be per-
      formed the 0 key should not be trusted.

  Access Control Options


  clientlimit limit
      Defines the number of clients from the same network that are allowed to
      use the server.  The default is 3.

  clientperiod period
      Specifies	the number of seconds after which a client is considered
      inactive and thus	no longer is counted for client	limit restriction.
      The default is 3600 seconds.

  restrict address [mask numeric_mask] [flag] [...]
      The xntpd	daemon implements a general purpose address-and-mask based
      restriction list.	 The list is sorted by address and by mask, and	the
      list is searched in this order for matches, with the last	match found
      defining the restriction flags associated	with the incoming packets.
      The source address of incoming packets is	used for the match, with the
      32 bit address being and'ed with the mask	associated with	the restric-
      tion entry and then compared with	the entry's address (which has also
      been and'ed with the mask) to look for a match.  The mask	argument
      defaults to 255.255.255.255, meaning that	the address is treated as the
      address of an individual host.  A	default	entry (address 0.0.0.0,	mask
      0.0.0.0) is always included and, given the sort algorithm, is always
      the first	entry in the list.  Note that, while address is	normally
      given in dotted-quad format, the text string default, with no mask
      option, may be used to indicate the default entry.

      In the current implementation, flags always restrict access: an entry
      with no flags indicates that free	access to the server is	to be given.
      The flags	are not	orthogonal, in that more restrictive flags will	often
      make less	restrictive ones redundant.  The flags can generally be
      classed into two categories: those that restrict time service and	those
      that restrict informational queries.  One	or more	of the following
      flags may	be specified:

      ignore
	  Ignores all packets from hosts that match this entry.	 If this flag
	  is specified,	queries	and time server	polls receive no response.

      noquery
	  Ignores all NTP mode 6 and 7 packets (information queries and	con-
	  figuration requests) from the	source.	 Time service is not
	  affected.

      nomodify
	  Ignores all NTP mode 6 and 7 packets that attempt to modify the
	  state	of the server (run time	reconfiguration).  Queries that
	  return information are permitted.

      notrap
	  Declines to provide mode 6 control message trap service to matching
	  hosts.  The trap service is a	subsystem of the mode 6	control	mes-
	  sage protocol, which is intended for use by remote event logging
	  programs.

      lowpriotrap
	  Declares traps set by	matching hosts to be low priority.  The
	  number of traps a server can maintain	is limited (the	current	limit
	  is 3).  Traps	are usually assigned on	a first	come, first served
	  basis, with later trap requestors being denied service.  This	flag
	  modifies the assignment algorithm by allowing	low priority traps to
	  be overridden	by later requests for normal priority traps.

      noserve
	  Ignores NTP packets whose mode is other than 6 or 7.	In effect,
	  time service is denied, though queries may still be permitted.

      nopeer
	  Provides stateless time service to polling hosts, but	does not
	  allocate peer	memory resources to these hosts	even if	they other-
	  wise might be	considered useful as future synchronization partners.

      notrust
	  Treats these hosts normally in other respects, but never uses	them
	  as synchronization sources.

      limited
	  Limits the number of clients that can	use these hosts	from the same
	  net.	Net in this context refers to the IP notion of net (class A,
	  class	B, class C, etc.).  Only the first clientlimit hosts that
	  have accessed	the server and that have been active during the	last
	  clientperiod seconds are accepted.  Requests from other clients
	  from the same	net are	rejected.  Only	time request packets are
	  taken	into account.  Private,	control, and broadcast packets are
	  not subject to client	limitation and therefore do not	contribute to
	  client count.	 History of clients is kept using the monitoring
	  capability of	xntpd.	Thus, monitoring is active as long as there
	  is a restriction entry with the limited flag.

      ntpport
	  Specifies a match algorithm modifier,	rather than a restriction
	  flag.	 Its presence causes the restriction entry to be matched only
	  if the source	port in	the packet is the standard NTP UDP port
	  (123).  Both ntpport and non-ntpport may be specified.  The ntpport
	  is considered	more specific and is sorted later in the list.

      Default restriction list entries,	with the flags ignore, ntpport,	for
      each of the local	host's interface addresses are inserted	into the
      table at startup to prevent the server from attempting to	synchronize
      to its own time.	A default entry	is also	always present,	though if it
      is otherwise unconfigured, no flags are associated with the default
      entry (everything	besides	your own NTP server is unrestricted).

      The restriction facility allows the current access policies of the time
      servers running on the NSFnet backbone to	be implemented with xntpd as
      well.  While this	facility may be	otherwise useful for keeping unwanted
      time servers from	affecting your own, it should not be considered	an
      alternative to the standard NTP authentication facility.	Source
      address based restrictions can be	circumvented by	a determined cracker.

  Monitoring Options


  filegen name [file filename] [type typename] [flag flagval] [link | nolink]
  [enable | disable]

      Configures setting of generation file set	name.  Generation file sets
      provide a	means for handling files that are continuously growing during
      the lifetime of a	server.	 Server	statistics are a typical example for
      such files.  Generation file sets	provide	access to a set	of files used
      to store the actual data.	 At any	time, only one element of the set is
      being written to.	 The type given	specifies when and how data will be
      directed to a new	element	of the set.  This way, information stored in
      elements of a file set that are currently	unused are available for
      administrational operations without the risk of disturbing the opera-
      tion of xntpd.  (The elements can	be removed to free space for new data
      produced.) File names of set members are built from three	elements:

      prefix
	  This is a constant filename path.  It	is not subject to modifica-
	  tions	by the filegen statement.  It is defined by the	server,	usu-
	  ally specified as a compile time constant.  It may, however, be
	  configurable for individual file generation sets via other com-
	  mands.  For example, the prefix used with loopstats and peerstats
	  filegens can be configured using the statsdir	statement explained
	  previously.

      filename
	  This string is directly concatenated to the prefix with no inter-
	  vening slash character (/).  This can	be modified using the file
	  argument to the filegen statement.  No .. elements are allowed in
	  this component to prevent filenames referring	to parts outside the
	  filesystem hierarchy denoted by prefix.

      suffix
	  This part reflects individual	elements of a file set.	 It is gen-
	  erated according to the type of a file set.

      A	file generation	set is characterized by	its type.  The following
      types are	supported:

      none
	  The file set is a single plain file.

      pid One element of file set is used per incarnation of a xntpd server.
	  This type does not perform any changes to file set members during
	  runtime, however it provides an easy way of separating files
	  belonging to different xntpd server incarnations.  The set member
	  filename is built by appending a dot (.) to concatenated prefix and
	  filename strings, and	appending the decimal representation of	the
	  process id of	the xntpd server process.

      day One file generation set element is created per day.  The term	day
	  is based on UTC.  A day is defined as	the period between 00:00 and
	  24:00	UTC.  The file set member suffix consists of a dot (.) and a
	  day specification in the following form:
	       YYYYMMDD
	  YYYY is a four-digit year number (for	example, 1992);	MM is a	two-
	  digit	month number; and DD is	a two-digit day	number.	 Thus, infor-
	  mation written at December 10th, 1992	would be written to a file
	  named	prefixfilename.19921210.

      week
	  Any file set member contains data related to a certain week of a
	  year.	 The term week is defined by computing "day of year" modulo
	  7.  Elements of such a file generation set are distinguished by
	  appending the	following suffix to the	file set filename base:	A
	  dot, a four-digit year number, the letter W, and a two-digit week
	  number.  For example,	information from January, 10th 1992 would be
	  written to a file with suffix	.1992W1.

      month
	  One generation file set element is generated per month.  The file
	  name suffix consists of a dot, a four-digit year number, and a
	  two-digit month.

      year
	  One generation file element is generated per year.  The filename
	  suffix consists of a dot and a four-digit year number.

      age This type of file generation sets changes to a new element of	the
	  file set every 24 hours of server operation.	The filename suffix
	  consists of a	dot, the letter	a, and an eight-digit number.  This
	  number is taken to be	the number of seconds the server is running
	  at the start of the corresponding 24 hour period.

      Information is only written to a file generation set when	this set is
      enabled.	Output is prevented by specifying disable.

      It is convenient to be able to access the	current	element	of a file
      generation set by	a fixed	name.  This feature is enabled by specifying
      link and disabled	using nolink.  If link is specified, a hard link from
      the current file set element to a	file without suffix is created.	 When
      there is already a file with this	name and the number of links of	this
      file is one, it is renamed appending a dot, the letter C,	and the	pid
      of the xntpd server process.  When the number of links is	greater	than
      one, the file is unlinked.  This allows the current file to be accessed
      by a constant name.

  statistics name ...
      Enables writing of statistics records.  The following types of statis-
      tics are supported:

      loopstats
	  Enables recording of loop filter statistics information.  Each
	  update of the	local clock outputs a line of the following form to
	  the file generation set named	"loopstats":
	       48773 10847.650 0.0001307 17.3478 2

	  The first two	fields show the	date (Modified Julian Day) and time
	  (seconds and fraction	past UTC midnight).  The next three fields
	  show time offset in seconds, frequency offset	in parts-per-million
	  and time constant of the clock-discipline algorithm at each update
	  of the clock.

      peerstats
	  Enables recording of peer statistics information.  This includes
	  statistics records of	all peers of a NTP server and of the 1-pps
	  signal, where	present	and configured.	 Each valid update appends a
	  line of the following	form to	the current element of a file genera-
	  tion set named "peerstats":
	       48773 10847.650 127.127.4.1 9714	-0.001605 0.00000 0.00142

	  The first two	fields show the	date (Modified Julian Day) and time
	  (seconds and fraction	past UTC midnight).  The next two fields show
	  the peer address in dotted-quad notation and status, respectively.
	  The status field is encoded in hex in	the format described in
	  Appendix A of	the NTP	specification RFC 1305.	 The final three
	  fields show the offset, delay	and dispersion,	all in seconds.

      clockstats
	  Enables recording of clock driver statistics information.  Each
	  update received from a clock driver outputs a	line of	the following
	  form to the file generation set named	"clockstats":
	       49213 525.624 127.127.4.1 93 226	00:08:29.606 D

	  The first two	fields show the	date (Modified Julian Day) and time
	  (seconds and fraction	past UTC midnight).  The next field shows the
	  clock	address	in dotted-quad notation, The final field shows the
	  last timecode	received from the clock	in decoded ASCII format,
	  where	meaningful.  In	some clock drivers a good deal of additional
	  information can be gathered and displayed as well.  See information
	  specific to each clock for further details.

	  Statistic files are managed using file generation sets (see the
	  filegen description).	 The information obtained by enabling statis-
	  tics recording allows	analysis of temporal properties	of a xntpd
	  server.  It is usually only useful to	primary	servers	or maybe main
	  campus servers.

      rawstats
	  Enables recording of raw-timestamp statistics	information. This
	  includes statistics records of all peers of a	NTP server and of
	  special signals, where present and configured. Each NTP message
	  received from	a peer or clock	driver appends a line of the follow-
	  ing form to the file generation set named rawstats:
	       50928 2132.543 128.4.1.1	128.4.1.20 3102453281.584327000
	       3102453281.58622800031 02453332.540806000 3102453332.541458000

	  The first two	fields show the	date (Modified Julian Day) and time
	  (seconds and fraction	past UTC midnight). The	next two fields	show
	  the remote peer or clock address followed by the local address in
	  dotted-quad notation.	The final four fields show the originate,
	  receive, transmit and	final NTP timestamps in	order. The timestamp
	  values are as	received and before processing by the various data
	  smoothing and	mitigation algorithms.

  statsdir /directory path/
      Indicates	the full path of a directory where statistics files should be
      created.	This keyword allows the	(otherwise constant) filegen filename
      prefix to	be modified for	file generation	sets used for handling
      statistics logs (see the description of the filegen statement).

  Miscellaneous	Options


  broadcastdelay seconds
      Specifies	the default delay to be	used in	cases where the	delay cali-
      bration procedure	between	local and remote servers might fail due	to
      network or server	access controls.  Typically (for Ethernet), a number
      between 0.003 and	0.007 seconds is appropriate.  The default when	this
      command is not used is 0.004 seconds.

      The broadcast and	multicast modes	require	a special calibration to
      determine	the network delay between the local and	remote servers.
      Ordinarily, this is done automatically by	the initial protocol
      exchanges	between	the local and remote servers.

  setvar variable [default]
      Adds an additional system	variable.  These variables can be used to
      distribute additional information	such as	the access policy.  If the
      variable of the form name=value is followed by the default keyword, the
      variable is listed as part of the	default	system variables (ntpq rv
      command).	 These additional variables serve informational	purposes
      only.  They are not related to the protocol other	that they can be
      listed.  The known protocol variables always override any	variables
      defined by the the setvar	mechanism.

      There are	three special variables	that contain the names of all vari-
      ables of the same	group.	The sys_var_list holds the names of all	sys-
      tem variables.  The peer_var_list	holds the names	of all peer variables
      and the clock_var_list hold the names of the reference clock variables.

      trap host_address	[port port_number] [interface interface_address]

      Configures a trap	receiver at the	given host address and port number,
      sending messages with the	specified local	interface address.  If the
      port number is unspecified, a value of 18447 is used.  If	the interface
      address is not specified,	the message is sent with a source address
      (the local interface the message is sent through).

				       Note

	   On a	multihomed host, the interface used may	vary from time
	   to time with	routing	changes.


      The trap receiver	generally logs event messages and other	information
      from the server in a log file.  While such monitor programs may also
      request their own	trap dynamically, configuring a	trap receiver ensures
      that no messages are lost	when the server	is started.

  Variables


  Most variables used by the NTP protocol can be examined with the xntpdc
  (mode	7 messages) and	the ntpq (mode 6 messages).  Currently very few	vari-
  ables	can be modified	by using mode 6	messages.  These variables are either
  created with the setvar directive or the leap	warning	variables.  The	leap
  warning bits that can	be set in the leapwarning variable (up to one month
  ahead).  Both, the leapwarning and in	the leapindication variable, have a
  slightly different encoding than the usual leap bits interpretation:

  00  The daemon passes	the leap bits of its synchronization source (usual
      mode of operation).

  01/10
      A	leap second is added/deleted (operator forced leap second).

  11  Leap information from the	synchronization	source is ignored (thus
      LEAP_NOWARNING is	passed on).

  Reference Clock Support


  The xntpd daemon includes support for	a number of types of reference
  clocks.  A reference clock is	generally (though not always) a	radio
  timecode receiver that is synchronized to a source of	standard time, such
  as the services offered by the NRC in	Canada and NIST	in the U.S.  The
  interface between the	computer and the timecode receiver is device depen-
  dent and will	vary, but is often a serial port.

  For configuration purposes, xntpd treats reference clocks like normal	NTP
  peers.  However, unlike normal peers,	reference clocks are referred to by
  an invalid IP	address.

  Reference clock addresses are	of the form 127.127.t.u, where t is an
  integer denoting the clock type and u	indicates the type-specific unit
  number, in the range 0-3, that is used to identify multiple instances	of
  clocks of the	same type.  Most of these clocks require support in the	form
  of a serial port or special bus peripheral. The particular device is nor-
  mally	specified by adding a soft link	/dev/device%d to the particular
  hardware device involved.  The device	is compiled in xntpd according to the
  clock	type.

  The following	table lists the	supported reference clock types, device
  names, clock names, and descriptions:
  ________________________________________________________________
  Type	 Device	  Name	      Description
  ________________________________________________________________
  1	 (none)	  LOCAL	      Undisciplined Local Clock
  3	 pst	  WWV_PST     PSTI/Traconex WWV/WWVH Receiver
  4	 wwvb	  WWVB_SPEC   Spectracom WWVB Receiver
  5	 true	  TRUETIME    TrueTime GPS/GOES/OMEGA Receivers
  15	 true	  TRUETIME    TrueTime Generic Receivers (alias)
  18	 acts	  NIST_ACTS   NIST Automated Computer Time Service
  25	 true	  TRUETIME    TrueTime Generic Receivers (alias)
  ________________________________________________________________

				     Note

       Although	clock types 15 and 25 still exist as aliases for True-
       Time clocks, it is best to use type 5, because the aliases might
       change in the future.


  Reference clocks are configured using	a server statement in the configura-
  tion file.  Typically, this is the only command necessary to configure a
  reference clock.  The	following is the format	for this command:

  server 127.127.t.u [prefer] [mode m] [minpoll	#] [maxpoll #]

  In the preceding command:

  t   Specifies	the clock type number.

  u   Specifies	the unit number.  This is typically 1, but can range from 0-
      3.

  prefer
      Modifies the clock selection algorithm.

  mode m
      Specifies	a clock	mode for those clock drivers that support multiple
      modes of operation.

  minpoll #

  maxpoll #
      Specifies	the minimum and	maximum	polling	interval for reference clock
      messages,	in seconds to the power	of two.	For most directly connected
      reference	clocks,	both minpoll and maxpoll default to 6 (64 seconds).
      For modem	reference clocks, minpoll defaults to 10 (147.1	minutes) and
      maxpoll defaults to 14 (4.5 hours). The allowable	range is 4 (16
      seconds) to 17 (36.4 hours) inclusive.

  Reference clock support provides the fudge command, which can	be used	to
  configure reference clocks in	special	ways.  This command must follow	the
  corresponding	server command in the configuration file.  The following is
  the format for this command:


  fudge	127.127.t.u [time1 secs] [time2	secs] [stratum #] [refid id] [mode #]
  [flag1 0|1] [flag2 0|1] [flag4 0|1]

  time1	secs
      Specifies	a fixed-point decimal number (in seconds) to be	added to the
      time offset produced by xntpd. This provides a way to correct a
      systematic error or bias by a particular clock.

  time2	secs
      Specifies	a fixed-point decimal number that is interpreted in a clock-
      dependent	way.

  mode #
      Specifies	a mode number which is interpreted in a	device-specific
      fashion.	For instance, it selects a dialing protocol in the ACTS
      driver and a device subtype in the parse drivers.

  stratum #
      Specifies	a number in the	range 0	(zero) to 15, if you want to override
      the default stratum assigned by xntpd.

  refid	id
      Specifies	a four-character, null-terminated ASCII	string,	if you want
      to override the default reference	identifier assigned by xntpd.

  flag1
      A	flag whose interpretation depends on the clock receiving it.

  flag2
      A	flag whose interpretation depends on the clock receiving it.

  flag4
      Enables detailed status monitoring and event recording.  The data	col-
      lected are written to the	clockstats file	maintained by the filegen
      utility (See xntpd(8)).  This file is normally processed by a cron job
      run once per day to produce summary statistics and performance data.

  The clock drivers, and the addresses used to configure them, are described
  as follows:

  127.127.1.u -	Undisciplined Local Clock

  This driver can have the following applications:

    +  Allow a machine to use its own system clock as a	reference clock,
       using no	outside	clock discipline source.  This is useful if you	want
       to use NTP in an	isolated environment with no radio clock or NIST
       modem available.	 Choose	a machine that has a good clock	oscillator
       and configure it	with this support.  Set	the clock using	the best
       means available.	Then, point all	the other machines at this one or use
       broadcast (not multicast) mode to distribute time.

    +  You want	to use a particular server's clock as the clock	of last
       resort when all other normal synchronization sources have gone away.
       This is useful if that server has an ovenized oscillator. For this you
       would configure this clock at a higher stratum (3 or 4) to prevent the
       server's	stratum	from falling below that.

    +  An external discipline source is	available, such	as the NIST
       "lockclock" program, which synchronizes the local clock using a tele-
       phone modem and the NIST	Automated Computer Time	Service	(ACTS),	or
       the Digital Time	Synchronization	Service	(DTSS),	which runs on DCE
       machines.  In this case,	set the	stratum	to zero, indicating a bona
       fide stratum-1 source.  Use this	with caution since there is no easy
       way to telegraph	through	NTP that something might be wrong in the dis-
       cipline source itself.  In the case of DTSS, the	local clock can	have
       a rather	large jitter, depending	on the interval	between	corrections
       and the intrinsic frequency error of the	clock oscillator.  In extreme
       cases, this can cause clients to	exceed the 128-ms slew window and
       drop off	the NTP	subnet.


  In the default mode, the behavior of the clock selection algorithm is	modi-
  fied when this support is in use.  The algorithm is designed so that the
  local	clock support is not selected unless no	other discipline source	is
  available.  This can be overridden with the prefer keyword of	the server
  configuration	command, in which case only this support is selected for syn-
  chronization and all other discipline	sources	are ignored.  This behavior
  is intended for use when an external discipline source controls the system
  clock.

  Fudge	Factors

  By default, the stratum for this driver LCLSTRATUM is	set at 3 and the
  reference ID is set to LCL.  Both can	be changed by the fudge	command	or
  the xntpdc utility.  Never configure this driver to operate at a stratum
  that might disrupt a client with access to a bona fide primary server,
  unless the local clock oscillator is reliably	disciplined by another
  source.  Never configure a server that might devolve to an undisciplined
  local	clock to use multicast mode.

  This driver provides a mechanism to trim the local clock in both time	and
  frequency, as	well as	a way to manipulate the	leap bits.  The	fudge time1
  parameter adjusts the	time (in seconds) and the fudge	time2 parameter
  adjusts the frequency	(in ppm).  Both	parameters are additive; that is,
  they add increments in time or frequency to the present values. Note:	The
  frequency cannot be changed when the kernel modifications are	in use.	 The
  fudge	flag1 and fudge	flag2 bits set the corresponding leap bits.  For
  example, setting flag1 causes	a leap second to be added at the end of	the
  UTC day.  These bits are not reset automatically when	the leap takes place;
  they must be turned off manually after the leap event.

  127.127.3.u -	PSTI/Traconex WWV/WWVH Receiver

  This driver supports the PSTI	1010 and Traconex 1020 WWV/WWVH	Receivers. No
  specific claim of accuracy is	made for these receivers, but actual experi-
  ence suggests	that 10	ms would be a conservative assumption.

  The DIP switches should be set for 9600 bps line speed, 24-hour day-of-year
  format and UTC time zone. Automatic correction for DST should	be disabled.
  It is	very important that the	year be	set correctly in the DIP switches;
  otherwise, the day of	year will be incorrect after 28	April of a normal or
  leap year. The propagation delay DIPswitches should be set according to the
  distance from	the transmitter	for both WWV and WWVH, as described in the
  instructions.	While the delay	can be set only	to within 11 ms, the fudge
  time1	parameter can be used for vernier corrections.

  Using	the poll sequence QTQDQM, the response timecode	is in three sections
  totaling 50 ASCII printing characters, as concatenated by the	driver,	in
  the following	format:

       ahh:mm:ss.fffs<cr> yy/dd/mm/ddd<cr> frdzycchhSSFTttttuuxx<cr>

  In the preceding format:

  a   Is an AM/PM indicator.  If this is a space (" "),	it indicates 24-hour
      mode.

  hh:mm:ss.fff
      Denotes hours, minutes, seconds, and milliseconds.  LI "s" Is a
      daylight-saving indicator.  If this is a space ("	"), it indicates 24-
      hour mode.

  first	<&lt;cr>&gt;
      Denotes on-time.

  yy  Denotes year (from DIP switches).

  dd/mm/ddd
      Denotes day of month, month, and day of year.

  f   Denotes frequency	enable (O = all	frequencies enabled).

  r   Denotes baud rate	(3 = 1200, 6 = 9600).

  d   Is a features indicator (@ = month/day display enabled).

  z   Denotes time zone	(0 = UTC).

  y   Denotes year (5 =	91).

  cc  Denotes WWV propagation delay (52	= 22 ms).

  hh  Denotes WWVH propagation delay (81 = 33 ms).

  SS  Denotes status (80 or 82 = operating correctly).

  F   Denotes current receive frequency	(4 = 15	MHz).

  T   Denotes transmitter (C = WWV, H =	WWVH).

  tttt
      Denotes time since last update (0000 = minutes).

  uu  Denotes flush character (03 = ^c).

  xx  Denotes 94 (unknown).

  The alarm condition is indicated by other than '8' at	A, which occurs	dur-
  ing initial synchronization and when received	signal is lost for an
  extended period; unlock condition is indicated by other than "0000" in the
  tttt subfield	at Q.

  Fudge	Factors

  Only generic fudge factors apply.

  127.127.4.u -	Spectracom WWVB	Receiver

  This driver supports the Spectracom Model 8170 and Netclock/2	WWVB Syn-
  chronized Clock. This	clock has proven a reliable source of time, except in
  some cases of	high ambient conductive	RF interference. The claimed accuracy
  of the clock is 100 usec relative to the broadcast signal; however, in most
  cases	the actual accuracy is limited by the precision	of the timecode	and
  the latencies	of the serial interface	and operating system.

  The DIP switches on this clock should	be set to 24-hour display, AUTO	DST
  off, time zone 0 (UTC), data format 0	or 2, and baud rate 9600.

  There	are two	timecode formats used by these clocks: format 0, which is
  available with both the Netclock/2 and 8170; and format 2, which is avail-
  able only with the Netclock/2	and specially modified 8170.

  Format 0 (22 ASCII printing characters)

       <cr><lf>i  ddd hh:mm:ss	TZ=zz<cr><lf>


  In the preceding format:

  first	<&lt;cr>&gt;
	    Denotes on-time.

  hh:mm:ss  Denotes hours, minutes, and	seconds.

  i	    Is a synchronization flag.	A space	(" ") indicates	in synchroni-
	    zation; a question mark (?)	indicates out of synchronization.
	    The	alarm condition	is indicated by	other than " " at A, which
	    occurs during initial synchronization and when received signal is
	    lost for about ten hours.

  Format 2 (24 ASCII printing characters)

       <cr><lf>iqyy ddd	hh:mm:ss.fff ld

  In the preceding format:

  <&lt;cr>&gt;	    Denotes on-time.

  i	    Is a synchronization flag.	A space	(" ") indicates	in synchroni-
	    zation; a question mark (?)	indicates out of synchronization.

  q	    Is a quality indicator.  A space ("	") indicates locked and
	    A,B,C, or D	indicates unlocked.

  yy	    Denotes year (as broadcast).

  ddd	    Denotes day	of year.

  hh:mm:ss.fff
	    Denotes hours, minutes, seconds, and milliseconds.

  The alarm condition is indicated by other than " " at	A, which occurs	dur-
  ing initial synchronization and when received	signal is lost for about ten
  hours. The unlock condition is indicated by other than " " at	Q.

  The Q	is normally " "	when the time error is less than 1 ms, but either
  A,B,C, or D when the time error is less than 10 ms, 100 ms, 500 ms, or
  greater than 500 ms, respectively.  The L is normally	" ", but is set	to
  "L" early in the month of an upcoming	UTC leap second	and reset to ' ' on
  the first day	of the following month.	 The D is set to 'S' for standard
  time 'I' on the day preceding	a switch to daylight time, 'D' for daylight
  time and 'O' on the day preceding a switch to	standard time. The start bit
  of the first <cr> is synchronized to the indicated time as returned.

  This driver interpolates the format in use from the length of	the message.
  A three-stage	median filter is used to reduce	jitter and provide a disper-
  sion measure.	 The driver makes no attempt to	correct	for the	intrinsic
  jitter of the	radio itself, which is a known problem with the	older radios.

  Fudge	Factors

  This driver can retrieve a table of quality data maintained internally by
  the Netclock/2 receiver.  If flag4 of	the fudge configuration	command	is
  set to 1, the	driver retrieves this table and	writes it to the clockstats
  file when the	first timecode message of a new	day is received.

  127.127.5.u -	TrueTime GPS/GOES/OMEGA	Receivers

  This driver supports several models of Kinemetrics/TrueTime Timing
  Receivers, including the 468-DC MK III GOES Synchronized Clock, GPS- DC MK
  III and GPS/TM-TMD GPS Synchronized Clock, XL-DC (a 151-602-210, reported
  by the driver	as a GPS/TM-TMD), GPS-800 TCU (an 805-957 with the RS232
  Talker/Listener module), OM-DC OMEGA Synchronized Clock, and very likely
  others in the	same model family that use the same timecode format.

  These	clocks are connected to	a serial port.	Up to four units, with unit
  numbers in the range 0 through 3, can	be configured.	The driver assumes
  the serial port device name is /dev/truex (for example, unit 1 at
  127.127.5.1 opens the	clock at /dev/true1) and that the clock	is configured
  for 9600-baud	operation.

  TrueTime clocks have the following timecode format:

       ADDD:HH:MM:SSQCL

  In the preceding format:

  A	    Denotes control-A (^A), which is stripped before the user sees
	    it.

  ddd	    Denotes day	of year.

  HH:MM:SS  Denotes hours, minutes, and	seconds.

  Q	    Is a quality indicator.

  C	    Denotes carriage return, or	on time.  Start	bit begins on 0
	    seconds and	extends	to 1 bit time.

  L	    Denotes line feed.

  The quality codes report the following offsets for all receivers:

  ?	    +/-	500 milliseconds

  #	    +/-	50 milliseconds

  *	    +/-	5 milliseconds

  .	    +/-	1 millisecond

  space	    Less than 1	millsecond

  The OM-DC OMEGA Receiver adds	the following codes:

  >&gt;	    +/-	1 second

  A-H	    Less than 1	millisecond. Indicates which station is	being
	    received as	follows:

	    A	      Norway

	    B	      Liberia

	    C	      Hawaii

	    D	      North Dakota

	    E	      La Reunion

	    F	      Argentina

	    G	      Australia

	    H	      Japan

  Notes	on 468-DC and OMEGA receiver:


  Send the clock an R or C, and	once per second	a timestamp will appear. Send
  an R to get the satellite position once (GOES	only).

  Notes	on the 468-DC receiver:


  Since	the old	east/west satellite locations are only historical, you cannot
  set your clock propagation delay settings correctly and still	use automatic
  mode.	The manual says	to use a compromise when setting the switches. This
  results in significant errors. The solution is to use	fudge time1 and	time2
  to incorporate corrections. If your clock is set for 50 and it should	be 58
  for using the	west and 46 for	using the east,	use the	following fudge	line:

       fudge 127.127.5.0 time1 +0.008 time2 -0.004

  This corrects	the 4 milliseconds advance and 8 milliseconds retard needed.
  The software will ask	the clock which	satellite it sees.

  Fudge	Factors

  Only generic fudge factors apply.

  127.127.18.u - NIST Automated	Computer Time Service

  This driver supports the NIST	Automated Computer Time	Service	(ACTS).	 It
  periodically dials a prespecified telephone number, receives the NIST
  timecode data	and calculates the local clock correction.  It designed	for
  use when neither a radio clock nor connectivity to Internet time servers is
  available.  For the best accuracy, the individual telephone line/modem
  delay	needs to be calibrated using outside sources.

  The ACTS is located at NIST Boulder, CO, telephone 303-494-4774.  A toll
  call from Newark, DE,	costs between three and	four cents, although it	is
  not clear what carrier and time of day discounts apply.  The modem dial
  string will differ depending on local	telephone configuration, and is
  specified by the phone command in the	configuration file.  The argument to
  this command is an AT	command	for a Hayes compatible modem.

  The accuracy produced	by this	driver should be in the	range of a mil-
  lisecond or two, but may need	correction due to the delay characteristics
  of the individual modem involved.  For undetermined reasons, some modems
  work with the	ACTS echo-delay	measurement scheme and some do not.  This
  driver tries to do the best it can with what it gets.	Initial	experiments
  with a Practical Peripherals 9600SA modem in Delaware	suggest	an accuracy
  of a millisecond or two can be achieved without the scheme by	using a	fudge
  time1	value of 65.0 ms.  In either case, the dispersion for a	single call
  involving ten	samples	is about 1.3 ms.

  The driver can operate in either of three modes, as determined by the	mode
  parameter in the server configuration	command.  In mode 0 (automatic), the
  driver operates continuously at intervals depending on the prediction
  error, as measured by	the driver, usually in the order of several hours.
  In mode 1, (backup) the driver is enabled in automatic mode only when	no
  other	source of synchronization is available and when	more than MAXOUTAGE
  (3600	s) have	elapsed	since last synchronized	by other sources.  In mode 2,
  (manual) the driver operates only when enabled using a fudge flags switch
  (see Fudge Factors).

  For reliable call management,	this driver requires a 1200-bps	modem with a
  Hayes-compatible command set and control over	the modem data terminal	ready
  (DTR)	control	line. Present restrictions require the use of a	POSIX-
  compatible programming interface, although other interfaces may work as
  well.	The ACTS telephone number and modem setup string are hard-coded	in
  the driver and may require changes for nonstandard modems or special cir-
  cumstances.

  Fudge	Factors

  Ordinarily, the propagation time correction is computed automatically	by
  ACTS and the driver. When this is not	possible or erratic due	to individual
  modem	characteristics, the fudge flag2 switch	should be set to disable the
  ACTS echo-delay scheme. In any case, the fudge time1 parameter can be	used
  to adjust the	propagation delay as required.

  The ACTS call	interval is determined in one the following ways:

    +  In manual mode, a call is initiated by setting fudge flag1 using
       xntpdc, either manually or by a cron job.

    +  In automatic mode, this flag is set by the peer timer, which is con-
       trolled by the sys_poll variable	in response to measured	errors.

    +  In backup mode, the driver is ordinarily	asleep,	but awakes (in
       automatic mode) if all other synchronization sources are	lost.

  In either automatic or backup	modes, the call	interval increases as long as
  the measured errors do not exceed the	value of the fudge time2 parameter.

  When the fudge flag1 is set, the ACTS	calling	program	is activated.  This
  program dials	each number listed in the phones command of the	configuration
  file in turn.	If a call attempt fails, the next number in the	list is
  dialed. The fudge flag1 and counter are reset	and the	calling	program	ter-
  minated if a valid clock update has been determined, no more numbers remain
  in the list, a device	fault or timeout occurs, or fudge flag1	is reset
  manually using xntpdc.

  The NIST timecode message is transmitted at 1200 bps in the following	for-
  mat:

       jjjjj yy-mm-dd hh:mm:ss tt l uuu	mmmmm UTC(NIST)	*

  In the previous messages:

  jjjjj	    Denotes the	modified Julian	day.

  yy-mm-dd  Denotes the	year, month, and day.

  hh:mm:ss  Denotes the	hours, minutes,	and seconds.

  tt	    Is the DST indicator (see driver listing).

  l	    Is the leap-second warning (see driver listing).

  uuu	    Denotes DUT1 correction (see driver	listing).

  mmmmm	    Denotes modem calibration (see driver listing).

  *	    Denotes an on-time character.

  The timecode message is transmitted continuously after a signon banner,
  which	this driver ignores.  The driver also ignores all but the yy-mm-dd,
  hh:mm:ss and on-time character (*) fields, although it checks	the format of
  all fields of	the message.  A	time stamp is captured at the *	character, as
  required by the ACTS specification, and used as the reference	time of	the
  timecode.  If	a message with an on-time character of # is received, the
  driver updates the propagation delay.	 The driver disconnects	when ten
  valid	messages have been received, no	message	has been received for 15
  seconds, or an # on-time character is	received.  These messages are pro-
  cessed by a trimmed-mean filter to reduce timing noise and then by the
  usual	NTP algorithms to develop the clock correction.


  The behavior of the clock selection algorithm	is modified when this driver
  is in	use.  The algorithm is designed	so that	this driver will never be
  selected unless no other discipline source is	available.  This can be	over-
  ridden with the prefer keyword of the	server configuration command, in
  which	case only this driver will be selected for synchronization and all
  other	discipline sources will	be ignored.  Ordinarily, the prefer keyword
  is used only in automatic mode when primary time is to be obtained through
  ACTS,	and backup NTP peers used only when ACTS fails.

  Call Management

  Since	ACTS is	a toll call in most areas of the country, it is	necessary to
  carefully manage the calling interval.  The ACTS call	program	is initiated
  by setting fudge flag1.  This	flag can be set	manually using xntpdc, by a
  cron job that	calls xntpdc, or automatically by the driver itself.  The
  fudge	flag1 is reset when the	program	terminates after a time	determination
  is complete or when no more numbers remain in	the alternate path list; a
  device fault or timeout has occurred;	or the fudge flag1 has been reset
  using	xntpdc.

  In automatic and backup modes, the driver determines the call	interval
  using	a procedure depending on the measured prediction error and the fudge
  time2	parameter.  If the error exceeds time2 for a number of times depend-
  ing on the current interval, the interval is decreased, but not less than
  about	1000 seconds.  If the error is less than time2 for some	number of
  times, the interval is increased, but	not more than about 18 hours.  With
  the default value of zero for	fudge time2, the interval increases from 1000
  seconds to the 4000-8000 second range, in which the expected accuracy
  should be in the 1-2 ms range.  Setting fudge	time2 to a large value,	like
  0.1 second, may result in errors of that order, but increase the call
  interval to the maximum.  The	exact value for	each configuration depends on
  the modem and	operating system involved; you might have to experiment.

  Manual call attempts can be made at any time by setting fudge	flag1 using
  xntpdc. For example, the following xntpdc command asks for a key identifier
  and password and, if authenticated by	the server, sets flag1:

       fudge 127.127.18.1 flags	1

  There	might be a short delay until the expiration of the current poll
  timeout.

  The flag1 can	be set from a cron job using the following steps:

   1.  Create a	file with the following	contents:
	    keyid 11
	    passwd dialup
	    fudge 127.127.18.1 flags 1
	    quit

   2.  Run the following program at specified times as required:
	    /usr/local/bin/xntpdc file

FILES

  /etc/ntp.conf
	    Default name of the	configuration file

  /etc/ntp.drift
	    Conventional name of the drift file

  /etc/ntp.keys
	    Conventional name of the key file



RELATED	INFORMATION

  Commands: ntp(1), ntpdate(8),	ntpq(8), xntpd(8), xntpdc(8)

  Files: ntp.keys(4)

  Network Administration: Services