11 KiB
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
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 invalidcheck_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
- Configuration Errors: Invalid settings or conflicts
- Resource Errors: Insufficient resources or conflicts
- Network Errors: Invalid network configuration
- Storage Errors: Storage not available or invalid
- GPU Errors: GPU configuration failures
- Container Creation Errors: LXC creation failures