[ntpsec commit] Merge docs/ntpdsim_new.txt into docs/ntpdsim.txt.

Eric S. Raymond esr at ntpsec.org
Tue Oct 13 10:41:16 UTC 2015


Module:    ntpsec
Branch:    master
Commit:    b2d4b5accaa6200e2afa35a5f36b6a92f2ffd1e6
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=b2d4b5accaa6200e2afa35a5f36b6a92f2ffd1e6

Author:    Eric S. Raymond <esr at thyrsus.com>
Date:      Tue Oct 13 06:40:25 2015 -0400

Merge docs/ntpdsim_new.txt into docs/ntpdsim.txt.

---

 devel-docs/TODO          |   4 +-
 docs/includes/manual.txt |   2 +-
 docs/ntpdsim.txt         | 209 +++++++++++++++++++++++++++++++----------------
 docs/ntpdsim_new.txt     | 160 ------------------------------------
 4 files changed, 140 insertions(+), 235 deletions(-)

diff --git a/devel-docs/TODO b/devel-docs/TODO
index 42ec609..92ac20e 100644
--- a/devel-docs/TODO
+++ b/devel-docs/TODO
@@ -57,6 +57,8 @@ None right now. (Sep-22 2015)
 * We need a build time option to disable all dangerous operations
   that ntpq can produce.
 
+* systime.c needs patching to put ntpdsim's hook back in place.
+
 * Fixup copyright notices.
   See Mark's message of Oct-13th.
   Subject: FLOSS license policy and copyright marking policy
@@ -111,8 +113,6 @@ is not yet tested anywhere but in ntpd itself.
 
 * Run everything through a spell checker.
 
-* docs/ntpdsim.txt and docs/ntpdsim_new.txt need to be merged.
-
 * These manpages have no corresponding material inside docs/.  Is that OK?
 
   ntpd/ntp.keys.txt
diff --git a/docs/includes/manual.txt b/docs/includes/manual.txt
index ab1e008..a4b9e53 100644
--- a/docs/includes/manual.txt
+++ b/docs/includes/manual.txt
@@ -6,6 +6,6 @@
 * link:ntptickadj.html[`{ntptickadj}` - set time-related kernel variables]
 * link:ntptime.html[`{ntptime}` - read and set kernel time variables]
 * link:keygen.html[`{ntpkeygen}` - generate public and private keys]
-* link:ntpdsim_new.html[`ntpdsim` - Network Time Protocol (NTP) simulator]
+* link:ntpdsim.html[`ntpdsim` - Network Time Protocol (NTP) simulator]
 * link:sitemap.html[Site Map]
 
diff --git a/docs/ntpdsim.txt b/docs/ntpdsim.txt
index c901243..4c8479d 100644
--- a/docs/ntpdsim.txt
+++ b/docs/ntpdsim.txt
@@ -1,4 +1,4 @@
-= `ntpdsim` - Network Time Protocol (NTP) simulator =
+= `ntpdsim` - Network Time Protocol (NTP) Simulator =
 
 [cols="10%,90%",frame="none",grid="none",style="verse"]
 |==============================
@@ -9,38 +9,70 @@ All in a row.
 
 |==============================
 
+
 == Related Links ==
 
 include::includes/manual.txt[]
 
 == Table of Contents ==
 
-* link:#synop[Synopsis]
-* link:#descr[Description]
-* link:#cmd[Command Line Oprionts]
-* link:#files[Files]
+* link:#caveat[Caveat Emptor]
+* link:#description[Description]
+* link:#configuration[Configuration]
+* link:#sample[Sample Configuration File]
 
 '''''
 
-[[synop]]
-== Synopsis ==
+[[caveat]]
+== Caveat Emptor ==
+
+At present, if you attempt to build `ntpsdsim` it probably won't, and
+if built it would probably fail.  Its code has been dusty and
+neglected for a long time.  This documentation is retained mainly as a
+matter of historical interest.
 
-`ntpdsim` [ `-B` 'bdly' ] [ `-C` 'snse' ] [ `-O` 'clk_time' ] [ `-S` 'sim_time' ] [ `-T` 'ferr' ] [ `-W` 'fsne' ] [ `-Y` 'ndly' ] [ `-X` 'pdly' ]
+The {project-shortname} maintainers have an internal project
+code-named TESTFRAME that intends to create the capability 
+for replicable end-to-end testing of `{ntpd}`.  It is likely
+that some version of this code will replace or merge in ntpdsim's
+capabilities.
 
-[[descr]]
+[[description]]
 == Description ==
 
-The `ntpdsim` program is an adaptation of the `{ntpd}` operating system
-daemon. The program operates as a discrete time simulator using
-specified systematic and random driving sources. It includes all the
-mitigation and discipline algorithms of the actual daemon, but with the
-packet I/O and system clock algorithms driven by simulation. Most
-functions of the real `{ntpd}` remain intact, including the monitoring,
-statistics recording, trace and host name resolution features. Further
+The ntpdsim program is used to simulate and study the behavior of an NTP
+daemon that derives its time from a number of different simulated time
+sources (servers). Each simulated server can be configured to have a
+different time offset, frequency offset, propagation delay, processing
+delay, network jitter and oscillator wander.
+
+The program operates as a discrete time simulator using specified
+systematic and random driving sources. Most functions of the real
+`{ntpd}` remain intact, including the monitoring, statistics
+recording, trace and host name resolution features. Further
 information on the simulator is on the
 http://www.eecis.udel.edu/%7emills/ntpsim.html[NTP Discrete Event
 Simulator] page.
 
+The ntpdsim program runs all the same selection, mitigation, and
+discipline algorithms as the actual ntpd daemon at the client. (It
+actually uses the same code). However, the input/output routines and
+servers are simulated. That is, instead of sending the client messages
+over the network to the actual servers, the client messages are
+intercepted by the ntpdsim program, which then generates the replies to
+those messages. The reply messages are carefully "inserted" into the
+input queue of the client at the right time according to the specified
+server properties (like propagation delay).
+
+Each simulated server runs according to a specified script that
+describes the server properties at a particular time. Each script
+consists of a series of consecutive acts. Each act runs for a particular
+duration and specifies the frequency offset, propagation delay,
+processing delay, network jitter and oscillator wander of the server for
+that duration. Once the duration of an act expires, the simulated server
+reconfigures itself according to the properties specified in the next
+act.
+
 The simulator is most useful to study NTP behavior in response to time
 and/or frequency transients under specific conditions of network jitter
 and oscillator wander. For this purpose the daemon can be driven by
@@ -49,63 +81,96 @@ networks and oscillators. The jitter generator produces samples from a
 Poisson distribution, while the wander generator produces samples from a
 Guassian distribution.
 
-The easiest way to use this program is to create a `ntpstats` directory,
-configuration file `{ntpconf}` and frequency file `ntp.drift` and test
-shell `test.sh` in the base directory. The `ntp.drift` file and
-`ntpstats` directory can be empty to start. The `test.sh` script can
-contain something like
-
--------------------------------------------------
-rm ./ntpstats/*
-ntpdsim -O 0.1 -C .001 -T 400 -W 1 -c ./{ntpconf},
--------------------------------------------------
-
-which starts the simulator with a time offset 100 ms, network jitter 1
-ms, frequency offset 400 PPM and oscillator wander 1 PPM/s. These
-parameters represent typical conditions with modern workstations on a
-Ethernet LAN. The {ntpconf} file should contain something like
-
----------------------------------
-disable kernel
-server pogo
-driftfile ./ntp.drift
-statsdir ./ntpstats/
-filegen loopstats type day enable
-filegen peerstats type day enable
----------------------------------
-
-[[cmd]]
-== Command Line Options ==
-
-Note: The NTP development team is moving to the use of a syntax-directed
-configuration file design. When complete these options will be replaced
-by a link:ntpdsim_new.html[new one]. Most of the `{ntpd}` command line
-options apply also to `ntpdsim`. In addition, the following command line
-
-`-B` 'bdly'::
-  Specify beep delay (3600) s.
-`-C` 'snse'::
-  Specify network jitter parameter (0) s.
-`-O` 'clk_time'::
-  Specify initial time offset (0) s.
-`-S` 'sim_time'::
-  Specify simulation duration (86400) s.
-`-T` 'ferr'::
-  Specify initial frequency offset (0) PPM.
-`-W` 'fnse'::
-  Specify oscillator wander parameter (0) PPM/s.
-`-Y` 'ndly'::
-  Specify network propagation delay (.001) s.
-`-Z` 'pdly'::
-  Specify server processing delay (.001) s.
-
-[[files]]
-== Files ==
-//NAMECHANGE
-`/etc/ntp.conf` - the default name of the configuration file +
-`/etc/ntp.drift` - the default name of the drift file +
-`/etc/ntp.keys` - the default name of the key file
+[[configuration]]
+== Configuration ==
+
+The ntpdsim program is configured by providing a configuration file at
+startup. The crux of the simulator configuration is specified using a
+`simulate` command, the syntax of which is given below. Note that all
+time quantities are in seconds and all frequency quantities are in parts
+per million (PPM):
+
+'<simulate_command>' ::= `simulate` { '<init_statement_list> <server_list>' } +
+'<init_statement_list>' ::= <init_statement_list> <init_statement> ; | <init_statement> ; +
+'<init_statement>' ::= `beep_delay` = <number> | `simulation_duration` = <number> + 
+'<server_list>' ::= '<server_list>' <server> | <server> +
+'<server_list>' ::= `server` = <address> { `server_offset` = <number> ; <act_list> } +
+'<act_list>' ::= '<act_list> <act>' | '<act>' +
+'<act>' ::= `duration` = <number> { '<act_stmt_list>' } +
+'<act_stmt_list>' ::= '<act_stmt_list> <act_stmt>' ; | '<act_stmt>' ; +
+'<act_stmt>' ::= `freq_offset` = <number> | `wander` = <number> | `jitter` = <number> | `prop_delay` = <number> | `proc_delay` = <number> +
+
+In addition to the `simulate` command, other standard NTP configuration
+commands can be specified. These commands have the same meaning as in
+the ntpd configuration. Note that newlines are *not* significant within
+the `simulate` command even though they are used to mark the end of a
+normal NTP configuration command. While a newline is an "end of command"
+terminator for other configuration commands, in the `simulate` stanza
+`;` (the semicolon) is the "end of command" terminator.
+
+[[sample]]
+== Sample Configuration File ==
+
+A sample ntpdsim configuration file is given below. It specifies two
+simulated servers, each of which has two acts.
+
+-------------------------------------
+    # Client configuration 
+    disable kernel
+    server pogo
+    driftfile ./ntp.drift
+    statsdir ./ntpstats/
+    filegen loopstats type day enable
+    filegen peerstats type day enable
+
+    # Simulation configuration
+    simulate {
+        simulation_duration = 86400;
+        beep_delay = 3600;
+
+        # Server 1
+        server = louie.udel.edu {
+            server_offset = 0;
+            duration = 50000 {
+                freq_offset = 400;
+                wander = 1.0;
+                jitter = 0.001;
+                prop_delay = 0.001;
+                proc_delay = 0.001;
+            }
+            duration = 6400 {
+                freq_offset = 200;
+                wander = 1.0;
+                jitter = 0.001;
+                prop_delay = 0.001;
+                proc_delay = 0.001;
+            }
+        }
+
+        # Server 2
+        server = baldwin.udel.edu {
+            server_offset = 0.02;
+            duration = 10000 {
+                freq_offset = 400;
+                wander = 1.0;
+                jitter = 0.001;
+                prop_delay = 0.5;
+                proc_delay = 0.001;
+            }
+            duration = 60000 {
+                freq_offset = 200;
+                wander = 1.0;
+                jitter = 0.05;
+                prop_delay = 0.005;
+                proc_delay = 0.001;
+            }
+        }
+ }
+  
+-------------------------------------
 
 '''''
 
+mailto:skamboj at udel.edu['Sachin Kamboj']
+
 include::includes/footer.txt[]
diff --git a/docs/ntpdsim_new.txt b/docs/ntpdsim_new.txt
deleted file mode 100644
index b729885..0000000
--- a/docs/ntpdsim_new.txt
+++ /dev/null
@@ -1,160 +0,0 @@
-= `ntpdsim` - Network Time Protocol (NTP) Simulator =
-
-[cols="10%,90%",frame="none",grid="none",style="verse"]
-|==============================
-|image:pic/oz2.gif[]|
-http://www.eecis.udel.edu/%7emills/pictures.html[from 'The Wizard of Oz', L. Frank Baum]
-
-All in a row.
-
-|==============================
-
-
-== Related Links ==
-
-include::includes/manual.txt[]
-
-== Table of Contents ==
-
-* link:#caveat[Caveat Emptor]
-* link:#description[Description]
-* link:#configuration[Configuration]
-* link:#sample[Sample Configuration File]
-
-'''''
-
-[[caveat]]
-== Caveat Emptor ==
-
-At present, if you attempt to build `ntpsdsim` it probably won't, and
-if built it would probably fail.  Its code has been dusty and
-neglected for a long time.  This documentation is retained mainly as a
-matter of historical interest.
-
-The {project-shortname} maintainers have an internal project
-code-named TESTFRAME that intends to create the capability 
-for replicable end-to-end testing of `{ntpd}`.  It is likely
-that some version of thius code will replace or merge in ntpdsim's
-capabilities.
-
-[[description]]
-== Description ==
-
-The ntpdsim program is used to simulate and study the behavior of an NTP
-daemon that derives its time from a number of different simulated time
-sources (servers). Each simulated server can be configured to have a
-different time offset, frequency offset, propagation delay, processing
-delay, network jitter and oscillator wander.
-
-The ntpdsim program runs all the same selection, mitigation, and
-discipline algorithms as the actual ntpd daemon at the client. (It
-actually uses the same code). However, the input/output routines and
-servers are simulated. That is, instead of sending the client messages
-over the network to the actual servers, the client messages are
-intercepted by the ntpdsim program, which then generates the replies to
-those messages. The reply messages are carefully "inserted" into the
-input queue of the client at the right time according to the specified
-server properties (like propagation delay).
-
-Each simulated server runs according to a specified script that
-describes the server properties at a particular time. Each script
-consists of a series of consecutive acts. Each act runs for a particular
-duration and specifies the frequency offset, propagation delay,
-processing delay, network jitter and oscillator wander of the server for
-that duration. Once the duration of an act expires, the simulated server
-reconfigures itself according to the properties specified in the next
-act.
-
-[[configuration]]
-== Configuration ==
-
-The ntpdsim program is configured by providing a configuration file at
-startup. The crux of the simulator configuration is specified using a
-`simulate` command, the syntax of which is given below. Note that all
-time quantities are in seconds and all frequency quantities are in parts
-per million (PPM):
-
-'<simulate_command>' ::= `simulate` { '<init_statement_list> <server_list>' } +
-'<init_statement_list>' ::= <init_statement_list> <init_statement> ; | <init_statement> ; +
-'<init_statement>' ::= `beep_delay` = <number> | `simulation_duration` = <number> + 
-'<server_list>' ::= '<server_list>' <server> | <server> +
-'<server_list>' ::= `server` = <address> { `server_offset` = <number> ; <act_list> } +
-'<act_list>' ::= '<act_list> <act>' | '<act>' +
-'<act>' ::= `duration` = <number> { '<act_stmt_list>' } +
-'<act_stmt_list>' ::= '<act_stmt_list> <act_stmt>' ; | '<act_stmt>' ; +
-'<act_stmt>' ::= `freq_offset` = <number> | `wander` = <number> | `jitter` = <number> | `prop_delay` = <number> | `proc_delay` = <number> +
-
-In addition to the `simulate` command, other standard NTP configuration
-commands can be specified. These commands have the same meaning as in
-the ntpd configuration. Note that newlines are *not* significant within
-the `simulate` command even though they are used to mark the end of a
-normal NTP configuration command. While a newline is an "end of command"
-terminator for other configuration commands, in the `simulate` stanza
-`;` (the semicolon) is the "end of command" terminator.
-
-[[sample]]
-== Sample Configuration File ==
-
-A sample ntpdsim configuration file is given below. It specifies two
-simulated servers, each of which has two acts.
-
--------------------------------------
-    # Client configuration 
-    disable kernel
-    server pogo
-    driftfile ./ntp.drift
-    statsdir ./ntpstats/
-    filegen loopstats type day enable
-    filegen peerstats type day enable
-
-    # Simulation configuration
-    simulate {
-        simulation_duration = 86400;
-        beep_delay = 3600;
-
-        # Server 1
-        server = louie.udel.edu {
-            server_offset = 0;
-            duration = 50000 {
-                freq_offset = 400;
-                wander = 1.0;
-                jitter = 0.001;
-                prop_delay = 0.001;
-                proc_delay = 0.001;
-            }
-            duration = 6400 {
-                freq_offset = 200;
-                wander = 1.0;
-                jitter = 0.001;
-                prop_delay = 0.001;
-                proc_delay = 0.001;
-            }
-        }
-
-        # Server 2
-        server = baldwin.udel.edu {
-            server_offset = 0.02;
-            duration = 10000 {
-                freq_offset = 400;
-                wander = 1.0;
-                jitter = 0.001;
-                prop_delay = 0.5;
-                proc_delay = 0.001;
-            }
-            duration = 60000 {
-                freq_offset = 200;
-                wander = 1.0;
-                jitter = 0.05;
-                prop_delay = 0.005;
-                proc_delay = 0.001;
-            }
-        }
- }
-  
--------------------------------------
-
-'''''
-
-mailto:skamboj at udel.edu['Sachin Kamboj']
-
-include::includes/footer.txt[]



More information about the vc mailing list