Distributed Deployment Manual

 


Define server classes

NOTE - Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

Define server classes

A server class defines a deployment configuration shared by a group of deployment clients. It defines both the criteria for being a member of the class and the set of content to deploy to members of the class. This content (encapsulated as "deployment apps") can consist of Splunk apps, Splunk configurations, and other related content, such as scripts, images, and supporting material. You can define different server classes to reflect the different requirements, OSes, machine types, or functions of your deployment clients.

You define server classes in serverclass.conf on the deployment server. You can also define server classes and perform basic configuration through the Splunk Manager. To perform advanced configuration tasks, however, you'll need to edit serverclass.conf.

Use serverclass.conf

You can define server classes in serverclass.conf on the deployment server. Create one in $SPLUNK_HOME/etc/system/local. For information about configuration files, including an explanation of their basic structure, see "About configuration files" in the Admin manual.

If you have multiple server classes, you might want to define one server class that applies to all deployment clients by default. You can then override various aspects of it as needed by defining more specific server classes. For example, if you have a mix of Windows and Linux universal forwarders sending data to the same indexer, you might want to make sure that all forwarders get a common outputs.conf file, but that Windows forwarders get one inputs.conf file while Linux forwarders get a different one. In that case, you could define an "all forwarder" server class that distributes a deployment app containing the outputs.conf file to all forwarders, while also defining Windows and Linux server classes that distribute separate apps containing the different inputs.conf files to the appropriate subsets of forwarders.

In addition to defining attributes and content for specific server classes, you can also define attributes that pertain just to a single app within a server class.

A deployment client has its own configuration, defined in deploymentclient.conf. The information in deploymentclient.conf tells the deployment client where to go to get the content that the server class it belongs to says it should have.

The next section provides a reference for the server class configuration settings. You might want to read it while referring to the set of simple example configurations presented later in this topic. In addition, there are several longer and more complete examples presented later in this manual, including "Deploy several forwarders".

What you can configure for a server class

You can specify settings for a global server class, as well as for individual server classes or apps within server classes. There are three levels of stanzas to enable this:

Stanza Meaning Scope
[global] The global server class. Attributes defined here pertain to all server classes.
[serverClass:<serverClassName>] Individual server class. A serverClass is a collection of apps. Attributes defined here pertain to just the server class <serverClassName>.

Note: <serverClassName> cannot contain spaces.

[serverClass:<serverClassName>:app:<appName>] App within server class. Attributes defined here pertain to just the specified deployment app <appName> within the specified <serverClassName>. To indicate all apps within <serverClassName>, <appName> can be the wildcard character: *, in which case it will cause all content in the repositoryLocation to be added to this serverClass.

Important: When defining app names, you should be aware of the rules of configuration file precedence, as described in the topic "Configuration file precedence" in the Admin manual. In particular, note that app directories are evaluated by ASCII sort order. For example, if you set an attribute/value pair whatever=1 in the file x.conf in an app directory named "A", the setting in app A overrides the setting whatever=0 in x.conf in an app named "B", etc. For details, see the subtopic "How app names affect precedence".

Attributes in more specific stanzas override less specific stanzas. Therefore, an attribute defined in a [serverClass:<serverClassName>] stanza will override the same attribute defined in [global].

The attributes are definable for each stanza level, unless otherwise indicated. Here are the most common ones:

Attribute What it's for Default
repositoryLocation The location on the deployment server where the content to be deployed for this server class is stored. $SPLUNK_HOME/etc/deployment-apps
targetRepositoryLocation The location on the deployment client where the content to be deployed for this server class should be installed. You can override this in deploymentclient.conf on the deployment client. $SPLUNK_HOME/etc/apps
continueMatching If set to false, the deployment server will look through the list of server classes in this configuration file and stop when it matches the first one to a client. If set to true, the deployment server will continue to look and match. This option is available because you can define multiple, layered sets of server classes. A serverClass can override this property and stop the matching. true
endpoint The HTTP location from which content can be downloaded by a deployment client. The deployment server fills in the variable substitutions itself, based on information received from the client. You can provide any URI here, as long as it uses the same variables. In most cases, this attribute does not need to be specified. $deploymentServerUri$/services/streams/deployment?name=$serverClassName$:$appName$
filterType Set to "whitelist" or "blacklist".

This 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 stanza by default.
  • Items that match any whitelist entry, and do not match any blacklist entry, are considered to match the stanza.
  • Items that match any blacklist entry are not considered to match the stanza, regardless of whitelist.

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

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

More briefly:

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

You can override this value at the serverClass and serverClass:app levels. 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.

whitelist
whitelist.<n>

blacklist.<n>

<n> is a number starting at 0, and incrementing by 1.

Set the attribute to ipAddress, hostname, or clientName:

  • ipAddress is the IP address of the deployment client. Can use wildcards, such as 10.1.1.*
  • hostname is the host name of deployment client. Can use wildcards, such as *.splunk.com.
  • clientName is a logical or tag name that can be assigned to a deployment client in deploymentclient.conf. clientName takes precedence over ipAddress or hostname when matching a client to a filter.

Here are some examples: When filterType is whitelist:

whitelist.0=*.fflanda.com
blacklist.0=printer.fflanda.com
blacklist.1=scanner.fflanda.com

This will cause all hosts in fflanda.com, except 'printer' and 'scanner' to match this server class.

When filterType is blacklist:

blacklist.0=*
whitelist.0=*.web.fflanda.com
whitelist.1=*.linux.fflanda.com

This will cause only the 'web' and 'linux' hosts to match the server class. No other hosts will match.

You can override this value at the serverClass and serverClass:app levels.

Important: Overriding one type of filter (whitelist/blacklist) causes the other to be overridden too. If, for example, you override the whitelist, the blacklist will not be inherited from the parent; you must provide one in the stanza.

n/a
stateOnClient Set to "enabled", "disabled", or "noop". This setting specifies whether the deployment client receiving an app should enable or disable the app once it is installed. The "noop" value is for apps that do not require enablement; for example, apps containing only Splunk knowledge, such as event or source types. enabled
machineTypesFilter Matches any of the machine types in a comma-separated list.

This setting lets you use the hardware type of the deployment client as a filter. This filter will be used only if a client matches the whitelist/blacklist filters.

The value for machineTypesFilter is a comma-separated list of machine types; for example, linux-i686, linux-x86_64, etc. Each machine type is a specific string designated by the hardware platform itself.

Note: A machineTypesFilter value can contain wildcards; for example: linux-*, windows-*, or aix-*

The method for finding this string on the client varies by platform, but if the deployment client is already connected to the deployment server, you can determine the string's value by using this Splunk CLI command on the deployment server:

./splunk list deploy-clients

This will return a value for utsname that you can use to specify machineTypesFilter.

This setting will match any of the machine types in a comma-delimited list. Commonly-used machine types are linux-x86_64, windows-x64, linux-i686, freebsd-i386, darwin-i386, sunos-sun4u, linux-x86_64, sunos-i86pc, freebsd-amd64.

n/a
restartSplunkWeb Set to "true" or "false". Determines whether the client's Splunk Web restarts after the installation of a server class or app. false
restartSplunkd Set to "true" or "false". Determines whether the client's splunkd restarts after the installation of a server class or app. false

Note: The most accurate and up-to-date list of settings available for a given configuration file is in the .spec file for that configuration file. You can find the latest version of the .spec and .example files for serverclass.conf in serverclass.conf in the Configuration file reference in the Admin manual, or in $SPLUNK_HOME/etc/system/README.

Examples

Here are several examples of defining server classes in the serverclass.conf file:


# Example 1
# Matches all clients and includes all apps in the server class

[global]
whitelist.0=*
# whitelist matches all clients.
[serverClass:AllApps]
[serverClass:AllApps:app:*]
# a server class that encapsulates all apps in the repositoryLocation 


# Example 2
# Assign server classes based on hostnames.

[global]

[serverClass:AppsForOps]
whitelist.0=*.ops.yourcompany.com
[serverClass:AppsForOps:app:unix]
[serverClass:AppsForOps:app:SplunkLightForwarder]

[serverClass:AppsForDesktops]
filterType=blacklist
# blacklist everybody except the Windows desktop machines.
blacklist.0=* 
whitelist.0=*.desktops.yourcompany.com
[serverClass:AppsForDesktops:app:SplunkDesktop]


# Example 3
# Deploy server class based on machine types

[global]
# whitelist.0=* at the global level ensures that the machineTypesFilter attribute
# invoked later will apply.
whitelist.0=*

[serverClass:WindowsMachineTypes]
machineTypesFilter=windows-*

[serverClass:WindowsMachineTypes:app:WindowsApp]

[serverClass:LinuxMachineTypes]
machineTypesFilter=linux-i686, linux-x86_64

[serverClass:LinuxMachineTypes:app:LinuxApp]

Use Splunk Manager

To define deployment server classes in Splunk Manager:

1. Go to Splunk Manager > Deployment.

2. Select Add new from the Deployment server row.

3. Enter values for the Server class and Repository location fields.

4. Optionally, enter values for whitelists or blacklists.

For more information on what to enter in these fields, see the descriptions for the corresponding attributes in "What you can configure for a server class", located above.

You can only configure the most basic options using Splunk Manager. For advanced configurations, edit serverclass.conf directly.

This documentation applies to the following versions of Splunk: 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 , 5.0 , 5.0.1 , 5.0.2 , 5.0.3 , 5.0.4 , 5.0.5 , 5.0.6 , 5.0.7 , 5.0.8 , 5.0.9 , 5.0.10 View the Article History for its revisions.


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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!