Proxmox/ProxmoxVE
1
0
Fork 1
mirror of https://github.com/community-scripts/ProxmoxVE.git synced 2026-02-05 21:03:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: add GPU/TUN, update endpoints & tool refs

Browse Source 
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.
This commit is contained in:
CanbiZ (MickLesk)
2026-02-05 14:18:49 +01:00
parent b87fddbf6a
commit 33149f3bf8
7 changed files with 191 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/guides/CONFIGURATION_REFERENCE.md
View File

@@ -539,6 +539,50 @@ var_nesting=0 # Nested containers disabled
---
### var_gpu
**Type:** Boolean/Toggle
**Options:** `yes` or `no`
**Default:** `no`
**Description:** Enable GPU passthrough for the container.
```bash
var_gpu=yes # Enable GPU passthrough (auto-detect)
var_gpu=no # Disable GPU passthrough (default)
```
**Features enabled:**
- Auto-detects Intel (QuickSync), NVIDIA, and AMD GPUs
- Passes through `/dev/dri` and render nodes
- Configures appropriate container permissions
- Crucial for media servers (Plex, Jellyfin, Immich)
**Prerequisites:**
- Host drivers installed correctly
- Hardware present and visible to Proxmox
- IOMMU enabled (for some configurations)
---
### var_tun
**Type:** Boolean/Toggle
**Options:** `yes` or `no`
**Default:** `no`
**Description:** Enable TUN/TAP device support.
```bash
var_tun=yes # Enable TUN/TAP support
var_tun=no # Disable TUN/TAP support (default)
```
**Required for:**
- VPN software (WireGuard, OpenVPN)
- Network tunneling (Tailscale, ZeroTier)
- Custom network bridges
---
### var_keyctl
**Type:** Boolean (0 or 1)

66
docs/guides/UNATTENDED_DEPLOYMENTS.md
View File

@@ -57,7 +57,7 @@ pveversion
### 2. Network Connectivity
```bash
# Test GitHub access
curl -I https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/debian.sh
curl -I https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh
# Test internet connectivity
ping -c 1 1.1.1.1
@@ -108,6 +108,8 @@ var_cpu=4 \
var_ram=4096 \
var_disk=30 \
var_hostname=production-app \
var_os=debian \
var_version=13 \
var_brg=vmbr0 \
var_net=dhcp \
var_ipv6_method=none \
@@ -117,7 +119,7 @@ var_nesting=1 \
var_tags=production,automated \
var_protection=yes \
var_verbose=no \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/debian.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"
echo "✓ Container deployed successfully"
```
@@ -151,7 +153,7 @@ var_gateway=192.168.1.1 \
**Step 1: Create defaults once (interactive)**
```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/pihole.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"
# Select "Advanced Settings" → Configure → Save as "App Defaults"
```
@@ -161,10 +163,30 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
# deploy-with-defaults.sh
# App defaults are loaded automatically
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/pihole.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"
# Script will use /usr/local/community-scripts/defaults/pihole.vars
```
### Advanced Configuration Variables
Beyond the basic resource settings, you can control advanced container features:
| Variable | Description | Options |
|----------|-------------|---------|
| `var_os` | Operating system template | `debian`, `ubuntu`, `alpine` |
| `var_version` | OS version | `12`, `13` (Debian), `22.04`, `24.04` (Ubuntu) |
| `var_gpu` | Enable GPU passthrough | `yes`, `no` (Default: `no`) |
| `var_tun` | Enable TUN/TAP device | `yes`, `no` (Default: `no`) |
| `var_nesting` | Enable nesting | `1`, `0` (Default: `1`) |
**Example with GPU and TUN:**
```bash
var_gpu=yes \
var_tun=yes \
var_hostname=transcoder \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/plex.sh)"
```
---
## Batch Deployments
@@ -177,14 +199,14 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
#!/bin/bash
# batch-deploy-simple.sh
apps=("debian" "ubuntu" "alpine")
apps=("thingsboard" "qui" "flatnotes")
for app in "${apps[@]}"; do
echo "Deploying $app..."
var_hostname="$app-container" \
var_hostname="$app-server" \
var_cpu=2 \
var_ram=2048 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${app}.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${app}.sh)"
echo "✓ $app deployed"
sleep 5 # Wait between deployments
@@ -199,8 +221,8 @@ done
declare -A CONTAINERS=(
["pihole"]="2:1024:8:vmbr0:dns,network"
["homeassistant"]="4:4096:20:vmbr0:automation,ha"
["docker"]="6:8192:50:vmbr1:containers,docker"
["qui"]="4:4096:20:vmbr0:media,ui"
["thingsboard"]="6:8192:50:vmbr1:iot,industrial"
["nginx"]="2:2048:10:vmbr0:webserver,proxy"
)
@@ -228,7 +250,7 @@ for app in "${!CONTAINERS[@]}"; do
var_ipv6_method=none \
var_ssh=yes \
var_tags="$tags,automated" \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${app}.sh)" 2>&1 | tee "deploy-${app}.log"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${app}.sh)" 2>&1 | tee "deploy-${app}.log"
if [ $? -eq 0 ]; then
echo "✓ $app deployed successfully"
@@ -263,7 +285,7 @@ deploy_container() {
var_disk="$disk" \
var_hostname="$app" \
var_net=dhcp \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${app}.sh)" \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${app}.sh)" \
&> "deploy-${app}.log"
echo "[$app] ✓ Completed"
@@ -294,7 +316,7 @@ echo "All deployments complete!"
```yaml
---
# playbook-proxmox.yml
- name: Deploy ProxmoxVED Containers
- name: Deploy ProxmoxVE Containers
hosts: proxmox_hosts
become: yes
tasks:
@@ -308,7 +330,7 @@ echo "All deployments complete!"
var_net=dhcp \
var_ssh=yes \
var_tags=ansible,automated \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/debian.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"
args:
executable: /bin/bash
register: deploy_result
@@ -365,7 +387,7 @@ echo "All deployments complete!"
var_ssh=yes \
var_ssh_authorized_key="{{ ssh_key }}" \
var_tags="{{ item.tags }},ansible" \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/{{ item.name }}.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/{{ item.name }}.sh)"
args:
executable: /bin/bash
loop: "{{ containers }}"
@@ -417,7 +439,7 @@ resource "null_resource" "deploy_container" {
"var_disk=${each.value.disk}",
"var_hostname=${each.key}",
"var_net=dhcp",
"bash -c \"$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${each.value.template}.sh)\""
"bash -c \"$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${each.value.template}.sh)\""
]
connection {
@@ -498,7 +520,7 @@ jobs:
var_net=dhcp \
var_ssh=yes \
var_tags=ci-cd,automated \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${{ github.event.inputs.container_type }}.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${{ github.event.inputs.container_type }}.sh)"
- name: Notify deployment status
if: success()
@@ -532,7 +554,7 @@ deploy_container:
var_hostname=gitlab-ci-container \
var_net=dhcp \
var_tags=gitlab-ci,automated \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/debian.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"
EOF
only:
- main
@@ -564,7 +586,7 @@ deploy_container() {
var_hostname="$HOSTNAME" \
var_net=dhcp \
var_ssh=yes \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${APP}.sh)" 2>&1 | tee deploy.log
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${APP}.sh)" 2>&1 | tee deploy.log
return ${PIPESTATUS[0]}
}
@@ -656,7 +678,7 @@ deploy() {
var_hostname="$HOSTNAME" \
var_cpu=4 \
var_ram=4096 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${APP}.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${APP}.sh)"
return $?
}
@@ -759,7 +781,7 @@ deploy_secure() {
var_protection=yes \
var_tags=production,secure,automated \
var_verbose=no \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${APP}.sh)" 2>&1 | tee -a "$LOG_FILE"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${APP}.sh)" 2>&1 | tee -a "$LOG_FILE"
if [ ${PIPESTATUS[0]} -eq 0 ]; then
log "✓ Deployment successful"
@@ -824,7 +846,7 @@ SSH_KEYS=$(load_ssh_keys)
var_ssh=yes \
var_ssh_authorized_key="$SSH_KEYS" \
var_hostname=multi-key-server \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/debian.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"
```
---
@@ -903,7 +925,7 @@ deploy_from_config() {
var_ssh=yes \
var_tags="$tags,automated" \
var_protection=yes \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/${app}.sh)"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${app}.sh)"
if [ $? -eq 0 ]; then
log_success "Deployed: $name"

6
docs/misc/api.func/API_FUNCTIONS_REFERENCE.md
View File

@@ -56,7 +56,7 @@ get_error_description 255 # "Unknown critical error, often due to missing perm
- `DIAGNOSTICS` must be set to "yes"
- `RANDOM_UUID` must be set and not empty
**API Endpoint**: `http://api.community-scripts.org/dev/upload`
**API Endpoint**: `https://api.community-scripts.org/dev/upload`
**JSON Payload Structure**:
```json
@@ -110,7 +110,7 @@ post_to_api
- `curl` command must be available
- `RANDOM_UUID` must be set and not empty
**API Endpoint**: `http://api.community-scripts.org/dev/upload`
**API Endpoint**: `https://api.community-scripts.org/dev/upload`
**JSON Payload Structure**:
```json
@@ -167,7 +167,7 @@ post_to_api_vm
- `RANDOM_UUID` must be set and not empty
- POST_UPDATE_DONE must be false (prevents duplicates)
**API Endpoint**: `http://api.community-scripts.org/dev/upload/updatestatus`
**API Endpoint**: `https://api.community-scripts.org/dev/upload/updatestatus`
**JSON Payload Structure**:
```json

2
docs/misc/api.func/API_USAGE_EXAMPLES.md
View File

@@ -461,7 +461,7 @@ check_api_health() {
echo "Error description test: $test_error"
# Test API connectivity (without sending data)
local api_url="http://api.community-scripts.org/dev/upload"
local api_url="https://api.community-scripts.org/dev/upload"
if curl -s --head "$api_url" >/dev/null 2>&1; then
echo "API endpoint is reachable"
else

28
docs/misc/build.func/BUILD_FUNC_FUNCTIONS_REFERENCE.md
View File

@@ -438,6 +438,34 @@ default_var_settings() # Save global defaults
maybe_offer_save_app_defaults() # Save app defaults
```
### Container Resource & ID Management
#### `validate_container_id()`
**Purpose**: Validates if a container ID is available for use.
**Parameters**: `ctid` (Integer)
**Returns**: `0` if available, `1` if already in use or invalid.
**Description**: Checks for existing config files in `/etc/pve/lxc/` or `/etc/pve/qemu-server/`, and verifies LVM logical volumes.
#### `get_valid_container_id()`
**Purpose**: Returns the next available, unused container ID.
**Parameters**: `suggested_id` (Optional)
**Returns**: A valid container ID string.
**Description**: If the suggested ID is taken, it increments until it finds an available one.
#### `maxkeys_check()`
**Purpose**: Ensures host kernel parameters support high numbers of keys (required for some apps).
**Parameters**: None
**Description**: Checks and optionally updates `kernel.keys.maxkeys` and `kernel.keys.maxbytes`.
#### `get_current_ip()`
**Purpose**: Retrieves the current IP address of the container.
**Parameters**: `ctid` (Integer)
**Returns**: IP address string.
#### `update_motd_ip()`
**Purpose**: Updates the Message of the Day (MOTD) file with the container's IP.
**Parameters**: None
## Function Error Handling
### Validation Functions

131
docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md
View File

@@ -60,13 +60,13 @@ Complete alphabetical reference of all functions in tools.func with parameters,
## Core Functions
### pkg_install()
### install_packages_with_retry()
Install one or more packages safely with automatic retry logic and error handling.
Install one or more packages safely with automatic retry logic (3 attempts), APT refresh, and lock handling.
**Signature**:
```bash
pkg_install PACKAGE1 [PACKAGE2 ...]
install_packages_with_retry PACKAGE1 [PACKAGE2 ...]
```
**Parameters**:
@@ -74,112 +74,107 @@ pkg_install PACKAGE1 [PACKAGE2 ...]
**Returns**:
- `0` - All packages installed successfully
- `1` - Installation failed after retries
- `1` - Installation failed after all retries
**Features**:
- Automatically sets `DEBIAN_FRONTEND=noninteractive`
- Handles DPKG lock errors with `dpkg --configure -a`
- Retries on transient network or APT failures
**Example**:
```bash
install_packages_with_retry curl wget git
```
---
### upgrade_packages_with_retry()
Upgrades installed packages with the same robust retry logic as the installation helper.
**Signature**:
```bash
upgrade_packages_with_retry
```
**Returns**:
- `0` - Upgrade successful
- `1` - Upgrade failed
---
### fetch_and_deploy_gh_release()
The primary tool for downloading and installing software from GitHub Releases. Supports binaries, tarballs, and Debian packages.
**Signature**:
```bash
fetch_and_deploy_gh_release APPREPO TYPE [VERSION] [DEST] [ASSET_PATTERN]
```
**Parameters**:
- `APPREPO`: GitHub repository (e.g., `owner/repo`)
- `TYPE`: Asset type (`binary`, `tarball`, `prebuild`, `singlefile`, `binary_tarball`)
- `VERSION`: Specific tag or `latest` (Default: `latest`)
- `DEST`: Target directory (Default: `/opt/$APP`)
- `ASSET_PATTERN`: Regex or string pattern to match the release asset
**Environment Variables**:
- `$STD` - Output suppression (`silent` or empty)
- `CLEAN_INSTALL=1`: Removes the destination directory before extracting.
**Example**:
```bash
pkg_install curl wget git
fetch_and_deploy_gh_release "muesli/duf" "binary" "latest" "/opt/duf" "duf_.*_linux_amd64.tar.gz"
```
---
### pkg_update()
### check_for_gh_release()
Update package lists with automatic retry logic for network failures.
Checks if a newer version is available on GitHub compared to the installed version.
**Signature**:
```bash
pkg_update
check_for_gh_release APP REPO
```
**Parameters**: None
**Returns**:
- `0` - Package lists updated
- `1` - Failed after 3 retries
**Example**:
```bash
pkg_update
if check_for_gh_release "nodejs" "nodesource/distributions"; then
# update logic
fi
```
---
### pkg_remove()
### prepare_repository_setup()
Remove packages completely including dependencies.
Performs safe repository preparation by cleaning up old files, keyrings, and ensuring the APT system is in a working state.
**Signature**:
```bash
pkg_remove PACKAGE1 [PACKAGE2 ...]
prepare_repository_setup REPO_NAME [REPO_NAME2 ...]
```
**Parameters**:
- `PACKAGE1, PACKAGE2, ...` - Package names to remove
**Returns**:
- `0` - Packages removed
- `1` - Removal failed
**Example**:
```bash
pkg_remove old-package outdated-tool
prepare_repository_setup "mariadb" "mysql"
```
---
### setup_deb822_repo()
### verify_tool_version()
Add repository in modern deb822 format (recommended over legacy format).
Validates if the installed major version matches the expected version.
**Signature**:
```bash
setup_deb822_repo REPO_URL NAME DIST MAIN_URL RELEASE
verify_tool_version NAME EXPECTED INSTALLED
```
**Parameters**:
- `REPO_URL` - URL to GPG key (e.g., https://example.com/key.gpg)
- `NAME` - Repository name (e.g., "nodejs")
- `DIST` - Distribution (jammy, bookworm, etc.)
- `MAIN_URL` - Main repository URL
- `RELEASE` - Release type (main, testing, etc.)
**Returns**:
- `0` - Repository added successfully
- `1` - Repository setup failed
**Example**:
```bash
setup_deb822_repo \
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
"nodejs" \
"jammy" \
"https://deb.nodesource.com/node_20.x" \
"main"
```
---
### cleanup_repo_metadata()
Clean up GPG keys and old repository configurations.
**Signature**:
```bash
cleanup_repo_metadata
```
**Parameters**: None
**Returns**:
- `0` - Cleanup complete
**Example**:
```bash
cleanup_repo_metadata
verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"
```
---

15
docs/vm/README.md
View File

@@ -40,14 +40,15 @@ vm/OsName-vm.sh (host-side)
See `/vm` directory for all VM creation scripts. Examples:
- `ubuntu2404-vm.sh` - Ubuntu 24.04 VM
- `ubuntu2204-vm.sh` - Ubuntu 22.04 VM
- `debian-vm.sh` - Debian VM
- `debian-13-vm.sh` - Debian 13 VM
- `opnsense-vm.sh` - OPNsense firewall
- `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
- `unifi-os-vm.sh` - Unifi Dream Machine
- `k3s-vm.sh` - Kubernetes lightweight
- `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