diff options
Diffstat (limited to 'usr.sbin/ntp/doc/ntp_mon.8')
| -rw-r--r-- | usr.sbin/ntp/doc/ntp_mon.8 | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/usr.sbin/ntp/doc/ntp_mon.8 b/usr.sbin/ntp/doc/ntp_mon.8 new file mode 100644 index 0000000..c7b36a7 --- /dev/null +++ b/usr.sbin/ntp/doc/ntp_mon.8 @@ -0,0 +1,298 @@ +.\" +.\" $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. |
