claude-home/scripts/vm-management/README.md

# VM Management and Provisioning

Automated VM provisioning scripts for Proxmox environments with SSH key deployment, system updates, and Docker installation.

## Files

### `vm-post-install.sh`
Post-installation provisioning script for existing VMs.

**Usage:**
```bash
./vm-post-install.sh <vm-ip> [ssh-user]
```

**Example:**
```bash
./vm-post-install.sh 10.10.0.100 cal
```

**Features:**
- ✅ System updates and essential packages
- ✅ SSH key deployment (primary + emergency keys)
- ✅ SSH security hardening (disable password auth)
- ✅ Docker and Docker Compose installation
- ✅ User environment setup with aliases
- ✅ Automatic security updates configuration

**Requirements:**
- Target VM must have SSH access enabled initially
- Homelab SSH keys must exist: `~/.ssh/homelab_rsa` and `~/.ssh/emergency_homelab_rsa`
- Initial connection may require password authentication

### `cloud-init-user-data.yaml`
Cloud-init configuration for fully automated VM provisioning in Proxmox.

**Usage:**
1. Copy contents of this file
2. In Proxmox, create VM with cloud-init support
3. Paste the YAML content into the "User Data" field
4. Start the VM

**Features:**
- ✅ User creation with sudo privileges
- ✅ SSH keys pre-installed (no password auth needed)
- ✅ Automatic package updates
- ✅ Docker and Docker Compose installation
- ✅ Security hardening from first boot
- ✅ Useful bash aliases and environment setup
- ✅ Welcome message with system status

## Quick Start

### Option 1: Post-Installation Script (Existing VMs)
```bash
# Make script executable
chmod +x scripts/vm-management/vm-post-install.sh

# Provision an existing VM
./scripts/vm-management/vm-post-install.sh 10.10.0.100 cal
```

### Option 2: Cloud-Init (New VMs in Proxmox)
1. Create new VM in Proxmox with cloud-init support
2. Go to Cloud-Init tab
3. Copy contents of `cloud-init-user-data.yaml` 
4. Paste into "User Data" field
5. Start VM - it will be fully provisioned automatically

## SSH Key Management Integration

Both provisioning methods integrate with the existing homelab SSH key management:

- **Primary Key**: `~/.ssh/homelab_rsa` - Daily use authentication
- **Emergency Key**: `~/.ssh/emergency_homelab_rsa` - Backup access
- **Security**: Password authentication disabled after key deployment
- **Backup**: Keys are managed by existing SSH backup system

## Post-Provisioning Verification

After provisioning, verify the setup:

```bash
# Test SSH access with key
ssh cal@<vm-ip>

# Verify Docker installation
docker --version
docker compose version
docker run --rm hello-world

# Check user groups
groups cal
# Should include: cal sudo docker

# Verify SSH security
sudo sshd -T | grep -E "(passwordauth|pubkeyauth|permitroot)"
# Should show:
# passwordauthentication no
# pubkeyauthentication yes  
# permitrootlogin no
```

## Customization

### Modifying SSH Keys
Edit the SSH public keys in `cloud-init-user-data.yaml` or ensure your local SSH keys match the expected paths for the post-install script.

### Changing Default User
Update the username in both scripts (default: `cal`):
- In `vm-post-install.sh`: Change `SSH_USER="${2:-cal}"`
- In `cloud-init-user-data.yaml`: Change the user configuration section

### Additional Packages
Add packages to:
- **Post-install script**: Add to the `apt install` command
- **Cloud-init**: Add to the `packages:` section

### Custom Aliases
Modify bash aliases in:
- **Post-install script**: Update the aliases added to `~/.bashrc`
- **Cloud-init**: Edit the `.bash_aliases` file content

## Troubleshooting

### Script Fails to Connect
- Verify VM is accessible: `ping <vm-ip>`
- Check SSH service: `nc -z <vm-ip> 22`
- Ensure initial password/key authentication works

### Docker Installation Issues
- Check internet connectivity on VM
- Verify Docker GPG key download succeeded
- Review Docker service status: `systemctl status docker`

### SSH Key Authentication Problems
- Verify key file permissions (600 for private, 644 for public)
- Check authorized_keys file on target VM
- Test manual key-based connection

### Cloud-Init Not Working
- Check Proxmox cloud-init support is enabled for VM
- Verify YAML syntax is valid
- Review cloud-init logs: `sudo cloud-init status --long`

## Security Notes

- Password authentication is completely disabled after provisioning
- Only key-based SSH access allowed
- Emergency keys provide backup access
- Automatic security updates enabled
- User has sudo privileges but requires proper SSH key authentication
- Docker group membership allows container management without sudo

## Related Documentation

- SSH Key Management: `patterns/networking/ssh-key-management.md`
- SSH Setup Examples: `examples/networking/ssh-homelab-setup.md`
- Docker Patterns: `patterns/docker/`