mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-02-09 06:43:25 +01:00
33149f3bf8
Documentation updates across guides and function references: - Added var_gpu and var_tun configuration entries to CONFIGURATION_REFERENCE (GPU passthrough and TUN/TAP support), including features and prerequisites. - Fixed repository URLs throughout UNATTENDED_DEPLOYMENTS and examples: replaced community-scripts/ProxmoxVED with community-scripts/ProxmoxVE and updated curl usage to the new paths. - Added an "Advanced Configuration Variables" table and examples (var_os, var_version, var_gpu, var_tun, var_nesting) to UNATTENDED_DEPLOYMENTS; adjusted sample apps, hostnames, and container mappings in batch examples. - Switched API endpoints in API_FUNCTIONS_REFERENCE and API_USAGE_EXAMPLES from http://api.community-scripts.org to https://api.community-scripts.org. - Expanded BUILD_FUNC_FUNCTIONS_REFERENCE with container resource/ID management helper descriptions (validate_container_id, get_valid_container_id, maxkeys_check, get_current_ip, update_motd_ip). - Large edits to TOOLS_FUNC_FUNCTIONS_REFERENCE: renamed/refactored helper signatures and docs (pkg_install -> install_packages_with_retry, pkg_update -> upgrade_packages_with_retry), added new tooling functions (fetch_and_deploy_gh_release, check_for_gh_release, prepare_repository_setup, verify_tool_version) and updated examples and feature notes. - Updated vm/README.md to list additional VM scripts (new and reorganized examples). These are documentation-only changes to clarify configuration options, correct links and endpoints, and expand the reference material for tooling and build helpers.
131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# VM Scripts Documentation (/vm)
|
|
|
|
This directory contains comprehensive documentation for virtual machine creation scripts in the `/vm` directory.
|
|
|
|
## Overview
|
|
|
|
VM scripts (`vm/*.sh`) create full virtual machines (not containers) in Proxmox VE with complete operating systems and cloud-init provisioning.
|
|
|
|
## Documentation Structure
|
|
|
|
VM documentation parallels container documentation but focuses on VM-specific features.
|
|
|
|
## Key Resources
|
|
|
|
- **[misc/cloud-init.func/](../misc/cloud-init.func/)** - Cloud-init provisioning documentation
|
|
- **[CONTRIBUTION_GUIDE.md](../CONTRIBUTION_GUIDE.md)** - Contribution workflow
|
|
- **[EXIT_CODES.md](../EXIT_CODES.md)** - Exit code reference
|
|
|
|
## VM Creation Flow
|
|
|
|
```
|
|
vm/OsName-vm.sh (host-side)
|
|
│
|
|
├─ Calls: build.func (orchestrator)
|
|
│
|
|
├─ Variables: var_cpu, var_ram, var_disk, var_os
|
|
│
|
|
├─ Uses: cloud-init.func (provisioning)
|
|
│
|
|
└─ Creates: KVM/QEMU VM
|
|
│
|
|
└─ Boots with: Cloud-init config
|
|
│
|
|
├─ System phase
|
|
├─ Config phase
|
|
└─ Final phase
|
|
```
|
|
|
|
## Available VM Scripts
|
|
|
|
See `/vm` directory for all VM creation scripts. Examples:
|
|
|
|
- `ubuntu2504-vm.sh` - Ubuntu 25.04 VM (Latest)
|
|
- `ubuntu2404-vm.sh` - Ubuntu 24.04 VM (LTS)
|
|
- `debian-13-vm.sh` - Debian 13 VM (Trixie)
|
|
- `archlinux-vm.sh` - Arch Linux VM
|
|
- `haos-vm.sh` - Home Assistant OS
|
|
- `mikrotik-routeros.sh` - MikroTik RouterOS
|
|
- `openwrt-vm.sh` - OpenWrt VM
|
|
- `opnsense-vm.sh` - OPNsense firewall
|
|
- `umbrel-os-vm.sh` - Umbrel OS VM
|
|
- And 10+ more...
|
|
|
|
## VM vs Container
|
|
|
|
| Feature | VM | Container |
|
|
|---------|:---:|:---:|
|
|
| Isolation | Full | Lightweight |
|
|
| Boot Time | Slower | Instant |
|
|
| Resource Use | Higher | Lower |
|
|
| Use Case | Full OS | Single app |
|
|
| Init System | systemd/etc | cloud-init |
|
|
| Storage | Disk image | Filesystem |
|
|
|
|
## Quick Start
|
|
|
|
To understand VM creation:
|
|
|
|
1. Read: [misc/cloud-init.func/README.md](../misc/cloud-init.func/README.md)
|
|
2. Study: A similar existing script in `/vm`
|
|
3. Understand cloud-init configuration
|
|
4. Test locally
|
|
5. Submit PR
|
|
|
|
## Contributing a New VM
|
|
|
|
1. Create `vm/osname-vm.sh`
|
|
2. Use cloud-init for provisioning
|
|
3. Follow VM script template
|
|
4. Test VM creation and boot
|
|
5. Submit PR
|
|
|
|
## Cloud-Init Provisioning
|
|
|
|
VMs are provisioned using cloud-init:
|
|
|
|
```yaml
|
|
#cloud-config
|
|
hostname: myvm
|
|
timezone: UTC
|
|
|
|
packages:
|
|
- curl
|
|
- wget
|
|
|
|
users:
|
|
- name: ubuntu
|
|
ssh_authorized_keys:
|
|
- ssh-rsa AAAAB3...
|
|
|
|
bootcmd:
|
|
- echo "VM starting..."
|
|
|
|
runcmd:
|
|
- apt-get update
|
|
- apt-get upgrade -y
|
|
```
|
|
|
|
## Common VM Operations
|
|
|
|
- **Create VM with cloud-init** → [misc/cloud-init.func/](../misc/cloud-init.func/)
|
|
- **Configure networking** → Cloud-init YAML documentation
|
|
- **Setup SSH keys** → [misc/cloud-init.func/CLOUD_INIT_FUNC_USAGE_EXAMPLES.md](../misc/cloud-init.func/CLOUD_INIT_FUNC_USAGE_EXAMPLES.md)
|
|
- **Debug VM creation** → [EXIT_CODES.md](../EXIT_CODES.md)
|
|
|
|
## VM Templates
|
|
|
|
Common VM templates available:
|
|
|
|
- **Ubuntu LTS** - Latest stable Ubuntu
|
|
- **Debian Stable** - Latest stable Debian
|
|
- **OPNsense** - Network security platform
|
|
- **Home Assistant** - Home automation
|
|
- **Kubernetes** - K3s lightweight cluster
|
|
- **Proxmox Backup** - Backup server
|
|
|
|
---
|
|
|
|
**Last Updated**: December 2025
|
|
**Maintainers**: community-scripts team
|