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

   1 == ALTO User Guide
   2
   3 === Overview
   4 The ALTO project provides support for _Application Layer Traffic
   5 Optimization_ services defined in link:https://tools.ietf.org/html/rfc7285[RFC
   6 7285].
   7
   8 In the Lithium release, ALTO uses the YANG model described in
   9 link:https://tools.ietf.org/html/draft-shi-alto-yang-model-03[this draft].
  10
  11 === ALTO Architecture
  12
  13 There are three kinds of ALTO packages in OpenDaylight.
  14
  15 . **Core**
  16 The **core** packages include:
  17 .. `alto-model`: Defines the YANG model of ALTO services in MD-SAL
  18 .. `service-api-rfc7285`: Defines interfaces for ALTO services in AD-SAL
  19 .. `alto-northbound`: Implements the RFC7285-compatible RESTful API
  20 . **Basic**
  21 The **basic** packages include:
  22 .. Basic implementations of ALTO services:
  23 ... `alto-provider`: Implements the services defined in `alto-model`
  24 ... `simple-impl`: Implements the services defined in `service-api-rfc7285`
  25 .. Utilities:
  26 ... `alto-manager`: Provides a karaf command line tool to manipulate network
  27 maps and cost maps.
  28 . **Service**
  29 The **service** packages include:
  30 .. `alto-hosttracker`: Generates a network map, a corresponding cost map and
  31 the endpoint cost service based on <<_l2switch_user_guide, l2switch>>.
  32
  33 === Configuring ALTO
  34
  35 There are three packages that require their own configuration files,
  36 including `alto-provider`, `alto-hosttracker` and `simple-impl`. However, the
  37 only configurable option is the type of the data broker in all three
  38 configuration files.
  39
  40 === Administering or Managing ALTO
  41
  42 To enable ALTO, the features must be installed first.
  43
  44 [source,bash]
  45 karaf > feature:install odl-alto-provider
  46 karaf > feature:install odl-alto-manager
  47 karaf > feature:install odl-alto-northbound
  48 karaf > feature:install odl-alto-hosttracker
  49
  50 ==== Managing Data with RESTCONF
  51
  52 After installing `odl-alto-provider` feature in karaf, it is possible to manage
  53 network-maps and cost-maps using RESTCONF. Take a look at all the operations
  54 provided by `alto-model` at the API service page which can be found at
  55 `http://localhost:8181/apidoc/explorer/index.html`.
  56
  57 With the example input below you can insert a network map into the data store,
  58 either by filling the form in the API doc page, or by using tools such as `curl`.
  59
  60 [source,bash]
  61 HOST_IP=localhost                   # IP address of the controller
  62 CREDENTIAL=admin:admin              # username and password for authentication
  63 BASE_URL=$HOST_IP:8181/restconf/config
  64 SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
  65 RESOURCE_ID=test_odl                # Should match the one in the input file
  66 curl -X PUT -H "content-type:application/yang.data+json" \
  67             -d @example-input.json -u $CREDENTIAL \
  68             http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
  69
  70 [source,json]
  71 include::example-input.json[]
  72
  73 [[read-restconf]]Use the following command to see the results:
  74
  75 [source,bash]
  76 HOST_IP=localhost                   # IP address of the controller
  77 CREDENTIAL=admin:admin              # username and password for authentication
  78 BASE_URL=$HOST_IP:8181/restconf/config
  79 SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
  80 RESOURCE_ID=test_odl
  81 curl -X GET -u $CREDENTIAL http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
  82
  83 Use `DELETE` method to remove the data from the data store.
  84
  85 [source,bash]
  86 HOST_IP=localhost                   # IP address of the controller
  87 CREDENTIAL=admin:admin              # username and password for authentication
  88 BASE_URL=$HOST_IP:8181/restconf/config
  89 SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
  90 RESOURCE_ID=test_odl
  91 curl -X DELETE -H "content-type:application/yang.data+json" \
  92                -u $CREDENTIAL http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
  93
  94 ==== Using `alto-manager`
  95
  96 The `alto-manager` package provides a karaf command line tool which wraps up
  97 the functions described in the last section.
  98
  99 [source,bash]
 100 karaf > alto-create <type> <resource-file>
 101 karaf > alto-delete <type> <resource-id>
 102
 103 Currently only `network-map` and `cost-map` are supported. Also the resource
 104 files used in `alto-manager` follow the RFC7285-compatible format instead of
 105 RESTCONF format.
 106
 107 The following example shows how to use `alto-manager` to put a network map into
 108 the data store.
 109
 110 [source,bash]
 111 karaf > alto-create network-map example-rfc7285-networkmap.json
 112
 113 [source,json]
 114 include::example-rfc7285-networkmap.json[]
 115
 116 ==== Using `alto-hosttracker`
 117
 118 As a real instance of ALTO services, `alto-hosttracker` reads data from
 119 `l2switch` and generates a network map with resource id
 120 `hosttracker-network-map` and a cost map with resource id `hostracker-cost-map`.
 121 It can only work with OpenFlow-enabled networks.
 122
 123 After installing the `odl-alto-hosttracker` feature, the corresponding network
 124 map and cost map will be inserted into the data store. Follow the steps in
 125 <<read-restconf, how to read data with RESTCONF>> to see the contents.