server.conf - Splunk Documentation (original) (raw)

This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.

The following are the spec and example files for server.conf.

server.conf.spec

Version 7.3.0

############################################################################

This file contains settings and values to configure server options

in server.conf.

There is a server.conf in $SPLUNK_HOME/etc/system/default/. To set custom

configurations, place a copy of server.conf in

$SPLUNK_HOME/etc/system/local/.

For examples, see server.conf.example.

You must restart Splunk to enable configurations.

To learn more about configuration files (including how file precedence is

determined) see the Administration Manual section about configuration

files. Splunk documentation can be found at

https://docs.splunk.com/Documentation.

GLOBAL SETTINGS

Use the [default] stanza to define any global settings.

* You can also define global settings outside of any stanza at the top

of the file.

* Each configuration file should have at most one default stanza.

If you have multiple default stanzas, settings are combined. If you

have multiple definitions of the same settings, the last definition

in the file wins.

* If a setting is defined at both the global level and in a specific

stanza, the value in the specific stanza takes precedence.

General Server Configuration

[general] serverName =

• The name that identifies this Splunk software instance for features such as distributed search.
• Cannot be an empty string.
• Can contain environment variables.
• After any environment variables are expanded, the server name (if not an IPv6 address) can only contain letters, numbers, underscores, dots, and dashes. The server name must start with a letter, number, or an underscore.
• Default: -

hostnameOption =

• This option lets you specify the details in the server name that identifies this Splunk instance.
• Applies to Windows only.
• Can be one of the following: "fullyqualifiedname", "clustername", "shortname".
• Cannot be an empty string.

sessionTimeout = [s|m|h|d]

• The amount of time before a user session times out, expressed as a search-like time range.
• Examples include "24h" (24 hours), "3d" (3 days), "7200s" (7200 seconds, or two hours)
• Default: "1" (1 hour)

trustedIP =

• All logins from specified IP addresses are trusted. This means a password is no longer required.
• Only set this if you are using Single Sign-On (SSO).

allowRemoteLogin = always|never|requireSetPassword

• Controls remote management by restricting general login. Note that this does not apply to trusted SSO logins from a trustedIP.
• When set to "always", all remote login attempts are allowed.
• When set to "never", only local logins to splunkd are allowed. Note that this still allows remote management through splunkweb if splunkweb is on the same server.
• If set to "requireSetPassword":
  • In the free license, remote login is disabled.
  • In the pro license, remote login is disabled for the "admin" user if the default password of "admin" has not been changed.
• NOTE: As of version 7.1, Splunk software does not support the use of default passwords. The "requireSetPassword" value is deprecated and might be removed in the future.
• Default: requireSetPassword

tar_format = gnutar|ustar

• Sets the default TAR format.
• Default: gnutar

access_logging_for_phonehome =

• Enables/disables logging to the splunkd_access.log file for client phonehomes.
• Default: true (logging enabled)

hangup_after_phonehome =

• Controls whether or not the deployment server hangs up the connection after the phonehome is done.
• By default, persistent HTTP 1.1 connections are used with the server to handle phonehomes. This might show higher memory usage if you have a large number of clients.
• If you have more than the maximum recommended concurrent TCP connection deployment clients, persistent connections can not help with the reuse of connections. Setting this attribute to false helps bring down memory usage.
• Default: false (persistent connections for phonehome)

pass4SymmKey =

• Authenticates traffic between:
  • License master and its license slaves.
  • Members of a cluster.
  • Deployment server (DS) and its deployment clients (DCs).
• When authenticating members of a cluster, clustering might override the passphrase specified in the clustering stanza. A clustering searchhead connecting to multiple masters might further override in the [clustermaster:stanza1] stanza.
• When authenticating deployment servers and clients, by default, DS-DCs passphrase authentication is disabled. To enable DS-DCs passphrase authentication, you must also add the following line to the [broker:broker] stanza in the restmap.conf file: requireAuthentication = true
• In all scenarios, every node involved must set the same passphrase in the same stanzas. For example in the [general] stanza and/or [clustering] stanza. Otherwise, the respective communication does not proceed:
  • licensing and deployment in the case of the [general] stanza
  • clustering in case of the [clustering] stanza)
• Unencrypted passwords must not begin with "$1$". This is used by Splunk software to determine if the password is already encrypted.

listenOnIPv6 = no|yes|only

• By default, splunkd listens for incoming connections (both REST and TCP inputs) using IPv4 only.
• When you set this value to "yes", splunkd simultaneously listens for connections on both IPv4 and IPv6.
• To disable IPv4 entirely, set listenOnIPv6 to "only". This causes splunkd to exclusively accept connections over IPv6. You might need to change the mgmtHostPort setting in the web.conf file. Use '[::1]' instead of '127.0.0.1'.
• Any setting of SPLUNK_BINDIP in your environment or the splunk-launch.conf file overrides the listenOnIPv6 value. In this case splunkd listens on the exact address specified.

connectUsingIpVersion = auto|4-first|6-first|4-only|6-only

• When making outbound TCP connections for forwarding event data, making distributed search requests, etc., this setting controls whether the connections are made using IPv4 or IPv6.
• Connections to literal addresses are unaffected by this setting. For example, if a forwarder is configured to connect to "10.1.2.3" the connection is made over IPv4 regardless of this setting.
• "auto:"
  • If listenOnIPv6 is set to "no", the Splunk server follows the "4-only" behavior.
  • If listenOnIPv6 is set to "yes", the Splunk server follows "6-first"
  • If listenOnIPv6 is set to "only", the Splunk server follow "6-only" behavior.
• "4-first:" If a host is available over both IPv4 and IPv6, then the Splunk server connects over IPv4 first and falls back to IPv6 if the connection fails.
• "6-first": splunkd tries IPv6 first and fallback to IPv4 on failure.
• "4-only": splunkd only attempts to make connections over IPv4.
• "6-only": splunkd only attempts to connect to the IPv6 address.
• Default: auto. This means that the Splunk server selects a reasonable value based on the listenOnIPv6 setting.

guid =

• This setting (as of version 5.0) belongs in the [general] stanza of SPLUNK_HOME/etc/instance.cfg file. See the .spec file of instance.cfg for more information.

useHTTPServerCompression =

• Specifies whether the splunkd HTTP server should support gzip content encoding. For more info on how content encoding works, see Section 14.3 of Request for Comments: 2616 (RFC2616) on the World Wide Web Consortium (W3C) website.
• Default: true

defaultHTTPServerCompressionLevel =

• If the useHTTPServerCompression setting is enabled (it is enabled by default), this setting controls the compression level that the Splunk server attempts to use.
• This number must be between 1 and 9.
• Higher numbers produce smaller compressed results but require more CPU usage.
• Default: 6 (This is appropriate for most environments).

skipHTTPCompressionAcl =

• Lists a set of networks or addresses to skip data compression. These are addresses that are considered so close that network speed is never an issue, so any CPU time spent compressing a response is wasteful.
• Note that the server might still respond with compressed data if it already has a compressed version of the data available.
• These rules are separated by commas or spaces.
• Each rule can be in the following forms:
  1. A single IPv4 or IPv6 address, for example: "10.1.2.3", "fe80::4a3"
  2. A CIDR block of addresses, for example: "10/8", "fe80:1234/32"
  3. A DNS name, possibly with a '' used as a wildcard, for example: "myhost.example.com", ".splunk.com")
  4. A single '*' which matches anything
• Entries can also be prefixed with '!' to negate their meaning.
• Default: localhost addresses

legacyCiphers = decryptOnly|disabled

• This setting controls how Splunk software handles support for legacy encryption ciphers.
• If set to "decryptOnly", Splunk software supports decryption of configurations that have been encrypted with legacy ciphers. It encrypts all new configurations with newer and stronger cyphers.
• If set to "disabled", Splunk software neither encrypts nor decrypts configurations that have been encrypted with legacy ciphers.
• Default: decryptOnly

site =

• Specifies the site that this Splunk instance belongs to when multisite is enabled.
• Valid values for site-id include site0 to site63
• The special value "site0" can be set only on search heads or on forwarders that are participating in indexer discovery.
  • For a search head, "site0" disables search affinity. 
  • For a forwarder participating in indexer discovery, "site0" causes the forwarder to send data to all peer nodes across all sites.

useHTTPClientCompression = true|false|on-http|on-https

• Specifies whether gzip compression should be supported when Splunkd acts as a client (including distributed searches). Note: For the content to be compressed, the HTTP server that the client is connecting to should also support compression.
• If the connection is being made over https and useClientSSLCompression=true, then setting useHTTPClientCompression=true results in double compression work without much compression gain. To mitigate this, set this value to "on-http" (or to "true", and useClientSSLCompression to "false").
• Default: false

embedSecret =

• When using report embedding, normally the generated URLs can only be used on the search head that they were generated on.
• If "embedSecret" is set, then the token in the URL is encrypted with this key. Then other search heads with the exact same setting can also use the same URL.
• This is needed if you want to use report embedding across multiple nodes on a search head pool.

parallelIngestionPipelines =

• The number of discrete data ingestion pipeline sets to create for this instance.
• A pipeline set handles the processing of data, from receiving streams of events through event processing and writing the events to disk.
• An indexer that operates multiple pipeline sets can achieve improved performance with data parsing and disk writing, at the cost of additional CPU cores.
• For most installations, the default setting of "1" is optimal.
• Use caution when changing this setting. Increasing the CPU usage for data ingestion reduces available CPU cores for other tasks like searching.
• NOTE: Enabling multiple ingestion pipelines can change the behavior of some settings in other configuration files. Each ingestion pipeline enforces the limits of the following settings independently:
  1. maxKBps (in the limits.conf file)
  2. max_fd (in the limits.conf file)
  3. maxHotBuckets (in the indexes.conf file)
  4. maxHotSpanSecs (in the indexes.conf file)
• Default: 1

pipelineSetSelectionPolicy = <round_robin | weighted_random>

• Specifies the pipeline set selection policy to use while selecting pipeline sets for new inputs.
• If set to round_robin, the incoming inputs are assigned to pipeline sets in a round robin fashion.
• If set to weighted_random, the incoming inputs are assigned to pipeline sets using a weighted random scheme designed to even out the CPU usage of each pipeline set.
• NOTE: This setting only takes effect when parallelIngestionPipelines is greater than 1.
• Default: round_robin

pipelineSetWeightsUpdatePeriod =

• The interval, in seconds, when pipeline set weights are recalculated for the weighted_random pipeline set selection policy.
• Reducing this interval causes pipeline set weights to be re-evaluated more frequently, thereby enabling the system to react more quickly to changes in dutycycle estimation.
• Increasing this interval causes pipeline set weights to be re-evaluated less frequently, thereby reducing the likelihood of the system responding to bursty events.
• Default: 30

pipelineSetNumTrackingPeriods =

• The number of look-back periods, of interval pipelineSetWeightsUpdatePeriod, that are used to keep track of incoming ingestion requests for pipeline sets.
• This information is used as a heuristic to calculate the pipeline set weights at every expiry of pipelineSetWeightsUpdatePeriod.
• Default: 5

instanceType =

• Should not be modified by users.
• Informs components (such as the SplunkWeb Manager section) which environment the Splunk server is running in, to allow for more customized behaviors.
• Default: "download"

requireBootPassphrase =

• Prompt the user for a boot passphrase when starting splunkd.
• Splunkd uses this passphrase to grant itself access to platform-provided secret storage facilities, like the GNOME keyring.
• For more information about secret storage, see the [secrets] stanza in $SPLUNK_HOME/etc/system/README/authentication.conf.spec.
• Default (if Common Criteria mode is enabled): true
• Default (if Common Criteria mode is disabled): false

remoteStorageRecreateIndexesInStandalone =

• Controls re-creation of remote storage enabled indexes in standalone mode.
• Default: true

cleanRemoteStorageByDefault =

• Allows 'splunk clean eventdata' to clean the remote indexes when set to true.
• Default: false

recreate_index_fetch_bucket_batch_size =

• Controls the maximum number of bucket IDs to fetch from remote storage as part of a single transaction for a remote storage enabled index.
• Only valid for standalone mode.
• Default: 500

recreate_bucket_fetch_manifest_batch_size =

• Controls the maximum number of bucket manifests to fetch in parallel from remote storage.
• Only valid for standalone mode.
• Default: 100

splunkd_stop_timeout =

• The maximum time, in seconds, that splunkd waits for a graceful shutdown to complete before splunkd forces a stop.
• Default: 360 (6 minutes)

Deployment Configuration details

[deployment] pass4SymmKey = * Authenticates traffic between the deployment server (DS) and its deployment clients (DCs). * By default, DS-DCs passphrase authentication key is disabled. To enable DS-DCs passphrase authentication, you must also add the following line to the [broker:broker] stanza in the restmap.conf file: requireAuthentication = true * If the key is not set in the [deployment] stanza, the key is looked for in the [general] stanza. * NOTE: Unencrypted passwords must not begin with "$1$", because this is used by Splunk software to determine if the password is already encrypted.

SSL Configuration details

[sslConfig]

• Set SSL for communications on Splunk back-end under this stanza name.
  • NOTE: To set SSL (for example HTTPS) for Splunk Web and the browser, use the web.conf file.
• Follow this stanza name with any number of the following attribute/value pairs.
• If you do not specify an entry for each attribute, the default value is used.

enableSplunkdSSL =

• Enables/disables SSL on the splunkd management port (8089) and KV store port (8191).
• NOTE: Running splunkd without SSL is not recommended.
• Distributed search often performs better with SSL enabled.
• Default: true

useClientSSLCompression =

• Turns on HTTP client compression.
• Server-side compression is turned on by default. Setting this on the client-side enables compression between server and client.
• Enabling this potentially gives you much faster distributed searches across multiple Splunk instances.
• Default: true

useSplunkdClientSSLCompression =

• Controls whether SSL compression is used when splunkd is acting as an HTTP client, usually during certificate exchange, bundle replication, remote calls, etc.
• This setting is effective if, and only if, useClientSSLCompression is set to "true".
• NOTE: splunkd is not involved in data transfer in distributed search, the search in a separate process is.
• Default: true

sslVersions =

• Comma-separated list of SSL versions to support for incoming connections.
• The versions available are "ssl3", "tls1.0", "tls1.1", and "tls1.2".
• The special version "*" selects all supported versions. The version "tls" selects all versions tls1.0 or newer.
• If a version is prefixed with "-" it is removed from the list.
• SSLv2 is always disabled; "-ssl2" is accepted in the version list but does nothing.
• When configured in FIPS mode, "ssl3" is always disabled regardless of this configuration.
• The default can vary. See the 'sslVersions' setting in the $SPLUNK_HOME/etc/system/default/server.conf file for the current default.

sslVersionsForClient =

• Comma-separated list of SSL versions to support for outgoing HTTP connections from splunkd. This includes distributed search, deployment client, etc.
• This is usually less critical, since SSL/TLS always picks the highest version both sides support. However, you can use this setting to prohibit making connections to remote servers that only support older protocols.
• The syntax is the same as the 'sslVersions' setting above.
• NOTE: For forwarder connections, there is a separate 'sslVersions' setting in the outputs.conf file. For connections to SAML servers, there is a separate 'sslVersions' setting in the authentication.conf file.
• The default can vary. See the 'sslVersionsForClient' setting in the $SPLUNK_HOME/etc/system/default/server.conf file for the current default.

supportSSLV3Only =

• DEPRECATED. SSLv2 is disabled. The exact set of SSL versions allowed is configurable using the 'sslVersions' setting above.

sslVerifyServerCert =

• This setting is used by distributed search and distributed deployment clients.
  • For distributed search: Used when making a search request to another server in the search cluster.
  • For distributed deployment clients: Used when polling a deployment server.
• If set to true, make sure that the connected server is authenticated. Both the common name and the alternate name of the server are checked for a match if they are specified in this configuration file. A certificate is considered verified if either is matched.
• Default: false

sslCommonNameToCheck = , , ...

• If set, and 'sslVerifyServerCert' is set to true, splunkd limits most outbound HTTPS connections to hosts which use a certificate with one of the listed common names.
• The most important scenario is distributed search.
• This feature does not work with the deployment server and client communication over SSL.
• Optional.
• Default: No common name checking.

sslCommonNameList = , , ...

• DEPRECATED. Use the 'sslCommonNameToCheck' setting instead.

sslAltNameToCheck = , , ...

• If this value is set, and 'sslVerifyServerCert' is set to true, splunkd also verifies certificates which have a so-called "Subject Alternate Name" that matches any of the alternate names in this list.
  • Subject Alternate Names are effectively extended descriptive fields in SSL certificates beyond the commonName. A common practice for HTTPS certificates is to use these values to store additional valid hostnames or domains where the certificate should be considered valid.
• Accepts a comma-separated list of Subject Alternate Names to consider as valid.
• Items in this list are never validated against the SSL Common Name.
• This feature does not work with the deployment server and client communication over SSL.
• Optional.
• Default: No alternate name checking.

requireClientCert =

• Requires that any HTTPS client that connects to a splunkd internal HTTPS server has a certificate that was signed by a CA (Certificate Authority) specified by the 'sslRootCAPath' setting.
  • Used by distributed search: Splunk indexing instances must be authenticated to connect to another splunk indexing instance.
  • Used by distributed deployment: The deployment server requires that deployment clients are authenticated before allowing them to poll for new configurations/applications.
• If set to "true", a client can connect ONLY if a certificate created by our certificate authority was used on that client.
• Default: false

cipherSuite =

• If set, Splunk uses the specified cipher string for the HTTP server.
• If not set, Splunk uses the default cipher string provided by OpenSSL. This is used to ensure that the server does not accept connections using weak encryption protocols.
• Must specify 'dhFile' to enable any Diffie-Hellman ciphers.
• The default can vary. See the 'cipherSuite' setting in the $SPLUNK_HOME/etc/system/default/server.conf file for the current default.

ecdhCurveName =

• DEPRECATED.
• Use the 'ecdhCurves' setting instead.
• This setting specifies the Elliptic Curve Diffie-Hellman (ECDH) curve to use for ECDH key negotiation.
• Splunk only supports named curves that have been specified by their SHORT name.
• The list of valid named curves by their short and long names can be obtained by running this CLI command: $SPLUNK_HOME/bin/splunk cmd openssl ecparam -list_curves
• Default: empty string.

ecdhCurves =

• A list of ECDH curves to use for ECDH key negotiation.
• The curves should be specified in the order of preference.
• The client sends these curves as a part of an SSL Client Hello.
• The server supports only the curves specified in the list.
• Splunk software only supports named curves that have been specified by their SHORT names.
• The list of valid named curves by their short and long names can be obtained by running this CLI command: $SPLUNK_HOME/bin/splunk cmd openssl ecparam -list_curves
• Example setting: "ecdhCurves = prime256v1,secp384r1,secp521r1"
• The default can vary. See the 'ecdhCurves' setting in the $SPLUNK_HOME/etc/system/default/server.conf file for the current default.

serverCert =

• The full path to the PEM (Privacy-Enhanced Mail) format server certificate file.
• Certificates are auto-generated by splunkd upon starting Splunk Enterprise.
• You can replace the default certificate with your own PEM format file.
• Default: $SPLUNK_HOME/etc/auth/server.pem

sslKeysfile =

• DEPRECATED. Use the 'serverCert' setting instead.
• This file is in the directory specified by the 'caPath' setting (see below).
• Default: server.pem

sslPassword =

• Server certificate password.
• Default: "password"

sslKeysfilePassword =

• DEPRECATED. Use the 'sslPassword' setting instead.

sslRootCAPath =

• Full path to the root CA (Certificate Authority) certificate store on the operating system.
• The must refer to a PEM (Privacy-Enhanced Mail) format file containing one or more root CA certificates concatenated together.
• Required for Common Criteria.
• This setting is valid on Windows machines only if you have not set 'sslRootCAPathHonoredOnWindows' to "false".
• No default.

sslRootCAPathHonoredOnWindows =

• DEPRECATED.
• Whether or not the Splunk instance respects the 'sslRootCAPath' setting on Windows machines.
• If you set this setting to "false", then the instance does not respect the 'sslRootCAPath' setting on Windows machines.
• This setting is valid only on Windows, and only if you have set 'sslRootCAPath'.
• When the 'sslRootCAPath' setting is respected, the instance expects to find a valid PEM file with valid root certificates that are referenced by that path. If a valid file is not present, SSL communication fails.
• Default: true.

caCertFile =

• DEPRECATED. Use the 'sslRootCAPath' setting instead.
• Used only if 'sslRootCAPath' is not set.
• File name (relative to 'caPath') of the CA (Certificate Authority) certificate PEM format file containing one or more certificates concatenated together.
• Default: cacert.pem

dhFile =

• PEM (Privacy-Enhanced Mail) format Diffie-Hellman(DH) parameter file name.
• DH group size should be no less than 2048bits.
• This file is required in order to enable any Diffie-Hellman ciphers.
• No default.

caPath =

• DEPRECATED. Use absolute paths for all certificate files.
• If certificate files given by other settings in this stanza are not absolute paths, then they are relative to this path.
• Default: $SPLUNK_HOME/etc/auth.

certCreateScript =