Job Execution Settings¶

Overview¶

The Job Execution Settings page allows administrators to configure how KrakenHashes executes and distributes password cracking jobs across agents. These settings control chunking behavior, agent coordination, job control, and rule splitting strategies.

Accessing Job Execution Settings¶

1. Navigate to the Admin Panel
2. Click on Settings in the navigation menu
3. Select Job Execution Settings

The settings are grouped into panels on the page — Keyspace & Benchmark, Benchmark Reliability, Chunking, Scheduling & Allocation, Task Health, Loopback, Potfile and Job Notifications.

The ### sections below group settings by topic for reference. Most map directly to a panel, but a few do not: settings previously under Job Control and Agent Configuration have been distributed into the topic panels above (see Where a setting lives), so use the setting key rather than the section name when matching this page to the UI.

How this page saves¶

Each field writes only itself, the moment you change it (toggles and dropdowns save immediately; text and number fields save when they lose focus). There is no Save button.

This matters if you have previously been surprised by a setting reverting. Earlier versions submitted every setting on this page whenever any one of them was saved, so opening the page and touching one field would re-write all the others with whatever the form happened to be holding — silently overwriting a value changed elsewhere, and stamping every row with the same updated_at. That no longer happens; a save touches one key.

Where a setting lives¶

The dividing line is: Job Execution governs how a job runs; System Settings governs the system as a whole.

Settings that were on the wrong side of that line have moved:

Settings Categories¶

Keyspace & Benchmark¶

Groups every "how long may we spend measuring this?" control in one place, because the two that matter most were previously on different pages, in different units, both labelled timeout.

They are separate stages. Raising the speed-test values does nothing for a slow keyspace calculation, and vice versa — see Very large wordlists.

Benchmark Reliability¶

Previously not exposed in the UI at all; these existed only in the database. They bound what happens when benchmarks repeatedly fail, so one bad agent — or one unrunnable job configuration — cannot consume the fleet re-running a benchmark that cannot succeed.

The distinct-combination setting is the one that separates "this agent is broken" from "this job cannot run anywhere". Lower it and a healthy agent gets quarantined for one bad job; raise it and a genuinely faulty agent keeps being handed work.

Job Chunking¶

Job chunking divides large password cracking tasks into smaller, manageable pieces that can be distributed across multiple agents. This improves resource utilization and allows for better job scheduling.

Best Practices for Chunking¶

• Short jobs (< 1 hour): Use 5-10 minute chunks for better distribution
• Long jobs (> 24 hours): Use 30-60 minute chunks to reduce overhead
• Mixed agent speeds: Shorter chunks help balance workload

Agent Configuration¶

These settings control how agents behave and interact with the backend server.

Reconnect Grace Period Details¶

The Reconnect Grace Period is a critical setting for maintaining job continuity during server maintenance or unexpected restarts:

• Purpose: Allows agents with running tasks to reconnect and continue their work without losing progress
• How it works:
• When the backend restarts, tasks transition to reconnect_pending state
• Agents cache crack data locally and continue processing
• Upon reconnection, agents report their current task status
• If reconnected within the grace period, tasks resume automatically
• Recommended values:
• 5 minutes (default): Good for most environments
• 10-15 minutes: For environments with slower network recovery
• 1-3 minutes: For highly available setups with quick recovery

Job Control¶

Control job execution behavior and user interface settings.

Keyspace Calculation¶

Before a job can be scheduled, the backend measures it by running hashcat --keyspace and --total-candidates, both of which read the wordlist end to end. On a multi-gigabyte list that takes minutes, and this setting bounds it.

This runs in the background. Creating a job returns immediately with the job in preparing; it becomes pending once the measurement finishes. Users are never left waiting on the request, so raising this timeout costs nothing in responsiveness — it only lets a large wordlist finish being measured.

If the timeout is exceeded, the job is not rejected. For a straight (-a 0) attack the backend falls back to the wordlist's stored word count, starts the job anyway, and notifies the user with a keyspace_estimate_used notification naming this setting. The job runs normally and its size is refined by the first agent benchmark. Attack modes whose keyspace cannot be derived without hashcat still fail, with a message naming this setting.

Frequent keyspace_estimate_used notifications are the signal to raise this value.

Job Interruption Behavior¶

This is the global gate, and it is only one of three conditions. A job also needs its own Allow High Priority Override flag, and a priority above 0 — a priority-0 job never preempts anything. All three must hold before a single task is stopped.

Read the toggle rather than assuming its state. The database migration seeds this row true, but the scheduler's own fallback is the opposite: if the setting is missing or unreadable it is treated as off, so a configuration problem can never cause running work to be stopped. Preemption being disabled is silent by design — the waiting job simply waits — so "my high-priority job never interrupted anything" starts here.

When all three conditions hold, the system will: 1. Stop the newest running task at the lowest priority when a higher-priority job is waiting with no agent available 2. Truncate that task's keyspace at its last restore point and close it out as completed for the work it finished — the task is not returned to pending. If it never reached a restore point there is nothing to keep, so the task is deleted outright (or marked cancelled if it had already produced cracks, which preserves the crack attribution). A stopped task is never marked failed 3. Return the unfinished remainder to the queue as undispatched work, re-dispatched as soon as an agent is free 4. Preserve all crack progress; no keyspace is ever re-run

See Job Priority for the full model.

Agent Overflow Allocation Mode¶

This setting controls what happens to surplus agents — the ones still idle once every job at a priority tier has been filled to its max_agents cap.

Five modes are available, in two families. The table below is a summary; see Scheduler v2 Overview — Agent allocation and overflow modes for the full model rather than a second copy of it here.

The "Priority" family concentrates surplus on the highest tier that can use it; the "Max Agents" family guarantees every job its baseline cap before accelerating anything.

FIFO Mode (Default)¶

Behavior: Oldest job gets all overflow agents

Use Cases: - Default mode: Best for most scenarios - Fairness: Jobs get their turn in creation order - Completion focus: Concentrates resources to finish jobs faster - Simple behavior: Predictable allocation pattern

Example:

3 jobs at priority 50, each with max_agents = 2
15 available agents total

Job A (created first):  2 agents (max_agents)
Job B (created second): 2 agents (max_agents)
Job C (created third):  2 agents (max_agents)
Overflow:              9 agents → ALL go to Job A (oldest)

Final: Job A = 11 agents, Job B = 2 agents, Job C = 2 agents

Round-Robin Mode¶

Behavior: Distribute overflow agents evenly across all jobs at same priority

Use Cases: - Parallel progress: Want all jobs to progress simultaneously - Testing: Running multiple test jobs at once - Even distribution: Prefer balanced allocation over speed - Multiple clients: Each job from different client, want fairness

Example:

3 jobs at priority 50, each with max_agents = 2
15 available agents total

Job A (created first):  2 agents (max_agents)
Job B (created second): 2 agents (max_agents)
Job C (created third):  2 agents (max_agents)
Overflow:              9 agents → distributed evenly (3 each)

Final: Job A = 5 agents, Job B = 5 agents, Job C = 5 agents

Allocation Logic:

1. Calculate base allocation: 9 overflow / 3 jobs = 3 agents per job
2. Calculate remainder: 9 % 3 = 0 (no remainder)
3. Distribute base to all jobs: +3 each
4. If remainder exists, give to oldest jobs first

Priority-Based Behavior¶

The mode governs surplus agents; priority still decides who is filled first, and in the two "Priority" modes a higher tier is filled to exhaustion before a lower tier sees an agent:

Scenario: 2 jobs, 10 agents available

Job A: Priority 100, max_agents = 3
Job B: Priority 50,  max_agents = 5

fifo / round_robin:      Job A takes all 10 (surplus concentrates on the top tier)
enforce_max_agents:      Job A gets 3, Job B gets 5, 2 agents stay idle
max_agents_*:            Job A gets 3 and Job B gets 5 first, then the 2 surplus
                         agents go to Job A (highest priority with work left)

Configuration via SQL¶

-- View current setting
SELECT key, value, description
FROM system_settings
WHERE key = 'agent_overflow_allocation_mode';

-- Valid values: 'fifo', 'round_robin', 'enforce_max_agents',
--               'max_agents_fifo', 'max_agents_round_robin'
UPDATE system_settings
SET value = 'fifo'
WHERE key = 'agent_overflow_allocation_mode';

When to Use Each Mode¶

Hashlist Bulk Batch Size¶

This setting controls how many hashes are processed in each database batch during hashlist imports and bulk operations. It directly affects memory usage and import performance.

How It Works: 1. When importing a large hashlist (e.g., 10 million hashes), the system divides the work into batches 2. Each batch processes up to hashlist_bulk_batch_size hashes at once 3. Larger batches = faster imports but higher memory usage 4. Smaller batches = lower memory usage but slower imports

Recommended Values:

Configuration via SQL:

-- View current setting
SELECT key, value, description
FROM system_settings
WHERE key = 'hashlist_bulk_batch_size';

-- Set batch size (example: 50,000 for memory-constrained systems)
UPDATE system_settings
SET value = '50000'
WHERE key = 'hashlist_bulk_batch_size';

-- Set batch size (example: 200,000 for high-memory systems)
UPDATE system_settings
SET value = '200000'
WHERE key = 'hashlist_bulk_batch_size';

Performance Impact: - Import Time: Doubling batch size typically reduces import time by 20-30% - Memory Usage: Roughly linear with batch size (~10MB per 100,000 hashes) - Database Load: Larger batches create fewer but larger transactions

Loopback Round Cap¶

The loopback_max_rounds setting caps how many delta rounds a loopback session runs before it stops, even if new cracks keep appearing. It is a safety bound — most sessions go "dry" (a round finds nothing new) well before the cap.

The value is read when a session starts; changing it affects new sessions, not ones already in flight. If the setting is missing, the backend falls back to 10.

-- View current setting
SELECT key, value, description
FROM system_settings
WHERE key = 'loopback_max_rounds';

-- Raise the cap (example: allow up to 25 rounds)
UPDATE system_settings
SET value = '25'
WHERE key = 'loopback_max_rounds';

See Loopback for how sessions work and the Loopback Sessions architecture reference for internals.

Scheduler (v2) Timing¶

Found in the Scheduler (v2) panel of the Job Execution Settings page, alongside the chunk overrun guard below.

These knobs decide when the scheduler stops believing an agent is still working. Getting them wrong in one direction leaves a dead task holding keyspace for hours; in the other it evicts a healthy agent that was merely busy decompressing a 40 GB wordlist. When a task is declared lost, it goes through the same truncate-and-re-open recovery as every other stop — see Job Priority — Job Interruption Behavior.

Startup Stalls Count Against the Heartbeat Timeout¶

Everything between "task assigned" and "hashcat emits its first progress line" — downloading wordlists, rules and the hashlist, decompressing them, and hashcat's own kernel autotune — produces no progress. Since last_activity_at is stamped once at dispatch and refreshed only by progress updates, that entire startup window is counted against task_heartbeat_timeout_seconds: a first-time sync of a large wordlist over a slow link can be evicted as a dead task and re-dispatched to another agent that then faces the same download.

The same applies to the --slow-candidates startup stall described under Zero-Progress Overruns below — a healthy agent on a slow hash type legitimately reports nothing for the first several minutes of a chunk.

task_heartbeat_timeout_seconds is therefore the knob to raise if your fleet syncs large resources over slow links or works slow hash types. task_startup_grace_seconds reads like the setting for exactly this, but no scheduler code path consumes it, so raising it changes nothing. Lower the heartbeat timeout only if you would rather reclaim a wedged agent quickly than tolerate a long but legitimate startup.

Chunk Overrun Guard¶

Found in the Scheduler (v2) panel of the Job Execution Settings page.

Chunks are sized from an agent's benchmarked speed so that each one runs for roughly the target chunk duration. When that estimate is badly wrong — the agent is slower than benchmarked, or the work is heavier than expected — a chunk can run for hours instead of minutes, holding an agent hostage and blocking higher-priority work. The chunk overrun guard stops such a task, re-dispatches the unfinished remainder, and feeds the measured speed back so the next chunk for that agent is sized correctly.

What Happens When It Fires¶

1. The agent is sent a stop for that task.
2. The task's keyspace range is truncated at its last restore point and closed out as completed for the work it actually did; the remainder returns to the queue as an undispatched gap. This is the same truncate-and-re-open path used by preemption and agent disconnects — see Job Priority — Job Interruption Behavior.
3. The speed actually observed on that chunk is recorded, so the re-dispatched remainder (and future chunks for that agent, attack mode and hash type) are sized from reality instead of the stale benchmark.

Zero-Progress Overruns Count Against the Agent¶

If an overrunning chunk had made no keyspace progress at all — its restore point never advanced past its own range start — the guard additionally charges a failure against that agent, through the same per-(agent, attack mode, hash type) policy engine that handles ordinary task failures. Its cooldown and blocklist machinery then routes the re-opened range to a different agent.

This closes a livelock: the speed feedback above can't help a task that reported nothing, because there is no speed to record. Without the failure attribution the wedged agent keeps its optimistic benchmark, gets handed the very same re-opened range on the next cycle, wedges again, and the job never advances. Typical causes are hashcat stuck in autotune, a hung GPU driver, or a file download that never finishes.

Lower the tolerance if you want tighter turnaround on mis-sized chunks; raise it (or disable the guard) if your workload has legitimately variable chunk times and you would rather let long chunks run to completion.

Rule Splitting (removed)¶

Scheduler-v2 needs none of it: it splits every job over the base keyspace with hashcat --skip/--limit and accounts for a rule file's cost through the job's multiplication factor, so a heavy rule set produces smaller base-word chunks instead of physically split rule files. See Chunking System.

Performance Considerations¶

Network Load¶

• Progress Reporting Interval: Each update creates network traffic
• Job Refresh Interval: Affects UI responsiveness and server load
• Calculate: (Number of Agents × Active Jobs) / Reporting Interval = Updates per second

Storage Requirements¶

• Hashlist Retention: Average Hashlist Size × Number of Unique Jobs held for the retention window (agent_hashlist_retention_hours, 24 hours by default)
• Benchmark Cache: Minimal, typically < 1MB per agent

Optimal Settings by Environment¶

Small Environment (1-5 agents)¶

• Chunk Duration: 10-15 minutes
• Progress Interval: 30 seconds
• Max Concurrent Jobs: 1
• Grace Period: 5 minutes

Medium Environment (5-20 agents)¶

• Chunk Duration: 15-30 minutes
• Progress Interval: 60 seconds
• Max Concurrent Jobs: 1-2
• Grace Period: 10 minutes

Large Environment (20+ agents)¶

• Chunk Duration: 30-60 minutes
• Progress Interval: 120 seconds
• Max Concurrent Jobs: 2-3
• Grace Period: 15 minutes

Troubleshooting¶

Common Issues¶

Agents Not Receiving Jobs¶

• Check Max Concurrent Jobs per Agent setting
• Verify agents are not at capacity
• Review job priority settings

Poor Job Distribution¶

• Reduce Default Chunk Duration for better granularity
• Raise Minimum Chunk Duration if agents are being handed uselessly small gaps
• Check Agent Overflow Allocation Mode — a "Priority" mode concentrates surplus agents on one job by design

High Server Load¶

• Increase Progress Reporting Interval
• Increase Job Refresh Interval
• Disable Real-time Crack Notifications for large jobs

Lost Progress After Server Restart¶

• Increase Reconnect Grace Period
• Ensure agents have stable network connections
• Check agent logs for reconnection issues

Monitoring Settings Impact¶

Use the following metrics to evaluate settings effectiveness: - Average chunk completion time vs. configured duration - Number of retry attempts per job - Agent utilization percentage - Task reassignment frequency after restarts

Related Documentation¶

• Agent Management - Managing and monitoring agents
• Job Chunking - Detailed chunking strategies
• Performance Tuning - System optimization
• Rule Management - Managing rule files