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-06>`__ 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 SXP requires no manual configuration.
  62
  63 Administering or Managing SXP
  64 -----------------------------
  65
  66 By RPC (response is XML document containing requested data or operation
  67 status):
  68
  69 -  Get Connections POST
  70    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-connections
  71
  72 ::
  73
  74     <input xmlns:xsi="urn:opendaylight:sxp:controller">
  75      <domain-name>global</domain-name>
  76      <requested-node>0.0.0.100</requested-node>
  77     </input>
  78
  79 -  Add Connection POST
  80    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-connection
  81
  82 ::
  83
  84     <input xmlns:xsi="urn:opendaylight:sxp:controller">
  85      <requested-node>0.0.0.100</requested-node>
  86      <domain-name>global</domain-name>
  87      <connections>
  88       <connection>
  89        <peer-address>172.20.161.50</peer-address>
  90        <tcp-port>64999</tcp-port>
  91        <!-- Password setup: default | none leave empty -->
  92        <password>default</password>
  93        <!-- Mode: speaker/listener/both -->
  94        <mode>speaker</mode>
  95        <version>version4</version>
  96        <description>Connection to ASR1K</description>
  97        <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
  98        <connection-timers>
  99         <!-- Speaker -->
 100         <hold-time-min-acceptable>45</hold-time-min-acceptable>
 101         <keep-alive-time>30</keep-alive-time>
 102        </connection-timers>
 103       </connection>
 104       <connection>
 105        <peer-address>172.20.161.178</peer-address>
 106        <tcp-port>64999</tcp-port>
 107        <!-- Password setup: default | none leave empty-->
 108        <password>default</password>
 109        <!-- Mode: speaker/listener/both -->
 110        <mode>listener</mode>
 111        <version>version4</version>
 112        <description>Connection to ISR</description>
 113        <!-- Timers setup: 0 to disable specific timer usability, the default value will be used -->
 114        <connection-timers>
 115         <!-- Listener -->
 116         <reconciliation-time>120</reconciliation-time>
 117         <hold-time>90</hold-time>
 118         <hold-time-min>90</hold-time-min>
 119         <hold-time-max>180</hold-time-max>
 120        </connection-timers>
 121       </connection>
 122      </connections>
 123     </input>
 124
 125 -  Delete Connection POST
 126    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-connection
 127
 128 ::
 129
 130     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 131      <requested-node>0.0.0.100</requested-node>
 132      <domain-name>global</domain-name>
 133      <peer-address>172.20.161.50</peer-address>
 134     </input>
 135
 136 -  Add/Update Bindings POST
 137    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-bindings
 138
 139 ::
 140
 141     <input xmlns="urn:opendaylight:sxp:controller">
 142       <node-id>0.0.0.100</node-id>
 143       <domain-name>global</domain-name>
 144       <origin>LOCAL</origin>
 145       <master-database>
 146         <binding>
 147           <sgt>50</sgt>
 148           <ip-prefix>192.168.2.1/32</ip-prefix>
 149           <ip-prefix>192.168.2.2/32</ip-prefix>
 150         </binding>
 151         <binding>
 152           <sgt>100</sgt>
 153           <ip-prefix>192.168.3.1/32</ip-prefix>
 154           <ip-prefix>192.168.3.2/32</ip-prefix>
 155         </binding>
 156       </master-database>
 157     </input>
 158
 159 -  Delete Bindings POST
 160    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-bindings
 161
 162 ::
 163
 164     <input xmlns="urn:opendaylight:sxp:controller">
 165       <node-id>0.0.0.100</node-id>
 166       <domain-name>global</domain-name>
 167       <binding>
 168         <sgt>50</sgt>
 169         <ip-prefix>192.168.2.2/32</ip-prefix>
 170       </binding>
 171       <binding>
 172         <sgt>100</sgt>
 173         <ip-prefix>192.168.3.2/32</ip-prefix>
 174       </binding>
 175     </input>
 176
 177 -  Get Node Bindings
 178
 179    This RPC gets particular device bindings. An SXP-aware node is
 180    identified with a unique Node-ID. If a user requests bindings for a
 181    Speaker 20.0.0.2, the RPC will search for an appropriate path, which
 182    contains 20.0.0.2 Node-ID, within locally learnt SXP data in the SXP
 183    database and replies with associated bindings. POST
 184    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-node-bindings
 185
 186 ::
 187
 188     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 189      <requested-node>20.0.0.2</requested-node>
 190      <bindings-range>all</bindings-range>
 191      <domain-name>global</domain-name>
 192     </input>
 193
 194 -  Get Binding SGTs POST
 195    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-binding-sgts
 196
 197 ::
 198
 199     <input xmlns:xsi="urn:opendaylight:sxp:controller">
 200      <requested-node>0.0.0.100</requested-node>
 201      <domain-name>global</domain-name>
 202      <ip-prefix>192.168.12.2/32</ip-prefix>
 203     </input>
 204
 205 -  Add PeerGroup with or without filters to node. POST
 206    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-peer-group
 207
 208 ::
 209
 210     <input xmlns="urn:opendaylight:sxp:controller">
 211      <requested-node>127.0.0.1</requested-node>
 212      <sxp-peer-group>
 213       <name>TEST</name>
 214       <sxp-peers>
 215       </sxp-peers>
 216       <sxp-filter>
 217        <filter-type>outbound</filter-type>
 218        <acl-entry>
 219         <entry-type>deny</entry-type>
 220         <entry-seq>1</entry-seq>
 221         <sgt-start>1</sgt-start>
 222         <sgt-end>100</sgt-end>
 223        </acl-entry>
 224        <acl-entry>
 225         <entry-type>permit</entry-type>
 226         <entry-seq>45</entry-seq>
 227         <matches>1</matches>
 228         <matches>3</matches>
 229         <matches>5</matches>
 230        </acl-entry>
 231       </sxp-filter>
 232      </sxp-peer-group>
 233     </input>
 234
 235 -  Delete PeerGroup with peer-group-name from node request-node. POST
 236    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-peer-group
 237
 238 ::
 239
 240     <input xmlns="urn:opendaylight:sxp:controller">
 241      <requested-node>127.0.0.1</requested-node>
 242      <peer-group-name>TEST</peer-group-name>
 243     </input>
 244
 245 -  Get PeerGroup with peer-group-name from node request-node. POST
 246    http://127.0.0.1:8181/restconf/operations/sxp-controller:get-peer-group
 247
 248 ::
 249
 250     <input xmlns="urn:opendaylight:sxp:controller">
 251      <requested-node>127.0.0.1</requested-node>
 252      <peer-group-name>TEST</peer-group-name>
 253     </input>
 254
 255 -  Add Filter to peer group on node request-node. POST
 256    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-filter
 257
 258 ::
 259
 260     <input xmlns="urn:opendaylight:sxp:controller">
 261      <requested-node>127.0.0.1</requested-node>
 262      <peer-group-name>TEST</peer-group-name>
 263      <sxp-filter>
 264       <filter-type>outbound</filter-type>
 265       <acl-entry>
 266        <entry-type>deny</entry-type>
 267        <entry-seq>1</entry-seq>
 268        <sgt-start>1</sgt-start>
 269        <sgt-end>100</sgt-end>
 270       </acl-entry>
 271       <acl-entry>
 272        <entry-type>permit</entry-type>
 273        <entry-seq>45</entry-seq>
 274        <matches>1</matches>
 275        <matches>3</matches>
 276        <matches>5</matches>
 277       </acl-entry>
 278      </sxp-filter>
 279     </input>
 280
 281 -  Delete Filter from peer group on node request-node. POST
 282    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-filter
 283
 284 ::
 285
 286     <input xmlns="urn:opendaylight:sxp:controller">
 287      <requested-node>127.0.0.1</requested-node>
 288      <peer-group-name>TEST</peer-group-name>
 289      <filter-type>outbound</filter-type>
 290     </input>
 291
 292 -  Update Filter of the same type in peer group on node request-node.
 293    POST
 294    http://127.0.0.1:8181/restconf/operations/sxp-controller:update-filter
 295
 296 ::
 297
 298     <input xmlns="urn:opendaylight:sxp:controller">
 299      <requested-node>127.0.0.1</requested-node>
 300      <peer-group-name>TEST</peer-group-name>
 301      <sxp-filter>
 302       <filter-type>outbound</filter-type>
 303       <acl-entry>
 304        <entry-type>deny</entry-type>
 305        <entry-seq>1</entry-seq>
 306        <sgt-start>1</sgt-start>
 307        <sgt-end>100</sgt-end>
 308       </acl-entry>
 309       <acl-entry>
 310        <entry-type>permit</entry-type>
 311        <entry-seq>45</entry-seq>
 312        <matches>1</matches>
 313        <matches>3</matches>
 314        <matches>5</matches>
 315       </acl-entry>
 316      </sxp-filter>
 317     </input>
 318
 319 -  Add new SXP aware Node POST
 320    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-node
 321
 322 ::
 323
 324     <input xmlns="urn:opendaylight:sxp:controller">
 325       <node-id>1.1.1.1</node-id>
 326       <source-ip>0.0.0.0</source-ip>
 327       <timers>
 328         <retry-open-time>5</retry-open-time>
 329         <hold-time-min-acceptable>120</hold-time-min-acceptable>
 330         <delete-hold-down-time>120</delete-hold-down-time>
 331         <hold-time-min>90</hold-time-min>
 332         <reconciliation-time>120</reconciliation-time>
 333         <hold-time>90</hold-time>
 334         <hold-time-max>180</hold-time-max>
 335         <keep-alive-time>30</keep-alive-time>
 336       </timers>
 337       <mapping-expanded>150</mapping-expanded>
 338       <security>
 339         <password>password</password>
 340       </security>
 341       <tcp-port>64999</tcp-port>
 342       <version>version4</version>
 343       <description>ODL SXP Controller</description>
 344     </input>
 345
 346 -  Delete SXP aware node POST
 347    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-node
 348
 349 ::
 350
 351     <input xmlns="urn:opendaylight:sxp:controller">
 352      <node-id>1.1.1.1</node-id>
 353     </input>
 354
 355 -  Add SXP Domain on node request-node. POST
 356    http://127.0.0.1:8181/restconf/operations/sxp-controller:add-domain
 357
 358 ::
 359
 360     <input xmlns="urn:opendaylight:sxp:controller">
 361       <node-id>1.1.1.1</node-id>
 362       <domain-name>global</domain-name>
 363     </input>
 364
 365 -  Delete SXP Domain on node request-node. POST
 366    http://127.0.0.1:8181/restconf/operations/sxp-controller:delete-domain
 367
 368 ::
 369
 370     <input xmlns="urn:opendaylight:sxp:controller">
 371      <node-id>1.1.1.1</node-id>
 372      <domain-name>global</domain-name>
 373     </input>
 374
 375 -  Add Route Adds route to leader Node. PUT
 376    http://127.0.0.1:8181/restconf/config/sxp-cluster-route:sxp-cluster-route/
 377
 378 ::
 379
 380     <sxp-cluster-route xmlns="urn:opendaylight:sxp:cluster:route">
 381       <routing-definition>
 382         <ip-address>80.12.43.2</ip-address>
 383         <interface>eth1:0</interface>
 384         <netmask>255.255.255.0</netmask>
 385       </routing-definition>
 386     </sxp-cluster-route>
 387
 388 Use cases for SXP
 389 ~~~~~~~~~~~~~~~~~
 390
 391 Cisco has a wide installed base of network devices supporting SXP. By
 392 including SXP in OpenDaylight, the binding of policy groups to IP
 393 addresses can be made available for possible further processing to a
 394 wide range of devices, and applications running on OpenDaylight. The
 395 range of applications that would be enabled is extensive. Here are just
 396 a few of them:
 397
 398 OpenDaylight based applications can take advantage of the IP-SGT binding
 399 information. For example, access control can be defined by an operator
 400 in terms of policy groups, while OpenDaylight can configure access
 401 control lists on network elements using IP addresses, e.g., existing
 402 technology.
 403
 404 Interoperability between different vendors. Vendors have different
 405 policy systems. Knowing the IP-SGT binding for Cisco makes it possible
 406 to maintain policy groups between Cisco and other vendors.
 407
 408 OpenDaylight can aggregate the binding information from many devices and
 409 communicate it to a network element. For example, a firewall can use the
 410 IP-SGT binding information to know how to handle IPs based on the
 411 group-based ACLs it has set. But to do this with SXP alone, the firewall
 412 has to maintain a large number of network connections to get the binding
 413 information. This incurs heavy overhead costs to maintain all of the SXP
 414 peering and protocol information. OpenDaylight can aggregate the
 415 IP-group information so that the firewall need only connect to
 416 OpenDaylight. By moving the information flow outside of the network
 417 elements to a centralized position, we reduce the overhead of the CPU
 418 consumption on the enforcement element. This is a huge savings - it
 419 allows the enforcement point to only have to make one connection rather
 420 than thousands, so it can concentrate on its primary job of forwarding
 421 and enforcing.
 422
 423 OpenDaylight can relay the binding information from one network element
 424 to others. Changes in group membership can be propagated more readily
 425 through a centralized model. For example, in a security application a
 426 particular host (e.g., user or IP Address) may be found to be acting
 427 suspiciously or violating established security policies. The defined
 428 response is to put the host into a different source group for
 429 remediation actions such as a lower quality of service, restricted
 430 access to critical servers, or special routing conditions to ensure
 431 deeper security enforcement (e.g., redirecting the host’s traffic
 432 through an IPS with very restrictive policies). Updated group membership
 433 for this host needs to be communicated to multiple network elements as
 434 soon as possible; a very efficient and effective method of propagation
 435 can be performed using OpenDaylight as a centralized point for relaying
 436 the information.
 437
 438 OpenDaylight can create filters for exporting and receiving IP-SGT
 439 bindings used on specific peer groups, thus can provide more complex
 440 maintaining of policy groups.
 441
 442 Although the IP-SGT binding is only one specific piece of information,
 443 and although SXP is implemented widely in a single vendor’s equipment,
 444 bringing the ability of OpenDaylight to process and distribute the
 445 bindings, is a very specific immediate useful implementation of policy
 446 groups. It would go a long way to develop both the usefulness of
 447 OpenDaylight and of policy groups.