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