How OpenLogi Handles Configuration Updates and Backups: A Complete Technical Guide

OpenLogi stores configuration as a plain-text TOML file in the XDG config directory and implements an atomic update workflow that creates timestamped backups before overwriting, followed by hot-reloading via IPC without requiring agent restarts.

The AprilNEA/OpenLogi repository implements a robust atomic configuration system for managing input device settings. Every configuration change triggers an automatic backup rotation that preserves historic states, while the agent applies updates live through inter-process communication. This ensures users never lose working configurations and can revert changes instantly.

Configuration Storage and File Locations

OpenLogi adheres to the XDG Base Directory Specification, locating user configuration at $HOME/.config/openlogi/config.toml. This standardized path allows seamless integration with Linux desktop environments and simplifies backup management for system administrators.

TOML Structure and Validation

The core library parses this file using strict schema validation located in crates/openlogi-core/src/config/file.rs. When the GUI or CLI generates new configuration content, the library first validates the TOML structure before proceeding to the atomic write sequence.

The Configuration Update Workflow

The update process follows a strict three-phase protocol designed to prevent data loss and ensure zero-downtime configuration changes.

Step 1—Creating Immutable Backups

Before any write operation, the system invokes backup_config_once() at line 169 of crates/openlogi-core/src/config/file.rs. This function calls backup_existing_config(path) (lines 327–335) to initiate the rotation mechanism.

The backup rotation shifts existing copies upward through generations:

fn backup_existing_config(path: &Path) -> io::Result<()> {
    const MAX_BACKUPS: usize = 5; // Configurable retention limit
    
    // Rotate older backups forward: backup.2 becomes backup.3, etc.
    for gen in (1..=MAX_BACKUPS).rev() {
        let src = config_backup_path(path, gen)?;
        let dst = config_backup_path(path, gen + 1)?;
        if src.exists() {
            fs::rename(src, dst)?;
        }
    }
    
    // Create the newest backup as generation 1
    write_atomic(&config_backup_path(path, 1)?, &fs::read(path)?)
}

This rotation preserves the most recent MAX_BACKUPS generations, naming them config.toml.backup.1, config.toml.backup.2, etc., as implemented in lines 344–356.

Step 2—Atomic Write Operations

After securing the backup, OpenLogi writes the new configuration using atomic filesystem operations to prevent corruption during power loss or crashes. The write_atomic helper ensures that the file either updates completely or remains untouched, maintaining configuration integrity.

Step 3—Hot Reloading via IPC

Rather than restarting the background agent, OpenLogi utilizes the IPC layer defined in crates/openlogi-ipc/src/ipc.rs. The GUI issues a reload_config request (lines 381–387), which triggers the agent to:

1. Re-read the config.toml file from disk
2. Validate the new configuration against the schema
3. Update live state including DPI mappings and lighting profiles
4. Return success without disrupting active device connections

// GUI-side implementation
async fn apply_configuration(new_toml: String) -> Result<(), ConfigError> {
    // Phase 1 & 2: Backup and atomic write
    openlogi_core::config::write_config(&new_toml)?;
    
    // Phase 3: Notify agent via IPC
    ipc_client.reload_config().await?;
    Ok(())
}

Backup Rotation Mechanism

The config_backup_path function (lines 347–356) generates standardized backup filenames following the pattern config.toml.backup.{generation}. When the maximum generation count exceeds the configured limit, the oldest backup automatically expires during the rotation cycle.

The test suite in crates/openlogi-core/src/config/tests.rs (lines 27–64) validates this behavior, verifying that successive configuration writes correctly generate numbered backups and preserve historic generations. These tests ensure that the rotation logic handles edge cases such as missing intermediate generations or permission errors gracefully.

Configuration Recovery and Restoration

Users can manually restore previous configurations by copying any config.toml.backup.N file to config.toml. Because the agent only reads the configuration during explicit reload_config IPC calls or initial startup, administrators have complete control over when changes take effect simply by triggering a reload after file restoration.

Summary

• OpenLogi stores user settings in $HOME/.config/openlogi/config.toml following XDG standards.
• Automatic backups are created before every write via backup_existing_config() in crates/openlogi-core/src/config/file.rs, maintaining configurable generations of history.
• Atomic writes ensure configuration files cannot be corrupted during update operations.
• Hot reloading through the reload_config IPC method (lines 381–387 in crates/openlogi-ipc/src/ipc.rs) allows immediate configuration changes without agent restarts.
• Comprehensive tests in crates/openlogi-core/src/config/tests.rs verify backup rotation reliability.

Frequently Asked Questions

Where does OpenLogi store its configuration files?

OpenLogi stores its configuration in $HOME/.config/openlogi/config.toml according to the XDG Base Directory Specification. The core library locates this path dynamically using standard environment variables, falling back to the home directory when XDG variables are unset.

How many backup generations does OpenLogi keep?

OpenLogi maintains a configurable number of backup generations defined by the MAX_BACKUPS constant in the backup rotation logic. By default, the system preserves the five most recent versions, automatically expiring older copies during the rotation sequence defined in backup_existing_config().

Does OpenLogi require a restart to apply new settings?

No. OpenLogi implements a hot-reload mechanism where the GUI or CLI sends a reload_config IPC request to the running agent. The agent then re-reads and validates config.toml, applying DPI maps, lighting profiles, and other settings without terminating active processes or dropping device connections.

Can I manually restore a backup configuration?

Yes. To restore a previous state, copy the desired backup file (e.g., config.toml.backup.1) to config.toml in the configuration directory, then either restart the agent or trigger a configuration reload through the GUI. The backup files are plain TOML text identical in format to the main configuration file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}