Restructure and relocate documentation files
Removed outdated documentation files from docs/. Added new detailed guides to ct/ and install/ directories. Updated README.md to reflect new navigation, learning paths, and documentation structure. Relocated system guides and technical references to settings/ and install/ subdirectories for improved organization.
This commit is contained in:
CanbiZ
748
docs/settings/DEFAULTS_SYSTEM_GUIDE.md
Normal file
748
docs/settings/DEFAULTS_SYSTEM_GUIDE.md
Normal 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! 🚀**
|
||||
532
docs/settings/DEV_MODE.md
Normal file
532
docs/settings/DEV_MODE.md
Normal file
@@ -0,0 +1,532 @@
|
||||
# Dev Mode - Debugging & Development Guide
|
||||
|
||||
Development modes provide powerful debugging and testing capabilities for container creation and installation processes.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Single mode
|
||||
export dev_mode="motd"
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/wallabag.sh)"
|
||||
|
||||
# Multiple modes (comma-separated)
|
||||
export dev_mode="motd,keep,trace"
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/wallabag.sh)"
|
||||
|
||||
# Combine with verbose output
|
||||
export var_verbose="yes"
|
||||
export dev_mode="pause,logs"
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/wallabag.sh)"
|
||||
```
|
||||
|
||||
## Available Modes
|
||||
|
||||
### 1. **motd** - Early SSH/MOTD Setup
|
||||
|
||||
Sets up SSH access and MOTD **before** the main application installation.
|
||||
|
||||
**Use Case**:
|
||||
|
||||
- Quick access to container for manual debugging
|
||||
- Continue installation manually if something goes wrong
|
||||
- Verify container networking before main install
|
||||
|
||||
**Behavior**:
|
||||
|
||||
```
|
||||
✔ Container created
|
||||
✔ Network configured
|
||||
[DEV] Setting up MOTD and SSH before installation
|
||||
✔ [DEV] MOTD/SSH ready - container accessible
|
||||
# Container is now accessible via SSH while installation proceeds
|
||||
```
|
||||
|
||||
**Combined with**: `keep`, `breakpoint`, `logs`
|
||||
|
||||
---
|
||||
|
||||
### 2. **keep** - Preserve Container on Failure
|
||||
|
||||
Never delete the container when installation fails. Skips cleanup prompt.
|
||||
|
||||
**Use Case**:
|
||||
|
||||
- Repeated tests of the same installation
|
||||
- Debugging failed installations
|
||||
- Manual fix attempts
|
||||
|
||||
**Behavior**:
|
||||
|
||||
```
|
||||
✖ Installation failed in container 107 (exit code: 1)
|
||||
✔ Container creation log: /tmp/create-lxc-107-abc12345.log
|
||||
✔ Installation log: /tmp/install-lxc-107-abc12345.log
|
||||
|
||||
🔧 [DEV] Keep mode active - container 107 preserved
|
||||
root@proxmox:~#
|
||||
```
|
||||
|
||||
**Container remains**: `pct enter 107` to access and debug
|
||||
|
||||
**Combined with**: `motd`, `trace`, `logs`
|
||||
|
||||
---
|
||||
|
||||
### 3. **trace** - Bash Command Tracing
|
||||
|
||||
Enables `set -x` for complete command-line tracing. Shows every command before execution.
|
||||
|
||||
**Use Case**:
|
||||
|
||||
- Deep debugging of installation logic
|
||||
- Understanding script flow
|
||||
- Identifying where errors occur exactly
|
||||
|
||||
**Behavior**:
|
||||
|
||||
```
|
||||
+(/opt/wallabag/bin/console): /opt/wallabag/bin/console cache:warmup
|
||||
+(/opt/wallabag/bin/console): env APP_ENV=prod /opt/wallabag/bin/console cache:warmup
|
||||
+(/opt/wallabag/bin/console): [[ -d /opt/wallabag/app/cache ]]
|
||||
+(/opt/wallabag/bin/console): rm -rf /opt/wallabag/app/cache/*
|
||||
```
|
||||
|
||||
**⚠️ Warning**: Exposes passwords and secrets in log output! Only use in isolated environments.
|
||||
|
||||
**Log Output**: All trace output saved to logs (see `logs` mode)
|
||||
|
||||
**Combined with**: `keep`, `pause`, `logs`
|
||||
|
||||
---
|
||||
|
||||
### 4. **pause** - Step-by-Step Execution
|
||||
|
||||
Pauses after each major step (`msg_info`). Requires manual Enter press to continue.
|
||||
|
||||
**Use Case**:
|
||||
|
||||
- Inspect container state between steps
|
||||
- Understand what each step does
|
||||
- Identify which step causes problems
|
||||
|
||||
**Behavior**:
|
||||
|
||||
```
|
||||
⏳ Setting up Container OS
|
||||
[PAUSE] Press Enter to continue...
|
||||
⏳ Updating Container OS
|
||||
[PAUSE] Press Enter to continue...
|
||||
⏳ Installing Dependencies
|
||||
[PAUSE] Press Enter to continue...
|
||||
```
|
||||
|
||||
**Between pauses**: You can open another terminal and inspect the container
|
||||
|
||||
```bash
|
||||
# In another terminal while paused
|
||||
pct enter 107
|
||||
root@container:~# df -h # Check disk usage
|
||||
root@container:~# ps aux # Check running processes
|
||||
```
|
||||
|
||||
**Combined with**: `motd`, `keep`, `logs`
|
||||
|
||||
---
|
||||
|
||||
### 5. **breakpoint** - Interactive Shell on Error
|
||||
|
||||
Opens interactive shell inside the container when an error occurs instead of cleanup prompt.
|
||||
|
||||
**Use Case**:
|
||||
|
||||
- Live debugging in the actual container
|
||||
- Manual command testing
|
||||
- Inspect container state at point of failure
|
||||
|
||||
**Behavior**:
|
||||
|
||||
```
|
||||
✖ Installation failed in container 107 (exit code: 1)
|
||||
✔ Container creation log: /tmp/create-lxc-107-abc12345.log
|
||||
✔ Installation log: /tmp/install-lxc-107-abc12345.log
|
||||
|
||||
🐛 [DEV] Breakpoint mode - opening shell in container 107
|
||||
Type 'exit' to return to host
|
||||
root@wallabag:~#
|
||||
|
||||
# Now you can debug:
|
||||
root@wallabag:~# tail -f /root/.install-abc12345.log
|
||||
root@wallabag:~# mysql -u root -p$PASSWORD wallabag
|
||||
root@wallabag:~# apt-get install -y strace
|
||||
root@wallabag:~# exit
|
||||
|
||||
Container 107 still running. Remove now? (y/N): n
|
||||
🔧 Container 107 kept for debugging
|
||||
```
|
||||
|
||||
**Combined with**: `keep`, `logs`, `trace`
|
||||
|
||||
---
|
||||
|
||||
### 6. **logs** - Persistent Logging
|
||||
|
||||
Saves all logs to `/var/log/community-scripts/` with timestamps. Logs persist even on successful installation.
|
||||
|
||||
**Use Case**:
|
||||
|
||||
- Post-mortem analysis
|
||||
- Performance analysis
|
||||
- Automated testing with log collection
|
||||
- CI/CD integration
|
||||
|
||||
**Behavior**:
|
||||
|
||||
```
|
||||
Logs location: /var/log/community-scripts/
|
||||
|
||||
create-lxc-abc12345-20251117_143022.log (host-side creation)
|
||||
install-abc12345-20251117_143022.log (container-side installation)
|
||||
```
|
||||
|
||||
**Access logs**:
|
||||
|
||||
```bash
|
||||
# View creation log
|
||||
tail -f /var/log/community-scripts/create-lxc-*.log
|
||||
|
||||
# Search for errors
|
||||
grep ERROR /var/log/community-scripts/*.log
|
||||
|
||||
# Analyze performance
|
||||
grep "msg_info\|msg_ok" /var/log/community-scripts/create-*.log
|
||||
```
|
||||
|
||||
**With trace mode**: Creates detailed trace of all commands
|
||||
|
||||
```bash
|
||||
grep "^+" /var/log/community-scripts/install-*.log
|
||||
```
|
||||
|
||||
**Combined with**: All other modes (recommended for CI/CD)
|
||||
|
||||
---
|
||||
|
||||
### 7. **dryrun** - Simulation Mode
|
||||
|
||||
Shows all commands that would be executed without actually running them.
|
||||
|
||||
**Use Case**:
|
||||
|
||||
- Test script logic without making changes
|
||||
- Verify command syntax
|
||||
- Understand what will happen
|
||||
- Pre-flight checks
|
||||
|
||||
**Behavior**:
|
||||
|
||||
```
|
||||
[DRYRUN] apt-get update
|
||||
[DRYRUN] apt-get install -y curl
|
||||
[DRYRUN] mkdir -p /opt/wallabag
|
||||
[DRYRUN] cd /opt/wallabag
|
||||
[DRYRUN] git clone https://github.com/wallabag/wallabag.git .
|
||||
```
|
||||
|
||||
**No actual changes made**: Container/system remains unchanged
|
||||
|
||||
**Combined with**: `trace` (shows dryrun trace), `logs` (shows what would run)
|
||||
|
||||
---
|
||||
|
||||
## Mode Combinations
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# First test: See what would happen
|
||||
export dev_mode="dryrun,logs"
|
||||
bash -c "$(curl ...)"
|
||||
|
||||
# Then test with tracing and pauses
|
||||
export dev_mode="pause,trace,logs"
|
||||
bash -c "$(curl ...)"
|
||||
|
||||
# Finally full debug with early SSH access
|
||||
export dev_mode="motd,keep,breakpoint,logs"
|
||||
bash -c "$(curl ...)"
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```bash
|
||||
# Automated testing with full logging
|
||||
export dev_mode="logs"
|
||||
export var_verbose="yes"
|
||||
bash -c "$(curl ...)"
|
||||
|
||||
# Capture logs for analysis
|
||||
tar czf installation-logs-$(date +%s).tar.gz /var/log/community-scripts/
|
||||
```
|
||||
|
||||
### Production-like Testing
|
||||
|
||||
```bash
|
||||
# Keep containers for manual verification
|
||||
export dev_mode="keep,logs"
|
||||
for i in {1..5}; do
|
||||
bash -c "$(curl ...)"
|
||||
done
|
||||
|
||||
# Inspect all created containers
|
||||
pct list
|
||||
pct enter 100
|
||||
```
|
||||
|
||||
### Live Debugging
|
||||
|
||||
```bash
|
||||
# SSH in early, step through installation, debug on error
|
||||
export dev_mode="motd,pause,breakpoint,keep"
|
||||
bash -c "$(curl ...)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables Reference
|
||||
|
||||
### Dev Mode Variables
|
||||
|
||||
- `dev_mode` (string): Comma-separated list of modes
|
||||
- Format: `"motd,keep,trace"`
|
||||
- Default: Empty (no dev modes)
|
||||
|
||||
### Output Control
|
||||
|
||||
- `var_verbose="yes"`: Show all command output (disables silent mode)
|
||||
- Pairs well with: `trace`, `pause`, `logs`
|
||||
|
||||
### Examples with vars
|
||||
|
||||
```bash
|
||||
# Maximum verbosity and debugging
|
||||
export var_verbose="yes"
|
||||
export dev_mode="motd,trace,pause,logs"
|
||||
bash -c "$(curl ...)"
|
||||
|
||||
# Silent debug (logs only)
|
||||
export dev_mode="keep,logs"
|
||||
bash -c "$(curl ...)"
|
||||
|
||||
# Interactive debugging
|
||||
export var_verbose="yes"
|
||||
export dev_mode="motd,breakpoint"
|
||||
bash -c "$(curl ...)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting with Dev Mode
|
||||
|
||||
### "Installation failed at step X"
|
||||
|
||||
```bash
|
||||
export dev_mode="pause,logs"
|
||||
# Step through until the failure point
|
||||
# Check container state between pauses
|
||||
pct enter 107
|
||||
```
|
||||
|
||||
### "Password/credentials not working"
|
||||
|
||||
```bash
|
||||
export dev_mode="motd,keep,trace"
|
||||
# With trace mode, see exact password handling (be careful with logs!)
|
||||
# Use motd to SSH in and test manually
|
||||
ssh root@container-ip
|
||||
```
|
||||
|
||||
### "Permission denied errors"
|
||||
|
||||
```bash
|
||||
export dev_mode="breakpoint,keep"
|
||||
# Get shell at failure point
|
||||
# Check file permissions, user context, SELinux status
|
||||
ls -la /path/to/file
|
||||
whoami
|
||||
```
|
||||
|
||||
### "Networking issues"
|
||||
|
||||
```bash
|
||||
export dev_mode="motd"
|
||||
# SSH in with motd mode before main install
|
||||
ssh root@container-ip
|
||||
ping 8.8.8.8
|
||||
nslookup example.com
|
||||
```
|
||||
|
||||
### "Need to manually complete installation"
|
||||
|
||||
```bash
|
||||
export dev_mode="motd,keep"
|
||||
# Container accessible via SSH while installation runs
|
||||
# After failure, SSH in and manually continue
|
||||
ssh root@container-ip
|
||||
# ... manual commands ...
|
||||
exit
|
||||
# Then use 'keep' mode to preserve container for inspection
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Log Files Locations
|
||||
|
||||
### Default (without `logs` mode)
|
||||
|
||||
- Host creation: `/tmp/create-lxc-<SESSION_ID>.log`
|
||||
- Container install: Copied to `/tmp/install-lxc-<CTID>-<SESSION_ID>.log` on failure
|
||||
|
||||
### With `logs` mode
|
||||
|
||||
- Host creation: `/var/log/community-scripts/create-lxc-<SESSION_ID>-<TIMESTAMP>.log`
|
||||
- Container install: `/var/log/community-scripts/install-<SESSION_ID>-<TIMESTAMP>.log`
|
||||
|
||||
### View logs
|
||||
|
||||
```bash
|
||||
# Tail in real-time
|
||||
tail -f /var/log/community-scripts/*.log
|
||||
|
||||
# Search for errors
|
||||
grep -r "exit code [1-9]" /var/log/community-scripts/
|
||||
|
||||
# Filter by session
|
||||
grep "ed563b19" /var/log/community-scripts/*.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO
|
||||
|
||||
- Use `logs` mode for CI/CD and automated testing
|
||||
- Use `motd` for early SSH access during long installations
|
||||
- Use `pause` when learning the installation flow
|
||||
- Use `trace` when debugging logic issues (watch for secrets!)
|
||||
- Combine modes for comprehensive debugging
|
||||
- Archive logs after successful tests
|
||||
|
||||
### ❌ DON'T
|
||||
|
||||
- Use `trace` in production or with untrusted networks (exposes secrets)
|
||||
- Leave `keep` mode enabled for unattended scripts (containers accumulate)
|
||||
- Use `dryrun` and expect actual changes
|
||||
- Commit `dev_mode` exports to production deployment scripts
|
||||
- Use `breakpoint` in non-interactive environments (will hang)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Debug a Failed Installation
|
||||
|
||||
```bash
|
||||
# Initial test to see the failure
|
||||
export dev_mode="keep,logs"
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/wallabag.sh)"
|
||||
|
||||
# Container 107 kept, check logs
|
||||
tail /var/log/community-scripts/install-*.log
|
||||
|
||||
# SSH in to debug
|
||||
pct enter 107
|
||||
root@wallabag:~# cat /root/.install-*.log | tail -100
|
||||
root@wallabag:~# apt-get update # Retry the failing command
|
||||
root@wallabag:~# exit
|
||||
|
||||
# Re-run with manual step-through
|
||||
export dev_mode="motd,pause,keep"
|
||||
bash -c "$(curl ...)"
|
||||
```
|
||||
|
||||
### Example 2: Verify Installation Steps
|
||||
|
||||
```bash
|
||||
export dev_mode="pause,logs"
|
||||
export var_verbose="yes"
|
||||
bash -c "$(curl ...)"
|
||||
|
||||
# Press Enter through each step
|
||||
# Monitor container in another terminal
|
||||
# pct enter 107
|
||||
# Review logs in real-time
|
||||
```
|
||||
|
||||
### Example 3: CI/CD Pipeline Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
export dev_mode="logs"
|
||||
export var_verbose="no"
|
||||
|
||||
for app in wallabag nextcloud wordpress; do
|
||||
echo "Testing $app installation..."
|
||||
APP="$app" bash -c "$(curl ...)" || {
|
||||
echo "FAILED: $app"
|
||||
tar czf logs-$app.tar.gz /var/log/community-scripts/
|
||||
exit 1
|
||||
}
|
||||
echo "SUCCESS: $app"
|
||||
done
|
||||
|
||||
echo "All installations successful"
|
||||
tar czf all-logs.tar.gz /var/log/community-scripts/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Log Analysis
|
||||
|
||||
```bash
|
||||
# Extract all errors
|
||||
grep "ERROR\|exit code [1-9]" /var/log/community-scripts/*.log
|
||||
|
||||
# Performance timeline
|
||||
grep "^$(date +%Y-%m-%d)" /var/log/community-scripts/*.log | grep "msg_"
|
||||
|
||||
# Memory usage during install
|
||||
grep "free\|available" /var/log/community-scripts/*.log
|
||||
```
|
||||
|
||||
### Integration with External Tools
|
||||
|
||||
```bash
|
||||
# Send logs to Elasticsearch
|
||||
curl -X POST "localhost:9200/installation-logs/_doc" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d @/var/log/community-scripts/install-*.log
|
||||
|
||||
# Archive for compliance
|
||||
tar czf installation-records-$(date +%Y%m).tar.gz \
|
||||
/var/log/community-scripts/
|
||||
gpg --encrypt installation-records-*.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Support & Issues
|
||||
|
||||
When reporting installation issues, always include:
|
||||
|
||||
```bash
|
||||
# Collect all relevant information
|
||||
export dev_mode="logs"
|
||||
# Run the failing installation
|
||||
# Then provide:
|
||||
tar czf debug-logs.tar.gz /var/log/community-scripts/
|
||||
```
|
||||
|
||||
Include the `debug-logs.tar.gz` when reporting issues for better diagnostics.
|
||||
298
docs/settings/EXIT_CODES.md
Normal file
298
docs/settings/EXIT_CODES.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# Exit Code Reference
|
||||
|
||||
Comprehensive documentation of all exit codes used in ProxmoxVED scripts.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Generic/Shell Errors (1-255)](#genericshell-errors)
|
||||
- [Package Manager Errors (100-101, 255)](#package-manager-errors)
|
||||
- [Node.js/npm Errors (243-254)](#nodejsnpm-errors)
|
||||
- [Python/pip Errors (210-212)](#pythonpip-errors)
|
||||
- [Database Errors (231-254)](#database-errors)
|
||||
- [Proxmox Custom Codes (200-231)](#proxmox-custom-codes)
|
||||
|
||||
---
|
||||
|
||||
## Generic/Shell Errors
|
||||
|
||||
Standard Unix/Linux exit codes used across all scripts.
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | --------------------------------------- | ----------------------------------------- | ---------------------------------------------- |
|
||||
| **1** | General error / Operation not permitted | Permission denied, general failure | Check user permissions, run as root if needed |
|
||||
| **2** | Misuse of shell builtins | Syntax error in script | Review script syntax, check bash version |
|
||||
| **126** | Command cannot execute | Permission problem, not executable | `chmod +x script.sh` or check file permissions |
|
||||
| **127** | Command not found | Missing binary, wrong PATH | Install required package, check PATH variable |
|
||||
| **128** | Invalid argument to exit | Invalid exit code passed | Use exit codes 0-255 only |
|
||||
| **130** | Terminated by Ctrl+C (SIGINT) | User interrupted script | Expected behavior, no action needed |
|
||||
| **137** | Killed (SIGKILL) | Out of memory, forced termination | Check memory usage, increase RAM allocation |
|
||||
| **139** | Segmentation fault | Memory access violation, corrupted binary | Reinstall package, check system stability |
|
||||
| **143** | Terminated (SIGTERM) | Graceful shutdown signal | Expected during container stops |
|
||||
|
||||
---
|
||||
|
||||
## Package Manager Errors
|
||||
|
||||
APT, DPKG, and package installation errors.
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | -------------------------- | --------------------------------------- | ------------------------------------------------- |
|
||||
| **100** | APT: Package manager error | Broken packages, dependency conflicts | `apt --fix-broken install`, `dpkg --configure -a` |
|
||||
| **101** | APT: Configuration error | Malformed sources.list, bad repo config | Check `/etc/apt/sources.list`, run `apt update` |
|
||||
| **255** | DPKG: Fatal internal error | Corrupted package database | `dpkg --configure -a`, restore from backup |
|
||||
|
||||
---
|
||||
|
||||
## Node.js/npm Errors
|
||||
|
||||
Node.js runtime and package manager errors.
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | ------------------------------------------ | ------------------------------ | ---------------------------------------------- |
|
||||
| **243** | Node.js: Out of memory | JavaScript heap exhausted | Increase `--max-old-space-size`, optimize code |
|
||||
| **245** | Node.js: Invalid command-line option | Wrong Node.js flags | Check Node.js version, verify CLI options |
|
||||
| **246** | Node.js: Internal JavaScript Parse Error | Syntax error in JS code | Review JavaScript syntax, check dependencies |
|
||||
| **247** | Node.js: Fatal internal error | Node.js runtime crash | Update Node.js, check for known bugs |
|
||||
| **248** | Node.js: Invalid C++ addon / N-API failure | Native module incompatibility | Rebuild native modules, update packages |
|
||||
| **249** | Node.js: Inspector error | Debug/inspect protocol failure | Disable inspector, check port conflicts |
|
||||
| **254** | npm/pnpm/yarn: Unknown fatal error | Package manager crash | Clear cache, reinstall package manager |
|
||||
|
||||
---
|
||||
|
||||
## Python/pip Errors
|
||||
|
||||
Python runtime and package installation errors.
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | ------------------------------------ | --------------------------------------- | -------------------------------------------------------- |
|
||||
| **210** | Python: Virtualenv missing or broken | venv not created, corrupted environment | `python3 -m venv venv`, recreate virtualenv |
|
||||
| **211** | Python: Dependency resolution failed | Conflicting package versions | Use `pip install --upgrade`, check requirements.txt |
|
||||
| **212** | Python: Installation aborted | EXTERNALLY-MANAGED, permission denied | Use `--break-system-packages` or venv, check permissions |
|
||||
|
||||
---
|
||||
|
||||
## Database Errors
|
||||
|
||||
### PostgreSQL (231-234)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | ----------------------- | ---------------------------------- | ----------------------------------------------------- |
|
||||
| **231** | Connection failed | Server not running, wrong socket | `systemctl start postgresql`, check connection string |
|
||||
| **232** | Authentication failed | Wrong credentials | Verify username/password, check `pg_hba.conf` |
|
||||
| **233** | Database does not exist | Database not created | `CREATE DATABASE`, restore from backup |
|
||||
| **234** | Fatal error in query | Syntax error, constraint violation | Review SQL syntax, check constraints |
|
||||
|
||||
### MySQL/MariaDB (241-244)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | ----------------------- | ---------------------------------- | ---------------------------------------------------- |
|
||||
| **241** | Connection failed | Server not running, wrong socket | `systemctl start mysql`, check connection parameters |
|
||||
| **242** | Authentication failed | Wrong credentials | Verify username/password, grant privileges |
|
||||
| **243** | Database does not exist | Database not created | `CREATE DATABASE`, restore from backup |
|
||||
| **244** | Fatal error in query | Syntax error, constraint violation | Review SQL syntax, check constraints |
|
||||
|
||||
### MongoDB (251-254)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | --------------------- | -------------------- | ------------------------------------------ |
|
||||
| **251** | Connection failed | Server not running | `systemctl start mongod`, check port 27017 |
|
||||
| **252** | Authentication failed | Wrong credentials | Verify username/password, create user |
|
||||
| **253** | Database not found | Database not created | Database auto-created on first write |
|
||||
| **254** | Fatal query error | Invalid query syntax | Review MongoDB query syntax |
|
||||
|
||||
---
|
||||
|
||||
## Proxmox Custom Codes
|
||||
|
||||
Custom exit codes specific to ProxmoxVED scripts.
|
||||
|
||||
### Container Creation Errors (200-209)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | ---------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| **200** | Failed to create lock file | Permission denied, disk full | Check `/tmp` permissions, free disk space |
|
||||
| **203** | Missing CTID variable | Script configuration error | Set CTID in script or via prompt |
|
||||
| **204** | Missing PCT_OSTYPE variable | Template selection failed | Verify template availability |
|
||||
| **205** | Invalid CTID (<100) | CTID below minimum value | Use CTID ≥ 100 (1-99 reserved for Proxmox) |
|
||||
| **206** | CTID already in use | Container/VM with same ID exists | Check `pct list` and `/etc/pve/lxc/`, use different ID |
|
||||
| **207** | Password contains unescaped special characters | Special chars like `-`, `/`, `\`, `*` at start/end | Avoid leading special chars, use alphanumeric passwords |
|
||||
| **208** | Invalid configuration | DNS format (`.home` vs `home`), MAC format (`-` vs `:`) | Remove leading dots from DNS, use `:` in MAC addresses |
|
||||
| **209** | Container creation failed | Multiple possible causes | Check logs in `/tmp/pct_create_*.log`, verify template |
|
||||
|
||||
### Cluster & Storage Errors (210, 214, 217)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | --------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
|
||||
| **210** | Cluster not quorate | Cluster nodes down, network issues | Check cluster status: `pvecm status`, fix node connectivity |
|
||||
| **211** | Timeout waiting for template lock | Concurrent download in progress | Wait for other download to complete (60s timeout) |
|
||||
| **214** | Not enough storage space | Disk full, quota exceeded | Free disk space, increase storage allocation |
|
||||
| **217** | Storage does not support rootdir | Wrong storage type selected | Use storage supporting containers (dir, zfspool, lvm-thin) |
|
||||
|
||||
### Container Verification Errors (215-216)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | -------------------------------- | -------------------------------- | --------------------------------------------------------- |
|
||||
| **215** | Container created but not listed | Ghost state, incomplete creation | Check `/etc/pve/lxc/CTID.conf`, remove manually if needed |
|
||||
| **216** | RootFS entry missing in config | Incomplete container creation | Delete container, retry creation |
|
||||
|
||||
### Template Errors (218, 220-223, 225)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | ----------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------- |
|
||||
| **218** | Template file corrupted or incomplete | Download interrupted, file <1MB, invalid archive | Delete template, run `pveam update && pveam download` |
|
||||
| **220** | Unable to resolve template path | Template storage not accessible | Check storage availability, verify permissions |
|
||||
| **221** | Template file exists but not readable | Permission denied | `chmod 644 template.tar.zst`, check storage permissions |
|
||||
| **222** | Template download failed after 3 attempts | Network issues, storage problems | Check internet connectivity, verify storage space |
|
||||
| **223** | Template not available after download | Storage sync issue, I/O delay | Wait a few seconds, verify storage is mounted |
|
||||
| **225** | No template available for OS/Version | Unsupported OS version, catalog outdated | Run `pveam update`, check `pveam available -section system` |
|
||||
|
||||
### LXC Stack Errors (231)
|
||||
|
||||
| Code | Description | Common Causes | Solutions |
|
||||
| ------- | ------------------------------ | ------------------------------------------- | -------------------------------------------- |
|
||||
| **231** | LXC stack upgrade/retry failed | Outdated `pve-container`, Debian 13.1 issue | See [Debian 13.1 Fix Guide](#debian-131-fix) |
|
||||
|
||||
---
|
||||
|
||||
## Special Case: Debian 13.1 "unsupported version" Error
|
||||
|
||||
### Problem
|
||||
|
||||
```
|
||||
TASK ERROR: unable to create CT 129 - unsupported debian version '13.1'
|
||||
```
|
||||
|
||||
### Root Cause
|
||||
|
||||
Outdated `pve-container` package doesn't recognize Debian 13 (Trixie).
|
||||
|
||||
### Solutions
|
||||
|
||||
#### Option 1: Full System Upgrade (Recommended)
|
||||
|
||||
```bash
|
||||
apt update
|
||||
apt full-upgrade -y
|
||||
reboot
|
||||
```
|
||||
|
||||
Verify fix:
|
||||
|
||||
```bash
|
||||
dpkg -l pve-container
|
||||
# PVE 8: Should show 5.3.3+
|
||||
# PVE 9: Should show 6.0.13+
|
||||
```
|
||||
|
||||
#### Option 2: Update Only pve-container
|
||||
|
||||
```bash
|
||||
apt update
|
||||
apt install --only-upgrade pve-container -y
|
||||
```
|
||||
|
||||
**Warning:** If Proxmox fails to boot after this, your system was inconsistent. Perform Option 1 instead.
|
||||
|
||||
#### Option 3: Verify Repository Configuration
|
||||
|
||||
Many users disable Enterprise repos but forget to add no-subscription repos.
|
||||
|
||||
**For PVE 9 (Trixie):**
|
||||
|
||||
```bash
|
||||
cat /etc/apt/sources.list.d/pve-no-subscription.list
|
||||
```
|
||||
|
||||
Should contain:
|
||||
|
||||
```
|
||||
deb http://download.proxmox.com/debian/pve trixie pve-no-subscription
|
||||
deb http://download.proxmox.com/debian/ceph-squid trixie no-subscription
|
||||
```
|
||||
|
||||
**For PVE 8 (Bookworm):**
|
||||
|
||||
```
|
||||
deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription
|
||||
deb http://download.proxmox.com/debian/ceph-quincy bookworm no-subscription
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
apt update
|
||||
apt full-upgrade -y
|
||||
```
|
||||
|
||||
### Reference
|
||||
|
||||
Official discussion: [GitHub #8126](https://github.com/community-scripts/ProxmoxVE/discussions/8126)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Tips
|
||||
|
||||
### Finding Error Details
|
||||
|
||||
1. **Check logs:**
|
||||
|
||||
```bash
|
||||
tail -n 50 /tmp/pct_create_*.log
|
||||
```
|
||||
|
||||
2. **Enable verbose mode:**
|
||||
|
||||
```bash
|
||||
bash -x script.sh # Shows every command executed
|
||||
```
|
||||
|
||||
3. **Check container status:**
|
||||
|
||||
```bash
|
||||
pct list
|
||||
pct status CTID
|
||||
```
|
||||
|
||||
4. **Verify storage:**
|
||||
```bash
|
||||
pvesm status
|
||||
df -h
|
||||
```
|
||||
|
||||
### Common Patterns
|
||||
|
||||
- **Exit 0 with error message:** Configuration validation failed (check DNS, MAC, password format)
|
||||
- **Exit 206 but container not visible:** Ghost container state - check `/etc/pve/lxc/` manually
|
||||
- **Exit 209 generic error:** Check `/tmp/pct_create_*.log` for specific `pct create` failure reason
|
||||
- **Exit 218 or 222:** Template issues - delete and re-download template
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Chart
|
||||
|
||||
| Exit Code Range | Category | Typical Issue |
|
||||
| --------------- | ------------------ | ------------------------------------------- |
|
||||
| 1-2, 126-143 | Shell/System | Permissions, signals, missing commands |
|
||||
| 100-101, 255 | Package Manager | APT/DPKG errors, broken packages |
|
||||
| 200-209 | Container Creation | CTID, password, configuration |
|
||||
| 210-217 | Storage/Cluster | Disk space, quorum, storage type |
|
||||
| 218-225 | Templates | Download, corruption, availability |
|
||||
| 231-254 | Databases/Runtime | PostgreSQL, MySQL, MongoDB, Node.js, Python |
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Found an undocumented exit code or have a solution to share? Please:
|
||||
|
||||
1. Open an issue on [GitHub](https://github.com/community-scripts/ProxmoxVED/issues)
|
||||
2. Include:
|
||||
- Exit code number
|
||||
- Error message
|
||||
- Steps to reproduce
|
||||
- Solution that worked for you
|
||||
|
||||
---
|
||||
|
||||
_Last updated: November 2025_
|
||||
_ProxmoxVED Version: 2.x_
|
||||
881
docs/settings/TECHNICAL_REFERENCE.md
Normal file
881
docs/settings/TECHNICAL_REFERENCE.md
Normal 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**
|
||||
Reference in New Issue
Block a user