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:

./vm-post-install.sh <vm-ip> [ssh-user]

Example:

./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)

# 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:

# 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/