community-scripts/ProxmoxVED
1
0
Fork 0
mirror of https://github.com/community-scripts/ProxmoxVED.git synced 2026-02-24 21:47:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Cleanup

Browse Source
This commit is contained in:
CanbiZ
2025-12-01 10:19:04 +01:00
parent 804426dd24
commit 43dd7aacc8
28 changed files with 11728 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

504
docs/CHANGELOG_MISC.md Normal file
View File

@@ -0,0 +1,504 @@
# Changelog: /misc Directory Refactoring
> **Last Updated**: November 28, 2025
> **Status**: Major Refactoring Complete
## Overview
The `/misc` directory has undergone significant refactoring to improve maintainability, security, and functionality. This document tracks all changes, removed files, and new patterns.
---
## File Status Summary
| File | Status | Notes |
|------|--------|-------|
| `api.func` | ✅ Active | API integration & reporting |
| `build.func` | ✅ Refactored | Core build orchestration (Major changes) |
| `cloud-init.sh` | ✅ Active | Cloud-Init VM configuration |
| `core.func` | ✅ Active | Core utilities & functions |
| `error_handler.func` | ✅ Active | Centralized error handling |
| `install.func` | ✅ Active | Container installation orchestration |
| `passthrough.func` | ✅ Active | Hardware passthrough utilities |
| `tools.func` | ✅ Active | Utility functions & repository setup |
| `vm-core.func` | ✅ Active | VM-specific core functions |
| `config-file.func` | ❌ **REMOVED** | Replaced by defaults system |
| `create_lxc.sh` | ❌ **REMOVED** | Replaced by install.func workflow |
---
## Major Changes in build.func
### 1. **Configuration System Overhaul**
#### ❌ Removed
- **`config-file.func` dependency**: Old configuration file format no longer used
- **Static configuration approach**: Replaced with dynamic variable-based system
#### ✅ New System: Three-Tier Defaults Architecture
```
Priority Hierarchy (Highest to Lowest):
1. Environment Variables (var_*) ← Highest Priority
2. App-Specific Defaults (.vars files)
3. User Defaults (default.vars)
4. Built-in Defaults ← Fallback
```
### 2. **Variable Whitelisting System**
A new security layer has been introduced to control which variables can be persisted:
```bash
# Allowed configurable variables
VAR_WHITELIST=(
var_apt_cacher var_apt_cacher_ip var_brg var_cpu var_disk var_fuse
var_gateway var_hostname var_ipv6_method var_mac var_mknod var_mount_fs var_mtu
var_net var_nesting var_ns var_protection var_pw var_ram var_tags var_timezone
var_tun var_unprivileged var_verbose var_vlan var_ssh var_ssh_authorized_key
var_container_storage var_template_storage
)
```
**Changes from Previous**:
- ❌ Removed: `var_ctid` (unique per container, cannot be shared)
- ❌ Removed: `var_ipv6_static` (static IPs are container-specific)
### 3. **Default Settings Management Functions**
#### `default_var_settings()`
- Creates/updates global user defaults at `/usr/local/community-scripts/default.vars`
- Loads existing defaults and merges with current settings
- Respects environment variable precedence
- Sanitizes values to prevent injection attacks
#### `get_app_defaults_path()`
- Returns app-specific defaults path: `/usr/local/community-scripts/defaults/<appname>.vars`
- Example: `/usr/local/community-scripts/defaults/pihole.vars`
#### `maybe_offer_save_app_defaults()`
- Called after advanced installation
- Offers to save current settings as app-specific defaults
- Provides diff view when updating existing defaults
- Validates against whitelist before saving
### 4. **Load Variables File Function**
#### `load_vars_file()`
- Safely loads variables from `.vars` files
- **Key Security Feature**: Does NOT use `source` or `eval`
- Manual parsing with whitelist validation
- Handles escaping and special characters
- Returns 0 on success, 1 on failure
**Example Usage**:
```bash
load_vars_file "/usr/local/community-scripts/defaults/pihole.vars"
```
### 5. **Removed Functions**
- ❌ `create_lxc()` - Replaced by install.func workflow
- ❌ `read_config()` - Replaced by load_vars_file()
- ❌ `write_config()` - Replaced by direct file generation with sanitization
---
## Installation Modes & Workflows
### Mode 1: **Default Settings**
```
Quick installation with pre-defined values
├── User selects OS/Version
├── Uses built-in defaults
└── Creates container immediately
```
**Use Case**: First-time users, basic deployments
### Mode 2: **Advanced Settings**
```
Full control over all parameters
├── User prompted for each setting
├── 19-step configuration wizard
├── Shows summary before confirmation
└── Offers to save as app defaults
```
**Use Case**: Custom configurations, experienced users
### Mode 3: **User Defaults** (formerly "My Defaults")
```
Installation using saved user defaults
├── Loads: /usr/local/community-scripts/default.vars
├── Shows loaded settings summary
└── Creates container
```
**Use Case**: Consistent deployments across multiple containers
### Mode 4: **App Defaults**
```
Installation using app-specific defaults (if available)
├── Loads: /usr/local/community-scripts/defaults/<app>.vars
├── Shows loaded settings summary
└── Creates container
```
**Use Case**: Repeat installations with saved configurations
### Mode 5: **Settings Menu**
```
Manage configuration files
├── View current settings
├── Edit storage selections
├── Manage defaults location
└── Reset to built-ins
```
**Use Case**: Configuration management
---
## Configurable Variables Reference
### Resource Allocation
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `var_cpu` | Integer | App-dependent | `4` |
| `var_ram` | Integer (MB) | App-dependent | `2048` |
| `var_disk` | Integer (GB) | App-dependent | `20` |
| `var_unprivileged` | Boolean (0/1) | `1` | `1` |
### Network Configuration
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `var_net` | String | Auto | `veth` |
| `var_brg` | String | `vmbr0` | `vmbr100` |
| `var_gateway` | IP Address | Auto-detected | `192.168.1.1` |
| `var_mtu` | Integer | `1500` | `9000` |
| `var_vlan` | Integer | None | `100` |
### Identity & Access
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `var_hostname` | String | App name | `mypihole` |
| `var_pw` | String | Random | `MySecurePass123!` |
| `var_ssh` | Boolean (yes/no) | `no` | `yes` |
| `var_ssh_authorized_key` | String | None | `ssh-rsa AAAA...` |
### Container Features
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `var_fuse` | Boolean (0/1) | `0` | `1` |
| `var_tun` | Boolean (0/1) | `0` | `1` |
| `var_nesting` | Boolean (0/1) | `0` | `1` |
| `var_keyctl` | Boolean (0/1) | `0` | `1` |
| `var_mknod` | Boolean (0/1) | `0` | `1` |
| `var_mount_fs` | String | None | `ext4` |
| `var_protection` | Boolean (0/1) | `0` | `1` |
### System Configuration
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `var_timezone` | String | System | `Europe/Berlin` |
| `var_searchdomain` | String | None | `example.com` |
| `var_apt_cacher` | String | None | `apt-cacher-ng` |
| `var_apt_cacher_ip` | IP Address | None | `192.168.1.100` |
| `var_tags` | String | App name | `docker,production` |
| `var_verbose` | Boolean (yes/no) | `no` | `yes` |
### Storage Configuration
| Variable | Type | Default | Example |
|----------|------|---------|---------|
| `var_container_storage` | String | Auto-detected | `local` |
| `var_template_storage` | String | Auto-detected | `local` |
---
## File Formats
### User Defaults: `/usr/local/community-scripts/default.vars`
```bash
# User Global Defaults
# Generated by ProxmoxVED Scripts
# Date: 2024-11-28
var_cpu=4
var_ram=2048
var_disk=20
var_unprivileged=1
var_brg=vmbr0
var_gateway=192.168.1.1
var_vlan=100
var_mtu=1500
var_hostname=mydefaults
var_timezone=Europe/Berlin
var_ssh=yes
var_ssh_authorized_key=ssh-rsa AAAAB3NzaC1...
var_container_storage=local
var_template_storage=local
```
### App Defaults: `/usr/local/community-scripts/defaults/<app>.vars`
```bash
# App-specific defaults for PiHole (pihole)
# Generated on 2024-11-28T15:32:00Z
var_unprivileged=1
var_cpu=2
var_ram=1024
var_disk=10
var_brg=vmbr0
var_net=veth
var_gateway=192.168.1.1
var_mtu=1500
var_vlan=100
var_hostname=pihole
var_timezone=Europe/Berlin
var_container_storage=local
var_template_storage=local
var_tags=dns,pihole
var_verbose=no
```
---
## Usage Examples
### Example 1: Set Global User Defaults
1. Run any app installation script
2. Select **Advanced Settings**
3. Configure all parameters
4. When prompted: **"Save as User Defaults?"** → Select **Yes**
5. File saved to: `/usr/local/community-scripts/default.vars`
**Future Installations**: Select **User Defaults** mode to reuse settings
### Example 2: Create & Use App Defaults
1. Run app installation (e.g., `pihole-install.sh`)
2. Select **Advanced Settings**
3. Fine-tune all parameters for PiHole
4. When prompted: **"Save as App Defaults for PiHole?"** → Select **Yes**
5. File saved to: `/usr/local/community-scripts/defaults/pihole.vars`
**Next Time**:
- Run `pihole-install.sh` again
- Select **App Defaults**
- Same settings automatically applied
### Example 3: Override via Environment Variables
```bash
# Set custom values before running script
export var_cpu=8
export var_ram=4096
export var_hostname=custom-pihole
bash pihole-install.sh
```
**Priority**: Environment variables override all defaults
### Example 4: Manual File Editing
```bash
# Edit User Defaults
sudo nano /usr/local/community-scripts/default.vars
# Edit App-Specific Defaults
sudo nano /usr/local/community-scripts/defaults/pihole.vars
# Verify syntax (no source/eval, safe to read)
cat /usr/local/community-scripts/default.vars
```
---
## Security Improvements
### 1. **No `source` or `eval` Used**
- ❌ OLD: `source config_file` (Dangerous - executes arbitrary code)
- ✅ NEW: `load_vars_file()` (Safe - manual parsing with validation)
### 2. **Variable Whitelisting**
- Only explicitly allowed variables can be persisted
- Prevents accidental storage of sensitive values
- Protects against injection attacks
### 3. **Value Sanitization**
```bash
# Prevents command injection
_sanitize_value() {
case "$1" in
*'$('* | *'`'* | *';'* | *'&'* | *'<('*)
return 1 # Reject dangerous values
;;
esac
echo "$1"
}
```
### 4. **File Permissions**
```bash
# Default vars accessible only to root
-rw-r--r-- root root /usr/local/community-scripts/default.vars
-rw-r--r-- root root /usr/local/community-scripts/defaults/pihole.vars
```
---
## Migration Guide
### For Users
**OLD Workflow**: Manual config file editing
**NEW Workflow**:
1. Run installation script
2. Select "Advanced Settings"
3. Answer prompts
4. Save as defaults when offered
### For Script Developers
**OLD Pattern**:
```bash
source /path/to/config-file.conf
```
**NEW Pattern**:
```bash
# User defaults are automatically loaded in build.func
# No manual intervention needed
# Just use the variables directly
```
---
## Removed Components
### `config-file.func` (Deprecated)
**Reason**: Replaced by three-tier defaults system
- Static configuration was inflexible
- Manual editing error-prone
- No validation or sanitization
**Migration Path**: Use app/user defaults system
### `create_lxc.sh` (Deprecated)
**Reason**: Workflow integrated into install.func
- Centralized container creation logic
- Better error handling
- Unified with VM creation
**Migration Path**: Use install.func directly
---
## Future Enhancements
### Planned Features
1. **Configuration UI**: Web-based settings editor
2. **Configuration Sync**: Push defaults to multiple nodes
3. **Configuration History**: Track changes and diffs
4. **Batch Operations**: Apply defaults to multiple containers
5. **Configuration Templates**: Pre-built setting templates per app
---
## Troubleshooting
### Issue: Defaults not loading
**Solution**:
```bash
# Check if defaults file exists
ls -la /usr/local/community-scripts/default.vars
# Verify syntax
cat /usr/local/community-scripts/default.vars
# Check file permissions
sudo chown root:root /usr/local/community-scripts/default.vars
sudo chmod 644 /usr/local/community-scripts/default.vars
```
### Issue: Variable not being applied
**Solution**:
1. Check if variable is in `VAR_WHITELIST`
2. Verify variable name starts with `var_`
3. Check syntax in .vars file (no spaces around `=`)
4. Use `cat` not `source` to read files
### Issue: "Invalid option" in defaults menu
**Solution**:
- Ensure defaults directory exists: `/usr/local/community-scripts/defaults/`
- Create if missing: `sudo mkdir -p /usr/local/community-scripts/defaults/`
---
## Technical Reference
### Variable Loading Precedence
```
1. parse ARGV
2. capture ENV variables (hard environment)
3. load defaults file if exists
4. load app-specific defaults if exists
5. parse command line flags (lowest priority for overrides)
Precedence (Highest to Lowest):
ENV var_* > AppDefaults.vars > UserDefaults.vars > Built-ins
```
### State Machine: Installation Modes
```
┌─────────────────┐
│ Start Script │
└────────┬────────┘
│
┌────v────────────────┐
│ Display Mode Menu │
└────┬─────────────────┘
│
┌────────────────────────────────────┐
│ User Selects Mode │
├──────────┬──────────┬──────────┬──────────┐
│ │ │ │ │
v v v v v
┌─────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ ┌───────┐
│Def. │ │Adv. │ │User │ │App │ │Setting│
│Set. │ │Set. │ │Default │ │Default │ │Menu │
└─────┘ └────────┘ └──────────┘ └─────────┘ └───────┘
```
---
## Document Versions
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2024-11-28 | Initial comprehensive documentation |
---
**Last Updated**: November 28, 2025
**Maintainers**: community-scripts Team
**License**: MIT

748
docs/DEFAULTS_SYSTEM_GUIDE.md Normal file
View File

@@ -0,0 +1,748 @@
# Configuration & Defaults System - User Guide
> **Complete Guide to App Defaults and User Defaults**
>
> *Learn how to configure, save, and reuse your installation settings*
---
## Table of Contents
1. [Quick Start](#quick-start)
2. [Understanding the Defaults System](#understanding-the-defaults-system)
3. [Installation Modes](#installation-modes)
4. [How to Save Defaults](#how-to-save-defaults)
5. [How to Use Saved Defaults](#how-to-use-saved-defaults)
6. [Managing Your Defaults](#managing-your-defaults)
7. [Advanced Configuration](#advanced-configuration)
8. [Troubleshooting](#troubleshooting)
---
## Quick Start
### 30-Second Setup
```bash
# 1. Run any container installation script
bash pihole-install.sh
# 2. When prompted, select: "Advanced Settings"
# (This allows you to customize everything)
# 3. Answer all configuration questions
# 4. At the end, when asked "Save as App Defaults?"
# Select: YES
# 5. Done! Your settings are now saved
```
**Next Time**: Run the same script again, select **"App Defaults"** and your settings will be applied automatically!
---
## Understanding the Defaults System
### The Three-Tier System
Your installation settings are managed through three layers:
#### 🔷 **Tier 1: Built-in Defaults** (Fallback)
```
These are hardcoded in the scripts
Provide sensible defaults for each application
Example: PiHole uses 2 CPU cores by default
```
#### 🔶 **Tier 2: User Defaults** (Global)
```
Your personal global defaults
Applied to ALL container installations
Location: /usr/local/community-scripts/default.vars
Example: "I always want 4 CPU cores and 2GB RAM"
```
#### 🔴 **Tier 3: App Defaults** (Specific)
```
Application-specific saved settings
Only applied when installing that specific app
Location: /usr/local/community-scripts/defaults/<appname>.vars
Example: "Whenever I install PiHole, use these exact settings"
```
### Priority System
When installing a container, settings are applied in this order:
```
┌─────────────────────────────────────┐
│ 1. Environment Variables (HIGHEST) │ Set in shell: export var_cpu=8
│ (these override everything) │
├─────────────────────────────────────┤
│ 2. App Defaults │ From: defaults/pihole.vars
│ (app-specific saved settings) │
├─────────────────────────────────────┤
│ 3. User Defaults │ From: default.vars
│ (your global defaults) │
├─────────────────────────────────────┤
│ 4. Built-in Defaults (LOWEST) │ Hardcoded in script
│ (failsafe, always available) │
└─────────────────────────────────────┘
```
**In Plain English**:
- If you set an environment variable → it wins
- Otherwise, if you have app-specific defaults → use those
- Otherwise, if you have user defaults → use those
- Otherwise, use the hardcoded defaults
---
## Installation Modes
When you run any installation script, you'll be presented with a menu:
### Option 1️⃣ : **Default Settings**
```
Quick installation with standard settings
├─ Best for: First-time users, quick deployments
├─ What happens:
│ 1. Script uses built-in defaults
│ 2. Container created immediately
│ 3. No questions asked
└─ Time: ~2 minutes
```
**When to use**: You want a standard installation, don't need customization
---
### Option 2️⃣ : **Advanced Settings**
```
Full customization with 19 configuration steps
├─ Best for: Power users, custom requirements
├─ What happens:
│ 1. Script asks for EVERY setting
│ 2. You control: CPU, RAM, Disk, Network, SSH, etc.
│ 3. Shows summary before creating
│ 4. Offers to save as App Defaults
└─ Time: ~5-10 minutes
```
**When to use**: You want full control over the configuration
**Available Settings**:
- CPU cores, RAM amount, Disk size
- Container name, network settings
- SSH access, API access, Features
- Password, SSH keys, Tags
---
### Option 3️⃣ : **User Defaults**
```
Use your saved global defaults
├─ Best for: Consistent deployments across many containers
├─ Requires: You've previously saved User Defaults
├─ What happens:
│ 1. Loads settings from: /usr/local/community-scripts/default.vars
│ 2. Shows you the loaded settings
│ 3. Creates container immediately
└─ Time: ~2 minutes
```
**When to use**: You have preferred defaults you want to use for every app
---
### Option 4️⃣ : **App Defaults** (if available)
```
Use previously saved app-specific defaults
├─ Best for: Repeating the same configuration multiple times
├─ Requires: You've previously saved App Defaults for this app
├─ What happens:
│ 1. Loads settings from: /usr/local/community-scripts/defaults/<app>.vars
│ 2. Shows you the loaded settings
│ 3. Creates container immediately
└─ Time: ~2 minutes
```
**When to use**: You've installed this app before and want identical settings
---
### Option 5️⃣ : **Settings Menu**
```
Manage your saved configurations
├─ Functions:
│ • View current settings
│ • Edit storage selections
│ • Manage defaults location
│ • See what's currently configured
└─ Time: ~1 minute
```
**When to use**: You want to review or modify saved settings
---
## How to Save Defaults
### Method 1: Save While Installing
This is the easiest way:
#### Step-by-Step: Create App Defaults
```bash
# 1. Run the installation script
bash pihole-install.sh
# 2. Choose installation mode
# ┌─────────────────────────┐
# │ Select installation mode:│
# │ 1) Default Settings │
# │ 2) Advanced Settings │
# │ 3) User Defaults │
# │ 4) App Defaults │
# │ 5) Settings Menu │
# └─────────────────────────┘
#
# Enter: 2 (Advanced Settings)
# 3. Answer all configuration questions
# • Container name? → my-pihole
# • CPU cores? → 4
# • RAM amount? → 2048
# • Disk size? → 20
# • SSH access? → yes
# ... (more options)
# 4. Review summary (shown before creation)
# ✓ Confirm to proceed
# 5. After creation completes, you'll see:
# ┌──────────────────────────────────┐
# │ Save as App Defaults for PiHole? │
# │ (Yes/No) │
# └──────────────────────────────────┘
#
# Select: Yes
# 6. Done! Settings saved to:
# /usr/local/community-scripts/defaults/pihole.vars
```
#### Step-by-Step: Create User Defaults
```bash
# Same as App Defaults, but:
# When you select "Advanced Settings"
# FIRST app you run with this selection will offer
# to save as "User Defaults" additionally
# This saves to: /usr/local/community-scripts/default.vars
```
---
### Method 2: Manual File Creation
For advanced users who want to create defaults without running installation:
```bash
# Create User Defaults manually
sudo tee /usr/local/community-scripts/default.vars > /dev/null << 'EOF'
# Global User Defaults
var_cpu=4
var_ram=2048
var_disk=20
var_unprivileged=1
var_brg=vmbr0
var_gateway=192.168.1.1
var_timezone=Europe/Berlin
var_ssh=yes
var_container_storage=local
var_template_storage=local
EOF
# Create App Defaults manually
sudo tee /usr/local/community-scripts/defaults/pihole.vars > /dev/null << 'EOF'
# App-specific defaults for PiHole
var_unprivileged=1
var_cpu=2
var_ram=1024
var_disk=10
var_brg=vmbr0
var_gateway=192.168.1.1
var_hostname=pihole
var_container_storage=local
var_template_storage=local
EOF
```
---
### Method 3: Using Environment Variables
Set defaults via environment before running:
```bash
# Set as environment variables
export var_cpu=4
export var_ram=2048
export var_disk=20
export var_hostname=my-container
# Run installation
bash pihole-install.sh
# These settings will be used
# (Can still be overridden by saved defaults)
```
---
## How to Use Saved Defaults
### Using User Defaults
```bash
# 1. Run any installation script
bash pihole-install.sh
# 2. When asked for mode, select:
# Option: 3 (User Defaults)
# 3. Your settings from default.vars are applied
# 4. Container created with your saved settings
```
### Using App Defaults
```bash
# 1. Run the app you configured before
bash pihole-install.sh
# 2. When asked for mode, select:
# Option: 4 (App Defaults)
# 3. Your settings from defaults/pihole.vars are applied
# 4. Container created with exact same settings
```
### Overriding Saved Defaults
```bash
# Even if you have defaults saved,
# you can override them with environment variables
export var_cpu=8 # Override saved defaults
export var_hostname=custom-name
bash pihole-install.sh
# Installation will use these values instead of saved defaults
```
---
## Managing Your Defaults
### View Your Settings
#### View User Defaults
```bash
cat /usr/local/community-scripts/default.vars
```
#### View App Defaults
```bash
cat /usr/local/community-scripts/defaults/pihole.vars
```
#### List All Saved App Defaults
```bash
ls -la /usr/local/community-scripts/defaults/
```
### Edit Your Settings
#### Edit User Defaults
```bash
sudo nano /usr/local/community-scripts/default.vars
```
#### Edit App Defaults
```bash
sudo nano /usr/local/community-scripts/defaults/pihole.vars
```
### Update Existing Defaults
```bash
# Run installation again with your app
bash pihole-install.sh
# Select: Advanced Settings
# Make desired changes
# At end, when asked to save:
# "Defaults already exist, Update?"
# Select: Yes
# Your saved defaults are updated
```
### Delete Defaults
#### Delete User Defaults
```bash
sudo rm /usr/local/community-scripts/default.vars
```
#### Delete App Defaults
```bash
sudo rm /usr/local/community-scripts/defaults/pihole.vars
```
#### Delete All App Defaults
```bash
sudo rm /usr/local/community-scripts/defaults/*
```
---
## Advanced Configuration
### Available Variables
All configurable variables start with `var_`:
#### Resource Allocation
```bash
var_cpu=4 # CPU cores
var_ram=2048 # RAM in MB
var_disk=20 # Disk in GB
var_unprivileged=1 # 0=privileged, 1=unprivileged
```
#### Network
```bash
var_brg=vmbr0 # Bridge interface
var_net=veth # Network driver
var_gateway=192.168.1.1 # Default gateway
var_mtu=1500 # MTU size
var_vlan=100 # VLAN ID
```
#### System
```bash
var_hostname=pihole # Container name
var_timezone=Europe/Berlin # Timezone
var_pw=SecurePass123 # Root password
var_tags=dns,pihole # Tags for organization
var_verbose=yes # Enable verbose output
```
#### Security & Access
```bash
var_ssh=yes # Enable SSH
var_ssh_authorized_key="ssh-rsa AA..." # SSH public key
var_protection=1 # Enable protection flag
```
#### Features
```bash
var_fuse=1 # FUSE filesystem support
var_tun=1 # TUN device support
var_nesting=1 # Nesting (Docker in LXC)
var_keyctl=1 # Keyctl syscall
var_mknod=1 # Device node creation
```
#### Storage
```bash
var_container_storage=local # Where to store container
var_template_storage=local # Where to store templates
```
### Example Configuration Files
#### Gaming Server Defaults
```bash
# High performance for gaming containers
var_cpu=8
var_ram=4096
var_disk=50
var_unprivileged=0
var_fuse=1
var_nesting=1
var_tags=gaming
```
#### Development Server
```bash
# Development with Docker support
var_cpu=4
var_ram=2048
var_disk=30
var_unprivileged=1
var_nesting=1
var_ssh=yes
var_tags=development
```
#### IoT/Monitoring
```bash
# Low-resource, always-on containers
var_cpu=2
var_ram=512
var_disk=10
var_unprivileged=1
var_nesting=0
var_fuse=0
var_tun=0
var_tags=iot,monitoring
```
---
## Troubleshooting
### "App Defaults not available" Message
**Problem**: You want to use App Defaults, but option says they're not available
**Solution**:
1. You haven't created App Defaults yet for this app
2. Run the app with "Advanced Settings"
3. When finished, save as App Defaults
4. Next time, App Defaults will be available
---
### "Settings not being applied"
**Problem**: You saved defaults, but they're not being used
**Checklist**:
```bash
# 1. Verify files exist
ls -la /usr/local/community-scripts/default.vars
ls -la /usr/local/community-scripts/defaults/<app>.vars
# 2. Check file permissions (should be readable)
stat /usr/local/community-scripts/default.vars
# 3. Verify correct mode selected
# (Make sure you selected "User Defaults" or "App Defaults")
# 4. Check for environment variable override
env | grep var_
# If you have var_* set in environment,
# those override your saved defaults
```
---
### "Cannot write to defaults location"
**Problem**: Permission denied when saving defaults
**Solution**:
```bash
# Create the defaults directory if missing
sudo mkdir -p /usr/local/community-scripts/defaults
# Fix permissions
sudo chmod 755 /usr/local/community-scripts
sudo chmod 755 /usr/local/community-scripts/defaults
# Make sure you're running as root
sudo bash pihole-install.sh
```
---
### "Defaults directory doesn't exist"
**Problem**: Script can't find where to save defaults
**Solution**:
```bash
# Create the directory
sudo mkdir -p /usr/local/community-scripts/defaults
# Verify
ls -la /usr/local/community-scripts/
```
---
### Settings seem random or wrong
**Problem**: Container gets different settings than expected
**Possible Causes & Solutions**:
```bash
# 1. Check if environment variables are set
env | grep var_
# If you see var_* entries, those override your defaults
# Clear them: unset var_cpu var_ram (etc)
# 2. Verify correct defaults are in files
cat /usr/local/community-scripts/default.vars
cat /usr/local/community-scripts/defaults/pihole.vars
# 3. Check which mode you actually selected
# (Script output shows which defaults were applied)
# 4. Check Proxmox logs for errors
sudo journalctl -u pve-daemon -n 50
```
---
### "Variable not recognized"
**Problem**: You set a variable that doesn't work
**Solution**:
Only certain variables are allowed (security whitelist):
```
Allowed variables (starting with var_):
✓ var_cpu, var_ram, var_disk, var_unprivileged
✓ var_brg, var_gateway, var_mtu, var_vlan, var_net
✓ var_hostname, var_pw, var_timezone
✓ var_ssh, var_ssh_authorized_key
✓ var_fuse, var_tun, var_nesting, var_keyctl
✓ var_container_storage, var_template_storage
✓ var_tags, var_verbose
✓ var_apt_cacher, var_apt_cacher_ip
✓ var_protection, var_mount_fs
✗ Other variables are NOT supported
```
---
## Best Practices
### ✅ Do's
✓ Use **App Defaults** when you want app-specific settings
✓ Use **User Defaults** for your global preferences
✓ Edit defaults files directly with `nano` (safe)
✓ Keep separate App Defaults for each app
✓ Back up your defaults regularly
✓ Use environment variables for temporary overrides
### ❌ Don'ts
✗ Don't use `source` on defaults files (security risk)
✗ Don't put sensitive passwords in defaults (use SSH keys)
✗ Don't modify defaults while installation is running
✗ Don't delete defaults.d while containers are being created
✗ Don't use special characters without escaping
---
## Quick Reference
### Defaults Locations
| Type | Location | Example |
|------|----------|---------|
| User Defaults | `/usr/local/community-scripts/default.vars` | Global settings |
| App Defaults | `/usr/local/community-scripts/defaults/<app>.vars` | PiHole-specific |
| Backup Dir | `/usr/local/community-scripts/defaults/` | All app defaults |
### File Format
```bash
# Comments start with #
var_name=value
# No spaces around =
✓ var_cpu=4
✗ var_cpu = 4
# String values don't need quotes
✓ var_hostname=mycontainer
✓ var_hostname='mycontainer'
# Values with spaces need quotes
✓ var_tags="docker,production,testing"
✗ var_tags=docker,production,testing
```
### Command Reference
```bash
# View defaults
cat /usr/local/community-scripts/default.vars
# Edit defaults
sudo nano /usr/local/community-scripts/default.vars
# List all app defaults
ls /usr/local/community-scripts/defaults/
# Backup your defaults
cp -r /usr/local/community-scripts/defaults/ ~/defaults-backup/
# Set temporary override
export var_cpu=8
bash pihole-install.sh
# Create custom defaults
sudo tee /usr/local/community-scripts/defaults/custom.vars << 'EOF'
var_cpu=4
var_ram=2048
EOF
```
---
## Getting Help
### Need More Information?
- 📖 [Main Documentation](../../docs/)
- 🐛 [Report Issues](https://github.com/community-scripts/ProxmoxVED/issues)
- 💬 [Discussions](https://github.com/community-scripts/ProxmoxVED/discussions)
### Useful Commands
```bash
# Check what variables are available
grep "var_" /path/to/app-install.sh | head -20
# Verify defaults syntax
cat /usr/local/community-scripts/default.vars
# Monitor installation with defaults
bash pihole-install.sh 2>&1 | tee installation.log
```
---
## Document Information
| Field | Value |
|-------|-------|
| Version | 1.0 |
| Last Updated | November 28, 2025 |
| Status | Current |
| License | MIT |
---
**Happy configuring! 🚀**

881
docs/TECHNICAL_REFERENCE.md Normal file
View File

@@ -0,0 +1,881 @@
# Technical Reference: Configuration System Architecture
> **For Developers and Advanced Users**
>
> *Deep dive into how the defaults and configuration system works*
---
## Table of Contents
1. [System Architecture](#system-architecture)
2. [File Format Specifications](#file-format-specifications)
3. [Function Reference](#function-reference)
4. [Variable Precedence](#variable-precedence)
5. [Data Flow Diagrams](#data-flow-diagrams)
6. [Security Model](#security-model)
7. [Implementation Details](#implementation-details)
---
## System Architecture
### Component Overview
```
┌─────────────────────────────────────────────────────────────┐
│ Installation Script │
│ (pihole-install.sh, docker-install.sh, etc.) │
└────────────────────┬────────────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────────┐
│ build.func Library │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ variables() │ │
│ │ - Initialize NSAPP, var_install, etc. │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ install_script() │ │
│ │ - Display mode menu │ │
│ │ - Route to appropriate workflow │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ base_settings() │ │
│ │ - Apply built-in defaults │ │
│ │ - Read environment variables (var_*) │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ load_vars_file() │ │
│ │ - Safe file parsing (NO source/eval) │ │
│ │ - Whitelist validation │ │
│ │ - Value sanitization │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ default_var_settings() │ │
│ │ - Load user defaults │ │
│ │ - Display summary │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ maybe_offer_save_app_defaults() │ │
│ │ - Offer to save current settings │ │
│ │ - Handle updates vs. new saves │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────────┐
│ Configuration Files (on Disk) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ /usr/local/community-scripts/default.vars │ │
│ │ (User global defaults) │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ /usr/local/community-scripts/defaults/*.vars │ │
│ │ (App-specific defaults) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## File Format Specifications
### User Defaults: `default.vars`
**Location**: `/usr/local/community-scripts/default.vars`
**MIME Type**: `text/plain`
**Encoding**: UTF-8 (no BOM)
**Format Specification**:
```
# File Format: Simple key=value pairs
# Purpose: Store global user defaults
# Security: Sanitized values, whitelist validation
# Comments and blank lines are ignored
# Line format: var_name=value
# No spaces around the equals sign
# String values do not need quoting (but may be quoted)
[CONTENT]
var_cpu=4
var_ram=2048
var_disk=20
var_hostname=mydefault
var_brg=vmbr0
var_gateway=192.168.1.1
```
**Formal Grammar**:
```
FILE := (BLANK_LINE | COMMENT_LINE | VAR_LINE)*
BLANK_LINE := \n
COMMENT_LINE := '#' [^\n]* \n
VAR_LINE := VAR_NAME '=' VAR_VALUE \n
VAR_NAME := 'var_' [a-z_]+
VAR_VALUE := [^\n]* # Any printable characters except newline
```
**Constraints**:
| Constraint | Value |
|-----------|-------|
| Max file size | 64 KB |
| Max line length | 1024 bytes |
| Max variables | 100 |
| Allowed var names | `var_[a-z_]+` |
| Value validation | Whitelist + Sanitization |
**Example Valid File**:
```bash
# Global User Defaults
# Created: 2024-11-28
# Resource defaults
var_cpu=4
var_ram=2048
var_disk=20
# Network defaults
var_brg=vmbr0
var_gateway=192.168.1.1
var_mtu=1500
var_vlan=100
# System defaults
var_timezone=Europe/Berlin
var_hostname=default-container
# Storage
var_container_storage=local
var_template_storage=local
# Security
var_ssh=yes
var_protection=0
var_unprivileged=1
```
### App Defaults: `<app>.vars`
**Location**: `/usr/local/community-scripts/defaults/<appname>.vars`
**Format**: Identical to `default.vars`
**Naming Convention**: `<nsapp>.vars`
- `nsapp` = lowercase app name with spaces removed
- Examples:
- `pihole` → `pihole.vars`
- `opnsense` → `opnsense.vars`
- `docker compose` → `dockercompose.vars`
**Example App Defaults**:
```bash
# App-specific defaults for PiHole (pihole)
# Generated on 2024-11-28T15:32:00Z
# These override user defaults when installing pihole
var_unprivileged=1
var_cpu=2
var_ram=1024
var_disk=10
var_brg=vmbr0
var_net=veth
var_gateway=192.168.1.1
var_hostname=pihole
var_timezone=Europe/Berlin
var_container_storage=local
var_template_storage=local
var_tags=dns,pihole
```
---
## Function Reference
### `load_vars_file()`
**Purpose**: Safely load variables from .vars files without using `source` or `eval`
**Signature**:
```bash
load_vars_file(filepath)
```
**Parameters**:
| Param | Type | Required | Example |
|-------|------|----------|---------|
| filepath | String | Yes | `/usr/local/community-scripts/default.vars` |
**Returns**:
- `0` on success
- `1` on error (file missing, parse error, etc.)
**Environment Side Effects**:
- Sets all parsed `var_*` variables as shell variables
- Does NOT unset variables if file missing (safe)
- Does NOT affect other variables
**Implementation Pattern**:
```bash
load_vars_file() {
local file="$1"
# File must exist
[ -f "$file" ] || return 0
# Parse line by line (not with source/eval)
local line key val
while IFS='=' read -r key val || [ -n "$key" ]; do
# Skip comments and empty lines
[[ "$key" =~ ^[[:space:]]*# ]] && continue
[[ -z "$key" ]] && continue
# Validate key is in whitelist
_is_whitelisted_key "$key" || continue
# Sanitize and export value
val="$(_sanitize_value "$val")"
[ $? -eq 0 ] && export "$key=$val"
done < "$file"
return 0
}
```
**Usage Examples**:
```bash
# Load user defaults
load_vars_file "/usr/local/community-scripts/default.vars"
# Load app-specific defaults
load_vars_file "$(get_app_defaults_path)"
# Check if successful
if load_vars_file "$vars_path"; then
echo "Settings loaded successfully"
else
echo "Failed to load settings"
fi
# Values are now available as variables
echo "Using $var_cpu cores"
echo "Allocating ${var_ram} MB RAM"
```
---
### `get_app_defaults_path()`
**Purpose**: Get the full path for app-specific defaults file
**Signature**:
```bash
get_app_defaults_path()
```
**Parameters**: None
**Returns**:
- String: Full path to app defaults file
**Implementation**:
```bash
get_app_defaults_path() {
local n="${NSAPP:-${APP,,}}"
echo "/usr/local/community-scripts/defaults/${n}.vars"
}
```
**Usage Examples**:
```bash
# Get app defaults path
app_defaults="$(get_app_defaults_path)"
echo "App defaults at: $app_defaults"
# Check if app defaults exist
if [ -f "$(get_app_defaults_path)" ]; then
echo "App defaults available"
fi
# Load app defaults
load_vars_file "$(get_app_defaults_path)"
```
---
### `default_var_settings()`
**Purpose**: Load and display user global defaults
**Signature**:
```bash
default_var_settings()
```
**Parameters**: None
**Returns**:
- `0` on success
- `1` on error
**Workflow**:
```
1. Find default.vars location
(usually /usr/local/community-scripts/default.vars)
2. Create if missing
3. Load variables from file
4. Map var_verbose → VERBOSE variable
5. Call base_settings (apply to container config)
6. Call echo_default (display summary)
```
**Implementation Pattern**:
```bash
default_var_settings() {
local VAR_WHITELIST=(
var_apt_cacher var_apt_cacher_ip var_brg var_cpu var_disk var_fuse
var_gateway var_hostname var_ipv6_method var_mac var_mtu
var_net var_ns var_pw var_ram var_tags var_tun var_unprivileged
var_verbose var_vlan var_ssh var_ssh_authorized_key
var_container_storage var_template_storage
)
# Ensure file exists
_ensure_default_vars
# Find and load
local dv="$(_find_default_vars)"
load_vars_file "$dv"
# Map verbose flag
if [[ -n "${var_verbose:-}" ]]; then
case "${var_verbose,,}" in
1 | yes | true | on) VERBOSE="yes" ;;
*) VERBOSE="${var_verbose}" ;;
esac
fi
# Apply and display
base_settings "$VERBOSE"
echo_default
}
```
---
### `maybe_offer_save_app_defaults()`
**Purpose**: Offer to save current settings as app-specific defaults
**Signature**:
```bash
maybe_offer_save_app_defaults()
```
**Parameters**: None
**Returns**: None (side effects only)
**Behavior**:
1. After advanced installation completes
2. Offers user: "Save as App Defaults for <APP>?"
3. If yes:
- Saves to `/usr/local/community-scripts/defaults/<app>.vars`
- Only whitelisted variables included
- Previous defaults backed up (if exists)
4. If no:
- No action taken
**Flow**:
```bash
maybe_offer_save_app_defaults() {
local app_vars_path="$(get_app_defaults_path)"
# Build current settings from memory
local new_tmp="$(_build_current_app_vars_tmp)"
# Check if already exists
if [ -f "$app_vars_path" ]; then
# Show diff and ask: Update? Keep? View Diff?
_show_app_defaults_diff_menu "$new_tmp" "$app_vars_path"
else
# New defaults - just save
if whiptail --yesno "Save as App Defaults for $APP?" 10 60; then
mv "$new_tmp" "$app_vars_path"
chmod 644 "$app_vars_path"
fi
fi
}
```
---
### `_sanitize_value()`
**Purpose**: Remove dangerous characters/patterns from configuration values
**Signature**:
```bash
_sanitize_value(value)
```
**Parameters**:
| Param | Type | Required |
|-------|------|----------|
| value | String | Yes |
**Returns**:
- `0` (success) + sanitized value on stdout
- `1` (failure) + nothing if dangerous
**Dangerous Patterns**:
| Pattern | Threat | Example |
|---------|--------|---------|
| `$(...)` | Command substitution | `$(rm -rf /)` |
| `` ` ` `` | Command substitution | `` `whoami` `` |
| `;` | Command separator | `value; rm -rf /` |
| `&` | Background execution | `value & malicious` |
| `<(` | Process substitution | `<(cat /etc/passwd)` |
**Implementation**:
```bash
_sanitize_value() {
case "$1" in
*'$('* | *'`'* | *';'* | *'&'* | *'<('*)
echo ""
return 1 # Reject dangerous value
;;
esac
echo "$1"
return 0
}
```
**Usage Examples**:
```bash
# Safe value
_sanitize_value "192.168.1.1" # Returns: 192.168.1.1 (status: 0)
# Dangerous value
_sanitize_value "$(whoami)" # Returns: (empty) (status: 1)
# Usage in code
if val="$(_sanitize_value "$user_input")"; then
export var_hostname="$val"
else
msg_error "Invalid value: contains dangerous characters"
fi
```
---
### `_is_whitelisted_key()`
**Purpose**: Check if variable name is in allowed whitelist
**Signature**:
```bash
_is_whitelisted_key(key)
```
**Parameters**:
| Param | Type | Required | Example |
|-------|------|----------|---------|
| key | String | Yes | `var_cpu` |
**Returns**:
- `0` if key is whitelisted
- `1` if key is NOT whitelisted
**Implementation**:
```bash
_is_whitelisted_key() {
local k="$1"
local w
for w in "${VAR_WHITELIST[@]}"; do
[ "$k" = "$w" ] && return 0
done
return 1
}
```
**Usage Examples**:
```bash
# Check if variable can be saved
if _is_whitelisted_key "var_cpu"; then
echo "var_cpu can be saved"
fi
# Reject unknown variables
if ! _is_whitelisted_key "var_custom"; then
msg_error "var_custom is not supported"
fi
```
---
## Variable Precedence
### Loading Order
When a container is being created, variables are resolved in this order:
```
Step 1: Read ENVIRONMENT VARIABLES
├─ Check if var_cpu is already set in shell environment
├─ Check if var_ram is already set
└─ ...all var_* variables
Step 2: Load APP-SPECIFIC DEFAULTS
├─ Check if /usr/local/community-scripts/defaults/pihole.vars exists
├─ Load all var_* from that file
└─ These override built-ins but NOT environment variables
Step 3: Load USER GLOBAL DEFAULTS
├─ Check if /usr/local/community-scripts/default.vars exists
├─ Load all var_* from that file
└─ These override built-ins but NOT app-specific
Step 4: Use BUILT-IN DEFAULTS
└─ Hardcoded in script (lowest priority)
```
### Precedence Examples
**Example 1: Environment Variable Wins**
```bash
# Shell environment has highest priority
$ export var_cpu=16
$ bash pihole-install.sh
# Result: Container gets 16 cores
# (ignores app defaults, user defaults, built-ins)
```
**Example 2: App Defaults Override User Defaults**
```bash
# User Defaults: var_cpu=4
# App Defaults: var_cpu=2
$ bash pihole-install.sh
# Result: Container gets 2 cores
# (app-specific setting takes precedence)
```
**Example 3: All Defaults Missing (Built-ins Used)**
```bash
# No environment variables set
# No app defaults file
# No user defaults file
$ bash pihole-install.sh
# Result: Uses built-in defaults
# (var_cpu might be 2 by default)
```
### Implementation in Code
```bash
# Typical pattern in build.func
base_settings() {
# Priority 1: Environment variables (already set if export used)
CT_TYPE=${var_unprivileged:-"1"} # Use existing or default
# Priority 2: Load app defaults (may override above)
if [ -f "$(get_app_defaults_path)" ]; then
load_vars_file "$(get_app_defaults_path)"
fi
# Priority 3: Load user defaults
if [ -f "/usr/local/community-scripts/default.vars" ]; then
load_vars_file "/usr/local/community-scripts/default.vars"
fi
# Priority 4: Apply built-in defaults (lowest)
CORE_COUNT=${var_cpu:-"${APP_CPU_DEFAULT:-2}"}
RAM_SIZE=${var_ram:-"${APP_RAM_DEFAULT:-1024}"}
# Result: var_cpu has been set through precedence chain
}
```
---
## Data Flow Diagrams
### Installation Flow: Advanced Settings
```
┌──────────────┐
│ Start Script│
└──────┬───────┘
│
v
┌──────────────────────────────┐
│ Display Installation Mode │
│ Menu (5 options) │
└──────┬───────────────────────┘
│ User selects "Advanced Settings"
v
┌──────────────────────────────────┐
│ Call: base_settings() │
│ (Apply built-in defaults) │
└──────┬───────────────────────────┘
│
v
┌──────────────────────────────────┐
│ Call: advanced_settings() │
│ (Show 19-step wizard) │
│ - Ask CPU, RAM, Disk, Network... │
└──────┬───────────────────────────┘
│
v
┌──────────────────────────────────┐
│ Show Summary │
│ Review all chosen values │
└──────┬───────────────────────────┘
│ User confirms
v
┌──────────────────────────────────┐
│ Create Container │
│ Using current variable values │
└──────┬───────────────────────────┘
│
v
┌──────────────────────────────────┐
│ Installation Complete │
└──────┬───────────────────────────┘
│
v
┌──────────────────────────────────────┐
│ Offer: Save as App Defaults? │
│ (Save current settings) │
└──────┬───────────────────────────────┘
│
├─ YES → Save to defaults/<app>.vars
│
└─ NO → Exit
```
### Variable Resolution Flow
```
CONTAINER CREATION STARTED
│
v
┌─────────────────────┐
│ Check ENVIRONMENT │
│ for var_cpu, var_..│
└──────┬──────────────┘
│ Found? Use them (Priority 1)
│ Not found? Continue...
v
┌──────────────────────────┐
│ Load App Defaults │
│ /defaults/<app>.vars │
└──────┬───────────────────┘
│ File exists? Parse & load (Priority 2)
│ Not found? Continue...
v
┌──────────────────────────┐
│ Load User Defaults │
│ /default.vars │
└──────┬───────────────────┘
│ File exists? Parse & load (Priority 3)
│ Not found? Continue...
v
┌──────────────────────────┐
│ Use Built-in Defaults │
│ (Hardcoded values) │
└──────┬───────────────────┘
│
v
┌──────────────────────────┐
│ All Variables Resolved │
│ Ready for container │
│ creation │
└──────────────────────────┘
```
---
## Security Model
### Threat Model
| Threat | Mitigation |
|--------|-----------|
| **Arbitrary Code Execution** | No `source` or `eval`; manual parsing only |
| **Variable Injection** | Whitelist of allowed variable names |
| **Command Substitution** | `_sanitize_value()` blocks `$()`, backticks, etc. |
| **Path Traversal** | Files locked to `/usr/local/community-scripts/` |
| **Permission Escalation** | Files created with restricted permissions |
| **Information Disclosure** | Sensitive variables not logged |
### Security Controls
#### 1. Input Validation
```bash
# Only specific variables allowed
if ! _is_whitelisted_key "$key"; then
skip_this_variable
fi
# Values sanitized
if ! val="$(_sanitize_value "$value")"; then
reject_entire_line
fi
```
#### 2. Safe File Parsing
```bash
# ❌ DANGEROUS (OLD)
source /path/to/config.conf
# Could execute: rm -rf / or any code
# ✅ SAFE (NEW)
load_vars_file "/path/to/config.conf"
# Only reads var_name=value pairs, no execution
```
#### 3. Whitelisting
```bash
# Only these variables can be configured
var_cpu, var_ram, var_disk, var_brg, ...
var_hostname, var_pw, var_ssh, ...
# NOT allowed:
var_malicious, var_hack, custom_var, ...
```
#### 4. Value Constraints
```bash
# No command injection patterns
if [[ "$value" =~ ($|`|;|&|<\() ]]; then
reject_value
fi
```
---
## Implementation Details
### Module: `build.func`
**Load Order** (in actual scripts):
1. `#!/usr/bin/env bash` - Shebang
2. `source /dev/stdin <<<$(curl ... api.func)` - API functions
3. `source /dev/stdin <<<$(curl ... build.func)` - Build functions
4. `variables()` - Initialize variables
5. `check_root()` - Security check
6. `install_script()` - Main flow
**Key Sections**:
```bash
# Section 1: Initialization & Variables
- variables()
- NSAPP, var_install, INTEGER pattern, etc.
# Section 2: Storage Management
- storage_selector()
- ensure_storage_selection_for_vars_file()
# Section 3: Base Settings
- base_settings() # Apply defaults to all var_*
- echo_default() # Display current settings
# Section 4: Variable Loading
- load_vars_file() # Safe parsing
- _is_whitelisted_key() # Validation
- _sanitize_value() # Threat mitigation
# Section 5: Defaults Management
- default_var_settings() # Load user defaults
- get_app_defaults_path() # Get app defaults path
- maybe_offer_save_app_defaults() # Save option
# Section 6: Installation Flow
- install_script() # Main entry point
- advanced_settings() # 19-step wizard
```
### Regex Patterns Used
| Pattern | Purpose | Example Match |
|---------|---------|---|
| `^[0-9]+([.][0-9]+)?$` | Integer validation | `4`, `192.168` |
| `^var_[a-z_]+$` | Variable name | `var_cpu`, `var_ssh` |
| `*'$('*` | Command substitution | `$(whoami)` |
| `*\`*` | Backtick substitution | `` `cat /etc/passwd` `` |
---
## Appendix: Migration Reference
### Old Pattern (Deprecated)
```bash
# ❌ OLD: config-file.func
source config-file.conf # Executes arbitrary code
if [ "$USE_DEFAULTS" = "yes" ]; then
apply_settings_directly
fi
```
### New Pattern (Current)
```bash
# ✅ NEW: load_vars_file()
if load_vars_file "$(get_app_defaults_path)"; then
echo "Settings loaded securely"
fi
```
### Function Mapping
| Old | New | Location |
|-----|-----|----------|
| `read_config()` | `load_vars_file()` | build.func |
| `write_config()` | `_build_current_app_vars_tmp()` | build.func |
| None | `maybe_offer_save_app_defaults()` | build.func |
| None | `get_app_defaults_path()` | build.func |
---
**End of Technical Reference**