1 files changed, 110 insertions, 0 deletions
diff --git a/test-env/README.md b/test-env/README.md
new file mode 100644
index 0000000..ef2bb0a
--- /dev/null
+++ b/test-env/README.md
@@ -0,0 +1,110 @@
+# Technical Specification: Automated KVM Provisioning for Hoods Gate Testing
+
+This document outlines the architecture and implementation of a shell-based
+automation utility for deploying Kernel-based Virtual Machines (KVM) on Ubuntu
+Server using virt-install. This approach is designed for rapid iteration in
+kernel development and network stack testing where total environment isolation
+is required.
+
+## Overview
+
+The goal of this implementation is to provide a reproducible, command-line
+driven interface for deploying headless virtual machines. By utilizing a Linux
+Bridge and Serial Console redirection, developers can perform destructive
+kernel operations while maintaining persistent access to the debug output,
+bypassing the overhead of a graphical user interface.
+
+## System Requirements & Prerequisites
+
+The host system must support hardware virtualization (Intel VT-x or AMD-V) and
+have the following packages installed:
+
+- qemu-kvm: Backend emulator
+- libvirt-daemon-system: Management system
+- virinst: CLI Utility for provisioning
+- bridge-utils: Necessary for L2 network bridging
+
+### Storage Persistence
+
+Virtual disk images created by this script are stored in
+/var/lib/libvirt/images/. During kernel testing, if the filesystem becomes
+corrupted due to experimental kernel modules, the storage must be manually
+purged or overwritten.
+
+### Network Configuration
+
+The host must have a bridge interface (e.g., br0) configured via Netplan.
+This allows the Guest VM to obtain its own IP address and provides a
+transparent environment for testing custom networking protocols or firewall
+rules.
+
+## Implementation
+
+The script, [provision-lab.sh](./provision-vm.sh), automates the
+virt-install process for isolated kernel and network testing. It utilizes local
+ISO media and libosinfo detection to ensure hardware-optimized environments
+while configuring the serial console for direct TTY access.
+
+## Operational Procedures
+
+### VM Creation
+
+Execute the script with optional parameters for resource allocation:
+
+```shell
+sudo ./provision-vm.sh <name> <vcpus> <ram_in_mb>
+```
+
+### Interacting with the Guest Kernel
+
+Since the VM is configured without a graphics card, the standard virsh console
+command is used to attach to the guest's serial port. This is essential for
+capturing Kernel Panics or Early Printk output that would otherwise be lost.
+
+Attach to Console:
+
+```shell
+virsh console <vm-name>
+```
+
+Detach from Console (Press):
+
+```
+CTRL + ]
+```
+
+### Modifying Kernel Parameters
+
+To test specific kernel options (e.g., disabling KASLR or isolating CPUs),
+edit the VM configuration directly via the XML descriptor:
+
+```shell
+virsh edit <vm-name>
+```
+
+Locate the <cmdline> tag within the <os> section to append your required flags.
+
+### Network Analysis
+
+Use tcpdump -i br0 on the host to monitor raw packet traffic moving through the
+VM's virtual interface.
+
+```shell
+tcpdump -i br0
+```
+
+## Lifecycle Management
+
+Operation|Command|Description
+Start|virsh start <name>|Powers on the virtual machine
+Stop|virsh shutdown <name>|Sends an ACPI power signal for a graceful exit
+Destroy|virsh destroy <name>|Equivalent to pulling the power plug (immediate stop)
+Undefine|virsh undefine <name> --remove-all-storage|Completely removes the VM and its disk images
+
+## Technical Considerations
+
+When performing kernel modifications, the following behaviors should be expected:
+
+- _Storage Persistence_: Changes made to the filesystem persist unless the --remove-all-storage flag is used during deletion.
+- _Network Isolation_: By using a bridge, the VM possesses its own MAC address. Ensure the host firewall (ufw/iptables) is configured to allow traffic across the bridge.
+- _Instruction Set Passthrough_: If the kernel testing requires specific CPU instructions (e.g., AES-NI), append --cpu host-passthrough to the virt-install command.