Download and install the JDBC driver file

Download the JDBC driver for the database you want to add, and copy the .JAR file to the $SPLUNK_HOME/etc/apps/splunk_app_db_connect/drivers directory (%SPLUNK_HOME%\etc\apps\splunk_app_db_connect\drivers on Windows hosts).

Add the custom database to db_connection_types.conf

When you add a custom database connection that Splunk DB Connect does not support by default, you must create a stanza to define the database connection in a copy of db_connection_types.conf under $SPLUNK_HOME/etc/apps/splunk_app_db_connect/local (%SPLUNK_HOME%\etc\apps\splunk_app_db_connect\local on Windows hosts), for example

 displayName = $your database name$
 serviceClass = com.splunk.dbx2.DefaultDBX2JDBC
 jdbcDriverClass = $JDBC driver class$
 jdbcUrlFormat = $JDBC URI Format$
 ui_default_catalog = $database$

For more information, see Configuration file reference.

Database connection validation

Each time DB Connect uses a database connection, it tries to validate that the database connection is actually working. If validation fails, you might see an error message, such as "ValidateObject failed".

DB Connect uses these two methods to validate a connection:

1. If a testQuery is specified in db_connection_types.conf, DB Connect executes that query, and receives a response that validates that the connection is working.
2. If testQuery is not specified, DB Connect uses the Java method connection.isValid(), and relies on the JDBC driver to answer. Some JDBC drivers do not implement this API call. (For instance, Apache Derby was built against Java 1.5, where JDBC doesn't have the method isValid.) The workaround is to specify a manual testQuery, such as SELECT 1.

After you add the custom database driver, continue with either the single server or distributed deployment instructions.

Enable SSL for your database connection

DB Connect has built-in support for connecting via SSL to several supported databases. Though other supported databases may support SSL connections, DB Connect support for SSL means that Splunk has tested SSL for that database type and supports connecting over SSL using DB Connect.

If you want to deploy DB Connect in Splunk Cloud. You must enable SSL connection for your database. See supported database matrix for the database supported for cloud deployment.

DB Connect will detect whether it supports SSL for your database type,

• If DB Connect supports SSL connections for your database type, enabling an SSL connection is easy. When you create a new database connection, select the Enable SSL checkbox.
• If DB Connect does not natively support SSL for your database type, you cannot select the Enable SSL checkbox in connection settings, it is grey out. However, you can add in SSL support by selecting Edit JDBC URL and editing the URL. Be aware that Splunk cannot certify that databases for which DB Connect does not have native support for SSL will connect via SSL correctly. Splunk Support will not help you troubleshoot such connections.

The possibility to configure one-way SSL authentication from the UI was added for MySQL, MSSQL and Oracle databases. While creating a connection users will be able to pass a certificate which will be automatically added to the Java TrustStore and used for the server authentication. If the Enable SSL checkbox will be selected, but the certificate field would be empty - DB Connect will ignore it and work as before.

To improve security following some properties have been removed from the default connection properties. The full list of changes can be found below.

1. MySQL - {"verifyServerCertificate":"false"}
2. MS-SQL Server Using MS Generic Driver - {"trustServerCertificate":"true"}
3. MS-SQL Server Using MS Generic Driver With Windows Authentication - {"trustServerCertificate":"true"}
4. MS-SQL Server Using MS Generic Driver With Kerberos Authentication - {"trustServerCertificate":"true"}
5. Oracle - {"oracle.net.authentication_services":"(TCPS)","oracle.net.ssl_cipher_suites":"(SSL_DH_anon_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA)"}
6. Oracle Service - {"oracle.net.authentication_services":"(TCPS)","oracle.net.ssl_cipher_suites":"(SSL_DH_anon_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA)"}
7. PostgreSQL - {"sslfactory":"org.postgresql.ssl.NonValidatingFactory"}
8. AWS RedShift - {"verifyServerCertificate":"false"}
9. AWS RedShift version 2.0 - {"verifyServerCertificate":"false"}
10. AWS RDS Aurora - {"verifyServerCertificate":"false"}
11. Hive - {"verifyServerCertificate":"false"}
12. Spark SQL - {"verifyServerCertificate":"false"}

If you still want to use them, they can be added to connection_properties in the connection definition, or defined in the jdbcUrl.

Use a different default driver for your database

You can change the driver that DB Connect uses for your database type. This can be useful if you want to use a custom driver to connect to your database. To change the driver, you edit the db_connection_types.conf file.

First, get the JDBC driver vendor's Java driver class name. For example, the class name of the Microsoft JDBC Driver for SQL Server is com.microsoft.sqlserver.jdbc.SQLServerDriver. Once you've found the correct Java class name, do the following:

1. Using a text editor, open the db_connection_types.conf from within $SPLUNK_HOME/etc/apps/splunk_app_db_connect/default/ (%SPLUNK_HOME%\etc\apps\splunk_app_db_connect\default on Windows hosts).
2. Find the stanza for the database type for which you want to configure a custom driver, select it, and then type Ctrl-C or Command-C to copy it.
3. Create a new db_connection_types.conf file (if one doesn't already exist) in $SPLUNK_HOME/etc/apps/splunk_app_db_connect/local/ (%SPLUNK_HOME%\etc\apps\splunk_app_db_connect\local on Windows hosts). If the file is a new file, open it and type [local] and then two new lines.
4. Paste in the database stanza you copied from the default db_connection_types.conf file.
5. Change the entry next to jdbcDriverClass to match the Java class name for your custom driver.
6. If you want to retain the ability to choose the original database driver, change the name of the stanza and update the displayName attribute to differentiate it from the original driver.
7. Restart Splunk Enterprise.

Supported databases by JDBC Add-Ons

JDBC driver Add-Ons provides in documentation what version of java and database supports.

Other Supported Databases

* SSL support: This column specifies whether DB Connect tests and supports Secure Sockets Layer (SSL) connections to this database. Though other supported databases may support SSL connections, DB Connect support for SSL means that Splunk has tested SSL for that database type and supports connecting over SSL using DB Connect.

Useful information about drivers configuration

Notes:

• Your database connection must be set up to return results encoded in UTF-8. Consult your database vendor's documentation for instructions.
• DB Connect supports sending data that is in a multi-byte character set, such as Traditional Chinese, using a database output. Depending on your database, you may need to change certain settings on the database side to the database to properly receive and store the data. See Enable output to multi-byte character sets.

IBM DB2

IBM DB2 is supported when the database is running on Linux. Splunk doesn't test or support DB2 on AS/400 or Windows.

Note: IBM DB2 is only supported when the database is running on Linux. Splunk doesn't test or support DB Connect with DB2 on AS/400 or on Windows.

jdbcUrlFormat = jdbc:db2://<host>:<port>/<database>:securityMechanism=9;encryptionAlgorithm=2;

Follow these instructions to install the DB2 JDBC Driver:

1. Go to DB2 JDBC Driver Versions and Downloads on the IBM website, and click the link for the latest DB2 Version 10.5 driver.
2. Click the Download link for the IBM Data Server Driver for JDBC and SQLJ (JCC Driver).
3. Select the newest fix pack, and then click Continue. You will need to log in with your IBM ID, or create one if you don't already have one.
4. Click the Download using your browser (HTTPS) radio button, and then Continue.
5. Right-click the file name, and then save it to your hard disk.
6. Expand the downloaded file, and then expand the db2_db2driver_for_jdbc_sqlj.zip file.
7. Copy or move the db2jcc4.jar file to the $SPLUNK_HOME/etc/apps/splunk_app_db_connect/drivers directory.
8. Reload the driver under Settings>Drivers.

For additional information, see the Installing and Connecting to Clients documentation on the IBM website.

Hive

We support connecting to Hive using two database drivers: Simba and Cloudera

• For Simba, the procedure involves requesting a trial or purchasing the driver. After obtaining the license, it will be sent to you, and you'll need to follow attached instructions to activate it.

Microsoft SQL Server

You have several options for connecting to a Microsoft SQL Server. Start by determining:

• Which operating system (Windows or Linux) is running Splunk DB Connect.
• Which driver you want to use.
• How your database server authenticates your connection.

See Legends below the table for a more detailed explanation.

Follow this table from left to right, choosing the options that correspond to your Microsoft SQL Server environment. For more information about the meaning of each column, see the legend that follows the table.

Legend

• SQL Authentication: Log into SQL Server as a SQL Server user. This option assumes you will create an identity that uses a username and password that is defined on the database.
• Windows Authentication: Log into SQL Server as a Microsoft Integrated Windows Authentication user ("domain user"). This assumes that you are creating an identity that uses a domain, user name, and password to connect to the database, and that the user you assign to the identity is part of an Active Directory user group that has been set up to log into your SQL Server.
• Kerberos Authentication: DB Connect uses a Kerberos client (Linux) to negotiate an authentication ticket with the Active Directory environment directly. This assumes that the user you assign to the identity is part of an Active Directory user group that has been set up to log into your SQL Server.

Install the SQL Server database driver using a SQL server authentication

If you will log onto your SQL Server database using a SQL Server username and password (non-domain attached), follow these instructions:

Install the SQL server database driver

To install the Microsoft JDBC Driver for SQL Server, please follow these instructions:

1. Install the MSSQL JDBC driver add-on.
2. Reload the driver under Settings>Drivers.

1. Download the appropriate JDBC driver for SQL Server:
   • For the Microsoft JDBC Driver for SQL Server download the driver from the Microsoft JDBC Driver page.
2. Move the driver file to the correct location:
   • For the MS Generic Driver, from inside the zip file, copy or move the proper jar file to the $SPLUNK_HOME/etc/apps/splunk_app_db_connect/drivers directory (%SPLUNK_HOME%\etc\apps\splunk_app_db_connect\drivers on Windows hosts).
   • If you will need to use a database service account on Windows with the Generic driver, you will also need to install the JDBC Auth library:
     1. From the Microsoft JDBC Driver for SQL Server download, locate the .dll file.
     2. Copy the .dll' file to C:\Windows\System32 on your Splunk Enterprise server.
     3. From the Windows Control Panel, go to Services, and then get properties on Splunk Service.
     4. Click the Log On tab, and then change the Log on as setting from the Local System account to that of the logged on domain user.

        Note: The domain user should have sufficient privileges to access the SQL Server instance.

     5. Save your changes, and then restart the Splunk Enterprise server for the changes to take effect.

When you create a connection to this database in DB Connect, you must choose MS-SQL Server Using MS Generic Driver from the Connection Types popup menu.

Install the SQL Server database driver using the MS Generic driver with Kerberos authentication

If you're running DB Connect on Linux, you can connect to a Microsoft SQL Server using a Windows domain and user name by enabling Kerberos authentication.

Before starting the following procedure:

1. See the instructions on how to Install the appropriate JDBC driver for SQL Server
2. Enable Kerberos on the Microsoft SQL Server.
[/topic/topic/body/section/ol/p {""}) Now complete the following steps to enable DB Connect to use Kerberos authentication to connect to your SQL Server database: (p] [/topic/topic/body/section/ol/ol {""}) [/topic/topic/body/section/ol/ol/li {""}) First, get the domain name: [/topic/topic/body/section/ol/ol/li/ol {""}) [/topic/topic/body/section/ol/ol/li/ol/li {""}) Log onto the Windows server that is running your SQL Server database. (li][/topic/topic/body/section/ol/ol/li/ol/li {""}) At the command line, run [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) systeminfo (codeph], and then copy down the domain name (next to the [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) Domain: (b] label). (li] (ol] (li] [/topic/topic/body/section/ol/ol/li {""}) Next, get the Kerberos Distribution Center (KDC) information: [/topic/topic/body/section/ol/ol/li/ol {""}) [/topic/topic/body/section/ol/ol/li/ol/li {""}) From the command line, run the following, replacing [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) <domain> (codeph] with the domain name you copied in the previous step: [/topic/topic/body/section/ol/ol/li/ol/li/codeblock {""}) nltest /DSGETDC:<domain> (codeblock] (li][/topic/topic/body/section/ol/ol/li/ol/li {""}) Copy down the name of the domain controller, which is next to the [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) DC: (b] label. This is the KDC host name. (li] (ol] (li] [/topic/topic/body/section/ol/ol/li {""}) Back on the machine running DB Connect, use the [/topic/topic/body/section/ol/ol/li/codeph {""}) kinit (codeph] command to generate a [/topic/topic/body/section/ol/ol/li/b {""}) krb5.conf (b] file, which Kerberos will use to authenticate with the SQL Server for DB Connect. [/topic/topic/body/section/ol/ol/li/ol {""}) [/topic/topic/body/section/ol/ol/li/ol/li {""}) First, install [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) kinit (codeph] by entering the following at the command line: [/topic/topic/body/section/ol/ol/li/ol/li/codeblock {""}) apt-get install krb5-user (codeblock] If you are prompted to enter a realm, enter the domain name you obtained in Step 1, but in all upper-case letters. For example, if your domain is [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) abc.dbx (codeph], you'd enter [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) ABC.DBX (codeph]. (li][/topic/topic/body/section/ol/ol/li/ol/li {""}) Next, use [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) kinit (codeph] to initialize the Kerberos ticket cache. Enter the following at the command line, replacing [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) <username> (codeph] with the appropriate user name (such as [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) Administrator (codeph]) and [/topic/topic/body/section/ol/ol/li/ol/li/codeph {""}) <DOMAIN> (codeph] with the domain name, in upper-case letters: [/topic/topic/body/section/ol/ol/li/ol/li/codeblock {""}) kinit <username>@<DOMAIN> (codeblock] [/topic/topic/body/section/ol/ol/li/ol/li/p {""}) The [/topic/topic/body/section/ol/ol/li/ol/li/p/b {""}) krb5.conf (b] has been generated in the [/topic/topic/body/section/ol/ol/li/ol/li/p/b {""}) /etc (b] directory. (p] [/topic/topic/body/section/ol/ol/li/ol/li/p {""}) [/topic/topic/body/section/ol/ol/li/ol/li/p/b {""}) Note: (b] If the [/topic/topic/body/section/ol/ol/li/ol/li/p/b {""}) krb5.conf (b] file is not in the [/topic/topic/body/section/ol/ol/li/ol/li/p/b {""}) /etc (b] directory, set the following option in [/topic/topic/body/section/ol/ol/li/ol/li/p/b {""}) JVM Options (b] under the [/topic/topic/body/section/ol/ol/li/ol/li/p/b {""}) Settings (b] tab: [/topic/topic/body/section/ol/ol/li/ol/li/p/codeph {""}) -Djava.security.krb5.conf=/path/to/krb5.conf (codeph] (p] (li] (ol] (li] [/topic/topic/body/section/ol/ol/li {""}) Create an identity in DB Connect. [/topic/topic/body/section/ol/ol/li/ol {""}) [/topic/topic/body/section/ol/ol/li/ol/li {""}) Select [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) New Identity (b] under [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) Explorer (b] > [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) Identities (b]. (li][/topic/topic/body/section/ol/ol/li/ol/li {""}) Enter [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) Identity Name (b], [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) Username (b], [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) Password (b], and then click [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) save (b].[/topic/topic/body/section/ol/ol/li/ol/li/div {""}) (div] [/topic/topic/body/section/ol/ol/li/ol/li/ul {""}) [/topic/topic/body/section/ol/ol/li/ol/li/ul/li {""}) [/topic/topic/body/section/ol/ol/li/ol/li/ul/li/b {""}) Username (b]: Enter the username of your Kerberos account. If you don't select [/topic/topic/body/section/ol/ol/li/ol/li/ul/li/b {""}) Use Windows Authentication Domain? (b], you have to append @<DOMAIN> at the end of the username, e.g. Administrator@<DOMAIN> (li][/topic/topic/body/section/ol/ol/li/ol/li/ul/li {""}) [/topic/topic/body/section/ol/ol/li/ol/li/ul/li/b {""}) Password (b] and [/topic/topic/body/section/ol/ol/li/ol/li/ul/li/b {""}) Confirm Password (b]: Enter the password of your Kerberos account. (li][/topic/topic/body/section/ol/ol/li/ol/li/ul/li {""}) [/topic/topic/body/section/ol/ol/li/ol/li/ul/li/b {""}) Use Windows Authentication Domain? (b]: If you select it, you have to enter the <DOMAIN> in [/topic/topic/body/section/ol/ol/li/ol/li/ul/li/b {""}) Windows Authentication Domain (b] field, then you don't have to append @<DOMAIN> at the end of the [/topic/topic/body/section/ol/ol/li/ol/li/ul/li/b {""}) Username (b].[/topic/topic/body/section/ol/ol/li/ol/li/ul/li/div {""}) (div] (li] (ul] [/topic/topic/body/section/ol/ol/li/ol/li/b {""}) Note: (b] You can add multiple identities if you need to use the different users to do the Kerberos authentication. (li] (ol] (li] [/topic/topic/body/section/ol/ol/li {""}) Create a new connection in DB Connect as you normally would, keeping in mind the following: [/topic/topic/body/section/ol/ol/li/ul {""}) [/topic/topic/body/section/ol/ol/li/ul/li {""}) [/topic/topic/body/section/ol/ol/li/ul/li/b {""}) Database Types: (b] Be sure to choose [/topic/topic/body/section/ol/ol/li/ul/li/b {""}) MS-SQL Server Using MS Generic Driver with Kerberos Authentication (b] from the popup menu. (li][/topic/topic/body/section/ol/ol/li/ul/li {""}) [/topic/topic/body/section/ol/ol/li/ul/li/b {""}) JDBC URL Format: (b] Once you've entered all the necessary connection information, add the following to the JDBC URL string to enable DB Connect to use the Kerberos authentication you just set up: [/topic/topic/body/section/ol/ol/li/ul/li/ul {""}) [/topic/topic/body/section/ol/ol/li/ul/li/ul/li {""}) [/topic/topic/body/section/ol/ol/li/ul/li/ul/li/codeph {""}) integratedSecurity=true (codeph] (li][/topic/topic/body/section/ol/ol/li/ul/li/ul/li {""}) [/topic/topic/body/section/ol/ol/li/ul/li/ul/li/codeph {""}) authenticationScheme=javaKerberos (codeph] (li] (ul] (li] (ul] [/topic/topic/body/section/ol/ol/li/p {""}) After you're finished, the field should contain the following: (p] [/topic/topic/body/section/ol/ol/li/codeblock {""}) jdbc:sqlserver://<host>:<port>;databaseName=<database>;selectMethod=cursor;integratedSecurity=true;authenticationScheme=javaKerberos (codeblock] (li] (ol]