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

build.func Functions Reference

Overview

This document provides a comprehensive reference of all functions in build.func, organized alphabetically with detailed descriptions, parameters, and usage information.

Function Categories

Initialization Functions

start()

Purpose: Main entry point when build.func is sourced or executed Parameters: None Returns: None Side Effects:

• Detects execution context (Proxmox host vs container)
• Captures hard environment variables
• Sets CT_TYPE based on context
• Routes to appropriate workflow (install_script or update_script) Dependencies: None Environment Variables Used: CT_TYPE, APP, CTID

variables()

Purpose: Load and resolve all configuration variables using precedence chain Parameters: None Returns: None Side Effects:

• Loads app-specific .vars file
• Loads global default.vars file
• Applies variable precedence chain
• Sets all configuration variables Dependencies: base_settings() Environment Variables Used: All configuration variables

base_settings()

Purpose: Set built-in default values for all configuration variables Parameters: None Returns: None Side Effects: Sets default values for all variables Dependencies: None Environment Variables Used: All configuration variables

UI and Menu Functions

install_script()

Purpose: Main installation workflow coordinator Parameters: None Returns: None Side Effects:

• Displays installation mode selection menu
• Coordinates the entire installation process
• Handles user interaction and validation Dependencies: variables(), build_container(), default_var_settings() Environment Variables Used: APP, CTID, var_hostname

advanced_settings()

Purpose: Provide advanced configuration options via whiptail menus Parameters: None Returns: None Side Effects:

• Displays whiptail menus for configuration
• Updates configuration variables based on user input
• Validates user selections Dependencies: select_storage(), detect_gpu_devices() Environment Variables Used: All configuration variables

settings_menu()

Purpose: Display and handle settings configuration menu Parameters: None Returns: None Side Effects: Updates configuration variables Dependencies: advanced_settings() Environment Variables Used: All configuration variables

Storage Functions

select_storage()

Purpose: Handle storage selection for templates and containers Parameters: None Returns: None Side Effects:

• Resolves storage preselection
• Prompts user for storage selection if needed
• Validates storage availability
• Sets var_template_storage and var_container_storage Dependencies: resolve_storage_preselect(), choose_and_set_storage_for_file() Environment Variables Used: var_template_storage, var_container_storage, TEMPLATE_STORAGE, CONTAINER_STORAGE

resolve_storage_preselect()

Purpose: Resolve preselected storage options Parameters:

• storage_type: Type of storage (template or container) Returns: Storage name if valid, empty if invalid Side Effects: Validates storage availability Dependencies: None Environment Variables Used: var_template_storage, var_container_storage

choose_and_set_storage_for_file()

Purpose: Interactive storage selection via whiptail Parameters:

• storage_type: Type of storage (template or container)
• content_type: Content type (vztmpl or rootdir) Returns: None Side Effects:
• Displays whiptail menu
• Updates storage variables
• Validates selection Dependencies: None Environment Variables Used: var_template_storage, var_container_storage

Container Creation Functions

build_container()

Purpose: Validate settings and prepare container creation Parameters: None Returns: None Side Effects:

• Validates all configuration
• Checks for conflicts
• Prepares container configuration
• Calls create_lxc_container() Dependencies: create_lxc_container() Environment Variables Used: All configuration variables

create_lxc_container()

Purpose: Create the actual LXC container Parameters: None Returns: None Side Effects:

• Creates LXC container with basic configuration
• Configures network settings
• Sets up storage and mount points
• Configures features (FUSE, TUN, etc.)
• Sets resource limits
• Configures startup options
• Starts container Dependencies: configure_gpu_passthrough(), fix_gpu_gids() Environment Variables Used: All configuration variables

GPU and Hardware Functions

detect_gpu_devices()

Purpose: Detect available GPU hardware on the system Parameters: None Returns: None Side Effects:

• Scans for Intel, AMD, and NVIDIA GPUs
• Updates var_gpu_type and var_gpu_devices
• Determines GPU capabilities Dependencies: None Environment Variables Used: var_gpu_type, var_gpu_devices, GPU_APPS

configure_gpu_passthrough()

Purpose: Configure GPU passthrough for the container Parameters: None Returns: None Side Effects:

• Adds GPU device entries to container config
• Configures proper device permissions
• Sets up device mapping
• Updates /etc/pve/lxc/.conf Dependencies: detect_gpu_devices() Environment Variables Used: var_gpu, var_gpu_type, var_gpu_devices, CTID

fix_gpu_gids()

Purpose: Fix GPU group IDs after container creation Parameters: None Returns: None Side Effects:

• Updates GPU group IDs in container
• Ensures proper GPU access permissions
• Configures video and render groups Dependencies: configure_gpu_passthrough() Environment Variables Used: CTID, var_gpu_type

SSH Configuration Functions

configure_ssh_settings()

Purpose: Interactive SSH key and access configuration wizard Parameters:

• step_info (optional): Step indicator string (e.g., "Step 17/19") for consistent dialog headers Returns: None Side Effects:
• Creates temporary file for SSH keys
• Discovers and presents available SSH keys from host
• Allows manual key entry or folder/glob scanning
• Sets SSH variable to "yes" or "no" based on user selection
• Sets SSH_AUTHORIZED_KEY if manual key provided
• Populates SSH_KEYS_FILE with selected keys Dependencies: ssh_discover_default_files(), ssh_build_choices_from_files() Environment Variables Used: SSH, SSH_AUTHORIZED_KEY, SSH_KEYS_FILE

SSH Key Source Options:

1. found - Select from auto-detected host keys
2. manual - Paste a single public key
3. folder - Scan custom folder or glob pattern
4. none - No SSH keys

Note: The "Enable root SSH access?" dialog is always shown, regardless of whether SSH keys or password are configured. This ensures users can always enable SSH access even with automatic login.

ssh_discover_default_files()

Purpose: Discover SSH public key files on the host system Parameters: None Returns: Array of discovered key file paths Side Effects: Scans common SSH key locations Dependencies: None Environment Variables Used: var_ssh_import_glob

ssh_build_choices_from_files()

Purpose: Build whiptail checklist choices from SSH key files Parameters:

• Array of file paths to process Returns: None Side Effects:
• Sets CHOICES array for whiptail checklist
• Sets COUNT variable with number of keys found
• Creates MAPFILE for key tag to content mapping Dependencies: None Environment Variables Used: CHOICES, COUNT, MAPFILE

Settings Persistence Functions

default_var_settings()

Purpose: Offer to save current settings as defaults Parameters: None Returns: None Side Effects:

• Prompts user to save settings
• Saves to default.vars file
• Saves to app-specific .vars file Dependencies: maybe_offer_save_app_defaults() Environment Variables Used: All configuration variables

maybe_offer_save_app_defaults()

Purpose: Offer to save app-specific defaults Parameters: None Returns: None Side Effects:

• Prompts user to save app-specific settings
• Saves to app.vars file
• Updates app-specific configuration Dependencies: None Environment Variables Used: APP, SAVE_APP_DEFAULTS

Utility Functions

validate_settings()

Purpose: Validate all configuration settings Parameters: None Returns: 0 if valid, 1 if invalid Side Effects:

• Checks for configuration conflicts
• Validates resource limits
• Validates network configuration
• Validates storage configuration Dependencies: None Environment Variables Used: All configuration variables

check_conflicts()

Purpose: Check for configuration conflicts Parameters: None Returns: 0 if no conflicts, 1 if conflicts found Side Effects:

• Checks for conflicting settings
• Validates resource allocation
• Checks network configuration Dependencies: None Environment Variables Used: All configuration variables

cleanup_on_error()

Purpose: Clean up resources on error Parameters: None Returns: None Side Effects:

• Removes partially created containers
• Cleans up temporary files
• Resets configuration Dependencies: None Environment Variables Used: CTID

Function Call Flow

Main Installation Flow

start()
├── variables()
│   ├── base_settings()
│   ├── Load app.vars
│   └── Load default.vars
├── install_script()
│   ├── advanced_settings()
│   │   ├── select_storage()
│   │   │   ├── resolve_storage_preselect()
│   │   │   └── choose_and_set_storage_for_file()
│   │   └── detect_gpu_devices()
│   ├── build_container()
│   │   ├── validate_settings()
│   │   ├── check_conflicts()
│   │   └── create_lxc_container()
│   │       ├── configure_gpu_passthrough()
│   │       └── fix_gpu_gids()
│   └── default_var_settings()
│       └── maybe_offer_save_app_defaults()

Error Handling Flow

Error Detection
├── validate_settings()
│   └── check_conflicts()
├── Error Handling
│   └── cleanup_on_error()
└── Exit with error code

Function Dependencies

Core Dependencies

• start() → install_script() → build_container() → create_lxc_container()
• variables() → base_settings()
• advanced_settings() → select_storage() → detect_gpu_devices()

Storage Dependencies

• select_storage() → resolve_storage_preselect()
• select_storage() → choose_and_set_storage_for_file()

GPU Dependencies

• configure_gpu_passthrough() → detect_gpu_devices()
• fix_gpu_gids() → configure_gpu_passthrough()

Settings Dependencies

• default_var_settings() → maybe_offer_save_app_defaults()

Function Usage Examples

Basic Container Creation

# Set required variables
export APP="plex"
export CTID="100"
export var_hostname="plex-server"

# Call main functions
start()  # Entry point
# → variables()  # Load configuration
# → install_script()  # Main workflow
# → build_container()  # Create container
# → create_lxc_container()  # Actual creation

Advanced Configuration

# Set advanced variables
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"

# Call advanced functions
advanced_settings()  # Interactive configuration
# → select_storage()  # Storage selection
# → detect_gpu_devices()  # GPU detection

GPU Passthrough

# Enable GPU passthrough
export GPU_APPS="plex"
export var_gpu="nvidia"

# Call GPU functions
detect_gpu_devices()  # Detect hardware
configure_gpu_passthrough()  # Configure passthrough
fix_gpu_gids()  # Fix permissions

Settings Persistence

# Save settings as defaults
export SAVE_DEFAULTS="true"
export SAVE_APP_DEFAULTS="true"

# Call persistence functions
default_var_settings()  # Save global defaults
maybe_offer_save_app_defaults()  # Save app defaults

Function Error Handling

Validation Functions

• validate_settings(): Returns 0 for valid, 1 for invalid
• check_conflicts(): Returns 0 for no conflicts, 1 for conflicts

Error Recovery

• cleanup_on_error(): Cleans up on any error
• Error codes are propagated up the call stack
• Critical errors cause script termination

Error Types

1. Configuration Errors: Invalid settings or conflicts
2. Resource Errors: Insufficient resources or conflicts
3. Network Errors: Invalid network configuration
4. Storage Errors: Storage not available or invalid
5. GPU Errors: GPU configuration failures
6. Container Creation Errors: LXC creation failures