path: root/usr.sbin/ntp/doc/ntp_mon.8

.\"
.\" $FreeBSD$
.\"
.Dd January 12, 2000
.Dt NTP_MON 8
.Os
.Sh NAME
.Nm ntp_mon
.Nd NTP daemon monitoring options
.Sh SYNOPSIS
.Pa /etc/ntp.conf
.Sh DESCRIPTION
Xr ntpd 8
includes a comprehensive monitoring facility
suitable for continuous, long term recording
of server and client timekeeping performance.
See the
.Ic statistics
command below for a listing
and example of each type of statistics currently supported.
Statistic files are managed using file generation sets
and scripts in the
.Pa ./scripts
directory of the source distribution.
Using these facilities and Unix
.Xr cron 8
jobs,
the data can be automatically summarized and archived
for retrospective analysis.
.Ss Monitoring Commands
The following monitoring commands are available:
.Bl -tag -width indent
.It Xo Ic statistics
.Ar name
.Op ...
.Xc
Enables writing of statistics records.
Currently, four kinds of
.Ar name
statistics are supported.
.Bl -tag -width indent
.It 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:
.Pp
.Dl 50935 75440.031 0.000006019 13.778190 0.000351733 0.013380 6
.Pp
The first two fields show the date (Modified Julian Day)
and time (seconds and fraction past UTC midnight).
The next five fields show time offset (seconds),
frequency offset (parts per million - PPM), RMS jitter (seconds),
Allan deviation (PPM) and clock discipline time constant.
.It peerstats
Enables recording of peer statistics information.
This includes statistics records of all peers of a NTP server
and of special signals, where present and configured.
Each valid update appends a line of the following form to
the current element of a file generation set named peerstats:
.Pp
.Dl 48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142
.Pp
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 RMS jitter,
all in seconds.
.It clockstats
Enables recording of clock driver statistics information.
Each update received from a clock driver appends a line
of the following form to the file generation set named clockstats:
.Pp
.Dl 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
.Pp
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.
.It 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 following form
to the file generation set named rawstats:
.Pp
.Bd -ragged -offset indent
.Li 50928
.Li 2132.543
.Li 128.4.1.1
.\"
.\" XXX The next field is unaccounted for in the descriptive text
.\"	that follows.
.\"
.Li 128.4.1.20
.Li 3102453281.584327000
.Li 3102453281.58622800031
.Li 02453332.540806000
.Li 3102453332.541458000
.Ed
.Pp
The first two fields show the date (Modified Julian Day)
and time (seconds and fraction past UTC midnight).
The next field shows the peer or clock 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.
.El
.It Ic statsdir Ar directory_path
Indicates the full path of a directory
where statistics files should be created (see below).
This keyword allows the
(otherwise constant) filegen filename prefix to be modified
for file generation sets,
which is useful for handling statistics logs.
.It Xo Ic filegen
.Ar name
.Op file Ar filename
.Op type Ar typename
.Op link | nolink
.Op enable | disable
.Xc
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 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 administrative operations
without the risk of disturbing the operation of
.Xr ntpd 8 .
Most importantly,
they can be removed to free space for new data produced.
.Pp
Note that this command can be sent from the
.Xr ntpdc 8
program running at a remote location.
.Bl -tag -width indent
.It name
This is the type of the statistics records,
as shown in the
.Ic statistics
command.
.It file Ar filename
This is the file name for the statistics records.
Filenames of set members are built from three elements:
.Bl -tag -width indent
.It prefix
This is a constant filename path.
It is not subject to modifications via the
.Ic filegen
option.
It is defined by the server,
usually specified as a compile-time constant.
It may, however, be configurable for individual file generation sets
via other commands.
For example, the prefix used with loopstats and peerstats generation
can be configured using the
.Ic statsdir
option explained above.
.Ar filename
This string is directly concatenated to the prefix mentioned above
(no intervening
.Qq /
(slash)) .
This can be modified using the
.Ar filename
argument to the
.Ic filegen
statement.
No
.Qq ..
elements are allowed in this component
to prevent filenames referring to parts
outside the filesystem hierarchy denoted by prefix.
.Ic suffix
This part is reflects individual elements of a file set.
It is generated according to the type of a file set.
.El
.It type Ar typename
A file generation set is characterized by its type.
The following types are supported:
.Bl -tag -width indent
.It none
The file set is actually a single plain file.
.It pid
One element of file set is used per incarnation of a
.Xr ntpd 8
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
.Xr ntpd 8
server incarnations.
The set member filename is built by appending a
.Qq \&.
(dot) to concatenated prefix and
.Ar filename
strings,
and appending the decimal representation
of the process ID of the
.Xr ntpd 8
server process.
.It day
One file generation set element is created per day.
A day is defined as the period between 00:00 and 24:00 UTC.
The file set member suffix consists of a
.Qq \&.
(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 10 December 1992
would end up in a file named
.Pa <prefix><filename>.19921210 .
.It week
Any file set member contains data
related to a certain week of a year.
The term week is defined by computing the day of the year modulo 7.
Elements of such a file generation set are distinguished
by appending the following suffix to the file set
.Ar filename
base:
A dot, a 4-digit year number, the letter W,
and a 2-digit week number.
For example, information from January, 10th 1992
would end up in a file with suffix .1992W1.
.It month
One generation file set element is generated per month.
The file name suffix consists of a dot, a 4-digit year number,
and a 2-digit month.
.It year
One generation file element is generated per year.
The filename suffix consists of a dot and a 4 digit year number.
.It 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 8-digit number.
This number is taken to be the number of seconds
the server has been running
at the start of the corresponding 24-hour period.
Information is only written to a file generation
by specifying enable; output is prevented by specifying disable.
.It 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.
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
.Xr ntpd
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.
.It enable | disable
Enables or disables the recording function.
.El
.El
.Sh SEE ALSO
.Xr ntp_conf 8 ,
.Xr ntpd 8 ,
.Xr ntpdc 8 ,
.Xr ntpq 8
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 3)
.%O RFC1305
.Re
.Sh HISTORY
Written by
.An Dennis Ferguson
at the University of Toronto.
Text amended by
.An David Mills
at the University of Delaware.