Yolinux.com

ntpdc manpage

Search topic Section


ntpdc(8)		    System Manager's Manual		      ntpdc(8)



NAME
       ntpdc - special NTP query program


SYNOPSIS
       ntpdc [ -46dilnps ] [ -c command ] [ host ] [ ... ]


DESCRIPTION
       ntpdc  is  used to query the ntpd daemon about its current state and to
       request changes in that state. The program may be run either in	inter-
       active mode or controlled using command line arguments. Extensive state
       and statistics information is available through the ntpdc interface. In
       addition,  nearly  all the configuration options which can be specified
       at startup using ntpd's configuration file may also be specified at run
       time using ntpdc.

       If  one	or  more request options are included on the command line when
       ntpdc 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,  ntpdc  will
       attempt	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. ntpdc
       will prompt for commands if the standard input is a terminal device.

       ntpdc uses NTP mode 7 packets to communicate with the NTP  server,  and
       hence  can  be used to query any compatible server on the network which
       permits it. Note that since NTP is a UDP	 protocol  this	 communication
       will  be	 somewhat unreliable, especially over large distances in terms
       of network topology. ntpdc makes no attempt to retransmit requests, and
       will  time  requests  out if the remote host is not heard from within a
       suitable timeout time.

       The operation of ntpdc are specific to the particular implementation of
       the  ntpd  daemon  and can be expected to work only with this and maybe
       some previous versions of the daemon. Requests from a remote ntpdc pro-
       gram  which 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.

       Note  that  in  contexts	 where a host name is expected, a -4 qualifier
       preceding the host name forces DNS resolution to	 the  IPv4  namespace,
       while a -6 qualifier forces DNS resolution to the IPv6 namespace.


COMMAND LINE OPTIONS
       Specifying  a  command  line  option other than -i or -n will cause the
       specified query (queries) to be sent to the indicated  host(s)  immedi-
       ately.  Otherwise,  ntpdc  will attempt to read interactive format com-
       mands from the standard input.


       -4      Force DNS resolution of following host  names  on  the  command
	       line to the IPv4 namespace.

       -6      Force  DNS  resolution  of  following host names on the command
	       line to the IPv6 namespace.

       -c command
	       The following argument is interpreted as an interactive	format
	       command	and is added to the list of commands to be executed on
	       the specified host(s). Multiple -c options may be given.

       -d      Turn on debugging mode.

       -i      Force ntpdc to operate in interactive  mode.  Prompts  will  be
	       written to the standard output and commands read from the stan-
	       dard input.

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

       -n      Output  all host addresses in dotted-quad numeric format rather
	       than converting to the canonical host names.

       -p      Print a list of the peers known to the server as well as a sum-
	       mary of their state. This is equivalent to -c peers.

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


INTERACTIVE COMMANDS
       Interactive  format  commands  consist of a keyword followed by zero to
       four 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 ntpdc program itself and do not result in NTP mode 7 requests being
       sent to a server. These are described following.


       ? [ command_keyword ]

       help [ command_keyword ]
	       A ? by itself will print a list of  all	the  command  keywords
	       known  to  this	incarnation of ntpq. A ? followed by a command
	       keyword will print function and	usage  information  about  the
	       command.	 This  command is probably a better source of informa-
	       tion about ntpq than this manual page.

       delay milliseconds
	       Specify a time interval to be added to timestamps  included  in
	       requests	 which	require authentication. This is used to enable
	       (unreliable) server reconfiguration  over  long	delay  network
	       paths  or  between  machines  whose  clocks are unsynchronized.
	       Actually the server does not now require timestamps in  authen-
	       ticated requests, so this command may be obsolete.

       host hostname
	       Set the host to which future queries will be sent. Hostname may
	       be either a host name or a numeric address.

       hostnames [ yes | no ]
	       If yes is specified, host names are printed in information dis-
	       plays.  If  no  is  specified,  numeric	addresses  are printed
	       instead. The default is yes, unless modified using the  command
	       line -n switch.

       keyid keyid
	       This  command  allows  the  specification of a key number to be
	       used to authenticate configuration requests from ntpdc  to  the
	       host(s).	 This  must  correspond	 to  a	key  number  which the
	       host/server has been configured to use for this purpose (server
	       options:	 trustedkey, and requestkey). If authentication is not
	       enabled on the host(s) for ntpdc commands, the  command	"keyid
	       0"  should be given; otherwise the keyid of the next subsequent
	       addpeer/addserver/broadcast  command will be used.

       quit    Exit ntpdc.

       passwd  This command prompts you to type in a password (which will  not
	       be  echoed)  which  will	 be 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.

       timeout milliseconds
	       Specify a timeout period for responses to server	 queries.  The
	       default	is  about  8000	 milliseconds.	Note  that since ntpdc
	       retries each query once after a timeout, the total waiting time
	       for a timeout will be twice the timeout value set.


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


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

       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 polling interval,  in  sec-
	       onds,  the  reachability	 register,  in	octal, and the current
	       estimated delay, offset and dispersion of the peer, all in sec-
	       onds.  The character in the left margin indicates the mode this
	       peer entry is operating in. A + denotes symmetric active,  a  -
	       indicates  symmetric  passive,  a  = means the remote server is
	       being polled in client mode, a ^ indicates that the  server  is
	       broadcasting  to this address, a ~ denotes that the remote peer
	       is sending broadcasts and a * marks the peer the server is cur-
	       rently 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, param-
	       eter). On hostnames no only IP-addresses will be displayed.


       dmpeers A slightly different peer summary list. Identical to the output
	       of  the peers command, except for the character in the leftmost
	       column. Characters only appear beside peers which were included
	       in  the final stage of the clock selection algorithm. A . indi-
	       cates that this peer was cast off in the falseticker detection,
	       while  a + indicates that the peer made it through. A * denotes
	       the peer the server is currently synchronizing with.

       showpeer peer_address [...]
	       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 specification.

       pstats peer_address [...]
	       Show per-peer statistic counters associated with the  specified
	       peer(s).

       clockinfo clock_peer_address [...]
	       Obtain  and print information concerning a peer clock. The val-
	       ues obtained provide information on the setting of  fudge  fac-
	       tors and other clock performance information.

       kerninfo
	       Obtain  and  print kernel phase-lock loop operating parameters.
	       This information is available only if the kernel has been  spe-
	       cially modified for a precision timekeeping function.

       loopinfo [ oneline | multiline ]
	       Print  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 fre-
	       quency error of the local 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  which  have
	       elapsed since the last sample offset was given to the loop fil-
	       ter. The oneline and multiline options specify  the  format  in
	       which  this information is to be printed, with multiline as the
	       default.

       sysinfo Print a variety of system state variables, i.e., state  related
	       to  the	local  server.	All  except  the  last	four lines are
	       described in the NTP Version 3  specification,  RFC-1305.   The
	       system  flags  show  various system flags, some of which can be
	       set and cleared by the enable and  disable  configuration  com-
	       mands, respectively. These are the auth, bclient, monitor, pll,
	       pps and stats flags. See the ntpd documentation for the meaning
	       of  these  flags. There are two additional flags which are read
	       only, the kernel_pll and kernel_pps. These flags	 indicate  the
	       synchronization status when the precision time kernel modifica-
	       tions are in use. The kernel_pll indicates that the local clock
	       is  being disciplined by the kernel, while the kernel_pps indi-
	       cates the kernel discipline is provided by the PPS signal.

	       The stability is the residual frequency error  remaining	 after
	       the  system frequency correction 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.

	       The authdelay shows the default authentication delay, as set by
	       the authdelay configuration command.


       sysstats
	       Print statistics counters maintained in the protocol module.

       memstats
	       Print statistics counters related to memory allocation code.

       iostats Print  statistics  counters maintained in the input-output mod-
	       ule.

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

       reslist Obtain  and  print  the server's restriction list. This list is
	       (usually) printed in sorted order and may  help	to  understand
	       how the restrictions are applied.

       ifstats List  interface statistics for interfaces used by ntpd for net-
	       work communication.

       ifreload
	       Force rescan of current system  interfaces.  Outputs  interface
	       statistics  for	interfaces  that  could possibly change. Marks
	       unchanged interfaces  with  .,  added  interfaces  with	+  and
	       deleted interfaces with -.

       monlist [ version ]
	       Obtain and print traffic counts collected and maintained by the
	       monitor facility. The version number should not	normally  need
	       to be specified.

       clkbug clock_peer_address [...]
	       Obtain debugging information for a reference clock driver. This
	       information is provided only  by	 some  clock  drivers  and  is
	       mostly undecodable without a copy of the driver source in hand.


RUNTIME CONFIGURATION REQUESTS
       All  requests which cause state changes in the server are authenticated
       by the server using a configured NTP key (the facility can also be dis-
       abled  by  the server by not configuring a key). The key number and the
       corresponding key must also be made known to ntpdc. 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  automatically  for	 both  the key number and password the
       first time a command which would result in an authenticated request  to
       the server is given. Authentication 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 timestamp in the packet data,
       which is included in the computation of the authentication  code.  This
       timestamp  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 con-
       figuration 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  ade-
       quate level of security.

       The following commands all make authenticated requests.


       addpeer peer_address [ keyid ] [ version ] [ minpoll# | prefer | iburst
       | burst | minpoll N | maxpoll N [...]  ]

       addpeer peer_address [ prefer | iburst | burst | minpoll N | maxpoll  N
       | keyidN | version N [...]  ]
	       Add  a  configured  peer	 association  at the given address and
	       operating in symmetric active mode. Note that an existing asso-
	       ciation	with the same peer may be deleted when this command is
	       executed, or may simply be converted to conform to the new con-
	       figuration, as appropriate. If the keyid is nonzero, all outgo-
	       ing packets to the remote server will  have  an	authentication
	       field  attached	encrypted with this key. If the value is 0 (or
	       not given) no authentication will be done. If ntpdc's key  num-
	       ber  has not yet been set (e.g., by the keyid command), it will
	       be set to this value. The version#  can	be  1  through	4  and
	       defaults to 3. The remaining options are either a numeric value
	       for minpoll or literals prefer, iburst, burst, minpoll N, keyid
	       N,  version   N, or maxpoll N (where N is a numeric value), and
	       have the action as specified in	the  peer  configuration  file
	       command of ntpd. See the Server Options page for further infor-
	       mation. Each flag (or its absence) replaces the	previous  set-
	       ting.  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 sig-
	       nal - if the preferred peer is suitable for synchronisation  so
	       is  the PPS signal. The dynamic keyword allows association con-
	       figuration even when no suitable network interface is found  at
	       configuration  time. The dynamic interface update mechanism may
	       complete the configuration when	new  interfaces	 appear	 (e.g.
	       WLAN/PPP	 interfaces) at a later time and thus render the asso-
	       ciation operable.

       addserver peer_address [ keyid ] [ version ]  [	minpoll#  |  prefer  |
       iburst | burst | minpoll N | maxpoll N [...]  ]

       addserver  peer_address [ prefer | iburst | burst | minpoll N | maxpoll
       N | keyidN | version N [...]  ]
	       Identical to the addpeer command,  except  that	the  operating
	       mode is client.

       broadcast peer_address [ keyid ] [ version ] [ prefer ]
	       Identical  to  the  addpeer  command, except that the operating
	       mode is broadcast. In this case a valid non-zero 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.

       unconfig peer_address [...]
	       This command causes the configured bit to be removed  from  the
	       specified peer(s). In many cases this will cause the peer asso-
	       ciation to be deleted. When appropriate, however, the  associa-
	       tion  may persist in an unconfigured mode if the remote peer is
	       willing to continue on in this fashion.

       fudge peer_address [ time1 ] [ time2 ] [ stratum ] [ refid ]
	       This command provides a way to set certain data for a reference
	       clock. See the source listing for further information.

       enable  [  auth	| bclient | calibrate | kernel | monitor | ntp | pps |
       stats]

       disable [ auth | bclient | calibrate | kernel | monitor | ntp |	pps  |
       stats]
	       These  commands	operate in the same way as the enable and dis-
	       able configuration file commands of ntpd. See the Miscellaneous
	       Options page for further information.

       restrict address mask flag [ flag ]
	       This  command operates in the same way as the restrict configu-
	       ration file commands of ntpd.

       unrestrict address mask flag [ flag ]
	       Unrestrict the matching entry from the restrict list.

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

       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  ntpd  configuration  file).  This
	       allows  encryption  keys	 to  be changed without restarting the
	       server.

       trustedkey keyid [...]

       untrustedkey keyid [...]
	       These commands operate in the same way as  the  trustedkey  and
	       untrustedkey configuration file commands of ntpd.

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

       traps   Display the traps set in the server. See the source listing for
	       further information.

       addtrap [ address ] [ port ] [ interface ]
	       Set a trap for asynchronous messages. See  the  source  listing
	       for further information.

       clrtrap [ address ] [ port ] [ interface]
	       Clear  a trap for asynchronous messages. See the source listing
	       for further information.

       reset   Clear the statistics counters in various modules of the server.
	       See the source listing for further information.


BUGS
       ntpdc  is a crude hack. Much of the information it shows is deadly bor-
       ing and could only  be  loved  by  its  implementer.  The  program  was
       designed	 so that new (and temporary) features were easy to hack in, at
       great expense to the program's ease of use. Despite this,  the  program
       is occasionally useful.


SEE ALSO
       ntpd(8)

       The official HTML documentation.

       This file was automatically generated from HTML source.




								      ntpdc(8)