FreeBSD locate Index Operations: Build, Scope, and Refresh File Searches

FreeBSD’s locate command searches a precomputed database of pathnames rather than walking the filesystem for every query. It is fast for broad name searches, but it is not a live view: paths can be missing because they were created after the last rebuild, and removed paths can remain in results until the database is refreshed. Use find when you need current filesystem state or need to constrain a search by ownership, size, type, timestamps, or other live attributes.

The base-system database is commonly rebuilt by a weekly periodic script. It is generally generated as an unprivileged user and skips directories that user cannot read. This is both a performance and information-boundary behavior. An administrator should decide which mounted filesystems belong in the index, how much storage and I/O a rebuild may consume, and how users will distinguish an indexed pathname from an existing file.

Confirm the database and its freshness

Check the installed command, its default database path, and the update script:

locate -S
ls -lh /var/db/locate.database
ls -l /usr/libexec/locate.updatedb /etc/periodic/weekly/310.locate
grep -n "locate" /etc/periodic.conf /etc/periodic.conf.local 2>/dev/null

The locate manual documents /var/db/locate.database as the default database and /etc/periodic/weekly/310.locate as the script that starts its rebuild. File modification time is a useful freshness clue, but it does not prove a rebuild completed successfully. Correlate it with periodic output, system logs, and the script’s exit status.

The weekly job is controlled by periodic configuration. Inspect the installed periodic.conf(5) manual and the script before changing variables; names and defaults should be verified on the target release. Do not edit the generated database directly. Rebuild it with the supported utility or weekly job so its format, permissions, and temporary-file handling remain consistent.

An administrator may run the documented update script during a quiet window after confirming its scope:

/usr/libexec/locate.updatedb
locate -S
locate example.conf

The command can traverse substantial parts of the filesystem and create a temporary list before replacing the database. On a busy or constrained system, inspect its manual and periodic script for available controls, free space, user identity, and exclusion rules before invoking it. Do not launch simultaneous rebuilds; concurrent jobs can consume storage and make it harder to determine which database was installed.

Understand what a locate result proves

locate matches patterns against stored pathnames. A bare string is generally treated as a substring pattern, so locate sshd.conf can match paths where that text appears anywhere. Shell metacharacters such as *, ?, [, and ] have pattern meaning and may need quoting or escaping. Use -l to limit results when exploring a broad pattern.

A result proves that the pathname was present in the searched database when it was built. It does not prove the file still exists, that it is readable by the current user, that it is the expected version, or that it is safe to execute. Verify a candidate with stat, file, or a direct directory listing before acting:

locate -l 50 rc.conf
stat /etc/rc.conf
file /etc/rc.conf

Conversely, no result does not prove the file is absent. It may have been created after the last index, excluded by configuration, hidden from the unprivileged indexing user, or stored on a filesystem that was not mounted during the rebuild. If exact existence matters, use find on the relevant path:

find /etc -type f -name 'rc.conf' -print

Constrain find to the smallest relevant subtree. An unrestricted live scan can be more expensive than a database query, especially on network mounts or large datasets. For transient paths and operational incident response, the freshness requirement usually matters more than the convenience of a fast stale search.

Control the indexing scope

The FreeBSD locate.updatedb manual documents /etc/locate.rc as the configuration file that controls the contents of the new database. The LOCATE_CONFIG environment variable can select an alternate config file. Read the current manual before using configuration variables, as the exact syntax belongs to the FreeBSD script and should not be copied from NetBSD, OpenBSD, Linux updatedb, or plocate documentation.

Inspect the current configuration and the script’s source before changing it:

test -r /etc/locate.rc && sed -n '1,200p' /etc/locate.rc
man locate.updatedb
man periodic.conf

Use documented exclusions for filesystems or subtrees that should not be scanned. Examples include mounted removable media, remote filesystems that are unavailable during weekly maintenance, large caches with rapidly changing names, and paths whose contents should not be exposed through a shared search database. Keep exclusions narrow and review them after mount-layout changes.

The indexer normally runs without root privileges, so unreadable paths are skipped. Do not make a private directory world-readable merely to add its names to locate. If administrators need a broader inventory, build a separate database with an explicitly controlled access policy and carefully chosen user, paths, and permissions. The default database is designed for public pathnames; it should not be repurposed as a private inventory without verifying its ownership and mode.

Filesystem boundaries affect results. A filesystem mounted only after the weekly scan will not have been indexed for that cycle. A network filesystem may be omitted if it is unavailable or deliberately excluded. A jail or alternate root has its own filesystem view and may require a separate search database. Make the index scope visible in runbooks so operators do not infer that locate spans every host-visible or jail-visible mount.

Search alternate databases safely

locate accepts one or more databases with -d and can read compressed data through a pipeline in supported forms. LOCATE_PATH also selects database locations unless -d is explicitly provided. Keep alternate database files readable only by their intended audience, and document how they are rebuilt and rotated.

To query an alternate database that has already been built with the compatible locate format, use an explicit path and avoid changing the system default:

locate -d /var/db/project.locate database.conf

This command searches that database for the pattern; it does not create or update it. Building a separate index requires a documented updater configuration and output path for the installed implementation. Do not assume LOCATE_CONFIG changes the output filename; it selects configuration for the updater. Do not hand-create a database by concatenating filenames unless the official format and byte-order requirements are understood. The format is not a portable interchange database across all architectures. Use FreeBSD’s update utility and matching locate implementation, and rebuild after platform or database format changes.

When scripting, request NUL-separated paths with -0 if the consumer supports NUL delimiters; pathnames can contain spaces, tabs, quotes, and newlines. A newline-delimited locate result is convenient for a terminal but unsafe to pass through naive shell word splitting. For example, a null-safe inspection pipeline can be built with:

locate -0 'rc.conf' | xargs -0 -n 1 stat

This avoids splitting on spaces or tabs, but still reports the index snapshot and can encounter paths removed after indexing. Handle stat failures rather than suppressing them. In scripts, check the command’s exit status, handle zero matches distinctly from query failure, and verify each result before destructive action.

For current, constrained searches, prefer find with explicit predicates rather than broad locate-to-command pipelines. For example, find /etc -type f -name ‘*.conf’ -print0 | xargs -0 stat can inspect existing configuration files under /etc without depending on the weekly index. Review the exact root and command before running a pipeline on production; NUL delimiters protect path parsing, not the correctness of the selected root or action.

Never pipe locate output directly into rm, chmod, chown, or a deployment command. Stale results and pattern surprises can target the wrong files. First save and inspect the candidate set, use a null-safe representation, confirm paths remain within an approved root, and require explicit review for destructive operations.

Troubleshoot stale, missing, or excessive results

A deleted path still appears. The database is stale. Confirm the rebuild schedule and its completion record, then run the supported updater if the host can tolerate a scan.

A newly created path is missing. Check the database timestamp, mount timing, exclusion configuration, and indexer permissions. Search the exact subtree with find to distinguish a stale index from a missing file.

Only some directories appear. The unprivileged indexing account may not traverse them, or a mount may be excluded. Do not weaken permissions; review the intended database scope and access policy.

The update is slow or fills temporary storage. Inspect filesystem size, mount list, periodic configuration, and update script behavior. Reduce scope using documented controls, schedule outside peak I/O, and reserve space for the temporary database list.

A search returns too much. Use a narrower path-like pattern, a result limit, or a live find with explicit predicates. Be aware that locate’s pattern matching is not equivalent to find -name in every respect.

Operational acceptance

An accepted locate deployment has a known default database path, a documented index scope, a scheduled rebuild owner, adequate temporary and final storage, correct file permissions, and an observable success record. Validate a known path after a rebuild, a deliberately excluded path, and a path created after the database snapshot. Confirm the latter is absent until the next rebuild, then appears when expected.

Record the FreeBSD release, database path, update timestamp, periodic configuration, exclusions, indexing identity, database size, rebuild duration, and query test. Use locate for fast discovery and find for live truth. This simple distinction avoids both stale-path mistakes and unnecessary filesystem-wide scans.

Related:

Sources: