unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



xntpdc(8)							    xntpdc(8)



NAME

  xntpdc - Monitor and control program for the Network Time Protocol daemon

SYNOPSIS

  /usr/bin/xntpdc [-ilnps] [-c command]	[host1 host2...]

OPTIONS

  -i  Forces xntpdc to operate in interactive mode.  Prompts will be written
      to the standard output and commands read from the	standard input.

  -l  Obtains a	list of	peers which are	known to the server(s).	 This switch
      is equivalent to -c listpeers.

  -n  Outputs all host addresses in dotted decimal notation rather than	con-
      verting to the canonical host names.

  -p  Prints a list of the peers known to the server as	well as	a summary of
      their state.  This is equivalent to -c peers.

  -s  Prints a list of the peers known to the server as	well as	a summary of
      their state, but in a slightly different format than the -p option.
      This is equivalent to -c dmpeers.

  -c command
      Interprets command as an interactive format command and adds it to the
      list of commands to be executed on the specified host(s).	 Multiple -c
      options may be given.

  Specifying a command line option other than -i or -n sends the specified
  query	(queries) to the indicated host(s) immediately;	if no host is speci-
  fied,	localhost is the default. Otherwise, xntpdc attempts to	read interac-
  tive format commands from the	standard input.

DESCRIPTION

				     Note

       The latest versions of the xntpdc command and xntpd daemon, delivered
       with NTP	Version	4, are incompatible with previous versions of NTP. If
       you use the latest xntpdc command to collect information	from an	older
       xntpd daemon, or	an older xntpdc	command	to collect information from
       the latest xntpd	daemon,	you will receive inconsistent results.

  The xntpdc program enables system managers to	monitor	and control the
  xntpd(8) daemon, and to make runtime configuration changes to	xntpd running
  either locally or remotely. The program may be run either in interactive
  mode or controlled using command line	arguments.  Extensive state and
  statistics information is available through the xntpdc interface.


  If one or more request options is included on	the command line when xntpdc
  is executed, each of the requests will be sent to the	NTP servers running
  on each of the hosts given as	command	line arguments,	or on localhost	by
  default.  If no request options are given, xntpdc attempts to	read commands
  from the standard input and execute these on the NTP server running on the
  first	host given on the command line,	again defaulting to localhost when no
  other	host is	specified. The xntpdc program prompts for commands if the
  standard input is a terminal device.

  The xntpdc program uses NTP mode 7 packets to	communicate with the NTP
  server, and can be used to query any compatible server on the	network	that
  permits it.  Note: Since NTP uses the	UDP protocol, this communication will
  be somewhat unreliable, especially over large	network	topologies. The
  xntpdc program makes no attempt to retransmit	requests, and will time	out
  if the remote	host is	not heard from within a	suitable time.

COMMANDS

  Interactive Commands


  Interactive format commands consist of a keyword followed by zero or more
  arguments.  Only enough characters of	the full keyword to uniquely identify
  the command need be typed.  The output of a command is normally sent to the
  standard output, but optionally the output of	individual commands may	be
  sent to a file by appending a	>>, followed by a file name, to the command
  line.

  A number of interactive format commands are executed entirely	within the
  xntpdc program itself	and do not result in NTP mode 7	requests being sent
  to a server.	These commands are as follows:

  ? [command_keyword]
      A	? (question mark) by itself prints a list of all the command keywords
      known to this version of xntpdc.	A ? followed by	a command keyword
      prints function and usage	information about the command.

  delay	milliseconds
      Specifies	a time interval	to be added to timestamps included in
      requests that require authentication.  This is used to enable (unreli-
      able) server reconfiguration over	long delay network paths or between
      machines whose clocks are	unsynchronized.

  help [command_keyword]
      A	synonym	for the	? command.

  host [hostname]
      Sets the host to which future queries will be sent. The hostname param-
      eter may be either a host	name or	a numeric (dotted quad)address.	If
      hostname is not specified, the current hostname is used.

  hostnames yes|no
      If yes is	specified, prints host names in	information displays.  If no
      is given,	prints numeric addresses instead.  The default is yes unless
      modified using the command line -n option.

  keyid	#
      Allows the specification of a key	number to be used to authenticate
      configuration requests. This must	correspond to the key number the
      server has been configured to use	for this purpose.

  passwd
      Prompts you to type in a password	(which will not	be echoed) that	is
      used to authenticate configuration requests.  The	password must
      correspond to the	key configured for use by the NTP server for this
      purpose if such requests are to be successful.

  quit
      Exits xntpdc.

  timeout milliseconds
      Specifies	a time out period for responses	to server queries.  The
      default is about 8000 milliseconds.

  Query	Commands


  Query	commands result	in NTP mode 7 packets containing requests for infor-
  mation being sent to the server. These are read-only commands	in that	they
  make no modification of the server configuration state.

  authinfo
      Obtains and prints the state of the authentication code.

  clkbug clock_peer_address [addr2] [addr3] [addr4]
      Obtains debugging	information for	a clock	peer.  This information	is
      provided only by some clock drivers, and is mostly unreadable without a
      copy of the driver source	in hand.

  clockstat clock_address [addr2] [addr3] [addr4]
      Obtains and prints clock status information.

  ctlstats
      Obtains and prints packet	count statistics from the control module.

  debug	[no | more | less]
      Sets or changes the debugging level.

  dmpeers
      A	slightly different peer	summary	list.  Identical to the	output of the
      peers command except for the character in	the leftmost column. Charac-
      ters only	appear beside peers which were included	in the final stage of
      the clock	selection algorithm.  The following characters are used:

      .	  Indicates that this peer was cast off	in the falseticker detection.

      +	  Indicates that the peer made it through.

      *	  Denotes the peer to which the	server is currently synchronizing.

  iostats
      Prints counters maintained in the	input-output module.

  kerninfo
      Obtains and prints kernel	phase-lock loop	operating parameters. This
      information is available only if the kernel has been specially modified
      for a precision timekeeping function.

  leapinfo
      Obtains and prints current leap second state.

  listpeers
      Obtains and prints a brief list of the peers for which the server	is
      maintaining state.  These	should include all configured peer associa-
      tions as well as those peers whose stratum is such that they are con-
      sidered by the server to be possible future synchronization candidates.

  loopinfo [oneline|multiline]
      Prints the values	of selected loop filter	variables.  The	loop filter
      is the part of NTP which deals with adjusting the	local system clock.
      The offset is the	last offset given to the loop filter by	the packet
      processing code.	The frequency is the frequency error, or drift,	of
      your system's clock in parts-per-million (ppm). The time_const controls
      the "stiffness" of the phase-lock	loop and thus the speed	at which it
      can adapt	to oscillator drift. The watchdog timer	value is the number
      of seconds that have elapsed since a new sample offset was given to the
      loop filter.  The	oneline	and multiline options specify the format in
      which this information is	to be printed; multiline is the	default.

  memstats
      Prints a number of counters related to the peer memory allocation	code.

  monlist version
      Obtains and prints traffic counts	collected and maintained by the	moni-
      tor facility. The	version	number should not normally need	to be speci-
      fied.

  peers
      Obtains a	list of	peers for which	the server is maintaining state,
      along with a summary of that state.  Summary information includes	the
      address of the remote peer, the local interface address (0.0.0.0 if a
      local address has	yet to be determined), the stratum of the remote peer
      (a stratum of 16 indicates the remote peer is unsynchronized), the pol-
      ling interval, in	seconds, the reachability register, in octal, and the
      current estimated	delay, offset and dispersion of	the peer, all in
      seconds.	In addition, the character in the left margin indicates	the
      current mode for this peer entry.	The following characters are used:

      +	  Denotes symmetric active.

      -	  Indicates symmetric passive.

      =	  Indicates the	remote server is being polled in client	mode.

      ^	  Indicates that the server is broadcasting to this address.

      ~	  Denotes that the remote peer is sending broadcasts.

      *	  Marks	the peer the server is currently synchronizing to.

      The contents of the host field may be one	of four	forms. It may be a
      host name, an IP address,	a reference clock implementation name with
      its parameter or REFCLK(implementation number, parameter). On hostnames
      no only, IP-addresses will be displayed.

  pstats peer_address [addr2] [addr3] [addr4]
      Shows per-peer statistic counters	associated with	the specified
      peer(s).

  reslist
      Obtains and prints the server's restriction list.	 This list is (usu-
      ally) printed in sorted order and	may help to understand how the res-
      trictions	are applied.

  showpeer peer_address	[addr2]	[addr3]	[addr4]
      Shows a detailed display of the current peer variables for one or	more
      peers.  Most of these values are described in the	NTP Version 2 specif-
      ication.

  sysinfo
      Prints a variety of system state variables, that is the state related
      to the local server.  Many of these values are described in the NTP
      Version 3	specification, RFC 1305.  The system options show various
      system options, some of which can	be set and cleared by the enable and
      disable configuration commands, respectively. The	stability is the
      residual frequency error remaining after the system frequency correc-
      tion is applied and is intended for maintenance and debugging. In	most
      architectures, this value	will initially decrease	from as	high as	500
      ppm to a nominal value in	the range .01 to 0.1 ppm. If it	remains	high
      for some time after starting the daemon, something may be	wrong with
      the local	clock, or the value of the kernel variable tick	may be
      incorrect.  The broadcastdelay shows the default broadcast delay,	as
      set by the broadcastdelay	configuration command, while the authdelay
      shows the	default	authentication delay, as set by	the authdelay
      configuration command.

  sysstats
      Prints a number of stat counters maintained in the protocol module.

  timerstats
      Prints counters maintained in the	timer/event queue support code.

  version
      Prints the xntpdc	program	version	number.

  Runtime Configuration	Requests


  All requests that cause state	changes	in the server are authenticated	by
  the server using a configured	NTP key	(the facility can also be disabled by
  the server by	not configuring	a key).	 The key number	and the	corresponding
  key must also	be made	known to xtnpdc. This can be done using	the keyid and
  passwd commands, the latter of which will prompt at the terminal for a
  password to use as the encryption key.  You will also	be prompted automati-
  cally	for both the key number	and password the first time a command which
  would	result in an authenticated request to the server is given.  Authenti-
  cation not only provides verification	that the requester has permission to
  make such changes, but also gives an extra degree of protection again
  transmission errors.

  Authenticated	requests always	include	a time stamp in	the packet data,
  which	is included in the computation of the authentication code.  This time
  stamp	is compared by the server to its receive time stamp.  If they differ
  by more than a small amount the request is rejected.	This is	done for two
  reasons.  First, it makes simple replay attacks on the server, by someone
  who might be able to overhear	traffic	on your	LAN, much more difficult.
  Second, it makes it more difficult to	request	configuration changes to your
  server from topologically remote hosts.  While the reconfiguration facility
  will work well with a	server on the local host, and may work adequately
  between time-synchronized hosts on the same LAN, it will work	very poorly
  for more distant hosts.  As such, if reasonable passwords are	chosen,	care
  is taken in the distribution and protection of keys and appropriate source
  address restrictions are applied, the	run time reconfiguration facility
  should provide an adequate level of security.

  The following	commands all make authenticated	requests:

  addpeer peer_address [keyid] [version#] [prefer]
      Adds a configured, symmetric active peer association with	a peer at the
      given address.  If the optional keyid is a nonzero integer, all outgo-
      ing packets to the remote	server have an authentication field attached
      that is encrypted	with this key.	If the value is	0 (or not given), no
      authentication is	done.  The version# can	be 1, 2, or 3; the default is
      3.  The prefer keyword indicates a preferred peer	(and thus will be
      used primarily for clock synchronisation if possible).  The preferred
      peer also	determines the validity	of the PPS signal -- if	the preferred
      peer is suitable for synchronisation so is the PPS signal.

  addrefclock address [mode] [minpoll |	prefer]	[minpoll | prefer]
      Adds a new server	at address.  The prefer	keyword	indicates a preferred
      peer (and	thus will be used primarily for	clock synchronisation if pos-
      sible).  The preferred peer also determines the validity of the PPS
      signal - if the preferred	peer is	suitable for synchronisation so	is
      the PPS signal. If minpoll is specified, the polling interval for	the
      association will remain clamped at the minimum.

  addserver peer_address [keyid] [version#] [prefer]
      Identical	to the addpeer command except that operating mode is client.

  addtrap address [port] [interface]
      Sets a trap for asynchronous messages.

  authinfo
      Returns information concerning the authentication	module,	including
      known keys and counts of encryptions and decryptions which have been
      done.

  broadcast peer_address [keyid] [version#]
      Identical	to the addpeer command except that packets are instead sent
      in broadcast mode.  In this case a valid key identifier and key are
      required.	The peer_address parameter can be the broadcast	address	of
      the local	network	or a multicast group address assigned to NTP. If a
      multicast	address, a multicast-capable kernel is required.

  clrtrap address [port] [interface]
      Clears a trap for	asynchronous messages.

  controlkey keyid
      Changes the authorization	key identifier that the	server uses to
      authenticate control messages to keyid.

  delrestrict address mask [ntpport]
      Deletes the matching entry from the restrict list.

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

  enable auth|bclient|pll|pps|monitor|stats
      Provides a way to	enable the following server options. Options not men-
      tioned 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 option 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 option is dis-
	  able (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 option 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.

      pps

      monitor
	  Enables the monitoring facility (see elsewhere), with	default	dis-
	  able (off).

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

  fudge	peer_address [time1] [time2] [stratum] [refid]
      This command provides a way to set certain data for a reference clock.

  keytype key type [md5|des]
      Set the key type to use for authenticated	requests.

  monitor yes|no
      Enables or disables the monitoring facility.  A monitor no command fol-
      lowed by a monitor yes command is	a good way of resetting	the packet
      counts.

  preset peer_address [addr2] [addr3] [addr4]
      Resets the statistics counters associated	with peers at the designated
      addresses.

  readkeys
      Causes the current set of	authentication keys to be purged and a new
      set to be	obtained by rereading the keys file (which must	have been
      specified	in the xntpd configuration file).  This	allows encryption
      keys to be changed without restarting the	server.

  reset	...
      Clears the statistics counters in	various	modules	of the server.

  restrict address mask	flag [flag]
      Causes flag(s) to	be added to an existing	restrict list entry, or	adds
      a	new entry to the list with the specified flag(s).  The possible
      choices for the flags arguments are as follows:

      ignore
	  Ignores all packets from hosts that match this entry.	 If this flag
	  is specified neither queries nor time	server polls will be
	  responded to.

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

      nomodify
	  Ignores all NTP mode 7 packets that attempt to modify	the state of
	  the server (run time reconfiguration).  Queries that return infor-
	  mation 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	over-
	  ridden by later requests for normal priority traps.

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

      nopeer
	  Provides stateless time service to polling hosts, but	do not allo-
	  cate peer memory resources to	these hosts even if they otherwise
	  might	be considered useful as	future synchronization partners.

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

      limited
	  These	hosts are subject to limitation	of number of clients 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 client_limit hosts	that
	  have shown up	at the server and that have been active	during the
	  last client_limit_period 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 are not contri-
	  buting to client count. History of clients is	kept using the moni-
	  toring capability of xntpd. Thus, monitoring is active as long as
	  there	is a restriction entry with the	limited	flag. The default
	  value	for client_limit is 3. The default value for
	  client_limit_period is 3600 seconds. Currently both variables	are
	  not runtime configurable.

      ntpport
	  This is actually a match algorithm modifier, rather than a restric-
	  tion 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.

  setprecision precision_value
      Sets the precision which the server advertises to	the specified value.
      This should be a negative	integer	in the range -4	through	-20.

  traps
      Displays the traps set in	the server.

  trustkey keyid [keyid] [keyid] [keyid]
      Adds one or more keys to the trusted key list.  When authentication is
      enabled, peers whose time	is to be trusted must be authenticated using
      a	trusted	key.

  unconfig peer_address	[addr2]	[addr3]	[addr4]
      This command causes the configured bit to	be removed from	the specified
      peer(s).	In many	cases this causes the peer association to be deleted.
      When appropriate,	however, the association may persist in	an unconfig-
      ured mode	if the remote peer is willing to continue on in	this fashion.

  unrestrict address mask flag [flag]
      Removes the specified flag(s) from the restrict list entry indicated by
      the address and mask arguments.

  untrustkey keyid [keyid] [keyid] [keyid]
      Removes one or more keys from the	trusted	key list.

ERRORS

    +  ***Can't	find host hostname

       Explanation:

       The hostname is not in the local	/etc/hosts file.

    +  hostname: timed out, nothing received ***Request	timed out

       Explanation:

       Check that xntpd	is running on the remote host being queried.


SEE ALSO

  Commands: ntpdate(8),	ntpq(8), xntpd(8)


  Files: ntp.conf(4)