From: Harlan Stenn Date: Thu, 6 Dec 2012 02:14:12 +0000 (+0000) Subject: sntp doc cleanup X-Git-Tag: NTP_4_2_7P332~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=16fb6e29fd9034d2a88690e2e93761ffda59d5d5;p=thirdparty%2Fntp.git sntp doc cleanup bk: 50bfff74rpbnBZCQAnoweVz295X7Dg --- diff --git a/ChangeLog b/ChangeLog index 386b98c23..70a284258 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* sntp documentation cleanup. (4.2.7p331) 2012/12/03 Released by Harlan Stenn * [Bug 2114] Correctly calculate sntp's synch distance. (4.2.7p330) 2012/12/03 Released by Harlan Stenn diff --git a/sntp/invoke-sntp.texi b/sntp/invoke-sntp.texi index 1f6c59d02..09152dbe8 100644 --- a/sntp/invoke-sntp.texi +++ b/sntp/invoke-sntp.texi @@ -6,7 +6,7 @@ # # EDIT THIS FILE WITH CAUTION (invoke-sntp.texi) # -# It has been AutoGen-ed December 3, 2012 at 11:43:13 AM by AutoGen 5.16.2 +# It has been AutoGen-ed December 6, 2012 at 02:11:56 AM by AutoGen 5.16.2 # From the definitions sntp-opts.def # and the template file agtexi-cmd.tpl @end ignore @@ -24,7 +24,7 @@ job. NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) are defined and described by RFC 5905. -.PP + The default is to write the estimated correct local date and time (i.e. not UTC) to the standard output in a format like: @@ -106,7 +106,7 @@ This software is released under the NTP license, . * sntp exit status:: exit status * sntp Usage:: Usage * sntp Authors:: Authors -* sntp Bugs:: Bugs +* sntp Notes:: Notes @end menu @node sntp usage @@ -151,7 +151,7 @@ USAGE: sntp [ - [] | --[@{=| @}] ]... \ -M Num steplimit Adjustments less than steplimit msec will be slewed - It must be in the range: greater than or equal to 0 - -o Num ntpversion Send int as our NTP version + -o Num ntpversion Send int as our NTP protocol version - It must be in the range: 0 to 7 -r no usereservedport Use the NTP Reserved Port (port 123) @@ -221,10 +221,10 @@ to the IPv6 namespace. This is the ``enable authentication with the key @var{auth-keynumber}'' option. This option takes an argument number @file{auth-keynumber}. -This option enables authentication using the key specified in this -option's argument. The argument of this option is the keyid, a -number specified in the keyfile as this key's identifier. See the -keyfile option (@option{-k}) for more details. +Enable authentication using the key specified in this option's +argument. The argument of this option is the @option{keyid}, a +number specified in the @option{keyfile} as this key's identifier. +See the @option{keyfile} option (@option{-k}) for more details. @node sntp broadcast @subsection broadcast option (-b) @cindex sntp-broadcast @@ -259,8 +259,8 @@ may appear an unlimited number of times. Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of -ntpd, and therefore @code{sntp} will send queries to these IPs one -after another, with a 2-second gap in between each query. +@code{ntpd}, and therefore @code{sntp} will send queries to these IPs +one after another, with a 2-second gap in between each query. The @option{-c} or @option{--concurrent} flag says that any IPs returned for the DNS lookup of the supplied host-name are on @@ -291,18 +291,8 @@ This is the ``look in this file for the key specified with @option{-a}'' option. This option takes an argument file @file{file-name}. This option specifies the keyfile. @code{sntp} will search for the key specified with @option{-a} -@file{keyno} in this file. Key files follow the following format: - -@file{keyid keytype key} - -Where @file{keyid} is a number identifying this key -@file{keytype} is one of the following: -@code{S} Key is a 64 Bit hexadecimal number as specified in in the DES specification. -@code{N} Key is a 64 Bit hexadecimal number as specified in the NTP standard. -@code{A} Key is a 1-to-8 character ASCII string. -@code{M} Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. - -For more information see @command{ntp.keys(5)}. +@file{keyno} in this file. See @command{ntp.keys(5)} for more +information. @node sntp logfile @subsection logfile option (-l) @cindex sntp-logfile @@ -324,7 +314,7 @@ correction using @command{settimeofday(2)}. @subsection ntpversion option (-o) @cindex sntp-ntpversion -This is the ``send @var{int} as our ntp version'' option. +This is the ``send @var{int} as our ntp protocol version'' option. This option takes an argument number. When sending requests to a remote server, tell them we are running NTP protocol version @file{ntpversion} . @@ -493,6 +483,7 @@ Stenn" .An "Dave Hart" -@node sntp Bugs -@subsection sntp Bugs -Please report bugs to http://bugs.ntp.org . +@node sntp Notes +@subsection sntp Notes +This document corresponds to version @VERSION@ of +@code{sntp}. diff --git a/sntp/sntp-opts.c b/sntp/sntp-opts.c index 6be20402c..afe54785e 100644 --- a/sntp/sntp-opts.c +++ b/sntp/sntp-opts.c @@ -1,7 +1,7 @@ /* * EDIT THIS FILE WITH CAUTION (sntp-opts.c) * - * It has been AutoGen-ed December 3, 2012 at 11:37:03 AM by AutoGen 5.16.2 + * It has been AutoGen-ed December 6, 2012 at 02:11:18 AM by AutoGen 5.16.2 * From the definitions sntp-opts.def * and the template file options * @@ -72,7 +72,7 @@ extern FILE * option_usage_fp; /* * sntp option static const strings */ -static char const sntp_opt_strs[2491] = +static char const sntp_opt_strs[2500] = /* 0 */ "sntp 4.2.7p331\n" "Copyright (C) 1970-2012 The University of Delaware, all rights reserved.\n" "This is free software. It is licensed for use, modification and\n" @@ -126,46 +126,46 @@ static char const sntp_opt_strs[2491] = /* 1587 */ "Adjustments less than steplimit msec will be slewed\0" /* 1639 */ "STEPLIMIT\0" /* 1649 */ "steplimit\0" -/* 1659 */ "Send int as our NTP version\0" -/* 1687 */ "NTPVERSION\0" -/* 1698 */ "ntpversion\0" -/* 1709 */ "Use the NTP Reserved Port (port 123)\0" -/* 1746 */ "USERESERVEDPORT\0" -/* 1762 */ "usereservedport\0" -/* 1778 */ "OK to 'step' the time with settimeofday(2)\0" -/* 1821 */ "STEP\0" -/* 1826 */ "step\0" -/* 1831 */ "OK to 'slew' the time with adjtime(2)\0" -/* 1869 */ "SLEW\0" -/* 1874 */ "slew\0" -/* 1879 */ "The number of seconds to wait for responses\0" -/* 1923 */ "TIMEOUT\0" -/* 1931 */ "timeout\0" -/* 1939 */ "Wait for pending replies (if not setting the time)\0" -/* 1990 */ "WAIT\0" -/* 1995 */ "no-wait\0" -/* 2003 */ "no\0" -/* 2006 */ "Display extended usage information and exit\0" -/* 2050 */ "help\0" -/* 2055 */ "Extended usage information passed thru pager\0" -/* 2100 */ "more-help\0" -/* 2110 */ "Output version information and exit\0" -/* 2146 */ "version\0" -/* 2154 */ "Save the option state to a config file\0" -/* 2193 */ "save-opts\0" -/* 2203 */ "Load options from a config file\0" -/* 2235 */ "LOAD_OPTS\0" -/* 2245 */ "no-load-opts\0" -/* 2258 */ "SNTP\0" -/* 2263 */ "sntp - standard Simple Network Time Protocol client program - Ver. 4.2.7p331\n" +/* 1659 */ "Send int as our NTP protocol version\0" +/* 1696 */ "NTPVERSION\0" +/* 1707 */ "ntpversion\0" +/* 1718 */ "Use the NTP Reserved Port (port 123)\0" +/* 1755 */ "USERESERVEDPORT\0" +/* 1771 */ "usereservedport\0" +/* 1787 */ "OK to 'step' the time with settimeofday(2)\0" +/* 1830 */ "STEP\0" +/* 1835 */ "step\0" +/* 1840 */ "OK to 'slew' the time with adjtime(2)\0" +/* 1878 */ "SLEW\0" +/* 1883 */ "slew\0" +/* 1888 */ "The number of seconds to wait for responses\0" +/* 1932 */ "TIMEOUT\0" +/* 1940 */ "timeout\0" +/* 1948 */ "Wait for pending replies (if not setting the time)\0" +/* 1999 */ "WAIT\0" +/* 2004 */ "no-wait\0" +/* 2012 */ "no\0" +/* 2015 */ "Display extended usage information and exit\0" +/* 2059 */ "help\0" +/* 2064 */ "Extended usage information passed thru pager\0" +/* 2109 */ "more-help\0" +/* 2119 */ "Output version information and exit\0" +/* 2155 */ "version\0" +/* 2163 */ "Save the option state to a config file\0" +/* 2202 */ "save-opts\0" +/* 2212 */ "Load options from a config file\0" +/* 2244 */ "LOAD_OPTS\0" +/* 2254 */ "no-load-opts\0" +/* 2267 */ "SNTP\0" +/* 2272 */ "sntp - standard Simple Network Time Protocol client program - Ver. 4.2.7p331\n" "USAGE: %s [ - [] | --[{=| }] ]... \\\n" "\t\t[ hostname-or-IP ...]\n\0" -/* 2424 */ "$HOME\0" -/* 2430 */ ".\0" -/* 2432 */ ".ntprc\0" -/* 2439 */ "http://bugs.ntp.org, bugs@ntp.org\0" -/* 2473 */ "\n\n\0" -/* 2476 */ "sntp 4.2.7p331"; +/* 2433 */ "$HOME\0" +/* 2439 */ ".\0" +/* 2441 */ ".ntprc\0" +/* 2448 */ "http://bugs.ntp.org, bugs@ntp.org\0" +/* 2482 */ "\n\n\0" +/* 2485 */ "sntp 4.2.7p331"; /* * ipv4 option description with @@ -284,8 +284,8 @@ static int const aIpv6CantList[] = { * ntpversion option description: */ #define NTPVERSION_DESC (sntp_opt_strs+1659) -#define NTPVERSION_NAME (sntp_opt_strs+1687) -#define NTPVERSION_name (sntp_opt_strs+1698) +#define NTPVERSION_NAME (sntp_opt_strs+1696) +#define NTPVERSION_name (sntp_opt_strs+1707) #define NTPVERSION_DFT_ARG ((char const*)4) #define NTPVERSION_FLAGS (OPTST_DISABLED \ | OPTST_SET_ARGTYPE(OPARG_TYPE_NUMERIC)) @@ -293,33 +293,33 @@ static int const aIpv6CantList[] = { /* * usereservedport option description: */ -#define USERESERVEDPORT_DESC (sntp_opt_strs+1709) -#define USERESERVEDPORT_NAME (sntp_opt_strs+1746) -#define USERESERVEDPORT_name (sntp_opt_strs+1762) +#define USERESERVEDPORT_DESC (sntp_opt_strs+1718) +#define USERESERVEDPORT_NAME (sntp_opt_strs+1755) +#define USERESERVEDPORT_name (sntp_opt_strs+1771) #define USERESERVEDPORT_FLAGS (OPTST_DISABLED) /* * step option description: */ -#define STEP_DESC (sntp_opt_strs+1778) -#define STEP_NAME (sntp_opt_strs+1821) -#define STEP_name (sntp_opt_strs+1826) +#define STEP_DESC (sntp_opt_strs+1787) +#define STEP_NAME (sntp_opt_strs+1830) +#define STEP_name (sntp_opt_strs+1835) #define STEP_FLAGS (OPTST_DISABLED) /* * slew option description: */ -#define SLEW_DESC (sntp_opt_strs+1831) -#define SLEW_NAME (sntp_opt_strs+1869) -#define SLEW_name (sntp_opt_strs+1874) +#define SLEW_DESC (sntp_opt_strs+1840) +#define SLEW_NAME (sntp_opt_strs+1878) +#define SLEW_name (sntp_opt_strs+1883) #define SLEW_FLAGS (OPTST_DISABLED) /* * timeout option description: */ -#define TIMEOUT_DESC (sntp_opt_strs+1879) -#define TIMEOUT_NAME (sntp_opt_strs+1923) -#define TIMEOUT_name (sntp_opt_strs+1931) +#define TIMEOUT_DESC (sntp_opt_strs+1888) +#define TIMEOUT_NAME (sntp_opt_strs+1932) +#define TIMEOUT_name (sntp_opt_strs+1940) #define TIMEOUT_DFT_ARG ((char const*)5) #define TIMEOUT_FLAGS (OPTST_DISABLED \ | OPTST_SET_ARGTYPE(OPARG_TYPE_NUMERIC)) @@ -327,21 +327,21 @@ static int const aIpv6CantList[] = { /* * wait option description: */ -#define WAIT_DESC (sntp_opt_strs+1939) -#define WAIT_NAME (sntp_opt_strs+1990) -#define NOT_WAIT_name (sntp_opt_strs+1995) -#define NOT_WAIT_PFX (sntp_opt_strs+2003) +#define WAIT_DESC (sntp_opt_strs+1948) +#define WAIT_NAME (sntp_opt_strs+1999) +#define NOT_WAIT_name (sntp_opt_strs+2004) +#define NOT_WAIT_PFX (sntp_opt_strs+2012) #define WAIT_name (NOT_WAIT_name + 3) #define WAIT_FLAGS (OPTST_INITENABLED) /* * Help/More_Help/Version option descriptions: */ -#define HELP_DESC (sntp_opt_strs+2006) -#define HELP_name (sntp_opt_strs+2050) +#define HELP_DESC (sntp_opt_strs+2015) +#define HELP_name (sntp_opt_strs+2059) #ifdef HAVE_WORKING_FORK -#define MORE_HELP_DESC (sntp_opt_strs+2055) -#define MORE_HELP_name (sntp_opt_strs+2100) +#define MORE_HELP_DESC (sntp_opt_strs+2064) +#define MORE_HELP_name (sntp_opt_strs+2109) #define MORE_HELP_FLAGS (OPTST_IMM | OPTST_NO_INIT) #else #define MORE_HELP_DESC NULL @@ -354,14 +354,14 @@ static int const aIpv6CantList[] = { # define VER_FLAGS (OPTST_SET_ARGTYPE(OPARG_TYPE_STRING) | \ OPTST_ARG_OPTIONAL | OPTST_IMM | OPTST_NO_INIT) #endif -#define VER_DESC (sntp_opt_strs+2110) -#define VER_name (sntp_opt_strs+2146) -#define SAVE_OPTS_DESC (sntp_opt_strs+2154) -#define SAVE_OPTS_name (sntp_opt_strs+2193) -#define LOAD_OPTS_DESC (sntp_opt_strs+2203) -#define LOAD_OPTS_NAME (sntp_opt_strs+2235) -#define NO_LOAD_OPTS_name (sntp_opt_strs+2245) -#define LOAD_OPTS_pfx (sntp_opt_strs+2003) +#define VER_DESC (sntp_opt_strs+2119) +#define VER_name (sntp_opt_strs+2155) +#define SAVE_OPTS_DESC (sntp_opt_strs+2163) +#define SAVE_OPTS_name (sntp_opt_strs+2202) +#define LOAD_OPTS_DESC (sntp_opt_strs+2212) +#define LOAD_OPTS_NAME (sntp_opt_strs+2244) +#define NO_LOAD_OPTS_name (sntp_opt_strs+2254) +#define LOAD_OPTS_pfx (sntp_opt_strs+2012) #define LOAD_OPTS_name (NO_LOAD_OPTS_name + 3) /* * Declare option callback procedures @@ -695,17 +695,17 @@ static tOptDesc optDesc[OPTION_CT] = { * * Define the sntp Option Environment */ -#define zPROGNAME (sntp_opt_strs+2258) -#define zUsageTitle (sntp_opt_strs+2263) -#define zRcName (sntp_opt_strs+2432) +#define zPROGNAME (sntp_opt_strs+2267) +#define zUsageTitle (sntp_opt_strs+2272) +#define zRcName (sntp_opt_strs+2441) static char const * const apzHomeList[3] = { - sntp_opt_strs+2424, - sntp_opt_strs+2430, + sntp_opt_strs+2433, + sntp_opt_strs+2439, NULL }; -#define zBugsAddr (sntp_opt_strs+2439) -#define zExplain (sntp_opt_strs+2473) +#define zBugsAddr (sntp_opt_strs+2448) +#define zExplain (sntp_opt_strs+2482) #define zDetail (NULL) -#define zFullVersion (sntp_opt_strs+2476) +#define zFullVersion (sntp_opt_strs+2485) /* extracted from optcode.tlib near line 350 */ #if defined(ENABLE_NLS) diff --git a/sntp/sntp-opts.def b/sntp/sntp-opts.def index ac68d372c..105ec43fd 100644 --- a/sntp/sntp-opts.def +++ b/sntp/sntp-opts.def @@ -50,10 +50,10 @@ flag = { arg-type = number; arg-name = "auth-keynumber"; doc = <<- _EndOfDoc_ - This option enables authentication using the key specified in this - option's argument. The argument of this option is the keyid, a - number specified in the keyfile as this key's identifier. See the - keyfile option (@option{-k}) for more details. + Enable authentication using the key specified in this option's + argument. The argument of this option is the @option{keyid}, a + number specified in the @option{keyfile} as this key's identifier. + See the @option{keyfile} option (@option{-k}) for more details. _EndOfDoc_; }; @@ -84,8 +84,8 @@ flag = { Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of - ntpd, and therefore @code{sntp} will send queries to these IPs one - after another, with a 2-second gap in between each query. + @code{ntpd}, and therefore @code{sntp} will send queries to these IPs + one after another, with a 2-second gap in between each query. The @option{-c} or @option{--concurrent} flag says that any IPs returned for the DNS lookup of the supplied host-name are on @@ -132,18 +132,8 @@ flag = { doc = <<- _EndOfDoc_ This option specifies the keyfile. @code{sntp} will search for the key specified with @option{-a} - @file{keyno} in this file. Key files follow the following format: - - @file{keyid keytype key} - - Where @file{keyid} is a number identifying this key - @file{keytype} is one of the following: - @code{S} Key is a 64 Bit hexadecimal number as specified in in the DES specification. - @code{N} Key is a 64 Bit hexadecimal number as specified in the NTP standard. - @code{A} Key is a 1-to-8 character ASCII string. - @code{M} Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. - - For more information see @command{ntp.keys(5)}. + @file{keyno} in this file. See @command{ntp.keys(5)} for more + information. _EndOfDoc_; }; @@ -175,7 +165,7 @@ flag = { flag = { name = ntpversion; value = o; - descrip = "Send @var{int} as our NTP version"; + descrip = "Send @var{int} as our NTP protocol version"; arg-type = number; arg-default = 4; arg-range = "0->7"; @@ -257,7 +247,7 @@ job. NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) are defined and described by RFC 5905. -.PP +.Pp The default is to write the estimated correct local date and time (i.e. not UTC) to the standard output in a format like: @@ -377,9 +367,10 @@ doc-section = { }; doc-section = { - ds-type = 'BUGS'; + ds-type = 'NOTES'; ds-format = 'mdoc'; - ds-text = <<- _END_MDOC_BUGS -Please report bugs to http://bugs.ntp.org . - _END_MDOC_BUGS; + ds-text = <<- _END_MDOC_NOTES +This document corresponds to version @VERSION@ of +.Nm . + _END_MDOC_NOTES; }; diff --git a/sntp/sntp-opts.h b/sntp/sntp-opts.h index 384329302..11e491013 100644 --- a/sntp/sntp-opts.h +++ b/sntp/sntp-opts.h @@ -1,7 +1,7 @@ /* * EDIT THIS FILE WITH CAUTION (sntp-opts.h) * - * It has been AutoGen-ed December 3, 2012 at 11:37:02 AM by AutoGen 5.16.2 + * It has been AutoGen-ed December 6, 2012 at 02:11:18 AM by AutoGen 5.16.2 * From the definitions sntp-opts.def * and the template file options * diff --git a/sntp/sntp.1sntpman b/sntp/sntp.1sntpman index 311180de3..ad1c90a71 100644 --- a/sntp/sntp.1sntpman +++ b/sntp/sntp.1sntpman @@ -1,8 +1,8 @@ -.TH sntp 1sntpman "03 Dec 2012" "4.2.7p331" "User Commands" +.TH sntp 1sntpman "06 Dec 2012" "4.2.7p331" "User Commands" .\" .\" EDIT THIS FILE WITH CAUTION (sntp-opts.man) .\" -.\" It has been AutoGen-ed December 3, 2012 at 11:43:09 AM by AutoGen 5.16.2 +.\" It has been AutoGen-ed December 6, 2012 at 02:11:59 AM by AutoGen 5.16.2 .\" From the definitions sntp-opts.def .\" and the template file agman-cmd.tpl .\" @@ -14,6 +14,46 @@ sntp \- standard Simple Network Time Protocol client program .RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ hostname-or-IP ...] .PP .SH DESCRIPTION +.B +can be used as an SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or from a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.PP +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +.Ic "'+4.567'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +.Ic "'+/- 0.089'" +is the reported +.I synchronization distance +(in seconds), which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +.Ic "'+/- ?'" . +If the +.I host +is different from the +.I IP , +both will be displayed. +Otherwise, only the +.I IP +is displayed. +Finally, the +.I stratum +of the host is reported. .SH "OPTIONS" .TP .BR \-4 ", " -\-ipv4 @@ -36,10 +76,10 @@ to the IPv6 namespace. Enable authentication with the key \fBauth-keynumber\fP. This option takes an integer number as its argument. .sp -This option enables authentication using the key specified in this -option's argument. The argument of this option is the keyid, a -number specified in the keyfile as this key's identifier. See the -keyfile option (\fB-k\fP) for more details. +Enable authentication using the key specified in this option's +argument. The argument of this option is the \fBkeyid\fP, a +number specified in the \fBkeyfile\fP as this key's identifier. +See the \fBkeyfile\fP option (\fB-k\fP) for more details. .TP .BR \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP Listen to the address specified for broadcast time sync. @@ -56,8 +96,8 @@ This option may appear an unlimited number of times. Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of -ntpd, and therefore \fBsntp\fP will send queries to these IPs one -after another, with a 2-second gap in between each query. +\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs +one after another, with a 2-second gap in between each query. The \fB-c\fP or \fB--concurrent\fP flag says that any IPs returned for the DNS lookup of the supplied host-name are on different machines, so we can send concurrent queries. @@ -99,15 +139,8 @@ Look in this file for the key specified with \fB-a\fP. .sp This option specifies the keyfile. \fBsntp\fP will search for the key specified with \fB-a\fP -\fIkeyno\fP in this file. Key files follow the following format: -\fIkeyid keytype key\fP -Where \fIkeyid\fP is a number identifying this key -\fIkeytype\fP is one of the following: -\fBS\fP Key is a 64 Bit hexadecimal number as specified in in the DES specification. -\fBN\fP Key is a 64 Bit hexadecimal number as specified in the NTP standard. -\fBA\fP Key is a 1-to-8 character ASCII string. -\fBM\fP Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. -For more information see \fBntp.keys(5)\fP. +\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more +information. .TP .BR \-l " \fIfile\-name\fP, " \-\-logfile "=" \fIfile\-name\fP Log to specified logfile. @@ -131,7 +164,7 @@ slew the amount using \fBadjtime(2)\fP. Otherwise, step the correction using \fBsettimeofday(2)\fP. .TP .BR \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP -Send \fBint\fP as our NTP version. +Send \fBint\fP as our NTP protocol version. This option takes an integer number as its argument. The value of \fInumber\fP is constrained to being: .in +4 @@ -215,6 +248,25 @@ The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". If any of these are directories, then the file \fI.ntprc\fP is searched for within those directories. .SH USAGE +.TP +.BR Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.TP +.BR Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate 1ntpdatemdoc , +or +.Xr rdate 8 +commands. .SH "ENVIRONMENT" See \fBOPTION PRESETS\fP for configuration environment variables. .SH "FILES" @@ -235,11 +287,17 @@ A specified configuration file could not be loaded. libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you. .SH AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" .SH "COPYRIGHT" Copyright (C) 1970-2012 The University of Delaware all rights reserved. This program is released under the terms of the NTP license, . -.SH BUGS +.SH "BUGS" Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.SH "NOTES" +.SH NOTES +This document corresponds to version @VERSION@ of +.B . +.PP This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP option definitions. diff --git a/sntp/sntp.1sntpmdoc b/sntp/sntp.1sntpmdoc index 827dce81c..af58fbf2e 100644 --- a/sntp/sntp.1sntpmdoc +++ b/sntp/sntp.1sntpmdoc @@ -1,9 +1,9 @@ -.Dd December 3 2012 +.Dd December 6 2012 .Dt SNTP 1sntpmdoc User Commands -.Os SunOS 5.10 +.Os FreeBSD 6.4-STABLE .\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc) .\" -.\" It has been AutoGen-ed December 3, 2012 at 11:43:15 AM by AutoGen 5.16.2 +.\" It has been AutoGen-ed December 6, 2012 at 02:11:47 AM by AutoGen 5.16.2 .\" From the definitions sntp-opts.def .\" and the template file agmdoc-cmd.tpl .Sh NAME @@ -18,6 +18,46 @@ [ hostname-or-IP ...] .Pp .Sh DESCRIPTION +.Nm +can be used as an SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or from a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.Pp +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +.Ic "'+4.567'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +.Ic "'+/- 0.089'" +is the reported +.Em synchronization distance +(in seconds), which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +.Ic "'+/- ?'" . +If the +.Em host +is different from the +.Em IP , +both will be displayed. +Otherwise, only the +.Em IP +is displayed. +Finally, the +.Em stratum +of the host is reported. .Sh "OPTIONS" .Bl -tag .It \-4 ", " -\-ipv4 @@ -38,10 +78,10 @@ to the IPv6 namespace. Enable authentication with the key \fBauth\-keynumber\fP. This option takes an integer number as its argument. .sp -This option enables authentication using the key specified in this -option's argument. The argument of this option is the keyid, a -number specified in the keyfile as this key's identifier. See the -keyfile option (\fB\-k\fP) for more details. +Enable authentication using the key specified in this option's +argument. The argument of this option is the \fBkeyid\fP, a +number specified in the \fBkeyfile\fP as this key's identifier. +See the \fBkeyfile\fP option (\fB\-k\fP) for more details. .It \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP Listen to the address specified for broadcast time sync. This option may appear an unlimited number of times. @@ -56,8 +96,8 @@ This option may appear an unlimited number of times. Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of -ntpd, and therefore \fBsntp\fP will send queries to these IPs one -after another, with a 2\-second gap in between each query. +\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs +one after another, with a 2\-second gap in between each query. .sp The \fB\-c\fP or \fB\-\-concurrent\fP flag says that any IPs returned for the DNS lookup of the supplied host\-name are on @@ -97,18 +137,8 @@ Look in this file for the key specified with \fB\-a\fP. .sp This option specifies the keyfile. \fBsntp\fP will search for the key specified with \fB\-a\fP -\fIkeyno\fP in this file. Key files follow the following format: -.sp -\fIkeyid keytype key\fP -.sp -Where \fIkeyid\fP is a number identifying this key -\fIkeytype\fP is one of the following: -\fBS\fP Key is a 64 Bit hexadecimal number as specified in in the DES specification. -\fBN\fP Key is a 64 Bit hexadecimal number as specified in the NTP standard. -\fBA\fP Key is a 1\-to\-8 character ASCII string. -\fBM\fP Key is a 1\-to\-8 character ASCII string using the MD5 authentication scheme. -.sp -For more information see \fBntp.keys(5)\fP. +\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more +information. .It \-l " \fIfile\-name\fP, " \-\-logfile "=" \fIfile\-name\fP Log to specified logfile. .sp @@ -129,7 +159,7 @@ If the time adjustment is less than \fIsteplimit\fP milliseconds, slew the amount using \fBadjtime(2)\fP. Otherwise, step the correction using \fBsettimeofday(2)\fP. .It \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP -Send \fBint\fP as our NTP version. +Send \fBint\fP as our NTP protocol version. This option takes an integer number as its argument. The value of \fInumber\fP is constrained to being: .in +4 @@ -206,6 +236,25 @@ The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". If any of these are directories, then the file \fI.ntprc\fP is searched for within those directories. .Sh USAGE +.Bl -tag -width indent +.It Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.It Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate 1ntpdatemdoc , +or +.Xr rdate 8 +commands. +.El .Sh "ENVIRONMENT" See \fBOPTION PRESETS\fP for configuration environment variables. .Sh "FILES" @@ -224,11 +273,17 @@ libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you. .El .Sh AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" .Sh "COPYRIGHT" Copyright (C) 1970-2012 The University of Delaware all rights reserved. This program is released under the terms of the NTP license, . -.Sh BUGS +.Sh "BUGS" Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh "NOTES" +.Sh NOTES +This document corresponds to version @VERSION@ of +.Nm . +.Pp This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP option definitions. diff --git a/sntp/sntp.html b/sntp/sntp.html index c42026f2e..aa0dfb06f 100644 --- a/sntp/sntp.html +++ b/sntp/sntp.html @@ -3,7 +3,7 @@ Sntp User's Manual - + @@ -14,18 +14,20 @@ pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } - span.sc { font-variant:small-caps } - span.roman { font-family: serif; font-weight: normal; } + span.sc { font-variant:small-caps } + span.roman { font-family:serif; font-weight:normal; } + span.sansserif { font-family:sans-serif; font-weight:normal; } -->

Sntp User's Manual

+

-Next: , +Next: , Previous: (dir), Up: (dir) -
+

Simple Network Time Protocol User Manual

@@ -55,9 +57,10 @@ IETF specification.
-

-
+

+ +
@@ -76,9 +79,10 @@ the +4.567 +/- 0.089 secs indicates the time offset and error bound of the system clock relative to the server clock.
-

-
+

+ +

Invoking sntp

@@ -96,8 +100,7 @@ job.

NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) are defined and described by RFC 5905. -

.PP -The default is to write the estimated correct local date and time (i.e. not +

The default is to write the estimated correct local date and time (i.e. not UTC) to the standard output in a format like:

.Ic @@ -159,7 +162,7 @@ using the agtexi-cmd template and the option descriptions for the < This software is released under the NTP license, <http://ntp.org/license>.

+

-Next: , +Next: , Up: sntp Invocation -
+
-

sntp help/usage (--help)

+

sntp help/usage (--help)

This is the automatically generated usage text for sntp.

The text printed is the same whether selected with the help option -(--help) or the more-help option (--more-help). more-help will print +(--help) or the more-help option (--more-help). more-help will print the usage text by passing it through a pager program. more-help is disabled on platforms without a working fork(2) function. The PAGER environment variable is -used to select the program, defaulting to more. Both will exit +used to select the program, defaulting to more. Both will exit with a status code of 0. 

sntp - standard Simple Network Time Protocol client program - Ver. 4.2.7p331
@@ -227,7 +231,7 @@ USAGE:  sntp [ -<flag> [<val>] | --<name>[{=| }<val>] ].
    -M Num steplimit      Adjustments less than steplimit msec will be slewed
                                 - It must be in the range:
                                   greater than or equal to 0
-   -o Num ntpversion     Send int as our NTP version
+   -o Num ntpversion     Send int as our NTP protocol version
                                 - It must be in the range:
                                   0 to 7
    -r no  usereservedport Use the NTP Reserved Port (port 123)
@@ -258,11 +262,12 @@ The following option preset mechanisms are supported:
 please send bug reports to:  http://bugs.ntp.org, bugs@ntp.org
+

-Next: , +Next: , Previous: sntp usage, Up: sntp Invocation -
+

ipv4 option (-4)

@@ -279,11 +284,12 @@ ipv6.

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

+

-Next: , +Next: , Previous: sntp ipv4, Up: sntp Invocation -
+

ipv6 option (-6)

@@ -300,35 +306,37 @@ ipv4.

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

+

-Next: , +Next: , Previous: sntp ipv6, Up: sntp Invocation -
+

authentication option (-a)

This is the “enable authentication with the key auth-keynumber” option. -This option takes an argument number auth-keynumber. -This option enables authentication using the key specified in this -option's argument. The argument of this option is the keyid, a -number specified in the keyfile as this key's identifier. See the -keyfile option (-k) for more details. +This option takes an argument number auth-keynumber. +Enable authentication using the key specified in this option's +argument. The argument of this option is the keyid, a +number specified in the keyfile as this key's identifier. +See the keyfile option (-k) for more details.

+

-Next: , +Next: , Previous: sntp authentication, Up: sntp Invocation -
+

broadcast option (-b)

This is the “listen to the address specified for broadcast time sync” option. -This option takes an argument string broadcast-address. +This option takes an argument string broadcast-address.

This option has some usage constraints. It:

    @@ -337,20 +345,21 @@ This option takes an argument string broadcast-address

    If specified sntp will listen to the specified address for NTP broadcasts. The default maximum wait time -can (and probably should) be modified with -t. +can (and probably should) be modified with -t.

    +

    -Next: , +Next: , Previous: sntp broadcast, Up: sntp Invocation -
    +

    concurrent option (-c)

    This is the “concurrently query all ips returned for host-name” option. -This option takes an argument string host-name. +This option takes an argument string host-name.

    This option has some usage constraints. It:

      @@ -360,92 +369,87 @@ This option takes an argument string host-name.

      Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of -ntpd, and therefore sntp will send queries to these IPs one -after another, with a 2-second gap in between each query. +ntpd, and therefore sntp will send queries to these IPs +one after another, with a 2-second gap in between each query. -

      The -c or --concurrent flag says that any IPs +

      The -c or --concurrent flag says that any IPs returned for the DNS lookup of the supplied host-name are on different machines, so we can send concurrent queries.

      +

      -Next: , +Next: , Previous: sntp concurrent, Up: sntp Invocation -
      +

      gap option (-g)

      This is the “the gap (in milliseconds) between time requests” option. -This option takes an argument number milliseconds. +This option takes an argument number milliseconds. Since we're only going to use the first valid response we get and there is benefit to specifying a good number of servers to query, separate the queries we send out by the specified number of milliseconds.

      +

      -Next: , +Next: , Previous: sntp gap, Up: sntp Invocation -
      +

      kod option (-K)

      This is the “kod history filename” option. -This option takes an argument file file-name. +This option takes an argument file file-name. Specifies the filename to be used for the persistent history of KoD responses received from servers.

      +

      -Next: , +Next: , Previous: sntp kod, Up: sntp Invocation -
      +

      keyfile option (-k)

      -This is the “look in this file for the key specified with -a” option. -This option takes an argument file file-name. +This is the “look in this file for the key specified with -a” option. +This option takes an argument file file-name. This option specifies the keyfile. -sntp will search for the key specified with -a -keyno in this file. Key files follow the following format: - -

      keyid keytype key - -

      Where keyid is a number identifying this key -keytype is one of the following: -S Key is a 64 Bit hexadecimal number as specified in in the DES specification. -N Key is a 64 Bit hexadecimal number as specified in the NTP standard. -A Key is a 1-to-8 character ASCII string. -M Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. - -

      For more information see ntp.keys(5). +sntp will search for the key specified with -a +keyno in this file. See ntp.keys(5) for more +information.

      +

      -Next: , +Next: , Previous: sntp keyfile, Up: sntp Invocation -
      +

      logfile option (-l)

      This is the “log to specified logfile” option. -This option takes an argument file file-name. +This option takes an argument file file-name. This option causes the client to write log messages to the specified -logfile. +logfile.

      +

      -Next: , +Next: , Previous: sntp logfile, Up: sntp Invocation -
      +

      steplimit option (-M)

      @@ -453,30 +457,32 @@ Up: sntp Invocation

      This is the “adjustments less than steplimit msec will be slewed” option. This option takes an argument number. -If the time adjustment is less than steplimit milliseconds, -slew the amount using adjtime(2). Otherwise, step the -correction using settimeofday(2). +If the time adjustment is less than steplimit milliseconds, +slew the amount using adjtime(2). Otherwise, step the +correction using settimeofday(2).

      +

      -Next: , +Next: , Previous: sntp steplimit, Up: sntp Invocation -
      +

      ntpversion option (-o)

      -This is the “send int as our ntp version” option. +This is the “send int as our ntp protocol version” option. This option takes an argument number. When sending requests to a remote server, tell them we are running -NTP protocol version ntpversion . +NTP protocol version ntpversion .

      +

      -Next: , +Next: , Previous: sntp ntpversion, Up: sntp Invocation -
      +

      usereservedport option (-r)

      @@ -486,29 +492,31 @@ This is the “use the ntp reserved port (port 123)” option. Use port 123, which is reserved for NTP, for our network communications.
      +

      -Next: , +Next: , Previous: sntp usereservedport, Up: sntp Invocation -
      +

      timeout option (-t)

      This is the “the number of seconds to wait for responses” option. -This option takes an argument number seconds. +This option takes an argument number seconds. When waiting for a reply, sntp will wait the number of seconds specified before giving up. The default should be more than enough for a unicast response. If sntp is only waiting for a broadcast response a longer timeout is likely needed.

      +

      -Next: , +Next: , Previous: sntp timeout, Up: sntp Invocation -
      +

      wait option

      @@ -524,11 +532,12 @@ This is the “wait for pending replies (if not setting the time)” opt

      If we are not setting the time, wait for all pending responses.

      +

      -Next: , +Next: , Previous: sntp wait, Up: sntp Invocation -
      +

      presetting/configuring sntp

      @@ -546,9 +555,9 @@ values are treated like option arguments.
    • $PWD
    The environment variables HOME, and PWD -are expanded and replaced when sntp runs. +are expanded and replaced when sntp runs. For any of these that are plain files, they are simply processed. -For any that are directories, then a file named .ntprc is searched for +For any that are directories, then a file named .ntprc is searched for within that directory and processed.

    Configuration files may be in a wide variety of formats. @@ -590,44 +599,46 @@ detail to provide. The default is to print just the version. The licensing inf first letter of the argument is examined:

    -
    version
    Only print the version. This is the default. -
    copyright
    Name the copyright usage licensing terms. -
    verbose
    Print the full copyright usage licensing terms. +
    ‘version’
    Only print the version. This is the default. +
    ‘copyright’
    Name the copyright usage licensing terms. +
    ‘verbose’
    Print the full copyright usage licensing terms.
    +

    -Next: , +Next: , Previous: sntp config, Up: sntp Invocation -
    +

    sntp exit status

    One of the following exit values will be returned:

    -
    0 (EXIT_SUCCESS)
    Successful program execution. -
    1 (EXIT_FAILURE)
    The operation failed or the command syntax was not valid. -
    66 (EX_NOINPUT)
    A specified configuration file could not be loaded. -
    70 (EX_SOFTWARE)
    libopts had an internal operational error. Please report +
    ‘0 (EXIT_SUCCESS)’
    Successful program execution. +
    ‘1 (EXIT_FAILURE)’
    The operation failed or the command syntax was not valid. +
    ‘66 (EX_NOINPUT)’
    A specified configuration file could not be loaded. +
    ‘70 (EX_SOFTWARE)’
    libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you.
    +

    -Next: , +Next: , Previous: sntp exit status, Up: sntp Invocation -
    +

    sntp Usage

    -
    Li
    is the simplest use of this program +
    ‘Li’
    is the simplest use of this program and can be run as an unprivileged command to check the current time and error in the local clock. -
    Li
    With suitable privilege, +
    ‘Li’
    With suitable privilege, run as a command or from a cron(8) @@ -643,11 +654,12 @@ or commands.
    +

    -Next: , +Next: , Previous: sntp Usage, Up: sntp Invocation -
    +

    sntp Authors

    @@ -663,20 +675,23 @@ Stenn" "Dave Hart"
    +

    -Previous: sntp Authors, +Previous: sntp Authors, Up: sntp Invocation -
    +
    -

    sntp Bugs

    +

    sntp Notes

    -

    Please report bugs to http://bugs.ntp.org . +

    This document corresponds to version of +sntp.

    -

    -
    +

    + +
    @@ -687,13 +702,13 @@ check the current time, offset, and error in the local clock. For example: 
             sntp ntpserver.somewhere
-
    +

    With suitable privilege, it can be run as a command or in a crom job to reset the local clock from a reliable server, like the ntpdate and rdate commands. For example: 

             sntp -a ntpserver.somewhere
-
    + diff --git a/sntp/sntp.man.in b/sntp/sntp.man.in index ef2cab0f4..230534b05 100644 --- a/sntp/sntp.man.in +++ b/sntp/sntp.man.in @@ -1,8 +1,8 @@ -.TH sntp @SNTP_MS@ "03 Dec 2012" "4.2.7p331" "User Commands" +.TH sntp @SNTP_MS@ "06 Dec 2012" "4.2.7p331" "User Commands" .\" .\" EDIT THIS FILE WITH CAUTION (sntp-opts.man) .\" -.\" It has been AutoGen-ed December 3, 2012 at 11:43:09 AM by AutoGen 5.16.2 +.\" It has been AutoGen-ed December 6, 2012 at 02:11:59 AM by AutoGen 5.16.2 .\" From the definitions sntp-opts.def .\" and the template file agman-cmd.tpl .\" @@ -14,6 +14,46 @@ sntp \- standard Simple Network Time Protocol client program .RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \-\-\fIopt\-name\fP " [[=| ]\fIvalue\fP]]..." [ hostname-or-IP ...] .PP .SH DESCRIPTION +.B +can be used as an SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or from a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.PP +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +.Ic "'+4.567'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +.Ic "'+/- 0.089'" +is the reported +.I synchronization distance +(in seconds), which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +.Ic "'+/- ?'" . +If the +.I host +is different from the +.I IP , +both will be displayed. +Otherwise, only the +.I IP +is displayed. +Finally, the +.I stratum +of the host is reported. .SH "OPTIONS" .TP .BR \-4 ", " -\-ipv4 @@ -36,10 +76,10 @@ to the IPv6 namespace. Enable authentication with the key \fBauth-keynumber\fP. This option takes an integer number as its argument. .sp -This option enables authentication using the key specified in this -option's argument. The argument of this option is the keyid, a -number specified in the keyfile as this key's identifier. See the -keyfile option (\fB-k\fP) for more details. +Enable authentication using the key specified in this option's +argument. The argument of this option is the \fBkeyid\fP, a +number specified in the \fBkeyfile\fP as this key's identifier. +See the \fBkeyfile\fP option (\fB-k\fP) for more details. .TP .BR \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP Listen to the address specified for broadcast time sync. @@ -56,8 +96,8 @@ This option may appear an unlimited number of times. Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of -ntpd, and therefore \fBsntp\fP will send queries to these IPs one -after another, with a 2-second gap in between each query. +\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs +one after another, with a 2-second gap in between each query. The \fB-c\fP or \fB--concurrent\fP flag says that any IPs returned for the DNS lookup of the supplied host-name are on different machines, so we can send concurrent queries. @@ -99,15 +139,8 @@ Look in this file for the key specified with \fB-a\fP. .sp This option specifies the keyfile. \fBsntp\fP will search for the key specified with \fB-a\fP -\fIkeyno\fP in this file. Key files follow the following format: -\fIkeyid keytype key\fP -Where \fIkeyid\fP is a number identifying this key -\fIkeytype\fP is one of the following: -\fBS\fP Key is a 64 Bit hexadecimal number as specified in in the DES specification. -\fBN\fP Key is a 64 Bit hexadecimal number as specified in the NTP standard. -\fBA\fP Key is a 1-to-8 character ASCII string. -\fBM\fP Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. -For more information see \fBntp.keys(5)\fP. +\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more +information. .TP .BR \-l " \fIfile\-name\fP, " \-\-logfile "=" \fIfile\-name\fP Log to specified logfile. @@ -131,7 +164,7 @@ slew the amount using \fBadjtime(2)\fP. Otherwise, step the correction using \fBsettimeofday(2)\fP. .TP .BR \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP -Send \fBint\fP as our NTP version. +Send \fBint\fP as our NTP protocol version. This option takes an integer number as its argument. The value of \fInumber\fP is constrained to being: .in +4 @@ -215,6 +248,25 @@ The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". If any of these are directories, then the file \fI.ntprc\fP is searched for within those directories. .SH USAGE +.TP +.BR Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.TP +.BR Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate @NTPDATE_MS@ , +or +.Xr rdate 8 +commands. .SH "ENVIRONMENT" See \fBOPTION PRESETS\fP for configuration environment variables. .SH "FILES" @@ -235,11 +287,17 @@ A specified configuration file could not be loaded. libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you. .SH AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" .SH "COPYRIGHT" Copyright (C) 1970-2012 The University of Delaware all rights reserved. This program is released under the terms of the NTP license, . -.SH BUGS +.SH "BUGS" Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.SH "NOTES" +.SH NOTES +This document corresponds to version @VERSION@ of +.B . +.PP This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP option definitions. diff --git a/sntp/sntp.mdoc.in b/sntp/sntp.mdoc.in index cb082e75c..fd228bca1 100644 --- a/sntp/sntp.mdoc.in +++ b/sntp/sntp.mdoc.in @@ -1,9 +1,9 @@ -.Dd December 3 2012 +.Dd December 6 2012 .Dt SNTP @SNTP_MS@ User Commands -.Os SunOS 5.10 +.Os FreeBSD 6.4-STABLE .\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc) .\" -.\" It has been AutoGen-ed December 3, 2012 at 11:43:15 AM by AutoGen 5.16.2 +.\" It has been AutoGen-ed December 6, 2012 at 02:11:47 AM by AutoGen 5.16.2 .\" From the definitions sntp-opts.def .\" and the template file agmdoc-cmd.tpl .Sh NAME @@ -18,6 +18,46 @@ [ hostname-or-IP ...] .Pp .Sh DESCRIPTION +.Nm +can be used as an SNTP client to query a NTP or SNTP server and either display +the time or set the local system's time (given suitable privilege). It can be +run as an interactive command or from a +.Ic cron +job. +NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) +are defined and described by RFC 5905. +.Pp +The default is to write the estimated correct local date and time (i.e. not +UTC) to the standard output in a format like: +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'" +where the +.Ic "'(+0800)'" +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +.Ic "'+4.567'" +indicates the local clock is 4.567 seconds behind the correct time +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +.Ic "'+/- 0.089'" +is the reported +.Em synchronization distance +(in seconds), which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +.Ic "'+/- ?'" . +If the +.Em host +is different from the +.Em IP , +both will be displayed. +Otherwise, only the +.Em IP +is displayed. +Finally, the +.Em stratum +of the host is reported. .Sh "OPTIONS" .Bl -tag .It \-4 ", " -\-ipv4 @@ -38,10 +78,10 @@ to the IPv6 namespace. Enable authentication with the key \fBauth\-keynumber\fP. This option takes an integer number as its argument. .sp -This option enables authentication using the key specified in this -option's argument. The argument of this option is the keyid, a -number specified in the keyfile as this key's identifier. See the -keyfile option (\fB\-k\fP) for more details. +Enable authentication using the key specified in this option's +argument. The argument of this option is the \fBkeyid\fP, a +number specified in the \fBkeyfile\fP as this key's identifier. +See the \fBkeyfile\fP option (\fB\-k\fP) for more details. .It \-b " \fIbroadcast\-address\fP, " \-\-broadcast "=" \fIbroadcast\-address\fP Listen to the address specified for broadcast time sync. This option may appear an unlimited number of times. @@ -56,8 +96,8 @@ This option may appear an unlimited number of times. Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of -ntpd, and therefore \fBsntp\fP will send queries to these IPs one -after another, with a 2\-second gap in between each query. +\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs +one after another, with a 2\-second gap in between each query. .sp The \fB\-c\fP or \fB\-\-concurrent\fP flag says that any IPs returned for the DNS lookup of the supplied host\-name are on @@ -97,18 +137,8 @@ Look in this file for the key specified with \fB\-a\fP. .sp This option specifies the keyfile. \fBsntp\fP will search for the key specified with \fB\-a\fP -\fIkeyno\fP in this file. Key files follow the following format: -.sp -\fIkeyid keytype key\fP -.sp -Where \fIkeyid\fP is a number identifying this key -\fIkeytype\fP is one of the following: -\fBS\fP Key is a 64 Bit hexadecimal number as specified in in the DES specification. -\fBN\fP Key is a 64 Bit hexadecimal number as specified in the NTP standard. -\fBA\fP Key is a 1\-to\-8 character ASCII string. -\fBM\fP Key is a 1\-to\-8 character ASCII string using the MD5 authentication scheme. -.sp -For more information see \fBntp.keys(5)\fP. +\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more +information. .It \-l " \fIfile\-name\fP, " \-\-logfile "=" \fIfile\-name\fP Log to specified logfile. .sp @@ -129,7 +159,7 @@ If the time adjustment is less than \fIsteplimit\fP milliseconds, slew the amount using \fBadjtime(2)\fP. Otherwise, step the correction using \fBsettimeofday(2)\fP. .It \-o " \fInumber\fP, " \-\-ntpversion "=" \fInumber\fP -Send \fBint\fP as our NTP version. +Send \fBint\fP as our NTP protocol version. This option takes an integer number as its argument. The value of \fInumber\fP is constrained to being: .in +4 @@ -206,6 +236,25 @@ The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". If any of these are directories, then the file \fI.ntprc\fP is searched for within those directories. .Sh USAGE +.Bl -tag -width indent +.It Li "sntp ntpserver.somewhere" +is the simplest use of this program +and can be run as an unprivileged command +to check the current time and error in the local clock. +.It Li "sntp -a ntpserver.somewhere" +With suitable privilege, +run as a command +or from a +.Xr cron 8 +job, +.Ic "sntp -a" +will reset the local clock from a synchronized specified server, +like the (deprecated) +.Xr ntpdate @NTPDATE_MS@ , +or +.Xr rdate 8 +commands. +.El .Sh "ENVIRONMENT" See \fBOPTION PRESETS\fP for configuration environment variables. .Sh "FILES" @@ -224,11 +273,17 @@ libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you. .El .Sh AUTHORS +.An "Johannes Maximilian Kuehn" +.An "Harlan Stenn" +.An "Dave Hart" .Sh "COPYRIGHT" Copyright (C) 1970-2012 The University of Delaware all rights reserved. This program is released under the terms of the NTP license, . -.Sh BUGS +.Sh "BUGS" Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh "NOTES" +.Sh NOTES +This document corresponds to version @VERSION@ of +.Nm . +.Pp This manual page was \fIAutoGen\fP-erated from the \fBsntp\fP option definitions.