docs: Adding installation instructions and configuration tips
README.md and INSTALL.md now redirect to documentation in docs/ folder.
Later we will add links to HTML pages with NFD documentation.
Change-Id: I4f02f3166e7802570b24ed225ac4de8c56c6e64e
Refs: #1446
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
new file mode 100644
index 0000000..2c74157
--- /dev/null
+++ b/docs/INSTALL.rst
@@ -0,0 +1,109 @@
+.. _NFD Installation Instructions:
+
+NFD Installation Instructions
+=============================
+
+Prerequisites
+-------------
+
+- `ndn-cpp-dev library <https://github.com/named-data/ndn-cpp-dev>`__
+ and its requirements:
+
+ - ``libcrypto``
+ - ``libsqlite3``
+ - ``libcrypto++``
+ - ``pkg-config``
+ - Boost libraries (>= 1.48)
+ - OSX Security framework (on OSX platform only)
+
+ Refer to https://github.com/named-data/ndn-cpp-dev/blob/master/INSTALL.md for detailed
+ installation instructions.
+
+- ``libpcap``
+
+ Comes with base on OS X 10.8 and 10.9:
+
+ On Ubuntu >= 12.04:
+
+ ::
+
+ sudo apt-get install libpcap-dev
+
+To build manpages and API documentation:
+
+- ``doxygen``
+- ``graphviz``
+- ``python-sphinx``
+
+ On OS X 10.8 and 10.9 with macports:
+
+ ::
+
+ sudo port install doxygen graphviz py27-sphinx sphinx_select
+ sudo port select sphinx py27-sphinx
+
+ On Ubuntu >= 12.04:
+
+ ::
+
+ sudo apt-get install doxygen graphviz python-sphinx
+
+Build
+-----
+
+The following commands should be used to build NFD:
+
+::
+
+ ./waf configure
+ ./waf
+ sudo ./waf install
+
+Refer to :ref:`NFD Configuration Tips` (``README.rst``) for more options that can be used
+during ``configure`` stage and how to properly configure and run NFD.
+
+In some configurations, configuration step may require small modification. For example, on
+OSX that uses macports (correct the path if macports was not installed in the default path
+``/opt/local``):
+
+::
+
+ export PKG_CONFIG_PATH=/opt/local/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/lib/pkgconfig:$PKG_CONFIG_PATH
+ ./waf configure
+ ./waf
+ sudo ./waf install
+
+On some Linux distributions (e.g., Fedora 20):
+
+::
+
+ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig:/usr/lib64/pkgconfig:$PKG_CONFIG_PATH
+ ./waf configure
+ ./waf
+ sudo ./waf install
+
+Building documentation
+----------------------
+
+NFD tutorials and API documentation can be built using the following commands:
+
+::
+
+ # Full set of documentation (tutorials + API) in build/docs
+ ./waf docs
+
+ # Only tutorials in `build/docs`
+ ./waf sphinx
+
+ # Only API docs in `build/docs/doxygen`
+ ./waf doxgyen
+
+
+Manpages are automatically created and installed during the normal build process
+(e.g., during ``./waf`` and ``./waf install``), if ``python-sphinx`` module is detected
+during ``./waf configure`` stage. By default, manpages are installed into
+``${PREFIX}/share/man`` (where default value for ``PREFIX`` is ``/usr/local``). This
+location can be changed during ``./waf configure`` stage using ``--prefix``,
+``--datarootdir``, or ``--mandir`` options.
+
+For more details, refer to ``./waf --help``.
diff --git a/docs/README.rst b/docs/README.rst
new file mode 100644
index 0000000..7788bb5
--- /dev/null
+++ b/docs/README.rst
@@ -0,0 +1,124 @@
+.. _NFD Configuration Tips:
+
+NFD - Named Data Networking Forwarding Daemon
+=============================================
+
+Default Paths
+-------------
+
+This document uses ``SYSCONFDIR`` when referring to the default locations
+of various NFD configuration files. By default, ``SYSCONFDIR`` is set to
+``/usr/local/etc``. If you override ``PREFIX``, then ``SYSCONFDIR`` will
+default to ``PREFIX/etc``.
+
+You may override ``SYSCONFDIR`` and ``PREFIX`` by specifying their
+corresponding options during installation:
+
+::
+
+ ./waf configure --prefix <path/for/prefix> --sysconfdir <some/other/path>
+
+Refer to :ref:`NFD Installation Instructions` for more detailed instructions on how to compile
+and install NFD.
+
+Running and Configuring NFD
+---------------------------
+
+NFD's runtime settings may be modified via configuration file. After
+installation, a working sample configuration is provided at
+``SYSCONFDIR/ndn/nfd.conf.sample``. At startup, NFD will attempt to read
+the default configuration file location: ``SYSCONFDIR/ndn/nfd.conf``.
+
+You may also specify an alternative configuration file location by
+running NFD with:
+
+::
+
+ nfd --config </path/to/nfd.conf>
+
+Once again, note that you may simply copy or rename the provided sample
+configuration and have an **almost** fully configured NFD. However, this
+NFD will be unable to add FIB entries or perform other typical operation
+tasks until you authorize an NDN certificate with the appropriate
+privileges.
+
+Installing an NDN Certificate for Command Authentication
+--------------------------------------------------------
+
+Many NFD management protocols require signed commands to be processed
+(e.g. FIB modification, Face creation/destructions, etc.). You will need
+an NDN certificate to use any application that issues signed commands.
+
+If you do not already have NDN certificate, you can generate one with
+the following commands:
+
+**Generate and install a self-signed identity certificate**:
+
+::
+
+ ndnsec-keygen /`whoami` | ndnsec-install-cert -
+
+Note that the argument to ndnsec-key will be the identity name of the
+new key (in this case, ``/your-username``). Identity names are
+hierarchical NDN names and may have multiple components (e.g.
+``/ndn/ucla/edu/alice``). You may create additional keys and identities
+as you see fit.
+
+**Dump the NDN certificate to a file**:
+
+The following commands assume that you have not modified ``PREFIX`` or
+``SYSCONFDIR`` If you have, please substitute ``/usr/local/etc`` for the
+appropriate value (the overriden ``SYSCONFDIR`` or ``PREFIX/etc`` if you
+changed ``PREFIX``).
+
+::
+
+ sudo mkdir -p /usr/local/etc/ndn/keys
+ ndnsec-cert-dump -i /`whoami` > default.ndncert
+ sudo mv default.ndncert /usr/local/etc/ndn/keys/default.ndncert
+
+Running NFD with Ethernet Face Support
+--------------------------------------
+
+The ether configuration file section contains settings for Ethernet
+faces and channels. These settings will **NOT** work without root or
+setting the appropriate permissions:
+
+::
+
+ sudo setcap cap_net_raw,cap_net_admin=eip /full/path/nfd
+
+You may need to install a package to use setcap:
+
+**Ubuntu:**
+
+::
+
+ sudo apt-get install libcap2-bin
+
+**Mac OS X:**
+
+::
+
+ curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz
+ tar zxvf ChmodBPF.tar.gz
+ open ChmodBPF/Install\ ChmodBPF.app
+
+or manually:
+
+::
+
+ sudo chgrp admin /dev/bpf*
+ sudo chmod g+rw /dev/bpf*
+
+UDP multicast support in multi-homed Linux machines
+---------------------------------------------------
+
+The UDP configuration file section contains settings for unicast and multicast UDP
+faces. If the Linux box is equipped with multiple network interfaces with multicast
+capabilities, the settings for multicast faces will **NOT** work without root
+or setting the appropriate permissions:
+
+::
+
+ sudo setcap cap_net_raw=eip /full/path/nfd
diff --git a/docs/index.rst b/docs/index.rst
index 6bc1fff..385a657 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,9 +1,11 @@
NFD - Named Data Networking Forwarding Daemon's documentation
=============================================================
-Contents:
-
.. toctree::
release_notes
+ Installation Instruction <INSTALL>
+ NFD Configuration Tips <README>
manpages
- :maxdepth: 2
+ :maxdepth: 1
+
+* `API documentation (doxygen) <doxygen/annotated.html>`_
diff --git a/docs/manpages.rst b/docs/manpages.rst
index ff5630a..9690f11 100644
--- a/docs/manpages.rst
+++ b/docs/manpages.rst
@@ -6,3 +6,4 @@
manpages/nrd
manpages/ndn-autoconfig
manpages/ndn-autoconfig-server
+ :maxdepth: 1
diff --git a/docs/named_data_theme/static/base.css_t b/docs/named_data_theme/static/base.css_t
index 93fa4e1..ea6938e 100644
--- a/docs/named_data_theme/static/base.css_t
+++ b/docs/named_data_theme/static/base.css_t
@@ -17,7 +17,7 @@
/* Page layout */
div.header, div.content, div.footer {
- width: {{ theme_pagewidth }};
+ width: 90%;
margin-left: auto;
margin-right: auto;
}
@@ -159,13 +159,13 @@
}
div.document {
- width: {{ theme_documentwidth }};
+ width: 70%;
float: left;
}
div.body {
padding-right: 2em;
- text-align: {{ theme_textalign }};
+ text-align: left;
}
div.document h1 {
@@ -236,7 +236,7 @@
/* Sidebar */
div.sidebar {
- width: {{ theme_sidebarwidth }};
+ width: 20%;
float: right;
font-size: .9em;
}
@@ -453,3 +453,11 @@
border-top: 1px solid #ac9;
border-bottom: 1px solid #ac9;
}
+
+td.linenos pre {
+ padding: 5px 0px;
+ border: 0;
+ background-color: transparent;
+ color: #aaa;
+ margin-top: -10pt;
+}
\ No newline at end of file
diff --git a/docs/named_data_theme/static/named_data_style.css_t b/docs/named_data_theme/static/named_data_style.css_t
index 0d00020..f37be7f 100644
--- a/docs/named_data_theme/static/named_data_style.css_t
+++ b/docs/named_data_theme/static/named_data_style.css_t
@@ -10,7 +10,7 @@
padding: 10px;
background-color: #fafafa;
color: #222;
- line-height: 1.0em;
+ /* line-height: 1.0em; */
border: 2px solid #C6C9CB;
font-size: 0.9em;
/* margin: 1.5em 0 1.5em 0; */
diff --git a/docs/named_data_theme/theme.conf b/docs/named_data_theme/theme.conf
index 1dab97e..aa5a7ff 100644
--- a/docs/named_data_theme/theme.conf
+++ b/docs/named_data_theme/theme.conf
@@ -6,6 +6,9 @@
theme_bodyfont = "normal 12px Verdana, sans-serif"
theme_bgcolor = "#ccc"
+theme_documentwidth = "100%"
+theme_textalign = "left"
+
[options]
stickysidebar = true