Splunk® DB Connect

Deploy and Use Splunk DB Connect

Download manual as PDF

NOTE - Splunk DB Connect version 1.x reached its End of Life on July 28, 2016. Please see the migration information.
This documentation does not apply to the most recent version of DBX. Click here for the latest version.
Download topic as PDF

Set up search head pooling

Note: The search head pooling feature has been deprecated as of Splunk Enterprise version 6.2. This means that although it continues to function, it might be removed in a future version.

If you're using search head pooling with Splunk DB Connect, you must run the dbx_shpinst.py script against each search head for each database connection to ensure that the database password is encrypted with the Splunk secret key for that particular search head.

While you can install and configure Splunk DB Connect on a single search head, in a pooling environment, the app state is written to shared storage and is visible to all search heads.

In addition, the Java Server Bridge will work only on the search head on which the database connection is configured (because the password is encrypted with that particular search head's secret key).

To make the Java Bridge Server work on all search heads, you must run the dbx_shpinst.py script against each search head and each database connection. See example below.

Set up search head pooling for Splunk DB Connect

These instructions assume you have already created a search head pooling environment. If you have not yet done so, see Create a search head pool for complete instructions.

To setup search head pooling for Splunk DB Connect:

On each search head:

  1. Install JRE in the same location. The java path must be the same on each search head. (To see if your database requires JDBC driver installation, see Install database drivers.)
  2. Make sure the Java Bridge Server port is open in $SPLUNK_HOME/etc/apps/dbx/local/java.conf

On any search head:

  1. Install and configure the Splunk DB Connect app. This includes creating a database connection for each database. For instructions on how to install apps in a search head pooling environment, see Create a search head pool. Note: The database connection name will be the same on each search head.
  2. Run the dbx_shpinst.py script against each search head, as follows:
./splunk cmd python <path_to_shared_storage>/etc/apps/dbx/bin/dbx_shpinst.py <searchHeadHost>:<searchHeadHostPort> --user <userName> --targetuser <targetUserName> --db <databaseName>

splunk password:
database password:

The userName must belong to the Admin role and targetUserName must have permission to access databaseName.

If --user is admin, you don't need to specify --targetuser. The --targetuser is the Splunk user (not database user) under whose context a database configuration is stored. By default, --targetuser is "nobody." Specify --targetuser only if you need to locate a db configuration that is stored in a specific Splunk user context. For example:

./splunk cmd python <path_to_shared_storage>/etc/apps/dbx/bin/dbx_shpinst.py localhost:8089 --user julian --targetuser admin --db oracle

splunk password:
database password:

Note: You must rerun the dbx_shpinst.py script against each search head for every subsequent database password change.


This example shows you how to setup search head pooling for a Splunk DB Connect deployment that includes 3 search heads and 2 database connections.

First, we setup search head pooling for our 3 search heads, as shown in Create a search head pool.

Next, we create 2 database connections on search head 1. The other two search heads pick up the database configuration from shared storage used by search head pooling.

Here we see the configuration of each database connection in /<path_to_shared_storage>/etc/apps/dbx/local/database.conf:

database = dbxtest 
host = 
password = enc:CDr9SiQKgXhss4JDRxb7vQ== 
readonly = 1 
type = mssql 
username = sa

database = orders 
host = 
password = enc:pDWbcIFP7iPt11cDHMe9Zw== 
port = 9408 
readonly = 1 
type = mysql 
username = mktadmin 
disabled = 0 

Complete the following tasks on each search head where the DB Connect app will be used to connect to the above databases:

1. Execute the dbx_shpinst.py script from search head $SPLUNK_HOME/bin, as shown:

./splunk cmd python /<path_to_shared_storage>/etc/apps/dbx/bin/dbx_shpinst.py <searchHeadHost>:<searchHeadHostPort> --user <userName> --db <databaseName>

For example:

./splunk cmd python /<path_to_shared_storage>/etc/apps/dbx/bin/dbx_shpinst.py splunksh01:8089 --user admin --db MSSQL

You will then be prompted to enter passwords for splunk user (--user) and database user.

Once dbx_shpinst.py has successfully executed, the following message appears:

Password at <searchHeadHost> set successfully.

Note: You must repeat step 1 on each search head for each database connection.

2. Verify that a distributed.conf file has been created under the search pool location /<path_to_shared_storage>/etc/apps/dbx/local/.

After repeating step 1 for all 3 search heads and 2 database connections, our /<path_to_shared_storage>/etc/apps/dbx/local/distributed.conf should look like this:

password = enc:CDr9SiQKgXhss4JDRxb7vQ== 
readonly = 1 

password = enc:pDWbcIFP7iPt11cDHMe9Zw== 
readonly = 1 

password = enc:WE44Q8qoC8Lm8roTDE5SvQ== 
readonly = 1 

password = enc:QOcS2rA2GcfSjq+3HoHtTw== 
readonly = 1 

password = enc:EnYgSEcf+dfskTOSlcAzWw== 
readonly = 1 

password = enc:RbQQeXTUPYYL/FBHPMCBjQ== 
readonly = 1 

This distributed.conf file will be used by the db connect instances on the search heads to decrypt the database connection passwords. Since each search uses its own secret key, the password strings should be different.

Security and access controls
Use database search commands

This documentation applies to the following versions of Splunk® DB Connect: 1.1, 1.1.1, 1.1.2, 1.1.3, 1.1.4, 1.1.5, 1.1.6, 1.1.7, 1.2.0, 1.2.1, 1.2.2


few comments to help...<br /><br />>>Make sure the Java Bridge Server port is open in $SPLUNK_HOME/etc/apps/dbx/local/java.conf<br />this is confusing under the chapter "on each search head" as dbx is only installed on one of them and as it's pooled app it goes in the shared folder by default... so this should be updated<br />//etc/apps/dbx/local/java.conf<br /><br />>>2. Verify that a distributed.conf file has been created under the search pool location >>//etc/apps/dbx/etc/.<br />>>//etc/apps/dbx/etc/distributed.conf should look like this:<br /><br />on those 2 lines path should be /etc/apps/dbx/local... instead of /etc/apps/dbx/etc<br /><br />You might want to indicate a procedure in case admin use shared secret key (making ldap auth easier) as it simplify the making of the distributed.conf.<br /><br />Also the script dvx_shpinst.py always setup readonly=1 even if database.conf specify readonly=0 on the 1st search head.

February 6, 2014

Jamie, <br /><br />Thanks for your feedback on this. We've recently updated this topic and integrated your suggestions into our revisions.

Sroback splunk
December 17, 2013

Whoops! dbx_shpinst.py, not dvx_shpinst.py

October 18, 2013

You might need to specify absolute path to the dvx_shpinst.py script.<br />searchHeadHostPort should be the 8089 management port, not the 8000 web-interface port<br />user should be a user with the admin role<br />targetuser should be a user with write-access to the DBConnect config item for the database connection<br />databaseName should be the name of the DBConnect config item- surround it in ""s if the config item has a space in it<br /><br />Jamie

October 18, 2013

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters