Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

Splunk Enterprise version 6.x is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Deployment

Use the Deployment endpoints to manage deployment servers and clients.

deployment/*
Access and configure Splunk deployment servers and deployment clients.


search/distributed/config*
Access and manage distributed search configurations.


deployment/client

Provides access to deployment client configuration and status.

GET deployment/client

Returns the status of the deployment client in this Splunk instance, including the host/port of its deployment server, and which server classes it is a part of.

A deployment client is a Splunk instance remotely configured by a deployment server. A Splunk instance can be both a deployment server and client at the same time. A Splunk deployment client must belong to one or more server classes if it is to receive apps from the deployment server.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view deployment client status.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
disabled Indicates if the deployment client is disabled.
serverClasses The server classes to which this client belongs.
targetUri URI of the deployment server for this deployment client.

Example

Retrieves deployment client status.


curl -k -u admin:pass https://localhost:8089/services/deployment/client


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>deploymentclient</title>
  <id>https://localhost:8089/services/deployment/client</id>
  <updated>2011-07-11T00:35:37-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>deployment-client</title>
    <id>https://localhost:8089/services/deployment/client/deployment-client</id>
    <updated>2011-07-11T00:35:37-07:00</updated>
    <link href="/services/deployment/client/deployment-client" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/client/deployment-client" rel="list"/>
    <link href="/services/deployment/client/deployment-client" rel="edit"/>
    <link href="/services/deployment/client/deployment-client/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="serverClasses">
          <s:list>
            <s:item>dstest:dstestapp</s:item>
          </s:list>
        </s:key>
        <s:key name="targetUri">essplunk:8089</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/client/config

Access configuration information for this deployment client.

GET deployment/client/config

List the configuration information for this deployment server client.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view configuration information for this client.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
disabled Indicates whether the deployment client is disabled.
serverClasses List of server classes associated with this client configuration.
targetUri The URI of the deployment server, including the managment port.

Example

List configuration information for this deployment client.

curl -k -u admin:pass https://localhost:8089/services/deployment/client/config
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>deploymentclient</title>
  <id>https://vgenovese-centos62x64-3:8089/services/deployment/client</id>
  <updated>2013-07-31T20:49:58-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/client/listIsDisabled" rel="listIsDisabled"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>config</title>
    <id>https://vgenovese-centos62x64-3:8089/services/deployment/client/config</id>
    <updated>2013-07-31T20:49:58-07:00</updated>
    <link href="/services/deployment/client/config" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/client/config" rel="list"/>
    <link href="/services/deployment/client/config" rel="edit"/>
    <link href="/services/deployment/client/config/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <!-- eai:attributes nodes elided for brevity. -->
        <s:key name="serverClasses">
          <s:list>
            <s:item>sc_apps_wma:wma-app2</s:item>
            <s:item>sc_apps_wma:wma-app1</s:item>
            <s:item>sc_mach_type:wma-app2</s:item>
            <s:item>sc_new:wma-app2</s:item>
            <s:item>sc_new:wma-app1</s:item>
          </s:list>
        </s:key>
        <s:key name="targetUri">vgenovese-centos62x64-2:8089</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/client/config/listIsDisabled

Access the information on whether the deployment client is disabled.

GET deployment/client/config/listIsDisabled

Returns whether or not the deployment client is disabled.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Endpoint returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to access resource.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
disabled Indicates whether the client is disabled.

Example

Determine whether deployment client is disabled.

curl -k -u admin:pass \
    https://localhost:8089/services/deployment/client/config/listIsDisabled
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>deploymentclient</title>
  <id>https://vgenovese-centos62x64-3:8089/services/deployment/client</id>
  <updated>2013-08-04T18:49:25-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/client/listIsDisabled" rel="listIsDisabled"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>default</title>
    <id>https://vgenovese-centos62x64-3:8089/services/deployment/client/default</id>
    <updated>2013-08-04T18:49:25-07:00</updated>
    <link href="/services/deployment/client/default" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/client/default" rel="list"/>
    <link href="/services/deployment/client/default" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
      </s:dict>
    </content>
  </entry>
</feed>

deployment/client/config/reload

POST deployment/client/config/reload

Access information on reloading the named client.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Endpoint returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to access resource.
404 Specified resoruce does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Reload the named client.

curl -k -u admin:pass -X POST\
	https://localhost:8089/services/deployment/client/config/reload
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>deploymentclient</title>
  <id>https://localhost:8089/services/deployment/client</id>
  <updated>2013-10-07T15:49:06-07:00</updated>
  <generator build="182462" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/client/listIsDisabled" rel="listIsDisabled"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>config</title>
    <id>https://localhost:8089/services/deployment/client/config</id>
    <updated>2013-10-07T15:49:06-07:00</updated>
    <link href="/services/deployment/client/config" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/client/config" rel="list"/>
    <link href="/services/deployment/client/config" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="disabled">1</s:key>
        <!-- eai:acl nodes elided for brevity. -->
      </s:dict>
    </content>
  </entry>
</feed>

deployment/client/{name}/reload

POST deployment/client/{name}/reload

Restarts the deployment client, reloading configuration from disk.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deployment client restarted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to restart deployment client.
404 Deployment client does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
disabled Indicates if the deployment client is disabled.
serverClasses Reloads server class configuration.
targetUri URI of the deployment server for this deployment client.

Example

Reload the deployment client configuration from disk. Note that "deployment-client" is the only valid name here.


curl -k -u admin:pass \
      https://localhost:8089/services/deployment/client/deployment-client/reload


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>deploymentclient</title>
  <id>https://localhost:8089/services/deployment/client</id>
  <updated>2011-07-11T00:39:23-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>deployment-client</title>
    <id>https://localhost:8089/services/deployment/client/deployment-client</id>
    <updated>2011-07-11T00:39:23-07:00</updated>
    <link href="/services/deployment/client/deployment-client" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/client/deployment-client" rel="list"/>
    <link href="/services/deployment/client/deployment-client" rel="edit"/>
    <link href="/services/deployment/client/deployment-client/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="serverClasses">
          <s:list>
            <s:item>dstest:dstestapp</s:item>
          </s:list>
        </s:key>
        <s:key name="targetUri">tiny:8089</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/applications

Access information for this deployment server about applications and server classes to which they belong.

GET deployment/server/applications

List the applications and the serverclasses that they are associated with.

Request

Name Type Required Default Description
clientId String Only list applications associated with the specified client ID.

The client ID is an MD5 of serialized (catenated) client attributes. For example: 8cf5b2b2b4d734f2dd46a1079c1c5d1b.

count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
hasDeploymentError Boolean Indicates whether to list applications that have a deployment error on a known client.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view applications for this deployment server.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
archive Specifies the location of an archived version of the application.
clientId The deployment client ID associated with this application.
hasDeploymentError Indicates whether there is a deployment error with the application on at least one client.
loadtime Specifies the date and time the application was last loaded (or reloaded) by the deployment server.

An application not mapped to any serverclasses does not get loaded, thus its loadtime attribute is 0; in epoch terms, that's 01 Jan 1970 at midnight GMT.

restartSplunkWeb Indicates whether to restart Splunk Web.
restartSplunkd Indicates whether to restart splunkd.
serverclasses List of server classes associated with the application.
size Indicates in bytes the size on disk of the compressed version (bundle) of the application.
stateOnClient Indicates whether the application is enabled or disabled.

Example

List information about applications deployed with this deployment server.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/applications
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>applications</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/applications</id>
  <updated>2013-08-01T09:35:22-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/applications/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>wma-app-test2</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/applications/wma-app2</id>
    <updated>2013-08-01T09:35:22-07:00</updated>
    <link href="/services/deployment/server/applications/wma-app2" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_new/wma-app2-1375305443.bundle</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="loadtime">Wed Jul 31 14:17:23 2013</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="serverclasses">
          <s:list>
            <s:item>sc_mach_type</s:item>
            <s:item>sc_new</s:item>
            <s:item>sc_apps_wma</s:item>
          </s:list>
        </s:key>
        <s:key name="size">112640</s:key>
        <s:key name="stateOnClient">enabled</s:key>
      </s:dict>
    </content>
  </entry>
  <entry>
    <title>wma-app1</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/applications/wma-app1</id>
    <updated>2013-08-01T09:35:22-07:00</updated>
    <link href="/services/deployment/server/applications/wma-app_test1" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_new/wma-app1-1375305443.bundle</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="loadtime">Wed Jul 31 14:17:23 2013</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="serverclasses">
          <s:list>
            <s:item>sc_new</s:item>
            <s:item>sc_apps_wma</s:item>
          </s:list>
        </s:key>
        <s:key name="size">112640</s:key>
        <s:key name="stateOnClient">enabled</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/applications/{name}

GET deployment/server/applications/{name}

List details about the named application.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view details about the named application.
404 Rquested resource does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
archive Specifies the location of an archived version of the app.
clientId The deployment client ID associated with this application.
eai:attributes See Accessing Splunk resources
hasDeploymentError Indicates if the named application has a deployment error.
loadtime Specifies the date and time the application was last loaded (or reloaded) by the deployment server.

An application not mapped to any serverclasses does not get loaded, thus its loadtime attribute is 0; in epoch terms, that's 01 Jan 1970 at midnight GMT.

restartSplunkWeb Indicates whether to restart Splunk Web.
restartSplunkd Indicates whether to restart splunkd.
serverclasses List of server classes associated with the application.
size Indicates in bytes the size on disk of the compressed version (bundle) of the application.
stateOnClient Indicates whether the application is enabled or disabled.

Example

List details about the named application, wma-app1.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/applications/wma-app1
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>applications</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/applications</id>
  <updated>2013-08-04T18:53:50-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/applications/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>wma-app1</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/applications/wma-app1</id>
    <updated>2013-08-04T18:53:50-07:00</updated>
    <link href="/services/deployment/server/applications/wma-app1" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_new/wma-app1-1375467593.bundle</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>continueMatching</s:item>
                <s:item>deinstall</s:item>
                <s:item>filterType</s:item>
                <s:item>machineTypesFilter</s:item>
                <s:item>repositoryLocation</s:item>
                <s:item>restartSplunkWeb</s:item>
                <s:item>restartSplunkd</s:item>
                <s:item>serverclass</s:item>
                <s:item>stateOnClient</s:item>
                <s:item>targetRepositoryLocation</s:item>
                <s:item>tmpFolder</s:item>
                <s:item>unmap</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list>
                <s:item>blacklist\..*</s:item>
                <s:item>whitelist\..*</s:item>
              </s:list>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="loadtime">Fri Aug  2 11:19:53 2013</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="serverclasses">
          <s:list>
            <s:item>sc_new</s:item>
            <s:item>sc_apps_wma</s:item>
          </s:list>
        </s:key>
        <s:key name="size">112640</s:key>
        <s:key name="stateOnClient">enabled</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST deployment/server/applications/{name}

Update the named application.

Request

Name Type Required Default Description
blacklist.* String List of hosts to exclude when mapping this application to a server class.

For each blacklist, replace * with an ordinal number to specify additional blacklists. Filter ordinals must start at 0 and be consecutive.

continueMatching Boolean Indicates how configuration is layered across classes and server-specific settings. Defaults to true.

If true, configuration lookups continue matching server classes, beyond the first match. If false, only uses the first match.

Matching is done in the order in which server classes are defined.

deinstall Boolean Indicates whether to remove the mapping of the named application from all server classes and delete it from the target repositories of the clients.
filterType Enum Valid values: (whitelist | blacklist)

Determines the order of execution of filters. If filterType is whitelist, all whitelist filters are applied first, followed by blacklist filters. If filterType is blacklist, all blacklist filters are applied first, followed by whitelist filters.

The whitelist setting indicates a filtering strategy that pulls in a subset:

  • Items are not considered to match the server class by default.
  • Items that match any whitelist entry, and do not match any blacklist entry, are considered to match the server class.
  • Items that match any blacklist entry are not considered to match the server class, regardless of whitelist.

The blacklist setting indicates a filtering strategy that rules out a subset:

  • Items are considered to match the server class by default.
  • Items that match any blacklist entry, and do not match any whitelist entry, are considered to not match the server class.
  • Items that match any whitelist entry are considered to match the server class.

More briefly:

whitelist: default no-match -> whitelists enable -> blacklists disable
blacklist: default match -> blacklists disable-> whitelists enable

If you specify whitelist at the global level, and then specify blacklist for an individual server class, the setting becomes blacklist for that server class, and you have to provide another filter in that server class definition to replace the one you overrode.

machineTypesFilter String Comma-separated list of filters to be used in boolean and logic with whitelist and blacklist filters.

Only clients that match the white/blacklist filters AND that match this machineTypesFilter are included.

Thus the match is an intersection of the matches for the white/blacklist and the matches for MachineTypesFilter.

The patterns are PCRE regular expressions, with the following aids for easier entry:

  • You can specify '.' to mean '\\.'
  • You can specify '*' to mean '.*'
  • Matches are always case-insensitive; you do not need to specify the '(?i)' prefix.
repositoryLocation String The location on the deployment server to store the content that is to be deployed for this server class.

For example: $SPLUNK_HOME/etc/deployment-apps

restartSplunkWeb boolean Indicates whether to restart SplunkWeb on the client when a member app or a directly configured app is updated.

Defaults to false

restartSplunkd Boolean Indicates whether to restart splunkd on the client when a member app or a directly configured app is updated.

Defaults to false

serverclass String The name of the server class to which the application is mapped.

Do not specify this parameter if deinstall is true.

stateOnClient Enum Valid values are (enabled | disabled | noop).
  • enabled: Default value. Sets the application state to enabled on the client, regardless of state on the deployment server.
  • disabled: Sets the application state to disabled on the client, regardless of state on the deployment server.
  • noop: The state on the client is the same as on the deployment server.
targetRepositoryLocation String The location on the deployment client to install the apps defined for this Deployment Server.

If unset, or set to empty, the repositoryLocation path is used. That is, defaults to:

$SPLUNK_HOME/etc/apps (the live configuration directory for a Splunk instance)

Useful only with complex (for example, tiered) deployment strategies.

tmpFolder String Working folder used by deployment server.

Defaults to $SPLUNK_HOME/var/run/tmp

unmap Boolean Indicates whether to remove the mapping of the application to the specified server class.
whitelist.* String List of hosts to accept for this server class.

For each whitelist, replace * with an ordinal number to specify additional whitelists. Filter ordinals must start at 0 and be consecutive.

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit the specified application.
404 Requested resource does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
archive Specifies the location of the compressed version (bundle) of the app.
blacklist.* Regular expressions used to exclude, when mapping this application to a client.

If a client matches any of the blacklist regular expressions, it does not receive the application. The * is replaced by an integral ordinal number.

continueMatching If true, configuration lookups continue matching server classes, beyond the first match. If false, only the first match is used.
filterType blacklist)

Determines the order of execution of filters. If filterType is whitelist, all whitelist filters are applied first, followed by blacklist filters. If filterType is blacklist, all blacklist filters are applied first, followed by whitelist filters.

See description for the filterType POST parameter for more information.

loadtime Specifies the date and time the application was last loaded (or reloaded) by the deployment server.

An application not mapped to any serverclasses does not get loaded, thus its loadtime attribute is 0; in epoch terms, that's 01 Jan 1970 at midnight GMT.

machineTypesFilter List of filters to be used in boolean and logic with whitelist and blacklist filters.
repositoryLocation The location on the deployment server to store the content that is to be deployed for this server class.
restartSplunkWeb Indicates whether to restart Splunk Web.
restartSplunkd Indicates whether to restart splunkd.
serverclass The name of the server class to which the application is mapped.
serverclasses List of server classes associated with the application.
size Indicates in bytes the size on disk of the compressed version (bundle) of the application.
stateOnClient Specifies whether the deployment client is enabled or disabled.
targetRepositoryLocation The location on the deployment client to install the apps defined for this Deployment Server.

If unset, or set to empty, the repositoryLocation path is used.

tmpFolder Working folder used by deployment server.
whitelist.* Regular expressions used to accept, when mapping this application to a client.

If a client matches any of the whitelist regular expressions, it accepts the application. The * is replaced by an integral ordinal number.

Example

Update the application to specify a serverclass to which it belongs.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/applications/wma-app3 \
	-d serverclass=sc_apps_wma
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>applications</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/applications</id>
  <updated>2013-08-10T12:50:59-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/applications/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>wma-app3</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/applications/wma-app3</id>
    <updated>2013-08-10T12:50:59-07:00</updated>
    <link href="/services/deployment/server/applications/wma-app3" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_mach_type/wma-app3-1376164259.bundle</s:key>
        <!-- eai:acl nodes elided for brevity -->
        <s:key name="loadtime">Sat Aug 10 12:50:59 2013</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="serverclasses">
          <s:list>
            <s:item>sc_mach_type</s:item>
            <s:item>sc_apps_wma</s:item>
          </s:list>
        </s:key>
        <s:key name="size">112640</s:key>
        <s:key name="stateOnClient">enabled</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/clients

Provides access to information about clients to a deployment server.

GET deployment/server/clients

Lists information about clients to a deployment server.

Request

Name Type Required Default Description
application String Lists clients to the deployment server that have attempted to download the named application.
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
hasDeploymentError Boolean False Indicates whether to list only clients that have a deployment error.
maxPhonehome_latency_to_avgInterval_ratio Number List clients to the deployment server when the ratio of the phone home latency to the average phone home interval is less than the value supplied to this parameter.
minLatestPhonehomeTime Number Lists clients for which there is a phone home message at the specified time or later, in epoch seconds. That is, list the client for the following condition:

  client's latency ≤ (now−minLatestPhonehomeTime)

minPhonehome_latency_to_avgInterval_ratio Number List clients to the deployment server when the ratio of the phone home latency to the average phone home interval is greater than the value supplied with this parameter.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

serverclasses String Comma-separated list of serverclasses. List clients that are configured to receive an application to a listed serverclass.

The match is a logical OR of, for each Si, include C if C would have been sent an app A that maps to Si in serverclass.conf, if such an app existed.

The "would have" is per blacklist.n or whitelist.n/machineTypesFilter in serverclass.conf

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view clients to the deployment server.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
applications List of applications deployed to the deployment client.
averagePhoneHomeInterval The average phone home interval, in seconds.
build The build number for the instance of Splunk on the deployment client.
dns The DNS lookup name of the deployment client server.
guid Identifier for the deployment server client.
hasDeploymentError Specifies whether to check for clients with a deployment error.
hostname The host name of the deployment client server.
id ID for the client based on client name and IP address.
ip The IP address of the client to the deployment server.
lastPhoneHomeTime The last time the deployment client phones home to the deployment server, in epoch time.
mgmt The managment port for the deployment client.
minLatestPhonehomeTime Specifies in epoch seconds the minimum latency for a client to contact the deployment server.
minPhonehome_latency_to_avgInterval_ratio The minimum value specified for the ratio of the phone home latency to the average phone home interval.
name The name of the deployment client server.
serverclasses List of server classes for the deployment client.
utsname Machine type for the deployment server client.

Example

List information about clients to this deployment server.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/clients
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclients</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients</id>
  <updated>2013-08-01T09:41:42-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/clients/countClients_by_machineType" rel="countClients_by_machineType"/>
  <link href="/services/deployment/server/clients/countRecentDownloads" rel="countRecentDownloads"/>
  <link href="/services/deployment/server/clients/getMatchingAppsForClient_dryRun" rel="getMatchingAppsForClient_dryRun"/>
  <link href="/services/deployment/server/clients/preview" rel="preview"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>dc95537d0e8fdadc44d00c50fc431e25</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25</id>
    <updated>2013-08-01T09:41:42-07:00</updated>
    <link href="/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25" rel="list"/>
    <link href="/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="applications">
          <s:dict>
            <s:key name="wma-app-test2">
              <s:dict>
                <s:key name="action">Install</s:key>
                <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_new/wma-app2-1375305443.bundle</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="result">Ok</s:key>
                <s:key name="serverclasses">
                  <s:list>
                    <s:item>sc_mach_type</s:item>
                    <s:item>sc_new</s:item>
                    <s:item>sc_apps_wma</s:item>
                  </s:list>
                </s:key>
                <s:key name="size">112640</s:key>
                <s:key name="stateOnClient">enabled</s:key>
                <s:key name="timestamp">Wed Jul 31 14:11:23 2013</s:key>
              </s:dict>
            </s:key>
            <s:key name="wma-app_test1">
              <s:dict>
                <s:key name="action">Install</s:key>
                <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_new/wma-app1-1375305443.bundle</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="result">Ok</s:key>
                <s:key name="serverclasses">
                  <s:list>
                    <s:item>sc_new</s:item>
                    <s:item>sc_apps_wma</s:item>
                  </s:list>
                </s:key>
                <s:key name="size">112640</s:key>
                <s:key name="stateOnClient">enabled</s:key>
                <s:key name="timestamp">Wed Jul 31 14:17:23 2013</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="averagePhoneHomeInterval">60</s:key>
        <s:key name="build">172889</s:key>
        <s:key name="dns">vgenovese-centos62x64-3.sv.splunk.com</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="guid">dc95537d0e8fdadc44d00c50fc431e25</s:key>
        <s:key name="hostname">vgenovese-centos62x64-3.sv.splunk.com</s:key>
        <s:key name="id">connection_10.160.24.187_8089_vgenovese-centos62x64-3.sv.splunk.com_vgenovese-centos62x64-3.sv.splunk.com_Ombra</s:key>
        <s:key name="ip">10.160.24.187</s:key>
        <s:key name="lastPhoneHomeTime">1375375291</s:key>
        <s:key name="mgmt">8089</s:key>
        <s:key name="name">Ombra</s:key>
        <s:key name="serverClasses">
          <s:dict>
            <s:key name="sc_apps_wma">
              <s:dict>
                <s:key name="loadTime">1375305443</s:key>
                <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
            <s:key name="sc_mach_type">
              <s:dict>
                <s:key name="loadTime">1375305443</s:key>
                <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
            <s:key name="sc_new">
              <s:dict>
                <s:key name="loadTime">1375305443</s:key>
                <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="utsname">linux-x86_64</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/clients/countClients_by_machineType

Access information about deployment clients to this server according to the machine type of the client.

GET deployment/server/clients/countClients_by_machineType

Lists the count of deployment clients to this server by machine type.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Endpoint returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to return count of clients by machine type.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
counts The list of machine types for this deployment client, showing the count of each machine type.

Example

List deployment clients to this deployment server by machine type.

curl -k -u admin:pass \
	https://localhost:8089/services/deployment/server/clients/countClients_by_machineType
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclients</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients</id>
  <updated>2013-07-30T15:07:38-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/clients/countClients_by_machineType" rel="countClients_by_machineType"/>
  <link href="/services/deployment/server/clients/countRecentDownloads" rel="countRecentDownloads"/>
  <link href="/services/deployment/server/clients/getMatchingAppsForClient_dryRun" rel="getMatchingAppsForClient_dryRun"/>
  <link href="/services/deployment/server/clients/preview" rel="preview"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>default</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients/default</id>
    <updated>2013-07-30T15:07:38-07:00</updated>
    <link href="/services/deployment/server/clients/default" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/clients/default" rel="list"/>
    <link href="/services/deployment/server/clients/default" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="counts">
          <s:dict>
            <s:key name="linux-x86_64">3</s:key>
          </s:dict>
        </s:key>
        <!-- eai:acl nodes elided for brevity. -->
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/clients/countRecentDownloads

Access the count of the number of downloads from this client to the deployment server during the last specified time period.

GET deployment/server/clients/countRecentDownloads

Return the count of the number of downloads from this client to the deployment server during the last specified time period.

Request

Name Type Required Default Description
maxAgeSecs Number
Age of the downloads to count, in seconds.
application String Count the number of downloads for clients that have attempted to download the named application.
hasDeploymentError Boolean Indicates whether to count downloads for clients that have a deployment error.
maxPhonehome_latency_to_avgInterval_ratio Number List the count of recent download by this client to the deployment server when the ratio of the phone home latency to the average phone home interval is less than the value supplied to this parameter
minLatestPhonehomeTime Number Specifies in epoch seconds the minimum latency for a client to contact the deployment server. This endpoint lists the number of downloads for clients to the deployment server with a latency equal to or greater than specified by this parameter.
minPhonehome_latency_to_avgInterval_ratio Number List the number of recent downloads by clients to the deployment server when the ratio of the phone home latency to the average phone home interval is greater than the value supplied with this parameter.
serverclasses String Comma-separated list of server classes. Lists the number of recent downloads by clients to the deployment server that are configured to send an application to a listed serverclass.

Response Codes

Status Code Description
200 Endpoint returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view count of recent downloads by clients to the deployment server.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
count The number of recent downloads.

Example

Get the count of downloads from this client of the deployment server with the last hour.

curl -k -u admin:pass \
  -d maxAgeSecs=1 -G \
  https://localhost:8089/services/deployment/server/clients/countRecentDownloads
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclients</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients</id>
  <updated>2013-07-30T20:00:43-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/clients/countClients_by_machineType" rel="countClients_by_machineType"/>
  <link href="/services/deployment/server/clients/countRecentDownloads" rel="countRecentDownloads"/>
  <link href="/services/deployment/server/clients/getMatchingAppsForClient_dryRun" rel="getMatchingAppsForClient_dryRun"/>
  <link href="/services/deployment/server/clients/preview" rel="preview"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>default</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients/default</id>
    <updated>2013-07-30T20:00:43-07:00</updated>
    <link href="/services/deployment/server/clients/default" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/clients/default" rel="list"/>
    <link href="/services/deployment/server/clients/default" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="count">6</s:key>
        <!-- eai:acl nodes elided for brevity. -->
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/clients/{name}

DELETE deployment/server/clients/{name}

Removes the specified client from the deployment server registry.

The next time the client "phones home" the record is re-created.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete the client record from the deployment server registry.
404 Resource does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Remove the specified client from server registry.

curl -k -u admin:pass --request DELETE \
  https://localhost:8089/services/deployment/server/clients/1d3de43af2aae61139c367044127f44a
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclients</title>
  <id>https://qa-sv-rh61x64-7:8103/services/deployment/server/clients</id>
  <updated>2013-10-21T16:03:49-07:00</updated>
  <generator build="182785" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/clients/countClients_by_machineType" rel="countClients_by_machineType"/>
  <link href="/services/deployment/server/clients/countRecentDownloads" rel="countRecentDownloads"/>
  <link href="/services/deployment/server/clients/getMatchingAppsForClient_dryRun" rel="getMatchingAppsForClient_dryRun"/>
  <link href="/services/deployment/server/clients/preview" rel="preview"/>
  <!-- opensearch nodes elided for brevity-->
  <s:messages/>
  <entry>
    <title>149685cb3e39898fbd15be6604672a31</title>
    <id>https://qa-sv-rh61x64-7:8103/services/deployment/server/clients/149685cb3e39898fbd15be6604672a31</id>
    <updated>2013-10-21T16:03:49-07:00</updated>
    <link href="/services/deployment/server/clients/149685cb3e39898fbd15be6604672a31" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/clients/149685cb3e39898fbd15be6604672a31" rel="list"/>
    <link href="/services/deployment/server/clients/149685cb3e39898fbd15be6604672a31" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="averagePhoneHomeInterval">60</s:key>
        <s:key name="build">177748</s:key>
        <s:key name="clientName">4D4EA12E-FDBA-41D3-99CD-2A61CC1DAB29</s:key>
        <s:key name="dns">qa-sv-rh61x64-10.sv.splunk.com</s:key>
        <!-- eai:acl nodes elided for brevity -->
        <s:key name="guid">149685cb3e39898fbd15be6604672a31</s:key>
        <s:key name="hostname">qa-sv-rh61x64-10</s:key>
        <s:key name="id">connection_10.160.24.224_8097_qa-sv-rh61x64-10.sv.splunk.com_qa-sv-rh61x64-10_4D4EA12E-FDBA-41D3-99CD-2A61CC1DAB29</s:key>
        <s:key name="ip">10.160.24.224</s:key>
        <s:key name="lastPhoneHomeTime">1382396628</s:key>
        <s:key name="mgmt">8097</s:key>
        <s:key name="name">4D4EA12E-FDBA-41D3-99CD-2A61CC1DAB29</s:key>
        <s:key name="serverClasses"/>
        <s:key name="utsname">linux-x86_64</s:key>
      </s:dict>
    </content>
  </entry>
  . . .
</feed>

GET deployment/server/clients/{name}

Lists information about the named client to the deployment server.

Request

Name Type Required Default Description
application String Lists information about this client with respect to the named application.
hasDeploymentError Boolean Indicates whether to list this client if has a deployment error.
maxPhonehome_latency_to_avgInterval_ratio Number List clients to the deployment server when the ratio of the phone home latency to the average phone home interval is less than the value supplied to this parameter.
minLatestPhonehomeTime Number Specifies in epoch seconds the minimum latency for a client to contact the deployment server. This endpoint lists information about the named client if it has a latency equal to or greater than specified by this parameter.
minPhonehome_latency_to_avgInterval_ratio Number List information about the named client to the deployment server when the ratio of the phone home latency to the average phone home interval is greater than the value supplied with this parameter.
serverclasses String Comma-separated list of serverclasses. Lists information about this client if it is configured to send an application to a listed serverclass.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view this resource.
404 Resource does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
application The name of the application specified to filter the results of this call.
applications List of applications deployed to the deployment client.
averagePhoneHomeInterval The average phone home interval, in seconds.
build The build number for the instance of Splunk on the deployment client.
dns The DNS lookup name of the deployment client server.
guid Identifier for the deployment server client.
hasDeploymentError Specifies whether to check for clients with a deployment error.
hostname The host name of the deployment client server.
id ID for the client based on client name and IP address.
ip The IP address of the client to the deployment server.
lastPhoneHomeTime The last time the deployment client phones home to the deployment server, in epoch time.
maxPhonehome_latency_to_avgInterval_ratio The maximum value specified for the ratio of the phone home latency to the average phone home interval.
mgmt The managment port for the deployment client.
minLatestPhonehomeTime Specifies in epoch seconds the minimum latency for a client to contact the deployment server.
minPhonehome_latency_to_avgInterval_ratio The minimum value specified for the ratio of the phone home latency to the average phone home interval.
name The name of the deployment client server.
serverClasses The list of server classes to which the client belongs.
serverclasses List of server classes for the deployment client.
utsname Machine type for the deployment server client.

Example

List details about the named client (specified by it's GUID, dc95537d0e8fdadc44d00c50fc431e25).

curl -k -u admin:pass \
  https://localhost:8089/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclients</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients</id>
  <updated>2013-08-04T18:59:31-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/clients/countClients_by_machineType" rel="countClients_by_machineType"/>
  <link href="/services/deployment/server/clients/countRecentDownloads" rel="countRecentDownloads"/>
  <link href="/services/deployment/server/clients/getMatchingAppsForClient_dryRun" rel="getMatchingAppsForClient_dryRun"/>
  <link href="/services/deployment/server/clients/preview" rel="preview"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>dc95537d0e8fdadc44d00c50fc431e25</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25</id>
    <updated>2013-08-04T18:59:31-07:00</updated>
    <link href="/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25" rel="list"/>
    <link href="/services/deployment/server/clients/dc95537d0e8fdadc44d00c50fc431e25" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="applications">
          <s:dict>
            <s:key name="wma-app2">
              <s:dict>
                <s:key name="action">Unknown</s:key>
                <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_new/wma-app2-1375467593.bundle</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="result">Ok</s:key>
                <s:key name="serverclasses">
                  <s:list>
                    <s:item>sc_mach_type</s:item>
                    <s:item>sc_new</s:item>
                    <s:item>sc_apps_wma</s:item>
                  </s:list>
                </s:key>
                <s:key name="size">112640</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
            <s:key name="wma-app1">
              <s:dict>
                <s:key name="action">Unknown</s:key>
                <s:key name="archive">/opt/cluster/peer1/splunk/var/run/tmp/sc_new/wma-app1-1375467593.bundle</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="result">Ok</s:key>
                <s:key name="serverclasses">
                  <s:list>
                    <s:item>sc_new</s:item>
                    <s:item>sc_apps_wma</s:item>
                  </s:list>
                </s:key>
                <s:key name="size">112640</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="averagePhoneHomeInterval">60</s:key>
        <s:key name="build">172889</s:key>
        <s:key name="dns">vgenovese-centos62x64-3.sv.splunk.com</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <!-- eai:attribute nodes elided for brevity. -->
        <s:key name="guid">dc95537d0e8fdadc44d00c50fc431e25</s:key>
        <s:key name="hostname">vgenovese-centos62x64-3.sv.splunk.com</s:key>
        <s:key name="id">connection_10.160.24.187_8089_vgenovese-centos62x64-3.sv.splunk.com_vgenovese-centos62x64-3.sv.splunk.com_Ombra</s:key>
        <s:key name="ip">10.160.24.187</s:key>
        <s:key name="lastPhoneHomeTime">1375667964</s:key>
        <s:key name="mgmt">8089</s:key>
        <s:key name="name">Ombra</s:key>
        <s:key name="serverClasses">
          <s:dict>
            <s:key name="sc_apps_wma">
              <s:dict>
                <s:key name="loadTime">1375467593</s:key>
                <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
            <s:key name="sc_mach_type">
              <s:dict>
                <s:key name="loadTime">1375467593</s:key>
                <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
            <s:key name="sc_new">
              <s:dict>
                <s:key name="loadTime">1375467593</s:key>
                <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
                <s:key name="restartSplunkWeb">0</s:key>
                <s:key name="restartSplunkd">0</s:key>
                <s:key name="stateOnClient">enabled</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="utsname">linux-x86_64</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/config

Access server configuration information for deployment servers.

GET deployment/server/config

List configuration information for all deployment servers.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view deployment server configuration.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
currentDownloads The number of current downloads for this deployment server.
disabled Indicates whether the deployment server is disabled.
loadTime The time, in epoch seconds, the serverclass for this server was loaded.
repositoryLocation The location on the deployment server to store the content that is to be deployed.
whitelist.0 Lists the contents of whitelist.0.

Example

List the deployment configuration information for a deployment server.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/config
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:s="http://dev.splunk.com/ns/rest" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>deploymentserver</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/config</id>
  <updated>2013-08-01T08:17:38-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/config/_reload" rel="_reload"/>
  <link href="/services/deployment/server/config/attributesUnsupportedInUI" rel="attributesUnsupportedInUI"/>
  <link href="/services/deployment/server/config/listIsDisabled" rel="listIsDisabled"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>config</title>
    <id>https://vgenovese-centos62x64-2:8089/servicesNS/nobody/system/deployment/server/config/config</id>
    <updated>2013-08-01T08:17:38-07:00</updated>
    <link href="/servicesNS/nobody/system/deployment/server/config/config" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/deployment/server/config/config" rel="list"/>
    <link href="/servicesNS/nobody/system/deployment/server/config/config/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/system/deployment/server/config/config" rel="edit"/>
    <link href="/servicesNS/nobody/system/deployment/server/config/config/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="currentDownloads">0</s:key>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="loadTime">1375305443</s:key>
        <s:key name="repositoryLocation">$SPLUNK_HOME/etc/deployment-apps</s:key>
        <s:key name="whitelist.0">*</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/config/attributesUnsupportedInUI

Access deployment server attriutes that cannot be configured from Splunk Web.

GET deployment/server/config/attributesUnsupportedInUI

Lists deployment server attributes that cannot be configured from Splunk Web.

For each attribute listed, the following information is provided:

  • stanza in serverclass.conf
  • property (attribute)
  • reason

Request

No parameters for this request.

Response Codes

Status Code Description
200 Endpoint returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to access this resource.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
property The attribute that cannot be configured from Splunk Web.
reason The reason an attribute cannot be configured from Splunk Web.
stanza The stanza in serverclass.conf that lists deployment server attributes that cannot be configured from Splunk Web.

Example

List attributes in serverclass.conf that cannot be managed from Splunk Web manager pages.

curl -k -u admin:pass \
	https://localhost:8089/services/deployment/server/config/attributesUnsupportedInUI
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>deploymentserver</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/config</id>
  <updated>2013-08-04T19:14:20-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/config/_reload" rel="_reload"/>
  <link href="/services/deployment/server/config/attributesUnsupportedInUI" rel="attributesUnsupportedInUI"/>
  <link href="/services/deployment/server/config/listIsDisabled" rel="listIsDisabled"/>
  <!-- eai:acl nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>item_0</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/config/item_0</id>
    <updated>2013-08-04T19:14:20-07:00</updated>
    <link href="/services/deployment/server/config/item_0" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/config/item_0" rel="list"/>
    <link href="/services/deployment/server/config/item_0/_reload" rel="_reload"/>
    <link href="/services/deployment/server/config/item_0" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <!-- opensearch nodes elided for brevity. -->
        <s:key name="property">whitelist.0</s:key>
        <s:key name="reason">unsupported at this level</s:key>
        <s:key name="stanza">global</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/config/listIsDisabled

Access information as to whether the deployment server is enabled.

GET deployment/server/config/listIsDisabled

List whether the deployment server is disabled.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Endpoint returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to access resource.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
disabled Indicates if the deployment server is disabled.

Example

Lists whether the deployment server is disabled.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/config/listIsDisabled
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>deploymentserver</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/config</id>
  <updated>2013-08-10T14:08:11-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/config/_reload" rel="_reload"/>
  <link href="/services/deployment/server/config/attributesUnsupportedInUI" rel="attributesUnsupportedInUI"/>
  <link href="/services/deployment/server/config/listIsDisabled" rel="listIsDisabled"/>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>default</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/config/default</id>
    <updated>2013-08-10T14:08:11-07:00</updated>
    <link href="/services/deployment/server/config/default" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/config/default" rel="list"/>
    <link href="/services/deployment/server/config/default/_reload" rel="_reload"/>
    <link href="/services/deployment/server/config/default" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity -->
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/serverclasses

Access information about server classes.

GET deployment/server/serverclasses

List server classes for this deployment server.

Request

Name Type Required Default Description
clientId String Only list server classes that are associated with the specified client.
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
hasDeploymentError Boolean List only server classes that have at least one application with a deployment error on a known client.

Defaults to false.

offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view server classes for this server.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
blacklist-size The number of entires in the blacklist for this serverclass.
clientId ID of deployment client for this server class.
currentDownloads Number of applications currently downloaded.
hasDeploymentError Indicates whether the serverclass has at least one deployment error.
loadTime The time, in epoch seconds, this serverclass was loaded.
machineTypesFilter List of filters to be used in boolean and logic with whitelist and blacklist filters.
repositoryList List of applications stored at the location specified by repositoryLocation.
repositoryLocation The location on the deployment server to store the content that is to be deployed for this server class.
restartSplunkWeb Indicates whether to restart Splunk Web.
restartSplunkd Indicates whether to restart splunkd.
stateOnClient Indicates whether this server class is enabled or disabled.
whitelist-size Specifies the number of entries in the whitelist for this server class.
whitelist.0 List of servers for whitelist.0 for this server class.

Example

List information about server classes for this deployment server.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/serverclasses
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclasses</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/serverclasses</id>
  <updated>2013-08-01T09:50:16-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/serverclasses/_new" rel="create"/>
  <link href="/services/deployment/server/serverclasses/rename" rel="rename"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>sc_apps_wma</title>
    <id>https://vgenovese-centos62x64-2:8089/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma</id>
    <updated>2013-08-01T09:50:16-07:00</updated>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="list"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="edit"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="remove"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_apps_wma/applications" rel="applications"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_apps_wma/clients" rel="clients"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_apps_wma/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="blacklist-size">0</s:key>
        <s:key name="currentDownloads">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="loadTime">1375305443</s:key>
        <s:key name="machineTypesFilter"></s:key>
        <s:key name="repositoryList">
          <s:dict>
            <s:key name="wma-app2"/>
            <s:key name="wma-app1"/>
          </s:dict>
        </s:key>
        <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="stateOnClient">enabled</s:key>
        <s:key name="whitelist-size">1</s:key>
        <s:key name="whitelist.0">Ombra*</s:key>
      </s:dict>
    </content>
  </entry>
  <entry>
    <title>sc_mach_type</title>
    <id>https://vgenovese-centos62x64-2:8089/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type</id>
    <updated>2013-08-01T09:50:16-07:00</updated>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="list"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="edit"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="remove"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_mach_type/applications" rel="applications"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_mach_type/clients" rel="clients"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_mach_type/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="blacklist-size">0</s:key>
        <s:key name="currentDownloads">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="loadTime">1375305443</s:key>
        <s:key name="machineTypesFilter">linux-x86_64,</s:key>
        <s:key name="repositoryList">
          <s:dict>
            <s:key name="wma-app-test2"/>
            <s:key name="wma-app_test1"/>
          </s:dict>
        </s:key>
        <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="stateOnClient">enabled</s:key>
        <s:key name="whitelist-size">1</s:key>
        <s:key name="whitelist.0">Ombra*</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST deployment/server/serverclasses

Creates a server class.

Request

Name Type Required Default Description
name String
The name of the server class.
blacklist.* String List of hosts to exclude for this server class.

For each blacklist, replace * with an ordinal number to specify additional blacklists. Filter ordinals must start at 0 and be consecutive.

continueMatching Boolen Controls how configuration is layered across classes and server-specific settings.

If true, configuration lookups continue matching server classes, beyond the first match. If false, only the first match is used. Matching is done in the order that server classes are defined. Defaults to true.

A serverClass can override this property and stop the matching.

filterType Enum Valid values: (whitelist | blacklist)

Determines the order of execution of filters. If filterType is whitelist, all whitelist filters are applied first, followed by blacklist filters. If filterType is blacklist, all blacklist filters are applied first, followed by whitelist filters.

The whitelist setting indicates a filtering strategy that pulls in a subset:

  • Items are not considered to match the server class by default.
  • Items that match any whitelist entry, and do not match any blacklist entry, are considered to match the server class.
  • Items that match any blacklist entry are not considered to match the server class, regardless of whitelist.

The blacklist setting indicates a filtering strategy that rules out a subset:

  • Items are considered to match the server class by default.
  • Items that match any blacklist entry, and do not match any whitelist entry, are considered to not match the server class.
  • Items that match any whitelist entry are considered to match the server class.

More briefly:

whitelist: default no-match -> whitelists enable -> blacklists disable
blacklist: default match -> blacklists disable-> whitelists enable

If you specify whitelist at the global level, and then specify blacklist for an individual server class, the setting becomes blacklist for that server class, and you have to provide another filter in that server class definition to replace the one you overrode.

machineTypesFilter String Comma-separated list of filters to be used in boolean and logic with whitelist and blacklist filters.

Only clients that match the white/blacklist filters AND that match this machineTypesFilter are included.

Thus the match is an intersection of the matches for the white/blacklist and the matches for MachineTypesFilter.

The patterns are PCRE regular expressions, with the following aids for easier entry:

  • You can specify '.' to mean '\\.'
  • You can specify '*' to mean '.*'
  • Matches are always case-insensitive; you do not need to specify the '(?i)' prefix.
repositoryLocation String The location on the deployment server to store the content that is to be deployed for this server class.

For example: $SPLUNK_HOME/etc/deployment-apps

restartSplunkWeb Boolean Indicates whether to restart SplunkWeb on the client when a member app or a directly configured app is updated.

Defaults to false

restartSplunkd Boolean Indicates whether to restart splunkd on the client when a member app or a directly configured app is updated.

Defaults to false

stateOnClient Enum Valid values are (enabled | disabled | noop).
  • enabled: Default value. Sets the application state to enabled on the client, regardless of state on the deployment server.
  • disabled: Sets the application state to disabled on the client, regardless of state on the deployment server.
  • noop: The state on the client is the same as on the deployment server.
targetRepositoryLocation String The location on the deployment client to install the apps defined for this Deployment Server.

If unset, or set to empty, the repositoryLocation path is used. That is, defaults to:

$SPLUNK_HOME/etc/apps (the live configuration directory for a Splunk instance

Useful only with complex (for example, tiered) deployment strategies.


tmpFolder String Working folder used by deployment server.

Defaults to $SPLUNK_HOME/var/run/tmp

whitelist.* String List of hosts to accept for this server class.

For each whitelist, replace * with an ordinal number to specify additional whitelists. Filter ordinals must start at 0 and be consecutive.

Response Codes

Status Code Description
201 Created successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to create server classes.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
blacklist-size The number of entries in the blacklist for this serverclass.
blacklist.* Regular expressions used to exclude for this server class.

If a client matches any of the blacklist regular expressions, it is not included in the server class. The * is replaced by an integral ordinal number.

continueMatching If true, configuration lookups continue matching server classes, beyond the first match. If false, only the first match is used.
currentDownloads Number of applications currently downloaded.
filterType blacklist)

Determines the order of execution of filters. If filterType is whitelist, all whitelist filters are applied first, followed by blacklist filters. If filterType is blacklist, all blacklist filters are applied first, followed by whitelist filters.

See description for the filterType POST parameter for more information.

loadTime The time, in epoch seconds, this serverclass was loaded.
machineTypesFilter List of filters to be used in boolean and logic with whitelist and blacklist filters.
repositoryList List of applications stored at the location specified by repositoryLocation.
repositoryLocation The location on the deployment server to store the content that is to be deployed for this server class.
restartSplunkWeb Indicates whether to restart Splunk Web.
restartSplunkd Indicates whether to restart splunkd.
stateOnClient Specifies whether the deployment client is enabled or disabled.
targetRepositoryLocation The location on the deployment client to install the apps defined for this Deployment Server.

If unset, or set to empty, the repositoryLocation path is used.

That is, defaults to: $SPLUNK_HOME/etc/apps (the live configuration directory for a Splunk instance.

Useful only with complex (for example, tiered) deployment strategies.

tmpFolder Working folder used by deployment server.

Defaults to $SPLUNK_HOME/var/run/tmp

whitelist-size Specifies the number of entries in the whitelist for this server class.
whitelist.* Regular expressions used to accept for this server class.

If a client matches any of the whitelist regular expressions, it is included in the server class. The * is replaced by an integral ordinal number.

Example

Create a server class.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/serverclasses \
	-d name=sc_apps_ombra
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclasses</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/serverclasses</id>
  <updated>2013-08-10T13:18:28-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/serverclasses/_new" rel="create"/>
  <link href="/services/deployment/server/serverclasses/rename" rel="rename"/>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>sc_apps_ombra</title>
    <id>https://vgenovese-centos62x64-2:8089/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_ombra</id>
    <updated>2013-08-10T13:18:28-07:00</updated>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_ombra" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_ombra" rel="list"/>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_ombra" rel="edit"/>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_ombra" rel="remove"/>
    <link href="/servicesNS/nobody/search/deployment/serverclasses/sc_apps_ombra/applications" rel="applications"/>
    <link href="/servicesNS/nobody/search/deployment/serverclasses/sc_apps_ombra/clients" rel="clients"/>
    <link href="/servicesNS/nobody/search/deployment/serverclasses/sc_apps_ombra/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="blacklist-size">0</s:key>
        <s:key name="currentDownloads">0</s:key>
        <!-- opensearch nodes elided for brevity -->
        <s:key name="loadTime">1376165908</s:key>
        <s:key name="machineTypesFilter"></s:key>
        <s:key name="repositoryList">
          <s:dict>
            <s:key name="wma-app-test2"/>
            <s:key name="wma-app3"/>
            <s:key name="wma-app_test1"/>
          </s:dict>
        </s:key>
        <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="stateOnClient">enabled</s:key>
        <s:key name="whitelist-size">0</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/serverclasses/rename

Rename a server class.

POST deployment/server/serverclasses/rename

Specify a new name for a server class.

Request

Name Type Required Default Description
newName String
The new name of the server class.
oldName String
The current name of the server class.

Response Codes

Status Code Description
200 Endpoint returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to access resource.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Rename the server class from sc_apps_ombra to sc_apps_shadow

curl -k -u admin:pass \
	https://localhost:8089/services/deployment/server/serverclasses/rename \
	-d oldName=sc_apps_ombra \
	-d newName=sc_apps_shadow
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclasses</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/serverclasses</id>
  <updated>2013-10-09T08:54:09-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/serverclasses/_new" rel="create"/>
  <link href="/services/deployment/server/serverclasses/rename" rel="rename"/>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>sc_apps_shadow</title>
    <id>https://vgenovese-centos62x64-2:8089/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_shadow</id>
    <updated>2013-10-09T08:54:09-07:00</updated>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_shadow" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_shadow" rel="list"/>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_shadow" rel="edit"/>
    <link href="/servicesNS/nobody/search/deployment/server/serverclasses/sc_apps_shadow" rel="remove"/>
    <link href="/servicesNS/nobody/search/deployment/serverclasses/sc_apps_shadow/applications" rel="applications"/>
    <link href="/servicesNS/nobody/search/deployment/serverclasses/sc_apps_shadow/clients" rel="clients"/>
    <link href="/servicesNS/nobody/search/deployment/serverclasses/sc_apps_shadow/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="blacklist-size">0</s:key>
        <s:key name="currentDownloads">0</s:key>
        <!--eai:acl nodes elided for brevity -->
        <s:key name="loadTime">1381334049</s:key>
        <s:key name="machineTypesFilter"></s:key>
        <s:key name="repositoryList">
          <s:dict>
            <s:key name="tmp"/>
            <s:key name="wma-app-test2"/>
            <s:key name="wma-app3"/>
            <s:key name="wma-app_test1"/>
          </s:dict>
        </s:key>
        <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="stateOnClient">enabled</s:key>
        <s:key name="whitelist-size">0</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

deployment/server/serverclasses/{name}

DELETE deployment/server/serverclasses/{name}

Remove the specfied server class from this deployment server.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete the server class.
404 Specified server class does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Removes the named server class, sc_apps_shadow.

curl -k -u admin:pass --request DELETE \
   https://localhost:8089/services/deployment/server/serverclasses/sc_apps_shadow
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclasses</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/serverclasses</id>
  <updated>2013-10-09T09:13:27-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/serverclasses/_new" rel="create"/>
  <link href="/services/deployment/server/serverclasses/rename" rel="rename"/>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>sc_apps_wma</title>
    <id>https://vgenovese-centos62x64-2:8089/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma</id>
    <updated>2013-10-09T09:13:27-07:00</updated>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="list"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="edit"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_apps_wma" rel="remove"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_apps_wma/applications" rel="applications"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_apps_wma/clients" rel="clients"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_apps_wma/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="blacklist-size">0</s:key>
        <s:key name="currentDownloads">0</s:key>
        <!-- eai:acl nodes elided for brevity -->
        <s:key name="loadTime">1381335207</s:key>
        <s:key name="machineTypesFilter"></s:key>
        <s:key name="repositoryList">
          <s:dict>
            <s:key name="tmp"/>
            <s:key name="wma-app-test2"/>
            <s:key name="wma-app3"/>
            <s:key name="wma-app_test1"/>
          </s:dict>
        </s:key>
        <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="stateOnClient">enabled</s:key>
        <s:key name="whitelist-size">1</s:key>
        <s:key name="whitelist.0">Ombra*</s:key>
      </s:dict>
    </content>
  </entry>
  <!-- List of other remaining server classes elided for brevity -->
</feed>

GET deployment/server/serverclasses/{name}

List information about the named server class.

Request

Name Type Required Default Description
clientId String GUID of a deployment client that is a member of the named server class.

Lists information about the named server class with respect to this client.

hasDeploymentError Boolean Indicates whether to only list server classes that have a deployment error.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view this resource.
404 Specified resource does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
blacklist-size Specifies the size of the blacklist for the named server class.
clientId ID of deployment client for this server class.
currentDownloads The number of entires in the blacklist for this serverclass.
eai:attributes See Accessing Splunk resources
hasDeploymentError Indicates whether the serverclass has at least one deployment error.
loadTime The time, in epoch seconds, this serverclass was loaded.
machineTypesFilter List of filters to be used in boolean and logic with whitelist and blacklist filters.
repositoryList List of applications stored at the location specified by repositoryLocation.
repositoryLocation The location on the deployment server to store the content that is to be deployed for this server class.
restartSplunkWeb Indicates whether to restart Splunk Web.
restartSplunkd Indicates whether to restart splunkd.
stateOnClient Indicates whether this server class is enabled or disabled.
whitelist-size Specifies the number of entries in the whitelist for this server class.
whitelist.0 List of servers for whitelist.0 for this server class.

Example

List details about the named server class, sc_mach_type.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/serverclasses/sc_mach_type
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclasses</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/serverclasses</id>
  <updated>2013-08-04T19:19:34-07:00</updated>
  <generator build="172889" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/serverclasses/_new" rel="create"/>
  <link href="/services/deployment/server/serverclasses/rename" rel="rename"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>sc_mach_type</title>
    <id>https://vgenovese-centos62x64-2:8089/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type</id>
    <updated>2013-08-04T19:19:34-07:00</updated>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="list"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="edit"/>
    <link href="/servicesNS/nobody/system/deployment/server/serverclasses/sc_mach_type" rel="remove"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_mach_type/applications" rel="applications"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_mach_type/clients" rel="clients"/>
    <link href="/servicesNS/nobody/system/deployment/serverclasses/sc_mach_type/reload" rel="reload"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="blacklist-size">0</s:key>
        <s:key name="currentDownloads">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>continueMatching</s:item>
                <s:item>filterType</s:item>
                <s:item>machineTypesFilter</s:item>
                <s:item>repositoryLocation</s:item>
                <s:item>restartSplunkWeb</s:item>
                <s:item>restartSplunkd</s:item>
                <s:item>stateOnClient</s:item>
                <s:item>targetRepositoryLocation</s:item>
                <s:item>tmpFolder</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list>
                <s:item>blacklist\..*</s:item>
                <s:item>whitelist\..*</s:item>
              </s:list>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="loadTime">1375467593</s:key>
        <s:key name="machineTypesFilter">linux-x86_64,</s:key>
        <s:key name="repositoryList">
          <s:dict>
            <s:key name="wma-app2"/>
            <s:key name="wma-app1"/>
          </s:dict>
        </s:key>
        <s:key name="repositoryLocation">/opt/cluster/peer1/splunk/etc/deployment-apps</s:key>
        <s:key name="restartSplunkWeb">0</s:key>
        <s:key name="restartSplunkd">0</s:key>
        <s:key name="stateOnClient">enabled</s:key>
        <s:key name="whitelist-size">1</s:key>
        <s:key name="whitelist.0">Ombra*</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST deployment/server/serverclasses/{name}

Update the named server class.

Request

Name Type Required Default Description
blacklist.* String List of hosts to exclude for this server class.

For each blacklist, replace * with an ordinal number to specify additional blacklists. Filter ordinals must start at 0 and be consecutive.

continueMatching Boolen Controls how configuration is layered across classes and server-specific settings.

If true, configuration lookups continue matching server classes, beyond the first match. If false, only the first match is used. Matching is done in the order that server classes are defined. Defaults to true.

A serverClass can override this property and stop the matching.

filterType Enum Valid values: (whitelist | blacklist)

Determines the order of execution of filters. If filterType is whitelist, all whitelist filters are applied first, followed by blacklist filters. If filterType is blacklist, all blacklist filters are applied first, followed by whitelist filters.

The whitelist setting indicates a filtering strategy that pulls in a subset:

  • Items are not considered to match the server class by default.
  • Items that match any whitelist entry, and do not match any blacklist entry, are considered to match the server class.
  • Items that match any blacklist entry are not considered to match the server class, regardless of whitelist.

The blacklist setting indicates a filtering strategy that rules out a subset:

  • Items are considered to match the server class by default.
  • Items that match any blacklist entry, and do not match any whitelist entry, are considered to not match the server class.
  • Items that match any whitelist entry are considered to match the server class.

More briefly:

whitelist: default no-match -> whitelists enable -> blacklists disable
blacklist: default match -> blacklists disable-> whitelists enable

If you specify whitelist at the global level, and then specify blacklist for an individual server class, the setting becomes blacklist for that server class, and you have to provide another filter in that server class definition to replace the one you overrode.

machineTypesFilter String Comma-separated list of filters to be used in boolean and logic with whitelist and blacklist filters.

Only clients that match the white/blacklist filters AND that match this machineTypesFilter are included.

Thus the match is an intersection of the matches for the white/blacklist and the matches for MachineTypesFilter.

The patterns are PCRE regular expressions, with the following aids for easier entry:

  • You can specify '.' to mean '\\.'
  • You can specify '*' to mean '.*'
  • Matches are always case-insensitive; you do not need to specify the '(?i)' prefix.
repositoryLocation String The location on the deployment server to store the content that is to be deployed for this server class.

For example: $SPLUNK_HOME/etc/deployment-apps

restartSplunkWeb Boolean Indicates whether to restart SplunkWeb on the client when a member app or a directly configured app is updated.

Defaults to false

restartSplunkd Boolean Indicates whether to restart splunkd on the client when a member app or a directly configured app is updated.

Defaults to false

stateOnClient Enum Valid values are (enabled | disabled | noop).
  • enabled: Default value. Sets the application state to enabled on the client, regardless of state on the deployment server.
  • disabled: Sets the application state to disabled on the client, regardless of state on the deployment server.
  • noop: The state on the client is the same as on the deployment server.
targetRepositoryLocation String The location on the deployment client to install the apps defined for this Deployment Server.

If unset, or set to empty, the repositoryLocation path is used. That is, defaults to:

$SPLUNK_HOME/etc/apps (the live configuration directory for a Splunk instance

Useful only with complex (for example, tiered) deployment strategies.


tmpFolder String Working folder used by deployment server.

Defaults to $SPLUNK_HOME/var/run/tmp

whitelist.* String List of hosts to accept for this server class.

For each whitelist, replace * with an ordinal number to specify additional whitelists. Filter ordinals must start at 0 and be consecutive.

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit the server class.
404 The specified server class does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Update the state of the named server class so the state on the client is the same as the stae on the server.

curl -k -u admin:pass https://localhost:8089/services/deployment/server/serverclasses/sc_apps_ombra \
	-d stateOnClient=noop
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>serverclasses</title>
  <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/serverclasses</id>
  <updated>2013-08-10T13:24:16-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/deployment/server/serverclasses/_new" rel="create"/>
  <link href="/services/deployment/server/serverclasses/rename" rel="rename"/>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>sc_apps_ombra</title>
    <id>https://vgenovese-centos62x64-2:8089/services/deployment/server/serverclasses/sc_apps_ombra</id>
    <updated>2013-08-10T13:24:16-07:00</updated>
    <link href="/services/deployment/server/serverclasses/sc_apps_ombra" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/deployment/server/serverclasses/sc_apps_ombra" rel="list"/>
    <link href="/services/deployment/server/serverclasses/sc_apps_ombra" rel="edit"/>
    <link href="/services/deployment/server/serverclasses/sc_apps_ombra" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- opensearch nodes elided for brevity -->
      </s:dict>
    </content>
  </entry>
</feed>

search/distributed/bundle-replication-files

Provide access to distributed search bundle replication files.

GET search/distributed/bundle-replication-files

List distributed search bundle replication files.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
force_list_all Boolean Indicates whether to force a listing of all bundle replication files.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view resource.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

List bundle replications files for a distributed search.

curl -k -u admin:pass \
  https://localhost:8089/services/search/distributed/bundle-replication-files
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>search-head-bundles</title>
  <id>https://vgenovese-centos62x64-2:8089/services/search/distributed/bundle-replication-files</id>
  <updated>2013-10-09T09:42:51-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>13134207368020721783</title>
    <id>https://vgenovese-centos62x64-2:8089/services/search/distributed/bundle-replication-files/13134207368020721783</id>
    <updated>2013-10-09T09:42:51-07:00</updated>
    <link href="/services/search/distributed/bundle-replication-files/13134207368020721783" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/search/distributed/bundle-replication-files/13134207368020721783" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="checksum">13134207368020721783</s:key>
        <!-- eai:acl nodes elided for brevity -->
        <s:key name="filename">vgenovese-centos62x64-2-1381336958.bundle</s:key>
        <s:key name="location">/opt/cluster/peer1/splunk/var/run/vgenovese-centos62x64-2-1381336958.bundle</s:key>
        <s:key name="timestamp">1381336958</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

search/distributed/bundle-replication-files/{name}

GET search/distributed/bundle-replication-files/{name}

LIst information about the specified bundle replication file. For {name}, specify the checksum for the file.

Request

Name Type Required Default Description
force_list_all Boolean Indicates whether to force a listing of the file.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view specified resource.
404 Specified resource does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

List information about the bundle replication file indicated by its checksum value (13134207368020721783)

curl -k -u admin:pass \
	https://localhost:8089/services/search/distributed/bundle-replication-files/13134207368020721783
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>search-head-bundles</title>
  <id>https://vgenovese-centos62x64-2:8089/services/search/distributed/bundle-replication-files</id>
  <updated>2013-10-09T10:07:17-07:00</updated>
  <generator build="176231" version="6.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity -->
  <s:messages/>
  <entry>
    <title>13134207368020721783</title>
    <id>https://vgenovese-centos62x64-2:8089/services/search/distributed/bundle-replication-files/13134207368020721783</id>
    <updated>2013-10-09T10:07:17-07:00</updated>
    <link href="/services/search/distributed/bundle-replication-files/13134207368020721783" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/search/distributed/bundle-replication-files/13134207368020721783" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="checksum">13134207368020721783</s:key>
        <!-- eai:acl nodes elided for brevity -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>force_list_all</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="filename">vgenovese-centos62x64-2-1381336958.bundle</s:key>
        <s:key name="location">/opt/cluster/peer1/splunk/var/run/vgenovese-centos62x64-2-1381336958.bundle</s:key>
        <s:key name="timestamp">1381336958</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

search/distributed/config

Provides access to Splunk's distributed search options. This option is not for adding search peers.

GET search/distributed/config

Lists the configuration options for the distributed search system.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view configuration for distributed search.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
autoAddServers [Deprecated]
blacklistNames List of filenames that match the blacklist pattern, and are not replicated.
blacklistURLs List of URLs that are blacklisted, and thus will not be replicated.
checkTimedOutServersFrequency Rechecks servers at the specified frequency (in seconds). If this is set to 0, then no recheck occurs. Defaults to 60.

This attribute is ONLY relevant if removeTimedOutServers is set to true. If removeTimedOutServers is false, this attribute is ignored.

connectionTimeout TBD
disabled Indicates if the distributed search is disabled.
dist_search_enabled Indicates if the distributed search is enabled.
heartbeatFrequency [Deprecated]
heartbeatMcastAddr [Deprecated]
heartbeatPort [Deprecated]
receiveTimeout Amount of time in seconds to use as a timeout while trying to read/receive data from a search peer.
removedTimedOutServers If true, removes a server connection that cannot be made within serverTimeout.

If false, every call to that server attempts to connect. This may result in a slow user interface.

sendTimeout TBD
serverTimeout [Deprecated] Refer to connectionTimeout, sendTimeout, and receiveTimeout.
servers The initial list of servers.

If operating completely in autoAddServers mode (discovering all servers), there is no need to list any servers here.

shareBundles Indicates whether this server uses bundle replication to share search time configuration with search peers.

If set to false, the search head assumes that the search peers can access the correct bundles using an NFS share and have correctly configured the options listed under: "SEARCH HEAD BUNDLE MOUNTING OPTIONS."

skipOurselves [Deprecated]
statusTimeout Set connection timeout when gathering a search peer's basic info (/services/server/info). Read/write timeouts are automatically set to twice this value.
ttl [Deprecated]

Example

Retrieves distributed search configuration.


curl -k -u admin:pass https://localhost:8089/services/search/distributed/config


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>distsearch-setup</title>
  <id>https://localhost:8089/services/search/distributed/config</id>
  <updated>2011-07-10T23:21:51-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>distributedSearch</title>
    <id>https://localhost:8089/services/search/distributed/config/distributedSearch</id>
    <updated>2011-07-10T23:21:51-07:00</updated>
    <link href="/services/search/distributed/config/distributedSearch" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/search/distributed/config/distributedSearch" rel="list"/>
    <link href="/services/search/distributed/config/distributedSearch" rel="edit"/>
    <link href="/services/search/distributed/config/distributedSearch" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="autoAddServers">0</s:key>
        <s:key name="blacklistNames"/>
        <s:key name="blacklistURLs"/>
        <s:key name="checkTimedOutServersFrequency">60</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="dist_search_enabled">1</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="heartbeatFrequency">0</s:key>
        <s:key name="heartbeatMcastAddr">224.0.0.37</s:key>
        <s:key name="heartbeatPort">8888</s:key>
        <s:key name="removedTimedOutServers">0</s:key>
        <s:key name="serverTimeout">10</s:key>
        <s:key name="servers"/>
        <s:key name="shareBundles">1</s:key>
        <s:key name="skipOurselves">0</s:key>
        <s:key name="statusTimeout">10</s:key>
        <s:key name="ttl">1</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

search/distributed/peers

Provides distributed peer server management.

A search peer is defined as a splunk server to which another splunk server distributes searches. The splunk server where the search request originates is referred to as the search head.

GET search/distributed/peers

Returns a list of configured search peers that this search head is configured to distribute searches to. This includes configured search peers that have been disabled.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view search peer.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
build The Splunk build number for this peer.
bundle_versions The IDs of the bundles (of this search head) that the peer has.

The IDs are sorted from latest to earliest.

disabled Indicates if the peer is disabled.
guid GUID of the peer.
is_https Inidcates if the management port is ussing SSL.
licenseSignature The license signature.
peerName The Splunk server name of the peer.
peerType Specifies whether the peer is configured or discovered.
replicationStatus The status of bundle replication to this peer. Can be any of the following values:
Initial
In progress
Failed
Successful
Mounted
status The status of the peer.

Can be one of the following values:

Up
Down
Blacklisted
Not a Splunk server
Free Splunk server
Authentication Failed
Duplicate License
Duplicate Servername
Inconsistent bundles
version The Splunk version string this peer is running.

Example

This example lists configured search peers that this search head is configured to distribute searches to.



curl -k -u admin:pass https://localhost:8089/services/search/distributed/peers


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>distsearch-peer</title>
  <id>https://localhost:8089/services/search/distributed/peers</id>
  <updated>2011-07-11T18:21:48-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/search/distributed/peers/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>tiny:8090</title>
    <id>https://localhost:8089/services/search/distributed/peers/tiny%3A8090</id>
    <updated>2011-07-11T18:21:48-07:00</updated>
    <link href="/services/search/distributed/peers/tiny%3A8090" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/search/distributed/peers/tiny%3A8090" rel="list"/>
    <link href="/services/search/distributed/peers/tiny%3A8090" rel="edit"/>
    <link href="/services/search/distributed/peers/tiny%3A8090" rel="remove"/>
    <link href="/services/search/distributed/peers/tiny%3A8090/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="build"/>
        <s:key name="bundle_versions">
          <s:list/>
        </s:key>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="guid"/>
        <s:key name="is_https">1</s:key>
        <s:key name="licenseSignature"/>
        <s:key name="peerName">tiny:8090</s:key>
        <s:key name="peerType">configured</s:key>
        <s:key name="replicationStatus">Initial</s:key>
        <s:key name="status">Down</s:key>
        <s:key name="version"/>
      </s:dict>
    </content>
  </entry>
</feed>


POST search/distributed/peers

Add a new distributed search peer.

The distributed search must first be enabled using the search/distributed/config endpoint.

Request

Name Type Required Default Description
name String
The name of the search peer.

Defined as hostname:port, where port is the management port.

remotePassword String
The password of the remote user.
remoteUsername String
The username of a user with admin privileges in the search peer server.

This is used to exchange certificates.

Response Codes

Status Code Description
201 Created successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to create specified resource.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

This example adds a new search peer. Note that distributed search must first be enabled using the search/distributed/config endpoint.



curl -k -u admin:pass https://localhost:8089/services/search/distributed/peers \
	-d name=MrT:8092 \
	-d remoteUsername=admin \
	-d remotePassword=mypass


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>distsearch-peer</title>
  <id>https://localhost:8089/services/search/distributed/peers</id>
  <updated>2011-07-11T18:22:00-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/search/distributed/peers/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>


PREVIOUS
Configurations
  NEXT
Indexes

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14


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