Splunk for Shoretel

 

Installation Docs

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. Next download the Sideview Utils app also from this website. The apps will come down as *.spl files but don’t worry about the file format – it’s just a tar.gz with a strange extension and we will install them into Splunk as-is anyway.

Installing the 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 *.spl files that you downloaded from this site.   When it prompts you to restart, you can select “Restart Later” because we have two more apps to install first. Note that the *.spl file extension is an old Splunk convention that we need to support app upload in some older Splunk versions, and that in reality these files are just tar.gz files.

Installing the DBConnect 2 app

In the Apps menu click “Find more apps”.  On the following page search for “Splunk DB Connect 2” and click the “Install” button to install the “Splunk DB Connect 2” app.   Now finally that we have all four apps installed, you can follow the prompt to restart Splunk.

Installing the Google Maps app

Unfortunately you won’t be able to install this using the in-product App browser. Instead you’ll have to download it from this URL https://splunkbase.splunk.com/app/368. Then once you have the downloaded file, return to “Apps > Manage Apps > Install App From File” as you did with the other 2 apps, and upload it.

Manually adding an API key to the Google Maps app

First get your 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

  1. We will either add a new user to the MySQL DB inside Shoretel,  or add privileges to an existing user for remote access.
  2. Open a command prompt on the shoretel server.
  3. Change the directory to the MySQL path, eg C:\Program Files (x86)\Shoreline Communications\ShoreWare Server\MySQLCDR\MySQL Server\bin
  4. Launch MySQL  ie   mysql.exe -u root -p Hit return.
  5. You will be prompted for the password of the root user as defined inside mysql.
  6. From here,  to add a read only user  called ‘splunk’,  you would run:
    > 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 DB Connect app

If you restarted through the UI, it will have brought you back to the DB Connect setup screen.  If you’re not there go to the DB Connect app under “apps” and it’ll direct you there. Make sure you have version 2.X of DB Connect and not version 1.

  1. Next you will have to download a JAR file of the Mysql Connector and place that jar file within %SPLUNK_HOME%\etc\apps\splunk_app_db_connect\bin\lib.
    Splunk’s official instructions for this step can be found here but we have found them to be less than completely reliable on Windows and we have found that only the very latest connector will work with more recent MySQL versions.
    Therefore we recommend going to the homepage for the Connector here.  Select “Platform Independent” – do NOT download the windows msi version.   In “Platform Independent”, download the zip version instead.
  2. Unzip the zip file and you will see the mysql connector jar file.  Copy this to  $SPLUNK_HOME\etc\apps\dbx\bin\lib” and restart Splunk again.
  3. Log in to Splunk as an admin user and go to the “Splunk DB Connect 2” app.
  4. Under “Identities” on the left,  go ahead and add a new identity matching the username and password that you just created or selected in the MySQL command line tool.
  5. Next under “Connections” you will create a new connection.
    1. For the connection name enter “shoretel_connection”. This will be important later.
    2. Set the host to be the host of your Shoretel server.
    3. Set the “Database Type” to “MySQL”. 
    4. In the “Default Database” field you can enter “shorewarecdr”. Make sure it is all in lowercase.  
    5. For “Identity”, choose the identity that you just created in DBConnect.
    6. Unless the shoretel DB was set up in a nonstandard way on a nonstandard port, you should leave the port field blank.
    7. Last but not least, leave “Read only” checked.
    8. submit the form.
  6. Assuming the validation on the next page succeeds, at this point we have a working JDBC connection to the database, but we aren’t actually pulling any information in yet.

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.     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) OK we now have a working database connection.  Now we need to 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 inputs.conf file over in the DBConnect app’s local directory, at $SPLUNK_HOME/etc/apps/splunk_app_db_connect/local/inputs.conf .
  4. Take care not to alter any of the lines that already exist in the DBConnect file, as the existing config there represents some of our work from the previous steps.
  5. restart Splunk.

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

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.