manuals/user-guide/src/main/asciidoc/alto/alto-user-guide.adoc

   1 == ALTO User Guide ==
   2
   3 === Overview ===
   4
   5 The ALTO project is aimed to provide support for *Application Layer
   6 Traffic Optimization* services defined in
   7 https://tools.ietf.org/html/rfc7285[RFC 7285] in OpenDaylight.
   8
   9 This user guide will introduce the three basic services (namely
  10 `simple-ird`, `manual-maps` and `host-tracker`) which are implemented in
  11 the Beryllium release, and give instructions on how to configure them to
  12 provide corresponding ALTO services.
  13
  14 === How to Identify ALTO Resources ===
  15
  16 Each ALTO resource can be uniquely identified by a tuple . For each
  17 resource, a _version-tag_ is used to support historical look-ups.
  18
  19 The formats of _resource-id_ and _version-tag_ are defined in
  20 https://tools.ietf.org/html/rfc7285#section-10.2[section 10.2] and
  21 https://tools.ietf.org/html/rfc7285#section-10.3[section 10.3]
  22 respectively. The _context-id_ is not part of the protocol and we choose
  23 the same format as a _universal unique identifier_ (UUID) which is
  24 defined in http://tools.ietf.org/html/rfc4122[RFC 4122].
  25
  26 A context is like a namespace for ALTO resources, which eliminates
  27 _resource-id_ collisions. For simplicity, we also provide a default
  28 context with the id **000000000000-0000-0000-0000-00000000**.
  29
  30 === How to Use Simple IRD ===
  31
  32 The simple IRD feature provides a simple _information resource
  33 directory_ (IRD) service defined in
  34 https://tools.ietf.org/html/rfc7285#section-9[RFC 7285].
  35
  36 ==== Install the Feature ====
  37
  38 To enable simple IRD, run the following command in the karaf CLI:
  39
  40 [source,bash]
  41 karaf > feature:install odl-alto-simpleird
  42
  43 After the feature is successfully installed, a special context will be
  44 created for all simple IRD resources. The id for this context can be
  45 seen by executing the following command in a terminal:
  46
  47 [source,bash]
  48 curl -X GET -u admin:admin http://localhost:8181/restconf/operational/alto-simple-ird:information/
  49
  50 ==== Create a new IRD ====
  51
  52 To create a new IRD resource, two fields MUST be provided:
  53
  54 * Field **instance-id**: the _resource-id_ of the IRD resource;
  55 * Field **entry-context**: the context-id for non-IRD entries managed by
  56 this IRD resource.
  57
  58 Using the following script, one can create an empty IRD resource:
  59
  60 [source,bash]
  61 #!/bin/bash
  62 # filename: ird-create
  63 INSTANCE_ID=$1
  64 if [ $2 ]; then
  65     CONTEXT_ID=$2
  66 else
  67     CONTEXT_ID="00000000-0000-0000-0000-000000000000"
  68 fi
  69 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"/`]`"
  70 DATA=$(cat template \
  71   | sed 's/\$1/'$CONTEXT_ID'/g' \
  72   | sed 's/\$2/'$INSTANCE_ID'/g')
  73 curl -4 -D - -X PUT -u admin:admin \
  74   -H "Content-Type: application/json" -d "$(echo $DATA)"\
  75   $URL
  76
  77 For example, the following command will create a new IRD named _ird_
  78 which can accept entries with the default context-id:
  79
  80 [source,bash]
  81 $ ./ird-create ird 000000000000-0000-0000-0000-00000000
  82
  83 And below is the what the template file looks like:
  84
  85 [source,json]
  86 {
  87     "ird-instance-configuration": {
  88         "entry-context": "/alto-resourcepool:context[alto-resourcepool:context-id='$1']",
  89         "instance-id": "$2"
  90     }
  91 }
  92
  93 ==== Remove an IRD ====
  94
  95 To remove an existing IRD (and all the entries in it), one can use the
  96 following command in a terminal:
  97
  98 [source,bash]
  99 curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$INSTANCE_ID
 100
 101 ==== Add a new entry ====
 102
 103 There are several ways to add entries to an IRD and in this section we
 104 introduce only the simplest method. Using the following script, one can
 105 add a new entry to the target IRD.
 106
 107 For each new entry, four parameters MUST be provided:
 108
 109 * Parameter __ird-id__: the _resource-id_ of the target IRD;
 110 * Parameter __entry-id__: the _resource-id_ of the ALTO service to be
 111 added;
 112 * Parameter __context-id__: the _context-id_ of the ALTO service to be
 113 added, which MUST be identical to the target IRD's __entry-context__;
 114 * Parameter __location__: either a URI or a relative path to the ALTO
 115 service.
 116
 117 The following script can be used to add one entry to the target IRD,
 118 where the relative path is used:
 119
 120 [source,bash]
 121 #!/bin/bash
 122 # filename: ird-add-entry
 123 IRD_ID=$1
 124 ENTRY_ID=$2
 125 CONTEXT_ID=$3
 126 BASE_URL=$4
 127 URL="`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$IRD_ID"/ird-configuration-entry/"$ENTRY_ID"/"
 128 DATA=$(cat template \
 129   | sed 's/\$1/'$ENTRY_ID'/g' \
 130   | sed 's/\$2/'$CONTEXT_ID'/g' \
 131   | sed 's/\$3/'$BASE_URL'/g' )
 132 curl -4 -D - -X PUT -u admin:admin \
 133   -H "Content-Type: application/json" -d "$(echo $DATA)" \
 134   $URL
 135
 136 For example, the following command will add a new resource named
 137 __networkmap__, whose context-id is the default context-id and the base
 138 URL is /alto/networkmap, to the IRD named __ird__:
 139
 140 [source,bash]
 141 $ ./ird-add-entry ird networkmap 000000000000-0000-0000-0000-00000000 /alto/networkmap
 142
 143 And below is the template file:
 144
 145 [source,json]
 146 {
 147     "ird-configuration-entry": {
 148         "entry-id": "$1",
 149         "instance": "/alto-resourcepool:context[alto-resourcepool:context-id='$2']/alto-resourcepool:resource[alto-resourcepool:resource-id='$1']",
 150         "path": "$3/$1"
 151     }
 152 }
 153
 154 ==== Remove an entry ====
 155
 156 To remove an entry from an IRD, one can use the following one-line
 157 command:
 158
 159 [source,bash]
 160 curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$IRD_ID/ird-configuration-entry/$ENTRY_ID/
 161
 162 === How to Use Host-tracker-based ECS ===
 163
 164 As a real instance of ALTO services, *_alto-hosttracker_* reads data
 165 from *_l2switch_* and generates a network map with resource id
 166 *_hosttracker-network-map_* and a cost map with resource id
 167 *_hostracker-cost-map_*. It can only work with OpenFlow-enabled
 168 networks.
 169
 170 After installing the *_odl-alto-hosttracker_* feature, the corresponding
 171 network map and cost map will be inserted into the data store.
 172
 173 === Managing Resource with `alto-resourcepool` ===
 174
 175 After installing `odl-alto-release` feature in Karaf, `alto-resourcepool` feature
 176 will be installed automatically. And you can manage all resources in ALTO via
 177 RESTCONF APIs provided by `alto-resourcepool`.
 178
 179 With the example bash script below you can get any resource infomation in a
 180 given context.
 181
 182 [source,bash]
 183 #!/bin/bash
 184 RESOURCE_ID=$1
 185 if [ $2 ] ; then
 186         CONTEXT_ID=$2
 187 else
 188         CONTEXT_ID="00000000-0000-0000-0000-000000000000"
 189 fi
 190 URL="http://localhost:8181/restconf/operational/alto-resourcepool:context/"$CONTEXT_ID"/alto-resourcepool:resource/"$RESOURCE_ID
 191 curl -X GET -u admin:admin $URL | python -m json.tool | sed -n '/default-tag/p' | sed 's/.*:.*\"\(.*\)\".*/\1/g'
 192
 193 === Manual Configuration ===
 194
 195 ==== Using RESTCONF API ====
 196
 197 After installing `odl-alto-release` feature in Karaf, it is possible to manage
 198 network-maps and cost-maps using RESTCONF. Take a look at all the operations
 199 provided by `resource-config` at the API service page which can be found at
 200 `http://localhost:8181/apidoc/explorer/index.html`.
 201
 202 The easiest method to operate network-maps and cost-maps is to modify data broker
 203 via RESTCONF API directly.
 204
 205 ==== Using RPC ====
 206
 207 The `resource-config` package also provides a query RPC to config the resources.
 208 You can CREATE, UPDATE and DELETE *network-maps* and *cost-maps* via query RPC.
 209
 210 === Use Case ===
 211
 212 ==== Server Selection ====
 213
 214 One of the key use case for ALTO is server selection. For example, a client (with
 215 IP address 10.0.0.1) sends a data transferring request to Data Transferring Service
 216 (DTS). And there are three data replica servers (with IP address 10.60.0.1, 10.60.0.2
 217 and 10.60.0.3) which can response the request. In this case, DTS can send a query
 218 request to ALTO server to make server selection decision.
 219
 220 Following is an example ALTO query:
 221
 222 [source]
 223 POST /alto/endpointcost HTTP/1.1
 224 Host: localhost:8080
 225 Content-Type: application/alto-endpointcostparams+json
 226 Accept: application/alto-endpointcost+json,application/alto-error+json
 227 {
 228   "cost-type": {
 229     "cost-mode": "ordinal",
 230     "cost-metric": "hopcount"
 231   },
 232   "endpoints": {
 233     "srcs": [ "ipv4:10.0.0.1" ],
 234     "dsts": [
 235       "ipv4:10.60.0.1",
 236       "ipv4:10.60.0.2",
 237       "ipv4:10.60.0.3"
 238   ]
 239   }
 240 }