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

9.3 KiB

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:

# 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

# 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

# Enable GPU passthrough
export GPU_APPS="plex,jellyfin,emby"
export var_gpu="intel"
export ENABLE_PRIVILEGED="true"

3. Advanced Network Configuration

# 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

# 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

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

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

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"