Profiles API

Profiles API

The lib.ghaf namespace provides predefined configuration profiles and a factory function for creating custom profiles in the Ghaf framework.

Overview

Profiles provide consistent sets of global configuration values. Instead of manually configuring each option, select a profile that matches your needs.

lib.ghaf = {
  profiles = {
    debug     # Development/debugging profile
    release   # Production release profile
    minimal   # Minimal configuration profile
  };
  mkGlobalConfig   # Create custom profile by extending a base
};

---

Predefined Profiles

debug

Development profile with extensive debugging capabilities.

lib.ghaf.profiles.debug = {
  debug.enable = true;

  development = {
    ssh.daemon.enable = true;
    debug.tools.enable = true;
    nix-setup.enable = true;
  };

  logging = {
    enable = true;
    server.endpoint = "https://loki.ghaflogs.vedenemo.dev/loki/api/v1/push";
  };

  security.audit.enable = false;

  givc = {
    enable = true;
    debug = false;  # Disabled to allow logging (they conflict)
  };

  services = {
    power-manager.enable = false;
    performance.enable = false;
  };

  storage = {
    encryption.enable = false;
    storeOnDisk = false;
  };

  shm.enable = false;
  idsvm.mitmproxy.enable = false;

  features = {
    fprint = { enable = true; targetVms = [ "gui-vm" ]; };
    yubikey = { enable = true; targetVms = [ "gui-vm" ]; };
    brightness = { enable = true; targetVms = [ "gui-vm" ]; };
    wifi = { enable = true; targetVms = [ "net-vm" ]; };
    audio = { enable = true; targetVms = [ "audio-vm" ]; };
    bluetooth = { enable = true; targetVms = [ "audio-vm" ]; };
  };
};

Use when:

• Development and testing
• Need SSH access to VMs
• Need debug tools installed
• Troubleshooting issues

Example:

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

---

release

Production profile with security hardening.

lib.ghaf.profiles.release = {
  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;
  };

  shm.enable = false;
  idsvm.mitmproxy.enable = false;

  features = {
    fprint = { enable = true; targetVms = [ "gui-vm" ]; };
    yubikey = { enable = true; targetVms = [ "gui-vm" ]; };
    brightness = { enable = true; targetVms = [ "gui-vm" ]; };
    wifi = { enable = true; targetVms = [ "net-vm" ]; };
    audio = { enable = true; targetVms = [ "audio-vm" ]; };
    bluetooth = { enable = true; targetVms = [ "audio-vm" ]; };
  };
};

Use when:

• Production deployments
• Security-sensitive environments
• Final product images

Example:

ghaf.global-config = lib.ghaf.profiles.release;

---

minimal

Stripped-down profile for resource-constrained environments.

lib.ghaf.profiles.minimal = {
  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;
  };

  shm.enable = false;
  idsvm.mitmproxy.enable = false;

  features = {
    fprint = { enable = false; targetVms = []; };
    yubikey = { enable = false; targetVms = []; };
    brightness = { enable = false; targetVms = []; };
    wifi = { enable = false; targetVms = []; };
    audio = { enable = false; targetVms = []; };
    bluetooth = { enable = false; targetVms = []; };
  };
};

Use when:

• Resource-constrained hardware
• Minimal footprint requirements
• Testing core functionality without extras

Example:

ghaf.global-config = lib.ghaf.profiles.minimal;

---

Profile Comparison

Setting	debug	release	minimal
debug.enable	true	false	false
development.ssh.daemon.enable	true	false	false
development.debug.tools.enable	true	false	false
development.nix-setup.enable	true	false	false
logging.enable	true	false	false
security.audit.enable	false	true	false
givc.enable	true	true	false
givc.debug	false	false	false
services.power-manager.enable	false	true	false
services.performance.enable	false	true	false
storage.encryption.enable	false	true	false
features.* (all)	enabled	enabled	disabled

---

mkGlobalConfig

Factory function for creating custom profiles by extending a base profile.

Signature:

mkGlobalConfig :: String -> AttrSet -> AttrSet
mkGlobalConfig profileName overrides

Parameters:

Name	Type	Description
profileName	String	Base profile to extend: "debug", "release", or "minimal"
overrides	AttrSet	Values to merge over the base profile

Returns: Complete global configuration attrset.

Example:

# Start with debug profile, customize some settings
ghaf.global-config = lib.ghaf.mkGlobalConfig "debug" {
  # Override specific settings
  givc.debug = false;
  development.ssh.daemon.enable = false;

  # Add custom settings
  features.fprint.targetVms = [ "admin-vm" ];
};

---

Usage Patterns

Pattern 1: Direct Profile Selection

Simplest approach - select a predefined profile:

# For development
ghaf.global-config = lib.ghaf.profiles.debug;

# For production
ghaf.global-config = lib.ghaf.profiles.release;

Pattern 2: Profile with Overrides

Use a profile as base, then customize:

ghaf.global-config = lib.ghaf.profiles.debug // {
  # Disable GIVC debugging
  givc.debug = false;

  # Custom logging config
  logging.listener.port = 9998;
};

Pattern 3: mkGlobalConfig Factory

Use the factory for cleaner customization:

ghaf.global-config = lib.ghaf.mkGlobalConfig "debug" {
  # All debug profile defaults applied
  # Just specify overrides:
  features = {
    fprint.targetVms = [ "admin-vm" ];
    bluetooth.enable = false;
  };
};

Pattern 4: Downstream Project Profile

Create a project-specific profile:

# In downstream project's lib/profiles.nix
{ lib }:
{
  fmoDebug = lib.ghaf.mkGlobalConfig "debug" {
    # FMO-specific debug settings
    features.yubikey.targetVms = [ "gui-vm" "gcs-vm" ];
    logging.listener.port = 10000;
  };

  fmoRelease = lib.ghaf.mkGlobalConfig "release" {
    # FMO production overrides
    features.yubikey.targetVms = [ "gui-vm" "gcs-vm" ];
  };
}

Pattern 5: Conditional Profile Selection

Select profile based on variant:

# In target configuration
{ variant ? "debug", lib, ... }:
{
  ghaf.global-config =
    if variant == "release"
    then lib.ghaf.profiles.release
    else lib.ghaf.profiles.debug;
}

---

Complete globalConfig Schema

For reference, here’s the full schema of values in globalConfig:

{
  # Debug settings
  debug.enable = bool;         # Default: false

  # Development tools
  development = {
    ssh.daemon.enable = bool;  # Default: false
    debug.tools.enable = bool; # Default: false
    nix-setup.enable = bool;   # Default: false
  };

  # System logging
  logging = {
    enable = bool;             # Default: false
    listener = {
      address = str;           # Default: "" (auto-populated from admin-vm IP)
      port = port;             # Default: 9999
    };
    server.endpoint = str;     # Default: ""
  };

  # Security
  security.audit.enable = bool; # Default: false

  # GIVC inter-VM communication
  givc = {
    enable = bool;             # Default: false
    debug = bool;              # Default: false
  };

  # System services
  services = {
    power-manager.enable = bool; # Default: false
    performance.enable = bool;   # Default: false
  };

  # Storage settings
  storage = {
    encryption.enable = bool;  # Default: false
    storeOnDisk = bool;        # Default: false
  };

  # Shared memory
  shm = {
    enable = bool;             # Default: false
    serverSocketPath = str;    # Default: ""
  };

  # IDS VM settings
  idsvm.mitmproxy.enable = bool; # Default: false

  # Platform information
  platform = {
    buildSystem = str;         # Default: "x86_64-linux"
    hostSystem = str;          # Default: "x86_64-linux"
    timeZone = str;            # Default: "UTC"
  };

  # Feature assignments
  features = {
    fprint = {
      enable = bool;           # Default: true
      targetVms = [ str ];     # Default: [ "gui-vm" ]
    };
    yubikey = {
      enable = bool;           # Default: true
      targetVms = [ str ];     # Default: [ "gui-vm" ]
    };
    brightness = {
      enable = bool;           # Default: true
      targetVms = [ str ];     # Default: [ "gui-vm" ]
    };
    wifi = {
      enable = bool;           # Default: true
      targetVms = [ str ];     # Default: [ "net-vm" ]
    };
    audio = {
      enable = bool;           # Default: true
      targetVms = [ str ];     # Default: [ "audio-vm" ]
    };
    bluetooth = {
      enable = bool;           # Default: true
      targetVms = [ str ];     # Default: [ "audio-vm" ]
    };
  };
}

---

Integration with Targets

Profiles are typically applied via the variant parameter in mkGhafConfiguration:

targets/laptop/flake-module.nix

mkGhafConfiguration {
  name = "my-target";
  system = "x86_64-linux";
  profile = "laptop-x86";
  hardwareModule = self.nixosModules.hardware-my-target;
  variant = "debug";  # Selects lib.ghaf.profiles.debug via mkDefault
}

The builder applies the selected profile to ghaf.global-config using mkDefault, allowing profile modules to override specific values.

---

See Also

• Configuration Propagation - How profiles flow to VMs
• Extending Targets - Using profiles in targets