ghaf-vms: similar to microvm cmdline tool

Adds functionality to host to query the status of the vms that are on
the system.

When using the storeOnDisk option, there is no link created to the
current system so the `microvm -l` will not work and just stops. Ensure
that it is possible to see at a glance which vm is actually running/stopped.

Signed-off-by: Brian McGillion <[email protected]>

Author: brianmcgillion

docs/astro.config.mjs

@@ -97,6 +97,7 @@ export default defineConfig({
                         "ghaf/dev/ref/kill_switch",
                         "ghaf/dev/ref/wireguard-gui",
                         "ghaf/dev/ref/yubikey",
+                        "ghaf/dev/ref/ghaf-vms",
                       ],
                     },
                     {

docs/src/content/docs/ghaf/dev/ref/ghaf-vms.mdx

@@ -0,0 +1,78 @@
+---
+title: Ghaf VMs Status Tool
+description: CLI tool to monitor and manage MicroVM status in Ghaf.
+---
+
+## Overview
+
+`ghaf-vms` is a command-line utility in Ghaf that provides real-time status information about running MicroVMs on the host system. It queries systemd to determine the state of each configured MicroVM and displays the information in a color-coded, easy-to-read format.
+
+This tool is particularly useful for:
+- Checking which VMs are running or stopped
+- Debugging VM startup issues
+- Monitoring the overall health of the MicroVM architecture
+- Quick system status overview without navigating through systemd commands
+
+---
+
+## Usage & Commands
+
+Run `ghaf-vms` on the Ghaf host to view VM status. General usage:
+
+```sh
+[ghaf@ghaf-host:~]$ ghaf-vms [OPTIONS]
+```
+
+### Options
+
+* `-l` — List all configured MicroVMs and their current status (default behavior)
+* `-h` — Show usage instructions
+
+### Examples
+
+#### List all VMs and their status
+
+```bash
+[ghaf@ghaf-host:~]$ ghaf-vms -l
+```
+
+Or simply:
+
+```bash
+[ghaf@ghaf-host:~]$ ghaf-vms
+```
+
+Example output:
+
+```
+  VM Status:
+  =========
+  audio-vm: running
+  business-vm: running
+  chrome-vm: running
+  gui-vm: running
+  ids-vm: running
+  net-vm: running
+  zathura-vm: stopped
+```
+
+### Status Indicators
+
+The tool displays VMs with color-coded status indicators:
+
+| Status | Color | Description |
+|--------|-------|-------------|
+| `RUNNING` | Green | VM is currently active and running |
+| `STOPPED` | Red | VM is configured but not running |
+| `FAILED` | Bold Red | VM service failed to start |
+| `ACTIVATING` | Yellow | VM is in the process of starting |
+| Other states | Cyan | VM is in another systemd state (e.g., deactivating, reloading) |
+
+
+---
+
+## See Also
+
+- [Creating Application VM](/ghaf/dev/ref/creating_appvm/) — How to create new MicroVMs
+- [MicroVM Architecture](/ghaf/overview/arch/system-architecture/) — Understanding Ghaf's VM architecture
+- [Troubleshooting](/ghaf/dev/troubleshooting/) — General troubleshooting guidance

modules/development/dt-host.nix

@@ -27,6 +27,8 @@ in
           pkgs.cryptsetup
           # check hardware info
           pkgs.lshw
+          # List microvm status
+          pkgs.ghaf-vms
         ]);
   };
 }

packages/own-pkgs-overlay.nix

@@ -14,6 +14,7 @@
     ghaf-installer = final.callPackage ./pkgs-by-name/ghaf-installer/package.nix { };
     ghaf-open = final.callPackage ./pkgs-by-name/ghaf-open/package.nix { };
     ghaf-powercontrol = final.callPackage ./ghaf-powercontrol/package.nix { };
+    ghaf-vms = final.callPackage ./pkgs-by-name/ghaf-vms/package.nix { };
     hardware-scan = final.callPackage ./pkgs-by-name/hardware-scan/package.nix { };
     make-checks = final.callPackage ./pkgs-by-name/make-checks/package.nix { };
     memsocket = final.callPackage ./pkgs-by-name/memsocket/package.nix { };

packages/pkgs-by-name/ghaf-vms/package.nix

@@ -0,0 +1,121 @@
+# SPDX-FileCopyrightText: 2022-2026 TII (SSRC) and the Ghaf contributors
+# SPDX-License-Identifier: Apache-2.0
+{
+  writeShellApplication,
+  lib,
+  busybox,
+  systemd,
+}:
+let
+  colors = {
+    normal = "\\033[0m";
+    red = "\\033[0;31m";
+    green = "\\033[0;32m";
+    yellow = "\\033[0;33m";
+    boldRed = "\\033[1;31m";
+  };
+  colored = color: text: "${colors.${color}}${text}${colors.normal}";
+in
+writeShellApplication {
+  name = "ghaf-vms";
+
+  runtimeInputs = [
+    busybox
+    systemd
+  ];
+
+  text = ''
+    MICROVM_DIR="/var/lib/microvms"
+
+    # Function to display usage
+    show_usage() {
+        echo "Usage: ghaf-vms [OPTIONS]"
+        echo ""
+        echo "Options:"
+        echo "  -l, --list    List all VMs and their status"
+        echo "  -h, --help    Show this help message"
+        echo ""
+        echo "If no option is specified, -l/--list is assumed."
+    }
+
+    # Function to list VMs
+    list_vms() {
+        if [ ! -d "$MICROVM_DIR" ]; then
+            echo -e "${colored "red" "Error: MicroVM directory $MICROVM_DIR does not exist"}"
+            exit 1
+        fi
+
+        # Check if there are any VMs
+        if [ -z "$(ls -A "$MICROVM_DIR" 2>/dev/null)" ]; then
+            echo "No VMs found in $MICROVM_DIR"
+            exit 0
+        fi
+
+        echo "VM Status:"
+        echo "=========="
+
+        # Iterate through each VM directory
+        for vm_dir in "$MICROVM_DIR"/*; do
+            if [ -d "$vm_dir" ]; then
+                vm_name=$(basename "$vm_dir")
+
+                # Only allow alphanumeric, hyphens, and underscores
+                if [[ ! "$vm_name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+                    echo -e "${colored "yellow" "Warning: Skipping invalid VM name: $vm_name"}" >&2
+                    continue
+                fi
+
+                service_name="microvm@$vm_name.service"
+
+                # Get service status
+                if systemctl is-active --quiet "$service_name"; then
+                    status="${colored "green" "running"}"
+                elif systemctl is-enabled --quiet "$service_name" 2>/dev/null; then
+                    status="${colored "red" "stopped"}"
+                else
+                    # Check if service exists but is failed or in other state
+                    if systemctl status "$service_name" &>/dev/null; then
+                        service_state=$(systemctl show -p ActiveState --value "$service_name")
+                        case "$service_state" in
+                        failed)
+                            status="${colored "boldRed" "failed"}"
+                            ;;
+                        *)
+                            status="${colored "yellow" "$service_state"}"
+                            ;;
+                        esac
+                    else
+                        status="${colored "yellow" "unknown"}"
+                    fi
+                fi
+
+                # Print VM status
+                echo -e "$vm_name: $status"
+            fi
+        done
+    }
+
+    while getopts ":lh" opt; do
+        case $opt in
+        l) list_vms ;;
+        h)
+            show_usage
+            exit 0
+            ;;
+        *)
+            show_usage
+            exit 1
+            ;;
+        esac
+    done
+
+    # If no arguments are provided, list VMs
+    list_vms
+  '';
+
+  meta = {
+    description = "List status of Ghaf MicroVMs";
+    license = lib.licenses.asl20;
+    platforms = lib.platforms.linux;
+  };
+}