From e7d14426b4411033894e3b46d81db66dfe40ed01 Mon Sep 17 00:00:00 2001 From: Ollivier Robert Date: Thu, 9 Jun 2016 23:06:36 +0200 Subject: [PATCH] Basic manpage. --- ntimed.8 | 182 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 ntimed.8 diff --git a/ntimed.8 b/ntimed.8 new file mode 100644 index 0000000..a0d6b51 --- /dev/null +++ b/ntimed.8 @@ -0,0 +1,182 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd June 08, 2016 +.Dt NTIMED-CLIENT 8 +.Os +.Sh NAME +.Nm ntimed-client +.Nd set the date and time via NTP +.Sh SYNOPSIS +.Nm +.Op Fl p Ar param +.Op Fl t Ar tracefile +.Ar server ... +.Sh DESCRIPTION +The +.Nm +utility sets the local date and time by polling the +Network Time Protocol (NTP) server(s) given as the +.Ar server +arguments to determine the correct time. +It must be run as root on +the local host. +A number of samples are obtained from each of the +servers specified and a subset of the NTP clock filter and +selection algorithms are applied to select the best of these. +Note +that the accuracy and reliability of +.Nm +depends on +the number of servers, the number of polls each time it is run and +the interval between runs. +.Pp +The following options are available: +.Bl -tag -width indent +.It Fl p Ar param +This will display information about the named parameter. +Using '?' will list all possible parameters. +.It Fl p Ar param=value +Sets the +.Ar param +parameter to +.Ar value +.Pp +See below the list of possible parameters. +.sp +Not everything which should be a parameter is yet, and there are some +unused dummy parameters there, just to make sure the macro-magic works. +.It Fl t Ar tracefile +Specify the path for the trace file as the string +.Ar tracefile . +to store debugging information. +.El +.Pp +The +.Nm +utility can be run manually as necessary to set the +host clock, or it can be run from the host startup script to set +the clock at boot time. +.Sh HOW IT WORKS +After a few seconds, your clock will be stepped if necessary. (In the final +version, this is where the process daemonizes into the background -- from +which point you can trust your clock to be good.) +.sp +In the next 30-60 seconds, the PLL will eliminate any residual phase error +and from this point in time, your computer's clock should be good to a few +milliseconds - depending on the quality of the servers. +.sp +After about 5-10 minutes, the PLL will have integrated the frequency error +of your computer's crystal, and the PLL will start to "stiffen" to minimize +the amount of steering necessary to keep the clock aligned to the servers. +.sp +If you are using distant or very distant servers, it will take longer time +before the PLL stiffens. +.Sh PARAMETERS +There are currently two classes of parameters available to modify +.Nm +behaviour: +.Ss FILTER +These parameters affect the client part of +.Nm . +. +.Tp +.Bl -tag -width indent +.It Ic ntp_filter_average +Exponential average divisor for average packet delays. +.Pp +The value chosen is a compromise between gliding through congestion +of common durations and reacting to large-scale routing changes +in a timely manner. +.Pp +In reality there is no way to tell the two apart. +.Pp +Default is 20. +.It Ic ntp_filter_threshold +Packet delays exceeding the average by this factor are untrustworthy. +.Pp +Setting this too high increases noise from (mild) congestion. +Setting it too low throws away adequate timestamps. +.Pp +Default is 3.00. +.El +.Pp +.Ss PLL +These parameters are for the kernel PLL side. +.Bl -tag -width indent +.It Ic pll_std_p_init (float) +Proportional term when PLL starts. +.sp +Reducing this will make the PLL more resistant to measurement +noise and jitter, but also makes it converge slower. +Increasing this will almost certainly cause oscillation. +.sp +Default is 0.33. +.It Ic pll_std_i_init (integer) +Initial P/I ratio when PLL starts. +.sp +Reducing this speed up convergence, but risk overshoot. +Increasing this will slow convergence and reduce impact of +noise. +.sp +Default is 60. +.It Ic pll_std_capture_time (integer) +Capture time before stiffening PLL. +.sp +After this many seconds, the PLL will start to stiffen the +\fBP\fP +and +\fBI\fP +terms to gain noise immunity. +Decreasing risks that initial frequency capture is not +finished, which will increase the offset-excursion. +. +Increasing just delays this stiffening. +.sp +Default is 300. +.It Ic pll_std_stiffen_rate (float) +Rate of PLL P/I term stiffening. +.sp +The exponential stiffening per second of +\fBD\fP +and +\fBI\fP +terms. +.sp +Decreasing makes stiffening faster. Increasing makes stiffening slower. +.sp +Default is 0.999. +.It Ic pll_std_p_limit (float) +Lower limit for Proportional term. +.sp +Reducing this will make the PLL more resistent to noise, +but going too far it will not be able to steer the clock fast enough. +.sp +Increasing this makes the PLL more agile and prone to noise. +.sp +Default is 3e-2. +.El +.Pp +.Sh HISTORY +This work is sponsored by Linux Foundation, partly in response to the +HeartBleed fiasco, and after studying the 300,000+ lines of source-code in +NTPD. I concluded that while it could be salvaged, it would be more +economical, much faster and far more efficient to start from scratch. +.Sh NOTES +You can take this code, compile it, run it, and it will steer your +computer's clock, but I am not going to encourage you to do that in +production yet -- unless you know what you are doing and why you are doing +it: This is only a preview release. +.sp +Because this is a preview release, the process will not "daemonize" into +the background. +.sp +The '-t /tmp/somefile' arguments tells it to write a full blow-by-blow +tracefile, for analysis and debugging. +.sp +If something goes wrong, I'm going to ask you for a copy the tracefile. +.Sh AUTHORS +Poul-Henning Kamp is the author of +.Nm . +.sp +This manpage was written by Ollivier Robert