manuals/user-guide/src/main/asciidoc/tcpmd5/odl-tcpmd5-all-user.adoc

   1 == TCPMD5 User Guide
   2
   3 This user guide describes the configuration for Border Gateway Protocol (BGP) and Path Computation Element Protocol (PCEP)
   4 using MD5 authentication. It is destined for users who build applications using MD5 library.
   5
   6 === Overview
   7
   8 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.
   9 This option has been historically used to protect BGP sessions, but is equally useful for protecting PCEP sessions.
  10
  11 IMPORTANT: *Before you continue with steps in this user guide, make sure BGP and/or PCEP is configured properly.*
  12
  13 TCPMD5 authentication is *disabled* by default. To enable it (for both protocols), uncomment the contents of _20-tcpmd5.xml_.
  14 You can find this configuration file in your OpenDaylight directory _etc/opendaylight/karaf_ .
  15
  16 CAUTION: [big]#*If the connection can not be established, there are no warnings or errors,
  17 so be sure to double check your configuration and passwords.*#
  18
  19 === Configuring TCPMD5 manually
  20
  21 ==== BGP
  22
  23 IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.*
  24
  25 To enable TCPMD5 for the BGP protocol, perform the following steps:
  26
  27 . In _31-bgp.xml_ uncomment the TCP MD5 section:
  28 +
  29 [source,xml]
  30 ----
  31 <!--
  32  Uncomment this block to enable TCPMD5 Signature support
  33 -->
  34 <md5-channel-factory>
  35  <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-channel-factory</type>
  36  <name>md5-client-channel-factory</name>
  37 </md5-channel-factory>
  38 <md5-server-channel-factory>
  39  <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
  40  <name>md5-server-channel-factory</name>
  41 </md5-server-channel-factory>
  42 ----
  43 . In _41-bgp-example.xml_ add <password> tag to module example-bgp-peer.
  44 +
  45 [source,xml]
  46 ----
  47 <!--
  48  For TCPMD5 support, make sure the dispatcher associated with the rib has
  49  "md5-channel-factory" attribute set and then add a "password" attribute here.
  50  Note that the peer has to have the same password configured, otherwise the
  51  connection will not be established.
  52 -->
  53 <module>
  54  <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-peer</type>
  55  <name>example-bgp-peer</name>
  56  <host>10.25.2.27</host>
  57  <holdtimer>180</holdtimer>
  58  <rib>
  59   <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:cfg">prefix:rib</type>
  60   <name>example-bgp-rib</name>
  61  </rib>
  62  <advertized-table>
  63   <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
  64   <name>ipv4-unicast</name>
  65  </advertized-table>
  66  <advertized-table>
  67   <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
  68   <name>ipv6-unicast</name>
  69  </advertized-table>
  70  <advertized-table>
  71   <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
  72   <name>linkstate</name>
  73  </advertized-table>
  74  <password>changeme</password>
  75 </module>
  76 ----
  77
  78 NOTE: Setting a password on other BGP devices is out of scope for this document.
  79
  80 ==== PCEP
  81
  82 IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.*
  83
  84 To enable TCPMD5 for PCE protocol, perform the following steps:
  85
  86 . In _32-pcep.xml_ uncomment the TCPMD5 section:
  87 +
  88 [source,xml]
  89 ----
  90 <!--
  91  Uncomment this block to enable TCPMD5 Signature support
  92 -->
  93 <md5-channel-factory>
  94  <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-channel-factory</type>
  95   <name>md5-client-channel-factory</name>
  96 </md5-channel-factory>
  97 <md5-server-channel-factory>
  98  <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
  99   <name>md5-server-channel-factory</name>
 100 </md5-server-channel-factory>
 101 ----
 102
 103 . In _39-pcep-provider.xml_ uncomment following section:
 104 +
 105 [source,xml]
 106 ----
 107 <!--
 108  For TCPMD5 support make sure the dispatcher has the "md5-server-channel-factory"
 109  attribute set and then set the appropriate client entries here. Note that if this
 110  option is configured, the PCCs connecting here must have the same password,
 111  otherwise they will not be able to connect.
 112  -->
 113  <client>
 114   <address>192.0.2.2</address>
 115   <password>changeme</password>
 116  </client>
 117 ----
 118
 119 IMPORTANT: *Change the <address> value to the address of PCC, the one that is advertized to PCE and provide password matching the one set on PCC.*
 120
 121 NOTE: Setting a password on PCC is out of scope for this document.
 122
 123
 124 === Configuring TCPMD5 through RESTCONF
 125
 126 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.
 127 [source,xml]
 128 ----
 129 feature:install odl-netconf-connector-all
 130 ----
 131
 132 This log message indicates successful start of netconf-connector: _Netconf connector initialized successfully_
 133
 134 - 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/
 135
 136 - 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/
 137
 138 These URLs are also used to POST new configuration. If you want to change any other configuration that is listed here,
 139 make sure you include the correct namespaces. The correct namespace for <module> is always _urn:opendaylight:params:xml:ns:yang:controller:config_.
 140 The namespace for any other fields can be found by finding given module in configuration yang files.
 141
 142 NOTE: RESTCONF will tell you if some namespace is wrong.
 143
 144 To enable TCPMD5 for either one of the protocols, enable TCPMD5 modules and services:
 145
 146 CAUTION: You have to make *separate* POST requests for each module/service!
 147
 148 [big]#*URL:# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
 149
 150 [big]#*POST:*#
 151
 152 [source,xml]
 153 ----
 154 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 155  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:jni:cfg">x:native-key-access-factory</type>
 156  <name>global-key-access-factory</name>
 157 </module>
 158 ----
 159 [source,xml]
 160 ----
 161 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 162  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-client-channel-factory</type>
 163  <name>md5-client-channel-factory</name>
 164  <key-access-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">
 165   <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
 166   <name>global-key-access-factory</name>
 167  </key-access-factory>
 168 </module>
 169 ----
 170 [source,xml]
 171 ----
 172 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 173  <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory-impl</type>
 174  <name>md5-server-channel-factory</name>
 175  <server-key-access-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">
 176   <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
 177   <name>global-key-access-factory</name>
 178  </server-key-access-factory>
 179 </module>
 180 ----
 181
 182 [big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:services/
 183
 184 [big]#*POST:*#
 185
 186 [source,xml]
 187 ----
 188 <service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 189  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
 190  <instance>
 191   <name>global-key-access-factory</name>
 192   <provider>/modules/module[type='native-key-access-factory'][name='global-key-access-factory']</provider>
 193  </instance>
 194 </service>
 195 ----
 196 [source,xml]
 197 ----
 198 <service  xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 199  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
 200  <instance>
 201   <name>md5-client-channel-factory</name>
 202   <provider>/modules/module[type='md5-client-channel-factory'][name='md5-client-channel-factory']</provider>
 203  </instance>
 204 </service>
 205 ----
 206 [source,xml]
 207 ----
 208 <service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 209  <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
 210  <instance>
 211   <name>md5-server-channel-factory</name>
 212   <provider>/modules/module[type='md5-server-channel-factory-impl'][name='md5-server-channel-factory']</provider>
 213  </instance>
 214 </service>
 215 ----
 216
 217 ==== BGP
 218
 219 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.
 220
 221 CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
 222
 223 . Enabling TCPMD5 in BGP configuration:
 224 +
 225 [big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-bgp-rib-impl-cfg:bgp-dispatcher-impl/global-bgp-dispatcher
 226
 227 [big]#*PUT:*#
 228
 229 [source,xml]
 230 ----
 231 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 232  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">x:bgp-dispatcher-impl</type>
 233  <name>global-bgp-dispatcher</name>
 234  <md5-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
 235   <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
 236   <name>md5-client-channel-factory</name>
 237  </md5-channel-factory>
 238  <md5-server-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
 239   <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-server-channel-factory</type>
 240   <name>md5-server-channel-factory</name>
 241  </md5-server-channel-factory>
 242  ...
 243 </module>
 244 ----
 245
 246 CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
 247
 248 . Set password:
 249 +
 250 [big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-bgp-rib-impl-cfg:bgp-peer/example-bgp-peer
 251
 252 [big]#*PUT:*#
 253
 254 [source,xml]
 255 ----
 256 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 257  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">x:bgp-peer</type>
 258  <name>example-bgp-peer</name>
 259  <password xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">changeme</password>
 260  ...
 261 </module>
 262 ----
 263
 264 ==== PCEP
 265
 266 CAUTION: You have to introduce modules and services mentioned in the previous section.
 267
 268 CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
 269
 270 . Enable TCPMD5 in PCEP configuration:
 271 +
 272 [big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-pcep-impl-cfg:pcep-dispatcher-impl/global-pcep-dispatcher
 273
 274 [big]#*PUT:*#
 275
 276 [source,xml]
 277 ----
 278 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 279  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">x:pcep-dispatcher-impl</type>
 280  <name>global-pcep-dispatcher</name>
 281  <md5-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
 282   <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
 283   <name>md5-client-channel-factory</name>
 284  </md5-channel-factory>
 285  <md5-server-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
 286   <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-server-channel-factory</type>
 287   <name>md5-server-channel-factory</name>
 288  </md5-server-channel-factory>
 289  ...
 290 </module>
 291 ----
 292
 293 CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
 294
 295 . Set password:
 296 +
 297 [big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-pcep-impl-cfg:pcep-topology-provider/pcep-topology
 298
 299 [big]#*PUT:*#
 300 [source,xml]
 301 ----
 302 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 303  <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">x:pcep-topology-provider</type>
 304  <name>pcep-topology</name>
 305  <client xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">
 306   <address xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">192.0.2.2</address> <!--CHANGE THE VALUE -->
 307   <password>changeme</password> <!--CHANGE THE VALUE -->
 308  </client>
 309  ...
 310 </module>
 311 ----