summaryrefslogtreecommitdiffstats
path: root/release-notes/src/main/asciidoc/user_guide
diff options
context:
space:
mode:
Diffstat (limited to 'release-notes/src/main/asciidoc/user_guide')
-rw-r--r--release-notes/src/main/asciidoc/user_guide/user_guide.adoc54
-rw-r--r--release-notes/src/main/asciidoc/user_guide/user_honeycomb_and_ODL.adoc76
-rw-r--r--release-notes/src/main/asciidoc/user_guide/user_running_honeycomb.adoc119
-rw-r--r--release-notes/src/main/asciidoc/user_guide/user_troubleshooting.adoc20
4 files changed, 3 insertions, 266 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
index 0f72c8bc9..e1d7b3001 100644
--- a/release-notes/src/main/asciidoc/user_guide/user_guide.adoc
+++ b/release-notes/src/main/asciidoc/user_guide/user_guide.adoc
@@ -1,54 +1,6 @@
== User guide
-=== Running Honeycomb
-link:user_running_honeycomb.html[Running Honeycomb]
+Honeycomb provides a framework for building management agents, and as a standalone out of the box
+tool provides no value.
-=== 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/vpp-common-integration/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]
-* iOAM plugin:
-** {project-git-web}/ioam/impl/src/main/resources/honeycomb-minimal-resources/config/vppioam.json?h={project-branch}[IOAM 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]
-* iOAM plugin
-** {project-git-web}/ioam/api/src/main/yang?h={project-branch}[IOAM 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]
-* iOAM plugin
-** {project-git-web}/ioam/ioam_trace_postman_collection.json?h={project-branch}[IOAM postman collection]
+Refer to devel guide for how to utilize Honeycomb. \ No newline at end of file
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
deleted file mode 100644
index 23c7e521c..000000000
--- a/release-notes/src/main/asciidoc/user_guide/user_honeycomb_and_ODL.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-= 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
deleted file mode 100644
index 07b82a59f..000000000
--- a/release-notes/src/main/asciidoc/user_guide/user_running_honeycomb.adoc
+++ /dev/null
@@ -1,119 +0,0 @@
-= Running Honeycomb
-
-link:release_notes.html[< Home]
-
-== Starting Honeycomb agent
-The zipped vpp-integration distribution can be started by invoking:
-
-[subs="+attributes"]
- 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
deleted file mode 100644
index 42215f261..000000000
--- a/release-notes/src/main/asciidoc/user_guide/user_troubleshooting.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-= 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