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