unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 xntpd(1M)							   xntpd(1M)




 NAME
      xntpd - Network Time Protocol daemon

 SYNOPSIS
      xntpd [ -abdm ] [ -c conffile ] [ -e authdelay ] [ -f driftfile ]

	   [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -r broadcastdelay ]

	   [ -s statsdir ] [ -t key ] [ -v variable ] [ -V variable ] [ -x ]

 DESCRIPTION
      xntpd is an operating system daemon which sets and maintains the
      system time-of-day in synchronism with Internet standard time servers.
      xntpd is a complete implementation of the Network Time Protocol (NTP)
      version 3, as defined by RFC-1305, but also retains compatibility with
      version 1 and 2 servers as defined by RFC-1059 and RFC-1119,
      respectively.

      xntpd does all computations in 64-bit fixed point arithmetic and
      requires no floating point support. While the ultimate precision of
      this design, about 232 picoseconds, is not achievable with ordinary
      workstations and networks of today, it may be required with future
      nanosecond CPU clocks and gigabit LANs.

      The daemon can operate in any of several modes, including symmetric
      active/passive, client/server and broadcast/multicast, as described in
      RFC-1305. A broadcast/multicast client can discover remote servers,
      compute server-client propagation delay correction factors and
      configure itself automatically. This makes it possible to deploy a
      group of workstations without specifying configuration details
      specific to the local environment.

      Ordinarily, xntpd reads the /etc/ntp.conf configuration file at
      startup time in order to determine the synchronization sources and
      operating modes. It is also possible to specify a working, although
      limited, configuration entirely on the command line, obviating the
      need for a configuration file. This may be particularly appropriate
      when the local host is to be configured as a broadcast or multicast
      client, with all peers being determined by listening to broadcasts at
      run time. Various internal xntpd variables can be displayed and
      configuration options altered while the daemon is running using the
      ntpq and xntpdc utility programs.

 COMMAND LINE OPTIONS
      -a		Enable authentication mode. The default is disable.

      -b		Synchronize using NTP broadcast messages.

      -c conffile	Specify the name and path of the configuration file.





 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      -d		Specify debugging mode. This flag may occur multiple
			times, with each occurrence indicating greater
			detail of display.

      -e authdelay	Specify the time (in seconds) it takes to compute
			the NTP encryption field on this computer.

      -f driftfile	Specify the name and path of the drift file.

      -k keyfile	Specify the name and path of the file containing the
			NTP authentication keys.

      -l logfile	Specify the name and path of the log file. The
			default is the system log facility.

      -p pidfile	Specify the name and path to record the daemon's
			process ID.

      -r broadcastdelay Specify the default propagation delay from the
			broadcast/multicast server and this computer. This
			is used only if the delay cannot be computed
			automatically by the protocol.

      -s statsdir	Specify the directory path for files created by the
			statistics facility.

      -t key		Add a key number to the trusted key list.

      -v variable	Add a system variable.

      -V variable	Add a system variable listed by default.

      -x		Make all adjustments by SLEW.

 THE CONFIGURATION FILE
      The xntpd configuration file is read at initial startup in order to
      specify the synchronization sources, modes and other related
      information. Usually, it is installed in the /etc/ntp.conf directory,
      but could be installed elsewhere (see the -c conffile command line
      option).

      The file format is similar to other UNIX configuration files. Comments
      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, some of which may be
      optional, separated by white space. 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 following descriptions, while alternatives are
      separated by |.  The notation [ ... ] means an optional, indefinite



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      repetition of the last item before the [ ... ].

      While there is a rich set of options available, the only required
      option is one or more server, peer or broadcast commands described in
      the "Configuration Options" section.  The examples in
      /etc/ntp.conf.example may also be helpful.

 CONFIGURATION OPTIONS
      The configuration commands are as decribed below:

      peer address [ key key_id ] [ version version_id ] [ prefer ]

      server address [ key key_id ] [ version version_id ] [ prefer ]

	   [ mode mode ]

      broadcast address [ key key_id ] [ version version_id ] [ ttl ttl ]

      The above three commands can be used to specify either the name or
      address of the time server and the mode in which the time server
      should operate. The address can be either a DNS name or an IP address
      in dotted-quad notation.

      The peer command specifies that the local server is to operate in
      symmetric active mode with the remote server. In this mode, the local
      server can be synchronized to the remote server and, in addition, 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 may be the better source of time.

      The server command specifies that the local server is to operate in
      client mode with the specified remote server. 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. This is the most common
      operating mode (by far).

      The broadcast 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/multicast address
      specified. Ordinarily, this specification applies only to the local
      server operating as a sender; for operation as a broadcast client, see
      the broadcastclient or multicastclient commands below. In this mode,
      address is usually the broadcast address of (one of) the local
      network(s) or a multicast address assigned to NTP. The address of
      224.0.1.1 is assigned to NTP. This is presently the only address that
      should be used. Note that the use of multicast features requires a
      multicast kernel.

 OPTIONS
      key key_id     All packets sent to the address are to include
		     authentication fields encrypted using the specified key



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




		     identifier, which is an unsigned 32 bit integer. The
		     default is to not include an encryption field.

      version version_id
		     Specifies the version number to be used for outgoing
		     NTP packets. Versions 1, 2, and 3 are the choices, with
		     version 3 the default.

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

      ttl ttl	     This option is used only with broadcast mode. It
		     specifies the ttl (time-to-live) to use on multicast
		     packets. Selection of the proper value, which defaults
		     to 127, must be co-ordinated with the network
		     administrator(s).

      broadcastclient [address]
		     This command directs the local server to listen for
		     broadcast messages at the broadcast address of the
		     local network. The default address is the subnet
		     address with the host field bits set to ones. Upon
		     hearing a broadcast message for the first time, the
		     local server measures 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 should operate using authentication and
		     the same trusted key and key identifier.

      driftfile driftfile
		     This command specifies the name of the file used to
		     record the frequency offset of the local clock
		     oscillator. If the file exists, it is read at startup
		     in order to set the initial frequency offset and then
		     updated once per hour with the current frequency offset
		     computed by the daemon. 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.

      enable auth|bclient|monitor|pll|pps|stats

      disable auth|bclient|monitor|pll|pps|stats
		     Provides a way to enable or disable various server
		     options. Flags not mentioned are unaffected. Note that
		     all of these flags can be controlled remotely using the



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




		     xntpdc utility program. Each of these flags are
		     described below.

		     auth    Enables 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.

		     bclient Enables the server to listen for a message from
			     a broadcast or multicast server, as in the
			     multicastclient command with default address.
			     The default for this flag is disable.

		     monitor Enables the monitoring facility. See the xntpdc
			     monlist command for further information
			     (xntpdc(1M)).

		     pll     Enables the server to adjust its local clock,
			     with  default enable. 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. In
			     this case, the local clock driver is used. See
			     the Reference Clock Drivers for further
			     information.

		     pps     Enables the pulse-per-second (PPS) signal when
			     frequency and time is disciplined by the
			     precision time kernel modifications. The
			     default is enable when these modifications are
			     available and disable otherwise.

		     stats   Enables the statistics facility. By default
			     this option is enabled.

 Authentication Key File Format
      The NTP standard specifies an extension allowing verification of the
      authenticity of received NTP packets, and to provide an indication of
      authenticity in outgoing packets.	 This is implemented in xntpd using
      the DES encryption algorithm.  The specification allows any one of a
      possible 4 billion keys, numbered with 32 bit unsigned integers, to be
      used to authenticate an association.  The servers involved in an
      association must agree on the value of the key used to authenticate
      their data, though they must each learn the key independently.  The
      keys are standard 56 bit DES keys.

      Additionally, another authentication algorithm is available which uses
      an MD5 message digest to compute an authenticator.  The length of the



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      key or password is limited to 8 characters.  xntpd reads its keys from
      a file specified using the -k command line option or the keys
      statement in the configuration file.  While key number 0 is fixed by
      the NTP standard (as 56 zero bits) and may not be changed, one or more
      of the keys numbered 1 through 15 may be arbitrarily set in the keys
      file.

      The key file uses the same comment conventions as the configuration
      file.  Key entries use a fixed format of the form

	   keyno  type	key

      where keyno is a positive integer, type is a single character which
      defines the format the key is given in, and key is the key itself.

      The key may be given in one of four different formats, controlled by
      the type character.  The four key types, and corresponding formats,
      are listed following.

      S	   The key is a 64 bit hexadecimal number in the format specified in
	   the DES document, that is the high order 7 bits of each octet are
	   used to form the 56 bit key while the low order bit of each octet
	   is given a value such that odd parity is maintained for the
	   octet.  Leading zeroes must be specified (i.e. the key must be
	   exactly 16 hex digits long) and odd parity must be maintained.
	   Hence a zero key, in standard format, would be given as
	   0101010101010101 .

      N	   The key is a 64 bit hexadecimal number in the format specified in
	   the NTP standard.  This is the same as the DES format except the
	   bits in each octet have been rotated one bit right so that the
	   parity bit is now the high order bit of the octet.  Leading
	   zeroes must be specified and odd parity must be maintained.	A
	   zero key in NTP format would be specified as 8080808080808080

      A	   The key is a 1-to-8 character ASCII string.	A key is formed from
	   this by using the lower order 7 bits of the ASCII representation
	   of each character in the string, with zeroes being added on the
	   right when necessary to form a full width 56 bit key, in the same
	   way that encryption keys are formed from Unix passwords.

      M	   The key is a 1-to-32 character ASCII string, using the MD5
	   authentication scheme.  Note that both the keys and the
	   authentication schemes (DES or MD5) must be identical between a
	   set of peers sharing the same key number.

 FILEGEN UTILITY
      filegen name [ file filename ] [ type typename ] [ link|nolink ] [
      enable|disable ]





 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      This command helps in configuring the generation-file set name.  The
      generation-file sets provides a mean for handling files that are
      continuously growing during the lifetime of a server. Server
      statistics are a typical example for such files. The generation-file
      sets provide access to a set of files used to store the actual data.
      At any time at most one element of the set is being written to. The
      type given specifies 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 operation of xntpd.
      (Most important: they can be removed to free space for new data
      produced.) Filenames of set members are built from three elements.
      name is name of the statistic to be collected. Currently only two
      kinds of statistics are supported: loopstats and peerstats.

      file	Defines a filename string directly concatenated to the
		prefix mentioned above (no intervening / (slash)) if prefix
		is defined in the statsdir statement.

      type	This part reflects individual elements of a file set. It is
		generated according to the type of a file set as explained
		below.	A file generation set is characterized by its type.
		The following typenames are supported:

		none	  The file set is actually 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 the concatenated prefix and
			  filename strings, and appending the decimal
			  representation of the process id of the xntpd
			  server process.  (e.g <prefix><filename>.<pid> )

		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 form <YYYYMMDD>.  YYYY is
			  a 4 digit year number (e.g. 1992).  MM is a two
			  digit month number.  DD is a two digit day number.
			  Thus, all information written at December 10th,
			  1992 would end up in a file named
			  <prefix><filename>.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



 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




			  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
			  end up in 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 elment is generated per year.
			  The filename suffix consists of a dot and a 4
			  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.

      enabled/disabled
		Information is only written to a file generation set when
		this set is enabled.  Output is prevented by specifying
		disabled.  The default is enabled.

      link/nolink
	   It is convenient to be able to access the current element of a
	   file generation set by a fixed name. This feature is enabled by
	   specifying link and disabled using nolink.  The default is link.
	   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.

 REFERENCE CLOCK DRIVERS
      Individual clocks can be activated by configuration file commands,
      specifically the server and fudge commands described in the xntpdc(1M)
      manual page. The following discussion presents information on how to
      select and configure the device drivers in a running UNIX system.

      Radio and modem clocks by convention have addresses in the form
      127.127.t.u, where t is the clock type and u is a unit number in the
      range 0-3 used to distinguish 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 normally



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      specified by adding a soft link /dev/deviceu to the particular
      hardware device involved, where u correspond to the unit number above.

      Following is a list showing the type and title of each driver
      currently implemented. The compile-time identifier for each is shown
      in parentheses.

      The following four clock drivers are supported by HP.

	   Type 1 Local Clock Driver (LOCAL_CLOCK)
	   Type 4 Spectracom 8170 and Netclock/2 WWVB Receivers (WWVB)
	   Type 26 Hewlett Packard 58503A GPS Receiver (HPGPS)
	   Type 29 Trimble Palisade GPS Receiver (PALISADE)

      The clock drivers mentioned below are not supported by HP. They may
      work, but have not been tested. They are provided as is, for the
      convenience of the diverse users.

	   Type 2 Trak 8820 GPS Receiver (TRAK)
	   Type 3 PSTI/Traconex 1020 WWV/WWVH Receiver (PST)
	   Type 5 TrueTime GPS/GOES/OMEGA Receivers (TRUETIME)
	   Type 8 Generic Reference Driver (PARSE)
	   Type 10 Austron 2200A/2201A GPS Receivers (AS2201)
	   Type 11 * TrueTime OMEGA Receiver
	   Type 15 * TrueTime TM-TMD GPS Receiver
	   Type 16 Bancomm GPS/IRIG Receiver (HP only) (BANC)
	   Type 17 Datum Precision Time System (DATUM)
	   Type 18 NIST Modem Time Service (ACTS)
	   Type 20 Generic NMEA GPS Receiver (NMEA)
	   Type 23 PTB Modem Time Service (PTBACTS)
	   Type 24 USNO Modem Time Service (USNO)
	   Type 25 * TrueTime generic.

      All TrueTime receivers are now supported by one driver, type 5. Types
      11, 15 and 25 will be retained only for a limited time and may be
      reassigned in future.

 DEBUGGING HINTS FOR REFERENCE CLOCK DRIVERS
      The ntpq and xntpdc utility programs can be used to debug reference
      clocks, either on the server itself or from another machine elsewhere
      in the network. The server is compiled, installed and started using
      the command-line switches described in the xntpdc(1M) manual page.

      The first thing to look for are error messages on the system log. If
      none occur, the daemon has started, opened the devices specified and
      waiting for peers and radios to come up.

      The next step is to be sure the RS232 messages, if used, are getting
      to and from the clock. The most reliable way to do this is with an
      RS232 tester and to look for data flashes as the driver polls the
      clock and/or as data arrive from the clock. Our experience is that



 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      many of the problems occurring during installation are due to problems
      such as miswired connectors or improperly configured device links at
      this stage.

      If RS232 messages are getting to and from the clock, variables can be
      inspected using the ntpq command (see ntpq(1M)).	First, use the pe
      and as commands to display billboards showing the peer configuration
      and association IDs for all peers, including the radio clock peers.
      The assigned clock address should appear in the pe billboard and the
      association ID for it at the same relative line position in the as
      billboard. If things are operating correctly, after a minute or two
      samples should show up in the pe display line for the clock.

      Additional information is available with the rv and clockvar commands,
      which take as argument the association ID shown in the as billboard.
      The rv command with no argument shows the system variables, while the
      rv command with association ID argument shows the peer variables for
      the clock, as well as any other peers of interest. The clockvar
      command with argument shows the peer variables specific to reference
      clock peers, including the clock status, device name, last received
      timecode (if relevant), and various event counters. In addition, a
      subset of the fudge parameters is included.

      The xntpdc utility program can be used for detailed inspection of the
      clock driver status. The most useful are the clockstat file and the
      commands in xntpdc (seexntpdc(1M)).

      Most drivers write a message to the clockstats file as each timecode
      or surrogate is received from the radio clock. By convention, this is
      the last ASCII timecode (or ASCII gloss of a binary-coded one)
      received from the radio clock. This file is managed by the filegen
      facility described above and requires specific commands in the
      configuration file. This forms a highly useful record to discover
      anomalies during regular operation of the clock.

 SLEW
      SLEW is not recommended by HP because it reduces accuracy and
      stability.

      The NTP daemon has three regimes in which it operates:

      offset below 128 milliseconds
	  This is the normal operating regime of NTP.  A properly configured
	  NTP hierarchy (with reasonable networking) can operate for years
	  without ever approaching the 128 millisecond upper limit. All time
	  adjustments are small and smooth (known as SLEWING), and nobody
	  even notices the SLEW adjustments unless they have a cesium clock
	  or a GPS clock and expensive instrumentation to make sophisticated
	  measurements (HP/Agilent  makes the instruments).





 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      offset above 128 milliseconds
	  This regime is often encountered at power-on because, those
	  battery-backed real-time clocks they put in computers are not too
	  great. Because NTP is quite capable of keeping the offset below
	  one millisecond all the time it is running, many users want to get
	  into the normal regime quickly when an offset above 128
	  millisecond is encountered at startup. So in this situation NTP
	  will (fairly quickly) make a single STEP change, and is usually
	  successful in getting the offset well below 128 millisecond so
	  there will be no more of the disruptive STEP changes.

      offset above 1000 seconds
	  This is so far out of the normal operating range that NTP decides
	  something is terribly wrong and human intervention is required.
	  The daemon shuts down.

      The catch is that the dispersion on a WAN is frequently much greater
      than 128 milliseconds, so you may see (a lot of) the STEP changes,
      perhaps as large as 1000 milliseconds (depends on your network). But
      there are customer applications that are quite allergic to the STEP
      changes, particularly backward steps (which will happen about half the
      time). Databases and financial transaction systems are examples.

      The good news is that NTP can be forced to never make a STEP, but
      instead SLEW the clock to drive the offset to zero. This is
      accomplished with the -x option on the command line. This effectively
      removes the middle operating regime. You won't get millisecond (or
      microsecond) precision with this method, but you probably can't get
      that over a WAN anyway.

      It is important to note that SLEWING is a cover-up for a more
      fundamental problem (poor connection to the timesource), and it does
      not solve this problem.  SLEWING is not recommended by HP because it
      causes reduced accuracy and stability, and it leads to anamolous
      behavior that can be quite confusing. For example, you will see
      messages similar to this in the syslog:

	   : time reset (step) -411.093665 s
	   : synchronisation lost
	   : synchronized to 15.13.115.194, stratum=1
	   : Previous time adjustment incomplete; residual -0.022223 sec
	   : Previous time adjustment incomplete; residual -0.020624 sec
	   : Previous time adjustment incomplete; residual -0.020222 sec
	   : Previous time adjustment incomplete; residual -0.020623 sec
	   : Previous time adjustment incomplete; residual -0.020623 sec

      But this does not mean that your system clock has been stepped. Only
      the NTP daemon process has seen a step in its notion of the current
      time (and this will be passed on to clients). The system time is being
      gradually adjusted in a series of SLEW maneuvers, and the SLEW rate is
      quite limited. Be warned that it can take a long time for the system



 Hewlett-Packard Company	   - 11 -   HP-UX Release 11i: November 2000






 xntpd(1M)							   xntpd(1M)




      clock to reach nominal correctness, and much longer to stabilize.
      Each cpu model is unique, but the maximum slew rate is typically about
      40 milliseconds per second. Thus a SLEW adjustment of 411 seconds will
      take over 10,000 seconds (about 3 hours) to complete. A better
      approach would be to run the ntpdate command once at system startup,
      and accept the one STEP change that comes with it. Then start the NTP
      daemon process xntpd and it will never make a STEP as long as your
      connection to the timesource is good. This method also overcomes the
      1000 seconds problem. The NTP startup script /sbin/rc2.d/S660xntpd
      will  do this automatically if you configure the NTPDATE_SERVER
      variable in /etc/rc.config.d/netdamons.  A properly configured NTP
      hierarchy with average networking (say 10Base-T) can run for years
      without ever making a STEP change.

 AUTHOR
      xntpd was developed by Dennis Ferguson at the University of Toronto.

      Text amended by David Mills at the University of Delaware.

 FILES
      /etc/ntp.conf	       The default configuration file

      /etc/ntp.drift	       The default drift file

      /etc/ntp.keys	       The default key file

 SEE ALSO
      ntpq(1M), ntpdate(1M), xntpdc(1M).


























 Hewlett-Packard Company	   - 12 -   HP-UX Release 11i: November 2000