Splunk for Shoretel

 

Installation Docs

Overview

This product has several steps to the installation.  Not including the steps to download and install Splunk itself, the process is to:

  • Change user permissions inside the Shoretel Database
  • Install perform the basic configuration of several apps
    • Sideview Utils
    • DB Connect 3
    • Google Maps
    • Splunk for Shoretel
  • Configure the inputs via DB Connect 3
  • Index the data

1) Download Splunk

Download Splunk and install it on its own server. Here are some links to help you select an appropriate machine. If it’s just a demo you can put it on somewhat of a lesser machine, however be warned that Splunk will be much happier on a machine that meets their recommended hardware specs.

  1. Splunk’s System Requirements page
  2. Splunk’s Hardware Capacity Planning page.

2) Installing the apps

We will actually install 4 apps in total.  The Shoretel app and the Sideview Utils app will come from the Sideview site,  and then DBConnect and “Google Maps” we will get from apps.splunk.com.

First, download the 90 day trial version of the Splunk for Shoretel app from the app’s homepage on this website and save the *.tar.gz files locally for now.

Next download the Sideview Utils app also from this website, saving the *.tar.gz file locally as well.

Installing the two Sideview apps

Log into the Splunk UI as an admin user and navigate to “Apps > Manage Apps > Install App From File”.  Use the form on that page to upload each of the two *.tar.gz files that you downloaded from this site.   While we’ll have to restart later for other reasons, go ahead and restart splunk after the last of these two are uploaded and installed.

Installing and configuring the DBConnect 3 app

In the Apps menu click “Find more apps”.  On the following page search for “Splunk DB Connect 3” and click the “Install” button to install the “Splunk DB Connect 3” app.

This also requires you to set up the Java Runtime environment and a few other steps.

That last thing you’ll need in order to connect it to your Shoretel DB is the MySQL driver.

When finished with these steps, please confirm the following:

  • Selecting the Splunk DB Connect app shows no errors.
  • Clicking Configuration > Settings > General shows a JRE installation path and has no errors.
  • Clicking Configuration > Settings > Drivers shows a green check mark and “Yes” beside “MySQL”

Once you have a working copy of DB Connect, you should be able to proceed.

Installing and configuring the Google Maps app

Unfortunately the Google Maps app can’t be installed using the easier in-product App browser. Instead you’ll have to download it from this URL https://splunkbase.splunk.com/app/368 directly.  Once you have the downloaded file, return to “Apps > Manage Apps > Install App From File” as you did with the two Sideview apps, and upload it.

As a last prerequisite step, get a Google Maps API key from here:
https://developers.google.com/maps/documentation/javascript/get-api-key

Then edit $SPLUNK_HOME\etc\apps\maps\appserver\modules\GoogleMaps\GoogleMaps.js

Line 29 should read;
s.src =
"https://maps.google.com/maps/api/js?key=%%INSERT_API_KEY_HERE%%k&sensor=false&version=v3.6&callback=_gmapsOnLoad";


3) Setting user permissions in the Shoretel DB

There are a variety of possible ways this could be configured, but what we need is a MySQL user that has permission to read all the tables in the DB ‘shorewarecdr’.  If you have a preferred method of creating and granting access to a user for MySQL, please use it.  Otherwise, this might help get you started:

  1. Open an “Administrator” command prompt on the Shoretel server.
  2. Change the directory to the MySQL path, which defaults to C:\Program Files (x86)\Shoreline Communications\ShoreWare Server\MySQLCDR\MySQL Server\bin
  3. Launch MySQL (mysql.exe -u root -p).  Enter the MySQL root password when asked.
  4. From here,  to add a read only user  called ‘splunk’,  you would run the following command:
    mysql> GRANT SELECT ON shorewarecdr.* TO 'splunk'@'%' IDENTIFIED BY 'somePassword';

    NOTE: you should pick a real password of course, and if you prefer you can specify just the particular IP of the Splunk server instead of “%”


4) Configuring the Splunk DB Connect app

We have to now configure the Splunk DB Connect app to retrieve data from the Shoretel DB.  It will pull this data on a regular schedule.

If you aren’t already there, go to the Splunk DB Connect app in your Splunk installation.

  1. Click Configuration > Databases > Identities.
  2. Click the New Identity button on the right.
  3. Enter the following information:
    • Identity Name: shoretel_identity
    • User Name: <fill in the username of the user you created above, like … > splunk
    • Password: <fill in the password of the user you created above, like … > somePassword
    • Leave the rest at their default and click Save
  4. Click Configuration > Databases > Connections.
  5. Click the New Connection button on the right.
  6. Enter the connection information as below:
    • Connection Name: shoretel_connection. (This will be important later.)
    • Identity: select the one you just created, shoretel_identity.
    • Connection Type: to “MySQL”.
    • Host: provide the Shoretel server’s IP address or hostname.
    • Default Database: shorewarecdr. (Make sure it is all in lowercase.)
    • Port: Unless the Shoretel DB was set up in a nonstandard way on a nonstandard port, leave at its default.
    • Click Save.
    • NOTE – if you get an error about timezones being unrecognized, there is a bug in a lot of versions of the JDBC driver for MySQL that require you to…
      • Click the checkbox to “Edit JDBC URL”
      • To the end of that line, add “?serverTimezone=GMT”
      • Try saving it again.

If you get any errors here, read them closely and correct as required.  You can’t proceed with the rest of the instructions until this part works.


5) Indexing the Data

There are two types of data that the app needs.  First we will get the CDR data from Shoretel’s internal database, via our newly created remote JDBC connection and the Splunk DB Connect app.     Secondly we’ll use Splunk’s Universal Forwarder to send the TmsNcc.log data from the Shoretel server as well.

5a) Indexing CDR via remote JDBC (required)

Now that we have a working database connection as per step #4 above, we can create the actual input configurations.

Although we could create all of these using the User Interface in the DBConnect app,  it is easier to take the disabled configuration that ships with the app, copy it to DBConnect, and enable it.  Here is how:

  1. SSH or log into your Splunk host.
  2. Locate the inputs.conf.default file at $SPLUNK_HOME/etc/apps/shoretel/default/inputs.conf.default
  3. Copy the contents of this file,  and append them to the existing contents of the db_inputs.conf file over in the DBConnect app’s local directory, at $SPLUNK_HOME/etc/apps/splunk_app_db_connect/local/db_inputs.conf .
  4. If you have been following along with these instructions, we have assumed DB Connect is a fresh install.  That means your local/db_inputs.conf file was empty.  If this was not the case, just append the new material to the end of the existing file without overwriting anything.
  5. Restart Splunk.

Splunk will now index all of the historical data available, and it will also index new data as it comes in.

Validation Steps: After restarting, open the Splunk DB Connect app.  Click Data Lab > Inputs and confirm you see several inputs starting with shoretel_…  Click Health > DB Connect Input Health and

5b) Optional Extra Credit:   Indexing TmsNcc logs by installing the Splunk Universal Forwarder on the shoretel host This step is optional so feel free to come back and do this later. Log into the Shoretel server and find the directory called “Shoreline Data”, within which should be two more directories – “Call Records 2” and “Logs”. The “Logs” folder contains many log files including the TmsNcc logs.

OK. First we will tell the indexer to listen for data from the forwarder. On the indexer navigate to “Manager > Forwarding and Receiving”, and click “Configure Receiving”, then “New”, then enter “9997” as the port and submit.Now download and install the Splunk Universal Forwarder on the Shoretel server. Here are some links to help you.

  1. Deploying the Universal Forwarder on Windows using the installer.
  2. Deploying the Universal Forwarder on Windows using the command line.

When it asks you enter the IP address of your indexer, and enter 9997 as the port. If you use the windows GUI installer, leave all the data input options blank – just install the UF and tell it where the indexer is. Also remember to make sure that any firewall installed on the Splunk indexer has port 9997 open so that it can receive the data from the UF. Now log into the Universal Forwarder from the command line. From the %SPLUNK_HOME%\bin directory %SPLUNK_HOME%\bin> splunk login Default credentials are admin/changeme. We will now create our data input to get all the TmsNcc logs. %SPLUNK_HOME%\bin>splunk.exe add monitor -source “C:\Shoreline Data\Logs\TmsNcc-*.Log” -sourcetype shoretel_tmsncc -index shoretel Be careful, note that on your host the directory might be a little different or it might be on a different drive, and note that all characters are case-sensitive.

To quickly index exported TmsNcc logs, you will want to create a new Monitor data input in Splunk, to monitor your path like “C:\Shoreline Data\Logs\TmsNcc-*.Log”. If there are any other logs in the directory besides TmsNcc logs, make sure to include the wildcarded suffix in the path as you see it here. Make sure to give the data input a sourcetype of “shoretel_tmsncc” and an index of “shoretel”

6) Generating the lookup files.

This is an easy step – Log into Splunk as an admin user, navigate to the Splunk for Shoretel app, and then in the navigation bar choose “Setup > Populate Lookups”. When that page loads it will automatically pull various pieces of data from your Shoretel database and create lookups inside Splunk.   It should take several seconds or maybe a minute and then say that they have all been successfully generated.


7) Start playing around and creating reports and dashboards.

Log into the Splunk indexer using your browser, and navigate to the “Splunk for Shoretel” app. You should see no error messages and you should be able to test drive the Browse, Report, and Call Detail pages.  When you find a report or chart you like,  choose “Create > Dashboard Panel” or “Save Report”.   Explore the app.   Contact us with any questions at all, or to set up a webex for some Q&A.