docs/user-guide/sxp-user-guide.rst

   1 .. _sxp-user-guide:
   2
   3 SXP User Guide
   4 ==============
   5
   6 Overview
   7 --------
   8
   9 SXP (Scalable-Group Tag eXchange Protocol) project is an effort to enhance
  10 OpenDaylight platform with IP-SGT (IP Address to Source Group Tag)
  11 bindings that can be learned from connected SXP-aware network nodes. The
  12 current implementation supports SXP protocol version 4 according to the
  13 Smith, Kandula - SXP `IETF
  14 draft <https://tools.ietf.org/html/draft-smith-kandula-sxp-05>`__ and
  15 grouping of peers and creating filters based on ACL/Prefix-list syntax
  16 for filtering outbound and inbound IP-SGT bindings. All protocol legacy
  17 versions 1-3 are supported as well. Additionally, version 4 adds
  18 bidirectional connection type as an extension of a unidirectional one.
  19
  20 SXP Architecture
  21 ----------------
  22
  23 The SXP Server manages all connected clients in separate threads and a
  24 common SXP protocol agreement is used between connected peers. Each SXP
  25 network peer is modelled with its pertaining class, e.g., SXP Server
  26 represents the SXP Speaker, SXP Listener the Client. The server program
  27 creates the ServerSocket object on a specified port and waits until a
  28 client starts up and requests connect on the IP address and port of the
  29 server. The client program opens a Socket that is connected to the
  30 server running on the specified host IP address and port.
  31
  32 The SXP Listener maintains connection with its speaker peer. From an
  33 opened channel pipeline, all incoming SXP messages are processed by
  34 various handlers. Message must be decoded, parsed and validated.
  35
  36 The SXP Speaker is a counterpart to the SXP Listener. It maintains a
  37 connection with its listener peer and sends composed messages.
  38
  39 The SXP Binding Handler extracts the IP-SGT binding from a message and
  40 pulls it into the SXP-Database. If an error is detected during the
  41 IP-SGT extraction, an appropriate error code and sub-code is selected
  42 and an error message is sent back to the connected peer. All transitive
  43 messages are routed directly to the output queue of SXP Binding
  44 Dispatcher.
  45
  46 The SXP Binding Dispatcher represents a selector that will decides how
  47 many data from the SXP-database will be sent and when. It is responsible
  48 for message content composition based on maximum message length.
  49
  50 The SXP Binding Filters handles filtering of outgoing and incoming
  51 IP-SGT bindings according to BGP filtering using ACL and Prefix List
  52 syntax for specifying filter or based on Peer-sequence length.
  53
  54 The SXP Domains feature provides isolation of SXP peers and bindings
  55 learned between them, also exchange of Bindings is possible across
  56 SXP-Domains by ACL, Prefix List or Peer-Sequence filters
  57
  58 Configuring SXP
  59 ---------------
  60
  61 The OpenDaylight Karaf distribution comes pre-configured with baseline
  62 SXP configuration. Configuration of SXP Nodes is also possible via
  63 NETCONF.
  64
  65 -  **22-sxp-controller-one-node.xml** (defines the basic parameters)
  66
  67 Administering or Managing SXP
  68 -----------------------------
  69
  70 By RPC (response is XML document containing requested data or operation
  71 status):
  72
  73 -  Get Connections POST
  74    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-connections
  75
  76 ::
  77
  78     <input xmlns:xsi="urn:opendaylight:sxp:controller">
  79      <domain-name>global</domain-name>
  80      <requested-node>0.0.0.100</requested-node>
  81     </input>
  82
  83 -  Add Connection POST
  84    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-connection
  85
  86 ::
  87
  88     <input xmlns:xsi="urn:opendaylight:sxp:controller">
  89      <requested-node>0.0.0.100</requested-node>
  90      <domain-name>global</domain-name>
  91      <connections>
  92       <connection>
  93        <peer-address>172.20.161.50</peer-address>
  94        <tcp-port>64999</tcp-port>
  95        <!-- Password setup: default | none leave empty -->
  96        <password>default</password>
  97        <!-- Mode: speaker/listener/both -->
  98        <mode>speaker</mode>
  99        <version>version4</version>
 100        <description>Connection to ASR1K</description>
 101        <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
 102        <connection-timers>
 103         <!-- Speaker -->
 104         <hold-time-min-acceptable>45</hold-time-min-acceptable>
 105         <keep-alive-time>30</keep-alive-time>
 106        </connection-timers>
 107       </connection>
 108       <connection>
 109        <peer-address>172.20.161.178</peer-address>
 110        <tcp-port>64999</tcp-port>
 111        <!-- Password setup: default | none leave empty-->
 112        <password>default</password>
 113        <!-- Mode: speaker/listener/both -->
 114        <mode>listener</mode>
 115        <version>version4</version>
 116        <description>Connection to ISR</description>
 117        <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
 118        <connection-timers>
 119         <!-- Listener -->
 120         <reconciliation-time>120</reconciliation-time>
 121         <hold-time>90</hold-time>
 122         <hold-time-min>90</hold-time-min>
 123         <hold-time-max>180</hold-time-max>
 124        </connection-timers>
 125       </connection>
 126      </connections>
 127     </input>
 128
 129 -  Delete Connection POST
 130    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-connection
 131
 132 ::
 133
 134     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 135      <requested-node>0.0.0.100</requested-node>
 136      <domain-name>global</domain-name>
 137      <peer-address>172.20.161.50</peer-address>
 138     </input>
 139
 140 -  Add Binding Entry POST
 141    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-entry
 142
 143 ::
 144
 145     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 146      <requested-node>0.0.0.100</requested-node>
 147      <domain-name>global</domain-name>
 148      <ip-prefix>192.168.2.1/32</ip-prefix>
 149      <sgt>20</sgt >
 150     </input>
 151
 152 -  Update Binding Entry POST
 153    http://127.0.0.1:8181/restconf/operations/sxp-controller:update-entry
 154
 155 ::
 156
 157     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 158      <requested-node>0.0.0.100</requested-node>
 159      <domain-name>global</domain-name>
 160      <original-binding>
 161       <ip-prefix>192.168.2.1/32</ip-prefix>
 162       <sgt>20</sgt>
 163      </original-binding>
 164      <new-binding>
 165       <ip-prefix>192.168.3.1/32</ip-prefix>
 166       <sgt>30</sgt>
 167      </new-binding>
 168     </input>
 169
 170 -  Delete Binding Entry POST
 171    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-entry
 172
 173 ::
 174
 175     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 176      <requested-node>0.0.0.100</requested-node>
 177      <domain-name>global</domain-name>
 178      <ip-prefix>192.168.3.1/32</ip-prefix>
 179      <sgt>30</sgt >
 180     </input>
 181
 182 -  Get Node Bindings
 183
 184    This RPC gets particular device bindings. An SXP-aware node is
 185    identified with a unique Node-ID. If a user requests bindings for a
 186    Speaker 20.0.0.2, the RPC will search for an appropriate path, which
 187    contains 20.0.0.2 Node-ID, within locally learnt SXP data in the SXP
 188    database and replies with associated bindings. POST
 189    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-node-bindings
 190
 191 ::
 192
 193     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 194      <requested-node>20.0.0.2</requested-node>
 195      <bindings-range>all</bindings-range>
 196      <domain-name>global</domain-name>
 197     </input>
 198
 199 -  Get Binding SGTs POST
 200    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-binding-sgts
 201
 202 ::
 203
 204     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 205      <requested-node>0.0.0.100</requested-node>
 206      <domain-name>global</domain-name>
 207      <ip-prefix>192.168.12.2/32</ip-prefix>
 208     </input>
 209
 210 -  Add PeerGroup with or without filters to node. POST
 211    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-peer-group
 212
 213 ::
 214
 215     <input xmlns="urn:opendaylight:sxp:controller">
 216      <requested-node>127.0.0.1</requested-node>
 217      <sxp-peer-group>
 218       <name>TEST</name>
 219       <sxp-peers>
 220       </sxp-peers>
 221       <sxp-filter>
 222        <filter-type>outbound</filter-type>
 223        <acl-entry>
 224         <entry-type>deny</entry-type>
 225         <entry-seq>1</entry-seq>
 226         <sgt-start>1</sgt-start>
 227         <sgt-end>100</sgt-end>
 228        </acl-entry>
 229        <acl-entry>
 230         <entry-type>permit</entry-type>
 231         <entry-seq>45</entry-seq>
 232         <matches>1</matches>
 233         <matches>3</matches>
 234         <matches>5</matches>
 235        </acl-entry>
 236       </sxp-filter>
 237      </sxp-peer-group>
 238     </input>
 239
 240 -  Delete PeerGroup with peer-group-name from node request-node. POST
 241    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-peer-group
 242
 243 ::
 244
 245     <input xmlns="urn:opendaylight:sxp:controller">
 246      <requested-node>127.0.0.1</requested-node>
 247      <peer-group-name>TEST</peer-group-name>
 248     </input>
 249
 250 -  Get PeerGroup with peer-group-name from node request-node. POST
 251    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-peer-group
 252
 253 ::
 254
 255     <input xmlns="urn:opendaylight:sxp:controller">
 256      <requested-node>127.0.0.1</requested-node>
 257      <peer-group-name>TEST</peer-group-name>
 258     </input>
 259
 260 -  Add Filter to peer group on node request-node. POST
 261    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-filter
 262
 263 ::
 264
 265     <input xmlns="urn:opendaylight:sxp:controller">
 266      <requested-node>127.0.0.1</requested-node>
 267      <peer-group-name>TEST</peer-group-name>
 268      <sxp-filter>
 269       <filter-type>outbound</filter-type>
 270       <acl-entry>
 271        <entry-type>deny</entry-type>
 272        <entry-seq>1</entry-seq>
 273        <sgt-start>1</sgt-start>
 274        <sgt-end>100</sgt-end>
 275       </acl-entry>
 276       <acl-entry>
 277        <entry-type>permit</entry-type>
 278        <entry-seq>45</entry-seq>
 279        <matches>1</matches>
 280        <matches>3</matches>
 281        <matches>5</matches>
 282       </acl-entry>
 283      </sxp-filter>
 284     </input>
 285
 286 -  Delete Filter from peer group on node request-node. POST
 287    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-filter
 288
 289 ::
 290
 291     <input xmlns="urn:opendaylight:sxp:controller">
 292      <requested-node>127.0.0.1</requested-node>
 293      <peer-group-name>TEST</peer-group-name>
 294      <filter-type>outbound</filter-type>
 295     </input>
 296
 297 -  Update Filter of the same type in peer group on node request-node.
 298    POST
 299    http://127.0.0.1:8181/restconf/operations/sxp-controller:update-filter
 300
 301 ::
 302
 303     <input xmlns="urn:opendaylight:sxp:controller">
 304      <requested-node>127.0.0.1</requested-node>
 305      <peer-group-name>TEST</peer-group-name>
 306      <sxp-filter>
 307       <filter-type>outbound</filter-type>
 308       <acl-entry>
 309        <entry-type>deny</entry-type>
 310        <entry-seq>1</entry-seq>
 311        <sgt-start>1</sgt-start>
 312        <sgt-end>100</sgt-end>
 313       </acl-entry>
 314       <acl-entry>
 315        <entry-type>permit</entry-type>
 316        <entry-seq>45</entry-seq>
 317        <matches>1</matches>
 318        <matches>3</matches>
 319        <matches>5</matches>
 320       </acl-entry>
 321      </sxp-filter>
 322     </input>
 323
 324 -  Add new SXP aware Node POST
 325    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-node
 326
 327 ::
 328
 329     <input xmlns="urn:opendaylight:sxp:controller">
 330         <node-id>1.1.1.1</node-id>
 331         <source-ip>0.0.0.0</source-ip>
 332         <timers>
 333             <retry-open-time>5</retry-open-time>
 334             <hold-time-min-acceptable>120</hold-time-min-acceptable>
 335             <delete-hold-down-time>120</delete-hold-down-time>
 336             <hold-time-min>90</hold-time-min>
 337             <reconciliation-time>120</reconciliation-time>
 338             <hold-time>90</hold-time>
 339             <hold-time-max>180</hold-time-max>
 340             <keep-alive-time>30</keep-alive-time>
 341         </timers>
 342         <mapping-expanded>150</mapping-expanded>
 343         <security>
 344             <password>password</password>
 345         </security>
 346         <tcp-port>64999</tcp-port>
 347         <version>version4</version>
 348         <description>ODL SXP Controller</description>
 349         <master-database></master-database>
 350     </input>
 351
 352 -  Delete SXP aware node POST
 353    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-node
 354
 355 ::
 356
 357     <input xmlns="urn:opendaylight:sxp:controller">
 358      <node-id>1.1.1.1</node-id>
 359     </input>
 360
 361 -  Add SXP Domain on node request-node. POST
 362    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-domain
 363
 364 ::
 365
 366     <input xmlns="urn:opendaylight:sxp:controller">
 367       <node-id>1.1.1.1</node-id>
 368       <domain-name>global</domain-name>
 369     </input>
 370
 371 -  Delete SXP Domain on node request-node. POST
 372    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-domain
 373
 374 ::
 375
 376     <input xmlns="urn:opendaylight:sxp:controller">
 377      <node-id>1.1.1.1</node-id>
 378      <domain-name>global</domain-name>
 379     </input>
 380
 381 -  Add Route Adds route to leader Node. PUT
 382    http://127.0.0.1:8181/restconf/config/sxp-cluster-route:sxp-cluster-route/
 383
 384 ::
 385
 386     <sxp-cluster-route xmlns="urn:opendaylight:sxp:cluster:route">
 387         <routing-definition>
 388             <ip-address>80.12.43.2</ip-address>
 389             <interface>eth1:0</interface>
 390             <netmask>255.255.255.0</netmask>
 391         </routing-definition>
 392     </sxp-cluster-route>
 393
 394 Use cases for SXP
 395 ~~~~~~~~~~~~~~~~~
 396
 397 Cisco has a wide installed base of network devices supporting SXP. By
 398 including SXP in OpenDaylight, the binding of policy groups to IP
 399 addresses can be made available for possible further processing to a
 400 wide range of devices, and applications running on OpenDaylight. The
 401 range of applications that would be enabled is extensive. Here are just
 402 a few of them:
 403
 404 OpenDaylight based applications can take advantage of the IP-SGT binding
 405 information. For example, access control can be defined by an operator
 406 in terms of policy groups, while OpenDaylight can configure access
 407 control lists on network elements using IP addresses, e.g., existing
 408 technology.
 409
 410 Interoperability between different vendors. Vendors have different
 411 policy systems. Knowing the IP-SGT binding for Cisco makes it possible
 412 to maintain policy groups between Cisco and other vendors.
 413
 414 OpenDaylight can aggregate the binding information from many devices and
 415 communicate it to a network element. For example, a firewall can use the
 416 IP-SGT binding information to know how to handle IPs based on the
 417 group-based ACLs it has set. But to do this with SXP alone, the firewall
 418 has to maintain a large number of network connections to get the binding
 419 information. This incurs heavy overhead costs to maintain all of the SXP
 420 peering and protocol information. OpenDaylight can aggregate the
 421 IP-group information so that the firewall need only connect to
 422 OpenDaylight. By moving the information flow outside of the network
 423 elements to a centralized position, we reduce the overhead of the CPU
 424 consumption on the enforcement element. This is a huge savings - it
 425 allows the enforcement point to only have to make one connection rather
 426 than thousands, so it can concentrate on its primary job of forwarding
 427 and enforcing.
 428
 429 OpenDaylight can relay the binding information from one network element
 430 to others. Changes in group membership can be propagated more readily
 431 through a centralized model. For example, in a security application a
 432 particular host (e.g., user or IP Address) may be found to be acting
 433 suspiciously or violating established security policies. The defined
 434 response is to put the host into a different source group for
 435 remediation actions such as a lower quality of service, restricted
 436 access to critical servers, or special routing conditions to ensure
 437 deeper security enforcement (e.g., redirecting the host’s traffic
 438 through an IPS with very restrictive policies). Updated group membership
 439 for this host needs to be communicated to multiple network elements as
 440 soon as possible; a very efficient and effective method of propagation
 441 can be performed using OpenDaylight as a centralized point for relaying
 442 the information.
 443
 444 OpenDaylight can create filters for exporting and receiving IP-SGT
 445 bindings used on specific peer groups, thus can provide more complex
 446 maintaining of policy groups.
 447
 448 Although the IP-SGT binding is only one specific piece of information,
 449 and although SXP is implemented widely in a single vendor’s equipment,
 450 bringing the ability of OpenDaylight to process and distribute the
 451 bindings, is a very specific immediate useful implementation of policy
 452 groups. It would go a long way to develop both the usefulness of
 453 OpenDaylight and of policy groups.
 454