Release notes

- migrated from wiki
- updated versions to current version

- notes are built with each regular build
- notes root is at: target/generated-docs/release_notes.html
- notes are inlined into site

Change-Id: I581898988f41f77f5eafb20e9e61e08f09908b98
Signed-off-by: Maros Marsalek <mmarsale@cisco.com>

4 files changed, 262 insertions, 0 deletions

diff --git a/release-notes/src/main/asciidoc/user_guide/user_guide.adoc b/release-notes/src/main/asciidoc/user_guide/user_guide.adoc
new file mode 100644
index 000000000..494f2d241
--- /dev/null
+++ b/release-notes/src/main/asciidoc/user_guide/user_guide.adoc
@@ -0,0 +1,48 @@
+== User guide
+
+=== Running Honeycomb
+link:user_running_honeycomb.html[Running Honeycomb]
+
+=== Troubleshooting
+link:user_troubleshooting.html[Troubleshooting]
+
+=== Honeycomb and ODL
+link:user_honeycomb_and_ODL.html[Mounting Honeycomb in ODL]
+
+=== Configuration files
+Honeycomb's configuration files present within its distribution:
+
+* Honeycomb infra:
+** {project-git-web}/infra/minimal-distribution/src/main/resources/honeycomb-minimal-resources/config/honeycomb.json?h={project-branch}[Honeycomb base configuration]
+* Honeycomb vpp plugins commons:
+** {project-git-web}/vpp-common/minimal-distribution/src/main/resources/honeycomb-minimal-resources/config/jvpp.json?h={project-branch}[VPP plugins common configuration]
+* V3PO plugin:
+** {project-git-web}/v3po/v3po2vpp/src/main/resources/honeycomb-minimal-resources/config/v3po.json?h={project-branch}[V3PO plugin for Honeycomb configuration]
+* LISP plugin
+** {project-git-web}/lisp/lisp2vpp/src/main/resources/honeycomb-minimal-resources/config/lisp.json?h={project-branch}[LISP plugin for Honeycomb configuration]
+* NSH plugin:
+** {project-git-web}/nsh/impl/src/main/resources/honeycomb-minimal-resources/config/vppnsh.json?h={project-branch}[NSH_SFC plugin for Honeycomb configuration]
+
+=== YANG models
+
+* V3PO plugin
+** {project-git-web}/v3po/api/src/main/yang?h={project-branch}[V3PO YANG models]
+* LISP plugin
+** {project-git-web}/lisp/api/src/main/yang?h={project-branch}[LISP YANG models]
+* NSH plugin
+** {project-git-web}/nsh/api/src/main/yang?h={project-branch}[NSH YANG models]
+* NAT plugin
+** {project-git-web}/nat/nat-api/src/main/yang?h={project-branch}[NAT YANG models]
+* Context models
+** {project-git-web}/vpp-common/naming-context-api/src/main/yang?h={project-branch}[Context YANG models]
+
+=== POSTMAN collections
+
+* V3PO plugin
+** {project-git-web}/v3po/postman_rest_collection.json?h={project-branch}[V3PO postman collection]
+* LISP plugin
+** {project-git-web}/lisp/lisp_postman_rest_collection.json?h={project-branch}[LISP postman collection]
+* NSH plugin
+** {project-git-web}/nsh/nsh_postman_rest_collection.json?h={project-branch}[NSH postman collection]
+* NAT plugin
+** {project-git-web}/nat/postman_rest_collection.json?h={project-branch}[NAT postman collection]
diff --git a/release-notes/src/main/asciidoc/user_guide/user_honeycomb_and_ODL.adoc b/release-notes/src/main/asciidoc/user_guide/user_honeycomb_and_ODL.adoc
new file mode 100644
index 000000000..23c7e521c
--- /dev/null
+++ b/release-notes/src/main/asciidoc/user_guide/user_honeycomb_and_ODL.adoc
@@ -0,0 +1,76 @@
+= Honeycomb and ODL
+
+link:release_notes.html[< Home]
+
+Honeycomb can be managed using ODL as any NETCONF-enabled device. Please follow https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf for detailed instructions how to mount and connect to a NETCONF device
+
+== Troubleshooting
+
+Issues with Honeycomb and ODL integration
+
+=== Unable to open SSH session due to invalid crypto configuration
+
+If ODL fails to open ssh session due to InvalidAlgorithmParameterException, e.g.:
+
+[srouce]
+====
+2016-09-13 13:52:34,852 | WARN  | NioProcessor-3   | ClientSessionImpl | 180 -
+org.apache.sshd.core - 0.14.0 | Exception caught
+java.security.InvalidAlgorithmParameterException: Prime size must be multiple of 64,
+and can only range from 512 to 2048 (inclusive)
+ at com.sun.crypto.provider.DHKeyPairGenerator.initialize(DHKeyPairGenerator.java:120)
+   [sunjce_provider.jar:1.8.0_45]
+ at java.security.KeyPairGenerator$Delegate.initialize(KeyPairGenerator.java:674)
+   [:1.8.0_45-internal]
+ at java.security.KeyPairGenerator.initialize(KeyPairGenerator.java:411)
+   [:1.8.0_45-internal]
+ at org.apache.sshd.common.kex.DH.getE(DH.java:65)[180:org.apache.sshd.core:0.14.0]
+
+...
+
+2016-09-13 13:52:34,852 | DEBUG | NioProcessor-3   | ClientSessionImpl | 180 -
+org.apache.sshd.core - 0.14.0 | Closing ClientSessionImpl[admin@/127.0.0.1:2835] immediately
+====
+
+It probably means BouncyCastle provider is not properly configured/loaded on the ODL side.
+
+There are 2 solutions to this problem:
+
+==== Solution 1, HC side, less secure:
+
+First solution is to not use BouncyCastle in Honeycomb. This limits its capabilities in terms of security (using just default Java stuff), but makes it compatible with Opendaylight:
+
+As a workaround start honeycomb with (must be placed into Honeycomb's startup script)
+
+ -Dorg.apache.sshd.registerBouncyCastle=false
+
+As a result 1024 bit DH group will be used for SSH key exchange.
+
+==== Solution 2, ODL side, more secure
+Second solution is to locate mina sshd jar in ODL distribution's system folder. For Boron it is:
+
+ system/org/apache/sshd/sshd-core/0.14.0/sshd-core-0.14.0.jar
+
+Open the jar (it's just a zip archive), locate META-INF/MANIFEST.MF file, open it and update the Import-Package section. Find this piece:
+
+ org.bouncycast.openssl;version="[1.51,2)";resolution:=optional
+
+and replace it with:
+
+ org.bouncycast.openssl;version="[1.51,2)"
+
+This needs to be done before ODL is started the first time or it needs to be started with "clean" parameter.
+
+=== Background
+This issue is caused by a couple of reasons:
+
+* ODL and HC both use mina-sshd 0.14 for SSH
+* mina-sshd relies partially on bouncy-castle as a security provider
+* mina-sshd only defines bouncy-castle dependencies as optional for OSGi environment (which is not correct since there are bugs in the mina-sshd where missing bouncy-castle is just not expected, causing various problems... but that's a different topic)
+* netconf features in ODL make sure to first load bouncy-castle bundles and only then mina-sshd (in addition, bouncy-castle provider is placed in karaf's lib/ext and marked to be a security provider in karaf's etc/custom.properties)
+* however, when loading netconf features as initial features, there seems to be some sort of race condition in karaf and mina is started without bouncy-castle available, making it work only partially
+* but so far so good, everything loads and mina should just use less secure provider from Java
+* however when an SSH connection is started from ODL to e.g. Honeycomb. Mina-sshd is picking key size that's only supported by bouncy-castle (not by plain JDK) during negotiation
+* this means that if remote supports such size, mina-sshd in ODL subsequently fails, since it finds out bouncy-castle is not present and Java is unable to handle it
+
+NOTE: If loading netconf post karaf startup manually, the issue does not appear
\ No newline at end of file
diff --git a/release-notes/src/main/asciidoc/user_guide/user_running_honeycomb.adoc b/release-notes/src/main/asciidoc/user_guide/user_running_honeycomb.adoc
new file mode 100644
index 000000000..676bb1cdd
--- /dev/null
+++ b/release-notes/src/main/asciidoc/user_guide/user_running_honeycomb.adoc
@@ -0,0 +1,118 @@
+= Running Honeycomb
+
+link:release_notes.html[< Home]
+
+== Starting Honeycomb agent
+The zipped vpp-integration distribution can be started by invoking:
+
+ sudo ./vpp-integration-distribution-{project-version}/honeycomb
+
+This will start Honeycomb with all ODL dependencies and VPP translation code. It will automatically initialize vpp-jvpp to create interface between VPP and Honeycomb.
+
+If Honeycomb was installed from the RPM or DEB packages, it can be started by (make sure you start vpp first):
+
+ sudo service vpp start
+ sudo service honeycomb start
+
+The location of installed honeycomb is at /opt/honeycomb
+
+== Testing Honeycomb agent
+There are multiple ways of testing Honeycomb agent, depending on e.g. which northbound interface will be used
+
+=== Using NETCONF Northbound
+
+Netconf northbound can be easily tested manually using CLI SSH client. Initialize SSH connection by invoking:
+
+ ssh admin@localhost -p 2831 -s netconf
+
+NOTE: Using default credentials admin/admin, default port 2831 and netconf SSH channel Note: "Are you sure you want to continue connecting (yes/no)?" Answer yes
+
+Next thing to do is to provide client hello message to initialize netconf session. Following content must be copy&pasted into SSH session + hit enter:
+
+[source,xml]
+----
+<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+    <capabilities>
+        <capability>urn:ietf:params:netconf:base:1.0</capability>
+    </capabilities>
+</hello>
+]]>]]>
+----
+
+This initializes netconf session silently. No response from Honeycomb will be provided
+
+Next step is to get all the configuration data from VPP using Honeycomb's netconf northbound interface. Following content must be copy&pasted into SSH session + hit enter:
+
+[source,xml]
+----
+<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
+    <get-config>
+        <source>
+            <running/>
+        </source>
+    </get-config>
+</rpc>
+]]>]]>
+----
+
+Honeycomb will respond will all the data currently configured in Honeycomb + VPP
+
+Next step is to get all the operational data from VPP using Honeycomb's netconf northbound interface. Following content must be copy&pasted into SSH session + hit enter:
+
+[source,xml]
+----
+<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
+    <get/>
+</rpc>
+]]>]]>
+----
+
+Honeycomb will respond will all operational data present in VPP.
+
+==== Listening for notifications
+
+Notifications over NETCONF are supported by Honeycomb. To test it out, open ssh NETCONF session and send hello message. Exactly as detailed above.
+
+Next thing to do is to activate honeycomb notification stream over NETCONF. So just send this rpc over ssh session:
+
+[source,xml]
+----
+<netconf:rpc netconf:message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
+<create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
+   <stream>honeycomb</stream>
+</create-subscription>
+</netconf:rpc>
+]]>]]>
+----
+
+From now on, all notifications from honeycomb will appear in the netconf session. To verify, VPP's interface state can be changed over CLI:
+
+ telnet 0 5002
+ set interface state local0 up
+
+A notification should appear in opened NETCONF session.
+
+=== Using RESTCONF northbound
+
+[TIP]
+====
+Testing over RESTCONF is easier, and common calls can be found in this postman collection:
+
+*{project-git-web}/v3po/postman_rest_collection.json?h={project-branch}[V3PO postman collection][Honeycomb V3PO POSTMAN collection]*
+
+Each request in the collection contains equivalent VPP command (over CLI or VAT, whichever works) in the description.
+====
+
+To use:
+
+* POSTMAN is a google chrome application
+* Clicking the collection link above is not CORRECT
+* Open POSTMAN and select Import https://www.dropbox.com/s/v2odj4gih5if99d/Screenshot%202016-05-19%2008.51.45.png?dl=0
+* Select import from link https://www.dropbox.com/s/s6wsqzf7h4yhesh/Screenshot%202016-05-19%2008.52.54.png?dl=0
+* Copy the link above into the dialogue https://www.dropbox.com/s/3qc3bbndhy6rr1g/Screenshot%202016-05-19%2008.53.30.png?dl=0
+* PROFIT! https://www.dropbox.com/s/lrdtua7zziqyqc3/Screenshot%202016-05-19%2008.53.51.png?dl=0
+
+NOTE: All POSTMAN collections are listed under User Guide.
+
+==== Listening for notifications
+Notifications over RESTCONF are not supported due to ODL's RESTCONF limitations.
\ No newline at end of file
diff --git a/release-notes/src/main/asciidoc/user_guide/user_troubleshooting.adoc b/release-notes/src/main/asciidoc/user_guide/user_troubleshooting.adoc
new file mode 100644
index 000000000..42215f261
--- /dev/null
+++ b/release-notes/src/main/asciidoc/user_guide/user_troubleshooting.adoc
@@ -0,0 +1,20 @@
+= Troubleshooting
+
+link:release_notes.html[< Home]
+
+CAUTION:  Trying to fix any Honeycomb issue should start with looking at honeycomb log file (default location: /var/log/honeycomb/)
+
+== Unable to open SSH session
+If following warning is shown when invoking ssh command: WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!. Just invoke (as suggested by the warning):
+
+ ssh-keygen -f ...
+
+== Honeycomb fails to start properly
+First thing to do is to take a look at Honeycomb logs(default location: /var/log/honeycomb/).
+
+If following log message is present: VPP-ERROR: VPP api client connection failed java.io.IOException: Connection returned error -1. Make sure VPP is installed in the system and it's running.
+
+NOTE: If the VPP-ERROR also contains message stating vpp japi out of sync. It indicates incompatible versions of VPP and Honeycomb.
+
+== Honeycomb does not respond
+Check suggestions from previous item: Honeycomb fails to start properly
\ No newline at end of file