Wordlist Modes

Wordlist Modes

HashTasker has two ways of getting wordlist data to workers, selected by server.wordlist_mode in config.yaml.

Push Mode (default)

server:
  wordlist_mode: "push"

• At job creation, the server splits the selected wordlist into one chunk file per online worker in upload_path.
• Each worker downloads its chunk over HTTP (GET /api/worker/wordlist/<job>/<chunk>) and runs hashcat against it.
• Works with any worker version and needs no shared storage.
• Downside: splitting and transferring a very large wordlist takes time and disk space on both ends, and job creation waits for the split.

NFS Mode

server:
  wordlist_mode: "nfs"

• The wordlist directory is shared (NFS or any network filesystem) and mounted on the server and every worker.
• At job creation, the server counts the wordlist's lines (from a cache when possible) and gives each worker a --skip/--limit range. Nothing is copied.
• Job creation returns immediately; the line count and chunk creation happen in the background. The job stays queued until preparation finishes, or becomes failed with a status message if it cannot.
• Uploaded custom wordlists are still served by the server (GET /api/worker/custom-wordlist/<job>), since they are not on the share.

Health Gating

NFS mode is strict. Job creation is refused unless:

• the server's wordlists_path is readable, and
• every online worker reports a healthy wordlists_path.

The error names each unhealthy host. The server checks itself every 30 seconds (15 second timeout); workers check on startup and at each check-in. Health is shown on the dashboard's Server NFS card, the workers table, and the System Stats page.

If hashcat fails mid-chunk, the worker re-checks its mount and reports an NFS-specific failure if the mount dropped.

Line-Count Cache

Counting lines in a multi-billion-line wordlist is slow, so counts are cached in the database and keyed by path, invalidated when the file's size or modification time changes. A background warmer scans the wordlist directory shortly after startup and hourly, counting at most two new or changed files per cycle so it never saturates I/O. A wordlist the warmer has not reached yet is counted on demand at job creation.

HashTasker never deletes anything in the shared wordlist directory.

Choosing

Situation	Mode
A few workers, wordlists under a few GB	push
Wordlists in the tens of GB or larger	nfs
No shared storage available	push
Workers on mixed or old versions	push

Switching from Push to NFS

The mode is read only at startup and cannot change at runtime.

1. Upgrade the server and all workers to v1.3.0 or later.
2. Mount the share on every worker and add wordlists_path to each worker.json.
3. Restart workers and confirm green NFS status everywhere on the dashboard.
4. Let running jobs finish.
5. Set wordlist_mode: "nfs" and restart the server.
6. Run a small test job.