How to connect to Splunk

The Splunk SDK for Ruby is deprecated. For more information, see Deprecation notice.

To start a Splunk® session, the first thing your app must do is connect to Splunk by sending login credentials to the splunkd server. Splunk returns an authentication token, which is then automatically included in subsequent calls for the rest of your session. By default, the token is valid for one hour, but is refreshed every time you make a call to splunkd.

Note: Check out 1_connect.rb in the /examples folder of the Splunk SDK for Ruby for a working example of this functionality.

Connect to Splunk

The basic steps to connect to Splunk with your Ruby app are as follows:

  1. Start Splunk: Start the Splunk server if you haven't already.

  2. Add a reference to the SDK: Add a require statement to your Ruby document for the Splunk SDK for Ruby library, 'splunk-sdk-ruby'.

    Important: At this point, you should provide a mechanism to supply the login credentials for your Splunk server. In the example shown below, the login credentials are hard coded in an array for convenience. For security reasons, this practice is not recommended for your production app. Use whatever authentication mechanism you prefer (for instance, a login form) to supply the login credentials.
  3. Connect: You have a few options for connecting to Splunk:

    • Call the Splunk::connect method: Create a Splunk::Service object using the Splunk::connect(config) method, where config represents the login credentials, hostname, and port of the Splunk server.
    • Create a Service object and call its login method: Call Splunk::Service#new(config), where config represents the login credentials. Then, use the login method of the new Service object.
    • Use an existing token: If you've already obtained a valid token from the Splunk server, you can use it instead of a username and password. In this case you would again create a new instance of the Service object using Splunk::Service#new; this time, however, you pass the token to the constructor and don't call login.

The following shows examples of all three ways to connect to Splunk:

require 'splunk-sdk-ruby'

# How to get to the Splunk server. 
config = {
  :scheme => :https,
  :host => "localhost",
  :port => 8089,
  :username => "admin",
  :password => "changeme"

# Create a Service logged into Splunk, and print the authentication token
# that Splunk sent us.
service0 = Splunk::connect(config)
puts "Logged in service 0. Token: #{service0.token}"

# connect is a synonym for creating a Service by hand and calling login.
service1 =
puts "Logged in. Token: #{service1.token}"

# We don't always want to call login. If we have already obtained a valid
# token, we can use it instead of a username or password. In this case we
# must create the Service manually.
token_config = {
  :scheme => config[:scheme],
  :host => config[:host],
  :port => config[:port],
  :token => service1.token

service2 =
puts "Logged in. Token: #{service2.token}"

Connect to a specific namespace

All three connection methods detailed in the previous section will connect you to Splunk's default search app. You can specify a different app to connect to by first specifying a namespace using the Splunk::namespace method, and then connecting with Splunk::connect, adding the namespace you just specified as an argument. For instance:

ns = Splunk::namespace(:sharing => "app", :app => "testrubySS")
svc = Splunk::connect(:username => 'admin', :password => 'changed', :namespace => ns)