Relocating the fishbucket for a Universal Forwarder to a separate drive

Applicability

Description

The fishbucket stores file-monitoring checkpoints. These checkpoints allow a Universal Forwarder to continue reading monitored files from their saved positions.

There is no documented setting that relocates only the fishbucket. The documented SPLUNK_DB setting changes the data directory root that contains the index directories; the fishbucket is stored under that root. Therefore, changing SPLUNK_DB changes the location of the complete data directory, not just the fishbucket.

A symbolic link that redirects only the fishbucket is not documented as the recommended configuration.

In version 10.2, the Universal Forwarder uses the same SQLite-based fishbucket architecture as Splunk Enterprise 10.2. The fishbucket location remains unchanged, and existing checkpoints continue to be read. The SQLite database files include:

fishbucket.sqlite.db
fishbucket.sqlite.db-wal

The instance.cfg file stores the instance GUID, not file-monitoring read positions. It is separate from the fishbucket and is not moved by SPLUNK_DB.

Investigation

Follow these steps to identify the configured fishbucket location.

Step 1: Check the data directory setting

Inspect %SPLUNK_HOME%\etc\splunk-launch.conf and look for SPLUNK_DB. If it is not set, the Windows default is:

%SPLUNK_HOME%\var\lib\splunk

Step 2: Locate the fishbucket

Under the effective data directory root, locate:

fishbucket\splunk_private_db

For Universal Forwarder 10.2, the SQLite database files include:

fishbucket.sqlite.db
fishbucket.sqlite.db-wal

Step 3: Distinguish instance identity from file checkpoints

The instance GUID is stored in %SPLUNK_HOME%\etc\instance.cfg. This file does not store file-monitoring read positions. Do not modify or remove it.

Resolution

Recommended configuration

1. Use SPLUNK_DB in %SPLUNK_HOME%\etc\splunk-launch.conf when the data directory must be placed on another drive.
2. Set it to the root directory for the instance’s data and index directories. For example:

%SPLUNK_HOME%\etc\splunk-launch.confSPLUNK_DB = E:\SplunkData

splunk-launch.conf has no stanza for this setting. The example changes the complete data directory root; it does not relocate only the fishbucket.

3. When changing an existing installation, preserve the existing data directory and its fishbucket checkpoints at the destination before resuming file monitoring. Changing the setting should not be treated as a procedure that automatically moves existing data.
4. Validate the configuration in a non-production environment before deploying it. Confirm that the Universal Forwarder can access the destination and that the fishbucket checkpoints persist across restart or virtual desktop recreation.

A fishbucket-only symbolic link is not documented as the recommended method. Prefer the documented SPLUNK_DB setting when relocation is required.

Retain the fishbucket data for each instance. If an instance starts without its previous checkpoints, it may read previously monitored file content again and index duplicate events.

Related Links

Splunk Enterprise 10.2 splunk-launch.conf reference

Splunk Enterprise 10.2 instance.cfg.conf reference

Understanding file monitoring on Splunk Forwarders: The basics of fishbucket and CRC