community-scripts/ProxmoxVED
5
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add docs for all files in /misc
Some checks failed
Bump build.func Revision / bump-revision (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Michel Roegl-Brunner 2025-10-10 11:18:59 +02:00
parent b006c4f74b
commit 960fddb9ee
19 changed files with 7095 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/misc/README.md Normal file
View File

@ -0,0 +1,42 @@
# Misc Documentation
This directory contains miscellaneous documentation for various components of the Proxmox Community Scripts project.
## Documentation Categories
### 📁 [build.func/](./build.func/)
Comprehensive documentation for the `build.func` script - the core orchestration script for Proxmox LXC container creation.
**Contents:**
- Visual execution flowcharts
- Complete environment variables reference
- Function documentation
- Detailed execution flows
- System architecture guide
- Practical usage examples
### 📁 [core.func/](./core.func/)
Fundamental utility functions and system checks that form the foundation for all other scripts.
**Contents:**
- Visual execution flowcharts
- Complete function reference
- Practical usage examples
- Integration with other components
### 📁 [error_handler.func/](./error_handler.func/)
Comprehensive error handling and signal management for Proxmox Community Scripts.
**Contents:**
- Visual execution flowcharts
- Complete function reference
- Practical usage examples
- Integration with other components
## Other Documentation
Additional miscellaneous documentation may be added here as the project grows.
---
*This directory contains specialized documentation for specific components of the Proxmox Community Scripts project.*

410
docs/misc/build.func/BUILD_FUNC_ARCHITECTURE.md Normal file
View File

@ -0,0 +1,410 @@
# build.func Architecture Guide
## Overview
This document provides a high-level architectural overview of `build.func`, including module dependencies, data flow, integration points, and system architecture.
## High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Proxmox Host System │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ build.func │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ Entry Point │ │ Configuration │ │ Container Creation │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • start() │ │ • variables() │ │ • build_container() │ │ │
│ │ │ • install_ │ │ • base_ │ │ • create_lxc_container() │ │ │
│ │ │ script() │ │ settings() │ │ • configure_gpu_ │ │ │
│ │ │ • advanced_ │ │ • select_ │ │ passthrough() │ │ │
│ │ │ settings() │ │ storage() │ │ • fix_gpu_gids() │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Module Dependencies │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ core.func │ │ error_handler. │ │ api.func │ │ │
│ │ │ │ │ func │ │ │ │ │
│ │ │ • Basic │ │ • Error │ │ • Proxmox API │ │ │
│ │ │ utilities │ │ handling │ │ interactions │ │ │
│ │ │ • Common │ │ • Error │ │ • Container │ │ │
│ │ │ functions │ │ recovery │ │ management │ │ │
│ │ │ • System │ │ • Cleanup │ │ • Status │ │ │
│ │ │ utilities │ │ functions │ │ monitoring │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ tools.func │ │ │
│ │ │ │ │ │
│ │ │ • Additional utilities │ │ │
│ │ │ • Helper functions │ │ │
│ │ │ • System tools │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Module Dependencies
### Core Dependencies
```
build.func Dependencies:
├── core.func
│ ├── Basic system utilities
│ ├── Common functions
│ ├── System information
│ └── File operations
├── error_handler.func
│ ├── Error handling
│ ├── Error recovery
│ ├── Cleanup functions
│ └── Error logging
├── api.func
│ ├── Proxmox API interactions
│ ├── Container management
│ ├── Status monitoring
│ └── Configuration updates
└── tools.func
├── Additional utilities
├── Helper functions
├── System tools
└── Custom functions
```
### Dependency Flow
```
Dependency Flow:
├── build.func
│ ├── Sources core.func
│ ├── Sources error_handler.func
│ ├── Sources api.func
│ └── Sources tools.func
├── core.func
│ ├── Basic utilities
│ └── System functions
├── error_handler.func
│ ├── Error management
│ └── Recovery functions
├── api.func
│ ├── Proxmox integration
│ └── Container operations
└── tools.func
├── Additional tools
└── Helper functions
```
## Data Flow Architecture
### Configuration Data Flow
```
Configuration Data Flow:
├── Environment Variables
│ ├── Hard environment variables
│ ├── App-specific .vars
│ ├── Global default.vars
│ └── Built-in defaults
├── Variable Resolution
│ ├── Apply precedence chain
│ ├── Validate settings
│ └── Resolve conflicts
├── Configuration Storage
│ ├── Memory variables
│ ├── Temporary files
│ └── Persistent storage
└── Configuration Usage
├── Container creation
├── Feature configuration
└── Settings persistence
```
### Container Data Flow
```
Container Data Flow:
├── Input Data
│ ├── Configuration variables
│ ├── Resource specifications
│ ├── Network settings
│ └── Storage requirements
├── Processing
│ ├── Validation
│ ├── Conflict resolution
│ ├── Resource allocation
│ └── Configuration generation
├── Container Creation
│ ├── LXC container creation
│ ├── Network configuration
│ ├── Storage setup
│ └── Feature configuration
└── Output
├── Container status
├── Access information
├── Configuration files
└── Log files
```
## Integration Architecture
### With Proxmox System
```
Proxmox Integration:
├── Proxmox Host
│ ├── LXC container management
│ ├── Storage management
│ ├── Network management
│ └── Resource management
├── Proxmox API
│ ├── Container operations
│ ├── Configuration updates
│ ├── Status monitoring
│ └── Error handling
├── Proxmox Configuration
│ ├── /etc/pve/lxc/<ctid>.conf
│ ├── Storage configuration
│ ├── Network configuration
│ └── Resource configuration
└── Proxmox Services
├── Container services
├── Network services
├── Storage services
└── Monitoring services
```
### With Install Scripts
```
Install Script Integration:
├── build.func
│ ├── Creates container
│ ├── Configures basic settings
│ ├── Starts container
│ └── Provides access
├── Install Scripts
│ ├── <app>-install.sh
│ ├── Downloads application
│ ├── Configures application
│ └── Sets up services
├── Container
│ ├── Running application
│ ├── Configured services
│ ├── Network access
│ └── Storage access
└── Integration Points
├── Container creation
├── Network configuration
├── Storage setup
└── Service configuration
```
## System Architecture Components
### Core Components
```
System Components:
├── Entry Point
│ ├── start() function
│ ├── Context detection
│ ├── Environment capture
│ └── Workflow routing
├── Configuration Management
│ ├── Variable resolution
│ ├── Settings persistence
│ ├── Default management
│ └── Validation
├── Container Creation
│ ├── LXC container creation
│ ├── Network configuration
│ ├── Storage setup
│ └── Feature configuration
├── Hardware Integration
│ ├── GPU passthrough
│ ├── USB passthrough
│ ├── Storage management
│ └── Network management
└── Error Handling
├── Error detection
├── Error recovery
├── Cleanup functions
└── User notification
```
### User Interface Components
```
UI Components:
├── Menu System
│ ├── Installation mode selection
│ ├── Configuration menus
│ ├── Storage selection
│ └── GPU configuration
├── Interactive Elements
│ ├── Whiptail menus
│ ├── User prompts
│ ├── Confirmation dialogs
│ └── Error messages
├── Non-Interactive Mode
│ ├── Environment variable driven
│ ├── Silent execution
│ ├── Automated configuration
│ └── Error handling
└── Output
├── Status messages
├── Progress indicators
├── Completion information
└── Access details
```
## Security Architecture
### Security Considerations
```
Security Architecture:
├── Container Security
│ ├── Unprivileged containers (default)
│ ├── Privileged containers (when needed)
│ ├── Resource limits
│ └── Access controls
├── Network Security
│ ├── Network isolation
│ ├── VLAN support
│ ├── Firewall integration
│ └── Access controls
├── Storage Security
│ ├── Storage isolation
│ ├── Access controls
│ ├── Encryption support
│ └── Backup integration
├── GPU Security
│ ├── Device isolation
│ ├── Permission management
│ ├── Access controls
│ └── Security validation
└── API Security
├── Authentication
├── Authorization
├── Input validation
└── Error handling
```
## Performance Architecture
### Performance Considerations
```
Performance Architecture:
├── Execution Optimization
│ ├── Parallel operations
│ ├── Efficient algorithms
│ ├── Minimal user interaction
│ └── Optimized validation
├── Resource Management
│ ├── Memory efficiency
│ ├── CPU optimization
│ ├── Disk usage optimization
│ └── Network efficiency
├── Caching
│ ├── Configuration caching
│ ├── Template caching
│ ├── Storage caching
│ └── GPU detection caching
└── Monitoring
├── Performance monitoring
├── Resource monitoring
├── Error monitoring
└── Status monitoring
```
## Deployment Architecture
### Deployment Scenarios
```
Deployment Scenarios:
├── Single Container
│ ├── Individual application
│ ├── Standard configuration
│ ├── Basic networking
│ └── Standard storage
├── Multiple Containers
│ ├── Application stack
│ ├── Shared networking
│ ├── Shared storage
│ └── Coordinated deployment
├── High Availability
│ ├── Redundant containers
│ ├── Load balancing
│ ├── Failover support
│ └── Monitoring integration
└── Development Environment
├── Development containers
├── Testing containers
├── Staging containers
└── Production containers
```
## Maintenance Architecture
### Maintenance Components
```
Maintenance Architecture:
├── Updates
│ ├── Container updates
│ ├── Application updates
│ ├── Configuration updates
│ └── Security updates
├── Monitoring
│ ├── Container monitoring
│ ├── Resource monitoring
│ ├── Performance monitoring
│ └── Error monitoring
├── Backup
│ ├── Configuration backup
│ ├── Container backup
│ ├── Storage backup
│ └── Recovery procedures
└── Troubleshooting
├── Error diagnosis
├── Log analysis
├── Performance analysis
└── Recovery procedures
```
## Future Architecture Considerations
### Scalability
```
Scalability Considerations:
├── Horizontal Scaling
│ ├── Multiple containers
│ ├── Load balancing
│ ├── Distributed deployment
│ └── Resource distribution
├── Vertical Scaling
│ ├── Resource scaling
│ ├── Performance optimization
│ ├── Capacity planning
│ └── Resource management
├── Automation
│ ├── Automated deployment
│ ├── Automated scaling
│ ├── Automated monitoring
│ └── Automated recovery
└── Integration
├── External systems
├── Cloud integration
├── Container orchestration
└── Service mesh
```

248
docs/misc/build.func/BUILD_FUNC_ENVIRONMENT_VARIABLES.md Normal file
View File

@ -0,0 +1,248 @@
# 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:
```bash
# 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
```bash
# 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
```bash
# Enable GPU passthrough
export GPU_APPS="plex,jellyfin,emby"
export var_gpu="intel"
export ENABLE_PRIVILEGED="true"
```
### 3. Advanced Network Configuration
```bash
# 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
```bash
# 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
```bash
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
```bash
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
```bash
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"
```

413
docs/misc/build.func/BUILD_FUNC_EXECUTION_FLOWS.md Normal file
View File

@ -0,0 +1,413 @@
# build.func Execution Flows
## Overview
This document details the execution flows for different installation modes and scenarios in `build.func`, including variable precedence, decision trees, and workflow patterns.
## Installation Modes
### 1. Default Install Flow
**Purpose**: Uses built-in defaults with minimal user interaction
**Use Case**: Quick container creation with standard settings
```
Default Install Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "Default Install"
│ └── Proceed with defaults
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars (if exists)
│ ├── Load default.vars (if exists)
│ └── Apply variable precedence
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Minimal user prompts
- Uses built-in defaults
- Fast execution
- Suitable for standard deployments
### 2. Advanced Install Flow
**Purpose**: Full interactive configuration via whiptail menus
**Use Case**: Custom container configuration with full control
```
Advanced Install Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "Advanced Install"
│ └── Proceed with advanced configuration
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars (if exists)
│ ├── Load default.vars (if exists)
│ └── Apply variable precedence
├── advanced_settings()
│ ├── OS Selection Menu
│ ├── Resource Configuration Menu
│ ├── Network Configuration Menu
│ ├── select_storage()
│ │ ├── resolve_storage_preselect()
│ │ └── choose_and_set_storage_for_file()
│ ├── GPU Configuration Menu
│ │ └── detect_gpu_devices()
│ └── Feature Flags Menu
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Full interactive configuration
- Whiptail menus for all options
- Complete control over settings
- Suitable for custom deployments
### 3. My Defaults Flow
**Purpose**: Loads settings from global default.vars file
**Use Case**: Using previously saved global defaults
```
My Defaults Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "My Defaults"
│ └── Proceed with loaded defaults
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars (if exists)
│ ├── Load default.vars # Load global defaults
│ └── Apply variable precedence
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Uses global default.vars file
- Minimal user interaction
- Consistent with previous settings
- Suitable for repeated deployments
### 4. App Defaults Flow
**Purpose**: Loads settings from app-specific .vars file
**Use Case**: Using previously saved app-specific defaults
```
App Defaults Flow:
├── start()
│ ├── Detect execution context
│ ├── Capture hard environment variables
│ └── Set CT_TYPE="install"
├── install_script()
│ ├── Display installation mode menu
│ ├── User selects "App Defaults"
│ └── Proceed with app-specific defaults
├── variables()
│ ├── base_settings() # Set built-in defaults
│ ├── Load app.vars # Load app-specific defaults
│ ├── Load default.vars (if exists)
│ └── Apply variable precedence
├── build_container()
│ ├── validate_settings()
│ ├── check_conflicts()
│ └── create_lxc_container()
└── default_var_settings()
└── Offer to save as defaults
```
**Key Characteristics**:
- Uses app-specific .vars file
- Minimal user interaction
- App-optimized settings
- Suitable for app-specific deployments
## Variable Precedence Chain
### Precedence Order (Highest to Lowest)
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
### Variable Resolution Process
```
Variable Resolution:
├── Capture hard environment variables at start()
├── Load built-in defaults in base_settings()
├── Load global default.vars (if exists)
├── Load app-specific .vars (if exists)
└── Apply precedence chain
├── Hard env vars override all
├── App.vars override default.vars and built-ins
├── Default.vars override built-ins
└── Built-ins are fallback defaults
```
## Storage Selection Logic
### Storage Resolution Flow
```
Storage Selection:
├── Check if storage is preselected
│ ├── var_template_storage set? → Validate and use
│ └── var_container_storage set? → Validate and use
├── Count available storage options
│ ├── Only 1 option → Auto-select
│ └── Multiple options → Prompt user
├── User selection via whiptail
│ ├── Template storage selection
│ └── Container storage selection
└── Validate selected storage
├── Check availability
├── Check content type support
└── Proceed with selection
```
### Storage Validation
```
Storage Validation:
├── Check storage exists
├── Check storage is online
├── Check content type support
│ ├── Template storage: vztmpl support
│ └── Container storage: rootdir support
├── Check available space
└── Validate permissions
```
## GPU Passthrough Flow
### GPU Detection and Configuration
```
GPU Passthrough Flow:
├── detect_gpu_devices()
│ ├── Scan for Intel GPUs
│ │ ├── Check i915 driver
│ │ └── Detect devices
│ ├── Scan for AMD GPUs
│ │ ├── Check AMDGPU driver
│ │ └── Detect devices
│ └── Scan for NVIDIA GPUs
│ ├── Check NVIDIA driver
│ ├── Detect devices
│ └── Check CUDA support
├── Check GPU passthrough eligibility
│ ├── Is app in GPU_APPS list?
│ ├── Is container privileged?
│ └── Proceed if eligible
├── GPU selection logic
│ ├── Single GPU type → Auto-select
│ └── Multiple GPU types → Prompt user
├── configure_gpu_passthrough()
│ ├── Add GPU device entries
│ ├── Configure permissions
│ └── Update container config
└── fix_gpu_gids()
├── Update GPU group IDs
└── Configure access permissions
```
### GPU Eligibility Check
```
GPU Eligibility:
├── Check app support
│ ├── Is APP in GPU_APPS list?
│ └── Proceed if supported
├── Check container privileges
│ ├── Is ENABLE_PRIVILEGED="true"?
│ └── Proceed if privileged
└── Check hardware availability
├── Are GPUs detected?
└── Proceed if available
```
## Network Configuration Flow
### Network Setup Process
```
Network Configuration:
├── Basic network settings
│ ├── var_net (network interface)
│ ├── var_bridge (bridge interface)
│ └── var_gateway (gateway IP)
├── IP configuration
│ ├── var_ip (IPv4 address)
│ ├── var_ipv6 (IPv6 address)
│ └── IPV6_METHOD (IPv6 method)
├── Advanced network settings
│ ├── var_vlan (VLAN ID)
│ ├── var_mtu (MTU size)
│ └── var_mac (MAC address)
└── Network validation
├── Check IP format
├── Check gateway reachability
└── Validate network configuration
```
## Container Creation Flow
### LXC Container Creation Process
```
Container Creation:
├── create_lxc_container()
│ ├── Create basic container
│ ├── Configure network
│ ├── Set up storage
│ ├── Configure features
│ ├── Set resource limits
│ ├── Configure startup
│ └── Start container
├── Post-creation configuration
│ ├── Wait for network
│ ├── Configure GPU (if enabled)
│ ├── Set up SSH keys
│ └── Run post-install scripts
└── Finalization
├── Display container info
├── Show access details
└── Provide next steps
```
## Error Handling Flows
### Validation Error Flow
```
Validation Error Flow:
├── validate_settings()
│ ├── Check configuration validity
│ └── Return error if invalid
├── check_conflicts()
│ ├── Check for conflicts
│ └── Return error if conflicts found
├── Error handling
│ ├── Display error message
│ ├── cleanup_on_error()
│ └── Exit with error code
└── User notification
├── Show error details
└── Suggest fixes
```
### Storage Error Flow
```
Storage Error Flow:
├── Storage selection fails
├── Retry storage selection
│ ├── Show available options
│ └── Allow user to retry
├── Storage validation fails
│ ├── Show validation errors
│ └── Allow user to fix
└── Fallback to default storage
├── Use fallback storage
└── Continue with creation
```
### GPU Error Flow
```
GPU Error Flow:
├── GPU detection fails
├── Fall back to no GPU
│ ├── Disable GPU passthrough
│ └── Continue without GPU
├── GPU configuration fails
│ ├── Show configuration errors
│ └── Allow user to retry
└── GPU permission errors
├── Fix GPU permissions
└── Retry configuration
```
## Integration Flows
### With Install Scripts
```
Install Script Integration:
├── build.func creates container
├── Container starts successfully
├── Install script execution
│ ├── Download and install app
│ ├── Configure app settings
│ └── Set up services
└── Post-installation configuration
├── Verify installation
├── Configure access
└── Display completion info
```
### With Proxmox API
```
Proxmox API Integration:
├── API authentication
├── Container creation via API
├── Configuration updates via API
├── Status monitoring via API
└── Error handling via API
```
## Performance Considerations
### Execution Time Optimization
```
Performance Optimization:
├── Parallel operations where possible
├── Minimal user interaction in default mode
├── Efficient storage selection
├── Optimized GPU detection
└── Streamlined validation
```
### Resource Usage
```
Resource Usage:
├── Minimal memory footprint
├── Efficient disk usage
├── Optimized network usage
└── Minimal CPU overhead
```

244
docs/misc/build.func/BUILD_FUNC_FLOWCHART.md Normal file
View File

@ -0,0 +1,244 @@
# build.func Execution Flowchart
## Main Execution Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ START() │
│ Entry point when build.func is sourced or executed │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Check Environment │
│ • Detect if running on Proxmox host vs inside container │
│ • Capture hard environment variables │
│ • Set CT_TYPE based on context │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Determine Action │
│ • If CT_TYPE="update" → update_script() │
│ • If CT_TYPE="install" → install_script() │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ INSTALL_SCRIPT() │
│ Main container creation workflow │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Installation Mode Selection │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Default │ │ Advanced │ │ My Defaults │ │ App Defaults│ │
│ │ Install │ │ Install │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ • Use built-in │ │ • Full whiptail │ │ • Load from │ │ • Load from │ │
│ │ defaults │ │ menus │ │ default.vars │ │ app.vars │ │
│ │ • Minimal │ │ • Interactive │ │ • Override │ │ • App- │ │
│ │ prompts │ │ configuration │ │ built-ins │ │ specific │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ VARIABLES() │
│ • Load variable precedence chain: │
│ 1. Hard environment variables │
│ 2. App-specific .vars file │
│ 3. Global default.vars file │
│ 4. Built-in defaults in base_settings() │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ BASE_SETTINGS() │
│ • Set core container parameters │
│ • Configure OS selection │
│ • Set resource defaults (CPU, RAM, Disk) │
│ • Configure network defaults │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Storage Selection Logic │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ SELECT_STORAGE() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Template │ │ Container │ │ Resolution │ │ │
│ │ │ Storage │ │ Storage │ │ Logic │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Check if │ │ • Check if │ │ 1. Only 1 storage │ │ │
│ │ │ preselected │ │ preselected │ │ → Auto-select │ │ │
│ │ │ • Validate │ │ • Validate │ │ 2. Preselected │ │ │
│ │ │ availability │ │ availability │ │ → Validate & use │ │ │
│ │ │ • Prompt if │ │ • Prompt if │ │ 3. Multiple options │ │ │
│ │ │ needed │ │ needed │ │ → Prompt user │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ BUILD_CONTAINER() │
│ • Validate all settings │
│ • Check for conflicts │
│ • Prepare container configuration │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CREATE_LXC_CONTAINER() │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Container Creation Process │ │
│ │ │ │
│ │ 1. Create LXC container with basic configuration │ │
│ │ 2. Configure network settings │ │
│ │ 3. Set up storage and mount points │ │
│ │ 4. Configure features (FUSE, TUN, etc.) │ │
│ │ 5. Set resource limits │ │
│ │ 6. Configure startup options │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ GPU Passthrough Decision Tree │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ DETECT_GPU_DEVICES() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Intel GPU │ │ AMD GPU │ │ NVIDIA GPU │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Check i915 │ │ • Check AMDGPU │ │ • Check NVIDIA │ │ │
│ │ │ driver │ │ driver │ │ driver │ │ │
│ │ │ • Detect │ │ • Detect │ │ • Detect devices │ │ │
│ │ │ devices │ │ devices │ │ • Check CUDA support │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ GPU Selection Logic │ │
│ │ │ │
│ │ • Is app in GPU_APPS list? OR Is container privileged? │ │
│ │ └─ YES → Proceed with GPU configuration │ │
│ │ └─ NO → Skip GPU passthrough │ │
│ │ │ │
│ │ • Single GPU type detected? │ │
│ │ └─ YES → Auto-select and configure │ │
│ │ └─ NO → Prompt user for selection │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CONFIGURE_GPU_PASSTHROUGH() │
│ • Add GPU device entries to /etc/pve/lxc/<ctid>.conf │
│ • Configure proper device permissions │
│ • Set up device mapping │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Container Finalization │
│ • Start container │
│ • Wait for network connectivity │
│ • Fix GPU GIDs (if GPU passthrough enabled) │
│ • Configure SSH keys (if enabled) │
│ • Run post-installation scripts │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Settings Persistence │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ DEFAULT_VAR_SETTINGS() │ │
│ │ │ │
│ │ • Offer to save current settings as defaults │ │
│ │ • Save to /usr/local/community-scripts/default.vars │ │
│ │ • Save to /usr/local/community-scripts/defaults/<app>.vars │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ COMPLETION │
│ • Display container information │
│ • Show access details │
│ • Provide next steps │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Key Decision Points
### 1. Installation Mode Selection
- **Default**: Uses built-in defaults, minimal user interaction
- **Advanced**: Full interactive configuration via whiptail menus
- **My Defaults**: Loads settings from global default.vars file
- **App Defaults**: Loads settings from app-specific .vars file
### 2. Storage Selection Logic
```
Storage Selection Flow:
├── Check if storage is preselected via environment variables
│ ├── YES → Validate availability and use
│ └── NO → Continue to resolution logic
├── Count available storage options for content type
│ ├── Only 1 option → Auto-select
│ └── Multiple options → Prompt user via whiptail
└── Validate selected storage and proceed
```
### 3. GPU Passthrough Decision Tree
```
GPU Passthrough Flow:
├── Detect available GPU hardware
│ ├── Intel GPU detected
│ ├── AMD GPU detected
│ └── NVIDIA GPU detected
├── Check if GPU passthrough should be enabled
│ ├── App is in GPU_APPS list? → YES
│ ├── Container is privileged? → YES
│ └── Neither? → Skip GPU passthrough
├── Configure GPU passthrough
│ ├── Single GPU type → Auto-configure
│ └── Multiple GPU types → Prompt user
└── Fix GPU GIDs post-creation
```
### 4. Variable Precedence Chain
```
Variable Resolution Order:
1. Hard environment variables (captured at start)
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 in base_settings() function
```
## Error Handling Flow
```
Error Handling:
├── Validation errors → Display error message and exit
├── Storage errors → Retry storage selection
├── Network errors → Retry network configuration
├── GPU errors → Fall back to no GPU passthrough
└── Container creation errors → Cleanup and exit
```
## Integration Points
- **Core Functions**: Depends on core.func for basic utilities
- **Error Handling**: Uses error_handler.func for error management
- **API Functions**: Uses api.func for Proxmox API interactions
- **Tools**: Uses tools.func for additional utilities
- **Install Scripts**: Integrates with <app>-install.sh scripts

361
docs/misc/build.func/BUILD_FUNC_FUNCTIONS_REFERENCE.md Normal file
View File

@ -0,0 +1,361 @@
# 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/<ctid>.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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

600
docs/misc/build.func/BUILD_FUNC_USAGE_EXAMPLES.md Normal file
View File

@ -0,0 +1,600 @@
# build.func Usage Examples
## Overview
This document provides practical usage examples for `build.func`, covering common scenarios, CLI examples, and environment variable combinations.
## Basic Usage Examples
### 1. Simple Container Creation
**Scenario**: Create a basic Plex media server container
```bash
# Set basic environment variables
export APP="plex"
export CTID="100"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.100"
export var_template_storage="local"
export var_container_storage="local"
# Execute build.func
source build.func
```
**Expected Output**:
```
Creating Plex container...
Container ID: 100
Hostname: plex-server
OS: Debian 12
Resources: 4 CPU, 4GB RAM, 20GB Disk
Network: 192.168.1.100/24
Container created successfully!
```
### 2. Advanced Configuration
**Scenario**: Create a Nextcloud container with custom settings
```bash
# Set advanced environment variables
export APP="nextcloud"
export CTID="101"
export var_hostname="nextcloud-server"
export var_os="ubuntu"
export var_version="22.04"
export var_cpu="6"
export var_ram="8192"
export var_disk="50"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.101"
export var_vlan="100"
export var_mtu="9000"
export var_template_storage="nfs-storage"
export var_container_storage="ssd-storage"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
# Execute build.func
source build.func
```
### 3. GPU Passthrough Configuration
**Scenario**: Create a Jellyfin container with NVIDIA GPU passthrough
```bash
# Set GPU passthrough variables
export APP="jellyfin"
export CTID="102"
export var_hostname="jellyfin-server"
export var_os="debian"
export var_version="12"
export var_cpu="8"
export var_ram="16384"
export var_disk="30"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.102"
export var_template_storage="local"
export var_container_storage="local"
export GPU_APPS="jellyfin"
export var_gpu="nvidia"
export ENABLE_PRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
# Execute build.func
source build.func
```
## Silent/Non-Interactive Examples
### 1. Automated Deployment
**Scenario**: Deploy multiple containers without user interaction
```bash
#!/bin/bash
# Automated deployment script
# Function to create container
create_container() {
local app=$1
local ctid=$2
local ip=$3
export APP="$app"
export CTID="$ctid"
export var_hostname="${app}-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="$ip"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
source build.func
}
# Create multiple containers
create_container "plex" "100" "192.168.1.100"
create_container "nextcloud" "101" "192.168.1.101"
create_container "nginx" "102" "192.168.1.102"
```
### 2. Development Environment Setup
**Scenario**: Create development containers with specific configurations
```bash
#!/bin/bash
# Development environment setup
# Development container configuration
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 var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.200"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_NESTING="true"
export ENABLE_PRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export SSH="true"
# Execute build.func
source build.func
```
## Network Configuration Examples
### 1. VLAN Configuration
**Scenario**: Create container with VLAN support
```bash
# VLAN configuration
export APP="web-server"
export CTID="300"
export var_hostname="web-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.100.1"
export var_ip="192.168.100.100"
export var_vlan="100"
export var_mtu="1500"
export var_template_storage="local"
export var_container_storage="local"
source build.func
```
### 2. IPv6 Configuration
**Scenario**: Create container with IPv6 support
```bash
# IPv6 configuration
export APP="ipv6-server"
export CTID="301"
export var_hostname="ipv6-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_ipv6="2001:db8::101"
export IPV6_METHOD="static"
export var_template_storage="local"
export var_container_storage="local"
source build.func
```
## Storage Configuration Examples
### 1. Custom Storage Locations
**Scenario**: Use different storage for templates and containers
```bash
# Custom storage configuration
export APP="storage-test"
export CTID="400"
export var_hostname="storage-test"
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.140"
export var_template_storage="nfs-storage"
export var_container_storage="ssd-storage"
source build.func
```
### 2. High-Performance Storage
**Scenario**: Use high-performance storage for resource-intensive applications
```bash
# High-performance storage configuration
export APP="database-server"
export CTID="401"
export var_hostname="database-server"
export var_os="debian"
export var_version="12"
export var_cpu="8"
export var_ram="16384"
export var_disk="100"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.141"
export var_template_storage="nvme-storage"
export var_container_storage="nvme-storage"
source build.func
```
## Feature Configuration Examples
### 1. Privileged Container
**Scenario**: Create privileged container for system-level access
```bash
# Privileged container configuration
export APP="system-container"
export CTID="500"
export var_hostname="system-container"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.150"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_PRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
export ENABLE_KEYCTL="true"
export ENABLE_MOUNT="true"
source build.func
```
### 2. Unprivileged Container
**Scenario**: Create secure unprivileged container
```bash
# Unprivileged container configuration
export APP="secure-container"
export CTID="501"
export var_hostname="secure-container"
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.151"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_UNPRIVILEGED="true"
export ENABLE_FUSE="true"
export ENABLE_TUN="true"
source build.func
```
## Settings Persistence Examples
### 1. Save Global Defaults
**Scenario**: Save current settings as global defaults
```bash
# Save global defaults
export APP="default-test"
export CTID="600"
export var_hostname="default-test"
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.160"
export var_template_storage="local"
export var_container_storage="local"
export SAVE_DEFAULTS="true"
source build.func
```
### 2. Save App-Specific Defaults
**Scenario**: Save settings as app-specific defaults
```bash
# Save app-specific defaults
export APP="plex"
export CTID="601"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.161"
export var_template_storage="local"
export var_container_storage="local"
export SAVE_APP_DEFAULTS="true"
source build.func
```
## Error Handling Examples
### 1. Validation Error Handling
**Scenario**: Handle configuration validation errors
```bash
#!/bin/bash
# Error handling example
# Set invalid configuration
export APP="error-test"
export CTID="700"
export var_hostname="error-test"
export var_os="invalid-os"
export var_version="invalid-version"
export var_cpu="invalid-cpu"
export var_ram="invalid-ram"
export var_disk="invalid-disk"
export var_net="invalid-network"
export var_gateway="invalid-gateway"
export var_ip="invalid-ip"
# Execute with error handling
if source build.func; then
echo "Container created successfully!"
else
echo "Error: Container creation failed!"
echo "Please check your configuration and try again."
fi
```
### 2. Storage Error Handling
**Scenario**: Handle storage selection errors
```bash
#!/bin/bash
# Storage error handling
# Set invalid storage
export APP="storage-error-test"
export CTID="701"
export var_hostname="storage-error-test"
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.170"
export var_template_storage="nonexistent-storage"
export var_container_storage="nonexistent-storage"
# Execute with error handling
if source build.func; then
echo "Container created successfully!"
else
echo "Error: Storage not available!"
echo "Please check available storage and try again."
fi
```
## Integration Examples
### 1. With Install Scripts
**Scenario**: Integrate with application install scripts
```bash
#!/bin/bash
# Integration with install scripts
# Create container
export APP="plex"
export CTID="800"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.180"
export var_template_storage="local"
export var_container_storage="local"
# Create container
source build.func
# Run install script
if [ -f "plex-install.sh" ]; then
source plex-install.sh
else
echo "Install script not found!"
fi
```
### 2. With Monitoring
**Scenario**: Integrate with monitoring systems
```bash
#!/bin/bash
# Monitoring integration
# Create container with monitoring
export APP="monitored-app"
export CTID="801"
export var_hostname="monitored-app"
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.181"
export var_template_storage="local"
export var_container_storage="local"
export DIAGNOSTICS="true"
# Create container
source build.func
# Set up monitoring
if [ -f "monitoring-setup.sh" ]; then
source monitoring-setup.sh
fi
```
## Best Practices
### 1. Environment Variable Management
```bash
#!/bin/bash
# Best practice: Environment variable management
# Set configuration file
CONFIG_FILE="/etc/build.func.conf"
# Load configuration if exists
if [ -f "$CONFIG_FILE" ]; then
source "$CONFIG_FILE"
fi
# Set required variables
export APP="${APP:-plex}"
export CTID="${CTID:-100}"
export var_hostname="${var_hostname:-plex-server}"
export var_os="${var_os:-debian}"
export var_version="${var_version:-12}"
export var_cpu="${var_cpu:-2}"
export var_ram="${var_ram:-2048}"
export var_disk="${var_disk:-10}"
export var_net="${var_net:-vmbr0}"
export var_gateway="${var_gateway:-192.168.1.1}"
export var_ip="${var_ip:-192.168.1.100}"
export var_template_storage="${var_template_storage:-local}"
export var_container_storage="${var_container_storage:-local}"
# Execute build.func
source build.func
```
### 2. Error Handling and Logging
```bash
#!/bin/bash
# Best practice: Error handling and logging
# Set log file
LOG_FILE="/var/log/build.func.log"
# Function to log messages
log_message() {
echo "$(date): $1" >> "$LOG_FILE"
}
# Function to create container with error handling
create_container() {
local app=$1
local ctid=$2
log_message "Starting container creation for $app (ID: $ctid)"
# Set variables
export APP="$app"
export CTID="$ctid"
export var_hostname="${app}-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.$ctid"
export var_template_storage="local"
export var_container_storage="local"
# Create container
if source build.func; then
log_message "Container $app created successfully (ID: $ctid)"
return 0
else
log_message "Error: Failed to create container $app (ID: $ctid)"
return 1
fi
}
# Create containers
create_container "plex" "100"
create_container "nextcloud" "101"
create_container "nginx" "102"
```

260
docs/misc/build.func/README.md Normal file
View File

@ -0,0 +1,260 @@
# build.func Documentation
## Overview
This directory contains comprehensive documentation for the `build.func` script, which is the core orchestration script for Proxmox LXC container creation in the Community Scripts project.
## Documentation Files
### 📊 [BUILD_FUNC_FLOWCHART.md](./BUILD_FUNC_FLOWCHART.md)
Visual ASCII flowchart showing the main execution flow, decision trees, and key decision points in the build.func script.
**Contents:**
- Main execution flow diagram
- Installation mode selection flows
- Storage selection workflow
- GPU passthrough decision logic
- Variable precedence chain
- Error handling flow
- Integration points
### 🔧 [BUILD_FUNC_ENVIRONMENT_VARIABLES.md](./BUILD_FUNC_ENVIRONMENT_VARIABLES.md)
Complete reference of all environment variables used in build.func, organized by category and usage context.
**Contents:**
- Core container variables
- Operating system variables
- Resource configuration variables
- Network configuration variables
- Storage configuration variables
- Feature flags
- GPU passthrough variables
- API and diagnostics variables
- Settings persistence variables
- Variable precedence chain
- Critical variables for non-interactive use
- Common variable combinations
### 📚 [BUILD_FUNC_FUNCTIONS_REFERENCE.md](./BUILD_FUNC_FUNCTIONS_REFERENCE.md)
Alphabetical function reference with detailed descriptions, parameters, dependencies, and usage information.
**Contents:**
- Initialization functions
- UI and menu functions
- Storage functions
- Container creation functions
- GPU and hardware functions
- Settings persistence functions
- Utility functions
- Function call flow
- Function dependencies
- Function usage examples
- Function error handling
### 🔄 [BUILD_FUNC_EXECUTION_FLOWS.md](./BUILD_FUNC_EXECUTION_FLOWS.md)
Detailed execution flows for different installation modes and scenarios, including variable precedence and decision trees.
**Contents:**
- Default install flow
- Advanced install flow
- My defaults flow
- App defaults flow
- Variable precedence chain
- Storage selection logic
- GPU passthrough flow
- Network configuration flow
- Container creation flow
- Error handling flows
- Integration flows
- Performance considerations
### 🏗️ [BUILD_FUNC_ARCHITECTURE.md](./BUILD_FUNC_ARCHITECTURE.md)
High-level architectural overview including module dependencies, data flow, integration points, and system architecture.
**Contents:**
- High-level architecture diagram
- Module dependencies
- Data flow architecture
- Integration architecture
- System architecture components
- User interface components
- Security architecture
- Performance architecture
- Deployment architecture
- Maintenance architecture
- Future architecture considerations
### 💡 [BUILD_FUNC_USAGE_EXAMPLES.md](./BUILD_FUNC_USAGE_EXAMPLES.md)
Practical usage examples covering common scenarios, CLI examples, and environment variable combinations.
**Contents:**
- Basic usage examples
- Silent/non-interactive examples
- Network configuration examples
- Storage configuration examples
- Feature configuration examples
- Settings persistence examples
- Error handling examples
- Integration examples
- Best practices
## Quick Start Guide
### For New Users
1. Start with [BUILD_FUNC_FLOWCHART.md](./BUILD_FUNC_FLOWCHART.md) to understand the overall flow
2. Review [BUILD_FUNC_ENVIRONMENT_VARIABLES.md](./BUILD_FUNC_ENVIRONMENT_VARIABLES.md) for configuration options
3. Follow examples in [BUILD_FUNC_USAGE_EXAMPLES.md](./BUILD_FUNC_USAGE_EXAMPLES.md)
### For Developers
1. Read [BUILD_FUNC_ARCHITECTURE.md](./BUILD_FUNC_ARCHITECTURE.md) for system overview
2. Study [BUILD_FUNC_FUNCTIONS_REFERENCE.md](./BUILD_FUNC_FUNCTIONS_REFERENCE.md) for function details
3. Review [BUILD_FUNC_EXECUTION_FLOWS.md](./BUILD_FUNC_EXECUTION_FLOWS.md) for implementation details
### For System Administrators
1. Focus on [BUILD_FUNC_USAGE_EXAMPLES.md](./BUILD_FUNC_USAGE_EXAMPLES.md) for deployment scenarios
2. Review [BUILD_FUNC_ENVIRONMENT_VARIABLES.md](./BUILD_FUNC_ENVIRONMENT_VARIABLES.md) for configuration management
3. Check [BUILD_FUNC_ARCHITECTURE.md](./BUILD_FUNC_ARCHITECTURE.md) for security and performance considerations
## Key Concepts
### Variable Precedence
Variables are resolved in this 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)
### Installation Modes
- **Default Install**: Uses built-in defaults, minimal prompts
- **Advanced Install**: Full interactive configuration via whiptail
- **My Defaults**: Loads from global default.vars file
- **App Defaults**: Loads from app-specific .vars file
### Storage Selection Logic
1. If only 1 storage exists for content type → auto-select
2. If preselected via environment variables → validate and use
3. Otherwise → prompt user via whiptail
### GPU Passthrough Flow
1. Detect hardware (Intel/AMD/NVIDIA)
2. Check if app is in GPU_APPS list OR container is privileged
3. Auto-select if single GPU type, prompt if multiple
4. Configure `/etc/pve/lxc/<ctid>.conf` with proper device entries
5. Fix GIDs post-creation to match container's video/render groups
## Common Use Cases
### Basic Container Creation
```bash
export APP="plex"
export CTID="100"
export var_hostname="plex-server"
export var_os="debian"
export var_version="12"
export var_cpu="4"
export var_ram="4096"
export var_disk="20"
export var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.100"
export var_template_storage="local"
export var_container_storage="local"
source build.func
```
### GPU Passthrough
```bash
export APP="jellyfin"
export CTID="101"
export var_hostname="jellyfin-server"
export var_os="debian"
export var_version="12"
export var_cpu="8"
export var_ram="16384"
export var_disk="30"
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"
export GPU_APPS="jellyfin"
export var_gpu="nvidia"
export ENABLE_PRIVILEGED="true"
source build.func
```
### Silent/Non-Interactive Deployment
```bash
#!/bin/bash
# Automated deployment
export APP="nginx"
export CTID="102"
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 var_net="vmbr0"
export var_gateway="192.168.1.1"
export var_ip="192.168.1.102"
export var_template_storage="local"
export var_container_storage="local"
export ENABLE_UNPRIVILEGED="true"
source build.func
```
## Troubleshooting
### Common Issues
1. **Container creation fails**: Check resource availability and configuration validity
2. **Storage errors**: Verify storage exists and supports required content types
3. **Network errors**: Validate network configuration and IP address availability
4. **GPU passthrough issues**: Check hardware detection and container privileges
5. **Permission errors**: Verify user permissions and container privileges
### Debug Mode
Enable verbose output for debugging:
```bash
export VERBOSE="true"
export DIAGNOSTICS="true"
source build.func
```
### Log Files
Check system logs for detailed error information:
- `/var/log/syslog`
- `/var/log/pve/lxc/<ctid>.log`
- Container-specific logs
## Contributing
When contributing to build.func documentation:
1. Update relevant documentation files
2. Add examples for new features
3. Update architecture diagrams if needed
4. Test all examples before submitting
5. Follow the existing documentation style
## Related Documentation
- [Main README](../../README.md) - Project overview
- [Installation Guide](../../install/) - Installation scripts
- [Container Templates](../../ct/) - Container templates
- [Tools](../../tools/) - Additional tools and utilities
## Support
For issues and questions:
1. Check this documentation first
2. Review the [troubleshooting section](#troubleshooting)
3. Check existing issues in the project repository
4. Create a new issue with detailed information
---
*Last updated: $(date)*
*Documentation version: 1.0*

316
docs/misc/core.func/CORE_FLOWCHART.md Normal file
View File

@ -0,0 +1,316 @@
# core.func Execution Flowchart
## Main Execution Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ core.func Loading │
│ Entry point when core.func is sourced by other scripts │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Load Prevention Check │
│ • Check if _CORE_FUNC_LOADED is set │
│ • Return early if already loaded │
│ • Set _CORE_FUNC_LOADED=1 to prevent reloading │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ LOAD_FUNCTIONS() │
│ Main function loader - sets up all core utilities │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Core Function Loading Sequence │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ color() │ │ formatting() │ │ icons() │ │
│ │ │ │ │ │ │ │
│ │ • Set ANSI │ │ • Set format │ │ • Set symbolic icons │ │
│ │ color codes │ │ helpers │ │ • Define message │ │
│ │ • Define │ │ • Tab, bold, │ │ symbols │ │
│ │ colors │ │ line reset │ │ • Status indicators │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ default_vars() │ │ set_std_mode() │ │ Additional Functions │ │
│ │ │ │ │ │ │ │
│ │ • Set retry │ │ • Set verbose │ │ • Add more functions │ │
│ │ variables │ │ mode │ │ as needed │ │
│ │ • Initialize │ │ • Configure │ │ │ │
│ │ counters │ │ STD variable │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## System Check Functions Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ System Validation Flow │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ PVE_CHECK() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Get PVE │ │ Check PVE │ │ Check PVE │ │ │
│ │ │ Version │ │ 8.x Support │ │ 9.x Support │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • pveversion │ │ • Allow 8.0-8.9│ │ • Allow ONLY 9.0 │ │ │
│ │ │ • Parse version │ │ • Reject others │ │ • Reject 9.1+ │ │ │
│ │ │ • Extract │ │ • Exit if │ │ • Exit if │ │ │
│ │ │ major.minor │ │ unsupported │ │ unsupported │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ ARCH_CHECK() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check │ │ AMD64 Check │ │ PiMox Warning │ │ │
│ │ │ Architecture │ │ │ │ │ │ │
│ │ │ │ │ • dpkg --print- │ │ • Show PiMox │ │ │
│ │ │ • Get system │ │ architecture │ │ message │ │ │
│ │ │ architecture │ │ • Must be │ │ • Point to ARM64 │ │ │
│ │ │ • Compare with │ │ "amd64" │ │ support │ │ │
│ │ │ "amd64" │ │ • Exit if not │ │ • Exit script │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ SHELL_CHECK() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check │ │ Bash Check │ │ Error Handling │ │ │
│ │ │ Shell Type │ │ │ │ │ │ │
│ │ │ │ │ • ps -p $$ -o │ │ • Clear screen │ │ │
│ │ │ • Get current │ │ comm= │ │ • Show error │ │ │
│ │ │ shell │ │ • Must be │ │ • Sleep and exit │ │ │
│ │ │ • Compare with │ │ "bash" │ │ │ │ │
│ │ │ "bash" │ │ • Exit if not │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ ROOT_CHECK() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check │ │ Root Check │ │ Sudo Check │ │ │
│ │ │ User ID │ │ │ │ │ │ │
│ │ │ │ │ • id -u │ │ • Check parent │ │ │
│ │ │ • Get user ID │ │ • Must be 0 │ │ process │ │ │
│ │ │ • Check if │ │ • Exit if not │ │ • Detect sudo │ │ │
│ │ │ root (0) │ │ root │ │ usage │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Message System Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Message System Flow │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ MSG_INFO() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Message │ │ Duplicate │ │ Display Mode │ │ │
│ │ │ Validation │ │ Check │ │ Selection │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Check if │ │ • Track shown │ │ • Verbose mode: │ │ │
│ │ │ message │ │ messages │ │ Show directly │ │ │
│ │ │ exists │ │ • Skip if │ │ • Normal mode: │ │ │
│ │ │ • Return if │ │ already │ │ Start spinner │ │ │
│ │ │ empty │ │ shown │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ SPINNER() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Spinner │ │ Animation │ │ Display │ │ │
│ │ │ Initialization│ │ Loop │ │ Control │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Define │ │ • Cycle through │ │ • Print spinner │ │ │
│ │ │ characters │ │ characters │ │ character │ │ │
│ │ │ • Set index │ │ • Sleep 0.1s │ │ • Print message │ │ │
│ │ │ • Start loop │ │ • Increment │ │ • Clear line │ │ │
│ │ │ │ │ index │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ STOP_SPINNER() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Get Spinner │ │ Kill Process │ │ Cleanup │ │ │
│ │ │ PID │ │ │ │ │ │ │
│ │ │ │ │ • Send TERM │ │ • Remove PID file │ │ │
│ │ │ • From │ │ • Wait for │ │ • Unset variables │ │ │
│ │ │ SPINNER_PID │ │ termination │ │ • Reset terminal │ │ │
│ │ │ • From PID │ │ • Force kill │ │ settings │ │ │
│ │ │ file │ │ if needed │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Silent Execution Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SILENT() Execution Flow │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Command Execution │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Setup │ │ Execute │ │ Capture Output │ │ │
│ │ │ Environment │ │ Command │ │ │ │ │
│ │ │ │ │ │ │ • Redirect stdout │ │ │
│ │ │ • Disable │ │ • Run command │ │ to log file │ │ │
│ │ │ error │ │ • Capture │ │ • Redirect stderr │ │ │
│ │ │ handling │ │ return code │ │ to log file │ │ │
│ │ │ • Remove │ │ • Store exit │ │ • Log all output │ │ │
│ │ │ traps │ │ code │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Error Handling │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check Exit │ │ Load Error │ │ Display Error │ │ │
│ │ │ Code │ │ Handler │ │ Information │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • If exit code │ │ • Source │ │ • Show error code │ │ │
│ │ │ != 0 │ │ error_handler │ │ • Show explanation │ │ │
│ │ │ • Proceed to │ │ if needed │ │ • Show command │ │ │
│ │ │ error │ │ • Get error │ │ • Show log lines │ │ │
│ │ │ handling │ │ explanation │ │ • Show full log │ │ │
│ │ │ │ │ │ │ command │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Log Management │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Log File │ │ Log Display │ │ Log Access │ │ │
│ │ │ Management │ │ │ │ │ │ │
│ │ │ │ │ • Show last 10 │ │ • Provide command │ │ │
│ │ │ • Create log │ │ lines │ │ to view full log │ │ │
│ │ │ file path │ │ • Count total │ │ • Show line count │ │ │
│ │ │ • Use process │ │ lines │ │ • Enable debugging │ │ │
│ │ │ ID in name │ │ • Format │ │ │ │ │
│ │ │ │ │ output │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Header Management Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Header Management Flow │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ GET_HEADER() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Prepare │ │ Check Local │ │ Download Header │ │ │
│ │ │ Parameters │ │ File │ │ │ │ │
│ │ │ │ │ │ │ • Construct URL │ │ │
│ │ │ • Get app name │ │ • Check if │ │ • Download file │ │ │
│ │ │ from APP │ │ file exists │ │ • Save to local │ │ │
│ │ │ • Get app type │ │ • Check if │ │ path │ │ │
│ │ │ from APP_TYPE │ │ file has │ │ • Return success │ │ │
│ │ │ • Construct │ │ content │ │ status │ │ │
│ │ │ paths │ │ • Return if │ │ │ │ │
│ │ │ │ │ available │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ HEADER_INFO() │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Get Header │ │ Clear Screen │ │ Display Header │ │ │
│ │ │ Content │ │ │ │ │ │ │
│ │ │ │ │ • Clear │ │ • Show header │ │ │
│ │ │ • Call │ │ terminal │ │ content if │ │ │
│ │ │ get_header() │ │ • Get terminal │ │ available │ │ │
│ │ │ • Handle │ │ width │ │ • Format output │ │ │
│ │ │ errors │ │ • Set default │ │ • Center content │ │ │
│ │ │ • Return │ │ width if │ │ if possible │ │ │
│ │ │ content │ │ needed │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Swap Management Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CHECK_OR_CREATE_SWAP() Flow │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Swap Detection │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check Active │ │ Swap Found │ │ No Swap Found │ │ │
│ │ │ Swap │ │ │ │ │ │ │
│ │ │ │ │ • Show success │ │ • Show error │ │ │
│ │ │ • Use swapon │ │ message │ │ message │ │ │
│ │ │ command │ │ • Return 0 │ │ • Ask user for │ │ │
│ │ │ • Check for │ │ │ │ creation │ │ │
│ │ │ swap devices │ │ │ │ • Proceed to │ │ │
│ │ │ • Return │ │ │ │ creation flow │ │ │
│ │ │ status │ │ │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Swap Creation │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ User Input │ │ Size │ │ File Creation │ │ │
│ │ │ Collection │ │ Validation │ │ │ │ │
│ │ │ │ │ │ │ • Create swap file │ │ │
│ │ │ • Ask for │ │ • Validate │ │ with dd │ │ │
│ │ │ confirmation │ │ numeric input │ │ • Set permissions │ │ │
│ │ │ • Convert to │ │ • Check range │ │ • Format swap │ │ │
│ │ │ lowercase │ │ • Abort if │ │ • Activate swap │ │ │
│ │ │ • Check for │ │ invalid │ │ • Show success │ │ │
│ │ │ y/yes │ │ │ │ message │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Integration Points
### With Other Scripts
- **build.func**: Provides system checks and UI functions
- **tools.func**: Uses core utilities for extended operations
- **api.func**: Uses system checks and error handling
- **error_handler.func**: Provides error explanations for silent execution
### External Dependencies
- **curl**: For downloading header files
- **tput**: For terminal control (installed if missing)
- **swapon/mkswap**: For swap management
- **pveversion**: For Proxmox version checking
### Data Flow
- **Input**: Environment variables, command parameters
- **Processing**: System validation, UI rendering, command execution
- **Output**: Messages, log files, exit codes, system state changes

637
docs/misc/core.func/CORE_FUNCTIONS_REFERENCE.md Normal file
View File

@ -0,0 +1,637 @@
# core.func Functions Reference
## Overview
This document provides a comprehensive alphabetical reference of all functions in `core.func`, including parameters, dependencies, usage examples, and error handling.
## Function Categories
### Initialization Functions
#### `load_functions()`
**Purpose**: Main function loader that initializes all core utilities
**Parameters**: None
**Returns**: None
**Side Effects**:
- Sets `__FUNCTIONS_LOADED=1` to prevent reloading
- Calls all core function groups in sequence
- Initializes color, formatting, icons, defaults, and standard mode
**Dependencies**: None
**Environment Variables Used**: `__FUNCTIONS_LOADED`
**Usage Example**:
```bash
# Automatically called when core.func is sourced
source core.func
# load_functions() is called automatically
```
### Color and Formatting Functions
#### `color()`
**Purpose**: Set ANSI color codes for styled terminal output
**Parameters**: None
**Returns**: None
**Side Effects**: Sets global color variables
**Dependencies**: None
**Environment Variables Used**: None
**Sets Variables**:
- `YW`: Yellow
- `YWB`: Bright yellow
- `BL`: Blue
- `RD`: Red
- `BGN`: Bright green
- `GN`: Green
- `DGN`: Dark green
- `CL`: Clear/reset
**Usage Example**:
```bash
color
echo -e "${GN}Success message${CL}"
echo -e "${RD}Error message${CL}"
```
#### `color_spinner()`
**Purpose**: Set color codes specifically for spinner output
**Parameters**: None
**Returns**: None
**Side Effects**: Sets spinner-specific color variables
**Dependencies**: None
**Environment Variables Used**: None
**Sets Variables**:
- `CS_YW`: Yellow for spinner
- `CS_YWB`: Bright yellow for spinner
- `CS_CL`: Clear for spinner
#### `formatting()`
**Purpose**: Define formatting helpers for terminal output
**Parameters**: None
**Returns**: None
**Side Effects**: Sets global formatting variables
**Dependencies**: None
**Environment Variables Used**: None
**Sets Variables**:
- `BFR`: Back and forward reset
- `BOLD`: Bold text
- `HOLD`: Space character
- `TAB`: Two spaces
- `TAB3`: Six spaces
### Icon Functions
#### `icons()`
**Purpose**: Set symbolic icons used throughout user feedback and prompts
**Parameters**: None
**Returns**: None
**Side Effects**: Sets global icon variables
**Dependencies**: `formatting()` (for TAB variable)
**Environment Variables Used**: `TAB`, `CL`
**Sets Variables**:
- `CM`: Check mark
- `CROSS`: Cross mark
- `DNSOK`: DNS success
- `DNSFAIL`: DNS failure
- `INFO`: Information icon
- `OS`: Operating system icon
- `OSVERSION`: OS version icon
- `CONTAINERTYPE`: Container type icon
- `DISKSIZE`: Disk size icon
- `CPUCORE`: CPU core icon
- `RAMSIZE`: RAM size icon
- `SEARCH`: Search icon
- `VERBOSE_CROPPED`: Verbose mode icon
- `VERIFYPW`: Password verification icon
- `CONTAINERID`: Container ID icon
- `HOSTNAME`: Hostname icon
- `BRIDGE`: Bridge icon
- `NETWORK`: Network icon
- `GATEWAY`: Gateway icon
- `DISABLEIPV6`: IPv6 disable icon
- `DEFAULT`: Default settings icon
- `MACADDRESS`: MAC address icon
- `VLANTAG`: VLAN tag icon
- `ROOTSSH`: SSH key icon
- `CREATING`: Creating icon
- `ADVANCED`: Advanced settings icon
- `FUSE`: FUSE icon
- `HOURGLASS`: Hourglass icon
### Default Variables Functions
#### `default_vars()`
**Purpose**: Set default retry and wait variables for system actions
**Parameters**: None
**Returns**: None
**Side Effects**: Sets retry configuration variables
**Dependencies**: None
**Environment Variables Used**: None
**Sets Variables**:
- `RETRY_NUM`: Number of retry attempts (default: 10)
- `RETRY_EVERY`: Seconds between retries (default: 3)
- `i`: Retry counter initialized to RETRY_NUM
#### `set_std_mode()`
**Purpose**: Set default verbose mode for script execution
**Parameters**: None
**Returns**: None
**Side Effects**: Sets STD variable based on VERBOSE setting
**Dependencies**: None
**Environment Variables Used**: `VERBOSE`
**Sets Variables**:
- `STD`: "silent" if VERBOSE != "yes", empty string if VERBOSE = "yes"
### Silent Execution Functions
#### `silent()`
**Purpose**: Execute commands silently with detailed error reporting
**Parameters**: `$*` - Command and arguments to execute
**Returns**: None (exits on error)
**Side Effects**:
- Executes command with output redirected to log file
- On error, displays detailed error information
- Exits with command's exit code
**Dependencies**: `error_handler.func` (for error explanations)
**Environment Variables Used**: `SILENT_LOGFILE`
**Usage Example**:
```bash
silent apt-get update
silent apt-get install -y package-name
```
**Error Handling**:
- Captures command output to `/tmp/silent.$$.log`
- Shows error code explanation
- Displays last 10 lines of log
- Provides command to view full log
### System Check Functions
#### `shell_check()`
**Purpose**: Verify that the script is running in Bash shell
**Parameters**: None
**Returns**: None (exits if not Bash)
**Side Effects**:
- Checks current shell process
- Exits with error message if not Bash
**Dependencies**: None
**Environment Variables Used**: None
**Usage Example**:
```bash
shell_check
# Script continues if Bash, exits if not
```
#### `root_check()`
**Purpose**: Ensure script is running as root user
**Parameters**: None
**Returns**: None (exits if not root)
**Side Effects**:
- Checks user ID and parent process
- Exits with error message if not root
**Dependencies**: None
**Environment Variables Used**: None
**Usage Example**:
```bash
root_check
# Script continues if root, exits if not
```
#### `pve_check()`
**Purpose**: Verify Proxmox VE version compatibility
**Parameters**: None
**Returns**: None (exits if unsupported version)
**Side Effects**:
- Checks PVE version using pveversion command
- Exits with error message if unsupported
**Dependencies**: `pveversion` command
**Environment Variables Used**: None
**Supported Versions**:
- Proxmox VE 8.0 - 8.9
- Proxmox VE 9.0 (only)
**Usage Example**:
```bash
pve_check
# Script continues if supported version, exits if not
```
#### `arch_check()`
**Purpose**: Verify system architecture is AMD64
**Parameters**: None
**Returns**: None (exits if not AMD64)
**Side Effects**:
- Checks system architecture
- Exits with PiMox warning if not AMD64
**Dependencies**: `dpkg` command
**Environment Variables Used**: None
**Usage Example**:
```bash
arch_check
# Script continues if AMD64, exits if not
```
#### `ssh_check()`
**Purpose**: Detect and warn about external SSH usage
**Parameters**: None
**Returns**: None
**Side Effects**:
- Checks SSH_CLIENT environment variable
- Warns if connecting from external IP
- Allows local connections (127.0.0.1 or host IP)
**Dependencies**: None
**Environment Variables Used**: `SSH_CLIENT`
**Usage Example**:
```bash
ssh_check
# Shows warning if external SSH, continues anyway
```
### Header Management Functions
#### `get_header()`
**Purpose**: Download and cache application header files
**Parameters**: None (uses APP and APP_TYPE variables)
**Returns**: Header content on success, empty on failure
**Side Effects**:
- Downloads header from remote URL
- Caches header locally
- Creates directory structure if needed
**Dependencies**: `curl` command
**Environment Variables Used**: `APP`, `APP_TYPE`
**Usage Example**:
```bash
export APP="plex"
export APP_TYPE="ct"
header_content=$(get_header)
```
#### `header_info()`
**Purpose**: Display application header information
**Parameters**: None (uses APP variable)
**Returns**: None
**Side Effects**:
- Clears screen
- Displays header content
- Gets terminal width for formatting
**Dependencies**: `get_header()`, `tput` command
**Environment Variables Used**: `APP`
**Usage Example**:
```bash
export APP="plex"
header_info
# Displays Plex header information
```
### Utility Functions
#### `ensure_tput()`
**Purpose**: Ensure tput command is available for terminal control
**Parameters**: None
**Returns**: None
**Side Effects**:
- Installs ncurses package if tput missing
- Works on Alpine and Debian-based systems
**Dependencies**: `apk` or `apt-get` package managers
**Environment Variables Used**: None
**Usage Example**:
```bash
ensure_tput
# Installs ncurses if needed, continues if already available
```
#### `is_alpine()`
**Purpose**: Detect if running on Alpine Linux
**Parameters**: None
**Returns**: 0 if Alpine, 1 if not Alpine
**Side Effects**: None
**Dependencies**: None
**Environment Variables Used**: `var_os`, `PCT_OSTYPE`
**Usage Example**:
```bash
if is_alpine; then
echo "Running on Alpine Linux"
else
echo "Not running on Alpine Linux"
fi
```
#### `is_verbose_mode()`
**Purpose**: Check if verbose mode is enabled
**Parameters**: None
**Returns**: 0 if verbose mode, 1 if not verbose
**Side Effects**: None
**Dependencies**: None
**Environment Variables Used**: `VERBOSE`, `var_verbose`
**Usage Example**:
```bash
if is_verbose_mode; then
echo "Verbose mode enabled"
else
echo "Verbose mode disabled"
fi
```
#### `fatal()`
**Purpose**: Display fatal error and terminate script
**Parameters**: `$1` - Error message
**Returns**: None (terminates script)
**Side Effects**:
- Displays error message
- Sends INT signal to current process
**Dependencies**: `msg_error()`
**Environment Variables Used**: None
**Usage Example**:
```bash
fatal "Critical error occurred"
# Script terminates after displaying error
```
### Spinner Functions
#### `spinner()`
**Purpose**: Display animated spinner for progress indication
**Parameters**: None (uses SPINNER_MSG variable)
**Returns**: None (runs indefinitely)
**Side Effects**:
- Displays rotating spinner characters
- Uses terminal control sequences
**Dependencies**: `color_spinner()`
**Environment Variables Used**: `SPINNER_MSG`
**Usage Example**:
```bash
SPINNER_MSG="Processing..."
spinner &
SPINNER_PID=$!
# Spinner runs in background
```
#### `clear_line()`
**Purpose**: Clear current terminal line
**Parameters**: None
**Returns**: None
**Side Effects**: Clears current line using terminal control
**Dependencies**: `tput` command
**Environment Variables Used**: None
#### `stop_spinner()`
**Purpose**: Stop running spinner and cleanup
**Parameters**: None
**Returns**: None
**Side Effects**:
- Kills spinner process
- Removes PID file
- Resets terminal settings
- Unsets spinner variables
**Dependencies**: None
**Environment Variables Used**: `SPINNER_PID`, `SPINNER_MSG`
**Usage Example**:
```bash
stop_spinner
# Stops spinner and cleans up
```
### Message Functions
#### `msg_info()`
**Purpose**: Display informational message with spinner
**Parameters**: `$1` - Message text
**Returns**: None
**Side Effects**:
- Starts spinner if not in verbose mode
- Tracks shown messages to prevent duplicates
- Displays message with hourglass icon in verbose mode
**Dependencies**: `spinner()`, `is_verbose_mode()`, `is_alpine()`
**Environment Variables Used**: `MSG_INFO_SHOWN`
**Usage Example**:
```bash
msg_info "Installing package..."
# Shows spinner with message
```
#### `msg_ok()`
**Purpose**: Display success message
**Parameters**: `$1` - Success message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays green checkmark with message
- Removes message from shown tracking
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: `MSG_INFO_SHOWN`
**Usage Example**:
```bash
msg_ok "Package installed successfully"
# Shows green checkmark with message
```
#### `msg_error()`
**Purpose**: Display error message
**Parameters**: `$1` - Error message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays red cross with message
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: None
**Usage Example**:
```bash
msg_error "Installation failed"
# Shows red cross with message
```
#### `msg_warn()`
**Purpose**: Display warning message
**Parameters**: `$1` - Warning message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays yellow info icon with message
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: None
**Usage Example**:
```bash
msg_warn "This operation may take some time"
# Shows yellow info icon with message
```
#### `msg_custom()`
**Purpose**: Display custom message with specified symbol and color
**Parameters**:
- `$1` - Custom symbol (default: "[*]")
- `$2` - Color code (default: "\e[36m")
- `$3` - Message text
**Returns**: None
**Side Effects**:
- Stops spinner
- Displays custom formatted message
**Dependencies**: `stop_spinner()`
**Environment Variables Used**: None
**Usage Example**:
```bash
msg_custom "⚡" "\e[33m" "Custom warning message"
# Shows custom symbol and color with message
```
#### `msg_debug()`
**Purpose**: Display debug message if debug mode enabled
**Parameters**: `$*` - Debug message text
**Returns**: None
**Side Effects**:
- Only displays if var_full_verbose is set
- Shows timestamp and debug prefix
**Dependencies**: None
**Environment Variables Used**: `var_full_verbose`, `var_verbose`
**Usage Example**:
```bash
export var_full_verbose=1
msg_debug "Debug information here"
# Shows debug message with timestamp
```
### System Management Functions
#### `check_or_create_swap()`
**Purpose**: Check for active swap and optionally create swap file
**Parameters**: None
**Returns**: 0 if swap exists or created, 1 if skipped
**Side Effects**:
- Checks for active swap
- Prompts user to create swap if none found
- Creates swap file if user confirms
**Dependencies**: `swapon`, `dd`, `mkswap` commands
**Environment Variables Used**: None
**Usage Example**:
```bash
if check_or_create_swap; then
echo "Swap is available"
else
echo "No swap available"
fi
```
## Function Call Hierarchy
### Initialization Flow
```
load_functions()
├── color()
├── formatting()
├── icons()
├── default_vars()
└── set_std_mode()
```
### Message System Flow
```
msg_info()
├── is_verbose_mode()
├── is_alpine()
├── spinner()
└── color_spinner()
msg_ok()
├── stop_spinner()
└── clear_line()
msg_error()
└── stop_spinner()
msg_warn()
└── stop_spinner()
```
### System Check Flow
```
pve_check()
├── pveversion command
└── version parsing
arch_check()
├── dpkg command
└── architecture check
shell_check()
├── ps command
└── shell detection
root_check()
├── id command
└── parent process check
```
### Silent Execution Flow
```
silent()
├── Command execution
├── Output redirection
├── Error handling
├── error_handler.func loading
└── Log management
```
## Error Handling Patterns
### System Check Errors
- All system check functions exit with appropriate error messages
- Clear indication of what's wrong and how to fix it
- Graceful exit with sleep delay for user to read message
### Silent Execution Errors
- Commands executed via `silent()` capture output to log file
- On failure, displays error code explanation
- Shows last 10 lines of log output
- Provides command to view full log
### Spinner Errors
- Spinner functions handle process cleanup on exit
- Trap handlers ensure spinners are stopped
- Terminal settings are restored on error
## Environment Variable Dependencies
### Required Variables
- `APP`: Application name for header display
- `APP_TYPE`: Application type (ct/vm) for header paths
- `VERBOSE`: Verbose mode setting
### Optional Variables
- `var_os`: OS type for Alpine detection
- `PCT_OSTYPE`: Alternative OS type variable
- `var_verbose`: Alternative verbose setting
- `var_full_verbose`: Debug mode setting
### Internal Variables
- `_CORE_FUNC_LOADED`: Prevents multiple loading
- `__FUNCTIONS_LOADED`: Prevents multiple function loading
- `SILENT_LOGFILE`: Silent execution log file path
- `SPINNER_PID`: Spinner process ID
- `SPINNER_MSG`: Spinner message text
- `MSG_INFO_SHOWN`: Tracks shown info messages

517
docs/misc/core.func/CORE_INTEGRATION.md Normal file
View File

@ -0,0 +1,517 @@
# core.func Integration Guide
## Overview
This document describes how `core.func` integrates with other components in the Proxmox Community Scripts project, including dependencies, data flow, and API surface.
## Dependencies
### External Dependencies
#### Required Commands
- **`pveversion`**: Proxmox VE version checking
- **`dpkg`**: Architecture detection
- **`ps`**: Process and shell detection
- **`id`**: User ID checking
- **`curl`**: Header file downloading
- **`swapon`**: Swap status checking
- **`dd`**: Swap file creation
- **`mkswap`**: Swap file formatting
#### Optional Commands
- **`tput`**: Terminal control (installed if missing)
- **`apk`**: Alpine package manager
- **`apt-get`**: Debian package manager
### Internal Dependencies
#### error_handler.func
- **Purpose**: Provides error code explanations for silent execution
- **Usage**: Automatically loaded when `silent()` encounters errors
- **Integration**: Called via `explain_exit_code()` function
- **Data Flow**: Error code → explanation → user display
## Integration Points
### With build.func
#### System Validation
```bash
# build.func uses core.func for system checks
source core.func
pve_check
arch_check
shell_check
root_check
```
#### User Interface
```bash
# build.func uses core.func for UI elements
msg_info "Creating container..."
msg_ok "Container created successfully"
msg_error "Container creation failed"
```
#### Silent Execution
```bash
# build.func uses core.func for command execution
silent pct create "$CTID" "$TEMPLATE" \
--hostname "$HOSTNAME" \
--memory "$MEMORY" \
--cores "$CORES"
```
### With tools.func
#### Utility Functions
```bash
# tools.func uses core.func utilities
source core.func
# System checks
pve_check
root_check
# UI elements
msg_info "Running maintenance tasks..."
msg_ok "Maintenance completed"
```
#### Error Handling
```bash
# tools.func uses core.func for error handling
if silent systemctl restart service; then
msg_ok "Service restarted"
else
msg_error "Service restart failed"
fi
```
### With api.func
#### System Validation
```bash
# api.func uses core.func for system checks
source core.func
pve_check
root_check
```
#### API Operations
```bash
# api.func uses core.func for API calls
msg_info "Connecting to Proxmox API..."
if silent curl -k -H "Authorization: PVEAPIToken=$API_TOKEN" \
"$API_URL/api2/json/nodes/$NODE/lxc"; then
msg_ok "API connection successful"
else
msg_error "API connection failed"
fi
```
### With error_handler.func
#### Error Explanations
```bash
# error_handler.func provides explanations for core.func
explain_exit_code() {
local code="$1"
case "$code" in
1) echo "General error" ;;
2) echo "Misuse of shell builtins" ;;
126) echo "Command invoked cannot execute" ;;
127) echo "Command not found" ;;
128) echo "Invalid argument to exit" ;;
*) echo "Unknown error code" ;;
esac
}
```
### With install.func
#### Installation Process
```bash
# install.func uses core.func for installation
source core.func
# System checks
pve_check
root_check
# Installation steps
msg_info "Installing packages..."
silent apt-get update
silent apt-get install -y package
msg_ok "Installation completed"
```
### With alpine-install.func
#### Alpine-Specific Operations
```bash
# alpine-install.func uses core.func for Alpine operations
source core.func
# Alpine detection
if is_alpine; then
msg_info "Detected Alpine Linux"
silent apk add --no-cache package
else
msg_info "Detected Debian-based system"
silent apt-get install -y package
fi
```
### With alpine-tools.func
#### Alpine Utilities
```bash
# alpine-tools.func uses core.func for Alpine tools
source core.func
# Alpine-specific operations
if is_alpine; then
msg_info "Running Alpine-specific operations..."
# Alpine tools logic
msg_ok "Alpine operations completed"
fi
```
### With passthrough.func
#### Hardware Passthrough
```bash
# passthrough.func uses core.func for hardware operations
source core.func
# System checks
pve_check
root_check
# Hardware operations
msg_info "Configuring GPU passthrough..."
if silent lspci | grep -i nvidia; then
msg_ok "NVIDIA GPU detected"
else
msg_warn "No NVIDIA GPU found"
fi
```
### With vm-core.func
#### VM Operations
```bash
# vm-core.func uses core.func for VM management
source core.func
# System checks
pve_check
root_check
# VM operations
msg_info "Creating virtual machine..."
silent qm create "$VMID" \
--name "$VMNAME" \
--memory "$MEMORY" \
--cores "$CORES"
msg_ok "Virtual machine created"
```
## Data Flow
### Input Data
#### Environment Variables
- **`APP`**: Application name for header display
- **`APP_TYPE`**: Application type (ct/vm) for header paths
- **`VERBOSE`**: Verbose mode setting
- **`var_os`**: OS type for Alpine detection
- **`PCT_OSTYPE`**: Alternative OS type variable
- **`var_verbose`**: Alternative verbose setting
- **`var_full_verbose`**: Debug mode setting
#### Command Parameters
- **Function arguments**: Passed to individual functions
- **Command arguments**: Passed to `silent()` function
- **User input**: Collected via `read` commands
### Processing Data
#### System Information
- **Proxmox version**: Parsed from `pveversion` output
- **Architecture**: Retrieved from `dpkg --print-architecture`
- **Shell type**: Detected from process information
- **User ID**: Retrieved from `id -u`
- **SSH connection**: Detected from `SSH_CLIENT` environment
#### UI State
- **Message tracking**: `MSG_INFO_SHOWN` associative array
- **Spinner state**: `SPINNER_PID` and `SPINNER_MSG` variables
- **Terminal state**: Cursor position and display mode
#### Error Information
- **Exit codes**: Captured from command execution
- **Log output**: Redirected to temporary log files
- **Error explanations**: Retrieved from error_handler.func
### Output Data
#### User Interface
- **Colored messages**: ANSI color codes for terminal output
- **Icons**: Symbolic representations for different message types
- **Spinners**: Animated progress indicators
- **Formatted text**: Consistent message formatting
#### System State
- **Exit codes**: Returned from functions
- **Log files**: Created for silent execution
- **Configuration**: Modified system settings
- **Process state**: Spinner processes and cleanup
## API Surface
### Public Functions
#### System Validation
- **`pve_check()`**: Proxmox VE version validation
- **`arch_check()`**: Architecture validation
- **`shell_check()`**: Shell validation
- **`root_check()`**: Privilege validation
- **`ssh_check()`**: SSH connection warning
#### User Interface
- **`msg_info()`**: Informational messages
- **`msg_ok()`**: Success messages
- **`msg_error()`**: Error messages
- **`msg_warn()`**: Warning messages
- **`msg_custom()`**: Custom messages
- **`msg_debug()`**: Debug messages
#### Spinner Control
- **`spinner()`**: Start spinner animation
- **`stop_spinner()`**: Stop spinner and cleanup
- **`clear_line()`**: Clear current terminal line
#### Silent Execution
- **`silent()`**: Execute commands with error handling
#### Utility Functions
- **`is_alpine()`**: Alpine Linux detection
- **`is_verbose_mode()`**: Verbose mode detection
- **`fatal()`**: Fatal error handling
- **`ensure_tput()`**: Terminal control setup
#### Header Management
- **`get_header()`**: Download application headers
- **`header_info()`**: Display header information
#### System Management
- **`check_or_create_swap()`**: Swap file management
### Internal Functions
#### Initialization
- **`load_functions()`**: Function loader
- **`color()`**: Color setup
- **`formatting()`**: Formatting setup
- **`icons()`**: Icon setup
- **`default_vars()`**: Default variables
- **`set_std_mode()`**: Standard mode setup
#### Color Management
- **`color_spinner()`**: Spinner colors
### Global Variables
#### Color Variables
- **`YW`**, **`YWB`**, **`BL`**, **`RD`**, **`BGN`**, **`GN`**, **`DGN`**, **`CL`**: Color codes
- **`CS_YW`**, **`CS_YWB`**, **`CS_CL`**: Spinner colors
#### Formatting Variables
- **`BFR`**, **`BOLD`**, **`HOLD`**, **`TAB`**, **`TAB3`**: Formatting helpers
#### Icon Variables
- **`CM`**, **`CROSS`**, **`INFO`**, **`OS`**, **`OSVERSION`**, etc.: Message icons
#### Configuration Variables
- **`RETRY_NUM`**, **`RETRY_EVERY`**: Retry settings
- **`STD`**: Standard mode setting
- **`SILENT_LOGFILE`**: Log file path
#### State Variables
- **`_CORE_FUNC_LOADED`**: Loading prevention
- **`__FUNCTIONS_LOADED`**: Function loading prevention
- **`SPINNER_PID`**, **`SPINNER_MSG`**: Spinner state
- **`MSG_INFO_SHOWN`**: Message tracking
## Integration Patterns
### Standard Integration Pattern
```bash
#!/usr/bin/env bash
# Standard integration pattern
# 1. Source core.func first
source core.func
# 2. Run system checks
pve_check
arch_check
shell_check
root_check
# 3. Set up error handling
trap 'stop_spinner' EXIT INT TERM
# 4. Use UI functions
msg_info "Starting operation..."
# 5. Use silent execution
silent command
# 6. Show completion
msg_ok "Operation completed"
```
### Minimal Integration Pattern
```bash
#!/usr/bin/env bash
# Minimal integration pattern
source core.func
pve_check
root_check
msg_info "Running operation..."
silent command
msg_ok "Operation completed"
```
### Advanced Integration Pattern
```bash
#!/usr/bin/env bash
# Advanced integration pattern
source core.func
# System validation
pve_check
arch_check
shell_check
root_check
ssh_check
# Error handling
trap 'stop_spinner' EXIT INT TERM
# Verbose mode handling
if is_verbose_mode; then
msg_info "Verbose mode enabled"
fi
# OS-specific operations
if is_alpine; then
msg_info "Alpine Linux detected"
# Alpine-specific logic
else
msg_info "Debian-based system detected"
# Debian-specific logic
fi
# Operation execution
msg_info "Starting operation..."
if silent command; then
msg_ok "Operation succeeded"
else
msg_error "Operation failed"
exit 1
fi
```
## Error Handling Integration
### Silent Execution Error Flow
```
silent() command
├── Execute command
├── Capture output to log
├── Check exit code
├── If error:
│ ├── Load error_handler.func
│ ├── Get error explanation
│ ├── Display error details
│ ├── Show log excerpt
│ └── Exit with error code
└── If success: Continue
```
### System Check Error Flow
```
System Check Function
├── Check system state
├── If valid: Return 0
└── If invalid:
├── Display error message
├── Show fix instructions
├── Sleep for user to read
└── Exit with error code
```
## Performance Considerations
### Loading Optimization
- **Single Loading**: `_CORE_FUNC_LOADED` prevents multiple loading
- **Function Loading**: `__FUNCTIONS_LOADED` prevents multiple function loading
- **Lazy Loading**: Functions loaded only when needed
### Memory Usage
- **Minimal Footprint**: Core functions use minimal memory
- **Variable Reuse**: Global variables reused across functions
- **Cleanup**: Spinner processes cleaned up on exit
### Execution Speed
- **Fast Checks**: System checks are optimized for speed
- **Efficient Spinners**: Spinner animation uses minimal CPU
- **Quick Messages**: Message functions optimized for performance
## Security Considerations
### Privilege Escalation
- **Root Check**: Ensures script runs with sufficient privileges
- **Shell Check**: Validates shell environment
- **Process Validation**: Checks parent process for sudo usage
### Input Validation
- **Parameter Checking**: Functions validate input parameters
- **Error Handling**: Proper error handling prevents crashes
- **Safe Execution**: Silent execution with proper error handling
### System Protection
- **Version Validation**: Ensures compatible Proxmox version
- **Architecture Check**: Prevents execution on unsupported systems
- **SSH Warning**: Warns about external SSH usage
## Future Integration Considerations
### Extensibility
- **Function Groups**: Easy to add new function groups
- **Message Types**: Easy to add new message types
- **System Checks**: Easy to add new system checks
### Compatibility
- **Version Support**: Easy to add new Proxmox versions
- **OS Support**: Easy to add new operating systems
- **Architecture Support**: Easy to add new architectures
### Performance
- **Optimization**: Functions can be optimized for better performance
- **Caching**: Results can be cached for repeated operations
- **Parallelization**: Operations can be parallelized where appropriate

728
docs/misc/core.func/CORE_USAGE_EXAMPLES.md Normal file
View File

@ -0,0 +1,728 @@
# core.func Usage Examples
## Overview
This document provides practical usage examples for `core.func` functions, covering common scenarios, integration patterns, and best practices.
## Basic Script Setup
### Standard Script Initialization
```bash
#!/usr/bin/env bash
# Standard script setup using core.func
# Source core functions
source core.func
# Run system checks
pve_check
arch_check
shell_check
root_check
# Optional: Check SSH connection
ssh_check
# Set up error handling
trap 'stop_spinner' EXIT INT TERM
# Your script logic here
msg_info "Starting script execution"
# ... script code ...
msg_ok "Script completed successfully"
```
### Minimal Script Setup
```bash
#!/usr/bin/env bash
# Minimal setup for simple scripts
source core.func
# Basic checks only
pve_check
root_check
# Simple execution
msg_info "Running operation"
# ... your code ...
msg_ok "Operation completed"
```
## Message Display Examples
### Progress Indication
```bash
#!/usr/bin/env bash
source core.func
# Show progress with spinner
msg_info "Downloading package..."
sleep 2
msg_ok "Download completed"
msg_info "Installing package..."
sleep 3
msg_ok "Installation completed"
msg_info "Configuring service..."
sleep 1
msg_ok "Configuration completed"
```
### Error Handling
```bash
#!/usr/bin/env bash
source core.func
# Function with error handling
install_package() {
local package="$1"
msg_info "Installing $package..."
if silent apt-get install -y "$package"; then
msg_ok "$package installed successfully"
return 0
else
msg_error "Failed to install $package"
return 1
fi
}
# Usage
if install_package "nginx"; then
msg_ok "Nginx installation completed"
else
msg_error "Nginx installation failed"
exit 1
fi
```
### Warning Messages
```bash
#!/usr/bin/env bash
source core.func
# Show warnings for potentially dangerous operations
msg_warn "This will modify system configuration"
read -p "Continue? [y/N]: " confirm
if [[ "$confirm" =~ ^[yY]$ ]]; then
msg_info "Proceeding with modification..."
# ... dangerous operation ...
msg_ok "Modification completed"
else
msg_info "Operation cancelled"
fi
```
### Custom Messages
```bash
#!/usr/bin/env bash
source core.func
# Custom message with specific icon and color
msg_custom "🚀" "\e[32m" "Launching application"
msg_custom "⚡" "\e[33m" "High performance mode enabled"
msg_custom "🔒" "\e[31m" "Security mode activated"
```
### Debug Messages
```bash
#!/usr/bin/env bash
source core.func
# Enable debug mode
export var_full_verbose=1
# Debug messages
msg_debug "Variable value: $some_variable"
msg_debug "Function called: $FUNCNAME"
msg_debug "Current directory: $(pwd)"
```
## Silent Execution Examples
### Package Management
```bash
#!/usr/bin/env bash
source core.func
# Update package lists
msg_info "Updating package lists..."
silent apt-get update
# Install packages
msg_info "Installing required packages..."
silent apt-get install -y curl wget git
# Upgrade packages
msg_info "Upgrading packages..."
silent apt-get upgrade -y
msg_ok "Package management completed"
```
### File Operations
```bash
#!/usr/bin/env bash
source core.func
# Create directories
msg_info "Creating directory structure..."
silent mkdir -p /opt/myapp/{config,logs,data}
# Set permissions
msg_info "Setting permissions..."
silent chmod 755 /opt/myapp
silent chmod 644 /opt/myapp/config/*
# Copy files
msg_info "Copying configuration files..."
silent cp config/* /opt/myapp/config/
msg_ok "File operations completed"
```
### Service Management
```bash
#!/usr/bin/env bash
source core.func
# Start service
msg_info "Starting service..."
silent systemctl start myservice
# Enable service
msg_info "Enabling service..."
silent systemctl enable myservice
# Check service status
msg_info "Checking service status..."
if silent systemctl is-active --quiet myservice; then
msg_ok "Service is running"
else
msg_error "Service failed to start"
fi
```
### Network Operations
```bash
#!/usr/bin/env bash
source core.func
# Test network connectivity
msg_info "Testing network connectivity..."
if silent ping -c 1 8.8.8.8; then
msg_ok "Network connectivity confirmed"
else
msg_error "Network connectivity failed"
fi
# Download files
msg_info "Downloading configuration..."
silent curl -fsSL https://example.com/config -o /tmp/config
# Extract archives
msg_info "Extracting archive..."
silent tar -xzf /tmp/archive.tar.gz -C /opt/
```
## System Check Examples
### Comprehensive System Validation
```bash
#!/usr/bin/env bash
source core.func
# Complete system validation
validate_system() {
msg_info "Validating system requirements..."
# Check Proxmox version
if pve_check; then
msg_ok "Proxmox VE version is supported"
fi
# Check architecture
if arch_check; then
msg_ok "System architecture is supported"
fi
# Check shell
if shell_check; then
msg_ok "Shell environment is correct"
fi
# Check privileges
if root_check; then
msg_ok "Running with sufficient privileges"
fi
# Check SSH connection
ssh_check
msg_ok "System validation completed"
}
# Run validation
validate_system
```
### Conditional System Checks
```bash
#!/usr/bin/env bash
source core.func
# Check if running in container
if [[ -f /.dockerenv ]] || [[ -f /run/.containerenv ]]; then
msg_warn "Running inside container"
# Skip some checks
else
# Full system checks
pve_check
arch_check
fi
# Always check shell and privileges
shell_check
root_check
```
## Header Management Examples
### Application Header Display
```bash
#!/usr/bin/env bash
source core.func
# Set application information
export APP="plex"
export APP_TYPE="ct"
# Display header
header_info
# Continue with application setup
msg_info "Setting up Plex Media Server..."
```
### Custom Header Handling
```bash
#!/usr/bin/env bash
source core.func
# Get header content
export APP="nextcloud"
export APP_TYPE="ct"
header_content=$(get_header)
if [[ -n "$header_content" ]]; then
echo "Header found:"
echo "$header_content"
else
msg_warn "No header found for $APP"
fi
```
## Swap Management Examples
### Interactive Swap Creation
```bash
#!/usr/bin/env bash
source core.func
# Check and create swap
if check_or_create_swap; then
msg_ok "Swap is available"
else
msg_warn "No swap available - continuing without swap"
fi
```
### Automated Swap Check
```bash
#!/usr/bin/env bash
source core.func
# Check swap without prompting
check_swap_quiet() {
if swapon --noheadings --show | grep -q 'swap'; then
msg_ok "Swap is active"
return 0
else
msg_warn "No active swap detected"
return 1
fi
}
if check_swap_quiet; then
msg_info "System has sufficient swap"
else
msg_warn "Consider adding swap for better performance"
fi
```
## Spinner Usage Examples
### Long-Running Operations
```bash
#!/usr/bin/env bash
source core.func
# Long-running operation with spinner
long_operation() {
msg_info "Processing large dataset..."
# Simulate long operation
for i in {1..100}; do
sleep 0.1
# Update spinner message periodically
if (( i % 20 == 0 )); then
SPINNER_MSG="Processing... $i%"
fi
done
msg_ok "Dataset processing completed"
}
long_operation
```
### Background Operations
```bash
#!/usr/bin/env bash
source core.func
# Background operation with spinner
background_operation() {
msg_info "Starting background process..."
# Start spinner
SPINNER_MSG="Processing in background..."
spinner &
SPINNER_PID=$!
# Do background work
sleep 5
# Stop spinner
stop_spinner
msg_ok "Background process completed"
}
background_operation
```
## Integration Examples
### With build.func
```bash
#!/usr/bin/env bash
# Integration with build.func
source core.func
source build.func
# Use core functions for system validation
pve_check
arch_check
root_check
# Use build.func for container creation
export APP="plex"
export CTID="100"
# ... container creation ...
```
### With tools.func
```bash
#!/usr/bin/env bash
# Integration with tools.func
source core.func
source tools.func
# Use core functions for UI
msg_info "Starting maintenance tasks..."
# Use tools.func for maintenance
update_system
cleanup_logs
optimize_storage
msg_ok "Maintenance completed"
```
### With error_handler.func
```bash
#!/usr/bin/env bash
# Integration with error_handler.func
source core.func
source error_handler.func
# Use core functions for execution
msg_info "Running operation..."
# Silent execution will use error_handler for explanations
silent apt-get install -y package
msg_ok "Operation completed"
```
## Best Practices Examples
### Error Handling Pattern
```bash
#!/usr/bin/env bash
source core.func
# Robust error handling
run_with_error_handling() {
local operation="$1"
local description="$2"
msg_info "$description"
if silent "$operation"; then
msg_ok "$description completed successfully"
return 0
else
msg_error "$description failed"
return 1
fi
}
# Usage
run_with_error_handling "apt-get update" "Package list update"
run_with_error_handling "apt-get install -y nginx" "Nginx installation"
```
### Verbose Mode Handling
```bash
#!/usr/bin/env bash
source core.func
# Handle verbose mode
if is_verbose_mode; then
msg_info "Verbose mode enabled - showing detailed output"
# Show more information
else
msg_info "Normal mode - showing minimal output"
# Show less information
fi
```
### Alpine Linux Detection
```bash
#!/usr/bin/env bash
source core.func
# Handle different OS types
if is_alpine; then
msg_info "Detected Alpine Linux"
# Use Alpine-specific commands
silent apk add --no-cache package
else
msg_info "Detected Debian-based system"
# Use Debian-specific commands
silent apt-get install -y package
fi
```
### Conditional Execution
```bash
#!/usr/bin/env bash
source core.func
# Conditional execution based on system state
if [[ -f /etc/nginx/nginx.conf ]]; then
msg_warn "Nginx configuration already exists"
read -p "Overwrite? [y/N]: " overwrite
if [[ "$overwrite" =~ ^[yY]$ ]]; then
msg_info "Overwriting configuration..."
# ... overwrite logic ...
else
msg_info "Skipping configuration"
fi
else
msg_info "Creating new Nginx configuration..."
# ... create logic ...
fi
```
## Advanced Usage Examples
### Custom Spinner Messages
```bash
#!/usr/bin/env bash
source core.func
# Custom spinner with progress
download_with_progress() {
local url="$1"
local file="$2"
msg_info "Starting download..."
# Start spinner
SPINNER_MSG="Downloading..."
spinner &
SPINNER_PID=$!
# Download with progress
curl -L "$url" -o "$file" --progress-bar
# Stop spinner
stop_spinner
msg_ok "Download completed"
}
download_with_progress "https://example.com/file.tar.gz" "/tmp/file.tar.gz"
```
### Message Deduplication
```bash
#!/usr/bin/env bash
source core.func
# Messages are automatically deduplicated
for i in {1..5}; do
msg_info "Processing item $i"
# This message will only show once
done
# Different messages will show separately
msg_info "Starting phase 1"
msg_info "Starting phase 2"
msg_info "Starting phase 3"
```
### Terminal Control
```bash
#!/usr/bin/env bash
source core.func
# Ensure terminal control is available
ensure_tput
# Use terminal control
clear_line
echo "This line will be cleared"
clear_line
echo "New content"
```
## Troubleshooting Examples
### Debug Mode
```bash
#!/usr/bin/env bash
source core.func
# Enable debug mode
export var_full_verbose=1
export VERBOSE="yes"
# Debug information
msg_debug "Script started"
msg_debug "Current user: $(whoami)"
msg_debug "Current directory: $(pwd)"
msg_debug "Environment variables: $(env | grep -E '^(APP|CTID|VERBOSE)')"
```
### Silent Execution Debugging
```bash
#!/usr/bin/env bash
source core.func
# Debug silent execution
debug_silent() {
local cmd="$1"
local log_file="/tmp/debug.$$.log"
echo "Command: $cmd" > "$log_file"
echo "Timestamp: $(date)" >> "$log_file"
echo "Working directory: $(pwd)" >> "$log_file"
echo "Environment:" >> "$log_file"
env >> "$log_file"
echo "--- Command Output ---" >> "$log_file"
if silent "$cmd"; then
msg_ok "Command succeeded"
else
msg_error "Command failed - check $log_file for details"
fi
}
debug_silent "apt-get update"
```
### Error Recovery
```bash
#!/usr/bin/env bash
source core.func
# Error recovery pattern
retry_operation() {
local max_attempts=3
local attempt=1
while [[ $attempt -le $max_attempts ]]; do
msg_info "Attempt $attempt of $max_attempts"
if silent "$@"; then
msg_ok "Operation succeeded on attempt $attempt"
return 0
else
msg_warn "Attempt $attempt failed"
((attempt++))
if [[ $attempt -le $max_attempts ]]; then
msg_info "Retrying in 5 seconds..."
sleep 5
fi
fi
done
msg_error "Operation failed after $max_attempts attempts"
return 1
}
# Usage
retry_operation "apt-get install -y package"
```

181
docs/misc/core.func/README.md Normal file
View File

@ -0,0 +1,181 @@
# core.func Documentation
## Overview
The `core.func` file provides fundamental utility functions and system checks that form the foundation for all other scripts in the Proxmox Community Scripts project. It handles basic system operations, user interface elements, validation, and core infrastructure.
## Purpose and Use Cases
- **System Validation**: Checks for Proxmox VE compatibility, architecture, shell requirements
- **User Interface**: Provides colored output, icons, spinners, and formatted messages
- **Core Utilities**: Basic functions used across all scripts
- **Error Handling**: Silent execution with detailed error reporting
- **System Information**: OS detection, verbose mode handling, swap management
## Quick Reference
### Key Function Groups
- **System Checks**: `pve_check()`, `arch_check()`, `shell_check()`, `root_check()`
- **User Interface**: `msg_info()`, `msg_ok()`, `msg_error()`, `msg_warn()`, `spinner()`
- **Core Utilities**: `silent()`, `is_alpine()`, `is_verbose_mode()`, `get_header()`
- **System Management**: `check_or_create_swap()`, `ensure_tput()`
### Dependencies
- **External**: `curl` for downloading headers, `tput` for terminal control
- **Internal**: `error_handler.func` for error explanations
### Integration Points
- Used by: All other `.func` files and installation scripts
- Uses: `error_handler.func` for error explanations
- Provides: Core utilities for `build.func`, `tools.func`, `api.func`
## Documentation Files
### 📊 [CORE_FLOWCHART.md](./CORE_FLOWCHART.md)
Visual execution flows showing how core functions interact and the system validation process.
### 📚 [CORE_FUNCTIONS_REFERENCE.md](./CORE_FUNCTIONS_REFERENCE.md)
Complete alphabetical reference of all functions with parameters, dependencies, and usage details.
### 💡 [CORE_USAGE_EXAMPLES.md](./CORE_USAGE_EXAMPLES.md)
Practical examples showing how to use core functions in scripts and common patterns.
### 🔗 [CORE_INTEGRATION.md](./CORE_INTEGRATION.md)
How core.func integrates with other components and provides foundational services.
## Key Features
### System Validation
- **Proxmox VE Version Check**: Supports PVE 8.0-8.9 and 9.0
- **Architecture Check**: Ensures AMD64 architecture (excludes PiMox)
- **Shell Check**: Validates Bash shell usage
- **Root Check**: Ensures root privileges
- **SSH Check**: Warns about external SSH usage
### User Interface
- **Colored Output**: ANSI color codes for styled terminal output
- **Icons**: Symbolic icons for different message types
- **Spinners**: Animated progress indicators
- **Formatted Messages**: Consistent message formatting across scripts
### Core Utilities
- **Silent Execution**: Execute commands with detailed error reporting
- **OS Detection**: Alpine Linux detection
- **Verbose Mode**: Handle verbose output settings
- **Header Management**: Download and display application headers
- **Swap Management**: Check and create swap files
## Common Usage Patterns
### Basic Script Setup
```bash
# Source core functions
source core.func
# Run system checks
pve_check
arch_check
shell_check
root_check
```
### Message Display
```bash
# Show progress
msg_info "Installing package..."
# Show success
msg_ok "Package installed successfully"
# Show error
msg_error "Installation failed"
# Show warning
msg_warn "This operation may take some time"
```
### Silent Command Execution
```bash
# Execute command silently with error handling
silent apt-get update
silent apt-get install -y package-name
```
## Environment Variables
### Core Variables
- `VERBOSE`: Enable verbose output mode
- `SILENT_LOGFILE`: Path to silent execution log file
- `APP`: Application name for header display
- `APP_TYPE`: Application type (ct/vm) for header paths
### Internal Variables
- `_CORE_FUNC_LOADED`: Prevents multiple loading
- `__FUNCTIONS_LOADED`: Prevents multiple function loading
- `RETRY_NUM`: Number of retry attempts (default: 10)
- `RETRY_EVERY`: Seconds between retries (default: 3)
## Error Handling
### Silent Execution Errors
- Commands executed via `silent()` capture output to log file
- On failure, displays error code explanation
- Shows last 10 lines of log output
- Provides command to view full log
### System Check Failures
- Each system check function exits with appropriate error message
- Clear indication of what's wrong and how to fix it
- Graceful exit with sleep delay for user to read message
## Best Practices
### Script Initialization
1. Source `core.func` first
2. Run system checks early
3. Set up error handling
4. Use appropriate message functions
### Message Usage
1. Use `msg_info()` for progress updates
2. Use `msg_ok()` for successful completions
3. Use `msg_error()` for failures
4. Use `msg_warn()` for warnings
### Silent Execution
1. Use `silent()` for commands that might fail
2. Check return codes after silent execution
3. Provide meaningful error messages
## Troubleshooting
### Common Issues
1. **Proxmox Version**: Ensure running supported PVE version
2. **Architecture**: Script only works on AMD64 systems
3. **Shell**: Must use Bash shell
4. **Permissions**: Must run as root
5. **Network**: SSH warnings for external connections
### Debug Mode
Enable verbose output for debugging:
```bash
export VERBOSE="yes"
source core.func
```
### Log Files
Check silent execution logs:
```bash
cat /tmp/silent.$$.log
```
## Related Documentation
- [build.func](../build.func/) - Main container creation script
- [error_handler.func](../error_handler.func/) - Error handling utilities
- [tools.func](../tools.func/) - Extended utility functions
- [api.func](../api.func/) - Proxmox API interactions
---
*This documentation covers the core.func file which provides fundamental utilities for all Proxmox Community Scripts.*

347
docs/misc/error_handler.func/ERROR_HANDLER_FLOWCHART.md Normal file
View File

@ -0,0 +1,347 @@
# error_handler.func Execution Flowchart
## Main Error Handling Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Error Handler Initialization │
│ Entry point when error_handler.func is sourced by other scripts │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CATCH_ERRORS() │
│ Initialize error handling traps and strict mode │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Trap Setup Sequence │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
│ │ Set Strict │ │ Set Error │ │ Set Signal │ │
│ │ Mode │ │ Trap │ │ Traps │ │
│ │ │ │ │ │ │ │
│ │ • -Ee │ │ • ERR trap │ │ • EXIT trap │ │
│ │ • -o pipefail │ │ • error_handler │ │ • INT trap │ │
│ │ • -u (if │ │ function │ │ • TERM trap │ │
│ │ STRICT_UNSET) │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Error Handler Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ERROR_HANDLER() Flow │
│ Main error handler triggered by ERR trap or manual call │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Error Detection │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Error Information Collection │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Get Exit │ │ Get Command │ │ Get Line │ │ │
│ │ │ Code │ │ Information │ │ Number │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • From $? or │ │ • From │ │ • From │ │ │
│ │ │ parameter │ │ BASH_COMMAND │ │ BASH_LINENO[0] │ │ │
│ │ │ • Store in │ │ • Clean $STD │ │ • Default to │ │ │
│ │ │ exit_code │ │ references │ │ "unknown" │ │ │
│ │ │ │ │ • Store in │ │ • Store in │ │ │
│ │ │ │ │ command │ │ line_number │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Success Check │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Exit Code Validation │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check Exit │ │ Success │ │ Error │ │
│ │ │ Code │ │ Path │ │ Path │ │
│ │ │ │ │ │ │ │ │
│ │ │ • If exit_code │ │ • Return 0 │ │ • Continue to │ │
│ │ │ == 0 │ │ • No error │ │ error handling │ │
│ │ │ • Success │ │ processing │ │ • Process error │ │
│ │ │ • No error │ │ │ │ information │ │
│ │ │ handling │ │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Error Processing │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Error Explanation │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Get Error │ │ Display Error │ │ Log Error │ │ │
│ │ │ Explanation │ │ Information │ │ Information │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ • Call │ │ • Show error │ │ • Write to debug │ │
│ │ │ explain_exit_ │ │ message │ │ log if enabled │ │
│ │ │ code() │ │ • Show line │ │ • Include │ │
│ │ │ • Get human- │ │ number │ │ timestamp │ │
│ │ │ readable │ │ • Show command │ │ • Include exit │ │
│ │ │ message │ │ • Show exit │ │ code │ │
│ │ │ │ │ code │ │ • Include command │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Silent Log Integration │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Silent Log Display │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check Silent │ │ Display Log │ │ Exit with │ │
│ │ │ Log File │ │ Content │ │ Error Code │ │
│ │ │ │ │ │ │ │ │
│ │ │ • Check if │ │ • Show last 20 │ │ • Exit with │ │
│ │ │ SILENT_ │ │ lines │ │ original exit │ │
│ │ │ LOGFILE set │ │ • Show file │ │ code │ │
│ │ │ • Check if │ │ path │ │ • Terminate script │ │
│ │ │ file exists │ │ • Format │ │ execution │ │
│ │ │ • Check if │ │ output │ │ │ │
│ │ │ file has │ │ │ │ │ │
│ │ │ content │ │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Signal Handling Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Signal Handler Flow │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Signal Detection │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ SIGINT │ │ SIGTERM │ │ EXIT │ │ │
│ │ │ (Ctrl+C) │ │ (Termination) │ │ (Script End) │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ • User │ │ • System │ │ • Normal script │ │
│ │ │ interruption │ │ termination │ │ completion │ │
│ │ │ • Graceful │ │ • Graceful │ │ • Error exit │ │
│ │ │ handling │ │ handling │ │ • Signal exit │ │
│ │ │ • Exit code │ │ • Exit code │ │ • Cleanup │ │
│ │ │ 130 │ │ 143 │ │ operations │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ON_INTERRUPT() Flow │
│ Handles SIGINT (Ctrl+C) signals │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Interrupt Processing │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ User Interruption Handling │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Display │ │ Cleanup │ │ Exit with │ │ │
│ │ │ Message │ │ Operations │ │ Code 130 │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ • Show │ │ • Stop │ │ • Exit with │ │
│ │ │ interruption │ │ processes │ │ SIGINT code │ │
│ │ │ message │ │ • Clean up │ │ • Terminate script │ │
│ │ │ • Use red │ │ temporary │ │ execution │ │
│ │ │ color │ │ files │ │ │ │
│ │ │ • Clear │ │ • Remove lock │ │ │ │
│ │ │ terminal │ │ files │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Exit Handler Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ON_EXIT() Flow │
│ Handles script exit cleanup │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Exit Cleanup │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Cleanup Operations │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Lock File │ │ Temporary │ │ Exit with │ │ │
│ │ │ Cleanup │ │ File │ │ Original Code │ │ │
│ │ │ │ │ Cleanup │ │ │ │
│ │ │ • Check if │ │ • Remove │ │ • Exit with │ │
│ │ │ lockfile │ │ temporary │ │ original exit │ │
│ │ │ variable set │ │ files │ │ code │ │
│ │ │ • Check if │ │ • Clean up │ │ • Preserve exit │ │
│ │ │ lockfile │ │ process │ │ status │ │
│ │ │ exists │ │ state │ │ • Terminate │ │
│ │ │ • Remove │ │ │ │ execution │ │
│ │ │ lockfile │ │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Error Code Explanation Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ EXPLAIN_EXIT_CODE() Flow │
│ Converts numeric exit codes to human-readable explanations │
└─────────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Error Code Classification │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Error Code Categories │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Generic/ │ │ Package │ │ Node.js │ │ │
│ │ │ Shell │ │ Manager │ │ Errors │ │ │
│ │ │ Errors │ │ Errors │ │ │ │
│ │ │ │ │ │ │ • 243: Out of │ │
│ │ │ • 1: General │ │ • 100: APT │ │ memory │ │
│ │ │ error │ │ package │ │ • 245: Invalid │ │
│ │ │ • 2: Shell │ │ error │ │ option │ │
│ │ │ builtin │ │ • 101: APT │ │ • 246: Parse │ │
│ │ │ misuse │ │ config error │ │ error │ │
│ │ │ • 126: Cannot │ │ • 255: DPKG │ │ • 247: Fatal │ │
│ │ │ execute │ │ fatal error │ │ error │ │
│ │ │ • 127: Command │ │ │ │ • 248: Addon │ │
│ │ │ not found │ │ │ │ failure │ │
│ │ │ • 128: Invalid │ │ │ │ • 249: Inspector │ │
│ │ │ exit │ │ │ │ error │ │
│ │ │ • 130: SIGINT │ │ │ │ • 254: Unknown │ │
│ │ │ • 137: SIGKILL │ │ │ │ fatal error │ │
│ │ │ • 139: Segfault │ │ │ │ │ │
│ │ │ • 143: SIGTERM │ │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Python │ │ Database │ │ Proxmox │ │ │
│ │ │ Errors │ │ Errors │ │ Custom │ │ │
│ │ │ │ │ │ │ Errors │ │
│ │ │ • 210: Virtual │ │ • PostgreSQL: │ │ • 200: Lock file │ │
│ │ │ env missing │ │ 231-234 │ │ failed │ │
│ │ │ • 211: Dep │ │ • MySQL: 241- │ │ • 203: Missing │ │
│ │ │ resolution │ │ 244 │ │ CTID │ │
│ │ │ • 212: Install │ │ • MongoDB: 251- │ │ • 204: Missing │ │
│ │ │ aborted │ │ 254 │ │ PCT_OSTYPE │ │
│ │ │ │ │ │ │ • 205: Invalid │ │
│ │ │ │ │ │ │ CTID │ │
│ │ │ │ │ │ │ • 209: Container │ │
│ │ │ │ │ │ │ creation failed │ │
│ │ │ │ │ │ │ • 210: Cluster │ │
│ │ │ │ │ │ │ not quorate │ │
│ │ │ │ │ │ │ • 214: No storage │ │
│ │ │ │ │ │ │ space │ │
│ │ │ │ │ │ │ • 215: CTID not │ │
│ │ │ │ │ │ │ listed │ │
│ │ │ │ │ │ │ • 216: RootFS │ │
│ │ │ │ │ │ │ missing │ │
│ │ │ │ │ │ │ • 217: Storage │ │
│ │ │ │ │ │ │ not supported │ │
│ │ │ │ │ │ │ • 220: Template │ │
│ │ │ │ │ │ │ path error │ │
│ │ │ │ │ │ │ • 222: Template │ │
│ │ │ │ │ │ │ download failed │ │
│ │ │ │ │ │ │ • 223: Template │ │
│ │ │ │ │ │ │ not available │ │
│ │ │ │ │ │ │ • 231: LXC stack │ │
│ │ │ │ │ │ │ upgrade failed │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Default Case │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Unknown Error Handling │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check for │ │ Return │ │ Log Unknown │ │ │
│ │ │ Unknown │ │ Generic │ │ Error │ │ │
│ │ │ Code │ │ Message │ │ │ │
│ │ │ │ │ │ │ • Log to debug │ │
│ │ │ • If no match │ │ • "Unknown │ │ file if enabled │ │
│ │ │ found │ │ error" │ │ • Include error │ │
│ │ │ • Use default │ │ • Return to │ │ code │ │
│ │ │ case │ │ caller │ │ • Include │ │
│ │ │ │ │ │ │ timestamp │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Debug Logging Flow
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ Debug Log Integration │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Debug Log Writing │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ Check Debug │ │ Write Error │ │ Format Log │ │ │
│ │ │ Log File │ │ Information │ │ Entry │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ • Check if │ │ • Timestamp │ │ • Error separator │ │
│ │ │ DEBUG_LOGFILE │ │ • Exit code │ │ • Structured │ │
│ │ │ set │ │ • Explanation │ │ format │ │
│ │ │ • Check if │ │ • Line number │ │ • Easy to parse │ │
│ │ │ file exists │ │ • Command │ │ • Easy to read │ │
│ │ │ • Check if │ │ • Append to │ │ │ │
│ │ │ file writable │ │ file │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Integration Points
### With core.func
- **Silent Execution**: Provides error explanations for silent() function
- **Color Variables**: Uses color variables for error display
- **Log Integration**: Integrates with SILENT_LOGFILE
### With Other Scripts
- **Error Traps**: Sets up ERR trap for automatic error handling
- **Signal Traps**: Handles SIGINT, SIGTERM, and EXIT signals
- **Cleanup**: Provides cleanup on script exit
### External Dependencies
- **None**: Pure Bash implementation
- **Color Support**: Requires color variables from core.func
- **Log Files**: Uses standard file operations

424
docs/misc/error_handler.func/ERROR_HANDLER_FUNCTIONS_REFERENCE.md Normal file
View File

@ -0,0 +1,424 @@
# error_handler.func Functions Reference
## Overview
This document provides a comprehensive alphabetical reference of all functions in `error_handler.func`, including parameters, dependencies, usage examples, and error handling.
## Function Categories
### Error Explanation Functions
#### `explain_exit_code()`
**Purpose**: Convert numeric exit codes to human-readable explanations
**Parameters**:
- `$1` - Exit code to explain
**Returns**: Human-readable error explanation string
**Side Effects**: None
**Dependencies**: None
**Environment Variables Used**: None
**Supported Exit Codes**:
- **Generic/Shell**: 1, 2, 126, 127, 128, 130, 137, 139, 143
- **Package Manager**: 100, 101, 255
- **Node.js**: 243, 245, 246, 247, 248, 249, 254
- **Python**: 210, 211, 212
- **PostgreSQL**: 231, 232, 233, 234
- **MySQL/MariaDB**: 241, 242, 243, 244
- **MongoDB**: 251, 252, 253, 254
- **Proxmox Custom**: 200, 203, 204, 205, 209, 210, 214, 215, 216, 217, 220, 222, 223, 231
**Usage Example**:
```bash
explanation=$(explain_exit_code 127)
echo "Error 127: $explanation"
# Output: Error 127: Command not found
```
**Error Code Examples**:
```bash
explain_exit_code 1 # "General error / Operation not permitted"
explain_exit_code 126 # "Command invoked cannot execute (permission problem?)"
explain_exit_code 127 # "Command not found"
explain_exit_code 130 # "Terminated by Ctrl+C (SIGINT)"
explain_exit_code 200 # "Custom: Failed to create lock file"
explain_exit_code 999 # "Unknown error"
```
### Error Handling Functions
#### `error_handler()`
**Purpose**: Main error handler triggered by ERR trap or manual call
**Parameters**:
- `$1` - Exit code (optional, defaults to $?)
- `$2` - Command that failed (optional, defaults to BASH_COMMAND)
**Returns**: None (exits with error code)
**Side Effects**:
- Displays detailed error information
- Logs error to debug file if enabled
- Shows silent log content if available
- Exits with original error code
**Dependencies**: `explain_exit_code()`
**Environment Variables Used**: `DEBUG_LOGFILE`, `SILENT_LOGFILE`
**Usage Example**:
```bash
# Automatic error handling via ERR trap
set -e
trap 'error_handler' ERR
# Manual error handling
error_handler 127 "command_not_found"
```
**Error Information Displayed**:
- Error message with color coding
- Line number where error occurred
- Exit code with explanation
- Command that failed
- Silent log content (last 20 lines)
- Debug log entry (if enabled)
### Signal Handling Functions
#### `on_interrupt()`
**Purpose**: Handle SIGINT (Ctrl+C) signals gracefully
**Parameters**: None
**Returns**: None (exits with code 130)
**Side Effects**:
- Displays interruption message
- Exits with SIGINT code (130)
**Dependencies**: None
**Environment Variables Used**: None
**Usage Example**:
```bash
# Set up interrupt handler
trap on_interrupt INT
# User presses Ctrl+C
# Handler displays: "Interrupted by user (SIGINT)"
# Script exits with code 130
```
#### `on_terminate()`
**Purpose**: Handle SIGTERM signals gracefully
**Parameters**: None
**Returns**: None (exits with code 143)
**Side Effects**:
- Displays termination message
- Exits with SIGTERM code (143)
**Dependencies**: None
**Environment Variables Used**: None
**Usage Example**:
```bash
# Set up termination handler
trap on_terminate TERM
# System sends SIGTERM
# Handler displays: "Terminated by signal (SIGTERM)"
# Script exits with code 143
```
### Cleanup Functions
#### `on_exit()`
**Purpose**: Handle script exit cleanup
**Parameters**: None
**Returns**: None (exits with original exit code)
**Side Effects**:
- Removes lock file if set
- Exits with original exit code
**Dependencies**: None
**Environment Variables Used**: `lockfile`
**Usage Example**:
```bash
# Set up exit handler
trap on_exit EXIT
# Set lock file
lockfile="/tmp/my_script.lock"
# Script exits normally or with error
# Handler removes lock file and exits
```
### Initialization Functions
#### `catch_errors()`
**Purpose**: Initialize error handling traps and strict mode
**Parameters**: None
**Returns**: None
**Side Effects**:
- Sets strict error handling mode
- Sets up error traps
- Sets up signal traps
- Sets up exit trap
**Dependencies**: None
**Environment Variables Used**: `STRICT_UNSET`
**Strict Mode Settings**:
- `-E`: Exit on command failure
- `-e`: Exit on any error
- `-o pipefail`: Exit on pipe failure
- `-u`: Exit on unset variables (if STRICT_UNSET=1)
**Trap Setup**:
- `ERR`: Calls `error_handler` on command failure
- `EXIT`: Calls `on_exit` on script exit
- `INT`: Calls `on_interrupt` on SIGINT
- `TERM`: Calls `on_terminate` on SIGTERM
**Usage Example**:
```bash
# Initialize error handling
catch_errors
# Script now has full error handling
# All errors will be caught and handled
```
## Function Call Hierarchy
### Error Handling Flow
```
Command Failure
├── ERR trap triggered
├── error_handler() called
│ ├── Get exit code
│ ├── Get command info
│ ├── Get line number
│ ├── explain_exit_code()
│ ├── Display error info
│ ├── Log to debug file
│ ├── Show silent log
│ └── Exit with error code
```
### Signal Handling Flow
```
Signal Received
├── Signal trap triggered
├── Appropriate handler called
│ ├── on_interrupt() for SIGINT
│ ├── on_terminate() for SIGTERM
│ └── on_exit() for EXIT
└── Exit with signal code
```
### Initialization Flow
```
catch_errors()
├── Set strict mode
│ ├── -E (exit on failure)
│ ├── -e (exit on error)
│ ├── -o pipefail (pipe failure)
│ └── -u (unset variables, if enabled)
└── Set up traps
├── ERR → error_handler
├── EXIT → on_exit
├── INT → on_interrupt
└── TERM → on_terminate
```
## Error Code Reference
### Generic/Shell Errors
| Code | Description |
|------|-------------|
| 1 | General error / Operation not permitted |
| 2 | Misuse of shell builtins (e.g. syntax error) |
| 126 | Command invoked cannot execute (permission problem?) |
| 127 | Command not found |
| 128 | Invalid argument to exit |
| 130 | Terminated by Ctrl+C (SIGINT) |
| 137 | Killed (SIGKILL / Out of memory?) |
| 139 | Segmentation fault (core dumped) |
| 143 | Terminated (SIGTERM) |
### Package Manager Errors
| Code | Description |
|------|-------------|
| 100 | APT: Package manager error (broken packages / dependency problems) |
| 101 | APT: Configuration error (bad sources.list, malformed config) |
| 255 | DPKG: Fatal internal error |
### Node.js Errors
| Code | Description |
|------|-------------|
| 243 | Node.js: Out of memory (JavaScript heap out of memory) |
| 245 | Node.js: Invalid command-line option |
| 246 | Node.js: Internal JavaScript Parse Error |
| 247 | Node.js: Fatal internal error |
| 248 | Node.js: Invalid C++ addon / N-API failure |
| 249 | Node.js: Inspector error |
| 254 | npm/pnpm/yarn: Unknown fatal error |
### Python Errors
| Code | Description |
|------|-------------|
| 210 | Python: Virtualenv / uv environment missing or broken |
| 211 | Python: Dependency resolution failed |
| 212 | Python: Installation aborted (permissions or EXTERNALLY-MANAGED) |
### Database Errors
| Code | Description |
|------|-------------|
| 231 | PostgreSQL: Connection failed (server not running / wrong socket) |
| 232 | PostgreSQL: Authentication failed (bad user/password) |
| 233 | PostgreSQL: Database does not exist |
| 234 | PostgreSQL: Fatal error in query / syntax |
| 241 | MySQL/MariaDB: Connection failed (server not running / wrong socket) |
| 242 | MySQL/MariaDB: Authentication failed (bad user/password) |
| 243 | MySQL/MariaDB: Database does not exist |
| 244 | MySQL/MariaDB: Fatal error in query / syntax |
| 251 | MongoDB: Connection failed (server not running) |
| 252 | MongoDB: Authentication failed (bad user/password) |
| 253 | MongoDB: Database not found |
| 254 | MongoDB: Fatal query error |
### Proxmox Custom Errors
| Code | Description |
|------|-------------|
| 200 | Custom: Failed to create lock file |
| 203 | Custom: Missing CTID variable |
| 204 | Custom: Missing PCT_OSTYPE variable |
| 205 | Custom: Invalid CTID (<100) |
| 209 | Custom: Container creation failed |
| 210 | Custom: Cluster not quorate |
| 214 | Custom: Not enough storage space |
| 215 | Custom: Container ID not listed |
| 216 | Custom: RootFS entry missing in config |
| 217 | Custom: Storage does not support rootdir |
| 220 | Custom: Unable to resolve template path |
| 222 | Custom: Template download failed after 3 attempts |
| 223 | Custom: Template not available after download |
| 231 | Custom: LXC stack upgrade/retry failed |
## Environment Variable Dependencies
### Required Variables
- **`lockfile`**: Lock file path for cleanup (set by calling script)
### Optional Variables
- **`DEBUG_LOGFILE`**: Path to debug log file for error logging
- **`SILENT_LOGFILE`**: Path to silent execution log file
- **`STRICT_UNSET`**: Enable strict unset variable checking (0/1)
### Internal Variables
- **`exit_code`**: Current exit code
- **`command`**: Failed command
- **`line_number`**: Line number where error occurred
- **`explanation`**: Error explanation text
## Error Handling Patterns
### Automatic Error Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Initialize error handling
catch_errors
# All commands are now monitored
# Errors will be automatically caught and handled
```
### Manual Error Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Manual error handling
if ! command -v required_tool >/dev/null 2>&1; then
error_handler 127 "required_tool not found"
fi
```
### Custom Error Codes
```bash
#!/usr/bin/env bash
source error_handler.func
# Use custom error codes
if [[ ! -f /required/file ]]; then
echo "Error: Required file missing"
exit 200 # Custom error code
fi
```
### Signal Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Set up signal handling
trap on_interrupt INT
trap on_terminate TERM
trap on_exit EXIT
# Script handles signals gracefully
```
## Integration Examples
### With core.func
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
# Silent execution uses error_handler for explanations
silent apt-get install -y package
# If command fails, error_handler provides explanation
```
### With build.func
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
source build.func
# Container creation with error handling
# Errors are caught and explained
```
### With tools.func
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
source tools.func
# Tool operations with error handling
# All errors are properly handled and explained
```
## Best Practices
### Error Handling Setup
1. Source error_handler.func early in script
2. Call catch_errors() to initialize traps
3. Use appropriate exit codes for different error types
4. Provide meaningful error messages
### Signal Handling
1. Always set up signal traps
2. Provide graceful cleanup on interruption
3. Use appropriate exit codes for signals
4. Clean up temporary files and processes
### Error Reporting
1. Use explain_exit_code() for user-friendly messages
2. Log errors to debug files when needed
3. Provide context information (line numbers, commands)
4. Integrate with silent execution logging
### Custom Error Codes
1. Use Proxmox custom error codes (200-231) for container/VM errors
2. Use standard error codes for common operations
3. Document custom error codes in script comments
4. Provide clear error messages for custom codes

512
docs/misc/error_handler.func/ERROR_HANDLER_INTEGRATION.md Normal file
View File

@ -0,0 +1,512 @@
# error_handler.func Integration Guide
## Overview
This document describes how `error_handler.func` integrates with other components in the Proxmox Community Scripts project, including dependencies, data flow, and API surface.
## Dependencies
### External Dependencies
#### Required Commands
- **None**: Pure Bash implementation
#### Optional Commands
- **None**: No external command dependencies
### Internal Dependencies
#### core.func
- **Purpose**: Provides color variables for error display
- **Usage**: Uses `RD`, `CL`, `YWB` color variables
- **Integration**: Called automatically when core.func is sourced
- **Data Flow**: Color variables → error display formatting
## Integration Points
### With core.func
#### Silent Execution Integration
```bash
# core.func silent() function uses error_handler.func
silent() {
local cmd="$*"
local caller_line="${BASH_LINENO[0]:-unknown}"
# Execute command
"$@" >>"$SILENT_LOGFILE" 2>&1
local rc=$?
if [[ $rc -ne 0 ]]; then
# Load error_handler.func if needed
if ! declare -f explain_exit_code >/dev/null 2>&1; then
source error_handler.func
fi
# Get error explanation
local explanation
explanation="$(explain_exit_code "$rc")"
# Display error with explanation
printf "\e[?25h"
echo -e "\n${RD}[ERROR]${CL} in line ${RD}${caller_line}${CL}: exit code ${RD}${rc}${CL} (${explanation})"
echo -e "${RD}Command:${CL} ${YWB}${cmd}${CL}\n"
exit "$rc"
fi
}
```
#### Color Variable Usage
```bash
# error_handler.func uses color variables from core.func
error_handler() {
# ... error handling logic ...
# Use color variables for error display
echo -e "\n${RD}[ERROR]${CL} in line ${RD}${line_number}${CL}: exit code ${RD}${exit_code}${CL} (${explanation}): while executing command ${YWB}${command}${CL}\n"
}
on_interrupt() {
echo -e "\n${RD}Interrupted by user (SIGINT)${CL}"
exit 130
}
on_terminate() {
echo -e "\n${RD}Terminated by signal (SIGTERM)${CL}"
exit 143
}
```
### With build.func
#### Container Creation Error Handling
```bash
# build.func uses error_handler.func for container operations
source core.func
source error_handler.func
# Container creation with error handling
create_container() {
# Set up error handling
catch_errors
# Container creation operations
silent pct create "$CTID" "$TEMPLATE" \
--hostname "$HOSTNAME" \
--memory "$MEMORY" \
--cores "$CORES"
# If creation fails, error_handler provides explanation
}
```
#### Template Download Error Handling
```bash
# build.func uses error_handler.func for template operations
download_template() {
# Template download with error handling
if ! silent curl -fsSL "$TEMPLATE_URL" -o "$TEMPLATE_FILE"; then
# error_handler provides detailed explanation
exit 222 # Template download failed
fi
}
```
### With tools.func
#### Maintenance Operations Error Handling
```bash
# tools.func uses error_handler.func for maintenance operations
source core.func
source error_handler.func
# Maintenance operations with error handling
update_system() {
catch_errors
# System update operations
silent apt-get update
silent apt-get upgrade -y
# Error handling provides explanations for failures
}
cleanup_logs() {
catch_errors
# Log cleanup operations
silent find /var/log -name "*.log" -mtime +30 -delete
# Error handling provides explanations for permission issues
}
```
### With api.func
#### API Operations Error Handling
```bash
# api.func uses error_handler.func for API operations
source core.func
source error_handler.func
# API operations with error handling
api_call() {
catch_errors
# API call with error handling
if ! silent curl -k -H "Authorization: PVEAPIToken=$API_TOKEN" \
"$API_URL/api2/json/nodes/$NODE/lxc"; then
# error_handler provides explanation for API failures
exit 1
fi
}
```
### With install.func
#### Installation Process Error Handling
```bash
# install.func uses error_handler.func for installation operations
source core.func
source error_handler.func
# Installation with error handling
install_package() {
local package="$1"
catch_errors
# Package installation
silent apt-get install -y "$package"
# Error handling provides explanations for installation failures
}
```
### With alpine-install.func
#### Alpine Installation Error Handling
```bash
# alpine-install.func uses error_handler.func for Alpine operations
source core.func
source error_handler.func
# Alpine installation with error handling
install_alpine_package() {
local package="$1"
catch_errors
# Alpine package installation
silent apk add --no-cache "$package"
# Error handling provides explanations for Alpine-specific failures
}
```
### With alpine-tools.func
#### Alpine Tools Error Handling
```bash
# alpine-tools.func uses error_handler.func for Alpine tools
source core.func
source error_handler.func
# Alpine tools with error handling
alpine_tool_operation() {
catch_errors
# Alpine-specific tool operations
silent alpine_command
# Error handling provides explanations for Alpine tool failures
}
```
### With passthrough.func
#### Hardware Passthrough Error Handling
```bash
# passthrough.func uses error_handler.func for hardware operations
source core.func
source error_handler.func
# Hardware passthrough with error handling
configure_gpu_passthrough() {
catch_errors
# GPU passthrough operations
silent lspci | grep -i nvidia
# Error handling provides explanations for hardware failures
}
```
### With vm-core.func
#### VM Operations Error Handling
```bash
# vm-core.func uses error_handler.func for VM operations
source core.func
source error_handler.func
# VM operations with error handling
create_vm() {
catch_errors
# VM creation operations
silent qm create "$VMID" \
--name "$VMNAME" \
--memory "$MEMORY" \
--cores "$CORES"
# Error handling provides explanations for VM creation failures
}
```
## Data Flow
### Input Data
#### Environment Variables
- **`DEBUG_LOGFILE`**: Path to debug log file for error logging
- **`SILENT_LOGFILE`**: Path to silent execution log file
- **`STRICT_UNSET`**: Enable strict unset variable checking (0/1)
- **`lockfile`**: Lock file path for cleanup (set by calling script)
#### Function Parameters
- **Exit codes**: Passed to `explain_exit_code()` and `error_handler()`
- **Command information**: Passed to `error_handler()` for context
- **Signal information**: Passed to signal handlers
#### System Information
- **Exit codes**: Retrieved from `$?` variable
- **Command information**: Retrieved from `BASH_COMMAND` variable
- **Line numbers**: Retrieved from `BASH_LINENO[0]` variable
- **Process information**: Retrieved from system calls
### Processing Data
#### Error Code Processing
- **Code classification**: Categorize exit codes by type
- **Explanation lookup**: Map codes to human-readable messages
- **Context collection**: Gather command and line information
- **Log preparation**: Format error information for logging
#### Signal Processing
- **Signal detection**: Identify received signals
- **Handler selection**: Choose appropriate signal handler
- **Cleanup operations**: Perform necessary cleanup
- **Exit code setting**: Set appropriate exit codes
#### Log Processing
- **Debug logging**: Write error information to debug log
- **Silent log integration**: Display silent log content
- **Log formatting**: Format log entries for readability
- **Log analysis**: Provide log analysis capabilities
### Output Data
#### Error Information
- **Error messages**: Human-readable error explanations
- **Context information**: Line numbers, commands, timestamps
- **Color formatting**: ANSI color codes for terminal display
- **Log content**: Silent log excerpts and debug information
#### System State
- **Exit codes**: Returned from functions
- **Log files**: Created and updated for error tracking
- **Cleanup status**: Lock file removal and process cleanup
- **Signal handling**: Graceful signal processing
## API Surface
### Public Functions
#### Error Explanation
- **`explain_exit_code()`**: Convert exit codes to explanations
- **Parameters**: Exit code to explain
- **Returns**: Human-readable explanation string
- **Usage**: Called by error_handler() and other functions
#### Error Handling
- **`error_handler()`**: Main error handler function
- **Parameters**: Exit code (optional), command (optional)
- **Returns**: None (exits with error code)
- **Usage**: Called by ERR trap or manually
#### Signal Handling
- **`on_interrupt()`**: Handle SIGINT signals
- **`on_terminate()`**: Handle SIGTERM signals
- **`on_exit()`**: Handle script exit cleanup
- **Parameters**: None
- **Returns**: None (exits with signal code)
- **Usage**: Called by signal traps
#### Initialization
- **`catch_errors()`**: Initialize error handling
- **Parameters**: None
- **Returns**: None
- **Usage**: Called to set up error handling traps
### Internal Functions
#### None
- All functions in error_handler.func are public
- No internal helper functions
- Direct implementation of all functionality
### Global Variables
#### Configuration Variables
- **`DEBUG_LOGFILE`**: Debug log file path
- **`SILENT_LOGFILE`**: Silent log file path
- **`STRICT_UNSET`**: Strict mode setting
- **`lockfile`**: Lock file path
#### State Variables
- **`exit_code`**: Current exit code
- **`command`**: Failed command
- **`line_number`**: Line number where error occurred
- **`explanation`**: Error explanation text
## Integration Patterns
### Standard Integration Pattern
```bash
#!/usr/bin/env bash
# Standard integration pattern
# 1. Source core.func first
source core.func
# 2. Source error_handler.func
source error_handler.func
# 3. Initialize error handling
catch_errors
# 4. Use silent execution
silent command
# 5. Errors are automatically handled
```
### Minimal Integration Pattern
```bash
#!/usr/bin/env bash
# Minimal integration pattern
source error_handler.func
catch_errors
# Basic error handling
command
```
### Advanced Integration Pattern
```bash
#!/usr/bin/env bash
# Advanced integration pattern
source core.func
source error_handler.func
# Set up comprehensive error handling
export DEBUG_LOGFILE="/tmp/debug.log"
export SILENT_LOGFILE="/tmp/silent.log"
lockfile="/tmp/script.lock"
touch "$lockfile"
catch_errors
trap on_interrupt INT
trap on_terminate TERM
trap on_exit EXIT
# Advanced error handling
silent command
```
## Error Handling Integration
### Automatic Error Handling
- **ERR Trap**: Automatically catches command failures
- **Error Explanation**: Provides human-readable error messages
- **Context Information**: Shows line numbers and commands
- **Log Integration**: Displays silent log content
### Manual Error Handling
- **Custom Error Codes**: Use Proxmox custom error codes
- **Error Recovery**: Implement retry logic with error handling
- **Conditional Handling**: Different handling for different error types
- **Error Analysis**: Analyze error patterns and trends
### Signal Handling Integration
- **Graceful Interruption**: Handle Ctrl+C gracefully
- **Clean Termination**: Handle SIGTERM signals
- **Exit Cleanup**: Clean up resources on script exit
- **Lock File Management**: Remove lock files on exit
## Performance Considerations
### Error Handling Overhead
- **Minimal Impact**: Error handling adds minimal overhead
- **Trap Setup**: Trap setup is done once during initialization
- **Error Processing**: Error processing is only done on failures
- **Log Writing**: Log writing is only done when enabled
### Memory Usage
- **Minimal Footprint**: Error handler uses minimal memory
- **Variable Reuse**: Global variables reused across functions
- **No Memory Leaks**: Proper cleanup prevents memory leaks
- **Efficient Processing**: Efficient error code processing
### Execution Speed
- **Fast Error Detection**: Quick error detection and handling
- **Efficient Explanation**: Fast error code explanation lookup
- **Minimal Delay**: Minimal delay in error handling
- **Quick Exit**: Fast exit on error conditions
## Security Considerations
### Error Information Disclosure
- **Controlled Disclosure**: Only necessary error information is shown
- **Log Security**: Log files have appropriate permissions
- **Sensitive Data**: Sensitive data is not logged
- **Error Sanitization**: Error messages are sanitized
### Signal Handling Security
- **Signal Validation**: Only expected signals are handled
- **Cleanup Security**: Secure cleanup of temporary files
- **Lock File Security**: Secure lock file management
- **Process Security**: Secure process termination
### Log File Security
- **File Permissions**: Log files have appropriate permissions
- **Log Rotation**: Log files are rotated to prevent disk filling
- **Log Cleanup**: Old log files are cleaned up
- **Log Access**: Log access is controlled
## Future Integration Considerations
### Extensibility
- **New Error Codes**: Easy to add new error code explanations
- **Custom Handlers**: Easy to add custom error handlers
- **Signal Extensions**: Easy to add new signal handlers
- **Log Formats**: Easy to add new log formats
### Compatibility
- **Bash Version**: Compatible with different Bash versions
- **System Compatibility**: Compatible with different systems
- **Script Compatibility**: Compatible with different script types
- **Error Code Compatibility**: Compatible with different error codes
### Performance
- **Optimization**: Error handling can be optimized for better performance
- **Caching**: Error explanations can be cached for faster lookup
- **Parallel Processing**: Error handling can be parallelized
- **Resource Management**: Better resource management for error handling

625
docs/misc/error_handler.func/ERROR_HANDLER_USAGE_EXAMPLES.md Normal file
View File

@ -0,0 +1,625 @@
# error_handler.func Usage Examples
## Overview
This document provides practical usage examples for `error_handler.func` functions, covering common scenarios, integration patterns, and best practices.
## Basic Error Handling Setup
### Standard Script Initialization
```bash
#!/usr/bin/env bash
# Standard error handling setup
# Source error handler
source error_handler.func
# Initialize error handling
catch_errors
# Your script code here
# All errors will be automatically caught and handled
echo "Script running..."
apt-get update
apt-get install -y package
echo "Script completed successfully"
```
### Minimal Error Handling
```bash
#!/usr/bin/env bash
# Minimal error handling setup
source error_handler.func
catch_errors
# Simple script with error handling
echo "Starting operation..."
command_that_might_fail
echo "Operation completed"
```
## Error Code Explanation Examples
### Basic Error Explanation
```bash
#!/usr/bin/env bash
source error_handler.func
# Explain common error codes
echo "Error 1: $(explain_exit_code 1)"
echo "Error 127: $(explain_exit_code 127)"
echo "Error 130: $(explain_exit_code 130)"
echo "Error 200: $(explain_exit_code 200)"
```
### Error Code Testing
```bash
#!/usr/bin/env bash
source error_handler.func
# Test all error codes
test_error_codes() {
local codes=(1 2 126 127 128 130 137 139 143 100 101 255 200 203 204 205)
for code in "${codes[@]}"; do
echo "Code $code: $(explain_exit_code $code)"
done
}
test_error_codes
```
### Custom Error Code Usage
```bash
#!/usr/bin/env bash
source error_handler.func
# Use custom error codes
check_requirements() {
if [[ ! -f /required/file ]]; then
echo "Error: Required file missing"
exit 200 # Custom error code
fi
if [[ -z "$CTID" ]]; then
echo "Error: CTID not set"
exit 203 # Custom error code
fi
if [[ $CTID -lt 100 ]]; then
echo "Error: Invalid CTID"
exit 205 # Custom error code
fi
}
check_requirements
```
## Signal Handling Examples
### Interrupt Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Set up interrupt handler
trap on_interrupt INT
echo "Script running... Press Ctrl+C to interrupt"
sleep 10
echo "Script completed normally"
```
### Termination Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Set up termination handler
trap on_terminate TERM
echo "Script running... Send SIGTERM to terminate"
sleep 10
echo "Script completed normally"
```
### Complete Signal Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Set up all signal handlers
trap on_interrupt INT
trap on_terminate TERM
trap on_exit EXIT
echo "Script running with full signal handling"
sleep 10
echo "Script completed normally"
```
## Cleanup Examples
### Lock File Cleanup
```bash
#!/usr/bin/env bash
source error_handler.func
# Set up lock file
lockfile="/tmp/my_script.lock"
touch "$lockfile"
# Set up exit handler
trap on_exit EXIT
echo "Script running with lock file..."
sleep 5
echo "Script completed - lock file will be removed"
```
### Temporary File Cleanup
```bash
#!/usr/bin/env bash
source error_handler.func
# Create temporary files
temp_file1="/tmp/temp1.$$"
temp_file2="/tmp/temp2.$$"
touch "$temp_file1" "$temp_file2"
# Set up cleanup
cleanup() {
rm -f "$temp_file1" "$temp_file2"
echo "Temporary files cleaned up"
}
trap cleanup EXIT
echo "Script running with temporary files..."
sleep 5
echo "Script completed - temporary files will be cleaned up"
```
## Debug Logging Examples
### Basic Debug Logging
```bash
#!/usr/bin/env bash
source error_handler.func
# Enable debug logging
export DEBUG_LOGFILE="/tmp/debug.log"
catch_errors
echo "Script with debug logging"
apt-get update
apt-get install -y package
```
### Debug Log Analysis
```bash
#!/usr/bin/env bash
source error_handler.func
# Enable debug logging
export DEBUG_LOGFILE="/tmp/debug.log"
catch_errors
# Function to analyze debug log
analyze_debug_log() {
if [[ -f "$DEBUG_LOGFILE" ]]; then
echo "Debug log analysis:"
echo "Total errors: $(grep -c "ERROR" "$DEBUG_LOGFILE")"
echo "Recent errors:"
tail -n 5 "$DEBUG_LOGFILE"
else
echo "No debug log found"
fi
}
# Run script
echo "Running script..."
apt-get update
# Analyze results
analyze_debug_log
```
## Silent Execution Integration
### With core.func Silent Execution
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
# Silent execution with error handling
echo "Installing packages..."
silent apt-get update
silent apt-get install -y nginx
echo "Configuring service..."
silent systemctl enable nginx
silent systemctl start nginx
echo "Installation completed"
```
### Silent Execution Error Handling
```bash
#!/usr/bin/env bash
source core.func
source error_handler.func
# Function with silent execution and error handling
install_package() {
local package="$1"
echo "Installing $package..."
if silent apt-get install -y "$package"; then
echo "$package installed successfully"
return 0
else
echo "Failed to install $package"
return 1
fi
}
# Install multiple packages
packages=("nginx" "apache2" "mysql-server")
for package in "${packages[@]}"; do
if ! install_package "$package"; then
echo "Stopping installation due to error"
exit 1
fi
done
```
## Advanced Error Handling Examples
### Conditional Error Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Conditional error handling based on environment
setup_error_handling() {
if [[ "${STRICT_MODE:-0}" == "1" ]]; then
echo "Enabling strict mode"
export STRICT_UNSET=1
fi
catch_errors
echo "Error handling configured"
}
setup_error_handling
```
### Error Recovery
```bash
#!/usr/bin/env bash
source error_handler.func
# Error recovery pattern
retry_operation() {
local max_attempts=3
local attempt=1
while [[ $attempt -le $max_attempts ]]; do
echo "Attempt $attempt of $max_attempts"
if silent "$@"; then
echo "Operation succeeded on attempt $attempt"
return 0
else
echo "Attempt $attempt failed"
((attempt++))
if [[ $attempt -le $max_attempts ]]; then
echo "Retrying in 5 seconds..."
sleep 5
fi
fi
done
echo "Operation failed after $max_attempts attempts"
return 1
}
# Use retry pattern
retry_operation apt-get update
retry_operation apt-get install -y package
```
### Custom Error Handler
```bash
#!/usr/bin/env bash
source error_handler.func
# Custom error handler for specific operations
custom_error_handler() {
local exit_code=${1:-$?}
local command=${2:-${BASH_COMMAND:-unknown}}
case "$exit_code" in
127)
echo "Custom handling: Command not found - $command"
echo "Suggestions:"
echo "1. Check if the command is installed"
echo "2. Check if the command is in PATH"
echo "3. Check spelling"
;;
126)
echo "Custom handling: Permission denied - $command"
echo "Suggestions:"
echo "1. Check file permissions"
echo "2. Run with appropriate privileges"
echo "3. Check if file is executable"
;;
*)
# Use default error handler
error_handler "$exit_code" "$command"
;;
esac
}
# Set up custom error handler
trap 'custom_error_handler' ERR
# Test custom error handling
nonexistent_command
```
## Integration Examples
### With build.func
```bash
#!/usr/bin/env bash
# Integration with build.func
source core.func
source error_handler.func
source build.func
# Container creation with error handling
export APP="plex"
export CTID="100"
# Errors will be caught and explained
# Silent execution will use error_handler for explanations
```
### With tools.func
```bash
#!/usr/bin/env bash
# Integration with tools.func
source core.func
source error_handler.func
source tools.func
# Tool operations with error handling
# All errors are properly handled and explained
```
### With api.func
```bash
#!/usr/bin/env bash
# Integration with api.func
source core.func
source error_handler.func
source api.func
# API operations with error handling
# Network errors and API errors are properly handled
```
## Best Practices Examples
### Comprehensive Error Handling
```bash
#!/usr/bin/env bash
# Comprehensive error handling example
source error_handler.func
# Set up comprehensive error handling
setup_comprehensive_error_handling() {
# Enable debug logging
export DEBUG_LOGFILE="/tmp/script_debug.log"
# Set up lock file
lockfile="/tmp/script.lock"
touch "$lockfile"
# Initialize error handling
catch_errors
# Set up signal handlers
trap on_interrupt INT
trap on_terminate TERM
trap on_exit EXIT
echo "Comprehensive error handling configured"
}
setup_comprehensive_error_handling
# Script operations
echo "Starting script operations..."
# ... script code ...
echo "Script operations completed"
```
### Error Handling for Different Scenarios
```bash
#!/usr/bin/env bash
source error_handler.func
# Different error handling for different scenarios
handle_package_errors() {
local exit_code=$1
case "$exit_code" in
100)
echo "Package manager error - trying to fix..."
apt-get --fix-broken install
;;
101)
echo "Configuration error - checking sources..."
apt-get update
;;
*)
error_handler "$exit_code"
;;
esac
}
handle_network_errors() {
local exit_code=$1
case "$exit_code" in
127)
echo "Network command not found - checking connectivity..."
ping -c 1 8.8.8.8
;;
*)
error_handler "$exit_code"
;;
esac
}
# Use appropriate error handler
if [[ "$1" == "package" ]]; then
trap 'handle_package_errors $?' ERR
elif [[ "$1" == "network" ]]; then
trap 'handle_network_errors $?' ERR
else
catch_errors
fi
```
### Error Handling with Logging
```bash
#!/usr/bin/env bash
source error_handler.func
# Error handling with detailed logging
setup_logging_error_handling() {
# Create log directory
mkdir -p /var/log/script_errors
# Set up debug logging
export DEBUG_LOGFILE="/var/log/script_errors/debug.log"
# Set up silent logging
export SILENT_LOGFILE="/var/log/script_errors/silent.log"
# Initialize error handling
catch_errors
echo "Logging error handling configured"
}
setup_logging_error_handling
# Script operations with logging
echo "Starting logged operations..."
# ... script code ...
echo "Logged operations completed"
```
## Troubleshooting Examples
### Debug Mode
```bash
#!/usr/bin/env bash
source error_handler.func
# Enable debug mode
export DEBUG_LOGFILE="/tmp/debug.log"
export STRICT_UNSET=1
catch_errors
echo "Debug mode enabled"
# Script operations
```
### Error Analysis
```bash
#!/usr/bin/env bash
source error_handler.func
# Function to analyze errors
analyze_errors() {
local log_file="${1:-$DEBUG_LOGFILE}"
if [[ -f "$log_file" ]]; then
echo "Error Analysis:"
echo "Total errors: $(grep -c "ERROR" "$log_file")"
echo "Error types:"
grep "ERROR" "$log_file" | awk '{print $NF}' | sort | uniq -c
echo "Recent errors:"
tail -n 10 "$log_file"
else
echo "No error log found"
fi
}
# Run script with error analysis
analyze_errors
```
### Error Recovery Testing
```bash
#!/usr/bin/env bash
source error_handler.func
# Test error recovery
test_error_recovery() {
local test_cases=(
"nonexistent_command"
"apt-get install nonexistent_package"
"systemctl start nonexistent_service"
)
for test_case in "${test_cases[@]}"; do
echo "Testing: $test_case"
if silent $test_case; then
echo "Unexpected success"
else
echo "Expected failure handled"
fi
done
}
test_error_recovery
```

228
docs/misc/error_handler.func/README.md Normal file
View File

@ -0,0 +1,228 @@
# error_handler.func Documentation
## Overview
The `error_handler.func` file provides comprehensive error handling and signal management for Proxmox Community Scripts. It offers detailed error code explanations, graceful error recovery, and proper cleanup mechanisms.
## Purpose and Use Cases
- **Error Code Explanation**: Provides human-readable explanations for exit codes
- **Signal Handling**: Manages SIGINT, SIGTERM, and other signals gracefully
- **Error Recovery**: Implements proper cleanup and error reporting
- **Debug Logging**: Records error information for troubleshooting
- **Silent Execution Support**: Integrates with core.func silent execution
## Quick Reference
### Key Function Groups
- **Error Explanation**: `explain_exit_code()` - Convert exit codes to human-readable messages
- **Error Handling**: `error_handler()` - Main error handler with detailed reporting
- **Signal Handlers**: `on_interrupt()`, `on_terminate()` - Graceful signal handling
- **Cleanup**: `on_exit()` - Cleanup on script exit
- **Trap Setup**: `catch_errors()` - Initialize error handling traps
### Dependencies
- **External**: None (pure Bash implementation)
- **Internal**: Uses color variables from core.func
### Integration Points
- Used by: All scripts via core.func silent execution
- Uses: Color variables from core.func
- Provides: Error explanations for core.func silent function
## Documentation Files
### 📊 [ERROR_HANDLER_FLOWCHART.md](./ERROR_HANDLER_FLOWCHART.md)
Visual execution flows showing error handling processes and signal management.
### 📚 [ERROR_HANDLER_FUNCTIONS_REFERENCE.md](./ERROR_HANDLER_FUNCTIONS_REFERENCE.md)
Complete alphabetical reference of all functions with parameters, dependencies, and usage details.
### 💡 [ERROR_HANDLER_USAGE_EXAMPLES.md](./ERROR_HANDLER_USAGE_EXAMPLES.md)
Practical examples showing how to use error handling functions and common patterns.
### 🔗 [ERROR_HANDLER_INTEGRATION.md](./ERROR_HANDLER_INTEGRATION.md)
How error_handler.func integrates with other components and provides error handling services.
## Key Features
### Error Code Categories
- **Generic/Shell Errors**: Exit codes 1, 2, 126, 127, 128, 130, 137, 139, 143
- **Package Manager Errors**: APT/DPKG errors (100, 101, 255)
- **Node.js Errors**: JavaScript runtime errors (243-249, 254)
- **Python Errors**: Python environment and dependency errors (210-212)
- **Database Errors**: PostgreSQL, MySQL, MongoDB errors (231-254)
- **Proxmox Custom Errors**: Container and VM specific errors (200-231)
### Signal Handling
- **SIGINT (Ctrl+C)**: Graceful interruption handling
- **SIGTERM**: Graceful termination handling
- **EXIT**: Cleanup on script exit
- **ERR**: Error trap for command failures
### Error Reporting
- **Detailed Messages**: Human-readable error explanations
- **Context Information**: Line numbers, commands, timestamps
- **Log Integration**: Silent log file integration
- **Debug Logging**: Optional debug log file support
## Common Usage Patterns
### Basic Error Handling Setup
```bash
#!/usr/bin/env bash
# Basic error handling setup
source error_handler.func
# Initialize error handling
catch_errors
# Your script code here
# Errors will be automatically handled
```
### Manual Error Explanation
```bash
#!/usr/bin/env bash
source error_handler.func
# Get error explanation
explanation=$(explain_exit_code 127)
echo "Error 127: $explanation"
# Output: Error 127: Command not found
```
### Custom Error Handling
```bash
#!/usr/bin/env bash
source error_handler.func
# Custom error handling
if ! command -v required_tool >/dev/null 2>&1; then
echo "Error: required_tool not found"
exit 127
fi
```
## Environment Variables
### Debug Variables
- `DEBUG_LOGFILE`: Path to debug log file for error logging
- `SILENT_LOGFILE`: Path to silent execution log file
- `STRICT_UNSET`: Enable strict unset variable checking (0/1)
### Internal Variables
- `lockfile`: Lock file path for cleanup (set by calling script)
- `exit_code`: Current exit code
- `command`: Failed command
- `line_number`: Line number where error occurred
## Error Categories
### Generic/Shell Errors
- **1**: General error / Operation not permitted
- **2**: Misuse of shell builtins (syntax error)
- **126**: Command invoked cannot execute (permission problem)
- **127**: Command not found
- **128**: Invalid argument to exit
- **130**: Terminated by Ctrl+C (SIGINT)
- **137**: Killed (SIGKILL / Out of memory)
- **139**: Segmentation fault (core dumped)
- **143**: Terminated (SIGTERM)
### Package Manager Errors
- **100**: APT package manager error (broken packages)
- **101**: APT configuration error (bad sources.list)
- **255**: DPKG fatal internal error
### Node.js Errors
- **243**: JavaScript heap out of memory
- **245**: Invalid command-line option
- **246**: Internal JavaScript parse error
- **247**: Fatal internal error
- **248**: Invalid C++ addon / N-API failure
- **249**: Inspector error
- **254**: npm/pnpm/yarn unknown fatal error
### Python Errors
- **210**: Virtualenv/uv environment missing or broken
- **211**: Dependency resolution failed
- **212**: Installation aborted (permissions or EXTERNALLY-MANAGED)
### Database Errors
- **PostgreSQL (231-234)**: Connection, authentication, database, query errors
- **MySQL/MariaDB (241-244)**: Connection, authentication, database, query errors
- **MongoDB (251-254)**: Connection, authentication, database, query errors
### Proxmox Custom Errors
- **200**: Failed to create lock file
- **203**: Missing CTID variable
- **204**: Missing PCT_OSTYPE variable
- **205**: Invalid CTID (<100)
- **209**: Container creation failed
- **210**: Cluster not quorate
- **214**: Not enough storage space
- **215**: Container ID not listed
- **216**: RootFS entry missing in config
- **217**: Storage does not support rootdir
- **220**: Unable to resolve template path
- **222**: Template download failed after 3 attempts
- **223**: Template not available after download
- **231**: LXC stack upgrade/retry failed
## Best Practices
### Error Handling Setup
1. Source error_handler.func early in script
2. Call catch_errors() to initialize traps
3. Use proper exit codes for different error types
4. Provide meaningful error messages
### Signal Handling
1. Always set up signal traps
2. Provide graceful cleanup on interruption
3. Use appropriate exit codes for signals
4. Clean up temporary files and processes
### Error Reporting
1. Use explain_exit_code() for user-friendly messages
2. Log errors to debug files when needed
3. Provide context information (line numbers, commands)
4. Integrate with silent execution logging
## Troubleshooting
### Common Issues
1. **Missing Error Handler**: Ensure error_handler.func is sourced
2. **Trap Not Set**: Call catch_errors() to initialize traps
3. **Color Variables**: Ensure core.func is sourced for colors
4. **Lock Files**: Clean up lock files in on_exit()
### Debug Mode
Enable debug logging for detailed error information:
```bash
export DEBUG_LOGFILE="/tmp/debug.log"
source error_handler.func
catch_errors
```
### Error Code Testing
Test error explanations:
```bash
source error_handler.func
for code in 1 2 126 127 128 130 137 139 143; do
echo "Code $code: $(explain_exit_code $code)"
done
```
## Related Documentation
- [core.func](../core.func/) - Core utilities and silent execution
- [build.func](../build.func/) - Container creation with error handling
- [tools.func](../tools.func/) - Extended utilities with error handling
- [api.func](../api.func/) - API operations with error handling
---
*This documentation covers the error_handler.func file which provides comprehensive error handling for all Proxmox Community Scripts.*

2
misc/build.func
View File

@ -1625,6 +1625,8 @@ install_script() {
NEXTID=$(pvesh get /cluster/nextid)
timezone=$(cat /etc/timezone)
# Show APP Header
header_info
# --- Support CLI argument as direct preset (default, advanced, …) ---