Study guide
4.5 The Fishbucket: File Tracking, CRC Collisions & Re-reading Files
Splunk Enterprise Certified Admin SPLK-1003
Track your progress as you read
Finished sections get a check mark.
1 Introduction
About the Splunk Enterprise Certified Admin Exam
2 Chapter 1: Splunk Admin Basics
1.1 Splunk Enterprise Architecture & Core Components
3 Chapter 2: License Management
2.1 License Types, Stacks, Pools & Licensing Architecture 2.2 License Violations, Rolling Window Warnings & Troubleshooting
4 Chapter 3: Splunk Configuration Files
3.1 Splunk Configuration Directory Structure 3.2 Configuration Layering, Precedence & Resolution Rules 3.3 Using btool to Inspect & Debug Configurations
5 Chapter 4: Splunk Indexes
4.1 Index Structure: Directories, Buckets & Bucket Files 4.2 Bucket Types & the Hot-Warm-Cold-Frozen-Thawed Lifecycle 4.3 Checking Index Data Integrity 4.4 indexes.conf Options: Paths, Bucket Sizing & Volumes 4.5 The Fishbucket: File Tracking, CRC Collisions & Re-reading Files 4.6 Applying a Data Retention Policy
6 Chapter 5: Splunk User Management
5.1 Splunk Roles, Capabilities & Custom Role Design 5.2 User Account Administration, Search Restrictions & Limits
7 Chapter 6: Splunk Authentication Management
6.1 Integrating Splunk with LDAP 6.2 Other Authentication Options & Enabling Multifactor Authentication
8 Chapter 7: Getting Data In
7.1 CLI Administration & Basic Data Onboarding Workflows 7.2 Forwarder Types: Universal Forwarder vs. Heavy Forwarder
9 Chapter 8: Distributed Search
8.1 How Distributed Search Works 8.2 Roles of the Search Head and Search Peers 8.3 Configuring Search Peers & Distributed Search Groups 8.4 Search Head Scaling & Search Head Clustering (SHC)
10 Chapter 9: Getting Data In – Staging
9.1 Ingestion Pipeline Stages: Input, Parsing, Merging, Typing & Indexing 9.2 Pipeline Component Placement & Queue Management 9.3 Splunk Input Options
11 Chapter 10: Configuring Forwarders
10.1 Forwarder Setup & outputs.conf Load Balancing 10.2 Indexer Acknowledgment, Data Cloning & Forwarder Routing
12 Chapter 11: Forwarder Management
11.1 Deployment Management & the Deployment Server 11.2 Deployment Apps & Deployment Clients 11.3 Server Classes, Client Grouping & App Deployment Strategies 11.4 Forwarder Management Monitoring & Troubleshooting
13 Chapter 12: Monitor Inputs
12.1 File & Directory Monitoring Mechanics 12.2 Monitor Input Tuning: Whitelists, Blacklists & CRC Settings 12.3 Deploying a Remote Monitor Input, Network Shares & Archives
14 Chapter 13: Network and Scripted Inputs
13.1 Creating Network Inputs: TCP & UDP 13.2 Optional Settings for Network Inputs 13.3 Scripted Inputs & PowerShell Data Collection
15 Chapter 14: Agentless Inputs
14.1 Windows Management Instrumentation (WMI) Inputs 14.2 HTTP Event Collector (HEC) Architecture & Administration
16 Chapter 15: Fine Tuning Inputs
15.1 Input-Phase Processing & Default Metadata Assignment 15.2 Character Set Encoding & Handling Binary Data
17 Chapter 16: Parsing Phase and Data
16.1 Line Breaking & Event Segmentation 16.2 Timestamp Extraction, Time Zones & Clock Skew Handling 16.3 Validating Event Parsing with Data Preview
18 Chapter 17: Manipulating Raw Data
17.1 Transformation Mechanics: props.conf & transforms.conf 17.2 Data Masking, Redaction & SEDCMD 17.3 Event Routing, Dynamic Index Assignment & Filtering to nullQueue
4.5 The Fishbucket: File Tracking, CRC Collisions & Re-reading Files
Key Takeaways Explain This Topic AI
The fishbucket ($SPLUNK_DB/fishbucket/splunk_private_db, visible as the _thefishbucket index) stores a beginning CRC of each file's first 256 bytes, the seekAddress read so far, and a seekCRC.
A new beginning CRC means a new file; a matching CRC with matching seekCRC means Splunk resumes at the seekAddress, which is also how rotated copies are recognized and skipped.
Files with identical first 256 bytes collide; fix this with initCrcLength (256 to 1048576) or crcSalt = <SOURCE> , but never use crcSalt = <SOURCE> on files that are rotated or renamed.
splunk cmd btprobe -d $SPLUNK_HOME/var/lib/splunk/fishbucket/splunk_private_db --file <path> --reset makes Splunk read one file again from the start.
splunk clean eventdata -index _thefishbucket (with Splunk stopped) resets tracking for every file and causes everything to be indexed again.
Last updated: September 2026
- The Fishbucket: How Splunk Tracks Monitored Files
- The Fishbucket ( _thefishbucket )
When Splunk Enterprise or a forwarder monitors files with [monitor://...] inputs, it has to remember how far it has read in each file, so that a restart does not re-index everything or skip data. That memory is the fishbucket .
Where the Fishbucket Lives
On disk: $SPLUNK_DB/fishbucket/splunk_private_db (that is, $SPLUNK_HOME/var/lib/splunk/fishbucket/splunk_private_db with default paths).
As an index: it appears as the internal index _thefishbucket .
In Splunk Cloud Platform you have no file-system access to it. There you check file-read status through REST ( /services/admin/inputstatus/TailingProcessor:FileStatus ).
What a Fishbucket Record Holds
Splunk's documentation describes the record in terms of CRCs and a seek address , not file names or inodes:
Beginning CRC: a CRC computed over the first 256 bytes of the file ( initCrcLength ). This is the key the fishbucket is looked up by.
seekAddress: how many bytes into the file Splunk has already read.
seekCRC: a fingerprint of the data at the seek address, used to confirm the file is still the same content. Monitored file: /var/log/app.log
- ┌──────────────────────────────┬──────────────────────────────┐
- │ first 256 bytes → begin CRC │ ... data read so far ... │ ← seekAddress (+ seekCRC)
- └──────────────────────────────┴──────────────────────────────┘
- stored in the fishbucket, keyed by the begin CRC
- How Splunk Uses the Record
When the monitor processor finds a file, it hashes the first 256 bytes and looks up that beginning CRC:
No match → new file: Splunk reads from the start and records new CRCs and seek addresses as it goes.
Match, and the data at the seek address still matches the seekCRC, and the file is larger: the file was read before and has grown. Splunk seeks to the seekAddress and reads only the new data.
Match, but the data at the seek address does not match: either the file was modified in place, or it is a different file that starts with the same content. Because the fishbucket is keyed by the beginning CRC, Splunk cannot track the two streams independently without further configuration.
This is also how Splunk handles log rotation . When app.log is renamed to app.log.1 , the renamed file has the same beginning CRC and an already-read seek address, so Splunk does not read it again. The newly created app.log has different opening content, so it is treated as a new file. (Compressed .gz and .tar archives are the documented exception: renamed archives are processed.)
The CRC Collision Problem & crcSalt
Because the fishbucket is keyed by a CRC of only the first 256 bytes, files that begin with identical content collide. This is a CRC collision .
Why CRC Collisions Occur
Many enterprise applications and network devices generate log files that begin with identical, static header comments or boilerplate text. For example: # Logfile created by Enterprise Service Broker v4.2
- # Host: production-node
- # Format: W3C Extended Log File Format
- # Date: 2026-09-23
# Fields: date time c-ip cs-username cs-method cs-uri-stem sc-status ...
If multiple log files in a monitored directory begin with this exact same 256-byte header:
Splunk reads File A ( web_node1.log ), calculates its 256-byte CRC, and indexes it completely.
Splunk examines File B ( web_node2.log ). It calculates the CRC of the first 256 bytes.
The CRC of File B is identical to File A!
Splunk finds the record for File A and concludes it has already read this content, so File B is skipped or only partly read.
Result: Critical log files are silently skipped and never ingested into Splunk.
The Solution: crcSalt = <SOURCE>
To prevent CRC collisions, administrators configure the crcSalt attribute inside the monitor stanza in inputs.conf : [monitor:///var/log/apps/*.log]
- index = web_app
- sourcetype = app_access
- crcSalt = <SOURCE>
When crcSalt = <SOURCE> is defined, Splunk appends the full filesystem path of the source file to the 256-byte buffer before calculating the CRC.
Because /var/log/apps/web_node1.log and /var/log/apps/web_node2.log have different file paths, their resulting CRCs are completely different, even if their initial 256 bytes are identical.
This guarantees unique identification for every file.
Tip
Alternatively, set initCrcLength (256 to 1048576 bytes) in inputs.conf so the beginning CRC covers more than the shared header. Unlike crcSalt = <SOURCE> , this keeps rotation detection working, because the CRC still depends only on file content.
Caution
Splunk warns not to use crcSalt = <SOURCE> on files that the operating system rotates or renames into another monitored path. The renamed file gets a different CRC, looks new, and is indexed again.
Inspecting & Resetting the Fishbucket
Sometimes you need to know whether Splunk has read a file, or force a single file to be read again.
Checking File Status
Use the tailing processor's file status endpoint on the instance that monitors the file: curl -k -u admin:<password> https://localhost:8089/services/admin/inputstatus/TailingProcessor:FileStatus
Or run splunk list inputstatus from the CLI to see the files the tailing processor knows about, how far each has been read, and why any file is being ignored.
Re-reading One File with btprobe
btprobe works directly on the fishbucket database. Run it through splunk cmd so the Splunk environment is set, and reset the record for a single file: $SPLUNK_HOME/bin/splunk cmd btprobe \
- d $SPLUNK_HOME/var/lib/splunk/fishbucket/splunk_private_db \
- -file /var/log/secure --reset
After the reset, the next time the monitor processor evaluates /var/log/secure it finds no record and reads the file from the beginning. That file's data is indexed again , and the duplicate volume counts against the license. Do this with Splunk stopped, so the running tailing processor does not rewrite the record while you work.
The Complete Fishbucket Reset (The Nuclear Option)
When a development environment or test forwarder must be completely wiped to re-index all inputs from scratch, administrators can perform a full fishbucket reset using the splunk clean eventdata command: # Step 1: Stop Splunk
$SPLUNK_HOME/bin/splunk stop
- # Step 2: Clean the entire fishbucket index
- $SPLUNK_HOME/bin/splunk clean eventdata -index _thefishbucket
- # Step 3: Start Splunk
- $SPLUNK_HOME/bin/splunk start
Caution
Running splunk clean eventdata -index _thefishbucket erases the fishbucket. Upon starting, Splunk forgets every file it has ever read. It will scan every file matching monitor stanzas in inputs.conf and re-index all of them from byte 0. In a production environment, this causes massive event duplication, license quota violations, and excessive storage consumption.