docs: Rewrote most of the developer's guide for clarity
Change-Id: I88fa27898cf3c7be7b93403cc879addbdf04db4c
diff --git a/configuration.tex b/configuration.tex
index 1a56ec2..985de85 100644
--- a/configuration.tex
+++ b/configuration.tex
@@ -3,7 +3,9 @@
NLSR's configuration file contains numerous parameters to control the behavior and performance of NLSR.
The configuration file also includes the trust schema used by NLSR to verify LSA Data, Hello Data, and prefix update command Interests.
-The configuration file is divided into six sections each with parameters that mainly affect a specific module.
+
+\subsection{Naming Conventions}
+The NLSR naming convention is mostly arbitrary. For example, a router's name, maybe \texttt{\%C1.Router/router1}, is composed of two parts. \texttt{\%C1.Router} is the router ``tag'', and \texttt{router1} is the name or label of the router. Different entities are given different tags, depending on the context.
\subsection{General Section}
@@ -14,7 +16,7 @@
\begin{itemize}
\item \texttt{network} - the name of the network to which the router belongs; e.g., \texttt{/ndn}.
\item \texttt{site} - the name of the site to which the router belongs; e.g., \texttt{/edu/memphis}.
-\item \texttt{router} - the name to identify the router; e.g., \texttt{/\%C1.Router/cs/pollux}.
+\item \texttt{router} - the name to identify the router; e.g., \texttt{/\%C1.Router/cs/pollux}.t
\end{itemize}
The router prefix is constructed by combining the three parameters following the format: \texttt{/<network>/<site>/<router>}.
@@ -27,20 +29,15 @@
\end{itemize}
The \texttt{log-level} parameter configures the verbosity of NLSR's logging.
-The possible \texttt{log-level} values are listed in increasing verbosity:
-\begin{itemize}
-\item \texttt{NONE} - no messages
-\item \texttt{ERROR} - error messages
-\item \texttt{WARN} - warning messages
-\item \texttt{INFO} - informational messages (default)
-\item \texttt{DEBUG} - debugging messages
-\item \texttt{TRACE} - trace messages (most verbose)
-\item \texttt{ALL} - all messages
-\end{itemize}
-Note that all debugging levels listed above the selected value will also be enabled.
+The possible \texttt{log-level} values are listed in increasing verbosity. That is, the value all the way to the left includes the values all the way to the right.
+\begin{verbatim}
+NONE < ERROR < WARN < INFO (Default) < DEBUG < TRACE < ALL
+\end{verbatim}
+
+Note that a log level also enables all log levels to its left. That is, setting log level to \texttt{TRACE} causes \texttt{ERROR, WARN, INFO} and \texttt{DEBUG} messages. to also be logged.
The \texttt{general} configuration section also includes parameters to choose where the NLSR log file and the NLSR sequence number file are stored.
-The \texttt{log-dir} parameter is an absolute path to the directory where the NLSR log file should be written, and \texttt{seq-dir} is an absolute path to the directory where the NLSR sequence number should be written.
+The \texttt{log-dir} parameter is an absolute path to the directory where the NLSR log file should be written, and \texttt{seq-dir} is an absolute path to the directory where the NLSR sequence number should be written. The log directory must exist and be writable, or else NLSR will fail to start.
\subsection{Neighbors Section}
@@ -63,6 +60,8 @@
\subsection{Hyperbolic Section}
+Hyperbolic Routing is a greedy geometric routing technique available in NLSR. The best resource to understand how it works is its white paper. \cite{HyperbolicASF}
+
The \texttt{hyperbolic} section in the configuration file is used to enable/disable hyperbolic routing and to specify the hyperbolic coordinates of the router.
The \texttt{state} parameter indicates whether or not hyperbolic routing should be enabled. There are three possible values for this parameter: \texttt{on}, \texttt{off}, and \texttt{dry-run}. \texttt{on} enables hyperbolic routing; \texttt{off} disables hyperbolic routing (link-state routing is used); \texttt{dry-run} uses link-state routing to populate NFD's FIB, but will also perform the hyperbolic routing calculations and write them to the log file for debugging purposes.
@@ -79,13 +78,13 @@
\texttt{routing-calc-interval} is the time to wait in seconds after a routing table calculation is requested before actually performing the routing table calculation.
This parameter is intended to limit the number of routing table calculations, which may be performance intensive on some systems.
-The default value for \texttt{max-faces-per-prefix} is 15 seconds and can be configured to be in the range of 0 to 15 seconds.
+The default value for \texttt{routing-calc-interval} is 15 seconds and can be configured to be in the range of 0 to 15 seconds.
\subsection{Advertising Section}
The \texttt{advertising} section includes a list of name prefixes that the router should advertise as reachable through itself.
Each name prefix that should be advertised should be in the following format: \texttt{prefix /name/to/advertise}.
-This section allows for static configuration of the advertised prefixes, but prefixes can be dynamically advertised and withdrawn using the Prefix Update Processor.
+This section allows for static configuration of the advertised prefixes, but prefixes can be dynamically advertised and withdrawn using the Prefix Update Processor.
\subsection{Security Section}
diff --git a/fib.tex b/fib.tex
index e98ec45..da3ec06 100644
--- a/fib.tex
+++ b/fib.tex
@@ -1,21 +1,52 @@
\section{FIB Interaction}
\label{sec:fib}
-The FIB module interacts directly with NFD to perform registrations and unregistrations of name prefixes.
-The FIB module is notified of additions, removals, or updates to the Name Prefix Table and will use the updated Name Prefix Table to perform the necessary registrations or unregistrations.
-The Name Prefix Table notifies the FIB module using the \texttt{Fib::update()} method which accepts a name prefix and next hops for that name prefix as parameters.
-The FIB module maintains a shadow FIB which represents its expectations of NFD's FIB.
-The FIB module uses the shadow FIB to determine which registrations and unregistrations are necessary.
+The FIB module interacts with NFD to perform registrations and
+unregistrations of routes. By registration, what is meant is the
+submission of a RIB route to the local NFD, which includes a name
+prefix, the Face ID of the nexthop, an expiration time, and the
+calculated cost from the Routing Table calculation. Additionally, NLSR
+sets a field to tell NFD that the route originates from NLSR, and sets
+a route inheritance flag.
+
+The expiration time for a route is pegged at double the value of the
+LSA refresh time, which is defined by \texttt{lsa-refresh-time} in the
+configuration file. The route inheritance flag is set to capture,
+which forbids NFD from using a shorter prefix of the name prefix for
+forwarding.
+
+More information about NFD's RIB can be found on the
+\href{https://redmine.named-data.net/projects/nfd/wiki/RibMgmt}{Redmine
+ wiki}. An important thing to note is that NFD has a module called
+the FIB. Anywhere in this guide, the word ``FIB'' refers to the NLSR
+FIB, which models NLSR's expectation of how NFD would forward packets.
+
+The FIB is directed by the Name Prefix Table, which registers and
+unregisters routes based on calculations by the Routing Table and
+advertisements from LSAs. The connection between the FIB and the NPT
+is through the \texttt{Fib::update()} method.
\subsection{Updating the FIB}
-When the Name Prefix Table performs an update on the FIB module, the FIB module will first sort the passed next hops with the next hop's costs in increasing order.
-The FIB module will next determine the number of next hops that should be installed for the name prefix using the \texttt{max-faces-per-prefix} parameter as a maximum.
-If there are more passed next hops than the \texttt{max-faces-per-prefix} parameter allows, the FIB module will only use the first \texttt{max-faces-per-prefix} number of next hops from the sorted list.
-If there are less passed next hops than the \texttt{max-faces-per-prefix} parameter, the FIB module will use all of the passed next hops.
+Generally, updating the FIB looks like this:
+\begin{itemize}
+\item Sort the list of next hops for the prefix, by cost.
+\item Take the cheapest \texttt{max-faces-per-prefix} hops. This can be set to have no limit, so all next hops are registered.
+\item Send a RIB route registration command for each next hop.
+\item Send a RIB route unregistration command for any next hops that
+ have dropped out of the list. This includes next hops that became
+ invalid since the last Routing Table calculation, as well as valid
+ hops that are no longer in the top \texttt{max-faces-per-prefix}
+ next hops.
+\end{itemize}
-The FIB module next determines if there is already a FIB entry in the shadow FIB for the passed name prefix.
-If the name prefix will create a new FIB entry and the number of passed next hops is greater than zero, a new FIB entry will be created,
-the next hops will be registered for the name prefix in NFD's FIB, and the FIB entry will be set to expire in two times the \texttt{lsa-refresh-time} in order to clean up orphaned entries in NFD's FIB.
-If there is already an existing FIB entry for the name prefix and the number of passed next hops is greater than zero, any of the passed next hops that weren't previously registered for the FIB entry are registered.
-Then, any currently registered hops that are not in the passed next hops are removed from NFD's FIB, and the entry's expiration is refreshed.
-If there is already an existing FIB entry for the name prefix and the number of passed next hops is equal to zero, the routing table was unable to find a path to this name prefix and so the name prefix should be removed from NFD's FIB.
+If there are more passed next hops than the
+\texttt{max-faces-per-prefix}, the FIB module will only use the first
+\texttt{max-faces-per-prefix} number of next hops from the sorted
+list. If there are less passed next hops than
+\texttt{max-faces-per-prefix}, the FIB module will use all of the next hops.
+Specifically, when the NPT updates the FIB, the FIB creates entries so
+that it can compute the difference between the set of new next hops,
+and the set of old next hops that were registered at the last update.
+These entries are unique on the destination name prefix. The FIB will
+update an existing entry instead of creating a new one, which may
+involve unregistering old next hops, as mentioned above.
diff --git a/hello-protocol.tex b/hello-protocol.tex
index 5b913ea..21e1f09 100644
--- a/hello-protocol.tex
+++ b/hello-protocol.tex
@@ -27,14 +27,14 @@
If the Face is created successfully, the Hello Protocol registers the Sync prefix, LSA prefix, and Key prefix using the Face ID returned by the Face creation command and sends out the Hello Interest.
If the Face cannot be created, the Hello Protocol considers the failure as a Hello Interest timeout.
-If the Hello Protocol receives Data in response to the Hello Interest, it will first verify that the Data is signed by the correct entity.
+If the Hello Protocol receives Data in response to its Hello Interest, it will first ask the Validator module to verify that the Data is valid. Data is valid if the Data is legitimately signed (in the ordinary cryptographic way) and if the key name and Data name are of a certain format.
If the Data is valid, the corresponding neighbor is set as \texttt{ACTIVE} and its timeout count is reset to zero.
If the neighbor was previously \texttt{INACTIVE}, an Adjacency LSA build is scheduled to include the newly \texttt{ACTIVE} neighbor.
If the Data is not valid, the packet is dropped.
If the Hello Interest sent to the neighbor times out, the corresponding neighbor's timed-out count is incremented.
If the neighbor's timed-out count is less than \texttt{hello-retries} in the configuration file, the Hello Protocol will send another Hello Interest after \texttt{hello-timeout} seconds.
-If the neighbor's timed-out count equals the \texttt{hello-retries} value and the neighbor is currently marked as \texttt{ACTIVE}, the neighbor's status is set to \texttt{INACTIVE} and an Adjacency LSA build is scheduled.
+If the neighbor's timed-out count equals the \texttt{hello-retries} value and the neighbor is currently marked as \texttt{ACTIVE}, the neighbor's status is set to \texttt{INACTIVE} and an Adjacency LSA build is scheduled.
\subsection{Responding to Hello Interests}
\label{sec:respond-to-hello}
diff --git a/intro.tex b/intro.tex
index b5e9b77..87e47ce 100644
--- a/intro.tex
+++ b/intro.tex
@@ -15,21 +15,25 @@
NLSR uses the following modules:
\begin{itemize}
\item \textbf{Hello Protocol} (Section~\ref{sec:hello-protocol}) - determines the status of neighboring routers using periodic Hello Interests and notifies other modules when neighbors' statuses change.
-\item \textbf{NSync} - provides LSDB synchronization by extending the ChronoSync protocol~\cite{chronosync}.
+\item \textbf{ChronoSync} - provides network-wide synchronization of NLSR LSDBs.~\cite{chronosync}
\item \textbf{Sync Logic Handler} (Section~\ref{sec:sync-logic}) - handles sync update notifications from NSync by retrieving updated LSAs.
\item \textbf{LSAs} (Section~\ref{sec:lsas}) - represent routing information published by the router.
\item \textbf{LSDB} (Section~\ref{sec:lsdb}) - stores the LSA information distributed by other routers in the network.
\item \textbf{Routing Table} (Section~\ref{sec:routing-table}) - calculates and maintains a list of next hops for each router in the network.
\item \textbf{Name Prefix Table} (Section~\ref{sec:npt}) - stores all advertised name prefixes and their next hops.
\item \textbf{FIB} (Section~\ref{sec:fib}) - maintains a shadow FIB which represents the intended state of NFD's FIB~\cite{NFD}.
-\item \textbf{Prefix Update Processor} - listens for dynamic prefix announcements to advertise or withdraw name prefixes.
+\item \textbf{Prefix Update Processor} (Section~\ref{sec:prefix-update}) - listens for dynamic prefix announcements to advertise or withdraw name prefixes.
+\item \textbf{NFD RIB Command Processor} (Section~\ref{sec:nfd-rib-commands}) - listens for readvertise-to-NLSR commands to advertise or withdraw name prefixes that were inserted into NFD.
\end{itemize}
\subsection{Protocol Overview}
\label{sec:protocol-overview}
-NLSR is designed to accomplish three main tasks: (1) discover adjacent neighbors; (2) disseminate and synchronize topology, name prefix, and hyperbolic routing information; and (3) calculate a consistent routing table and populate NFD's FIB.
-The entire protocol is described in detail in the NLSR paper~\cite{NlsrTr}.
+NLSR is designed to accomplish three main tasks: (1) discover adjacent
+neighbors; (2) disseminate and synchronize topology, name prefix, and
+hyperbolic routing information; and (3) calculate a routing table and
+populate NFD's FIB. The entire protocol is described in detail in the
+NLSR paper~\cite{NlsrTr}.
\subsubsection{Discovering Neighbors}
@@ -38,15 +42,15 @@
\subsubsection{Disseminating Routing Information}
-When one of a router's LSAs (Section~\ref{sec:lsas}) changes, the information of this change should be distributed to every other router in the network.
+When a router's LSAs (Section~\ref{sec:lsas}) changes, the information of this change should be distributed to every other router in the network.
The Sync Logic Handler module (Section~\ref{sec:sync-logic}) is used to notify the synchronization protocol of changes to the router's own LSAs as well as to learn of LSA changes from other routers in the network;
-the Sync Logic Handler module interfaces with NSync to perform the two tasks.
+the Sync Logic Handler module interfaces with ChronoSync to perform the two tasks.
When the Sync Logic Handler module learns of a new LSA, it will inform the LSDB module.
The LSDB module will attempt to fetch the new LSA and will store it in the LSDB module's database if it can be retrieved.
If the newly fetched LSA informs the router of previously unknown routing information, the LSDB module will inform other modules depending on the type of routing information:
\begin{itemize}
-\item \textbf{Change in network topology} - the LSDB module will inform the Routing Table module (Section~\ref{sec:routing-table}), so the Routing Table module can calculate an up-to-date routing table.
+ \item \textbf{Change in network topology} - the LSDB module will ask the Routing Table module (Section~\ref{sec:routing-table}) to recalculate paths in the network
\item \textbf{Change in name prefix advertisement} - the LSDB module will inform the Name Prefix Table module (Section~\ref{sec:npt}), which will in turn notify the FIB module (Section~\ref{sec:fib}) in order to add or remove the changed name prefixes.
\item \textbf{Change in hyperbolic coordinates} - the LSDB module will inform the Routing Table module (Section~\ref{sec:routing-table}), so the Routing Table module can calculate an up-to-date routing table.
\end{itemize}
diff --git a/lsas.tex b/lsas.tex
index 6b4da0e..2467617 100644
--- a/lsas.tex
+++ b/lsas.tex
@@ -2,11 +2,6 @@
\label{sec:lsas}
Link-State Advertisements (LSAs) represent pieces of routing information distributed by routers.
-NLSR uses three types of LSAs to distribute routing information:
-Adjacency LSAs which include neighboring node and link information,
-Coordinate LSAs which include a router's hyperbolic coordinates, and
-Name LSAs which include advertised name prefixes reachable through the router.
-All of the LSAs received by the router are maintained by the LSDB module (Section~\ref{sec:lsdb}).
\subsection{LSA Base Class}
\label{sec:lsa-base-class}
@@ -14,15 +9,15 @@
All three LSA implementations inherit from an LSA Base class, \texttt{Lsa}, which maintains information that is included in each LSA.
The \texttt{LSA} class contains the following member variables:
\begin{itemize}
-\item \textbf{Origin Router} - the router that advertised the LSA.
-\item \textbf{Sequence Number} - a number used to indicate the LSAs version as well as its ordering compared to other LSAs received from the same router.
-\item \textbf{Expiration Time Point} - a time point indicating when the LSA is no longer valid.
+\item \textbf{Origin Router} - the router that advertised the LSA. Specifically, this is a name prefix that follows the NLSR convention of router naming.
+\item \textbf{Sequence Number} - a number used to indicate the LSA's version. Because sequence numbers are preserved between NLSR restarts, a higher sequence number also always indicates a \emph{newer} LSA.
+\item \textbf{Expiration Time Point} - a time point indicating when the LSA is no longer valid. This currently is represented as a Unix timestamp (i.e. seconds since Jan 1, 1970).
\end{itemize}
\subsection{Adjacency LSAs}
\label{sec:adjacency-lsas}
-Adjacency LSAs maintain an \texttt{AdjacencyList} which contains all the currently \texttt{ACTIVE} neighbors of the origin router.
+Adjacency LSAs maintain an \texttt{AdjacencyList} which contains information about all the currently \texttt{ACTIVE} neighbors of the origin router. It also includes the number of active routers, not just the list itself. This aids in serialization.
\subsection{Coordinate LSAs}
\label{sec:coordinate-lsas}
@@ -32,4 +27,4 @@
\subsection{Name LSAs}
\label{sec:name-lsas}
-Name LSAs maintain a \texttt{NamePrefixList} which contains advertised name prefixes that are reachable through the origin router.
\ No newline at end of file
+Name LSAs maintain a \texttt{NamePrefixList} which contains the name prefixes that are reachable at the origin router.
diff --git a/lsdb-status-dataset.tex b/lsdb-status-dataset.tex
new file mode 100644
index 0000000..d90fc88
--- /dev/null
+++ b/lsdb-status-dataset.tex
@@ -0,0 +1,22 @@
+\section{LSDB Status Dataset}
+\label{sec:lsdb-status-dataset}
+
+NLSR makes available the entire contents of the LSDB upon request. A
+command can request LSAs of just a specific type, or request the
+collection of all LSAs. Unlike the Prefix Update and NFD RIB command
+processors, the LSDB Status dataset is available over \emph{both} the
+\texttt{/localhost} and regular router prefixes. That is, you can
+request an arbitrary router's LSDB contents.
+
+\subsection{Requesting the dataset}
+\begin{itemize}
+\item To request the local dataset, simply send an Interest of the
+ form \texttt{/localhost/nlsr/lsdb/<dataset type>}.
+\item To request a remote dataset, send an Interest of the form
+ \texttt{/<router name>/lsdb/<dataset type>}, where \texttt{<router
+ name>} is whatever the router's name is. This is usually
+ \texttt{general.network + general.site + general.router} from the
+ configuration file.
+\end{itemize}
+
+Where \texttt{<dataset type>} is one of \texttt{names, adjacencies, coordinates} or \texttt{list}.
diff --git a/lsdb.tex b/lsdb.tex
index b5a3e13..7ada0a7 100644
--- a/lsdb.tex
+++ b/lsdb.tex
@@ -1,31 +1,137 @@
\section{Link-State Database}
\label{sec:lsdb}
-The Link-State Database (LSDB) holds LSA information distributed by other routers in the network.
-The LSDB stores all three types of LSAs and will trigger necessary events when a new LSA is added, when an LSA is updated, and when an LSA expires.
-The LSDB also handles LSA retrieval and validation, performs LSA builds, and triggers routing table calculations.
+The Link-State Database (LSDB) holds LSA information distributed by
+other routers in the network. The LSDB stores all types of LSAs and
+will trigger events when a new LSA is added, updated, or expires. The
+LSDB also handles LSA retrieval, performs LSA builds, and triggers
+routing table calculations.
\subsection{Retrieving an LSA}
-The LSDB provides \texttt{Lsdb::expressInterest()} as a public interface to retrieve an LSA from the network.
-If LSA Data is returned, the LSDB will handle the Data validation and perform the necessary LSDB modifications.
-If the LSA Interest times out, the LSDB will continue to re-attempt to fetch the LSA Data.
-The LSDB will stop trying these fetch re-attempts once it has tried for as long as the maximum configurable LSA refresh time.
+The LSDB provides the \texttt{Lsdb::expressInterest()} method as a
+public interface to retrieve an LSA from the network. If LSA Data is
+returned, the LSDB will validate the Data using the Validator
+module. Then, it will perform the necessary LSDB modifications. If
+the LSA Interest times out, the LSDB will retry until it reaches a
+configurable maximum number of tries, or a configurable deadline
+passes.
-\subsection{Building LSAs}
+The LSDB uses the SegmentFetcher system to retrieve LSAs. LSAs very
+often will exceed the maximum NDN packet size. In these cases, the LSA
+needs to be split into segments to be sent, so the LSDB uses the
+SegmentFetcher to send all LSAs. The SegmentFetcher can decide if the
+data actually needs to be split.
-The LSDB provides three interfaces to build and install a router's own various LSAs.
+\subsection{General Procedure}
+
+The LSDB is responsible for building, installing, and publishing
+NLSR's LSAs, as well as for installing and processing LSAs from other
+NSLRs. Generally, the functions of the LSDB are:
\begin{itemize}
-\item \texttt{Lsdb::scheduleAdjLsaBuild()} schedules an Adjacency LSA calculation if one is not already scheduled and if hyperbolic routing is not turned on, i.e. if link-state routing or dry run is on.
-\item \texttt{Lsdb::buildAndInstallOwnAdjLsa()} instantiates a new Adjacency LSA with the router's current adjacency list, incremented sequence number, and number of active neighbors. It also notifies the Sync Logic Handler to publish the routing update(Section~\ref{sssec:routing-update}) if link-state routing or dry-run is enabled to let other node in the network know the newly instlled Adjacency LSA.
-\item \texttt{Lsdb::buildAndInstallOwnCoordinateLsa()} instantiates a new Coordinate LSA with the router's hyperbolic coordinates and an incremented sequence number. The newly constructed Coordinate LSA is then installed in the LSDB. It also notifies the Sync Logic Handler to publish the routing update(Section~\ref{sssec:routing-update}) if hyperbolic routing or dry run is turned on to let other nodes in the network know the newly installed Coordinate LSA.
-\item \texttt{Lsdb::buildAndInstallOwnNameLsa()} instantiates a new Name LSA with the router's current name prefix list and an incremented sequence number. The newly constructed Name LSA is then installed in the LSDB.
+\item Schedule the building of an LSA.
+\item Building the LSA.
+\item Installing the LSA into the LSDB.
\end{itemize}
-\subsection{LSA Installation and Updates}
+\subsection{Scheduling LSA Builds}
+LSAs need to be rebuilt whenever the routing information NLSR has
+changes. This includes events like neighbors becoming active, or when
+a prefix for advertisement is inserted by the Prefix Update Processor,
+which would cause an adjacency LSA or a name LSA rebuild,
+respectively. To improve performance, instead of directly building
+adjacency LSAs the first request schedules the build, and build requests
+that occur after the scheduling but before the actual event are
+aggregated (in other words, ignored), because they will be satisfied
+by the already-scheduled build. Some specifics are shown below.
+below.
+\begin{itemize}
+\item \textbf{Adjacency LSAs} -- will only be scheduled if link-state
+ routing is enabled. In particular, this means Adjacency LSA builds
+ will \emph{not} occur if hyperbolic routing is enabled. Note that
+ adjacency LSAs will be built if dry-run hyperbolic routing is
+ enabled, as the network is still using link-state routing to
+ calculate paths.
+\end{itemize}
-The LSDB provides three internal interfaces for each of the three types of LSAs to add or update LSAs in the LSDB.
-The general logic for each type of LSA installation is similar (Figure~\ref{fig:generic-lsdb-flow}), but there are slight differences in the events that are triggered by an installation or update.
+\subsection{Building LSAs}
+Building LSAs has a part common to all LSAs and a part specific to
+each LSA type. For example, all LSA types increment sequence number
+and have the same expiration length, and of course come from the same
+router. Additionally, all LSA builds cause a sync update
+publishing. However, each type of LSA includes different data, to
+represent different kinds of information that NLSR
+has. (Section~\ref{sec:lsas}) In particular:
+\begin{itemize}
+ \item \textbf{Adjacency LSAs} -- the number and a list of active
+ neighbors is included.
+ \item \textbf{Coordinate LSAs} -- the hyperbolic radius and all
+ hyperbolic angles are included.
+ \item \textbf{Name LSAs} -- the list of name prefixes that are
+ accessible at this router is included.
+\end{itemize}
+
+\subsection{Installing and Processing LSAs}
+LSA installation procedure is mostly the same across any type of LSA,
+but each type also has installation behavior specific to that type,
+too. For any LSA type, we need to schedule an expiration event, and we
+need to update several fields in the LSA. However, installing an
+adjacency or coordinate LSA causes a Routing Table calculation, but a
+name LSA does not, for example.
+%%| Not yet true, but it should be true!
+Additionally, the name of the origin router is added as a ``routable prefix'' in the NPT. (Section~\ref{sec:npt}).
+\begin{itemize}
+ \item \textbf{Adjacency LSAs} -- each adjacency in the LSA will be
+ added as a ``routable prefix'' to the NPT. If the adjacencies have
+ changed since the last version of this LSA, a Routing Table
+ calculation needs to be scheduled, because the state of the
+ network has changed. Of course, this is necessarily true if the
+ LSA is new to us. Important to note is that we will also install
+ and process \emph{our own} adjacency LSA in this way.
+ \item \textbf{Coordinate LSAs} -- the router that the LSA is from
+ will be added as a ``routable prefix'' to the NPT. If the radius
+ and coordinates have changed since the last version of this LSA, a
+ Routing Table calculation needs to be scheduled, because the state
+ of the network has changed. As above, this is true for a new
+ LSA. This is only done if the LSA is from a foreign router.
+ \item \textbf{Name LSAs} -- each name prefix in the LSA will be
+ added to our NPT. This is only done if the LSA is from a foreign
+ router.
+\end{itemize}
+
+\subsection{LSA Expiration}
+LSAs expire so that the network can clean up when a router
+crashes. The amount of time an LSA lasts is configurable. When an LSA
+expires, we refresh it if it's our LSA, and remove it from the LSDB if
+not. There is a ``grace period'' window that is appended to the end of
+the expiration period of all LSAs, to provide time for the originating
+router to refresh the LSA and for it to propagate back to us. In all
+expiration cases, the name of the origin router will be removed from
+the NPT. What happens when an LSA is removed from the LSDB differs
+based on the type of LSA:
+\begin{itemize}
+ \item \textbf{Adjacency LSAs} -- a Routing Table calculation needs to occur,
+ since the state of the network has changed, at least from our
+ perspective.
+ \item \textbf{Coordinate LSAs} -- a Routing Table calculation needs to occur,
+ since the state of the network has changed, at least from our
+ perspective.
+ \item \textbf{Name LSAs} -- the name prefixes in the LSA are removed from the
+ NPT.
+\end{itemize}
+
+\subsection{LSA Refreshment}
+NLSR will only refresh its own LSAs. Additionally, the procedure for refreshing an LSA is the same for all types:
+\begin{itemize}
+\item Increment the LSA sequence number
+\item Schedule another expiration event. The length of time to wait
+ until refreshing is configurable, but it should probably be lower
+ than the expiration time that was set when building the LSA
+ initially. This prevents other routers from deleting our LSAs
+ because the network is slow, for instance. The length of time is set
+ by \texttt{lsa-refresh-time} in the configuration file.
+\item Publish an update to sync
+\end{itemize}
\begin{figure}[h]
\center
@@ -33,71 +139,3 @@
\label{fig:generic-lsdb-flow}
\caption{The general LSDB logic for each LSA type}
\end{figure}
-
-\subsubsection{Lsdb::installAdjLsa()}
-
-When an Adjacency LSA is passed to \texttt{Lsdb::installAdjLsa()}, the LSDB first attempts to find the LSA in its current database.
-
-If the Adjacency LSA is not installed in the database, the LSA will first be added to the database.
-If the installed LSA is advertised by a remote router, the remote router's name will be added to the NPT and the LSA will be scheduled to expire after the expiration time point included in the LSA.
-Since a new Adjacency LSA introduces a new node and new links in the network, a routing table calculation is scheduled.
-
-If the Adjacency LSA is already installed in the database, the existing LSA will only be updated if the newly received LSA has a higher sequence number.
-If an Adjacency LSA with a higher sequence number is being installed, the existing LSA's sequence number and expiration time will be updated.
-If the newly received LSA contains an adjacency list that is different from the existing LSA, the existing LSA's adjacencies are updated and a routing table calculation is scheduled to account for the network change.
-Finally, if the updated LSA is advertised by a remote router, the LSA will be scheduled to expire after the expiration time point included in the LSA.
-
-\subsubsection{Lsdb::installCoordinateLsa()}
-
-When a Coordinate LSA is passed to \texttt{Lsdb::installCoordinateLsa()}, the LSDB first attempts to find the LSA in its current database.
-
-If the Coordinate LSA is not installed in the database, the LSA will first be added to the database.
-If the installed LSA is advertised by a remote router, the remote router's name will be added to the NPT, and the LSA will be scheduled to expire after the expiration time point included in the LSA.
-If hyperbolic routing is enabled, a new Coordinate LSA means that the routing table should be re-calculated to include the new destination router.
-
-If the Coordinate LSA is already installed in the database, the existing LSA will only be updated if the newly received LSA has a higher sequence number.
-If a Coordinate LSA with a higher sequence number is being installed, the existing LSA's sequence number and expiration time will be updated.
-If the newly received LSA contains hyperbolic coordinate different from the existing LSA, the existing LSA's coordinates are updated.
-If hyperbolic routing is enabled, an LSA with new coordinates means the routing table should be re-calculated to account for the different coordinates.
-Finally, If the updated LSA is advertised by a remote router, the LSA will be scheduled to expire after the expiration time point included in the LSA.
-
-\subsubsection{Lsdb::installNameLsa()}
-
-When a Name LSA is passed to \texttt{Lsdb::installNameLsa()}, the LSDB first attempts to find the LSA in its current database.
-
-If the Name LSA is not installed in the database, the LSA will first be added to the database.
-If the installed LSA is advertised by a remote router, the remote router's name and each advertised name in the LSA will be added to the NPT, and the LSA will be scheduled to expire after the expiration time point included in the LSA.
-
-If the Name LSA is already installed in the database, the existing LSA will only be updated if the newly received LSA has a higher sequence number.
-If a Name LSA with a higher sequence number is being installed, the existing LSA's sequence number and expiration time will be updated.
-A set difference is performed between the new LSA's advertised name prefix list and the existing LSA's advertised name prefix list to determine name prefixes that have been added.
-If there are added name prefixes, the name prefixes are added to the NPT and to the existing LSA.
-A set difference is then performed between the new LSA's advertised name prefix list and the existing LSA's advertised name prefix list to determine name prefixes that have been removed.
-If there are removed name prefixes, the name prefixes are removed from the NPT and from the existing LSA.
-Finally, If the updated LSA is advertised by a remote router, the LSA will be scheduled to expire after the expiration time point included in the LSA.
-
-\subsection{LSA Expiration}
-
-LSAs are scheduled to expire after a configurable amount of time in order to allow for LSDB cleanup when a router crashes.
-After the expiration period, if the LSA belongs to the current router, the LSA is refreshed with an incremented sequence number (Section~\ref{sec:lsa-refresh}).
-Otherwise, if the LSA belongs to a remote router, the LSA is removed from the LSDB.
-Removing an LSA from the LSDB triggers different events depending on the type of the LSA.
-\begin{itemize}
-\item \textbf{Adjacency LSA} - When an Adjacency LSA is removed, a routing table calculation is scheduled to determine new paths that don't include the associated router.
-\item \textbf{Coordinate LSA} - When a Coordinate LSA is removed and hyperbolic routing is enabled, a routing table calculation is scheduled.
-\item \textbf{Name LSA} - When a Name LSA is removed, the name prefixes advertised by the LSA are removed from the NPT.
-\end{itemize}
-
-In all three cases, the LSA's origin router's name will also be removed from the NPT.
-
-\subsection{LSA Refresh}
-\label{sec:lsa-refresh}
-
-When a router refreshes its own LSA, all three LSA types trigger the same events:
-\begin{itemize}
-\item Increment the LSA's sequence number by one
-\item Schedule the LSA to expire after the configured \texttt{lsa-refresh-time}.
-\item Publish a routing update in NSync to notify other routers of the change in the LSDB.
-\end{itemize}
-
-
diff --git a/nfd-rib-command-processor.tex b/nfd-rib-command-processor.tex
new file mode 100644
index 0000000..0d5dba5
--- /dev/null
+++ b/nfd-rib-command-processor.tex
@@ -0,0 +1,23 @@
+\section{NFD RIB Command Processor}
+\label{sec:nfd-rib-commands}
+
+The NFD RIB Command Processor allows modification of NLSR's advertised
+name prefixes using NFD's RibMgmt commands. Such commands may
+originate from something like NFD's Readvertise module, which permits
+routes inserted in NFD to be propagated through to NLSR, so that NLSR
+can provide routing support for them.
+
+\subsection{Advertising and Withdrawing Routes}
+The processor accepts valid RibMgmt commands that have the name prefix
+to manipulate the origin of the route specified. No other validation
+is performed, as stated below.
+
+The processor does not send any kind of response to commands.
+
+\subsection{Security}
+Any RibMgmt commands received on the \texttt{/localhost/nlsr/rib}
+prefix are considered secure, and are processed. This introduces a
+security hole because anyone who can send a RibMgmt command on this
+prefix can arbitrarily manipulate NLSR's advertised prefixes. However,
+because sending commands to this prefix requires root access, a
+would-be attacker will already have root access locally.
diff --git a/nlsr-docs.pdf b/nlsr-docs.pdf
index 271c829..0b48d13 100644
--- a/nlsr-docs.pdf
+++ b/nlsr-docs.pdf
Binary files differ
diff --git a/nlsr-docs.tex b/nlsr-docs.tex
index 9857c7b..4d5c1af 100644
--- a/nlsr-docs.tex
+++ b/nlsr-docs.tex
@@ -68,9 +68,12 @@
\clearpage
\input{fib}
\clearpage
-%\input{sequencing-manager}
-%\input{prefix-update}
-%\input{publishers}
+\input{prefix-update}
+\clearpage
+\input{nfd-rib-command-processor}
+\clearpage
+\input{lsdb-status-dataset}
+\clearpage
\input{security}
\clearpage
\input{configuration}
diff --git a/nlsr.bib b/nlsr.bib
index ea8d32a..fb59791 100644
--- a/nlsr.bib
+++ b/nlsr.bib
@@ -4223,8 +4223,8 @@
@Misc{HyperbolicASF,
author = {Lehman, Vince and Gawande, Ashlesh and Aldecoa, Rodrigo and Krioukov, Dmitri and Wang, Lan and Zhang, Beichuan and Zhang, Lixia},
title = {{An Experimental Investigation of Hyperbolic Routing with a Smart Forwarding Plane in NDN}},
-note = {Manuscript submitted for publication},
-year = {2015}
+year = {2016},
+howpublished = {\url{https://named-data.net/wp-content/uploads/2016/07/ndn-0042-1-asf.pdf}}
}
@inproceedings{schneider2015beyond,
diff --git a/npt.tex b/npt.tex
index d9197d4..8140bc9 100644
--- a/npt.tex
+++ b/npt.tex
@@ -3,7 +3,7 @@
\begin{figure}[!h]
\center
- \includegraphics[width=0.8\linewidth]{npt}
+ \includegraphics[width=0.8\linewidth]{npt.pdf}
\begin{caption}
A diagram of the NPT and Routing Table.
@@ -22,61 +22,65 @@
The NPT entries keep shared pointers to the appropriate routing table pool entries.
If a name prefix is advertised by multiple routers, the name prefix will be represented by only one Name Prefix Table Entry, but will have multiple routing table pool entries which correspond with each origin router.
-If a Name LSA exists with an advertised name prefix, that advertised name prefix must be represented in the NPT.
-Thus, if two routers advertise the same name prefix and one Name LSA expires, the NPT entry must not be removed due to the existence of the Name LSA from the other router.
+If a Name LSA exists with some advertised name prefix, then that prefix must have an entry in the NPT. So, if two routers advertise the same name prefix, i.e. their name LSAs contain a common name prefix, even if one router withdraws that common name prefix, the entry must remain in the NPT, because the other router still advertises it.
-If an any type of LSA for a remote router exists in the LSDB, the remote router's name prefix must be present in the NPT.
-An NPT Entry for a router name can be safely removed when there are no more LSAs in the LSDB from the origin router or there are no routing table entries for the origin router.
+If any type of LSA for a remote router exists in the LSDB, the remote router's name prefix must be in the NPT.
+An NPT Entry for a router name can only be removed when there are no more LSAs in the LSDB from the origin router. Note, even if some NPT entry nas no next hops, it will \emph{not} be removed from the NPT; it may later become possible to route to this prefix. These prefixes will be removed from the FIB, however.
\subsection{Adding an NPT Entry}
\label{sec:npt-add}
-The \texttt{NamePrefixTable::addEntry()} method is the public interface for name prefixes to be added to the NPT.
-The name prefix as well as the router's prefix which originates the name prefix are passed as parameters to the interface.
-The NPT will look through its collection of routing table pool entries first to see if it already has the appropriate route.
-If the NPT locates a local entry, it will increment that entry's use count.
-If none can be found, if will check in the Routing Table to see if a ``raw'' routing table entry matching the origin of the prefix is available there.
-If one is found, it will create a routing table pool entry with the same information, and a use count of one. This new routing table pool entry will then be used.
-If one is not found, a routing table pool entry with no routing information and a use count of one is made, and the NPT entry will retain this ``dummy'' routing information until the Routing Table performs a calculation and updates it.
+The \texttt{NamePrefixTable::addEntry()} method is the public
+interface for name prefixes to be added to the NPT.
+The name prefix as well as the router's prefix which originates the
+name prefix are passed as parameters to the method.
-The rest of the method determines if this NPT entry already exists in the NPT itself.
-If it has not been added, i.e. it is new, a new NPT entry will be made and installed in the NPT.
-Then the routing table pool entry with the routing information to the origin router's prefix will be added to this new NPT entry.
-If the entry already exists in the NPT, then the existing entry will be updated in the same way as the new one.
-If the updated NPT entry has next hops, the NPT will update the FIB with the prefix and its next hops.
-If there are no next hops, then this means that there is no way for the router to reach the origin.
-The FIB entry will be removed, but the NPT entry will be retained, as the routing table may calculate a new route.
-
+If the name prefix is new, there will be no NPT entry for it, so one
+will be created. If the name prefix is not new, the existing entry
+will be updated, so the existing entry will also store this new origin
+router's prefix, too. If after updating, the NPT entry has any next
+hops, which are associated to each of the origin router prefixes, the
+NPT will update the FIB to include that prefix and its next hops. The
+next hop list is sorted and truncated to be only as long as the
+\texttt{max-faces-per-prefix} variable.
+n
\subsection{Removing an NPT Entry}
\label{sec:npt-del}
-The \texttt{NamePrefixTable::removeEntry()} method is the public interface for name prefixes to be removed from the NPT.
-The name prefix as well as the router's prefix which originates the name prefix are passed as parameters to the interface.
-The NPT will use the origin router's name to look through its local collection of routing table pool entries.
-Because this is the NPT's centralized, total pool of routing information, if the entry does not exist here it cannot exist in any NPT entries.
-In that case, the method ends.
-Else, the method will look through the collection of NPT entries for the entry matching the name prefix in the parameters.
-If it does not find it, there is nothing to be done, and the method ends.
-If it does find a matching entry, it will remove from that entry the routing table pool entry with the origin router prefix matching the one given in the parameters.
-The next hop information of the entry is rebuilt, and then the method checks if the entry has any next hops.
-If it does, the method will inform the FIB of the change with the name prefix and the next hops.
-If the entry no longer has any next hops, this means that there is no routing information to any router advertising that prefix.
-In this case, the NPT will remove that entry, as it is no longer useful.
+The \texttt{NamePrefixTable::removeEntry()} method is the public
+interface for name prefixes to be removed from the NPT.
+The name prefix as well as the router's prefix which originates the
+name prefix are passed as parameters to the interface.
+
+This method removes an origin router prefix from some advertised name
+prefix. After this, there may be other origin routers that serve this
+name prefix, so this does not guarantee that the NPT entry will be
+deleted. If after updating the entry has any next hops, the NPT will
+update the FIB to reflect the change. Since the next hop list is
+sorted by ascending cost and its length truncated to
+\texttt{max-faces-per-prefix}, the contents of next hop list will not
+change if the removed origin router prefix was not already in the list
+passed to the FIB.
+
+Note that even if the entry no longer has any next hops, it will be retained. All FIB entries for this prefix will be removed from the FIB, which will result in unregistrations from NFD, but the NPT entry will be retained. This is because it may become possible later to route to these origin routers again.
\subsection{Updating an NPT Entry with New Routing Table Entries}
\label{sec:npt-update-with-new-route}
-When the Routing Table module has finished calculating, it will notify the NPT using the \texttt{NamePrefixTable::updateWithNewRoute()} interface.
-The NPT will then iterate over each of its entries and each entry's routing table pool entry list.
-For each routing entry in the list, the NPT will attempt to fetch the new next hop list from the Routing Table, and set the entry's next hop list to that.
-If no list is available, it clears the routing table pool entry's next hop list.
-Then, \texttt{NamePrefixTable::addEntry()} is called with the current NPT entry and routing table pool entry pair.
+When the Routing Table module has finished calculating, it will notify
+the NPT using the \texttt{NamePrefixTable::updateWithNewRoute()}
+method.
+The NPT will then make approximately $m \times n$ calls to
+\texttt{addEntry}, where $m$ is the number of NPT entries and $n$ is
+the number of origin routers for each m. That is, $n$ will vary from
+one NPT entry to the next in most cases.
-\subsection{Adding routing table pool entries to the pool}
-\label{sec:npt-rtpe-add}
-Whenever a routing table pool entry (RTPE) needs to be constructed, the method \texttt{NamePrefixTable::addRtpeToPool()} is called.
-It constructs and inserts into the hash map a pair object whose first element is the origin router prefix, and whose second element is a shared pointer to the actual routing table pool entry object.
-As stated in the \texttt{NamePrefixTable::addEntry()} method, the RTPE will have a use count of one.
+\subsection{Routing Table Entry Pool}
+The Name Prefix Table has an internal data structure to help
+de-duplicate Routing Table information. Without this, each Routing
+Table entry has to be stored $n$ times, if $n$ is the number of
+prefixes that origin router advertises. Instead, each time a Routing
+Table entry would be fetched, the NPT first checks its internal data
+structure to see if that Routing Table entry is being used by another
+NPT entry. In that case those two NPT entries can share a pointer to
+that cached copy of the Routing Table entry.
-\subsection{Removing routing table pool entries from the pool}
-\label{sec:npt-rtpe-del}
-After an RTPE is removed from an NPT entry, it will be deleted from the pool if \texttt{NamePrefixTable::removeEntry()} determines that the RTPE now has a use count of 0.
-It will then call \texttt{NamePrefixTable::deleteRtpeFromPool()}, passing the RTPE as a parameter.
-The method will erase the element from the hash map that they are contained in.
+This internal cache is smart, and will clean up from the cache unused
+entries when they are removed from the last NPT entry.
diff --git a/prefix-update.tex b/prefix-update.tex
index bca2329..d1522b4 100644
--- a/prefix-update.tex
+++ b/prefix-update.tex
@@ -1,2 +1,20 @@
\section{Prefix Update Processor}
\label{sec:prefix-update}
+
+The Prefix Update processor allows manipulation of NLSR's advertised
+name prefixes with ordinary ControlCommands. Such commands may
+originate from something like \texttt{nlsrc}, the command line tool
+for manipulating NLSR.
+
+\subsection{Advertising and Withdrawing Routes}
+The processor accepts valid ControlCommands that are signed by the site operator's key. Additionally, the commands must be received on the \texttt{/localhost/nlsr/prefix-update/} prefix. The full condition list is specified in the validator rules in the configuration file.
+
+The processor will send responses to commands.
+
+\subsection{Security}
+Prefix Update commands are similar to NFD RIB commands, but with one
+additional requirement, so they are more secure. In addition to being
+on the root-only \texttt{/localhost/} prefix, Prefix Update commands
+must be signed by the site operator's key. If the site operator's key
+were compromised, an attacker could create any number of NLSRs that
+impersonate the legitimate NLSR running at that site.
diff --git a/routing-table.tex b/routing-table.tex
index 17ea6f2..597ad50 100644
--- a/routing-table.tex
+++ b/routing-table.tex
@@ -7,17 +7,16 @@
\subsection{Routing Table Calculators}
\label{sec:routing-table-calculator}
-The \texttt{RoutingTableCalculator} is a base class provides functionality common to both link-state and hyperbolic routing.
+The \texttt{RoutingTableCalculator} is a base class that provides functionality common to both link-state and hyperbolic routing.
The Routing Table module uses the implementation class specific to the type of routing currently enabled.
\subsubsection{Link-State Routing Table Calculator}
The \texttt{LinkStateRoutingTableCalculator} class calculates the routing table uses Dijkstra's algorithm to calculate the shortest paths in the network.
When \texttt{max-faces-per-prefix} is set to one, the \texttt{LinkStateRoutingTableCalculator} can simply run Dijkstra's algorithm.
-When \texttt{max-faces-per-prefix} is set to a value indicating multi-path calculation, the \\ \texttt{LinkStateRoutingTableCalculator} will iteratively perform Dijkstra's using only a single neighbor link as a next hop.
+When \texttt{max-faces-per-prefix} is greater than one, indicating multi-path calculation, the \\ \texttt{LinkStateRoutingTableCalculator} will iteratively perform Dijkstra's using only a single neighbor link as a next hop.
The calculation will be performed using each neighbor in order to learn the path costs for each destination through each next hop.
-
\subsubsection{Hyperbolic Routing Table Calculator}
The \texttt{HyperbolicRoutingCalculator} class calculates the routing table using the Coordinate LSAs received from each router in the network to determine the cost from each of its neighbors to every other router in the network.
@@ -27,6 +26,6 @@
\subsection{Notifications for Newly Calculated Next Hops}
-Once the Routing Table Module has finished calculating the routing table, it will notify the Name Prefix Table module using the \texttt{NamePrefixTable::updateWithNewRoute} interface.
+Once the Routing Table Module has finished calculating the routing table, it will update all of the Name Prefix Table's next hops.
The Name Prefix Table Module will then update the next hops for each name prefix based on the newly calculated routing table.
-This process is described in more detail in Section~\ref{sec:npt-update-with-new-route}.
\ No newline at end of file
+This process is described in more detail in Section~\ref{sec:npt-update-with-new-route}.
diff --git a/security.tex b/security.tex
index cffe4c7..e26d5d9 100644
--- a/security.tex
+++ b/security.tex
@@ -54,9 +54,10 @@
\subsection{Certificate Publishing}
-In a network, every router should have the root certificate configured as a trust anchor for the \texttt{validator} in the configuration file.
+In a network, every router must have the root certificate configured as a trust anchor for the \texttt{validator} in the configuration file. If two routers in a network do not share a common trust anchor, then when one seeks to validate the data of the other, they may be unable to establish trust in their signature. This is, of course, because of how the trust hierarchy is set up: you trust the person that signed some router's certificate, because it was signed by the site certificate, and the site certificate was signed by the region, etc., and the $nth$ certificate was signed by the root certificate, which is your trust anchor, so you ``just trust it''. Moreover, if your trust anchor is \emph{before} their trust anchor in the ``chain'', then they will be able to trust you, but you will not be able to trust them.
+
For each site, at least one router should publish the site certificate, and at least one router should publish the certificate of the site operator.
-Each router should publish its own certificate.
+Each router should publish its own certificate. This is a matter of performance; a network would work if all certificates for all nodes were kept centrally, but distributing the certificates in this way improves performance.
All this information must be explicitly specified in the configuration file.
For example, the following configuration file indicates that NLSR should publish the site certificate and the router certificate:
@@ -73,4 +74,4 @@
cert-to-publish "$SITE_CERT_OUTPUT_FILE" ; name of the router certificate file
...
}
-\end{verbatim}
\ No newline at end of file
+\end{verbatim}
diff --git a/sync-logic.tex b/sync-logic.tex
index a07f009..e821fc5 100644
--- a/sync-logic.tex
+++ b/sync-logic.tex
@@ -2,18 +2,23 @@
\label{sec:sync-logic}
The Sync Logic Handler acts as the interface between the synchronization protocol and the NLSR application.
-The Sync Logic Handler receives notifications from the synchronization protocol when an sync update is detected, and the Sync Logic Handler then determines if the updated LSA should be retrieved.
-The Sync Logic Handler also notifies the synchronization protocol when the router's LSAs are modified or refreshed, so the synchronization protocol can update its internal digest and synchronize the updated information.
+The Sync Logic Handler receives notifications from the synchronization protocol when another router updates an LSA, where an update can be modification of the contents of the LSA, or just incrementing the sequence number to refresh it. The Sync Logic Handler then determines if the updated LSA should be retrieved. The Sync Logic Handler is also how NLSR notifies the sync protocol when its own LSAs are updated.
\subsection{On Sync Update}
-When the synchronization protocol receives a sync update, the updated names and sequence numbers will be passed to \texttt{SyncLogicHandler::onNsyncUpdate()}.
-The Sync Logic Handler will process each updated name individually first by verifying that the update is not for one of the router's own LSAs.
-The Sync Logic Handler will then check the updated sequence number to see which LSAs were updated.
-If the sequence number for the LS in the update is greater than the sequence number of the existing LSA in the LSDB or there is no LSA for the updated Name,
-the Sync Logic Handler will use the \texttt{Lsdb::expressInterest()} interface to retrieve the LSA. The module will not try to retrive Coordinate LSA if link-state routing is on, or Adjacency LSA is hyperbolic routing is on.
-The logic used to express an LSA Interest and handle an LSA Data response is handled by the LSDB module (Section~\ref{sec:lsdb}).
+When the sync protocol receives an update, the procedure roughly is this:
+\begin{itemize}
+\item For each name in the update:
+\item Check that the sequence number in the LSA is newer than the one stored in the LSDB.
+\item If so, tell the LSDB to fetch this new LSA. The LSDB will finish processing.
+\end{itemize}
+
+When the synchronization protocol receives a sync update, which may contain multiple distinct items, the names and sequence numbers of each item will be passed to \texttt{SyncLogicHandler::onNsyncUpdate()}.
+%% This may not be necessary. It is currently true, though.
+% The Sync Logic Handler will process each updated name individually first by verifying that the update is not for one of the router's own LSAs.
+Since other syncs in the network blindly transmit what they think is new, we need to check that it's new \emph{to us}, and we use the LSA sequence number to do that. The higher sequence number of the locally-stored LSA with the same name as in the update and the sequence number in the update is taken to be the newer one, noting that an absent LSA has a sequence number of 0.
+If the update is found to be newer, the Sync Logic Handler will call \texttt{Lsdb::expressInterest()}, which attempts to fetch the LSA represented by the update. Other LSDB methods will finish processing and installing the new LSA. (Section~\ref{sec:lsdb})
\subsection{Publish Routing Update}
\label{sssec:routing-update}
-When any of a router's LSAs are updated or refreshed by the LSDB, the LSDB will use the \\ \texttt{SyncLogicHandler::publishRoutingUpdate()} interface to notify the synchronization protocol that the sequence number for the router's LSA prefix has changed.
-The Sync Logic Handler will also write the updated sequence number to file, so that a restarting router can begin publishing routing updates with sequence numbers larger than the sequence numbers it had published previously.
+When any of a router's LSAs are updated or refreshed by the LSDB, the LSDB will use the \\ \texttt{SyncLogicHandler::publishRoutingUpdate()} method to notify the sync protocol that the sequence number for that LSA has changed.
+The Sync Logic Handler will also write the updated sequence number to file, so that a restarting router can continue publishing routing updates with sequence numbers larger than the sequence numbers it had published before. This is only an optimization. If a router were to reset its sequence number to 1, other routers would initially reject these LSAs as not being new. However, the LSAs in their LSDBs would eventually expire, since they are not being refreshed anymore. Once those LSAs expire, the LSAs that the restarted router is publishing would then be considered new. However, this process could take quite a while, so we optimize by resuming numbering where we left off.