Global Configuration System

Global Configuration System

The Ghaf framework provides a global configuration system that allows settings to be defined once at the host level and automatically propagated to all VMs. This eliminates the need to manually synchronize settings between the host and each virtual machine.

Overview

The global configuration system solves the “configuration propagation problem” where settings like debug mode, SSH access, or storage encryption need to be consistent across the host and all guest VMs.

Key Benefits

• Single Source of Truth: Set configuration once, applied everywhere
• Reduced Errors: No more forgetting to update a setting in one VM
• Clear Inheritance: VMs automatically receive host settings
• Override Capability: Individual VMs can override inherited settings when needed
• Profile Support: Predefined profiles for common configurations (debug, release, minimal)

Usage

Using Predefined Profiles

The simplest way to configure Ghaf is to use a predefined profile:

{
  ghaf.global-config = lib.ghaf.profiles.debug;
}

Available profiles:

• lib.ghaf.profiles.debug - Full development/debugging capabilities
• lib.ghaf.profiles.release - Production settings with security enabled
• lib.ghaf.profiles.minimal - Bare minimum configuration

Customizing a Profile

You can extend a profile with custom settings:

{
  ghaf.global-config = lib.ghaf.mkGlobalConfig "debug" {
    storage.encryption.enable = true;  # Override storage setting
  };
}

Direct Configuration

Set options directly without using a profile:

{
  ghaf.global-config = {
    debug.enable = true;
    development = {
      ssh.daemon.enable = true;
      debug.tools.enable = true;
      nix-setup.enable = false;  # Don't enable nix development setup
    };
    logging.enable = true;
    storage.encryption.enable = true;
  };
}

Available Options

Debug Settings

Option	Type	Default	Description
debug.enable	bool	false	Enable debug mode globally

Development Settings

Option	Type	Default	Description
development.ssh.daemon.enable	bool	false	Enable SSH daemon on all VMs
development.debug.tools.enable	bool	false	Install debug tools
development.nix-setup.enable	bool	false	Enable Nix development setup

Logging Settings

Option	Type	Default	Description
logging.enable	bool	false	Enable centralized logging
logging.listener.address	string	“”	Logging listener address
logging.server.endpoint	string	“”	Remote logging server endpoint

Security Settings

Option	Type	Default	Description
security.audit.enable	bool	false	Enable security auditing

GIVC Settings

Option	Type	Default	Description
givc.enable	bool	false	Enable GIVC (Inter-VM Communication)
givc.debug	bool	false	Enable GIVC debug mode

Service Settings

Option	Type	Default	Description
services.power-manager.enable	bool	false	Enable power manager
services.performance.enable	bool	false	Enable performance service

Storage Settings

Option	Type	Default	Description
storage.encryption.enable	bool	false	Enable storage encryption
storage.storeOnDisk	bool	false	Store VM nix stores on disk

Platform Information

These are automatically populated from host configuration:

Option	Type	Description
platform.buildSystem	string	Build platform (e.g., “x86_64-linux”)
platform.hostSystem	string	Host platform (e.g., “x86_64-linux”)
platform.timeZone	string	System timezone

How It Works

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         HOST CONFIGURATION                       │
│                                                                  │
│  ghaf.global-config = lib.ghaf.profiles.debug;                  │
│         │                                                        │
│         ▼                                                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ ghaf.global-config (evaluated)                            │   │
│  │  - debug.enable = true                                    │   │
│  │  - development.ssh.daemon.enable = true                   │   │
│  │  - ...                                                    │   │
│  └──────────────────────────────────────────────────────────┘   │
└────────────────────────────┬────────────────────────────────────┘
                             │ specialArgs
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                          VM CONFIGURATION                        │
│                                                                  │
│  { config, lib, globalConfig, ... }:                            │
│  {                                                               │
│    # Access inherited settings                                   │
│    ghaf.profiles.debug.enable = globalConfig.debug.enable;      │
│    ghaf.development.ssh.daemon.enable =                         │
│      globalConfig.development.ssh.daemon.enable;                 │
│  }                                                               │
└─────────────────────────────────────────────────────────────────┘

For Module Authors

When creating VM modules that need global settings, access them via the globalConfig specialArg:

modules/microvm/sysvms/my-vm.nix

{
  config,
  lib,
  globalConfig,  # Provided via specialArgs
  ...
}:
let
  # Use globalConfig for settings that should be inherited from host
  debugEnabled = globalConfig.debug.enable;
in
{
  config = {
    # Apply global settings to VM
    ghaf.profiles.debug.enable = lib.mkDefault debugEnabled;

    ghaf.development.ssh.daemon.enable =
      lib.mkDefault globalConfig.development.ssh.daemon.enable;
  };
}

Backward Compatibility

The global configuration system maintains backward compatibility with existing Ghaf configurations. Old-style settings like ghaf.profiles.debug.enable = true are automatically synchronized to ghaf.global-config.debug.enable.

This means:

• Existing configurations continue to work without changes
• VMs using the new globalConfig pattern receive correct values
• Migration can be done incrementally

Migration Guide

For Existing Configurations

No changes are required. Your existing configuration will continue to work, and ghaf.global-config will automatically reflect your current settings.

For New Configurations

Consider using ghaf.global-config with profiles:

# Before (still works)
{
  ghaf.profiles.debug.enable = true;
  ghaf.development.ssh.daemon.enable = true;
  # ... repeated in each VM
}

# After (recommended)
{
  ghaf.global-config = lib.ghaf.profiles.debug;
  # Settings automatically propagate to all VMs
}

For VM Module Authors

Migrate from configHost pattern to globalConfig:

# Before
{ configHost }:
{
  config = {
    ghaf.profiles.debug.enable = configHost.ghaf.profiles.debug.enable;
  };
}

# After
{ globalConfig, ... }:
{
  config = {
    ghaf.profiles.debug.enable = lib.mkDefault globalConfig.debug.enable;
  };
}

Profiles Reference

Debug Profile

{
  debug.enable = true;
  development = {
    ssh.daemon.enable = true;
    debug.tools.enable = true;
    nix-setup.enable = true;
  };
  logging.enable = true;
  security.audit.enable = false;
  givc = {
    enable = true;
    debug = true;
  };
  services = {
    power-manager.enable = false;
    performance.enable = false;
  };
  storage = {
    encryption.enable = false;
    storeOnDisk = false;
  };
}

Release Profile

{
  debug.enable = false;
  development = {
    ssh.daemon.enable = false;
    debug.tools.enable = false;
    nix-setup.enable = false;
  };
  logging.enable = false;
  security.audit.enable = true;
  givc = {
    enable = true;
    debug = false;
  };
  services = {
    power-manager.enable = true;
    performance.enable = true;
  };
  storage = {
    encryption.enable = true;
    storeOnDisk = false;
  };
}

Minimal Profile

{
  debug.enable = false;
  development = {
    ssh.daemon.enable = false;
    debug.tools.enable = false;
    nix-setup.enable = false;
  };
  logging.enable = false;
  security.audit.enable = false;
  givc = {
    enable = false;
    debug = false;
  };
  services = {
    power-manager.enable = false;
    performance.enable = false;
  };
  storage = {
    encryption.enable = false;
    storeOnDisk = false;
  };
}

Future Development

The global configuration system will be extended in future phases to include:

• Complete VM migration to globalConfig pattern
• Additional settings for hardware passthrough
• Custom profile creation utilities
• Downstream project composition support