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

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