Configuration‐Guide

Configuration Guide

This page explains the Config struct in detail, which is central to initializing libfasttree. We'll cover each field, its purpose, default values (if any), and examples. The configuration allows you to tailor the library to your system's needs, such as distro type, security features, and storage paths.

Overview

The Config struct defines how libfasttree behaves. It's passed to FastTree::new(config).await to create an instance. All fields are required unless noted, and many have enums for type-safety.

Key principles:

• Paths: Use absolute paths for directories to avoid issues.
• Enums: Use provided enums for options like DistroType to ensure compatibility.
• Optional Features: Fields like health_check_script are Option<PathBuf>—set to None if not needed.
• Customization: For advanced use, populate fields like zstd_dicts or tpm_tcti.

Detailed Field Breakdown

Here's a breakdown of each field in Config:

1. repo_url: String

   • Purpose: The base URL of your distribution's repository (e.g., for APT mirrors).
   • Example: "http://deb.debian.org/debian".to_string()
   • Tip: Use HTTPS for security.

2. distro_type: DistroType

   • Purpose: Specifies the package manager type.
   • Options: Apt, Rpm, Pacman, Nix, Apk
   • Example: DistroType::Apt
   • Tip: Plugins allow extending to new types.

3. cas_dir: PathBuf

   • Purpose: Directory for content-addressed storage (CAS) objects.
   • Example: PathBuf::from("/var/lib/fasttree/objects")
   • Tip: Ensure this directory has enough space and is on a filesystem supporting reflinks (e.g., Btrfs).

4. db_path: PathBuf

   • Purpose: Path to the SQLite database file.
   • Example: PathBuf::from("/var/lib/fasttree/db.sqlite")
   • Tip: Back up this file regularly as it tracks trees, refs, and objects.

5. deployments_dir: PathBuf

   • Purpose: Directory where system trees (deployments) are built.
   • Example: PathBuf::from("/sysroot")
   • Tip: This should be on the root filesystem or a dedicated partition.

6. current_link: PathBuf

   • Purpose: Symlink pointing to the current active deployment.
   • Example: PathBuf::from("/ostree/current")
   • Tip: Used for booting into the active tree.

7. boot_dir: PathBuf

   • Purpose: Directory for boot files (e.g., kernel, initramfs).
   • Example: PathBuf::from("/boot")
   • Tip: Integrate with your bootloader.

8. bootloader: BootloaderType

   • Purpose: Type of bootloader for update integration.
   • Options: Grub, SystemdBoot
   • Example: BootloaderType::SystemdBoot

9. filesystem: FilesystemType

   • Purpose: Underlying filesystem for optimizations like reflinks.
   • Options: Btrfs, Xfs, Other
   • Example: FilesystemType::Btrfs
   • Tip: Btrfs enables subvolumes and snapshots.

10. health_check_script: Option

    • Purpose: Path to a script run after deployment for health checks.
    • Example: Some(PathBuf::from("/usr/bin/health-check.sh"))
    • Tip: Script should exit 0 on success.

11. overlay_dirs: Vec

    • Purpose: Directories to overlay (e.g., for writable /etc).
    • Example: vec![PathBuf::from("/etc"), PathBuf::from("/var")]
    • Tip: Use for ephemeral changes.

12. var_volume: Option

    • Purpose: Device path for mounting /var separately.
    • Example: Some(PathBuf::from("/dev/sdb1"))
    • Tip: Useful for persistent data.

13. gpg_keyring: PathBuf

    • Purpose: Path to GPG keyring for fallback signature verification.
    • Example: PathBuf::from("/etc/apt/trusted.gpg")
    • Tip: Sigstore is preferred for keyless signing.

14. use_fsverity: bool

    • Purpose: Enable FS-Verity for immutable files in CAS.
    • Example: true
    • Tip: Requires kernel support.

15. use_ima: bool

    • Purpose: Enable Integrity Measurement Architecture (IMA) labels.
    • Example: true
    • Tip: For runtime integrity checks.

16. partitioning: PartitioningType

    • Purpose: Partitioning scheme for deployments.
    • Options: Subvolumes, ABPartitions
    • Example: PartitioningType::Subvolumes

17. sysext_dir: PathBuf

    • Purpose: Directory for systemd-sysext images.
    • Example: PathBuf::from("/var/lib/extensions")

18. zstd_dicts: HashMap<String, Vec>

    • Purpose: Zstd compression dictionaries for file types (e.g., key: "elf", value: dict bytes).
    • Example: HashMap::new() or populate with pre-trained dicts.
    • Tip: Train dictionaries on similar files for better compression.

19. tpm_tcti: Tcti

    • Purpose: TPM context for sealing and signing.
    • Example: Tcti::Tpmtis (software) or Tcti::Device("/dev/tpm0")
    • Tip: Requires tss-esapi crate.

Example Configuration

A minimal config for an APT-based system:

use libfasttree::{Config, DistroType, BootloaderType, FilesystemType, PartitioningType};
use std::collections::HashMap;
use std::path::PathBuf;
use tss_esapi::tcti::Tcti;

let config = Config {
    repo_url: "https://deb.debian.org/debian".to_string(),
    distro_type: DistroType::Apt,
    cas_dir: PathBuf::from("/var/lib/fasttree/objects"),
    db_path: PathBuf::from("/var/lib/fasttree/db.sqlite"),
    deployments_dir: PathBuf::from("/sysroot"),
    current_link: PathBuf::from("/ostree/current"),
    boot_dir: PathBuf::from("/boot"),
    bootloader: BootloaderType::Grub,
    filesystem: FilesystemType::Other,
    health_check_script: None,
    overlay_dirs: vec![],
    var_volume: None,
    gpg_keyring: PathBuf::from("/etc/apt/trusted.gpg"),
    use_fsverity: false,
    use_ima: false,
    partitioning: PartitioningType::ABPartitions,
    sysext_dir: PathBuf::from("/var/lib/extensions"),
    zstd_dicts: HashMap::new(),
    tpm_tcti: Tcti::Tpmtis,
};

Tips for Configuration

• Security-First: Enable use_fsverity and use_ima on production systems.
• Testing: Start with minimal options and add features incrementally.
• Validation: libfasttree validates paths during init—check errors.
• Customization: For custom dicts, load bytes from files: fs::read("elf.dict")?.into().

Next: Proceed to Basic Usage: Installing and Deploying to see the config in action.

Last updated: February 11, 2026