module Splunk

if $splunk_xml_library == :rexml

class REXML::Text # :nodoc:
  def text
    value
  end
end

end

Provides a class representing the collection of users and roles in Splunk. This should look identical to Collection to the end user of the SDK.

Users and roles are both case insensitive to the entity name, and neither returns the newly created entity.

Provide a class representing a collection of input kinds.

Provides a class representing the collection of jobs in Splunk.

Provides a collection representing system-wide messages on Splunk.

Provides a subclass of Entity to represent stanzas in configuration files.

This module provides the Service class, which encapsulates the interaction with Splunk.

Constants

DEFAULT_HOST
DEFAULT_PATH_PREFIX
DEFAULT_PORT
DEFAULT_SCHEME
PATH_APPS_LOCAL

The paths used by service.

PATH_CAPABILITIES
PATH_CONF
PATH_CONFS
PATH_EXPORT
PATH_INDEXES
PATH_INFO
PATH_INPUTS
PATH_JOBS
PATH_LOGGER
PATH_MESSAGES
PATH_MODULAR_INPUT_KINDS
PATH_ROLES
PATH_SAVED_SEARCHES
PATH_SETTINGS
PATH_STANZA
PATH_USERS

Public Class Methods

connect(args) click to toggle source

Create a logged in reference to a Splunk instance.

connect takes a hash of values as its sole argument. The keys it understands are:

  • `:username` - log in to Splunk as this user (no default)

  • `:password` - password to use when logging in (no default)

  • `:host` - Splunk host (e.g. “10.1.2.3”) (defaults to 'localhost')

  • `:port` - the Splunk management port (defaults to '8089')

  • `:protocol` - either 'https' or 'http' (defaults to 'https')

  • `:namespace` - application namespace option. 'username:appname'

    (defaults to nil)
    
  • `:token` - a preauthenticated Splunk token (default to nil)

Returns: a logged in Service object.

Example:

require 'splunk-sdk-ruby'
service = Splunk::connect(:username => "admin", :password => "changeme")
# File lib/splunk-sdk-ruby/service.rb, line 81
def self.connect(args)
  Service.new(args).login()
end
eai_acl_to_namespace(eai_acl) click to toggle source

Convert a hash of eai:acl fields from Splunk's REST API into a namespace.

eai_acl should be a hash containing at least the key +“sharing”+, and, depending on the value associated with +“sharing”+, possibly keys +“app”+ and +“owner”+.

Returns: a Namespace.

# File lib/splunk-sdk-ruby/namespace.rb, line 80
def self.eai_acl_to_namespace(eai_acl)
  namespace(:sharing => eai_acl["sharing"],
            :app => eai_acl["app"],
            :owner => eai_acl["owner"])
end
namespace(args) click to toggle source

Create a Namespace.

namespace takes a hash of arguments, recognizing the keys :sharing, :owner, and :app. Among them, :sharing is required, and depending on its value, the others may be required or not.

:sharing determines what kind of namespace is produced. It can have the values +“default”+, +“global”+, +“system”+, +“user”+, or +“app”+.

If :sharing is +“default”+, +“global”+, or +“system”+, the other two arguments are ignored. If :sharing is +“app”+, only :app is used, specifying the application of the namespace. If :sharing is +“user”+, then both the :app and :owner arguments are used.

If :sharing is +“app”+ but :app is +“”+, it returns an AppReferenceNamespace.

Returns: a Namespace.

# File lib/splunk-sdk-ruby/namespace.rb, line 107
def self.namespace(args)
  sharing = args.fetch(:sharing, "default")
  owner = args.fetch(:owner, nil)
  app = args.fetch(:app, nil)

  if sharing == "system"
    return SystemNamespace.instance
  elsif sharing == "global"
    return GlobalNamespace.instance
  elsif sharing == "user"
    if owner.nil? or owner == ""
      raise ArgumentError.new("Must provide an owner for user namespaces.")
    elsif app.nil? or app == ""
      raise ArgumentError.new("Must provide an app for user namespaces.")
    else
      return UserNamespace.new(owner, app)
    end
  elsif sharing == "app"
    if app.nil?
      raise ArgumentError.new("Must specify an application for application sharing")
    elsif args[:app] == ""
      return AppReferenceNamespace.instance
    else
      return AppNamespace.new(args[:app])
    end
  elsif sharing == "default"
    return DefaultNamespace.instance
  else
    raise ArgumentError.new("Unknown sharing value: #{sharing}")
  end
end

Public Instance Methods

read_author(author) click to toggle source

Reads the author from its special tag.

Returns: a String.

# File lib/splunk-sdk-ruby/atomfeed.rb, line 312
def read_author(author)
  # The author tag has the form <author><name>...</name></author>
  # so we have to fetch the value out of the inside of it.
  #
  # In REXML, sets of elements are indexed starting at 1 to match
  # XPath. In Nokogiri they are indexed starting at 0. To work around
  # this, we coerce it to an array, which is always indexed starting at 0.
  #
  return Array(author.elements)[0].text
end
read_dict(dict) click to toggle source

Reads a dictionary from the XML in dict.

Returns: a Hash.

# File lib/splunk-sdk-ruby/atomfeed.rb, line 281
def read_dict(dict)
  result = {}
  dict.elements.each do |element|
    key = element.attributes["name"].text
    value = read_entry_field(element)
    result[key] = value
  end

  return result
end
read_entry(entry) click to toggle source

Reads a single entry from the XML in entry.

Returns: a Hash representing the entry.

# File lib/splunk-sdk-ruby/atomfeed.rb, line 202
def read_entry(entry)
  result = {"links" => {}}
  entry.elements.each do |element|
    name = element.name
    if name == "link"
      rel, uri = read_link(element)
      result["links"][rel] = uri
    else
      value = read_entry_field(element)
      result[name] = value
    end
  end

  return result
end
read_entry_field(field) click to toggle source

Reads a single field of an entry from the XML in field.

Returns: a single value (either a String or a URI).

# File lib/splunk-sdk-ruby/atomfeed.rb, line 238
def read_entry_field(field)
  # We have to coerce this to an Array to call length,
  # since Nokogiri defines `#length` on element sets,
  # but REXML does not.
  elements = Array(field.elements)
  if elements.length == 0 # This is a simple text field
    return read_simple_entry_field(field)
  elsif elements.length > 1
    raise ArgumentError, "Entry fields should contain one element " +
        "(found #{elements.length} in #{field.to_s}."
  elsif field.name == "author"
    return read_author(field)
  end

  # Coerce to Array because Nokogiri indexes from 0, and REXML from 1.
  # Arrays always index from 0.
  value_element = Array(field.elements)[0]
  if value_element.name == "dict"
    return read_dict(value_element)
  elsif value_element.name == "list"
    return read_list(value_element)
  end
end
read_feed(feed) click to toggle source

Reads a feed from the the XML in feed.

Returns: [+metadata, entries+], where metadata is a hash of feed headers, and entries is an Array of Hashes representing the feed.

# File lib/splunk-sdk-ruby/atomfeed.rb, line 157
def read_feed(feed)
  metadata = {"links" => {}, "messages" => []}
  entries = []

  feed.elements.each do |element|
    if element.name == "entry"
      entries << read_entry(element)
    elsif element.name == "author"
      # The author tag has the form <author><name>...</name></author>
      # so we have to fetch the value out of the inside of it.
      metadata["author"] = read_author(element)
    elsif element.name == "generator"
      # To handle elements of the form:
      #     <generator build="144175" version="5.0.2"/>
      metadata["generator"] = {}
      element.attributes.each do |name, attribute|
        metadata["generator"][name] = attribute.text
      end
    elsif element.name == "link"
      rel, uri = read_link(element)
      metadata["links"][rel] = uri
    elsif element.name == "id"
      metadata[element.name] = URI(children_to_s(element))
    elsif element.name == "messages"
      element.elements.each do |element|
        if element.name == "msg"
          metadata["messages"] << {
              "type" => element.attributes["type"].text,
              "message" => children_to_s(element)
          }
        end
      end
    else
      metadata[element.name] = children_to_s(element)
    end
  end

  return metadata, entries
end
read_list(list) click to toggle source

Reads an Array from the XML in list.

Returns: an Array.

# File lib/splunk-sdk-ruby/atomfeed.rb, line 297
def read_list(list)
  result = []
  list.elements.each do |element|
    value = read_entry_field(element)
    result << value
  end

  return result
end
read_simple_entry_field(field) click to toggle source

Reads a simple field.

Returns: a String or a URI.

# File lib/splunk-sdk-ruby/atomfeed.rb, line 267
def read_simple_entry_field(field)
  value = children_to_s(field)
  if field.name == "id"
    return URI(value)
  else
    return value
  end
end