diff --git a/usr.sbin/Makefile b/usr.sbin/Makefile index 55d198a5092d..9259885154ba 100644 --- a/usr.sbin/Makefile +++ b/usr.sbin/Makefile @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.185 2003/05/11 18:19:09 ragge Exp $ +# $NetBSD: Makefile,v 1.186 2003/12/04 18:14:59 drochner Exp $ # from: @(#)Makefile 5.20 (Berkeley) 6/12/93 .include @@ -16,7 +16,8 @@ SUBDIR= ac accton altq amd apm apmd arp bad144 bind bootp catman \ pstat pwd_mkdb powerd quot quotacheck quotaon rarpd rbootd rdate \ repquota rmt rpc.bootparamd rpc.lockd rpc.pcnfsd \ rpc.statd rpcbind rwhod sa screenblank sesd \ - sliplogin slstats spray sunlabel sup sushi syslogd tadpolectl tcpdchk \ + sliplogin slstats sntp \ + spray sunlabel sup sushi syslogd tadpolectl tcpdchk \ tcpdmatch tcpdump timed tpctl traceroute trpt trsp unlink \ usbdevs user videomode vipw vnconfig wiconfig wsconscfg \ wsfontload wsmoused wsmuxctl zdump zic diff --git a/usr.sbin/sntp/Makefile b/usr.sbin/sntp/Makefile new file mode 100644 index 000000000000..561d75444463 --- /dev/null +++ b/usr.sbin/sntp/Makefile @@ -0,0 +1,15 @@ +# $NetBSD: Makefile,v 1.1 2003/12/04 18:14:59 drochner Exp $ + +PROG= sntp +SRCS= internet.c main.c socket.c timing.c unix.c + +.include + +DIST= ${NETBSDSRCDIR}/dist/ntp + +LDADD+= -lm +DPADD+= ${LIBM} + +.PATH: ${DIST}/sntp + +.include diff --git a/usr.sbin/sntp/sntp.1 b/usr.sbin/sntp/sntp.1 new file mode 100644 index 000000000000..418b630c97ab --- /dev/null +++ b/usr.sbin/sntp/sntp.1 @@ -0,0 +1,325 @@ +.TH MSNTP 1 +.SH NAME +msntp \- a SNTP utility (command and daemon) +.SH SYNOPSIS +.B msntp +[ +.B \-h +| +.B \-\-help +| +.B \-? +] [ +.B \-v +| +.B \-V +| +.B \-W +] [ +.B \-B +[ +.I period +] | +.B \-S +| +.B \-q +[ +.BI \-f " savefile" +] | [ { +.B \-r +| +.B \-a +} [ +.BI \-P " prompt" +] [ +.BI \-l " lockfile" +] ] [ +.BI \-e " minerr" +] [ +.BI \-E " maxerr" +] [ +.BI \-c " count" +] [ +.BI \-d " delay" +| +.B \-x +[ +.I separation +] ] [ +.BI \-f " savefile" +] ] [ +.I address(es) +] ] +.SH DESCRIPTION +.PP +.I msntp +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, in a +.I cron +job or as a daemon. It can be run as a daemon to provide a SNTP server for +other clients. 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 msntp +recognizes the following options: +.TP +.B \-h +displays the syntax error message. If there are no other arguments, it then +stops; otherwise it then does what was requested. +.B \-\-help +and +.B \-? +are synonyms. +.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 +.BI \-B " period" +indicates that it should behave as a server, broadcasting time packets at +intervals of +.I period +minutes (sic). Acceptable values of +.I period +are from 1 to 1440 (a day), and the default (i.e. if +.B \-B +is specified but +.I period +is omitted) is 60. Naturally, this will work only if the user has enough +privilege. +.TP +.B \-S +indicates that it should behave as a server, responding to time requests from +clients. Naturally, this will work only if the user has enough privilege. +.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. In daemon mode, +it will add drift information in a format like +.BR "' + 1.3 +/- 0.1 ppm'" , +and display this at roughly +.I separation +intervals (see under the +.B \-x +option for details). +.TP +.BI \-l " lockfile" +sets the name of the lock file to ensure that there is only +one copy of +.I msntp +running at once. The default is installation-dependent, but will usually be +.IR /etc/msntp.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 +.BI \-x " separation" +causes the program to run as a daemon (i.e. forever), and to estimate and +correct for the clock drift. +.I separation +sets the minimum time between calls to the server in minutes if a NTP host is +specified, and between broadcast packets if not. Acceptable values are from 1 +to 1440 (a day), and the default (if +.B \-x +is specified but +.I separation +is omitted) is 300. +.TP +.BI \-f " savefile" +may be used with the +.B \-x +option to store a record of previous packets, which speeds up recalculating +the drift after +.I msntp +has to be restarted (e.g. because of network or server outages). In order to +restart the data, +.I msntp +must be restarted reasonably soon after it died (within a few times the value of +.IR separation ), +with the same value of the +.B \-c +option, the same value of +.IR separation , +in the same mode (i.e. broadcast or client), though the NTP servers need not +be the same for client mode, and with compatible values of other settings. +Note that the file will be created with the default ownerships and permissions, +using standard C facilities. The default is installation-dependent, but will +usually be +.IR /etc/msntp.state . +.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. +.IP +In daemon mode (i.e. when +.B \-x +is specified), +.B minerr +must be less than +.B maxerr +which must be less than +.B separation +(note that this is in minutes, not seconds, but the numeric value is compared). +.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 msntp ntpserver.somewhere +.PP +It can be run as a unprivileged background process to check on the clock drift +as well as the current error; this will probably fail if the local clock is +reset while it is running. For example: +.IP +.B msntp -x ntpserver.somewhere > output 2>\&1 \& +.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 msntp -a ntpserver.somewhere +.PP +It can also be run as a daemon to keep the local clock in step. For example: +.IP +.B msntp -a -x ntpserver.somewhere > output 2>\&1 \& +.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 msntp +was developed by N.M. Maclaren of the University of Cambridge Computing +Service.