11.3 Server Classes, Client Grouping & App Deployment Strategies

Server Classes, Client Grouping & App Deployment Strategies

Quick Summary: The core intelligence of the Splunk Deployment Server resides in serverclass.conf. This configuration file defines Server Classes—logical groupings that map specific deployment clients to one or more deployment apps. By leveraging granular whitelists and blacklists based on hostnames, IP subnets, machine architectures, and explicit client names, administrators can target configuration delivery across heterogeneous enterprise server fleets.

---

Detailed Anatomy of serverclass.conf

The serverclass.conf file is maintained on the Deployment Server inside $SPLUNK_HOME/etc/system/local/ or within a specialized management application. Its structure is hierarchical, consisting of three main stanza tiers:

# 1. Global Default Stanza
[global]
restartSplunkd = false
stateOnClient = enabled

# 2. Server Class Definition Stanza
[serverClass:Production_WebServers]
whitelist.0 = web*.prod.corp.internal
whitelist.1 = 10.200.15.*
blacklist.0 = web-dev*
restartSplunkd = false

# 3. Server Class App Association Stanzas
[serverClass:Production_WebServers:app:org_all_forwarder_outputs]
restartSplunkd = true

[serverClass:Production_WebServers:app:org_app_apache_inputs]
restartSplunkd = false
issueReload = true

Stanza Levels & Inheritance Rules

1. [global]: Establishes default behaviors applied to all server classes and all apps unless explicitly overridden at a lower level.
2. [serverClass:<class_name>]: Defines a specific server class named <class_name>. The filters specified in this stanza determine which deployment clients belong to this class. Attributes defined here (such as restartSplunkd) override the [global] defaults for all apps mapped within this class.
3. [serverClass:<class_name>:app:<app_name>]: Binds the deployment app <app_name> to <class_name>. Settings defined in this stanza represent the highest precedence level and override both class-level and global-level settings for that specific app.

---

Client Filtering Mechanisms: Include, Exclude, and Machine Type

A server class decides which clients it applies to with three kinds of filters:

• <n> is an unsigned integer, such as whitelist.0 and whitelist.1.
• A filter value is compared with the client's details in this order: clientName, IP address, DNS name, host name, instance ID.
• You can also load filter values from a file with whitelist.from_pathname / blacklist.from_pathname.

How Filters Combine (default filterType = whitelist)

1. By default, clients are not in the server class.
2. A client that matches any include entry and no exclude entry is in the class.
3. A client that matches any exclude entry is out, whatever the include list says.
4. The machine type filter then narrows the result of the include/exclude filters. To select on machine type alone, you still need an include filter of *.

With filterType = blacklist the logic is reversed: clients match by default, excludes remove them, and includes add them back. Forwarder management requires the default whitelist filter type.

Two-Tier Filtering: Class-Level vs. App-Level

Filters can be set at the global, server class, or app level, and the more specific level wins:

[serverClass:Corporate_Endpoints]
# Class-level filter: every corporate endpoint subnet
whitelist.0 = 10.50.*

[serverClass:Corporate_Endpoints:app:Splunk_TA_windows]
# App-level filter: only Windows clients get the Windows add-on
whitelist.0 = *
machineTypesFilter = windows-x64

[serverClass:Corporate_Endpoints:app:Splunk_TA_nix]
# App-level filter: only 64-bit Linux clients get the *nix add-on
whitelist.0 = *
machineTypesFilter = linux-x86_64

A Windows host at 10.50.12.4 is in Corporate_Endpoints because of the class-level include. It receives Splunk_TA_windows because its machine type is windows-x64, and it does not receive Splunk_TA_nix. When you override one filter type at a lower level, the other type is not inherited, so the lower stanza must supply the filters it needs.

---

App Installation Directives & Client Control Settings

When a client downloads a deployment app, the Deployment Server instructs the client on how to handle the app using directives configured in serverclass.conf:

1. restartSplunkd = true | false

• Default Value: false
• Function: Dictates whether the client's splunkd background daemon automatically restarts after the app is extracted into $SPLUNK_HOME/etc/apps/.
• When to Set true:
  • Deploying or updating outputs.conf (altering target indexer pools or TLS certificates).
  • Deploying or updating server.conf or web.conf.
  • Deploying new compiled binary executables, custom search commands, or modular input libraries in bin/.
• When to Set false:
  • Deploying simple file-monitoring inputs.conf or props.conf updates that can be loaded dynamically without terminating active data streams.

2. stateOnClient = enabled | disabled | noop

• Default Value: enabled
• Function: Controls the runtime state of the app on the client:
  • enabled: The app archive is unpacked into $SPLUNK_HOME/etc/apps/<app_name>/ and marked active. Its inputs, scripts, and configurations execute normally.
  • disabled: The app is installed on the client but left disabled. This is useful for pre-staging configuration.
  • noop: For apps that need no enablement, such as apps that contain only event types and source types.

3. issueReload = true | false

• Default Value: false
• Function: Informs the deployment client to issue an internal HTTP REST reload command to specific subsystems (such as data input monitors) upon downloading the app. This allows new file monitors in inputs.conf to take effect without incurring a full splunkd process restart.

4. targetRepositoryLocation = <path>

• Default Value: $SPLUNK_HOME/etc/apps
• Function: Specifies the root filesystem directory on the client where the app bundle should be extracted. While rarely altered in standard forwarder environments, it can be adjusted if apps must be staged in non-standard modular repositories.

---

Reload Workflows & App Checksum Verification

A common administrative mistake occurs when an administrator modifies a configuration file inside $SPLUNK_HOME/etc/deployment-apps/<app_name>/ or updates serverclass.conf directly on the Deployment Server filesystem, only to discover that forwarders never download the updated configuration.

Why Changes on Disk Are Not Automatically Deployed

To maximize performance, the Deployment Server caches serverclass.conf in memory and tracks deployment apps using calculated package checksums (hashes computed across the contents of the app directory). The Deployment Server does not continuously watch the filesystem for changes.

When a client phones home, it sends its installed app checksum. The Deployment Server compares this value against its in-memory cached checksum. If the administrator altered a file on disk but did not trigger a reload, the cached checksum remains unchanged, and the Deployment Server incorrectly informs the client that its configuration is up to date.

Reload Execution Workflows

To invalidate the cache, recalculate app checksums, and update server class mappings, an administrator must execute a reload through one of three methods:

# Method 1: Reload all server classes and recalculate all app checksums via CLI
splunk reload deploy-server

# Method 2: Target a specific server class to minimize processing overhead
splunk reload deploy-server -class Production_WebServers

# Method 3: Invoke the REST API reload endpoint programmatically
curl -k -u admin:password -X POST \
  https://splunk-ds.corp.internal:8089/services/deployment/server/config/_reload

In addition, making and saving changes via the Forwarder Management graphical interface in Splunk Web automatically triggers an internal reload.

Verifying Deployment Status

• Forwarder management lists each client with its last phone-home time and the apps it has received.
• On the deployment server, splunk list deploy-clients lists the clients and the details filters can match on.
• On a client, splunk show deploy-poll shows the configured deployment server, and splunk display deploy-client shows whether the client is enabled.