itenv_tools/tools/VM_README.md

# Ubuntu VM Management with Cloud Hypervisor

This directory contains scripts for creating and managing Ubuntu VMs using Cloud Hypervisor with btrfs thin provisioning.

## Scripts Overview

1. **`ubuntu_vm_start.sh`** - Creates and starts new VMs
2. **`ubuntu_vm_manage.sh`** - Manages existing VMs (list, status, console, stop, etc.)
3. **`setup_vm_network.sh`** - Sets up networking for SSH access to VMs

## Prerequisites

- Root access
- Btrfs filesystem (script will detect and guide setup)
- Cloud Hypervisor installed
- Basic networking tools

## Quick Start

### 1. Set up networking (one-time setup)
```bash
sudo ./setup_vm_network.sh
```

### 2. Create and start a VM
```bash
sudo ./ubuntu_vm_start.sh my-vm 2048 2
```
This creates a VM named "my-vm" with 2GB RAM and 2 CPU cores.

### 3. List all VMs
```bash
sudo ./ubuntu_vm_manage.sh list
```

### 4. Connect to VM console
```bash
sudo ./ubuntu_vm_manage.sh console my-vm
```

## Detailed Usage

### Creating VMs

```bash
sudo ./ubuntu_vm_start.sh <vm_name> <memory_mb> <cpu_cores>
```

**Examples:**
```bash
# Create a small VM
sudo ./ubuntu_vm_start.sh test-vm 1024 1

# Create a larger VM
sudo ./ubuntu_vm_start.sh dev-vm 4096 4
```

**What happens:**
- Downloads Ubuntu 24.04 cloud image (first time only)
- Creates btrfs subvolumes for thin provisioning
- Sets up cloud-init with default user
- Creates network interfaces
- Starts the VM with Cloud Hypervisor

### Managing VMs

```bash
sudo ./ubuntu_vm_manage.sh <command> [vm_name]
```

**Available commands:**

| Command | Description | Example |
|---------|-------------|---------|
| `list` | Show all VMs and their status | `./ubuntu_vm_manage.sh list` |
| `status <vm>` | Detailed status of specific VM | `./ubuntu_vm_manage.sh status my-vm` |
| `console <vm>` | Connect to VM console | `./ubuntu_vm_manage.sh console my-vm` |
| `stop <vm>` | Stop a running VM | `./ubuntu_vm_manage.sh stop my-vm` |
| `delete <vm>` | Delete VM completely | `./ubuntu_vm_manage.sh delete my-vm` |
| `ssh <vm>` | Show SSH connection info | `./ubuntu_vm_manage.sh ssh my-vm` |

### Accessing VMs

#### Method 1: Console Access (Always Available)
```bash
sudo ./ubuntu_vm_manage.sh console my-vm
```
- Direct serial console access
- No network required
- Press `Ctrl+A` then `X` to exit
- Default login: `ubuntu` / `ubuntu`

#### Method 2: SSH Access (Requires Network Setup)
1. Set up networking first:
   ```bash
   sudo ./setup_vm_network.sh
   ```

2. Find VM IP address:
   ```bash
   vm-ips
   # or
   arp -a | grep 192.168.100
   ```

3. SSH to the VM:
   ```bash
   ssh ubuntu@192.168.100.X
   ```
   Default password: `ubuntu`

## Network Configuration

The `setup_vm_network.sh` script configures:

- **Bridge interface**: `br0` with IP `192.168.100.1/24`
- **DHCP server**: Assigns IPs `192.168.100.10-100` to VMs
- **NAT**: Enables internet access for VMs
- **DNS**: Uses Google DNS (8.8.8.8, 8.8.4.4)

### Network Troubleshooting

1. **Check bridge status:**
   ```bash
   ip addr show br0
   ```

2. **Check VM IP assignments:**
   ```bash
   vm-ips
   ```

3. **Check DHCP leases:**
   ```bash
   cat /var/lib/dhcp/dhcpd.leases
   ```

4. **Restart networking:**
   ```bash
   systemctl restart dnsmasq
   ```

## Storage (Btrfs)

VMs use btrfs subvolumes for efficient storage:

- **Base image**: Shared read-only Ubuntu image
- **VM snapshots**: Copy-on-write clones for each VM
- **Thin provisioning**: Only changed blocks use disk space

### Storage locations:
- Base images: `/var/lib/vms/base/`
- VM instances: `/var/lib/vms/vms/<vm-name>/`

### Storage commands:
```bash
# List subvolumes
btrfs subvolume list /var/lib/vms

# Show space usage
btrfs filesystem usage /var/lib/vms

# Show individual VM sizes
du -sh /var/lib/vms/vms/*
```

## VM Configuration

### Default VM Setup:
- **OS**: Ubuntu 24.04 LTS
- **User**: `ubuntu` (password: `ubuntu`)
- **Sudo**: Passwordless sudo enabled
- **SSH**: Enabled with password authentication
- **Packages**: curl, wget, git, htop, vim pre-installed

### Customizing VMs:
Edit the cloud-init configuration in `ubuntu_vm_start.sh` to:
- Add SSH keys
- Install additional packages
- Set custom passwords
- Configure services

## Troubleshooting

### VM won't start:
1. Check if Cloud Hypervisor is installed:
   ```bash
   which cloud-hypervisor
   ```

2. Check btrfs filesystem:
   ```bash
   btrfs filesystem show /var/lib/vms
   ```

3. Check available resources:
   ```bash
   free -h
   nproc
   ```

### Can't connect to VM:
1. Verify VM is running:
   ```bash
   ./ubuntu_vm_manage.sh status my-vm
   ```

2. Try console access first:
   ```bash
   ./ubuntu_vm_manage.sh console my-vm
   ```

3. Check network setup:
   ```bash
   ip addr show br0
   vm-ips
   ```

### VM is slow or unresponsive:
1. Check host resources:
   ```bash
   top
   iostat
   ```

2. Adjust VM resources:
   - Stop VM: `./ubuntu_vm_manage.sh stop my-vm`
   - Delete and recreate with different specs

## Security Notes

- Default password is `ubuntu` - change after first login
- Consider adding SSH keys instead of password auth
- VMs have internet access through NAT
- Console access requires root privileges on host

## Examples

### Create a development environment:
```bash
# Set up networking
sudo ./setup_vm_network.sh

# Create VM
sudo ./ubuntu_vm_start.sh dev-env 4096 4

# Wait for boot, then connect
sudo ./ubuntu_vm_manage.sh console dev-env

# Inside VM, change password and install tools
passwd
sudo apt update && sudo apt install -y build-essential nodejs npm
```

### Create multiple VMs:
```bash
# Create web server
sudo ./ubuntu_vm_start.sh web-server 2048 2

# Create database server
sudo ./ubuntu_vm_start.sh db-server 4096 2

# Create load balancer
sudo ./ubuntu_vm_start.sh lb 1024 1

# List all VMs
sudo ./ubuntu_vm_manage.sh list
```

## Performance Tips

1. **Use appropriate VM sizing** - Don't over-allocate resources
2. **Monitor host resources** - Ensure sufficient RAM/CPU
3. **Use btrfs compression** - Add `compress=zstd` mount option
4. **Regular cleanup** - Delete unused VMs to free space
5. **SSD storage** - Use SSD for better I/O performance

## Backup and Recovery

### Backup a VM:
```bash
# Stop VM first
sudo ./ubuntu_vm_manage.sh stop my-vm

# Create snapshot
sudo btrfs subvolume snapshot /var/lib/vms/vms/my-vm /var/lib/vms/backups/my-vm-$(date +%Y%m%d)
```

### Restore from backup:
```bash
# Delete current VM
sudo ./ubuntu_vm_manage.sh delete my-vm

# Restore from snapshot
sudo btrfs subvolume snapshot /var/lib/vms/backups/my-vm-20231215 /var/lib/vms/vms/my-vm