From ebee2a96cadda87a4bb5af5a53eef31f9b1ab607 Mon Sep 17 00:00:00 2001
From: Norm Brandinger <n.brandinger@gmail.com>
Date: Tue, 30 Dec 2025 14:18:00 -0500
Subject: [PATCH] fix: improve vagrant-qemu configuration for Apple Silicon

- Use unique SSH ports per VM (52222-52224) to avoid port collisions
- Configure HVF acceleration with recommended settings
- Use generic/debian12 ARM64 box (proven to download correctly)
- Increase boot timeout to 1200s for slow first boots
- Document known issues with SSH timeouts during boot
- Add alternative virtualization approaches (VirtualBox 7.1+, UTM, Lima)
---
 vagrant/README.md   | 35 +++++++++++++++++++++++++++++++++++
 vagrant/Vagrantfile | 21 ++++++++++++---------
 2 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/vagrant/README.md b/vagrant/README.md
index 4f5dd01..691ba3f 100644
--- a/vagrant/README.md
+++ b/vagrant/README.md
@@ -305,6 +305,41 @@ ansible/inventory/
 
 3. **Multiple Networks**: Unlike libvirt, vagrant-qemu doesn't support bridged networking as easily. All VMs use private_network.
 
+4. **Box Compatibility**: Some Vagrant boxes may have boot issues with vagrant-qemu on Apple Silicon. The `generic/debian12` ARM64 box is recommended but may require extended boot timeouts.
+
+## Known Issues
+
+### SSH Timeout During Boot
+
+If VMs show "timeout during server version negotiating" or "Connection reset by peer", the VM may be:
+- Still booting (can take 5-10 minutes on first boot)
+- Using an incompatible box (ensure ARM64 architecture)
+
+**Solutions:**
+1. Increase boot timeout in Vagrantfile (currently set to 1200s)
+2. Try a different ARM64-compatible box
+3. Verify QEMU supports HVF: `qemu-system-aarch64 -accel help`
+
+### Alternative Approaches
+
+If vagrant-qemu proves unreliable, consider:
+
+1. **VirtualBox 7.1+**: Now supports Apple Silicon (as of September 2024)
+   ```bash
+   brew install --cask virtualbox
+   vagrant up --provider=virtualbox
+   ```
+
+2. **UTM with vagrant-utm**: Native macOS virtualization
+   - Install UTM from App Store
+   - `vagrant plugin install vagrant_utm`
+
+3. **Lima/Colima**: Lightweight alternative with QEMU backend
+   ```bash
+   brew install colima
+   colima start --vm-type=qemu --arch=aarch64
+   ```
+
 ## References
 
 - [vagrant-qemu GitHub](https://github.com/ppggff/vagrant-qemu)
diff --git a/vagrant/Vagrantfile b/vagrant/Vagrantfile
index 8b7b1f1..541e647 100644
--- a/vagrant/Vagrantfile
+++ b/vagrant/Vagrantfile
@@ -27,6 +27,7 @@
 Vagrant.require_version ">= 2.3.0"
 
 # VM Configuration
+# Using generic/debian12 ARM64 for vagrant-qemu on Apple Silicon
 VM_BOX = "generic/debian12"
 VM_BOX_VERSION = "4.3.12"
 
@@ -37,11 +38,13 @@ NETWORK_PREFIX = "192.168.64"
 GATEWAY = "192.168.64.1"
 
 # VM Definitions
+# Each VM needs a unique ssh_port to avoid port collisions with vagrant-qemu
 VMS = {
   "sip-1" => {
     ip: "#{NETWORK_PREFIX}.10",
     memory: 2048,
     cpus: 2,
+    ssh_port: 52222,
     role: "sip_proxy",
     description: "OpenSIPS SIP Proxy",
     ansible_groups: ["sip_proxies", "voip"]
@@ -50,6 +53,7 @@ VMS = {
     ip: "#{NETWORK_PREFIX}.20",
     memory: 4096,
     cpus: 4,
+    ssh_port: 52223,
     role: "media",
     description: "RTPEngine Media Proxy",
     ansible_groups: ["media_servers", "voip"]
@@ -58,6 +62,7 @@ VMS = {
     ip: "#{NETWORK_PREFIX}.30",
     memory: 4096,
     cpus: 2,
+    ssh_port: 52224,
     role: "pbx",
     description: "Asterisk PBX",
     ansible_groups: ["pbx", "voip"]
@@ -76,6 +81,9 @@ Vagrant.configure("2") do |config|
   config.ssh.insert_key = true
   config.ssh.forward_agent = true
 
+  # Increase boot timeout for QEMU VMs (can be slow on first boot)
+  config.vm.boot_timeout = 1200
+
   # Disable default synced folder (use Ansible for file transfers)
   config.vm.synced_folder ".", "/vagrant", disabled: true
 
@@ -90,22 +98,17 @@ Vagrant.configure("2") do |config|
         netmask: "255.255.255.0"
 
       # QEMU provider configuration
+      # Uses recommended settings for Apple Silicon/ARM64 with HVF acceleration
       vm.vm.provider "qemu" do |qe|
         qe.memory = vm_config[:memory].to_s
         qe.smp = vm_config[:cpus].to_s
         qe.arch = "aarch64"
-        qe.machine = "virt,accel=hvf,highmem=on"
+        qe.machine = "virt,accel=hvf,highmem=off"
         qe.cpu = "host"
         qe.net_device = "virtio-net-pci"
 
-        # Extra QEMU arguments for Apple Silicon optimization
-        qe.extra_qemu_args = %w(
-          -cpu host
-          -smp 2,sockets=1,cores=2,threads=1
-        )
-
-        # Enable serial console for debugging
-        qe.extra_qemu_args += %w(-serial mon:stdio) if ENV['VAGRANT_DEBUG']
+        # Unique SSH port for each VM to avoid collisions
+        qe.ssh_port = vm_config[:ssh_port]
       end
 
       # VM-specific provisioning message