ProxmoxVE/docs/misc/build.func/BUILD_FUNC_ENVIRONMENT_VARIABLES.md

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
var_fuse	Enable FUSE support	"no"	CT script / Advanced Settings	Container features
var_tun	Enable TUN/TAP support	"no"	CT script / Advanced Settings	Container features
var_nesting	Enable nesting support	"1"	CT script / Advanced Settings	Container features
var_keyctl	Enable keyctl support	"0"	CT script / Advanced Settings	Container features
var_mknod	Allow device node creation	"0"	CT script / Advanced Settings	Container features
var_mount_fs	Allowed filesystem mounts	""	CT script / Advanced Settings	Container features
var_protection	Enable container protection	"no"	CT script / Advanced Settings	Container creation
var_timezone	Container timezone	""	CT script / Advanced Settings	Container creation
var_verbose	Enable verbose output	"no"	Environment / Advanced Settings	Logging
var_ssh	Enable SSH key provisioning	"no"	CT script / Advanced Settings	SSH setup
ENABLE_FUSE	FUSE flag (internal)	"no"	Advanced Settings	Container creation
ENABLE_TUN	TUN/TAP flag (internal)	"no"	Advanced Settings	Container creation
ENABLE_NESTING	Nesting flag (internal)	"1"	Advanced Settings	Container creation
ENABLE_KEYCTL	Keyctl flag (internal)	"0"	Advanced Settings	Container creation
ENABLE_MKNOD	Mknod flag (internal)	"0"	Advanced Settings	Container creation
PROTECT_CT	Protection flag (internal)	"no"	Advanced Settings	Container creation
CT_TIMEZONE	Timezone setting (internal)	""	Advanced Settings	Container creation
VERBOSE	Verbose mode flag	"no"	Environment	Logging
SSH	SSH access flag	"no"	Advanced Settings	SSH setup

APT Cacher Configuration

Variable	Description	Default	Set In	Used In
var_apt_cacher	Enable APT cacher proxy	"no"	CT script / Advanced Settings	Package management
var_apt_cacher_ip	APT cacher server IP	""	CT script / Advanced Settings	Package management
APT_CACHER	APT cacher flag	"no"	Advanced Settings	Container creation
APT_CACHER_IP	APT cacher IP (internal)	""	Advanced Settings	Container creation

GPU Passthrough Variables

Variable	Description	Default	Set In	Used In
var_gpu	Enable GPU passthrough	"no"	CT script / Environment / Advanced Settings	GPU passthrough
ENABLE_GPU	GPU passthrough flag (internal)	"no"	Advanced Settings	Container creation

Note: GPU passthrough is controlled via var_gpu. Apps that benefit from GPU acceleration (media servers, AI/ML, transcoding) have var_gpu=yes as default in their CT scripts.

Apps with GPU enabled by default:

• Media: jellyfin, plex, emby, channels, ersatztv, tunarr, immich
• Transcoding: tdarr, unmanic, fileflows
• AI/ML: ollama, openwebui
• NVR: frigate

Usage Examples:

# Disable GPU for a specific installation
var_gpu=no bash -c "$(curl -fsSL https://...jellyfin.sh)"

# Enable GPU for apps without default GPU support
var_gpu=yes bash -c "$(curl -fsSL https://...debian.sh)"

# Set in default.vars for all apps
echo "var_gpu=yes" >> /usr/local/community-scripts/default.vars

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"