docs/user-guide/alto-user-guide.rst

   1 .. _alto-user-guide:
   2
   3 ALTO User Guide
   4 ===============
   5
   6 Overview
   7 --------
   8
   9 The ALTO project is aimed to provide support for **Application Layer
  10 Traffic Optimization** services defined in `RFC
  11 7285 <https://tools.ietf.org/html/rfc7285>`__ in OpenDaylight.
  12
  13 This user guide will introduce the three basic services (namely
  14 ``simple-ird``, ``manual-maps`` and ``host-tracker``) which are
  15 implemented since the Beryllium release, and give instructions on how to
  16 configure them to provide corresponding ALTO services.
  17
  18 A new feature named ``simple-pce`` (**Simple Path Computation Engine**)
  19 is added into Boron release as an ALTO extension service.
  20
  21 How to Identify ALTO Resources
  22 ------------------------------
  23
  24 Each ALTO resource can be uniquely identified by a tuple . For each
  25 resource, a *version-tag* is used to support historical look-ups.
  26
  27 The formats of *resource-id* and *version-tag* are defined in `section
  28 10.2 <https://tools.ietf.org/html/rfc7285#section-10.2>`__ and `section
  29 10.3 <https://tools.ietf.org/html/rfc7285#section-10.3>`__ respectively.
  30 The *context-id* is not part of the protocol and we choose the same
  31 format as a *universal unique identifier* (UUID) which is defined in
  32 `RFC 4122 <http://tools.ietf.org/html/rfc4122>`__.
  33
  34 A context is like a namespace for ALTO resources, which eliminates
  35 *resource-id* collisions. For simplicity, we also provide a default
  36 context with the id **000000000000-0000-0000-0000-00000000**.
  37
  38 How to Use Simple IRD
  39 ---------------------
  40
  41 The simple IRD feature provides a simple *information resource
  42 directory* (IRD) service defined in `RFC
  43 7285 <https://tools.ietf.org/html/rfc7285#section-9>`__.
  44
  45 Install the Feature
  46 ~~~~~~~~~~~~~~~~~~~
  47
  48 To enable simple IRD, run the following command in the karaf CLI:
  49
  50 .. code:: bash
  51
  52     karaf > feature:install odl-alto-simpleird
  53
  54 After the feature is successfully installed, a special context will be
  55 created for all simple IRD resources. The id for this context can be
  56 seen by executing the following command in a terminal:
  57
  58 .. code:: bash
  59
  60     curl -X GET -u admin:admin http://localhost:8181/restconf/operational/alto-simple-ird:information/
  61
  62 Create a new IRD
  63 ~~~~~~~~~~~~~~~~
  64
  65 To create a new IRD resource, two fields MUST be provided:
  66
  67 -  Field **instance-id**: the *resource-id* of the IRD resource;
  68
  69 -  Field **entry-context**: the context-id for non-IRD entries managed
  70    by this IRD resource.
  71
  72 Using the following script, one can create an empty IRD resource:
  73
  74 .. code:: bash
  75
  76     #!/bin/bash
  77     # filename: ird-create
  78     INSTANCE_ID=$1
  79     if [ $2 ]; then
  80         CONTEXT_ID=$2
  81     else
  82         CONTEXT_ID="00000000-0000-0000-0000-000000000000"
  83     fi
  84     URL="`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$INSTANCE_ID"/[`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$INSTANCE_ID"/`]`"
  85     DATA=$(cat template \
  86       | sed 's/\$1/'$CONTEXT_ID'/g' \
  87       | sed 's/\$2/'$INSTANCE_ID'/g')
  88     curl -4 -D - -X PUT -u admin:admin \
  89       -H "Content-Type: application/json" -d "$(echo $DATA)"\
  90       $URL
  91
  92 For example, the following command will create a new IRD named *ird*
  93 which can accept entries with the default context-id:
  94
  95 .. code:: bash
  96
  97     $ ./ird-create ird 000000000000-0000-0000-0000-00000000
  98
  99 And below is the what the template file looks like:
 100
 101 .. code:: json
 102
 103     {
 104         "ird-instance-configuration": {
 105             "entry-context": "/alto-resourcepool:context[alto-resourcepool:context-id='$1']",
 106             "instance-id": "$2"
 107         }
 108     }
 109
 110 Remove an IRD
 111 ~~~~~~~~~~~~~
 112
 113 To remove an existing IRD (and all the entries in it), one can use the
 114 following command in a terminal:
 115
 116 .. code:: bash
 117
 118     curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$INSTANCE_ID
 119
 120 Add a new entry
 121 ~~~~~~~~~~~~~~~
 122
 123 There are several ways to add entries to an IRD and in this section we
 124 introduce only the simplest method. Using the following script, one can
 125 add a new entry to the target IRD.
 126
 127 For each new entry, four parameters MUST be provided:
 128
 129 -  Parameter *ird-id*: the *resource-id* of the target IRD;
 130
 131 -  Parameter *entry-id*: the *resource-id* of the ALTO service to be
 132    added;
 133
 134 -  Parameter *context-id*: the *context-id* of the ALTO service to be
 135    added, which MUST be identical to the target IRD’s *entry-context*;
 136
 137 -  Parameter *location*: either a URI or a relative path to the ALTO
 138    service.
 139
 140 The following script can be used to add one entry to the target IRD,
 141 where the relative path is used:
 142
 143 .. code:: bash
 144
 145     #!/bin/bash
 146     # filename: ird-add-entry
 147     IRD_ID=$1
 148     ENTRY_ID=$2
 149     CONTEXT_ID=$3
 150     BASE_URL=$4
 151     URL="`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$IRD_ID"/ird-configuration-entry/"$ENTRY_ID"/"
 152     DATA=$(cat template \
 153       | sed 's/\$1/'$ENTRY_ID'/g' \
 154       | sed 's/\$2/'$CONTEXT_ID'/g' \
 155       | sed 's/\$3/'$BASE_URL'/g' )
 156     curl -4 -D - -X PUT -u admin:admin \
 157       -H "Content-Type: application/json" -d "$(echo $DATA)" \
 158       $URL
 159
 160 For example, the following command will add a new resource named
 161 *networkmap*, whose context-id is the default context-id and the base
 162 URL is /alto/networkmap, to the IRD named *ird*:
 163
 164 .. code:: bash
 165
 166     $ ./ird-add-entry ird networkmap 000000000000-0000-0000-0000-00000000 /alto/networkmap
 167
 168 And below is the template file:
 169
 170 .. code:: json
 171
 172     {
 173         "ird-configuration-entry": {
 174             "entry-id": "$1",
 175             "instance": "/alto-resourcepool:context[alto-resourcepool:context-id='$2']/alto-resourcepool:resource[alto-resourcepool:resource-id='$1']",
 176             "path": "$3/$1"
 177         }
 178     }
 179
 180 Remove an entry
 181 ~~~~~~~~~~~~~~~
 182
 183 To remove an entry from an IRD, one can use the following one-line
 184 command:
 185
 186 .. code:: bash
 187
 188     curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$IRD_ID/ird-configuration-entry/$ENTRY_ID/
 189
 190 How to Use Host-tracker-based ECS
 191 ---------------------------------
 192
 193 As a real instance of ALTO services, ***alto-hosttracker*** reads data
 194 from ***l2switch*** and generates a network map with resource id
 195 ***hosttracker-network-map*** and a cost map with resource id
 196 ***hostracker-cost-map***. It can only work with OpenFlow-enabled
 197 networks.
 198
 199 After installing the ***odl-alto-hosttracker*** feature, the
 200 corresponding network map and cost map will be inserted into the data
 201 store.
 202
 203 Managing Resource with ``alto-resourcepool``
 204 --------------------------------------------
 205
 206 After installing ``odl-alto-release`` feature in Karaf,
 207 ``alto-resourcepool`` feature will be installed automatically. And you
 208 can manage all resources in ALTO via RESTCONF APIs provided by
 209 ``alto-resourcepool``.
 210
 211 With the example bash script below you can get any resource infomation
 212 in a given context.
 213
 214 .. code:: bash
 215
 216     #!/bin/bash
 217     RESOURCE_ID=$1
 218     if [ $2 ] ; then
 219         CONTEXT_ID=$2
 220     else
 221         CONTEXT_ID="00000000-0000-0000-0000-000000000000"
 222     fi
 223     URL="http://localhost:8181/restconf/operational/alto-resourcepool:context/"$CONTEXT_ID"/alto-resourcepool:resource/"$RESOURCE_ID
 224     curl -X GET -u admin:admin $URL | python -m json.tool | sed -n '/default-tag/p' | sed 's/.*:.*\"\(.*\)\".*/\1/g'
 225
 226 Manual Configuration
 227 --------------------
 228
 229 Using RESTCONF API
 230 ~~~~~~~~~~~~~~~~~~
 231
 232 After installing ``odl-alto-release`` feature in Karaf, it is possible
 233 to manage network-maps and cost-maps using RESTCONF. Take a look at all
 234 the operations provided by ``resource-config`` at the API service page
 235 which can be found at
 236 ``http://localhost:8181/apidoc/explorer/index.html``.
 237
 238 The easiest method to operate network-maps and cost-maps is to modify
 239 data broker via RESTCONF API directly.
 240
 241 Using RPC
 242 ~~~~~~~~~
 243
 244 The ``resource-config`` package also provides a query RPC to config the
 245 resources. You can CREATE, UPDATE and DELETE **network-maps** and
 246 **cost-maps** via query RPC.
 247
 248 Simple Path Computation Engine
 249 ------------------------------
 250
 251 The ``simple-pce`` module provides a simple path computation engine for
 252 ALTO and other projects. It supports basic CRUD (create, read, update,
 253 delete) operations to manage L2 and L3 routing with/without rate
 254 limitation. This module is an independent feature, so you can follow the
 255 instruction below to install it independently.
 256
 257 .. code:: bash
 258
 259     karaf > feature:install odl-alto-extenstion
 260
 261 .. note::
 262
 263     The rate limitation meter requires OpenFlow 1.3 support.
 264
 265 Basic Usage with RESTCONF API
 266 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 267
 268 You can use the simple path computation engine with RESTCONF API, which
 269 is defined in the YANG model
 270 `here <https://git.opendaylight.org/gerrit/gitweb?p=alto.git;a=blob;f=alto-extensions/simple-pce/api/src/main/yang/alto-spce.yang;h=f5bbe6744f7dfba493edd275aa18114e363727ab;hb=refs/heads/stable/boron>`__.
 271
 272 Use Case
 273 --------
 274
 275 Server Selection
 276 ~~~~~~~~~~~~~~~~
 277
 278 One of the key use case for ALTO is server selection. For example, a
 279 client (with IP address 10.0.0.1) sends a data transferring request to
 280 Data Transferring Service (DTS). And there are three data replica
 281 servers (with IP address 10.60.0.1, 10.60.0.2 and 10.60.0.3) which can
 282 response the request. In this case, DTS can send a query request to ALTO
 283 server to make server selection decision.
 284
 285 Following is an example ALTO query:
 286
 287 ::
 288
 289     POST /alto/endpointcost HTTP/1.1
 290     Host: localhost:8080
 291     Content-Type: application/alto-endpointcostparams+json
 292     Accept: application/alto-endpointcost+json,application/alto-error+json
 293     {
 294       "cost-type": {
 295         "cost-mode": "ordinal",
 296         "cost-metric": "hopcount"
 297       },
 298       "endpoints": {
 299         "srcs": [ "ipv4:10.0.0.1" ],
 300         "dsts": [
 301           "ipv4:10.60.0.1",
 302           "ipv4:10.60.0.2",
 303           "ipv4:10.60.0.3"
 304       ]
 305       }
 306     }