diff options
Diffstat (limited to 'release-notes/src/main/asciidoc/user_guide')
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 |