From 0d3e0a41667a7c2baee3d568228e4abc1c5cc33d Mon Sep 17 00:00:00 2001 From: Dana Kutenicsova Date: Wed, 4 Mar 2015 15:33:11 +0100 Subject: [PATCH] Documentation for tcpmd5 Change-Id: I395c8f927a0aca56c38e2623c1daa7b738386c69 Signed-off-by: Ladislav Borak Signed-off-by: Dana Kutenicsova --- .../asciidoc/tcpmd5/odl-tcpmd5-all-dev.adoc | 72 ++-- .../asciidoc/tcpmd5/odl-tcpmd5-all-user.adoc | 374 ++++++++++++++---- 2 files changed, 340 insertions(+), 106 deletions(-) diff --git a/manuals/developer-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-dev.adoc b/manuals/developer-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-dev.adoc index 75ed9673f..bfc3b013e 100644 --- a/manuals/developer-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-dev.adoc +++ b/manuals/developer-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-dev.adoc @@ -1,40 +1,56 @@ == TCPMD5 Developer Guide === Overview -Provide an overview of the feature, what it logical functionality it -provides and why you might use it as a developer. To be clear the target -audience for this guide is a developer who will be _using_ the feature -to build something separate, but _not_ somebody who will be developing -code for this feature itself. -NOTE: More so than with user guides, the guide may cover more than one -feature. If that is the case, be sure to list all of the features this -covers. +The TCPMD5 project delivers the support for providing access to MD5 Signature +Option on operating systems which support it in their TCP stack. The +implementation is compliant with link:http://tools.ietf.org/html/rfc2385[RFC-2385]. + +The project is available from the tcpmd5 repository. It is split into: + +tcpmd5-api + +tcpmd5-jni + +tcpmd5-nio + +tcpmd5-netty + +tcpmd5-controller-config + +tcpmd5-feature === TCPMD5 Architecture -Provide information about feature components and how they work together. -Also include information about how the feature integrates with -OpenDaylight. An architecture diagram could help. This may be the same -as the diagram used in the user guide, but it should likely be less -abstract and provide more information that would be applicable to a -developer. + +This project defines a new TCP option for carrying an MD5 digest +in a TCP segment. This digest acts like a signature for that segment, +incorporating information known only to the connection end points. === Key APIs and Interfaces -Document the key things a user would want to use. For some features, -there will only be one logical grouping of APIs. For others there may be -more than one grouping. -Assuming the API is MD-SAL- and YANG-based, the APIs will be available -both via RESTCONF and via Java APIs. Giving a few examples using each is -likely a good idea. +As this project is fairly small, it provides only one feature that installs and +provides all APIs and implementations for this project. + +==== tcpmd5-api + +Defines the basic API and a dummy implementation. + +==== tcpmd5-jni + +Contains the JNI implementation and its Java binding. The core of the artifact +is NativeKeyAccess.java, which is the Java frontend and binding class. It +defines the two native methods, setChannelKey0() and isClassSupported0(). These +are implemented in tcpmd5_jni.c. Individual instances are then provided by +NativeKeyAccessFactory, which runs basic sanity tests before allowing itself +being instantiated. + +==== tcpmd5-nio + +Contains the code to bridge the JNI component with java.nio package, +specifically ServerSocketChannel, SocketChannel and SocketOption classes. -==== API Group 1 -Provide a description of what the API does and some examples of how to -use it. +==== tcpmd5-netty -==== API Group 2 -Provide a description of what the API does and some examples of how to -use it. +Contains the code to bridge the JNI component with netty.io, by providing the +appropriate SocketChannelFactory. -=== API Reference Documentation -Provide links to JavaDoc, REST API documentation, etc. diff --git a/manuals/user-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-user.adoc b/manuals/user-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-user.adoc index c5ca7ca8e..f34ce1335 100644 --- a/manuals/user-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-user.adoc +++ b/manuals/user-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-user.adoc @@ -1,81 +1,299 @@ == TCPMD5 User Guide -Refer to this template to identify the required sections and information -that you should provide for a User Guide. The user guide should contain -configuration, administration, management, using, and troubleshooting -sections for the feature. + +This user guide describes the configuration for Border Gateway Protocol (BGP) and Path Computation Element Protocol (PCEP) +using MD5 authentication. It is destined for users who build applications using MD5 library. === Overview -Provide an overview of the feature and the use case. Also include the -audience who will use the feature. For example, audience can be the -network administrator, cloud administrator, network engineer, system -administrators, and so on. - -=== TCPMD5 Architecture -Provide information about feature components and how they work together. -Also include information about how the feature integrates with -OpenDaylight. An architecture diagram could help. - -=== Configuring TCPMD5 - -Describe how to configure the feature or the project after installation. -Configuration information could include day-one activities for a project -such as configuring users, configuring clients/servers and so on. - -=== Administering or Managing TCPMD5 -Include related command reference or operations that you could perform -using the feature. For example viewing network statistics, monitoring -the network, generating reports, and so on. - -NOTE: Ensure that you create a step procedure whenever required and -avoid concepts. - -For example: - -.To configure L2switch components perform the following steps. -. Step 1: -. Step 2: -. Step 3: - -=== Tutorials - -If there is only one tutorial, you skip the "Tutorials" section and -instead just lead with the single tutorial's name. - -==== -Ensure that the title starts with a gerund. For example using, -monitoring, creating, and so on. - -===== Overview -An overview of the use case. - -===== Prerequisites -Provide any prerequisite information, assumed knowledge, or environment -required to execute the use case. - -===== Target Environment -Include any topology requirement for the use case. Ideally, provide -visual (abstract) layout of network diagrams and any other useful visual -aides. - -===== Instructions -Use case could be a set of configuration procedures. Including -screenshots to help demonstrate what is happening is especially useful. -Ensure that you specify them separately. For example: - -. *Setting up the VM* -To set up a VM perform the following steps. -.. Step 1 -.. Step 2 -.. Step 3 - -. *Installing the feature* -To install the feature perform the following steps. -.. Step 1 -.. Step 2 -.. Step 3 - -. *Configuring the environment* -To configure the system perform the following steps. -.. Step 1 -.. Step 2 -.. Step 3 + +The TCPMD5 library provides access to link:http://tools.ietf.org/html/rfc2385[RFC-2385] MD5 Signature Option on operating systems which support it in their TCP stack. +This option has been historically used to protect BGP sessions, but is equally useful for protecting PCEP sessions. + +IMPORTANT: *Before you continue with steps in this user guide, make sure BGP and/or PCEP is configured properly.* + +TCPMD5 authentication is *disabled* by default. To enable it (for both protocols), uncomment the contents of _20-tcpmd5.xml_. +You can find this configuration file in your OpenDaylight directory _etc/opendaylight/karaf_ . + +CAUTION: [big]#*If the connection can not be established, there are no warnings or errors, +so be sure to double check your configuration and passwords.*# + +=== Configuring TCPMD5 manually + +==== BGP + +IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.* + +To enable TCPMD5 for the BGP protocol, perform the following steps: + +. In _31-bgp.xml_ uncomment the TCP MD5 section: ++ +[source,xml] +---- + + + prefix:md5-channel-factory + md5-client-channel-factory + + + prefix:md5-server-channel-factory + md5-server-channel-factory + +---- +. In _41-bgp-example.xml_ add tag to module example-bgp-peer. ++ +[source,xml] +---- + + + prefix:bgp-peer + example-bgp-peer + 10.25.2.27 + 180 + + prefix:rib + example-bgp-rib + + + prefix:bgp-table-type + ipv4-unicast + + + prefix:bgp-table-type + ipv6-unicast + + + prefix:bgp-table-type + linkstate + + changeme + +---- + +NOTE: Setting a password on other BGP devices is out of scope for this document. + +==== PCEP + +IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.* + +To enable TCPMD5 for PCE protocol, perform the following steps: + +. In _32-pcep.xml_ uncomment the TCPMD5 section: ++ +[source,xml] +---- + + + prefix:md5-channel-factory + md5-client-channel-factory + + + prefix:md5-server-channel-factory + md5-server-channel-factory + +---- + +. In _39-pcep-provider.xml_ uncomment following section: ++ +[source,xml] +---- + + +
192.0.2.2
+ changeme + +---- + +IMPORTANT: *Change the
value to the address of PCC, the one that is advertized to PCE and provide password matching the one set on PCC.* + +NOTE: Setting a password on PCC is out of scope for this document. + + +=== Configuring TCPMD5 through RESTCONF + +IMPORTANT: Before you start, make sure, you have installed features for BGP and/or PCEP. Install another feature, that will provide you the access to _restconf/config/_ URLs. +[source,xml] +---- +feature:install odl-netconf-connector-all +---- + +This log message indicates successful start of netconf-connector: _Netconf connector initialized successfully_ + +- To check what modules you have currently configured, check following link: http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/ + +- To check what services you have currently configured, check following link: http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:services/ + +These URLs are also used to POST new configuration. If you want to change any other configuration that is listed here, +make sure you include the correct namespaces. The correct namespace for is always _urn:opendaylight:params:xml:ns:yang:controller:config_. +The namespace for any other fields can be found by finding given module in configuration yang files. + +NOTE: RESTCONF will tell you if some namespace is wrong. + +To enable TCPMD5 for either one of the protocols, enable TCPMD5 modules and services: + +CAUTION: You have to make *separate* POST requests for each module/service! + +[big]#*URL:# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/ + +[big]#*POST:*# + +[source,xml] +---- + + x:native-key-access-factory + global-key-access-factory + +---- +[source,xml] +---- + + x:md5-client-channel-factory + md5-client-channel-factory + + x:key-access-factory + global-key-access-factory + + +---- +[source,xml] +---- + + prefix:md5-server-channel-factory-impl + md5-server-channel-factory + + x:key-access-factory + global-key-access-factory + + +---- + +[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:services/ + +[big]#*POST:*# + +[source,xml] +---- + + x:key-access-factory + + global-key-access-factory + /modules/module[type='native-key-access-factory'][name='global-key-access-factory'] + + +---- +[source,xml] +---- + + x:md5-channel-factory + + md5-client-channel-factory + /modules/module[type='md5-client-channel-factory'][name='md5-client-channel-factory'] + + +---- +[source,xml] +---- + + prefix:md5-server-channel-factory + + md5-server-channel-factory + /modules/module[type='md5-server-channel-factory-impl'][name='md5-server-channel-factory'] + + +---- + +==== BGP + +CAUTION: You have to introduce modules and services mentioned in the previous section. Your BGP client needs to be *ALREADY* configured. Check User Guide for BGP. // TODO: link to BGP section + +. Enabling TCPMD5 in BGP configuration: ++ +[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/ + +[big]#*POST:*# + +[source,xml] +---- + + x:bgp-dispatcher-impl + global-bgp-dispatcher + + x:md5-channel-factory + md5-client-channel-factory + + + x:md5-server-channel-factory + md5-server-channel-factory + + +---- + +. Set password: ++ +[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/ + +[big]#*POST:*# + +[source,xml] +---- + + x:bgp-peer + example-bgp-peer + changeme + +---- + +==== PCEP + +CAUTION: You have to introduce modules and services mentioned in the previous section. + +. Enable TCPMD5 in PCEP configuration: ++ +[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/ + +[big]#*POST:*# + +[source,xml] +---- + + x:pcep-dispatcher-impl + global-pcep-dispatcher + + x:md5-channel-factory + md5-client-channel-factory + + + x:md5-server-channel-factory + md5-server-channel-factory + + +---- + +. Set password: ++ +[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/ + +[big]#*POST:*# +[source,xml] +---- + + x:pcep-topology-provider + pcep-topology + +
192.0.2.2
+ changeme + + +---- -- 2.36.6