manuals/getting-started-guide/src/main/asciidoc/tsdr/tsdr-installation-guide.adoc

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