Configuration Guide

Configuration Guide

This guide explains how BIT tests are configured and how to customize them for your system.

Configuration Overview

BIT tests use TOML configuration files that define:

  • Test enablement - Whether a test should run
  • Thresholds - Resource limits (CPU %, disk %, temperature)
  • Whitelists - Approved hardware devices (USB, PCI)
  • Expected states - Interface status (network UP/DOWN)
  • Frequencies - How often CBIT tests run (in seconds)

All configuration files are stored in /etc/bit/ (or $BIT_CONFIG_PATH if set).

Generating Configuration with bit-learn

The easiest way to create configuration files is using the bit-learn tool:

# Set configuration directory
export BIT_CONFIG_PATH=/etc/bit

# Generate all configuration files
sudo bit-learn

What bit-learn Does

  1. Detects your hardware - CPUs, disks, network interfaces, USB/PCI devices, temperature sensors
  2. Prompts for settings - Asks for thresholds and frequencies with sensible defaults
  3. Generates TOML files - Creates one config file per test

Interactive Prompts

All prompts show default values in brackets. Press Enter to accept:

pbit_cpu_usage: Set CPU usage threshold in % [42]: ⏎
cbit_disk_usage: Set test frequency in seconds [30]: ⏎
pbit_disk_usage: Set disk usage threshold in % for disk /dev/sda1 [80]: ⏎

Warning: Overwrites Existing Files

⚠️ bit-learn overwrites all configuration files. Any manual changes will be lost. Back up your configs before running bit-learn again.

Configuration File Structure

Common Fields

Every test configuration has these fields:

[test_name]
enabled = true     # Whether test should run

CBIT tests also have:

[cbit_test_name]
enabled = true
frequency = 30     # Run every 30 seconds

Test-Specific Fields

Different test types have additional fields:

Threshold Tests (CPU, Memory, Disk)

[pbit_cpu_usage]
enabled = true
threshold = 42     # Alert if CPU exceeds 42%

[cbit_memory_usage]
enabled = true
frequency = 30
threshold = 90     # Alert if memory exceeds 90%

Whitelist Tests (USB, PCI)

[pbit_usb_whitelist]
enabled = true

[[device]]
device_name = "USB Hub"
vendor_id = "1d6b"
device_id = "0002"

[[device]]
device_name = "Keyboard"
vendor_id = "046d"
device_id = "c52b"

CBIT whitelist tests reference the PBIT configuration:

[cbit_usb_whitelist]
enabled = true
frequency = 5
# Device list is read from pbit_usb_whitelist.toml

Interface Tests (Ethernet, CAN)

[pbit_ethernet]
enabled = true

[[interface]]
name = "eth0"
expected_speed = 1000
expected_state = "up"

[[interface]]
name = "eth1"
expected_speed = 1000
expected_state = "up"

Multi-Resource Tests (Disk, Temperature)

[cbit_disk_usage]
enabled = true
frequency = 30

[[disk]]
disk = "/dev/sda1"
threshold = 80

[[disk]]
disk = "/dev/shm"
threshold = 80

[pbit_temperature]
enabled = true

[[thermal_zone]]
label = "Core 0"
threshold = 85.0

[[thermal_zone]]
label = "Core 1"
threshold = 85.0

Manual Configuration

You can manually edit configuration files after generation:

# Edit a specific test
sudo nano /etc/bit/cbit_disk_usage.toml

Example: Adjusting Disk Threshold

[cbit_disk_usage]
enabled = true
frequency = 30

[[disk]]
disk = "/dev/sda1"
threshold = 90     # Changed from 80 to 90

[[disk]]
disk = "/dev/shm"
threshold = 80

Example: Disabling a Test

[pbit_gpu_loading]
enabled = false    # Test will not run
threshold = 95

Example: Changing CBIT Frequency

[cbit_cpu_usage]
enabled = true
frequency = 60     # Changed from 30 to 60 seconds
threshold = 32
sample_size = 5

Configuration by Test Type

PBIT (Power-On Tests)

PBIT tests run once at startup. Configuration typically includes:

  • enabled - Whether to run the test
  • Test-specific thresholds or expected values

Example tests: - pbit_cpu_usage - CPU usage threshold - pbit_disk_health - Disk list for SMART checks - pbit_ethernet - Expected network interfaces - pbit_usb_whitelist - Approved USB devices

CBIT (Continuous Tests)

CBIT tests run periodically. Configuration includes:

  • enabled - Whether to run the test
  • frequency - How often to run (in seconds)
  • Test-specific thresholds or expected values

Example tests: - cbit_memory_usage - Memory threshold, check every 30s - cbit_temperature - Temperature thresholds, check every 60s - cbit_disk_usage - Disk usage thresholds, check every 30s

FBIT (Factory Tests)

FBIT tests typically have minimal configuration:

[fbit_ssd]
enabled = true
test_file_size_mb = 1    # Size of test file
target_directory = "/tmp"

Common Configuration Scenarios

Adjusting Resource Thresholds

If you're getting false alerts, adjust thresholds:

# Edit CPU threshold
sudo nano /etc/bit/cbit_cpu_usage.toml
# Change threshold from 32 to 50

# Edit memory threshold  
sudo nano /etc/bit/cbit_memory_usage.toml
# Change threshold from 90 to 95

Changing Monitoring Frequency

Make tests run more or less often:

# Edit disk monitoring
sudo nano /etc/bit/cbit_disk_usage.toml
# Change frequency from 30 to 300 (every 5 minutes)

Adding Approved Devices

When you add new hardware:

# Add to USB whitelist
sudo nano /etc/bit/pbit_usb_whitelist.toml

Add a new device block:

[[device]]
device_name = "New USB Device"
vendor_id = "1234"
device_id = "5678"

Or regenerate configs to auto-detect:

sudo bit-learn

Handling Missing Hardware

If hardware isn't present (e.g., no CAN interfaces), tests gracefully pass:

[pbit_can]
enabled = true
# No CAN interfaces detected
# Test will pass when no interfaces configured

Configuration File Locations

Default Installation

  • Config Directory: /etc/bit/
  • Test Plugins: /usr/local/lib/bit_manager/
  • Binaries: /usr/bin/

Development Setup

  • Config Directory: ./bit_manager/config/
  • Test Plugins: ./target/debug/ or ./target/release/
  • Binaries: ./target/debug/ or ./target/release/

Environment Variables

Override defaults with environment variables:

export BIT_CONFIG_PATH=/custom/config/path
export BIT_TEST_PATH=/custom/plugin/path

Troubleshooting Configuration

Test Not Loading

Check that config file exists:

ls -l $BIT_CONFIG_PATH/test_name.toml

If missing, regenerate:

bit-learn

Invalid Configuration

Check logs for errors:

sudo journalctl -u bit_manager | grep ERROR

Validate TOML syntax:

# Install toml-cli if needed
cargo install toml-cli

# Validate config
toml get $BIT_CONFIG_PATH/test_name.toml

Permission Issues

Ensure bit-manager can read configs:

sudo chmod 644 /etc/bit/*.toml
sudo chown root:root /etc/bit/*.toml

Next Steps

Edit this page on GitHub