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

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