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 = {
      debug.tools.enable = true;
      nix-setup.enable = false;  # Don't enable nix development setup
    };
    security.ssh.debug.enable = true;
    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.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.logseald.enable`	bool	true	Enable clock-independent log sealing on every logged component
`logging.logseald.port`	port	59631	Admin VM logseald mTLS listener port
`logging.listener.address`	string	“”	Logging listener address
`logging.listener.serverName`	null or string	null	Optional TLS name for the Admin VM logging listener
`logging.listener.port`	port	9999	Logging listener port
`logging.server.enable`	bool	true	Forward aggregated logs from the Admin VM to the remote endpoint

Whether to log is a platform decision and lives here; where the logs go is deployment data and lives in ghaf.org.telemetry.logging.

Logseald starts only on components for which global logging is enabled and requires GIVC with TLS credentials. See Clock-Independent Log Sealing for the architecture, operational checks, and security properties.

Security Settings

Option	Type	Default	Description
`security.audit.enable`	bool	false	Enable security auditing
`security.ssh.debug.enable`	bool	false	Enable unprotected debug SSH on all machines (password + dev keys; debug images)
`security.ssh.release.enable`	bool	false	Enable hardened, certificate/key-only release SSH on all machines

Posture owns the switches; the key material itself is deployment data and lives in ghaf.org.identity.ssh.

security.ssh.debug and security.ssh.release are mutually exclusive — an assertion forbids enabling both. Release SSH ships off; a downstream enables it and supplies the key material. See the SSH Access reference for the full mechanism, hardening rationale, YubiKey enrolment, and the connect/recovery workflow.

Values that moved to `ghaf.org`

These six were global config until the organization layer landed. They are deployment data, not platform posture, and carrying them in both places gave one value two entry points with different merge behaviour. They are now set through ghaf.org, which reaches the host and every VM:

Removed from `ghaf.global-config`	Now set through
`logging.server.endpoint`	`ghaf.org.telemetry.logging.endpoint`
`logging.logseald.revokedPeerKeys`	`ghaf.org.telemetry.logging.logseald.revokedPeerKeys`
`security.ssh.release.authorizedKeys`	`ghaf.org.identity.ssh.releaseKeys`
`security.ssh.release.trustedUserCAKeys`	`ghaf.org.identity.ssh.trustedUserCAKeys`
`security.ssh.release.allowedPrincipals`	`ghaf.org.identity.ssh.allowedPrincipals`
`security.ssh.release.authorizedKeysOptions`	`ghaf.org.identity.ssh.authorizedKeysOptions`

Setting one of the old paths is a hard evaluation error (The option … does not exist). That is deliberate: a silent fallback on key material is worse than a build that stops.

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                                    │   │
│  │  - security.ssh.debug.enable = true                       │   │
│  │  - ...                                                    │   │
│  └──────────────────────────────────────────────────────────┘   │
└────────────────────────────┬────────────────────────────────────┘
                             │ specialArgs
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                          VM CONFIGURATION                        │
│                                                                  │
│  { config, lib, globalConfig, ... }:                            │
│  {                                                               │
│    # Access inherited settings                                   │
│    ghaf.profiles.debug.enable = globalConfig.debug.enable;      │
│    ghaf.security.ssh.debug.enable =                             │
│      globalConfig.security.ssh.debug.enable;                     │
│  }                                                               │
└─────────────────────────────────────────────────────────────────┘

For Module Authors

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

{
  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.security.ssh.debug.enable =
      lib.mkDefault globalConfig.security.ssh.debug.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.security.ssh.debug.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 = {
    debug.tools.enable = true;
    nix-setup.enable = true;
  };
  security.ssh.debug.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 = {
    debug.tools.enable = false;
    nix-setup.enable = false;
  };
  security.ssh.debug.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 = {
    debug.tools.enable = false;
    nix-setup.enable = false;
  };
  security.ssh.debug.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

Global Configuration System

Global Configuration System

Overview

Key Benefits

Usage

Using Predefined Profiles

Customizing a Profile

Direct Configuration

Available Options

Debug Settings

Development Settings

Logging Settings

Security Settings

Values that moved to ghaf.org

GIVC Settings

Service Settings

Storage Settings

Platform Information

How It Works

Architecture

For Module Authors

Backward Compatibility

Migration Guide

For Existing Configurations

For New Configurations

For VM Module Authors

Profiles Reference

Debug Profile

Release Profile

Minimal Profile

Future Development

Values that moved to `ghaf.org`