docs: Adding README and details NLSR instructions
Change-Id: I038c7a07858a26ed97e64e98c259ad1fcc41c4b8
diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md
new file mode 100644
index 0000000..e8315e1
--- /dev/null
+++ b/docs/GETTING-STARTED.md
@@ -0,0 +1,44 @@
+Getting Started with NLSR
+=============================================
+
+Getting Source
+--------------
+
+- [Github NLSR repository](https://github.com/named-data/NLSR)
+
+Installation instruction
+------------------------
+
+- [Installation](https://github.com/named-data/NLSR/blob/master/docs/INSTALL.md)
+
+Installing
+----------
+
+To install NLSR from source:
+
+- Install ndn-cxx according to [ndn-cxx installation instructions](http://named-data.net/doc/ndn-cxx/0.1.0/INSTALL.html)
+- Install nfd according to [nfd installation instructions](http://named-data.net/doc/NFD/current/INSTALL.html)
+- Install NLSR following [these instructions](https://github.com/named-data/NLSR/blob/master/docs/INSTALL.md)
+
+Configuration
+-------------
+
+After installing NLSR from source, you need to create a configuration file for
+NLSR. Please take a look at [nlsr.conf](https://github.com/named-data/NLSR/blob/master/nlsr.conf)
+for a sample configuration. For details on configuring a router, please refer to
+[build network topology](https://github.com/named-data/NLSR/blob/master/docs/TOPOLOGY.md)
+and for security configuration please refer to
+[NLSR's security configuration](https://github.com/named-data/NLSR/blob/master/docs/SECURITY.md)
+
+Running
+-------
+
+Run nlsr with the following command:
+
+ nlsr
+
+NLSR will look for the default configuration file, nlsr.conf, in the current directory.
+
+You can also run nlsr -f options as follows with the absolute path of the configuration file:
+
+ nlsr -f /nlsr/nlsr.conf
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
new file mode 100644
index 0000000..1235e89
--- /dev/null
+++ b/docs/INSTALL.md
@@ -0,0 +1,61 @@
+NLSR Installation Instructions
+=============================
+
+Prerequisites
+-------------
+
+- [ndn-cxx library](https://github.com/named-data/ndn-cxx) and its requirements:
+
+ libcrypto
+ libsqlite3
+ libcrypto++
+ pkg-config
+ Boost libraries (>= 1.48)
+ OSX Security framework (on OSX platform only)
+
+ Refer to [Getting started with ndn-cxx](http://named-data.net/doc/ndn-cxx/current/INSTALL.html) -for detailed installation instructions of the library.
+
+
+- [NFD](https://github.com/named-data/nfd) and its requirements:
+
+ Refer to [Getting started with NFD ](http://named-data.net/doc/NFD/current/getting-started.html)-for detailed installation and running instruction.
+
+
+- log4cxx library
+
+ On linux variants
+
+ sudo apt-get install liblog4cxx10-dev
+
+ On Mac OSx
+
+ sudo port install log4cxx
+
+- protobuf
+
+ On Mac OSx
+
+ sudo port install protobuf-cpp
+
+ On linux variants
+
+ sudo apt-get install libprotobuf-dev
+
+
+Build
+-----
+
+The following commands should be used to build NLSR:
+
+ ./waf configure
+ ./waf
+ sudo ./waf install
+
+Refer to ./waf --help for more options that can be used during configure stage and
+how to properly configure and run NLSR.
+
+If your pkgconfig path is not set properly you can do following before running `./waf configure`
+
+ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
+ or
+ export PKG_CONFIG_PATH=/path/to/pkgconfig/in/your/machine
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
new file mode 100644
index 0000000..c15dd60
--- /dev/null
+++ b/docs/SECURITY.md
@@ -0,0 +1,283 @@
+##Trust Model For NLSR
+
+The trust model of NLSR is semi-hierarchical.
+An example certificate signing hierarchy is:
+
+ root
+ |
+ +--------------+---------------+
+ site1 site2
+ | |
+ +---------+---------+ +
+ operator1 operator2 operator3
+ | | |
+ +-----+-----+ +----+-----+ +-----+-----+--------+
+ router1 router2 router3 router4 router5 router6 router7
+ | | | | | | |
+ + + + + + + +
+ NLSR NSLR NSLR NSLR NSLR NSLR NSLR
+
+Each entity's name and corresponding certificate name follow the convention below:
+
+ Entity | Identity Name | Example | Certificate Name Example
+ -------- | ------------------------------------------------- | ------------------------------- | -----------------------------------------------
+ root | /\<network\> | /ndn | /ndn/KEY/ksk-1/ID-CERT/%01
+ site | /\<network\>/\<site\> | /ndn/edu/ucla | /ndn/edu/ucla/KEY/ksk-2/ID-CERT/%01
+ operator | /\<network\>/\<site\>/%C1.Operator/\<operator-name\> | /ndn/edu/ucla/%C1.Operator/op1 | /ndn/edu/ucla/%C1.Operator/op1/KEY/ksk-3/ID-CERT/%01
+ router | /\<network\>/\<site\>/%C1.Router/\<router-name\> | /ndn/edu/ucla/%C1.Router/rt1 | /ndn/edu/ucla/%C1.Router/rt1/KEY/ksk-4/ID-CERT/%01
+ NLSR | /\<network\>/\<site\>/%C1.Router/\<router-name\>/NLSR | /ndn/edu/ucla/%C1.Router/rt1/NLSR | /ndn/edu/ucla/%C1.Router/rt1/NLSR/KEY/ksk-5/ID-CERT/%01
+
+Users should create keys according to the naming and signing hierarchies above.
+
+## Certificate Publishing
+
+In a network, every router should have the root certificate configured as a trust anchor.
+For each site, at least one router should publish the site certificate, at least one router should publish the certificate of the site operator.
+Each router should publish its own certificate.
+All this information should be explicitly specified in nlsr.conf file.
+For example, the following configuration file indicates that NLSR should publish the site certificate and the router certificate:
+
+ ...
+ security
+ {
+ validator
+ {
+ ...
+ }
+ cert-to-publish "site.cert" ; name of the file which contains the site certificate (optional).
+ cert-to-publish "router.cert" ; name of the file which contains the router certificate (required).
+ }
+
+Note that when a new NLSR instance is created, it will create a new key for the instance; generating the certificate for the new NLSR key is handled internally in NLSR.
+Therefore, user does not have to explcitly create keys and certificate for each NLSR instance.
+
+For key and certificate generation, please refer to the [ndnsec tool kit](http://named-data.net/doc/ndn-cxx/0.1.0/manpages/ndnsec.html).
+
+## Example
+
+Security Configuration: Every machine in network will have the same set of security rules to configure.
+However, different machine will have different configuration commands "cert-to-publish"
+depending on responsibility. Let us use the same topology used for example(https://github.com/named-data/NLSR/blob/master/docs/TOPOLOGY.md).
+
+ndnsec-key-gen generates a key
+
+Lets assume that `/ndn/memphis.edu/router1` is the router who is responsible as the memphis
+site router and also responsible as root which is the trust anchor of the network. So
+router in memphis will do the following key creation and signing.
+
+NOTE: The first two steps may not apply to everyone as the root certificate and the site certificate are usually present at a testbed outside the scope of NLSR. These steps will help if you are testing an isolated testbed.
+
+ 1. Create root key and self signed certificate with prefis `/ndn`
+ $ndnsec-key-gen -n /ndn
+ $ndnsec-sign-req /ndn > root.cert
+ This root.cert will be configured by "cert-to-publish" commands in nlsr.conf
+
+ 2. Generate key for site prefix `/ndn/edu/memphis` and sign it by root key
+ $ndnsec-key-gen -n /ndn/edu/memphis > unsigned_site.cert
+ $ndnsec-cert-gen -S 20140701000000 -E 20150701000000 -N "University of Memphis"
+ -s /ndn -p /ndn/edu/memphis -r unsigned_site.cert > site.cert
+
+ 3. Generate key for operator and sign it by memphis site key. Lets assume that
+ operator name in Memphis site is ndnuser, so the prefix is `/ndn/edu/memphis/%C1.O.N./ndnuser`
+ $ndnsec-key-gen -n /ndn/edu/memphis/%C1.Operator/ndnuser > unsigned_operator.cert
+ $ndnsec-cert-gen -S 20140701000000 -E 20150701000000 -N "University of Memphis Operator"
+ -s /ndn/edu/memphis -p /ndn/edu/memphis/%C1.Operator/ndnuser
+ -r unsigned_operator.cert > operator.cert
+
+ 4. Generate key for router and sign it with operator's key
+ $ndnsec-key-gen /ndn/edu/memphis/%C1.Router/router1 > unsigned_router.cert
+ $ndnsec-cert-gen -S 20140701000000 -E 20150701000000 -N "University of Memphis Router"
+ -s /ndn/edu/memphis/%C1.Operator/ndnuser -p /ndn/edu/memphis/%C1.Router/router1
+ -r unsigned_router.cert > router.cert
+
+
+Key creation and signing is done for `/ndn/memphis.edu/router1`. In nlsr.conf
+this router will have this lines
+
+ cert-to-publish "root.cert"
+ cert-to-publish "site.cert"
+ cert-to-publish "operator.cert"
+ cert-to-publish "router.cert"
+
+Here is the entire security configuraion of the router1 (As seen in nlsr.conf. Note that only the semi-colons before the certs have been removed, rest is same)
+
+ security
+ {
+ validator
+ {
+ rule
+ {
+ id "NSLR Hello Rule"
+ for data
+ filter
+ {
+ type name
+ regex ^[^<NLSR><INFO>]*<NLSR><INFO><><>$
+ }
+ checker
+ {
+ type customized
+ sig-type rsa-sha256
+ key-locator
+ {
+ type name
+ hyper-relation
+ {
+ k-regex ^([^<KEY><NLSR>]*)<NLSR><KEY><ksk-.*><ID-CERT>$
+ k-expand \\1
+ h-relation equal
+ p-regex ^([^<NLSR><INFO>]*)<NLSR><INFO><><>$
+ p-expand \\1
+ }
+ }
+ }
+ }
+
+ rule
+ {
+ id "NSLR LSA Rule"
+ for data
+ filter
+ {
+ type name
+ regex ^[^<NLSR><LSA>]*<NLSR><LSA>
+ }
+ checker
+ {
+ type customized
+ sig-type rsa-sha256
+ key-locator
+ {
+ type name
+ hyper-relation
+ {
+ k-regex ^([^<KEY><NLSR>]*)<NLSR><KEY><ksk-.*><ID-CERT>$
+ k-expand \\1
+ h-relation equal
+ p-regex ^([^<NLSR><LSA>]*)<NLSR><LSA>(<>*)<><><>$
+ p-expand \\1\\2
+ }
+ }
+ }
+ }
+
+ rule
+ {
+ id "NSLR Hierarchy Exception Rule"
+ for data
+ filter
+ {
+ type name
+ regex ^[^<KEY><%C1.Router>]*<%C1.Router>[^<KEY><NLSR>]*<KEY><ksk-.*><ID-CERT><>$
+ }
+ checker
+ {
+ type customized
+ sig-type rsa-sha256
+ key-locator
+ {
+ type name
+ hyper-relation
+ {
+ k-regex ^([^<KEY><%C1.Operator>]*)<%C1.Operator>[^<KEY>]*<KEY><ksk-.*><ID-CERT>$
+ k-expand \\1
+ h-relation equal
+ p-regex ^([^<KEY><%C1.Router>]*)<%C1.Router>[^<KEY>]*<KEY><ksk-.*><ID-CERT><>$
+ p-expand \\1
+ }
+ }
+ }
+ }
+
+ rule
+ {
+ id "NSLR Hierarchical Rule"
+ for data
+ filter
+ {
+ type name
+ regex ^[^<KEY>]*<KEY><ksk-.*><ID-CERT><>$
+ }
+ checker
+ {
+ type hierarchical
+ sig-type rsa-sha256
+ }
+ }
+
+ trust-anchor
+ {
+ type file
+ file-name "root.cert"
+ }
+ }
+ cert-to-publish "root.cert" //optional, a file containing the root certificate. only the router
+ //that is designated to publish root cert needs to specify this
+ cert-to-publish "site.cert" //optional, a file containing the root certificate. only the router
+ //that is designated to publish site cert need to specify this
+ cert-to-publish "operator.cert" //optional, a file containing the root certificate. only the
+ //router that is designated to publish operator cert need to
+ //specify this
+ cert-to-publish "router.cert" //required, a file containing the router certificate.
+ }
+
+Now lets see how `/ndn/colostate.edu/router2` will create and sign keys. Let assume
+that this router is responsible for hosting site keys and operator keys of colorado
+site.
+
+ 2. Generate key for site prefix `/ndn/edu/colorado`
+ $ndnsec-key-gen -n /ndn/edu/memphis > unsigned_site.cert
+
+ Send this cert to Memphis site ( as in example Memphis is the root) and get
+ it signed by root. After you get back the site please put it in your convenient
+ certificate directory.
+
+ 3. Generate key for operator and sign it by colorado site key. Lets assume that
+ operator name in Colorado site is testop, so the prefix is `/ndn/edu/colorado/%C1.O.N./testop`
+ $ndnsec-key-gen -n /ndn/edu/colorado/%C1.Operator/testop > unsigned_operator.cert
+ $ndnsec-cert-gen -S 20140701000000 -E 20150701000000 -N "Colorado State University Operator"
+ -s /ndn/edu/colorado -p /ndn/edu/colorado/%C1.Operator/testop
+ -r unsigned_operator.cert > operator.cert
+
+ 4. Generate key for router and sign it with operator's key
+ $ndnsec-key-gen /ndn/edu/colorado/%C1.Router/router2 > unsigned_router.cert
+ $ndnsec-cert-gen -S 20140701000000 -E 20150701000000 -N "Colorado State University Router"
+ -s /ndn/edu/colorado/%C1.Operator/testop -p /ndn/edu/colorado/%C1.Router/router2
+ -r unsigned_router.cert > router.cert
+
+
+Key creation and signing is done for `/ndn/edu/colorado/router2`. In nlsr.conf
+this router will have these lines
+
+ cert-to-publish "site.cert"
+ cert-to-publish "operator.cert"
+ cert-to-publish "router.cert"
+
+(The rest of the security configuration is same as the other router.)
+
+Colorado also need to bring the root.cert from Memphis and put it in the certificate
+directory as it is configured as trust anchor.
+
+Now both Memphis and Colorado router is ready to run with security configuration.
+Arizona router will follow the same step as Colorado to configure security for NLSR.
+
+
+# Disabling Security in NLSR
+
+To disable packet validation in NLSR, you need to change the configuration file
+in section: security.validator.trust-anchor
+
+ trust-anchor
+ {
+ type file
+ file-name "root.cert"
+ }
+
+change the previous section in security configuration to below
+
+ trust-anchor
+ {
+ type any
+ }
+
+With this change, packets are still signed, but validation will be skipped.
diff --git a/docs/TOPOLOGY.md b/docs/TOPOLOGY.md
new file mode 100644
index 0000000..c542de2
--- /dev/null
+++ b/docs/TOPOLOGY.md
@@ -0,0 +1,193 @@
+Example network and sample configuration:
+=========================================
+
+Lets assume that three routers in the same network but at three different sites (
+memphis.edu, arizona.edu, and colostate.edu) are connected to each other to
+construct the following topology:
+
+ -------------------------------------
+ | /ndn/edu/memphis/%C1.Router/router1 |
+ -------------------------------------
+ / 11 12\
+ / \
+ route-cost = 25 / \ route-cost = 30
+ / \
+ 17 / \ 13
+ ------------------------------------- 7 10 --------------------------------------
+ |/ndn/edu/arizona/%C1.Router/router3|-------------------|/ndn/edu/colostate/%C1.Router/router2|
+ ------------------------------------- route-cost = 28 --------------------------------------
+
+ Figure: Network Topology
+
+The number represents the connecting face id. For example, `/ndn/edu/memphis/%C1.Router/router1`
+is connected to `/ndn/edu/arizona/%C1.Router/router3` via face 11 and the route cost is 25.
+To reach `/ndn/edu/colostate/%C1.Router/router2` via face 12, the route cost is 30.
+
+We will walk through setting up the faces and creating the configuration file for
+`/ndn/edu/memphis/%C1.Router/router1`.
+
+Step 1. Ensure nfd is running :
+----------------
+Type the following in the terminal:
+
+ "nfd-status -f"
+
+
+if you see `ERROR: error while connecting to the forwarder (No such file or directory)`
+message that means nfd is not running. Follow the instructions in [Getting started with NFD ](http://named-data.net/doc/NFD/current/getting-started.html) to run nfd.
+
+Step 2. Determining FaceUri:
+--------------------
+Lets assume that `/ndn/edu/arizona/%C1.Router/router3` has hostname `router3.arizona.edu`
+and `/ndn/edu/colostate/%C1.Router/router2` has ip address `79.123.10.145`, and that all
+routers in the network had agreed to sync data in name prefix `/ndn/nlsr/sync`.
+`/ndn/edu/memphis/%C1.Router/router1` will consider face uri `udp4://router3.arizona.edu` for
+router `/ndn/edu/arizona/%C1.Router/router3` and face uri `udp4://79.123.10.145` for router
+`/ndn/edu/colostate/%C1.Router/router2`.
+
+Step 3: Creating configuration file:
+------------------------------------
+Now, lets assume that /ndn/memphis.edu/router1 wants to advertise three name
+prefixes that can be reached through it ( `/ndn/memphis/sports/basketball/grizzlies`,
+`/ndn/memphis/entertainment/blues`, `/ndn/news/memphis/politics/lutherking`). Now,
+the configuration file with minimum configuration commands will have the following
+commands
+
+ ; nlsr.conf starts here
+ ; the general section contains all the general settings for router
+
+ general
+ {
+ ; mandatory configuration command section network, site and router
+
+ network /ndn/ ; name of the network the router belongs to in ndn URI format
+ site /edu/memphis/ ; name of the site the router belongs to in ndn URI format
+ router /%C1.Router/router1 ; name of the network the router belongs to in ndn URI format
+
+ ; lsa-refresh-time is the time in seconds, after which router will refresh its LSAs
+
+ lsa-refresh-time 1800 ; default value 1800. Valid values 240-7200
+
+ ; log-level is to set the levels of log for NLSR
+
+ log-level INFO ; default value INFO, valid value DEBUG, INFO
+ log-dir /var/log/nlsr/
+ seq-dir /var/lib/nlsr/
+ }
+
+ ; the neighbors section contains the configuration for router's neighbors and hello's behavior
+
+ neighbors
+ {
+ ; in case hello interest timed out, router will try 'hello-retries' times at 'hello-time-out'
+ ; seconds interval before giving up for any neighbors (deciding link is down)
+
+ hello-retries 3 ; interest retries number in integer. Default value 3
+ ; valid values 1-10
+
+ hello-timeout 1 ; interest time out value in integer. Default value 1
+ ; Valid values 1-15
+
+ hello-interval 60 ; interest sending interval in seconds. Default value 60
+ ; valid values 30-90
+ ; neighbor command is used to configure router's neighbor. Each neighbor will need
+ ; one block of neighbor command
+
+ neighbor
+ {
+ name /ndn/edu/arizona/%C1.Router/router3 ; name prefix of the neighbor router consists
+ ; of network, site-name and router-name
+
+ face-uri udp4://router3.arizona.edu ; face uri of the face connected to the neighbor
+ link-cost 25 ; cost of the connecting link to neighbor
+ }
+
+ neighbor
+ {
+ name /ndn/edu/colostate/%C1.Router/router2 ; name prefix of the neighbor router consists
+ ; of network, site-name and router-name
+
+ face-uri udp4://79.123.10.145 ; face uri of the face connected to the neighbor
+ link-cost 30 ; cost of the connecting link to neighbor
+ }
+ }
+
+ ; the hyperbolic section contains the configuration settings of enabling a router to calculate
+ ; routing table using [hyperbolic routing table calculation](http://arxiv.org/abs/0805.1266) method
+
+ hyperbolic
+ {
+ ; commands in this section follows a strict order
+ ; the switch is used to set hyperbolic routing calculation in NLSR
+
+ state off ; default value 'off', set value 'on' to enable hyperbolic routing table
+ ; calculation which turns link state routing 'off'. set value to 'dry-run"
+ ; to test hyperbolic routing and compare with link state routing.
+
+
+ radius 123.456 ; radius of the router in hyperbolic coordinate system
+ angle 1.45 ; angle of the router in hyperbolic coordinate system
+ }
+
+
+ ; the fib section is used to configure fib entry's type to ndn FIB updated by NLSR
+
+ fib
+ {
+ ; the max-faces-per-prefix is used to limit the number of faces for each name prefixes
+ ; by NLSR in ndn FIB
+
+ max-faces-per-prefix 3 ; default value 0. Valid value 0-60. By default (value 0) NLSR adds
+ ; all available faces for each reachable name prefixes in NDN FIB
+
+ }
+
+ ; the advertising section contains the configuration settings of the name prefixes
+ ; hosted by this router
+
+ advertising
+ {
+ ; the ndnname is used to advertised name from the router. To advertise each name prefix
+ ; configure one block of ndnname configuration command for every name prefix.
+
+ prefix /ndn/memphis/sports/basketball/grizzlies
+ prefix /ndn/memphis/entertainment/blues
+ prefix /ndn/news/memphis/politics/lutherking
+ }
+
+ ; security configuration is discussed
+ ;[NLSR's security configuration](https://github.com/named-data/NLSR/blob/master/docs/SECURITY.md)
+ ; which will be also part of this configuration file here
+ ;
+ ; nlsr.conf end here
+
+Step 4: Running NLSR in /ndn/memphis.edu/router1:
+-------------------------------------------------
+Assuming the configuration file is saved as nlsr.conf. Type the following to run
+nlsr
+
+ $ nlsr -f nlsr.conf
+
+NLSR will look for nlsr.conf in the current directory. If nlsr.conf is not in
+the corrent directory, please provide the absolute path with the file name as the
+value. If nlsr.conf resides in /home/ndnuser/configuration directory, type "nlsr
+-f /home/ndnuser/configuration/nlsr.conf" to run nlsr.
+
+The same process needs to be followed for router /ndn/arizona.edu/router3 and
+/ndn/colostate.edu/router2 to run NLSR on these routers.
+
+Expected Output:
+----------------
+Assuming that all three routers are configured correctly and converged, nfd-status
+in `/ndn/edu/colostate/%C1.Router/router2` will have the following entries for the
+name advertised by `/ndn/edu/memphis/%C1.Router/router1`. This output can be
+seen by typing `nfd-status -f` in terminal
+
+FIB:
+
+ /ndn/memphis/sports/basketball/grizzlies nexthops={faceid=17 (cost=25), faceid=7 (cost=58)}
+ /ndn/memphis/entertainment/blues nexthops={faceid=17 (cost=25), faceid=7 (cost=58)}
+ /ndn/news/memphis/politics/lutherking nexthops={faceid=17 (cost=25), faceid=7 (cost=58)}
+
+Please refer to the network figure for face id. Numbers at the end of each link
+correspond to face ids.