/contrib/ntp/sntp/sntp-opts.def
https://bitbucket.org/freebsd/freebsd-head/ · Module-Definition · 327 lines · 307 code · 20 blank · 0 comment · 16 complexity · c3094450dc8dbbaa76005cd5eb8ea0c7 MD5 · raw file
- /* -*- Mode: Text -*- */
- autogen definitions options;
- #include autogen-version.def
- copyright = {
- date = "1970-2006";
- owner = "ntp.org";
- eaddr = "http://bugs.ntp.org, bugs@ntp.org";
- type = note;
- text = `cat COPYRIGHT`;
- };
- prog-name = "sntp";
- prog-title = "standard SNTP program";
- homerc = $HOME, ".";
- long-opts;
- config-header = "config.h";
- #ifndef __windows__
- rcfile = ".ntprc";
- #else
- rcfile = "ntp.ini";
- #endif
- environrc;
- #include version.def
- test-main;
- flag = {
- name = ipv4;
- value = 4;
- equivalence = ipv4;
- descrip = "Force IPv4 DNS name resolution";
- doc = <<- _EndOfDoc_
- Force DNS resolution of following host names on the command line
- to the IPv4 namespace.
- _EndOfDoc_;
- };
- flag = {
- name = ipv6;
- value = 6;
- equivalence = ipv4;
- descrip = "Force IPv6 DNS name resolution";
- doc = <<- _EndOfDoc_
- Force DNS resolution of following host names on the command line
- to the IPv6 namespace.
- _EndOfDoc_;
- };
- flag = {
- name = unprivport;
- value = u;
- descrip = "Use an unprivileged port";
- doc = <<- _EndOfDoc_
- Use an unprivilegded UDP port for our queries.
- _EndOfDoc_;
- };
- flag = {
- name = normalverbose;
- value = v;
- flags-cant = extraverbose, megaverbose;
- descrip = "Slightly verbose";
- doc = <<- _EndOfDoc_
- Diagnostic messages for non-fatal errors and a limited amount of
- tracing should be written to standard error. Fatal ones always
- produce a diagnostic. This option should be set when there is a
- suspected problem with the server, network or the source.
- _EndOfDoc_;
- };
- flag = {
- name = extraverbose;
- value = V;
- flags-cant = normalverbose, megaverbose;
- descrip = "Extra verbose";
- doc = <<- _EndOfDoc_
- Produce more and less comprehensible output, mainly for investigating
- problems with apparently inconsistent timestamps. This option should
- be set when the program fails with a message indicating that is the
- trouble.
- _EndOfDoc_;
- };
- flag = {
- name = megaverbose;
- value = W;
- flags-cant = normalverbose, extraverbose;
- descrip = "Mega verbose";
- doc = <<- _EndOfDoc_
- Very verbose debugging output that will interfere with the timing
- when writing to the terminal (because of line buffered output from C).
- Note that the times produced by this are the corrections needed, and
- not the error in the local clock. This option should be set only when
- debugging the source.
- _EndOfDoc_;
- };
- flag = {
- name = settimeofday;
- value = r;
- flags-cant = adjtime;
- descrip = "Set (step) the time with settimeofday()";
- doc = <<- _EndOfDoc_
- _EndOfDoc_;
- };
- flag = {
- name = adjtime;
- value = a;
- flags-cant = settimeofday;
- descrip = "Set (slew) the time with adjtime()";
- doc = <<- _EndOfDoc_
- _EndOfDoc_;
- };
- detail = <<- _END_DETAIL
- .I sntp
- can be used as a 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 in a
- .I cron
- job.
- NTP is the Network Time Protocol (RFC 1305) and SNTP is the
- Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
- _END_DETAIL;
- prog-man-descrip = <<- _END_PROG_MAN_DESCRIP
- .I sntp
- can be used as a 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 in a
- .I cron
- job.
- NTP is the Network Time Protocol (RFC 1305) and SNTP is the
- Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
- .SS Options
- .PP
- .I sntp
- recognizes the following options:
- .TP
- .B \-v
- indicates that diagnostic messages for non-fatal errors and a limited amount of
- tracing should be written to standard error. Fatal ones always produce a
- diagnostic. This option should be set when there is a suspected problem with
- the server, network or the source.
- .TP
- .B \-V
- requests more and less comprehensible output, mainly for investigating problems
- with apparently inconsistent timestamps. This option should be set when the
- program fails with a message indicating that is the trouble.
- .TP
- .B \-W
- requests very verbose debugging output, and will interfere with the timing
- when writing to the terminal (because of line buffered output from C). Note
- that the times produced by this are the corrections needed, and not the error
- in the local clock. This option should be set only when debugging the source.
- .TP
- .B \-q
- indicates that it should query a daemon save file being maintained by it.
- This needs no privilege and will change neither the save file nor the clock.
- .PP
- The default is that it should behave as a client, and the following options
- are then relevant:
- .TP
- .B \-r
- indicates that the system clock should be reset by
- .IR settimeofday .
- Naturally, this will work only if the user has enough privilege.
- .TP
- .B \-a
- indicates that the system clock should be reset by
- .IR adjtime .
- Naturally, this will work only if the user has enough privilege.
- .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
- .BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" ,
- where the
- .B "'+ 4.567 +/- 0.089 secs'"
- indicates the estimated error in the time on the local system.
- .TP
- .BI \-l " lockfile"
- sets the name of the lock file to ensure that there is only
- one copy of
- .I sntp
- running at once. The default is installation-dependent, but will usually be
- .IR /etc/sntp.pid .
- .TP
- .BI \-e " minerr"
- sets the maximum ignorable variation between the clocks to
- .IR minerr .
- Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is
- is specified and 0.5 otherwise.
- .TP
- .BI \-E " maxerr"
- sets the maximum value of various delays that are deemed acceptable to
- .IR maxerr .
- Acceptable values are from 1 to 60, and the default is 5. It should sometimes
- be increased if there are problems with the network, NTP server or system
- clock, but take care.
- .TP
- .BI \-P " prompt"
- sets the maximum clock change that will be made automatically to
- .IR maxerr .
- Acceptable values are from 1 to 3600 or
- .IR no ,
- and the default is 30. If the program is being run interactively in ordinary
- client mode, and the system clock is to be changed, larger corrections will
- prompt the user for confirmation. Specifying
- .I no
- will disable this and the correction will be made regardless.
- .TP
- .BI \-c " count"
- sets the maximum number of NTP packets required to
- .IR count .
- Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25
- otherwise, and the default is 5. If the maximum isn't enough, the system needs
- a better consistency algorithm than this program uses.
- .TP
- .BI \-d " delay"
- sets a rough limit on the total running time to
- .I delay
- seconds. Acceptable values are from 1 to 3600, and the default is 15 if a NTP
- host is specified and 300 otherwise.
- .TP
- .B -4
- force IPv4 DNS resolution.
- .TP
- .B -6
- force IPv6 DNS resolution.
- .PP
- .B address(es)
- are the DNS names or IP numbers of hosts to use for the challenge and response
- protocol; if no names are given, the program waits for broadcasts. Polling a
- server is vastly more reliable than listening to broadcasts. Note that a
- single component numeric address is not allowed, to avoid ambiguities. If
- more than one name is give, they will be used in a round-robin fashion.
- .PP
- Constraints:
- .IP
- .B minerr
- must be less than
- .B maxerr
- which must be less than
- .B delay
- (or, if a NTP host is not specified
- .BR delay / count "),"
- and
- .B count
- must be less than half of
- .BR delay .
- .IP
- In update mode,
- .B maxerr
- must be less than
- .BR prompt.
- .PP
- Note that none of the above values are closely linked to the limits described
- in the NTP protocol (RFC 1305).
- .SH USAGE
- The simplest use of this program is as an unprivileged command to check the
- current time and error in the local clock. For example:
- .IP
- .B sntp ntpserver.somewhere
- .PP
- With suitable privilege, it can be run as a command or in a
- .I cron
- job to reset the local clock from a reliable server, like the
- .I ntpdate
- and
- .I rdate
- commands. For example:
- .IP
- .B sntp -a ntpserver.somewhere
- .PP
- More information on how to use this utility is given in the
- .I README
- file in the distribution. In particular, this
- .I man
- page does not describe how to set it up as a server, which needs special care
- to avoid propagating misinformation.
- .SH RETURN VALUE
- When used as a client in non-daemon mode, the program returns a zero exit
- status for success, and a non-zero one otherwise. When used as a daemon
- (either client or server), it does not return except after a serious error.
- .SH BUGS
- The program implements the SNTP protocol, and does not provide all NTP
- facilities. In particular, it contains no checks against any form of spoofing.
- If this is a serious concern, some network security mechanism (like a firewall
- or even just
- .IR tcpwrappers )
- should be installed.
- .PP
- There are some errors, ambiguities and inconsistencies in the RFCs, and this
- code may not interwork with all other NTP implementations. Any unreasonable
- restrictions should be reported as bugs to whoever is responsible. It may
- be difficult to find out who that is.
- .PP
- The program will stop as soon as it feels that things have got out of control.
- In client daemon mode, it will usually fail during an extended period of
- network or server inaccessibility or excessively slow performance, or when the
- local clock is reset by another process. It will then need restarting
- manually. Experienced system administrators can write a shell script, a
- .I cron
- job or put it in
- .IR inittab ,
- to do this automatically.
- .PP
- The error cannot be estimated reliably with broadcast packets or for the drift
- in daemon mode (even with client-server packets), and the guess made by the
- program may be wrong (possibly even very wrong). If this is a problem, then
- setting the
- .B \-c
- option to a larger value may help. Or it may not.
- .SH AUTHOR
- .I sntp
- was developed by N.M. Maclaren of the University of Cambridge Computing
- Service.
- _END_PROG_MAN_DESCRIP;