Added explanatory comments to the priority file.

1 files changed, 56 insertions, 0 deletions

diff --git a/templates/priority b/templates/priority
index 86eef2c..dfc6d9f 100644
--- a/templates/priority
+++ b/templates/priority
@@ -1,3 +1,59 @@
+#
+# This file controls the processing of the Vyatta config file when it
+# is processed by the "load" command and at boot time.  This file has
+# two purposes.  First, it breaks the statements in the Vyatta config
+# file into groups that are applied in distinct transactions.  Second,
+# it defines the order in which these transactions are applied.
+#
+# Breaking the config file into multiple transactions is important
+# because transactions have all-or-nothing semantics.  If the file
+# were processed in a single transaction, a failure of any service would
+# mean that no services would be configured.  Processing the config
+# file in multiple transactions means that failures in one area do not
+# necessary prevent a service in another area from being configured.
+#
+# Ordering the transactions is important because some services are
+# dependent on other services being configured before they are.
+#
+# The format of this file is as a sequence of one-line entries that
+# have the following format:
+#
+#    <priority> <config-sub-tree>
+#
+# The <priority> field is number in the range 0 - 1000, and is used to
+# order the processing of of the config file.
+#
+# The <config-sub-tree> field is the path to a sub-tree of the
+# configuration tree.
+#
+# The "load" command first sorts the entries in increasing order by
+# their <priority> field.  We usually try to maintain this file in
+# sorted in increasing <priority> order so that we can redily see what
+# order the entries will be processed in.  Next, the "load" command
+# processes each entry, starting from the lowest priority entry, and
+# proceeding in increasing prioriy order.  For each entry, it checks
+# to see if the <config-sub-tree> exists in the config file.  If it
+# does, it takes the config statements under that sub-tree and removes
+# any statements that match a deeper sub-tree that was processed
+# earlier or will be processed later.  If any statements remain, they
+# are applied using "set" commands.  Then the entire group is
+# committed as a transaction using the "commit" command.  After
+# processing this entire file, if any un-applied configuration
+# statements remain, they are applied in one final transaction.
+#
+# This process has a few important consequences.  First, every
+# statement in the config file is applied exactly once.
+#
+# Second, each line in this file generates at most one transaction.
+#
+# Third, a config file statement may be applied in a transaction
+# before one of its parent nodes is applied.  Its parent may be a
+# multi-node parameter.  An example of this is if the routing protocol
+# parameters of an interface are applied before the interface itself
+# is applied.  In this case, the parent nodes are created in the
+# "active config" tree at the time the lower-level node is commited.
+#
+
 200 firewall/group
 210 firewall
 300 protocols/ospf