ProxmoxVED/docs/misc/build.func/BUILD_FUNC_ENVIRONMENT_VARIABLES.md
Michel Roegl-Brunner 960fddb9ee
Some checks failed
Bump build.func Revision / bump-revision (push) Has been cancelled
Add docs for all files in /misc
2025-10-10 11:18:59 +02:00

249 lines
9.3 KiB
Markdown

# build.func Environment Variables Reference
## Overview
This document provides a comprehensive reference of all environment variables used in `build.func`, organized by category and usage context.
## Variable Categories
### Core Container Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `APP` | Application name (e.g., "plex", "nextcloud") | - | Environment | Throughout |
| `NSAPP` | Namespace application name | `$APP` | Environment | Throughout |
| `CTID` | Container ID | - | Environment | Container creation |
| `CT_TYPE` | Container type ("install" or "update") | "install" | Environment | Entry point |
| `CT_NAME` | Container name | `$APP` | Environment | Container creation |
### Operating System Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_os` | Operating system selection | "debian" | base_settings() | OS selection |
| `var_version` | OS version | "12" | base_settings() | Template selection |
| `var_template` | Template name | Auto-generated | base_settings() | Template download |
### Resource Configuration Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_cpu` | CPU cores | "2" | base_settings() | Container creation |
| `var_ram` | RAM in MB | "2048" | base_settings() | Container creation |
| `var_disk` | Disk size in GB | "8" | base_settings() | Container creation |
| `DISK_SIZE` | Disk size (alternative) | `$var_disk` | Environment | Container creation |
| `CORE_COUNT` | CPU cores (alternative) | `$var_cpu` | Environment | Container creation |
| `RAM_SIZE` | RAM size (alternative) | `$var_ram` | Environment | Container creation |
### Network Configuration Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_net` | Network interface | "vmbr0" | base_settings() | Network config |
| `var_bridge` | Bridge interface | "vmbr0" | base_settings() | Network config |
| `var_gateway` | Gateway IP | "192.168.1.1" | base_settings() | Network config |
| `var_ip` | Container IP address | - | User input | Network config |
| `var_ipv6` | IPv6 address | - | User input | Network config |
| `var_vlan` | VLAN ID | - | User input | Network config |
| `var_mtu` | MTU size | "1500" | base_settings() | Network config |
| `var_mac` | MAC address | Auto-generated | base_settings() | Network config |
| `NET` | Network interface (alternative) | `$var_net` | Environment | Network config |
| `BRG` | Bridge interface (alternative) | `$var_bridge` | Environment | Network config |
| `GATE` | Gateway IP (alternative) | `$var_gateway` | Environment | Network config |
| `IPV6_METHOD` | IPv6 configuration method | "none" | Environment | Network config |
| `VLAN` | VLAN ID (alternative) | `$var_vlan` | Environment | Network config |
| `MTU` | MTU size (alternative) | `$var_mtu` | Environment | Network config |
| `MAC` | MAC address (alternative) | `$var_mac` | Environment | Network config |
### Storage Configuration Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `var_template_storage` | Storage for templates | - | select_storage() | Template storage |
| `var_container_storage` | Storage for container disks | - | select_storage() | Container storage |
| `TEMPLATE_STORAGE` | Template storage (alternative) | `$var_template_storage` | Environment | Template storage |
| `CONTAINER_STORAGE` | Container storage (alternative) | `$var_container_storage` | Environment | Container storage |
### Feature Flags
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `ENABLE_FUSE` | Enable FUSE support | "true" | base_settings() | Container features |
| `ENABLE_TUN` | Enable TUN/TAP support | "true" | base_settings() | Container features |
| `ENABLE_KEYCTL` | Enable keyctl support | "true" | base_settings() | Container features |
| `ENABLE_MOUNT` | Enable mount support | "true" | base_settings() | Container features |
| `ENABLE_NESTING` | Enable nesting support | "false" | base_settings() | Container features |
| `ENABLE_PRIVILEGED` | Enable privileged mode | "false" | base_settings() | Container features |
| `ENABLE_UNPRIVILEGED` | Enable unprivileged mode | "true" | base_settings() | Container features |
| `VERBOSE` | Enable verbose output | "false" | Environment | Logging |
| `SSH` | Enable SSH key provisioning | "true" | base_settings() | SSH setup |
### GPU Passthrough Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `GPU_APPS` | List of apps that support GPU | - | Environment | GPU detection |
| `var_gpu` | GPU selection | - | User input | GPU passthrough |
| `var_gpu_type` | GPU type (intel/amd/nvidia) | - | detect_gpu_devices() | GPU passthrough |
| `var_gpu_devices` | GPU device list | - | detect_gpu_devices() | GPU passthrough |
### API and Diagnostics Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `DIAGNOSTICS` | Enable diagnostics mode | "false" | Environment | Diagnostics |
| `METHOD` | Installation method | "install" | Environment | Installation flow |
| `RANDOM_UUID` | Random UUID for tracking | - | Environment | Logging |
| `API_TOKEN` | Proxmox API token | - | Environment | API calls |
| `API_USER` | Proxmox API user | - | Environment | API calls |
### Settings Persistence Variables
| Variable | Description | Default | Set In | Used In |
|----------|-------------|---------|---------|---------|
| `SAVE_DEFAULTS` | Save settings as defaults | "false" | User input | Settings persistence |
| `SAVE_APP_DEFAULTS` | Save app-specific defaults | "false" | User input | Settings persistence |
| `DEFAULT_VARS_FILE` | Path to default.vars | "/usr/local/community-scripts/default.vars" | Environment | Settings persistence |
| `APP_DEFAULTS_FILE` | Path to app.vars | "/usr/local/community-scripts/defaults/$APP.vars" | Environment | Settings persistence |
## Variable Precedence Chain
Variables are resolved in the following order (highest to lowest priority):
1. **Hard Environment Variables**: Set before script execution
2. **App-specific .vars file**: `/usr/local/community-scripts/defaults/<app>.vars`
3. **Global default.vars file**: `/usr/local/community-scripts/default.vars`
4. **Built-in defaults**: Set in `base_settings()` function
## Critical Variables for Non-Interactive Use
For silent/non-interactive execution, these variables must be set:
```bash
# Core container settings
export APP="plex"
export CTID="100"
export var_hostname="plex-server"
# OS selection
export var_os="debian"
export var_version="12"
# Resource allocation
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
# Network configuration
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.100"
# Storage selection
export var_template_storage="local"
export var_container_storage="local"
# Feature flags
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
```
## Environment Variable Usage Patterns
### 1. Container Creation
```bash
# Basic container creation
export APP="nextcloud"
export CTID="101"
export var_hostname="nextcloud-server"
export var_os="debian"
export var_version="12"
export var_cpu="2"
export var_ram="2048"
export var_disk="10"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.101"
export var_template_storage="local"
export var_container_storage="local"
```
### 2. GPU Passthrough
```bash
# Enable GPU passthrough
export GPU_APPS="plex,jellyfin,emby"
export var_gpu="intel"
export ENABLE_PRIVILEGED="true"
```
### 3. Advanced Network Configuration
```bash
# VLAN and IPv6 configuration
export var_vlan="100"
export var_ipv6="2001:db8::100"
export IPV6_METHOD="static"
export var_mtu="9000"
```
### 4. Storage Configuration
```bash
# Custom storage locations
export var_template_storage="nfs-storage"
export var_container_storage="ssd-storage"
```
## Variable Validation
The script validates variables at several points:
1. **Container ID validation**: Must be unique and within valid range
2. **IP address validation**: Must be valid IPv4/IPv6 format
3. **Storage validation**: Must exist and support required content types
4. **Resource validation**: Must be within reasonable limits
5. **Network validation**: Must be valid network configuration
## Common Variable Combinations
### Development Container
```bash
export APP="dev-container"
export CTID="200"
export var_hostname="dev-server"
export var_os="ubuntu"
export var_version="22.04"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export ENABLE_NESTING="true"
export ENABLE_PRIVILEGED="true"
```
### Media Server with GPU
```bash
export APP="plex"
export CTID="300"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="6"
export var_ram="8192"
export var_disk="50"
export GPU_APPS="plex"
export var_gpu="nvidia"
export ENABLE_PRIVILEGED="true"
```
### Lightweight Service
```bash
export APP="nginx"
export CTID="400"
export var_hostname="nginx-proxy"
export var_os="alpine"
export var_version="3.18"
export var_cpu="1"
export var_ram="512"
export var_disk="2"
export ENABLE_UNPRIVILEGED="true"
```