Configuration Reference

Complete reference for preheat configuration options.

Configuration File Location

/usr/local/etc/preheat.conf    # Default location (source install)
/etc/preheat.conf              # Alternative (package install)

Use preheat -c /path/to/config to specify an alternate location.

Configuration Format

Preheat uses INI-style configuration:

# Comments start with #
[section]
key = value
key2 = value2

[another_section]
key = value

Two-Tier Application Tracking

New in v1.0.0: Preheat separates applications into two pools for cleaner stats and smarter preloading.

excluded_patterns

Type: String (semicolon-separated) Default: /bin/sh;/bin/bash;/usr/bin/grep;/usr/bin/cat;/usr/bin/sed;/usr/bin/awk;/usr/bin/find;/usr/bin/xargs;/sbin/*

Path patterns to exclude from priority pool stats. Supports wildcards (*, ?).

[system]
excluded_patterns = /bin/sh;/bin/bash;/sbin/*

user_app_paths

Type: String (semicolon-separated) Default: /usr/share/applications;/usr/local/share/applications;~/.local/share/applications;/opt

Directories containing user applications. Apps in these paths are auto-added to priority pool.

[system]
user_app_paths = /usr/share/applications;~/.local/share/applications;/opt

Pool Classification Priority

1. Manual apps list → Priority pool (highest)
2. Has .desktop file → Priority pool
3. Matches excluded pattern → Observation pool
4. In user app directory → Priority pool
5. Default → Observation pool

Rules:

• Keys are case-sensitive
• Values have no quotes (even strings)
• Boolean values: true, false
• Path lists: separated by semicolons (;)

Section: [model]

Controls the prediction model and memory usage.

Inherited from preload 0.6.4 - behavioral parity maintained.

cycle

Description: Interval between daemon cycles (scan, predict, preload).

Recommendations:

• Lower values (5-15): More responsive, higher CPU usage
• Higher values (30-60): Less responsive, lower overhead
• Use even numbers for predictable timing

cycle = 20

Warning: Values below 10 may cause noticeable CPU usage on slower systems.

usecorrelation

Description: Use statistical correlation in prediction algorithm.

Correlation analysis improves prediction accuracy by measuring how strongly applications co-occur beyond random chance.

usecorrelation = true

minsize

Description: Minimum total size of memory maps for tracking.

Applications with smaller footprints are ignored (screen savers, tiny utilities).

minsize = 2000000

memtotal

Description: Percentage of total RAM to include in preload budget.

Negative values subtract from the budget, providing a safety margin.

memtotal = -10

memfree

Description: Percentage of free RAM to include in preload budget.

memfree = 50

memcached

Description: Percentage of cached RAM to include in preload budget.

Setting this above 0 risks evicting other useful cached data.

memcached = 0

Memory Budget Formula

Available = max(0, Total × memtotal% + Free × memfree%) + Cached × memcached%

Example with defaults on 8GB system, 3GB free, 2GB cached:

Available = max(0, 8192 × -0.10 + 3072 × 0.50) + 2048 × 0
          = max(0, -819 + 1536) + 0
          = 717 MB

Section: [system]

Controls daemon behavior and I/O operations.

doscan

Description: Enable process monitoring.

Set to false to stop learning (useful for debugging).

doscan = true

dopredict

Description: Enable prediction and preloading.

Set to false to monitor without preloading.

dopredict = true

autosave

Description: Interval for automatic state saves.

More frequent saves provide better crash recovery but increase disk writes.

autosave = 300

mapprefix

Description: Path filters for shared libraries (memory maps).

Syntax:

• Paths without ! prefix: Include
• Paths with ! prefix: Exclude
• First match wins
• !/ at end excludes everything else

mapprefix = /usr/;/lib;/var/cache/;!/

exeprefix

Description: Path filters for executables.

Default excludes system administration tools.

exeprefix = !/usr/sbin/;!/usr/local/sbin/;/usr/;!/

processes

Description: Maximum parallel readahead workers.

Higher values increase I/O parallelism. Set to 0 for single-process mode.

processes = 30

sortstrategy

Description: File ordering strategy for preloading.

sortstrategy = 3

Recommendation:

• HDD (spinning disk): 3 (default) - minimizes seek time
• SSD/NVMe: 0 - no benefit from sorting
• Network filesystems: 1 - groups by directory

manualapps

Description: Path to file containing always-preload applications.

manualapps = /etc/preheat.d/apps.list

File format:

# /etc/preheat.d/apps.list
# One path per line
/usr/bin/firefox
/usr/bin/code
/usr/bin/libreoffice

Automatic Path Resolution (v1.0.0+):

Preheat automatically resolves paths to actual ELF binaries:

Security: Only paths in trusted locations are accepted:

• /usr/bin/, /usr/sbin/, /usr/lib/, /usr/lib64/
• /usr/libexec/, /usr/local/bin/, /usr/local/lib/
• /usr/share/, /opt/

Proactive Registration:

Manual apps are registered at daemon startup, even if never run before. This means they will be preloaded immediately without waiting for first use.

Setup Steps:

1. Create directory: sudo mkdir -p /etc/preheat.d
2. Create file: sudo nano /etc/preheat.d/apps.list
3. Add apps (one per line, absolute paths)
4. Add to config: manualapps = /etc/preheat.d/apps.list
5. Reload: sudo preheat-ctl reload

Verification:

# Check what was resolved and registered
sudo tail -30 /usr/local/var/log/preheat.log | grep -i manual

Section: [preheat]

Optional extensions (require --enable-preheat-extensions build flag).

enable_preheat_scoring

Description: Enable enhanced scoring for priority applications.

enable_preheat_scoring = false

preheat_tool_boost

Description: Priority multiplier for boosted applications.

preheat_tool_boost = 1.0

enable_time_learning

Description: Enable time-of-day pattern learning.

When enabled, learns that certain apps are used at certain times.

enable_time_learning = false

manual_apps_list

Description: Path to manual applications list.

manual_apps_list = /etc/preheat.d/apps.list

blacklist

Description: Path to blacklisted applications.

blacklist = /etc/preheat.d/blacklist

File format:

# /etc/preheat.d/blacklist
# Applications to never track or preload
/usr/bin/some-broken-app
/opt/problematic/binary

Example Configurations

Minimal (Safe Defaults)

# Minimal configuration - uses all defaults
# Just create an empty file or use defaults
[model]
cycle = 20

[system]
doscan = true
dopredict = true

Balanced (Recommended)

# Good balance of responsiveness and resource usage
[model]
cycle = 20
usecorrelation = true
minsize = 2000000
memtotal = -10
memfree = 50
memcached = 0

[system]
doscan = true
dopredict = true
autosave = 300
processes = 30
sortstrategy = 3

Conservative (Low Resource Systems)

# For systems with limited RAM (2-4 GB)
[model]
cycle = 30
minsize = 5000000
memtotal = -20
memfree = 30
memcached = 0

[system]
autosave = 7200
processes = 10
sortstrategy = 3

Aggressive (High Performance)

# For systems with plenty of RAM (8+ GB)
[model]
cycle = 15
minsize = 1000000
memtotal = 0
memfree = 70
memcached = 10

[system]
autosave = 1800
processes = 50
sortstrategy = 3

SSD Optimized

# For SSD/NVMe storage
[model]
cycle = 20
memfree = 50

[system]
sortstrategy = 0   # No block sorting needed
processes = 50     # SSDs handle parallelism well

Applying Configuration Changes

After editing the configuration file:

# Method 1: Reload (no restart needed)
sudo preheat-ctl reload

# Method 2: Via systemd
sudo systemctl reload preheat

# Method 3: Full restart
sudo systemctl restart preheat

Reload re-reads the configuration file without losing learned state.

Validation

Check configuration for errors by running in foreground:

sudo preheat -f -c /path/to/config

The daemon will log configuration values on startup for verification.

Tuning Recommendations

For Low-Memory Systems (< 2GB RAM)

• Increase minsize to 5000000
• Decrease memfree to 30
• Set memtotal to -20
• Decrease processes to 10

For SSDs

• sortstrategy = 0 (NONE) - random access is fast
• Increase processes to 50

For HDDs

• sortstrategy = 3 (BLOCK) - minimize seeks
• Keep processes at 30

For Servers

• doscan = true, dopredict = false - monitor only
• autosave = 600 - save frequently

Behavioral Parity

DEFAULT CONFIGURATION produces behavior identical to upstream preload 0.6.4.

Do NOT modify defaults unless you understand the impact.

Files

Paths shown are defaults for local installation (/usr/local prefix). System packages may use /etc and /var instead.

Configuration

• /usr/local/etc/preheat.conf - Main config
• /etc/preheat.d/apps.list - Manual app list (optional)

Data

• /usr/local/var/lib/preheat/preheat.state - Learned state
• /usr/local/var/log/preheat.log - Daemon log

Runtime

• /run/preheat.pid - Process ID file

Navigation