docs/getting-started-guide/project-specific-guides/tsdr.rst

   1 TSDR Installation Guide
   2 =======================
   3
   4 This document is for the user to install the artifacts that are needed
   5 for using Time Series Data Repository (TSDR) functionality in the ODL
   6 Controller by enabling either an HSQLDB, HBase, or Cassandra Data Store.
   7
   8
   9 Overview
  10 --------
  11
  12 The Time Series Data Repository (TSDR) project in OpenDaylight (ODL) creates a framework for collecting, storing, querying, and maintaining time series data in the OpenDaylight SDN controller. Please refer to the User Guide for the detailed description of the functionality of the project and how to use the corresponding features provided in TSDR.
  13
  14 Pre Requisites for Installing TSDR
  15 ----------------------------------
  16
  17 The software requirements for TSDR HBase Data Store are as follows:
  18
  19 * In the case when the user chooses HBase or Cassandra data store, besides the software that ODL requires, we also require HBase and Cassandra database running in single node deployment scenario.
  20
  21 No additional software is required for the HSQLDB Data Stores.
  22
  23 Preparing for Installation
  24 --------------------------
  25
  26 * When using HBase data store,  download HBase from the following website:
  27
  28  http://archive.apache.org/dist/hbase/hbase-0.94.15/
  29
  30 * When using Cassandra data store, download Cassandra from the following website:
  31
  32  http://www.eu.apache.org/dist/cassandra/2.1.10/
  33
  34 * No additional steps are required to install the TSDR HSQL Data Store.
  35
  36 Installing TSDR Data Stores
  37 ---------------------------
  38
  39 Installing HSQLDB Data Store
  40 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  41
  42 Once OpenDaylight distribution is up, from karaf console install the HSQLDB data store using the following command::
  43
  44    feature:install odl-tsdr-hsqldb-all
  45
  46 This will install hsqldb related dependency features (and can take sometime) as well as openflow statistics collector before returning control to the console.
  47
  48
  49 Installing HBase Data Store
  50 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  51
  52 Installing TSDR HBase Data Store contains two steps:
  53
  54 #. Installing HBase server, and
  55 #. Installing TSDR HBase Data Store features from ODL Karaf console.
  56
  57 In Beryllium, we only support HBase single node running together on the same machine as OpenDaylight. Therefore, follow the steps to download and install HBase server onto the same machine as where OpenDaylight is running:
  58
  59 #. Create a folder in Linux operating system for the HBase server. For example, create an hbase directory under ``/usr/lib``::
  60
  61       mkdir /usr/lib/hbase
  62
  63 #. Unzip the downloaded HBase server tar file.
  64
  65    Run the following command to unzip the installation package::
  66
  67       tar xvf <hbase-installer-name>  /usr/lib/hbase
  68
  69 #. Make proper changes in hbase-site.xml
  70
  71    #. Under <hbase-install-directory>/conf/, there is a hbase-site.xml. Although it is not recommended, an experienced user with HBase can modify the data directory for hbase server to store the data.
  72
  73    #. Modify the value of the property with name "hbase.rootdir" in the file to reflect the desired file directory for storing hbase data.
  74
  75       The following is an example of the file::
  76
  77          <configuration>
  78            <property>
  79              <name>hbase.rootdir</name>
  80              <value>file:///usr/lib/hbase/data</value>
  81            </property>
  82            <property>
  83              <name>hbase.zookeeper.property.dataDir</name>
  84              <value>/usr/lib/hbase/zookeeper</value>
  85            </property>
  86          </configuration>
  87
  88 #. start hbase server::
  89
  90       cd <hbase-installation-directory>
  91       ./start-hbase.sh
  92
  93 #. start hbase shell::
  94
  95       cd <hbase-insatllation-directory>
  96       ./hbase shell
  97
  98 #. start Karaf console
  99
 100 #. install hbase data store feature from Karaf console::
 101
 102        feature:install odl-tsdr-hbase
 103
 104 Installing Cassandra Data Store
 105 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 106
 107 Installing TSDR Cassandra Data Store contains two steps:
 108
 109 #. Installing Cassandra server, and
 110 #. Installing TSDR Cassandra Data Store features from ODL Karaf console.
 111
 112 In Beryllium, we only support Cassadra single node running together on the same machine as OpenDaylight. Therefore, follow these steps to download and install Cassandra server onto the same machine as where OpenDaylight is running:
 113
 114 #. Install Cassandra (latest stable version) by downloading the zip file and untar the tar ball to cassandra/ directory on the testing machine::
 115
 116       mkdir cassandra
 117       wget http://www.eu.apache.org/dist/cassandra/2.1.10/apache-cassandra-2.1.10-bin.tar.gz[2.1.10 is current stable version, it can vary]
 118       mv apache-cassandra-2.1.10-bin.tar.gz cassandra/
 119       cd cassandra
 120       tar -xvzf apache-cassandra-2.1.10-bin.tar.gz
 121
 122 #. Start Cassandra from cassandra directory by running::
 123
 124       ./apache-cassandra-2.1.10/bin/cassandra
 125
 126 #. Start cassandra shell by running::
 127
 128       ./apache-cassandra-2.1.10/bin/cqlsh
 129
 130 #. Start Karaf according to the instructions above.
 131
 132 #. Install Cassandra data store feature from Karaf console::
 133
 134       feature:install odl-tsdr-cassandra
 135
 136 Verifying your Installation
 137 ---------------------------
 138
 139 After the TSDR data store is installed, no matter whether it is HBase data store, Cassandra data store, or HSQLDB data store, the user can verify the installation with the following steps.
 140
 141 #. Verify if the following two tsdr commands are available from Karaf console::
 142
 143       tsdr:list
 144       tsdr:purgeAll
 145
 146 #. Verify if openflow statisitcs data can be received successfully:
 147
 148    #. Run "feature:install odl-tsdr-openflow-statistics-collector" from Karaf.
 149
 150    #. Run mininet to connect to ODL controller. For example, use the following command to start a three node topology::
 151
 152          mn --topo single,3  --controller 'remote,ip=172.17.252.210,port=6653' --switch ovsk,protocols=OpenFlow13
 153
 154    #. From Karaf console, the user should be able to retrieve the statistics data of OpenFlow statistics data from the console::
 155
 156          tsdr:list FLOWSTATS
 157
 158 Troubleshooting
 159 ^^^^^^^^^^^^^^^
 160
 161 Check the ``../data/log/karaf.log`` for any exception related to TSDR features.
 162
 163 Post Installation Configuration
 164 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 165
 166 Post Installation Configuration for HSQLDB Data Store
 167 """""""""""""""""""""""""""""""""""""""""""""""""""""
 168
 169 The feature installation takes care of automated configuration of the datasource by installing a file in <install folder>/etc named org.ops4j.datasource-metric.cfg. This contains the default location of <install folder>/tsdr where the HSQLDB datastore files are stored. If you want to change the default location of the datastore files to some other location update the last portion of the url property in the org.ops4j.datasource-metric.cfg and then restart the Karaf container.
 170
 171 Post Installation Configuration for HBase Data Store
 172 """"""""""""""""""""""""""""""""""""""""""""""""""""
 173
 174 Please refer to HBase Data Store User Guide.
 175
 176 Post Installation Configuration for Cassandra Data Store
 177 """"""""""""""""""""""""""""""""""""""""""""""""""""""""
 178
 179 There is no post configuration for TSDR Cassandra data store.
 180
 181 Upgrading From a Previous Release
 182 ---------------------------------
 183
 184 The HBase data store was supported in the previous release as well as in this release. However, we do not support data store upgrade for HBase data store.
 185 The user needs to reinstall TSDR and start to collect data in TSDR HBase datastore after the installation.
 186
 187 HSQLDB and Cassandra are new data stores introduced in this release. Therefore, upgrading from previous release does not apply in these two data store scenarios.
 188
 189 Uninstalling TSDR Data Stores
 190 -----------------------------
 191
 192 To uninstall TSDR HSQLDB data store
 193 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 194
 195 To uninstall the TSDR functionality with the default store, you need to do the following from karaf console::
 196
 197    feature:uninstall odl-tsdr-hsqldb-all
 198    feature:uninstall odl-tsdr-core
 199    feature:uninstall odl-tsdr-hsqldb
 200    feature:uninstall odl-tsdr-openflow-statistics-collector
 201
 202 It is recommended to restart the Karaf container after the uninstallation of the TSDR functionality with the default store.
 203
 204 To uninstall TSDR HBase Data Store
 205 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 206
 207 To uninstall the TSDR functionality with the HBase data store,
 208
 209 * Uninstall HBase data store related features from karaf console::
 210
 211      feature:uninstall odl-tsdr-hbase
 212      feature:uninstall odl-tsdr-core
 213
 214 *  stop hbase server::
 215
 216       cd <hbase-installation-directory>
 217       ./stop-hbase.sh
 218
 219 * remove the file directory that contains the HBase server installation::
 220
 221       rm -r <hbase-installation-directory>
 222
 223 It is recommended to restart the Karaf container after the uninstallation of the TSDR data store.
 224
 225 To uninstall TSDR Cassandra Data Store
 226 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 227
 228 To uninstall the TSDR functionality with the Cassandra store,
 229
 230 * uninstall cassandra data store related features following from karaf console::
 231
 232      feature:uninstall odl-tsdr-cassandra
 233      feature:uninstall odl-tsdr-core
 234
 235 * stop cassandra database::
 236
 237      ps auwx | grep cassandra
 238      sudo kill pid
 239
 240 * remove the cassandra installation files::
 241
 242      rm <cassandra-installation-directory>
 243
 244 It is recommended to restart the Karaf container after uninstallation of the TSDR data store.