Use serverclass.conf to define server classes
You can optionally define server classes by directly editing the serverclass.conf configuration file, rather than using the agent management interface. More advanced configurations might require you to edit serverclass.conf, because the agent management interface only handles a subset of possible configurations. You can also start the configuration process through agent management UI and then switch to directly editing the configuration file to deal with advanced configuration issues.
serverclass.conf directly, you will likely not be able to return later to configuring via the agent management interface. This is because the agent management interface can handle only a subset of the configurations possible through serverclass.conf. For details on what changes are compatible with agent management UI, see the topic Compatibility and agent management UI.Location for serverclass.conf
Create a serverclass.conf file in $SPLUNK_HOME/etc/system/local on the agent management. If you have previously defined one or more server classes by means of the agent management interface, this file will already exist and you just need to edit or append to it. For information on serverclass.conf, see The serverclass.conf file.
What you can configure for a server class
The most important settings define the set of agents and the set of apps for each server class. You can set most attributes at any of three stanza levels.
Stanza levels
You can specify settings at the global level, 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 level. | Attributes defined here provide default values for all server classes. Note: The [global] stanza is a template only and does NOT perform agent matching. Primary agent matching occurs at the serverClass level. |
[serverClass:<serverClassName>] | An individual server class. There can be multiple | Attributes defined here pertain to just the server class <serverClassName>. Note:
|
[serverClass:<serverClassName>:app:<appName>] | App within the named server class. You use this to specify the apps that the server class applies to. There can be multiple stanzas of this type - one for each app in the server class. | <appname> can be either the name of a single app (usually, its directory name in repositoryLocation) or the wildcard character "*" to specify all apps in repositoryLocation. Attributes defined here pertain to just the specified deployment app |
Understanding the three-level hierarchy:
- The global level provides default values but does not perform agent matching. It is a template only.
- The server class level performs primary agent matching. If an agent does not match at this level, it receives no apps from this server class, regardless of app-level filters.
- The app level performs secondary filtering within the server class scope. It can only further restrict which agents receive a specific app. It cannot add agents beyond those matched by the parent server class.
Attributes are definable at each stanza level, unless otherwise indicated in the serverclass.conf spec file. 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].
Atomic override behavior
When you override
whitelistorblacklistat a child level, you must explicitly define both to avoid clearing inherited values. Overriding one filter type causes the other to be cleared as well This applies to serverclass level and app level.Filter-triggered atomic override (level-dependent)
DefiningmachineTypesFilter,packageTypesFilter, orupdaterRunningFilterhas different behavior depending on the level:- At the app level: Defining any of these filters clears both inherited
whitelistandblacklistfrom the parent server class. You must explicitly define filters at the app level. - At the server class level: Defining any of these filters doesn't clear inherited
whitelistandblacklistfrom the global level.
- At the app level: Defining any of these filters clears both inherited
Filters not applicable at the global level
Defining
machineTypesFilter,packageTypesFilter, orupdaterRunningFilterat global level has no effect. These filters are only operational at the serverClass or app level.
Agent filtering attributes
The most common attributes are the ones that configure agent filtering. See the topic Set up agent filters for detailed information on those attributes.
Version 9.4.3 change: Starting in Splunk Enterprise version 9.4.3, the app-level implicit filterType has been standardized: its default has changed from blacklist (default-allow) to whitelist (default-deny), aligning the app to the server class layer for consistent filtering behavior. If you are upgrading from a pre-9.4.3 version and experience apps not deploying, you might need to add explicit whitelist or filterType settings at the app level. See the serverclass.conf specification file for migration guidance.
Non-filtering attributes
Most of the non-filtering attributes are rarely changed from their defaults. These ones are of particular interest:
| Attribute | What it's for | Default |
|---|---|---|
| repositoryLocation | The location on the agent management where the content to be deployed for this server class is stored. | $SPLUNK_HOME/etc /deployment-apps |
| excludeFromUpdate | Specifies paths to one or more top-level files or directories, and their contents, to exclude from being touched during app updates. Each comma-separated entry must be prefixed by $app_root$/. Useful for preserving local configurations. Requires version 6.2.x or higher for both deployment server and agent. | No default |
| stateOnClient | Set to "enabled", "disabled", or "noop". This setting specifies whether the agent 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 event and source types. | enabled |
| restartSplunkWeb | Set to "true" or "false". Determines whether the agent's Splunk Web restarts after receiving an update. | false |
| restartSplunkd | Set to "true" or "false". Determines whether the agent's splunkd restarts after receiving an update. | false |
| issueReload | Set to "true" or "false". Determines whether the agent's splunkd reloads after receiving an update. | false |
| restartIfNeeded | Set to "true" or "false". Valid only on forwarders newer than version 6.4. When set to "true" and issueReload is also "true", the agent attempts to reload the app. If the reload fails, the agent restarts automatically. This provides a best-effort reload with automatic fallback to restart. | false |
The most accurate and complete 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.
Interaction of restartSplunkd and issueReload
The behavior of the agent varies depending on the settings of restartSplunkd and issueReload. These are the options:
| issueReload | restartSplunkd | Behavior |
|---|---|---|
| true | false | Reload only. No restart. It might be necessary to issue a manual restart to fully activate the downloaded apps. |
| true | true | Agent reloads. If some app components require a restart to activate, the agent restarts. |
| false | false | The downloaded apps are not activated. |
| false | true | The agent always restarts after app updates. |
These settings are customizable on a server class basis.
These settings can be configured at the global, server class, or app level. More specific stanza levels override less specific ones. For example, you can set issueReload=true globally but override it with issueReload=false for specific apps that should not be activated immediately upon deployment.
Examples
For some simple examples of serverclass.conf configurations, see Set up agent filters. In addition, there are several longer and more complete examples presented later in this manual.
Reload the agent management
In order for changes to take effect, you must reload the agent management after you add a server class or change its configuration. For example, if you add an app to a server class, the agent management only deploys the new app to the server class agents after you reload. Similarly, if you change the agent filters for a server class, the change in the set of agents (and any subsequent app deployment) only takes effect after you reload.
To reload the agent management, invoke the CLI reload deploy-server command:
splunk reload deploy-server
For more information on reloading the agent management, see the topic Deploy apps to agents.