Skip to main content
The Proxmox VE Helper Scripts architecture uses 10 specialized function libraries that work together to create and manage LXC containers and VMs. Each library has a specific purpose and integration point.

​
Core Libraries

​
build.func

LXC Container Build & Configuration The main orchestrator for Proxmox LXC container creation. This is the heart of the container creation workflow.
  • Variable initialization and defaults management
  • Container creation and resource allocation
  • Storage selection and validation
  • Advanced configuration wizard (19 steps)
  • User defaults and app-specific defaults loading
  • Installation mode routing (Default, Advanced, Edit)
  • variables() - Initialize core variables (NSAPP, SESSION_ID, EXECUTION_ID)
  • install_script() - Main entry point and mode selection
  • build_container() - Create and configure the LXC container
  • advanced_settings() - Interactive configuration wizard
  • base_settings() - Apply built-in and user defaults
  • load_vars_file() - Safe configuration file parsing
  • default_var_settings() - Load user global defaults
  • maybe_offer_save_app_defaults() - Save settings for future use
  • storage_selector() - Interactive storage selection
  • validate_container_id() - Cluster-wide CTID validation
  • Sources: api.func, core.func, error_handler.func
  • Called by: CT creation scripts (ct/<app>.sh)
  • Calls into: Container install scripts via pct exec
Location: misc/build.func

​
core.func

System Utilities & Foundation Provides essential utility functions used across all scripts including colors, messaging, validation checks, and execution helpers.
  • Terminal color codes and formatting
  • Standardized message output (msg_info, msg_ok, msg_error)
  • System validation (root check, PVE check, architecture check)
  • Silent/verbose execution modes
  • Spinner animations for long-running operations
  • Development mode parsing
  • load_functions() - Initialize all utility groups
  • color() - Set ANSI color codes
  • msg_info() - Display info message with spinner
  • msg_ok() - Display success message
  • msg_error() - Display error message
  • msg_warn() - Display warning message
  • root_check() - Verify root privileges
  • pve_check() - Verify Proxmox VE environment
  • arch_check() - Verify supported architecture
  • parse_dev_mode() - Parse development mode flags
  • silent() - Execute command with output suppression
  • spinner() - Animated loading indicator
  • Sourced by: ALL scripts (first library loaded)
  • No dependencies (foundation library)
  • Provides: Global variables and functions used everywhere
Location: misc/core.func

​
error_handler.func

Error Handling & Signal Management Comprehensive error handling and signal trapping to ensure proper cleanup and telemetry reporting.
  • Exit code explanations (150+ codes mapped)
  • Error handler with detailed logging
  • Signal handlers (EXIT, INT, TERM, HUP)
  • Orphaned container cleanup
  • Telemetry failure reporting
  • Log collection and display
  • catch_errors() - Initialize error handling and traps
  • error_handler() - Main error handler (ERR trap)
  • explain_exit_code() - Map exit code to description
  • on_exit() - EXIT trap (cleanup and orphan detection)
  • on_interrupt() - SIGINT handler (Ctrl+C)
  • on_terminate() - SIGTERM handler (kill)
  • on_hangup() - SIGHUP handler (SSH disconnect)
  • _send_abort_telemetry() - Report failure to API
  • _stop_container_if_installing() - Stop orphaned containers
  • 1-10: Generic shell errors
  • 4-95: curl/wget errors
  • 100-102: APT/DPKG errors
  • 103-123: Script validation & setup
  • 124-146: Signals and timeouts
  • 150-154: Systemd/service errors
  • 160-162: Python/pip errors
  • 170-193: Database errors (PostgreSQL, MySQL, MongoDB)
  • 200-231: Proxmox custom codes
  • 232-238: Tools & addon scripts
  • 239-249: Node.js/npm errors
  • 250-254: Application install/update errors
Location: misc/error_handler.func

​
api.func

Telemetry & Diagnostics API Handles anonymous telemetry reporting to help improve script reliability and track installation success rates.
  • Container/VM creation statistics
  • Installation success/failure tracking
  • Error code categorization and reporting
  • Repository source detection
  • Privacy-respecting anonymous telemetry
  • post_to_api() - Report LXC container creation start
  • post_to_api_vm() - Report VM creation start
  • post_update_to_api() - Update installation status
  • detect_repo_source() - Identify script source (ProxmoxVE/ProxmoxVED/external)
  • categorize_error() - Map exit code to error category
  • get_error_description() - Build error context string
  • Only anonymous statistics (no personal data)
  • User can opt-out via DIAGNOSTICS=no
  • Random UUID for session tracking only
  • Data retention: 30 days
  • No IP addresses or hostnames collected
Telemetry URL: https://telemetry.community-scripts.org/telemetry Location: misc/api.func

​
Installation & Setup Libraries

​
install.func

Container Installation Workflow Executes inside LXC containers after creation to perform initial setup and configuration.
  • Network connectivity verification (IPv4/IPv6)
  • OS updates and package installation
  • DNS resolution checks
  • MOTD and SSH configuration
  • Container customization and auto-login
  • setting_up_container() - Verify network connectivity
  • network_check() - Comprehensive IPv4/IPv6 internet check
  • update_os() - Update container OS packages
  • motd_ssh() - Configure MOTD and SSH access
  • customize() - Apply container customizations
  • cleanup_lxc() - Remove unnecessary packages
  • verb_ip6() - Configure IPv6 settings
  • post_progress_to_api() - Report installation progress
IPv4 DNS Servers Tested:
  • 1.1.1.1 (Cloudflare)
  • 8.8.8.8 (Google)
  • 9.9.9.9 (Quad9)
IPv6 DNS Servers Tested:
  • 2606:4700:4700::1111 (Cloudflare)
  • 2001:4860:4860::8888 (Google)
  • 2620:fe::fe (Quad9)
DNS Resolution Verified:
  • github.com
  • raw.githubusercontent.com
  • api.github.com
  • git.community-scripts.org
Location: misc/install.func

​
tools.func

Package & Tool Installation Robust package management and tool installation functions with automatic retry logic and OS-upgrade safety.
  • Automatic retry logic for transient APT failures
  • Unified keyring cleanup (3 locations)
  • Legacy installation cleanup (nvm, rbenv, rustup)
  • OS-upgrade-safe repository preparation
  • 30+ tool-specific installation functions
Package Management:
  • install_packages_with_retry() - Install with 3 retries
  • upgrade_packages_with_retry() - Upgrade with retry logic
  • pkg_install() - Wrapper for package installation
  • pkg_update() - Update package lists
Repository Management:
  • setup_deb822_repo() - Modern DEB822 format repositories
  • prepare_repository_setup() - Cleanup repos before setup
  • cleanup_tool_keyrings() - Remove old keyrings
  • download_gpg_key() - Download and validate GPG keys
Tool Installation (examples):
  • setup_nodejs() - Node.js with specific version
  • setup_php() - PHP with extensions
  • setup_mariadb() - MariaDB server
  • setup_docker() - Docker Engine
  • setup_python_uv() - Python with uv package manager
  • setup_postgresql() - PostgreSQL server
  • setup_nginx() - Nginx web server
  • setup_go() - Go programming language
  • setup_rust() - Rust programming language
# Install with automatic retry on failure
install_packages_with_retry "package1" "package2" "package3"

# Custom retry count
RETRY_COUNT=5 install_packages_with_retry "package"

# Debug mode
TOOLS_DEBUG=true install_packages_with_retry "package"
Location: misc/tools.func

​
Alpine Linux Libraries

​
alpine-install.func

Alpine Container Setup Alpine Linux-specific installation functions for lightweight container deployments.
  • Alpine OS updates (apk-based)
  • IPv6 configuration for Alpine
  • MOTD and SSH for Alpine
  • Alpine-specific customizations
  • update_os() - Alpine version using apk
  • verb_ip6() - IPv6 configuration for Alpine
  • motd_ssh() - Alpine MOTD/SSH setup
  • customize() - Alpine customizations
  • cleanup_lxc() - Alpine cleanup
Location: misc/alpine-install.func

​
alpine-tools.func

Alpine Tool Installation Alpine-specific package and tool installation functions.
  • Alpine package management (apk)
  • Community repository enablement
  • Alpine-specific tool installations
  • apk_add() - Install Alpine packages
  • apk_update() - Update Alpine package lists
  • apk_del() - Remove Alpine packages
  • add_community_repo() - Enable Alpine community repo
  • Alpine-specific tool setup functions
Location: misc/alpine-tools.func

​
VM Provisioning Libraries

​
cloud-init.func

VM Cloud-Init Configuration Cloud-init and VM provisioning functions for automated VM deployment.
  • Cloud-init configuration generation
  • User-data and meta-data creation
  • SSH key installation for VMs
  • Static IP configuration
  • VM network configuration
  • generate_cloud_init() - Generate cloud-init config
  • generate_user_data() - Create user-data file
  • setup_ssh_keys() - Configure SSH keys for VM
  • setup_static_ip() - Static IP configuration
  • configure_network() - VM network setup
Location: misc/cloud-init.func

​
vm-core.func

VM Core Utilities & Workflow Provides core utility functions specifically for VM provisioning workflows, including enhanced messaging, spinners, and VM-specific operations.
  • VM-specific color codes and formatting
  • Enhanced messaging for VM operations
  • Spinner animations for long-running VM tasks
  • VM workflow orchestration
  • Validation checks for VM parameters
  • Development mode support for VMs
  • load_functions() - Initialize VM utility groups
  • color() - Set VM-specific ANSI color codes
  • msg_info() - Display VM operation messages
  • msg_ok() - Display VM success messages
  • msg_error() - Display VM error messages
  • spinner_start() - Start progress spinner
  • spinner_stop() - Stop progress spinner
  • validate_vm_id() - Validate VMID
  • vm_cleanup() - Clean up failed VM creation
  • Sourced by: VM creation scripts (vm/*.sh)
  • Works with: cloud-init.func for provisioning
  • Provides: VM-specific utilities similar to core.func for containers
Location: misc/vm-core.func

​
Function Library Relationships

┌─────────────────────────────────────────────┐
│       Container Creation Flow               │
├─────────────────────────────────────────────┤
│                                             │
│  ct/AppName.sh                              │
│      ↓ (sources)                            │
│  build.func                                 │
│      ├─ variables()                         │
│      ├─ build_container()                   │
│      └─ advanced_settings()                 │
│      ↓ (calls pct create with)              │
│  install/appname-install.sh                 │
│      ↓ (sources)                            │
│      ├─ core.func      (colors, messaging)  │
│      ├─ error_handler.func (error trapping) │
│      ├─ install.func   (setup/network)      │
│      └─ tools.func     (packages/tools)     │
│                                             │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│       Alpine Container Flow                 │
├─────────────────────────────────────────────┤
│                                             │
│  install/appname-install.sh (Alpine)        │
│      ↓ (sources)                            │
│      ├─ core.func              (colors)     │
│      ├─ error_handler.func     (errors)     │
│      ├─ alpine-install.func    (apk setup)  │
│      └─ alpine-tools.func      (apk tools)  │
│                                             │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│       VM Provisioning Flow                  │
├─────────────────────────────────────────────┤
│                                             │
│  vm/OsName-vm.sh                            │
│      ↓ (sources)                            │
│  vm-core.func                               │
│      ├─ color(), msg_info()                 │
│      ├─ spinner operations                  │
│      └─ VM validation                       │
│      ↓ (uses)                               │
│  cloud-init.func                            │
│      ├─ generate_cloud_init()               │
│      ├─ setup_ssh_keys()                    │
│      └─ configure_network()                 │
│                                             │
└─────────────────────────────────────────────┘

​
Quick Stats

LibraryFunctionsPrimary Use CaseDependencies
build.func50+LXC container creationapi.func, core.func, error_handler.func
core.func20+System utilitiesNone (foundation)
error_handler.func10+Error handlingcore.func
api.func5+Telemetry reportingNone
install.func8+Container setupcore.func, error_handler.func
tools.func30+Package managementcore.func
alpine-install.func6+Alpine setupcore.func, error_handler.func
alpine-tools.func15+Alpine packagescore.func
cloud-init.func12+VM provisioningcore.func
Total: 9 function libraries, 150+ functions
All function libraries are loaded via HTTP/HTTPS from the main repository using source <(curl -fsSL ...) to ensure users always get the latest version without manual updates.

Build docs developers (and LLMs) love

Get started for freeTalk to us