[Git][NTPsec/ntpsec][master] ntp_conf.html had nothing to do with ntp.conf!
Gary E. Miller
gitlab at mg.gitlab.com
Wed Jan 11 00:27:09 UTC 2017
Gary E. Miller pushed to branch master at NTPsec / ntpsec
Commits:
5cd114ed by Gary E. Miller at 2017-01-10T16:26:20-08:00
ntp_conf.html had nothing to do with ntp.conf!
I sure I made a mess of this...
- - - - -
4 changed files:
- + docs/includes/ntp-conf-body.txt
- docs/ntp_conf.txt
- + docs/ntp_config.txt
- ntpd/ntp.conf-man.txt
Changes:
=====================================
docs/includes/ntp-conf-body.txt
=====================================
--- /dev/null
+++ b/docs/includes/ntp-conf-body.txt
@@ -0,0 +1,223 @@
+// This is the body of the manual page for ntpd.
+// It's included in two places: once for the docs/ HTML
+// tree, and once to make an individual man page.
+
+[[synop]]
+== SYNOPSIS ==
+/etc/ntp.conf
+
+[[desc]]
+== DESCRIPTION ==
+
+The `ntp.conf` configuration file is read at initial startup by the
+{ntpdman} daemon in order to specify the synchronization
+sources, modes and other related information. Usually, it is installed
+in the `/etc` directory, but could be installed elsewhere (see the
+daemon's `-c` command line option).
+
+The file format is similar to other UNIX configuration files. Comments
+begin with a ‘#’ character and extend to the end of the line; blank
+lines are ignored. Configuration commands consist of an initial keyword
+followed by a list of arguments, some of which may be optional,
+separated by whitespace. Commands may not be continued over multiple
+lines. Arguments may be host names, host addresses written in numeric,
+dotted-quad form, integers, floating point numbers (when specifying
+times in seconds) and text strings.
+
+The rest of this page describes the configuration and control options.
+The "Notes on Configuring NTP and Setting up an NTP Subnet" page
+(available as part of the HTML documentation provided under
+`/usr/share/doc/ntp`) contains an extended discussion of these options.
+In addition to the discussion of general 'Configuration Options',
+there are sections describing the following supported functionality and
+the options used to control it:
+
+* Authentication Support
+* Monitoring Support
+* Access Control Support
+* Automatic NTP Configuration Options
+* Reference Clock Support
+* Miscellaneous Options
+
+Following these is a section describing 'Miscellaneous Options'.
+While there is a rich set of options available, the only required
+option is one or more `pool`, `server`, `peer`, or `broadcast`
+commands.
+
+== Configuration Support ==
+
+Following is a description of the configuration commands in
+NTPv4. There are two classes of commands, association commands that
+configure a persistent association with a remote server or peer or
+reference clock, and auxiliary commands that specify environmental
+variables that control various related operations.
+
+=== Association Commands ===
+
+Only those options applicable to each command are listed below. Use of
+options not listed may not be caught as an error, but may result in
+some weird and even destructive behavior.
+
+In contexts where a host name is expected, a `-4`or `--ipv4`
+qualifier preceding the host name forces DNS resolution to the IPv4
+namespace, while a `-6` or `--ipv6' qualifier forces DNS resolution to
+the IPv6 namespace.
+
+include::../includes/assoc-commands.txt[]
+
+=== Association Options ===
+
+include::../includes/assoc-options.txt[]
+
+=== Association Auxiliary Commands ===
+
+include::../includes/assoc-auxcommands.txt[]
+
+== Authentication Commands ==
+
+include::../includes/auth-commands.txt[]
+
+== Monitoring Support ==
+
+{ntpdman} includes a comprehensive monitoring facility suitable
+for continuous, long term recording of server and client timekeeping
+performance. See the +statistics+ command below for a listing and example of
+each type of statistics currently supported. Statistic files are managed
+using file generation sets and scripts in the ./scripts directory of this
+distribution. Using these facilities and UNIX cron(8) jobs, the data
+can be automatically summarized and archived for retrospective
+analysis.
+
+=== Monitoring Commands ===
+
+include::../includes/mon-commands.txt[]
+
+== Access Control Support ==
+
+The {ntpdman} daemon implements a general purpose address/mask
+based restriction list. The list contains address/match entries sorted
+first by increasing address values and then by increasing mask
+values. A match occurs when the bitwise AND of the mask and the packet
+source address is equal to the bitwise AND of the mask and address in
+the list. The list is searched in order with the last match found
+defining the restriction flags associated with the entry. Additional
+information and examples can be found in the "Notes on Configuring NTP
+and Setting up a NTP Subnet" page (available as part of the HTML
+documentation).
+
+The restriction facility was implemented in conformance with the access
+policies for the original NSFnet backbone time servers. Later the
+facility was expanded to deflect cryptographic and clogging attacks.
+While this facility may be useful for keeping unwanted or broken or
+malicious clients from congesting innocent servers, it should not be
+considered an alternative to the NTP authentication facilities. Source
+address based restrictions are easily circumvented by a determined
+cracker.
+
+Clients can be denied service because they are explicitly included in
+the restrict list created by the restrict command or implicitly as the
+result of cryptographic or rate limit violations. Cryptographic
+violations include certificate or identity verification failure; rate
+limit violations generally result from defective NTP implementations
+that send packets at abusive rates. Some violations cause denied service
+only for the offending packet, others cause denied service for a timed
+period and others cause the denied service for an indefinite period.
+When a client or network is denied access for an indefinite period, the
+only way at present to remove the restrictions is by restarting the
+server.
+
+=== The Kiss-of-Death Packet ===
+
+Ordinarily, packets denied service are simply dropped with no further
+action except incrementing statistics counters. Sometimes a more
+proactive response is needed, such as a server message that explicitly
+requests the client to stop sending and leave a message for the system
+operator. A special packet format has been created for this purpose
+called the "kiss-of-death" (KoD) packet. KoD packets have the leap bits
+set unsynchronized and stratum set to zero and the reference identifier
+field set to a four-byte ASCII code. If the `noserve` or `notrust` flag
+of the matching restrict list entry is set, the code is "DENY"; if the
+`limited` flag is set and the rate limit is exceeded, the code is
+"RATE". Finally, if a cryptographic violation occurs, the code is
+"CRYP".
+
+A client receiving a KoD performs a set of sanity checks to minimize
+security exposure, then updates the stratum and reference identifier
+peer variables, sets the access denied (BOGON4) bit in the peer flash
+variable and sends a message to the log. As long as the BOGON4 bit is
+set, the client will send no further packets to the server. The only way
+at present to recover from this condition is to restart the protocol at
+both the client and server. This happens automatically at the client
+when the association times out. It will happen at the server only if the
+server operator cooperates.
+
+== Access Control Commands ==
+
+include::../includes/access-commands.txt[]
+
+== Automatic NTP Configuration Options ==
+
+=== Manycasting ===
+
+For a detailed description of manycast operation, see the "Server
+Discovery" page (available as part of the HTML documentation).
+
+=== Manycast Options ===
+
+// This is a subset of the tos options applicable to manycast.
+// It omits the more general tinkering options. If you change this,
+// be very sure to keep docs/miscopt.txt synchronized.
+
+`tos` [`ceiling` _ceiling_ | `cohort` \{ `0` | `1` } | `floor` _floor_ | `minclock` _minclock_ | `minsane` _minsane_]::
+ This command affects the clock selection and clustering algorithms. It
+ can be used to select the quality and quantity of peers used to
+ synchronize the system clock and is most useful in manycast mode. The
+ variables operate as follows:
+
+ `ceiling` _ceiling_;;
+ Peers with strata above _ceiling_ will be discarded if there are at
+ least _minclock_ peers remaining. This value defaults to 15, but can
+ be changed to any number from 1 to 15.
+ `cohort` \{0 | 1 };;
+ This is a binary flag which enables (0) or disables (1) manycast
+ server replies to manycast clients with the same stratum level. This
+ is useful to reduce implosions where large numbers of clients with
+ the same stratum level are present. The default is to enable these
+ replies.
+ `floor` _floor_;;
+ Peers with strata below _floor_ will be discarded if there are at
+ least _minclock_ peers remaining. This value defaults to 1, but can
+ be changed to any number from 1 to 15.
+ `minclock` _minclock_;;
+ The clustering algorithm repeatedly casts out outlier associations
+ until no more than _minclock_ associations remain. This value
+ defaults to 3, but can be changed to any number from 1 to the number
+ of configured sources.
+ `minsane` _minsane_;;
+ This is the minimum number of candidates available to the clock
+ selection algorithm in order to produce one or more truechimers for
+ the clustering algorithm. If fewer than this number are available,
+ the clock is undisciplined and allowed to run free. The default is 1
+ for legacy purposes. However, according to principles of Byzantine
+ agreement, _minsane_ should be at least 4 in order to detect and
+ discard a single falseticker.
+`ttl` _hop_ `...`::
+ This command specifies a list of TTL values in increasing order, up to
+ 8 values can be specified. In manycast mode these values are used in
+ turn in an expanding-ring search. The default is eight multiples of 32
+ starting at 31.
+
+== Reference Clock Support ==
+
+For a detailed description of reference-clock configuration, see the
+"Reference Clock Drivers" page (available as part of the HTML
+documentation provided in `/usr/share/doc/ntp`).
+
+== Reference Clock Commands
+
+include::../includes/clock-options.txt[]
+
+== Miscellaneous Options ==
+
+include::../includes/misc-options.txt[]
+
=====================================
docs/ntp_conf.txt
=====================================
--- a/docs/ntp_conf.txt
+++ b/docs/ntp_conf.txt
@@ -11,289 +11,16 @@ Racoon is shooting configuration bugs.
== Table of Contents ==
-* link:#synopsis[Synopsis]
+* link:#synop[Synopsis]
+* link:#descr[Description]
* link:#files[Files]
-* link:#high-level[High-Level Description]
-* link:#detailed[Detailed Description]
-* link:#guidelines[Guidelines for Adding Configuration Commands]
+* link:#bugs[Bugs]
'''''
-[[synopsis]]
-== Synopsis ==
-
-The NTP configuration process is driven by a phrase-structure grammar
-which is used to specify the format of the configuration commands and
-the actions needed to build an abstract syntax tree (AST). The grammar
-is fed to a parser generator (Bison) which produces a parser for the
-configuration file.
-
-The generated parser is used to parse an NTP configuration file and
-check it for syntax and semantic errors. The result of the parse is an
-AST, which contains a representation of the various commands and
-options. This AST is then traversed to set up the NTP daemon to the
-correct configuration.
-
-This document is intended for developers who wish to modify the
-configuration code and/or add configuration commands and options. It
-contains a description of the files used in the configuration process as
-well as guidelines on how to construct them.
-
-[[files]]
-== Files ==
-
-A brief description of the files used by the configuration code is given
-below:
-
-[cols="<40%,<60%",options="header"]
-|==============================================================================
-| File | Description
-| *ntp_config.y* | This file is a Bison source file that contains the phrase-structure grammar and the actions that need to be performed to generate an AST.
-|*ntp_config.c* | This file contains the major chunk of the configuration code. It contains all the functions that are called for building the AST as well as the functions that are needed for traversing the AST.
-| *ntp_config.h* | This file is the header file for *ntp_config.c*. It mainly contains the structure definitions needed to build the AST.
-| *ntp_scanner.c* | This file contains the code for a simple lexical analyzer. This file is directly included into the *ntp_config.c* file since this code is only used by the configuration code. The most important function in this file is +yylex+, which is called by the generated parser to get the next token on the input line.
-| *ntp_config.tab.c* | This file is generated by Bison from the *ntp_config.y* file. This file is also included directly into the configuration code.
-|==============================================================================
-
-[[high-level]]
-== High-Level Description ==
-
-A high-level description of the configuration process showing where all
-the files fit in is given below:
-
-image:pic/description.jpg[JPEG]
-
-The scanner reads in an NTP configuration file and converts it into
-tokens. The Bison generated parser reads these tokens and converts them
-into an AST. The AST traverser consists of a set of functions that
-configure parts of NTP on the basis of what is on the tree. A more
-detailed description of these parts and the files used is given below:
-
-[[detailed]]
-== Detailed Description ==
-
-*ntp_scanner.c*::
- This file contains the scanner. The scanner is a small program that
- converts an input NTP configuration file into a set of *tokens* that
- correspond to *lexemes* in the input. Lexemes are strings in the
- input, delimited by whitespace and/or special characters. Tokens are
- basically unique integers that represent these lexemes. A different
- token is generated for each reserved word and special character in the
- input. There are two main functions in the public interface of this
- file:
-+int yylex+()::
- This function is called +yylex+ for historical reasons; +lex+ is a
- program that takes a set of regular expressions and generates a
- scanner that returns tokens corresponding to those regular
- expressions. The name of the generated function is called +yylex+. We
- aren't using +lex+ because it requires linking against an
- external library and we didn't want to increase the compile-time
- requirements of NTP.
-+
-History lessons aside, this function basically checks to see if the
-next input character is a special character as defined in the array
-+char special_char[]+. (The function +int is_special(char ch)+, can be
-used for this.) If yes, the special character is returned as the
-token. If not, a set of characters is read until the next whitespace
-or special character is encountered. This set of characters forms the
-lexeme; +yylex+ then checks whether this lexeme is an integer, a
-double, an IP address or a reserved word. If yes, the corresponding
-token is returned. If not, a token for a string is returned as the
-default token.
-+
-+struct state *create_keyword_scanner(struct key_tok *keyword_list)+::
- This function takes a list of (_keyword, token_) pairs and converts
- them into a tree that can recognize the keywords (reserved words).
- Every time the scanner reads a lexeme, it compares it against the list
- of reserved words. If it finds a match, it returns the corresponding
- token for that keyword.
-
-*ntp_config.y*::
- This file is structured as a standard Bison file and consists of three
- main parts, separated by +%%+:
-
-1. The prologue and bison declarations: This section contains a list of
-the terminal symbols, the non-terminal symbols and the types of these
-symbols.
-2. The rules section: This section contains a description of the actual
-phrase-structure rules that are used to parse the configuration
-commands. Each rule consists of a left-hand side (LHS), a right-hand
-side (RHS) and an optional action. As is standard with phrase-structure
-grammars, the LHS consists of a single non-terminal symbol. The RHS can
-contain both terminal and non-terminal symbols, while the optional
-action can consist of any arbitrary C code.
-3. The epilogue: This section is left empty on purpose. It is
-traditionally used to code the support functions needed to build the
-ASTs. Since we have moved all the support functions to *ntp_config.c*,
-this section is left empty.
-
-== Prologue and Bison Declarations ==
-
-All the terminal symbols (also known as tokens) have to be declared in
-the prologue section. Note that terminals and non-terminals may have
-values associated with them and these values have types. (More on this
-later). An unnamed union has to be declared with all the possible types
-at the start of the prologue section. For example, we declare the
-following union at the start of the *ntp_config.y* file:
-
------------------------
-%union {
- char *String;
- double Double;
- int Integer;
- void *VoidPtr;
- queue *Queue;
- struct attr_val *Attr_val;
- struct address_node *Address_node;
- struct setvar_node *Set_var;
- /* Simulation types */
- server_info *Sim_server;
- script_info *Sim_script;
-}
------------------------
-
-Some tokens may not have any types. For example, tokens that
-correspond to reserved words do not usually have types as they simply
-indicate that a reserved word has been read in the input file. Such
-tokens have to be declared as follows:
-
------------------------
-%token T_Discard
-%token T_Dispersion
---------------------
-
-Other tokens do have types. For example, a +T_Double+ token is returned
-by the scanner whenever it sees a floating-point double in the
-configuration file. The value associated with the token is the actual
-number that was read in the configuration file and its type (after
-conversion) is double. Hence, the token +T_Double+ will have to be
-declared as follows in the prologue of *ntp_config.y* file:
-
------------------------
-%token <Double> T_Double
------------------------
-
-Note that the declaration given in the angled brackets is not +double+
-but +Double+, which is the name of the variable given in the +%union {}+
-declaration above.
-
-Finally, non-terminal symbols may also have values associated with them,
-which have types. This is because Bison allows non-terminal symbols to
-have actions associated with them. Actions may be thought of as small
-functions which get executed whenever the RHS of a non-terminal is
-detected. The return values of these functions are the values associated
-with the non-terminals. The types of the non-terminals are specified
-with a +%type+ declaration as shown below:
-
------------------------
-%type <Queue> address_list
-%type <Integer> boolean
------------------------
-
-The +%type+ declaration may be omitted for non-terminals that do not
-return any value and do not have type information associated with them.
-
-== The Rules Section ==
-
-The rule section only consists of phrase-structure grammar rules. Each
-rule typically has the following format:
-
------------------------
-LHS : RHS [{ Actions }]
- ;
------------------------
-
-where LHS consists of a single non-terminal symbol and the RHS consists
-of one or more terminal and non-terminal symbols. The +Actions+ are
-optional and may consist of any number of arbitrary C statements. Note
-that Bison can only process LALR(1) grammars, which imposes additional
-restrictions on the kind of rules that can be specified. Examples of
-rules are shown below:
-
------------------------
-orphan_mode_command
- : T_Tos tos_option_list
- { append_queue(my_config.orphan_cmds, $2); }
- ;
-
-tos_option_list
- : tos_option_list tos_option { $$ = enqueue($1, $2); }
- | tos_option { $$ = enqueue_in_new_queue($1); }
- ;
------------------------
-
-The +$n+ notation, where +n+ is an integer, is used to refer to the
-value of a terminal or non-terminal symbol. All terminals and
-non-terminal symbols within a particular rule are numbered (starting
-from 1) according to the order in which they appear within the RHS of a
-rule. +$$+ is used to refer to the value of the LHS terminal symbol - it
-is used to return a value for the non-terminal symbol specified in the
-LHS of the rule.
-
-== Invoking Bison ==
-
-Bison needs to be invoked in order to convert the *ntp_config.y* file
-into a C source file. To invoke Bison, simply enter the command:
-
------------------------
-bison ntp_config.y
------------------------
-
-at the command prompt. If no errors are detected, an *ntp_config.tab.c*
-file will be generated by default. This generated file can be directly
-included into the *ntp_config.c* file.
-
-If Bison report shift-reduce errors or reduce-reduce errors, it means
-that the grammar specified using the rules in not LALR(1). To debug such
-a grammar, invoke Bison with a +-v+ switch, as shown below. This will
-generate a *ntp_config.output* file, which will contain a description of
-the generated state machine, together with a list of states that have
-shift-reduce/reduce-reduce conflicts. You can then change the rules to
-remove such conflicts.
-
------------------------
-bison -v ntp_config.y
------------------------
-
-For more information, refer to the
-http://www.gnu.org/software/bison/manual/[Bison manual].
-
-*ntp_config.c*
-
-This file contains the major chunk of the configuration code including
-all the support functions needed for building and traversing the ASTs.
-As such, most of the functions in this file can be divided into two
-groups:
-
-1. Functions that have a +create_+ prefix. These functions are used to
-build a node of the AST.
-2. Functions that have a +config_+ prefix. These functions are used to
-traverse the AST and configure NTP according to the nodes present on the
-tree.
-
-[[guidelines]]
-== Guidelines for Adding Configuration Commands ==
-
-The following steps may be used to add a new configuration command to
-the NTP reference implementation:
-
-1. Write phrase-structure grammar rules for the syntax of the new
-command. Add these rules to the rules section of the *ntp_config.y*
-file.
-2. Write the action to be performed on recognizing the rules. These
-actions will be used to build the AST.
-3. If new reserved words are needed, add these to the
-+struct key_tok ntp_keywords[]+ structure in the *keyword-gen.c* file.
-This will allow the scanner to recognize these reserved words and
-generate the desired tokens on recognizing them.
-4. Specify the types of all the terminals and non-terminal symbols in
-the prologue section of the *ntp_config.c* file.
-5. Write a function with a +config_+ prefix that will be executed for
-this new command. Make sure this function is called in the
-+config_ntpd()+ function.
+include::includes/ntp-conf-body.txt[]
'''''
-mailto:skamboj at udel.edu[Sachin Kamboj]
-
include::includes/footer.txt[]
+
=====================================
docs/ntp_config.txt
=====================================
--- /dev/null
+++ b/docs/ntp_config.txt
@@ -0,0 +1,299 @@
+= Configuration File Definition (Advanced) =
+
+[cols="10%,90%",frame="none",grid="none",style="verse"]
+|==============================
+|image:pic/pogo7.gif[]|
+{millshome}pictures.html[from 'Pogo', Walt Kelly]
+
+Racoon is shooting configuration bugs.
+
+|==============================
+
+== Table of Contents ==
+
+* link:#synopsis[Synopsis]
+* link:#files[Files]
+* link:#high-level[High-Level Description]
+* link:#detailed[Detailed Description]
+* link:#guidelines[Guidelines for Adding Configuration Commands]
+
+'''''
+
+[[synopsis]]
+== Synopsis ==
+
+The NTP configuration process is driven by a phrase-structure grammar
+which is used to specify the format of the configuration commands and
+the actions needed to build an abstract syntax tree (AST). The grammar
+is fed to a parser generator (Bison) which produces a parser for the
+configuration file.
+
+The generated parser is used to parse an NTP configuration file and
+check it for syntax and semantic errors. The result of the parse is an
+AST, which contains a representation of the various commands and
+options. This AST is then traversed to set up the NTP daemon to the
+correct configuration.
+
+This document is intended for developers who wish to modify the
+configuration code and/or add configuration commands and options. It
+contains a description of the files used in the configuration process as
+well as guidelines on how to construct them.
+
+[[files]]
+== Files ==
+
+A brief description of the files used by the configuration code is given
+below:
+
+[cols="<40%,<60%",options="header"]
+|==============================================================================
+| File | Description
+| *ntp_config.y* | This file is a Bison source file that contains the phrase-structure grammar and the actions that need to be performed to generate an AST.
+|*ntp_config.c* | This file contains the major chunk of the configuration code. It contains all the functions that are called for building the AST as well as the functions that are needed for traversing the AST.
+| *ntp_config.h* | This file is the header file for *ntp_config.c*. It mainly contains the structure definitions needed to build the AST.
+| *ntp_scanner.c* | This file contains the code for a simple lexical analyzer. This file is directly included into the *ntp_config.c* file since this code is only used by the configuration code. The most important function in this file is +yylex+, which is called by the generated parser to get the next token on the input line.
+| *ntp_config.tab.c* | This file is generated by Bison from the *ntp_config.y* file. This file is also included directly into the configuration code.
+|==============================================================================
+
+[[high-level]]
+== High-Level Description ==
+
+A high-level description of the configuration process showing where all
+the files fit in is given below:
+
+image:pic/description.jpg[JPEG]
+
+The scanner reads in an NTP configuration file and converts it into
+tokens. The Bison generated parser reads these tokens and converts them
+into an AST. The AST traverser consists of a set of functions that
+configure parts of NTP on the basis of what is on the tree. A more
+detailed description of these parts and the files used is given below:
+
+[[detailed]]
+== Detailed Description ==
+
+*ntp_scanner.c*::
+ This file contains the scanner. The scanner is a small program that
+ converts an input NTP configuration file into a set of *tokens* that
+ correspond to *lexemes* in the input. Lexemes are strings in the
+ input, delimited by whitespace and/or special characters. Tokens are
+ basically unique integers that represent these lexemes. A different
+ token is generated for each reserved word and special character in the
+ input. There are two main functions in the public interface of this
+ file:
++int yylex+()::
+ This function is called +yylex+ for historical reasons; +lex+ is a
+ program that takes a set of regular expressions and generates a
+ scanner that returns tokens corresponding to those regular
+ expressions. The name of the generated function is called +yylex+. We
+ aren't using +lex+ because it requires linking against an
+ external library and we didn't want to increase the compile-time
+ requirements of NTP.
++
+History lessons aside, this function basically checks to see if the
+next input character is a special character as defined in the array
++char special_char[]+. (The function +int is_special(char ch)+, can be
+used for this.) If yes, the special character is returned as the
+token. If not, a set of characters is read until the next whitespace
+or special character is encountered. This set of characters forms the
+lexeme; +yylex+ then checks whether this lexeme is an integer, a
+double, an IP address or a reserved word. If yes, the corresponding
+token is returned. If not, a token for a string is returned as the
+default token.
++
++struct state *create_keyword_scanner(struct key_tok *keyword_list)+::
+ This function takes a list of (_keyword, token_) pairs and converts
+ them into a tree that can recognize the keywords (reserved words).
+ Every time the scanner reads a lexeme, it compares it against the list
+ of reserved words. If it finds a match, it returns the corresponding
+ token for that keyword.
+
+*ntp_config.y*::
+ This file is structured as a standard Bison file and consists of three
+ main parts, separated by +%%+:
+
+1. The prologue and bison declarations: This section contains a list of
+the terminal symbols, the non-terminal symbols and the types of these
+symbols.
+2. The rules section: This section contains a description of the actual
+phrase-structure rules that are used to parse the configuration
+commands. Each rule consists of a left-hand side (LHS), a right-hand
+side (RHS) and an optional action. As is standard with phrase-structure
+grammars, the LHS consists of a single non-terminal symbol. The RHS can
+contain both terminal and non-terminal symbols, while the optional
+action can consist of any arbitrary C code.
+3. The epilogue: This section is left empty on purpose. It is
+traditionally used to code the support functions needed to build the
+ASTs. Since we have moved all the support functions to *ntp_config.c*,
+this section is left empty.
+
+== Prologue and Bison Declarations ==
+
+All the terminal symbols (also known as tokens) have to be declared in
+the prologue section. Note that terminals and non-terminals may have
+values associated with them and these values have types. (More on this
+later). An unnamed union has to be declared with all the possible types
+at the start of the prologue section. For example, we declare the
+following union at the start of the *ntp_config.y* file:
+
+-----------------------
+%union {
+ char *String;
+ double Double;
+ int Integer;
+ void *VoidPtr;
+ queue *Queue;
+ struct attr_val *Attr_val;
+ struct address_node *Address_node;
+ struct setvar_node *Set_var;
+ /* Simulation types */
+ server_info *Sim_server;
+ script_info *Sim_script;
+}
+-----------------------
+
+Some tokens may not have any types. For example, tokens that
+correspond to reserved words do not usually have types as they simply
+indicate that a reserved word has been read in the input file. Such
+tokens have to be declared as follows:
+
+-----------------------
+%token T_Discard
+%token T_Dispersion
+--------------------
+
+Other tokens do have types. For example, a +T_Double+ token is returned
+by the scanner whenever it sees a floating-point double in the
+configuration file. The value associated with the token is the actual
+number that was read in the configuration file and its type (after
+conversion) is double. Hence, the token +T_Double+ will have to be
+declared as follows in the prologue of *ntp_config.y* file:
+
+-----------------------
+%token <Double> T_Double
+-----------------------
+
+Note that the declaration given in the angled brackets is not +double+
+but +Double+, which is the name of the variable given in the +%union {}+
+declaration above.
+
+Finally, non-terminal symbols may also have values associated with them,
+which have types. This is because Bison allows non-terminal symbols to
+have actions associated with them. Actions may be thought of as small
+functions which get executed whenever the RHS of a non-terminal is
+detected. The return values of these functions are the values associated
+with the non-terminals. The types of the non-terminals are specified
+with a +%type+ declaration as shown below:
+
+-----------------------
+%type <Queue> address_list
+%type <Integer> boolean
+-----------------------
+
+The +%type+ declaration may be omitted for non-terminals that do not
+return any value and do not have type information associated with them.
+
+== The Rules Section ==
+
+The rule section only consists of phrase-structure grammar rules. Each
+rule typically has the following format:
+
+-----------------------
+LHS : RHS [{ Actions }]
+ ;
+-----------------------
+
+where LHS consists of a single non-terminal symbol and the RHS consists
+of one or more terminal and non-terminal symbols. The +Actions+ are
+optional and may consist of any number of arbitrary C statements. Note
+that Bison can only process LALR(1) grammars, which imposes additional
+restrictions on the kind of rules that can be specified. Examples of
+rules are shown below:
+
+-----------------------
+orphan_mode_command
+ : T_Tos tos_option_list
+ { append_queue(my_config.orphan_cmds, $2); }
+ ;
+
+tos_option_list
+ : tos_option_list tos_option { $$ = enqueue($1, $2); }
+ | tos_option { $$ = enqueue_in_new_queue($1); }
+ ;
+-----------------------
+
+The +$n+ notation, where +n+ is an integer, is used to refer to the
+value of a terminal or non-terminal symbol. All terminals and
+non-terminal symbols within a particular rule are numbered (starting
+from 1) according to the order in which they appear within the RHS of a
+rule. +$$+ is used to refer to the value of the LHS terminal symbol - it
+is used to return a value for the non-terminal symbol specified in the
+LHS of the rule.
+
+== Invoking Bison ==
+
+Bison needs to be invoked in order to convert the *ntp_config.y* file
+into a C source file. To invoke Bison, simply enter the command:
+
+-----------------------
+bison ntp_config.y
+-----------------------
+
+at the command prompt. If no errors are detected, an *ntp_config.tab.c*
+file will be generated by default. This generated file can be directly
+included into the *ntp_config.c* file.
+
+If Bison report shift-reduce errors or reduce-reduce errors, it means
+that the grammar specified using the rules in not LALR(1). To debug such
+a grammar, invoke Bison with a +-v+ switch, as shown below. This will
+generate a *ntp_config.output* file, which will contain a description of
+the generated state machine, together with a list of states that have
+shift-reduce/reduce-reduce conflicts. You can then change the rules to
+remove such conflicts.
+
+-----------------------
+bison -v ntp_config.y
+-----------------------
+
+For more information, refer to the
+http://www.gnu.org/software/bison/manual/[Bison manual].
+
+*ntp_config.c*
+
+This file contains the major chunk of the configuration code including
+all the support functions needed for building and traversing the ASTs.
+As such, most of the functions in this file can be divided into two
+groups:
+
+1. Functions that have a +create_+ prefix. These functions are used to
+build a node of the AST.
+2. Functions that have a +config_+ prefix. These functions are used to
+traverse the AST and configure NTP according to the nodes present on the
+tree.
+
+[[guidelines]]
+== Guidelines for Adding Configuration Commands ==
+
+The following steps may be used to add a new configuration command to
+the NTP reference implementation:
+
+1. Write phrase-structure grammar rules for the syntax of the new
+command. Add these rules to the rules section of the *ntp_config.y*
+file.
+2. Write the action to be performed on recognizing the rules. These
+actions will be used to build the AST.
+3. If new reserved words are needed, add these to the
++struct key_tok ntp_keywords[]+ structure in the *keyword-gen.c* file.
+This will allow the scanner to recognize these reserved words and
+generate the desired tokens on recognizing them.
+4. Specify the types of all the terminals and non-terminal symbols in
+the prologue section of the *ntp_config.c* file.
+5. Write a function with a +config_+ prefix that will be executed for
+this new command. Make sure this function is called in the
++config_ntpd()+ function.
+
+'''''
+
+mailto:skamboj at udel.edu[Sachin Kamboj]
+
+include::includes/footer.txt[]
=====================================
ntpd/ntp.conf-man.txt
=====================================
--- a/ntpd/ntp.conf-man.txt
+++ b/ntpd/ntp.conf-man.txt
@@ -4,222 +4,7 @@
== NAME ==
ntp.conf - Network Time Protocol (NTP) daemon configuration file format
-== SYNOPSIS ==
-/etc/ntp.conf
-
-== DESCRIPTION ==
-
-The `ntp.conf` configuration file is read at initial startup by the
-{ntpdman} daemon in order to specify the synchronization
-sources, modes and other related information. Usually, it is installed
-in the `/etc` directory, but could be installed elsewhere (see the
-daemon's `-c` command line option).
-
-The file format is similar to other UNIX configuration files. Comments
-begin with a ‘#’ character and extend to the end of the line; blank
-lines are ignored. Configuration commands consist of an initial keyword
-followed by a list of arguments, some of which may be optional,
-separated by whitespace. Commands may not be continued over multiple
-lines. Arguments may be host names, host addresses written in numeric,
-dotted-quad form, integers, floating point numbers (when specifying
-times in seconds) and text strings.
-
-The rest of this page describes the configuration and control options.
-The "Notes on Configuring NTP and Setting up an NTP Subnet" page
-(available as part of the HTML documentation provided under
-`/usr/share/doc/ntp`) contains an extended discussion of these options.
-In addition to the discussion of general 'Configuration Options',
-there are sections describing the following supported functionality and
-the options used to control it:
-
-* Authentication Support
-* Monitoring Support
-* Access Control Support
-* Automatic NTP Configuration Options
-* Reference Clock Support
-* Miscellaneous Options
-
-Following these is a section describing 'Miscellaneous Options'.
-While there is a rich set of options available, the only required
-option is one or more `pool`, `server`, `peer`, or `broadcast`
-commands.
-
-== Configuration Support ==
-
-Following is a description of the configuration commands in
-NTPv4. There are two classes of commands, association commands that
-configure a persistent association with a remote server or peer or
-reference clock, and auxiliary commands that specify environmental
-variables that control various related operations.
-
-=== Association Commands ===
-
-Only those options applicable to each command are listed below. Use of
-options not listed may not be caught as an error, but may result in
-some weird and even destructive behavior.
-
-In contexts where a host name is expected, a `-4`or `--ipv4`
-qualifier preceding the host name forces DNS resolution to the IPv4
-namespace, while a `-6` or `--ipv6' qualifier forces DNS resolution to
-the IPv6 namespace.
-
-include::../docs/includes/assoc-commands.txt[]
-
-=== Association Options ===
-
-include::../docs/includes/assoc-options.txt[]
-
-=== Association Auxiliary Commands ===
-
-include::../docs/includes/assoc-auxcommands.txt[]
-
-== Authentication Commands ==
-
-include::../docs/includes/auth-commands.txt[]
-
-== Monitoring Support ==
-
-{ntpdman} includes a comprehensive monitoring facility suitable
-for continuous, long term recording of server and client timekeeping
-performance. See the +statistics+ command below for a listing and example of
-each type of statistics currently supported. Statistic files are managed
-using file generation sets and scripts in the ./scripts directory of this
-distribution. Using these facilities and UNIX cron(8) jobs, the data
-can be automatically summarized and archived for retrospective
-analysis.
-
-=== Monitoring Commands ===
-
-include::../docs/includes/mon-commands.txt[]
-
-== Access Control Support ==
-
-The {ntpdman} daemon implements a general purpose address/mask
-based restriction list. The list contains address/match entries sorted
-first by increasing address values and then by increasing mask
-values. A match occurs when the bitwise AND of the mask and the packet
-source address is equal to the bitwise AND of the mask and address in
-the list. The list is searched in order with the last match found
-defining the restriction flags associated with the entry. Additional
-information and examples can be found in the "Notes on Configuring NTP
-and Setting up a NTP Subnet" page (available as part of the HTML
-documentation).
-
-The restriction facility was implemented in conformance with the access
-policies for the original NSFnet backbone time servers. Later the
-facility was expanded to deflect cryptographic and clogging attacks.
-While this facility may be useful for keeping unwanted or broken or
-malicious clients from congesting innocent servers, it should not be
-considered an alternative to the NTP authentication facilities. Source
-address based restrictions are easily circumvented by a determined
-cracker.
-
-Clients can be denied service because they are explicitly included in
-the restrict list created by the restrict command or implicitly as the
-result of cryptographic or rate limit violations. Cryptographic
-violations include certificate or identity verification failure; rate
-limit violations generally result from defective NTP implementations
-that send packets at abusive rates. Some violations cause denied service
-only for the offending packet, others cause denied service for a timed
-period and others cause the denied service for an indefinite period.
-When a client or network is denied access for an indefinite period, the
-only way at present to remove the restrictions is by restarting the
-server.
-
-=== The Kiss-of-Death Packet ===
-
-Ordinarily, packets denied service are simply dropped with no further
-action except incrementing statistics counters. Sometimes a more
-proactive response is needed, such as a server message that explicitly
-requests the client to stop sending and leave a message for the system
-operator. A special packet format has been created for this purpose
-called the "kiss-of-death" (KoD) packet. KoD packets have the leap bits
-set unsynchronized and stratum set to zero and the reference identifier
-field set to a four-byte ASCII code. If the `noserve` or `notrust` flag
-of the matching restrict list entry is set, the code is "DENY"; if the
-`limited` flag is set and the rate limit is exceeded, the code is
-"RATE". Finally, if a cryptographic violation occurs, the code is
-"CRYP".
-
-A client receiving a KoD performs a set of sanity checks to minimize
-security exposure, then updates the stratum and reference identifier
-peer variables, sets the access denied (BOGON4) bit in the peer flash
-variable and sends a message to the log. As long as the BOGON4 bit is
-set, the client will send no further packets to the server. The only way
-at present to recover from this condition is to restart the protocol at
-both the client and server. This happens automatically at the client
-when the association times out. It will happen at the server only if the
-server operator cooperates.
-
-== Access Control Commands ==
-
-include::../docs/includes/access-commands.txt[]
-
-== Automatic NTP Configuration Options ==
-
-=== Manycasting ===
-
-For a detailed description of manycast operation, see the "Server
-Discovery" page (available as part of the HTML documentation).
-
-=== Manycast Options ===
-
-// This is a subset of the tos options applicable to manycast.
-// It omits the more general tinkering options. If you change this,
-// be very sure to keep docs/miscopt.txt synchronized.
-
-`tos` [`ceiling` _ceiling_ | `cohort` \{ `0` | `1` } | `floor` _floor_ | `minclock` _minclock_ | `minsane` _minsane_]::
- This command affects the clock selection and clustering algorithms. It
- can be used to select the quality and quantity of peers used to
- synchronize the system clock and is most useful in manycast mode. The
- variables operate as follows:
-
- `ceiling` _ceiling_;;
- Peers with strata above _ceiling_ will be discarded if there are at
- least _minclock_ peers remaining. This value defaults to 15, but can
- be changed to any number from 1 to 15.
- `cohort` \{0 | 1 };;
- This is a binary flag which enables (0) or disables (1) manycast
- server replies to manycast clients with the same stratum level. This
- is useful to reduce implosions where large numbers of clients with
- the same stratum level are present. The default is to enable these
- replies.
- `floor` _floor_;;
- Peers with strata below _floor_ will be discarded if there are at
- least _minclock_ peers remaining. This value defaults to 1, but can
- be changed to any number from 1 to 15.
- `minclock` _minclock_;;
- The clustering algorithm repeatedly casts out outlier associations
- until no more than _minclock_ associations remain. This value
- defaults to 3, but can be changed to any number from 1 to the number
- of configured sources.
- `minsane` _minsane_;;
- This is the minimum number of candidates available to the clock
- selection algorithm in order to produce one or more truechimers for
- the clustering algorithm. If fewer than this number are available,
- the clock is undisciplined and allowed to run free. The default is 1
- for legacy purposes. However, according to principles of Byzantine
- agreement, _minsane_ should be at least 4 in order to detect and
- discard a single falseticker.
-`ttl` _hop_ `...`::
- This command specifies a list of TTL values in increasing order, up to
- 8 values can be specified. In manycast mode these values are used in
- turn in an expanding-ring search. The default is eight multiples of 32
- starting at 31.
-
-== Reference Clock Support ==
-
-For a detailed description of reference-clock configuration, see the
-"Reference Clock Drivers" page (available as part of the HTML
-documentation provided in `/usr/share/doc/ntp`).
-
-== Reference Clock Commands
-
-include::../docs/includes/clock-options.txt[]
-
-== Miscellaneous Options ==
-
-include::../docs/includes/misc-options.txt[]
+include::../docs/includes/ntp-conf-body.txt[]
== FILES ==
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/commit/5cd114ed6966dc449c686657b3a505a1b71b29aa
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/vc/attachments/20170111/db6e0513/attachment.html>
More information about the vc
mailing list