[core]: Container Defaults System

[MickLesk]

Defaults System Guide

🎯 Overview

The community-scripts for Proxmox VE feature a powerful three-tier defaults system that replaces the old config file approach with a more flexible, secure, and user-friendly configuration management system.

What You Can Do

✅ Save global defaults for all containers
✅ Create app-specific configurations that persist across deployments
✅ Override any setting via environment variables on-the-fly
✅ Automate container deployments with zero interaction
✅ Compare configurations before updating with built-in diff view
✅ Secure variable handling - no arbitrary code execution
✅ Whitelist validation - only allowed variables can be saved

Why Use This System?

Old Config File	New Defaults System
Single config file	Three-tier priority system
Manual editing required	Interactive or automated
No validation	Whitelist + sanitization
Uses source (security risk)	Safe parser (no eval)
No diff view	Built-in comparison
One size fits all	Global + per-app configs

---

Table of Contents

1. Quick Start
2. Understanding the Priority System
3. Interactive Workflow
4. Global User Defaults
5. App-Specific Defaults
6. Environment Variable Overrides
7. File Format & Syntax
8. Unattended Deployments
9. Advanced Use Cases
10. Migration from Config File
11. Security Features
12. Troubleshooting

---

Quick Start

Your First Container (Interactive)

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

You'll see this menu:

┌─────────────── ProxmoxVE Helper Scripts ───────────────┐
│                                                         │
│  Select Installation Mode:                             │
│                                                         │
│    1) Default Settings                                 │
│    2) Advanced Settings                                │
│    3) User Defaults                                    │
│    4) App Defaults                                     │
│    5) Settings Menu                                    │
│                                                         │
│                      <Select>  <Exit>                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

What each option does:

1. Default Settings 🚀

   • Fastest option - one click deployment
   • Uses built-in defaults optimized for the app
   • Good for testing or first-time users

2. Advanced Settings ⚙️

   • Full control over all parameters
   • 19-step configuration wizard
   • Navigate back with BACK button
   • Shows summary before confirmation
   • Offers to save as App Defaults at the end

3. User Defaults 👤

   • Uses your global settings from /usr/local/community-scripts/default.vars
   • Shows what settings will be used
   • Good for consistent deployments across all apps

4. App Defaults 📱

   • Uses saved app-specific configuration
   • Only appears if defaults file exists for this app
   • Example: /usr/local/community-scripts/defaults/pihole.vars

5. Settings Menu 🛠️

   • View current configuration
   • Manage defaults location
   • Edit storage selections

Save Your First Defaults

Step-by-step walkthrough:

1. Run any script:

   bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"

2. Select "Advanced Settings"

3. Configure through the wizard:

   Step 1/19: Container ID → [Select automatically]
   Step 2/19: Hostname → pihole
   Step 3/19: Disk Size → 8 GB
   Step 4/19: CPU Cores → 2
   Step 5/19: RAM → 1024 MB
   Step 6/19: Network Type → DHCP
   ... and so on ...
   

4. Review summary:

   ┌───────── Configuration Summary ─────────┐
   │                                         │
   │  Container ID: 100                      │
   │  Hostname: pihole                       │
   │  Disk: 8 GB                             │
   │  CPU: 2 cores                           │
   │  RAM: 1024 MB                           │
   │  Network: DHCP                          │
   │  SSH: Enabled                           │
   │  ...                                    │
   │                                         │
   │     <Continue>  <Back>  <Cancel>       │
   └─────────────────────────────────────────┘
   

5. At the end, you'll see:

   ┌─────────── Save Configuration ───────────┐
   │                                           │
   │  Save these settings as App Defaults     │
   │  for PiHole?                             │
   │                                           │
   │  Future deployments can use these        │
   │  settings automatically.                 │
   │                                           │
   │           <Yes>  <No>                    │
   └───────────────────────────────────────────┘
   

6. Select "Yes" - Settings saved to /usr/local/community-scripts/defaults/pihole.vars

7. Next time: Run the script again → Select "App Defaults" → Instant deployment!

---

Interactive Workflow

Visual Guide

graph TD
    Start([Run Script]) --> SelectMode[Select Mode]

    SelectMode --> DefSet[Def. Set.]
    SelectMode --> AdvSet[Adv. Set.]
    SelectMode --> UserDef[User Def.]
    SelectMode --> AppDef[App Def.]
    SelectMode --> SetMenu[Set. Menu]

    AdvSet --> Wizard[19-Step Wizard with BACK]
    Wizard --> Summary[Show Summary]
    Summary --> Confirm{Confirm?}
    
    Confirm -- Yes --> CreateCT[Create CT]
    
    CreateCT --> SaveDefaults{Save Defaults?}
    
    SaveDefaults -- Yes --> FileExists{Check if file exists}
    
    FileExists -- No --> Save[Save]
    FileExists -- Yes --> ShowDiff[Show Diff]
    
    ShowDiff --> FileAction[Update/Keep/View]

Loading

The 19-Step Advanced Configuration Wizard

Each step allows you to configure a specific aspect:

Step 1:  Container ID (auto-assign or manual)
Step 2:  Hostname
Step 3:  Disk Size (GB)
Step 4:  CPU Cores
Step 5:  RAM (MB)
Step 6:  Bridge (vmbr0, vmbr1, etc.)
Step 7:  IPv4 Method (DHCP or Static)
  7a:    [If Static] IPv4 Address
  7b:    [If Static] Gateway
Step 8:  MTU Size
Step 9:  VLAN Tag
Step 10: IPv6 Method (auto/dhcp/static/none/disable)
  10a:   [If not none/disable] IPv6 Address
  10b:   [If not none/disable] IPv6 Gateway
Step 11: MAC Address
Step 12: Root Password (empty = auto-login)
Step 13: Container Type (Privileged/Unprivileged)
Step 14: Features (Nesting, Keyctl, Fuse, etc.)
Step 15: Mount Filesystems
Step 16: SSH Access
  16a:   [If Yes] SSH Key Management
Step 17: Container Tags
Step 18: Deletion Protection
Step 19: Verbose Mode

Navigation:

• OK: Move to next step
• BACK: Return to previous step
• CANCEL: Exit (Step 1 only) or go back (other steps)

---

Understanding the Priority System

The system follows a clear hierarchy when determining values:

Priority Hierarchy (Highest to Lowest):
┌──────────────────────────────────────────────────────┐
│ 1. Environment Variables (var_*)                    │ ← HIGHEST
│    Example: var_cpu=8 bash -c "$(curl ...)"         │
├──────────────────────────────────────────────────────┤
│ 2. App-Specific Defaults (.vars files)              │
│    Location: /usr/local/community-scripts/          │
│              defaults/<app>.vars                     │
├──────────────────────────────────────────────────────┤
│ 3. User Global Defaults (default.vars)              │
│    Location: /usr/local/community-scripts/          │
│              default.vars                            │
├──────────────────────────────────────────────────────┤
│ 4. Built-in Script Defaults                         │ ← LOWEST
│    Defined in the app script itself                 │
└──────────────────────────────────────────────────────┘

How It Works - Example

Scenario: Deploying a PiHole container

Built-in defaults (in pihole.sh script):

var_cpu=2
var_ram=1024
var_disk=8

User global defaults (/usr/local/community-scripts/default.vars):

var_cpu=4        # Override built-in
var_ram=2048     # Override built-in
# var_disk not specified - uses built-in (8)

App defaults (/usr/local/community-scripts/defaults/pihole.vars):

var_cpu=2        # Override user default
# var_ram not specified - uses user default (2048)
# var_disk not specified - uses built-in (8)

Environment variable:

var_cpu=8 bash -c "$(curl .../pihole.sh)"

Result:

var_cpu=8       # From ENV (highest priority)
var_ram=2048    # From user defaults
var_disk=8      # From built-in defaults

Visual Example

Setting: var_cpu

Step 1: Check Environment Variable
   var_cpu=8 bash -c "..."  → Found! Use 8 ✓

   ⚠️ If not found, continue to Step 2

Step 2: Check App Defaults
   /usr/local/community-scripts/defaults/pihole.vars
   var_cpu=2  → Found! Use 2 ✓

   ⚠️ If not found, continue to Step 3

Step 3: Check User Defaults
   /usr/local/community-scripts/default.vars
   var_cpu=4  → Found! Use 4 ✓

   ⚠️ If not found, continue to Step 4

Step 4: Use Built-in Default
   var_cpu=2  → Use script default ✓

Practical Examples

Example 1: Empty system

# No defaults files exist
bash -c "$(curl .../debian.sh)"

Result:
- All values from built-in defaults
- Quick deployment with sensible values

Example 2: Global defaults only

# /usr/local/community-scripts/default.vars exists
# Contains: var_cpu=4, var_ram=4096

bash -c "$(curl .../debian.sh)"

Result:
- CPU: 4 (from user defaults)
- RAM: 4096 (from user defaults)
- Disk: 4 (from built-in defaults)
- All containers use these values

Example 3: App defaults override

# User defaults: var_cpu=4
# App defaults (pihole): var_cpu=2

bash -c "$(curl .../pihole.sh)"

Result:
- CPU: 2 (app defaults override user defaults)
- Specific configuration for PiHole

Example 4: One-off override

# User defaults: var_cpu=4
# App defaults: var_cpu=2
# ENV override: var_cpu=8

var_cpu=8 bash -c "$(curl .../pihole.sh)"

Result:
- CPU: 8 (ENV overrides everything)
- Defaults files unchanged
- Perfect for testing or exceptions

---

Global User Defaults

Global defaults apply to all containers unless overridden by app-specific settings.

Location

/usr/local/community-scripts/default.vars

Creating Global Defaults

Method 1: Automatic Creation
The file is automatically created on first script run with sensible defaults:

# First run creates default.vars automatically
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

Method 2: Manual Creation

mkdir -p /usr/local/community-scripts
cat > /usr/local/community-scripts/default.vars <<'EOF'
# Global defaults for all containers
var_unprivileged=1
var_cpu=2
var_ram=2048
var_disk=10
var_brg=vmbr0
var_ipv6_method=none
var_ssh=yes
var_tags=community-script,production
var_verbose=no
EOF

Example: Set Your Preferred Defaults

# Edit global defaults
nano /usr/local/community-scripts/default.vars

Common Settings:

# Resources (adjust to your needs)
var_cpu=4
var_ram=4096
var_disk=20

# Network
var_brg=vmbr0
var_gateway=192.168.1.1
var_ipv6_method=none

# SSH Access
var_ssh=yes
var_ssh_authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...

# Features
var_unprivileged=1
var_nesting=1
var_tags=community-script,homelab

Now every container will use these values by default!

---

App-Specific Defaults

App defaults override global defaults for specific applications.

Location

/usr/local/community-scripts/defaults/<app>.vars

Examples:

• /usr/local/community-scripts/defaults/pihole.vars
• /usr/local/community-scripts/defaults/docker.vars
• /usr/local/community-scripts/defaults/homeassistant.vars

Creating App Defaults

Method 1: Interactive (Recommended)

1. Run your desired app script:

   bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"

2. Select Advanced Settings

3. Configure all parameters:

   • CPU: 2 cores
   • RAM: 1024 MB
   • Disk: 8 GB
   • Network: Static IP
   • etc.

4. When prompted: "Save as App Defaults for PiHole?"

   • Select Yes

5. Done! File saved to /usr/local/community-scripts/defaults/pihole.vars

Method 2: Manual Creation

mkdir -p /usr/local/community-scripts/defaults

cat > /usr/local/community-scripts/defaults/pihole.vars <<'EOF'
# PiHole-specific configuration
var_unprivileged=1
var_cpu=2
var_ram=1024
var_disk=8
var_brg=vmbr0
var_net=dhcp
var_ipv6_method=none
var_hostname=pihole
var_tags=dns,pihole,network
EOF

Updating Existing App Defaults

1. Run the script again with Advanced Settings
2. Change your desired parameters
3. When prompted to save, you'll see a diff view:

Differences between current and saved defaults:

- var_cpu=2
+ var_cpu=4

- var_ram=1024
+ var_ram=2048

4. Choose:
   • Update - Replace with new values
   • Keep - Keep existing file
   • View Diff - Show differences again
   • Cancel - Don't save

---

Environment Variable Overrides

Override any setting on-the-fly without changing saved defaults.

Basic Syntax

var_<setting>=<value> bash -c "$(curl -fsSL <script-url>)"

Single Override Examples

Override CPU:

var_cpu=8 bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

Override Hostname:

var_hostname=myserver bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

Override Network:

var_net=dhcp bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/docker.sh)"

Multiple Overrides

var_cpu=4 var_ram=4096 var_disk=30 var_hostname=production-server \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

Complete Override Example

var_unprivileged=1 \
var_cpu=6 \
var_ram=8192 \
var_disk=50 \
var_hostname=homeassistant-prod \
var_brg=vmbr1 \
var_net=dhcp \
var_ipv6_method=disable \
var_ssh=yes \
var_nesting=1 \
var_tags=production,ha,automation \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/homeassistant.sh)"

---

Unattended Deployments

Fully automated container creation with zero interaction.

Method 1: Using App Defaults

Step 1: Create App Defaults (once)

# Run interactively first time
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"
# Select Advanced Settings → Configure → Save as App Defaults

Step 2: Automated Deployment

# Future deployments are instant
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"
# Select "App Defaults" → Container created automatically

Method 2: Environment Variables Only

#!/bin/bash
# deploy-pihole.sh - Fully unattended PiHole deployment

var_unprivileged=1 \
var_cpu=2 \
var_ram=1024 \
var_disk=8 \
var_hostname=pihole \
var_brg=vmbr0 \
var_net=dhcp \
var_ipv6_method=none \
var_ssh=yes \
var_tags=dns,pihole \
var_verbose=no \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"

Make executable and run:

chmod +x deploy-pihole.sh
./deploy-pihole.sh

Method 3: Ansible Automation

---
# playbook.yml
- name: Deploy ProxmoxVE Containers
  hosts: proxmox
  tasks:
    - name: Deploy PiHole
      shell: |
        var_cpu=2 \
        var_ram=1024 \
        var_hostname=pihole \
        var_net=dhcp \
        bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"
      args:
        executable: /bin/bash

Method 4: Batch Deployment Script

#!/bin/bash
# batch-deploy.sh - Deploy multiple containers

apps=(
  "pihole:2:1024:8"
  "homeassistant:4:4096:20"
  "docker:6:8192:50"
)

for app_config in "${apps[@]}"; do
  IFS=':' read -r app cpu ram disk <<< "$app_config"

  echo "Deploying $app..."
  var_cpu=$cpu \
  var_ram=$ram \
  var_disk=$disk \
  var_hostname=$app \
  var_net=dhcp \
    bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/${app}.sh)"

  echo "✓ $app deployed"
  sleep 5
done

---

Advanced Use Cases

1. Development vs Production Environments

Development defaults:

# /usr/local/community-scripts/defaults/docker-dev.vars
var_cpu=2
var_ram=2048
var_disk=20
var_hostname=docker-dev
var_tags=development,testing

Production defaults:

# /usr/local/community-scripts/defaults/docker-prod.vars
var_cpu=8
var_ram=16384
var_disk=100
var_hostname=docker-prod
var_tags=production,critical
var_protection=yes

Deploy with:

# Development
bash -c "$(curl -fsSL .../docker.sh)"  # Select "App Defaults" (docker-dev)

# Production override
var_hostname=docker-prod var_cpu=8 var_ram=16384 \
  bash -c "$(curl -fsSL .../docker.sh)"

2. Multi-Node Deployment with Different Networks

# Node 1 (Main Network - vmbr0)
var_brg=vmbr0 var_gateway=192.168.1.1 var_vlan=10 \
  bash -c "$(curl -fsSL .../pihole.sh)"

# Node 2 (Guest Network - vmbr1)
var_brg=vmbr1 var_gateway=192.168.100.1 var_vlan=100 \
  bash -c "$(curl -fsSL .../pihole.sh)"

# Node 3 (IoT Network - vmbr2)
var_brg=vmbr2 var_gateway=192.168.200.1 var_vlan=200 \
  bash -c "$(curl -fsSL .../pihole.sh)"

3. SSH Key Deployment

Single key:

var_ssh=yes \
var_ssh_authorized_key="ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... user@host" \
  bash -c "$(curl -fsSL .../debian.sh)"

Multiple keys in global defaults:

# /usr/local/community-scripts/default.vars
var_ssh=yes
var_ssh_authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... admin@workstation

4. Storage Selection

Specify storage:

var_container_storage=local-zfs \
var_template_storage=local \
  bash -c "$(curl -fsSL .../debian.sh)"

5. IPv6 Configuration Options

# Disable IPv6 completely
var_ipv6_method=disable bash -c "$(curl -fsSL .../debian.sh)"

# Use DHCP for IPv6
var_ipv6_method=dhcp bash -c "$(curl -fsSL .../debian.sh)"

# Static IPv6 (requires advanced settings)
var_ipv6_method=static bash -c "$(curl -fsSL .../debian.sh)"

# Auto configuration
var_ipv6_method=auto bash -c "$(curl -fsSL .../debian.sh)"

# No IPv6 (default)
var_ipv6_method=none bash -c "$(curl -fsSL .../debian.sh)"

6. Container Features

# Docker host with all features
var_unprivileged=1 \
var_nesting=1 \
var_keyctl=1 \
var_fuse=1 \
  bash -c "$(curl -fsSL .../docker.sh)"

# Secure container (minimal features)
var_unprivileged=1 \
var_nesting=0 \
var_keyctl=0 \
var_protection=yes \
  bash -c "$(curl -fsSL .../debian.sh)"

---

File Format & Syntax

Basic Rules

# This is a comment (lines starting with #)
var_setting=value

# ✓ Correct - no spaces around =
var_cpu=4

# ✗ Wrong - spaces around =
var_cpu = 4

# ✓ Correct - quotes for strings with spaces
var_tags=production,webserver

# ✓ Correct - empty value
var_pw=

# Variable names must start with var_
# Only whitelisted variables are allowed

Example: Complete Default.vars File

# /usr/local/community-scripts/default.vars
# Global defaults for all containers
# Edit this file to customize your preferences

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Container Type
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
var_unprivileged=1        # 1=unprivileged (recommended), 0=privileged

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Resources
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
var_cpu=2                 # CPU cores
var_disk=10               # Disk size in GB
var_ram=2048              # RAM in MB

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Network Configuration
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
var_brg=vmbr0             # Network bridge
var_net=dhcp              # dhcp or static
var_ipv6_method=none      # auto/dhcp/static/none/disable
# var_gateway=            # Gateway IP (leave empty for auto-detect)
# var_vlan=               # VLAN tag (leave empty for none)
# var_mtu=                # MTU (leave empty for 1500)
# var_mac=                # MAC address (leave empty for auto)
# var_ns=                 # Nameserver IP (leave empty for auto)

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# SSH Access
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
var_ssh=no                # Enable SSH? (yes/no)
# var_ssh_authorized_key= # SSH public key (paste your key here)

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# APT Cacher (Optional - speeds up package installs)
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# var_apt_cacher=yes
# var_apt_cacher_ip=192.168.1.10

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Container Features
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
var_fuse=no               # FUSE support (0 or 1)
var_tun=no                # TUN/TAP support (0 or 1)
var_nesting=1             # Container nesting (required for Docker)
var_keyctl=0              # Keyctl support (0 or 1)
var_mknod=0               # Allow device node creation (0 or 1)
# var_mount_fs=           # Allowed filesystems (e.g., nfs,ext4)

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# System Configuration
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
var_protection=no         # Deletion protection (yes/no)
# var_timezone=           # Timezone (e.g., Europe/Berlin)
var_tags=community-script # Container tags (comma-separated)
var_verbose=no            # Verbose output (yes/no)

#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Security
#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# var_pw=                 # Root password (leave empty for auto-login)

Example: App-Specific Defaults

# /usr/local/community-scripts/defaults/pihole.vars
# PiHole-specific configuration

var_unprivileged=1
var_cpu=2
var_ram=1024
var_disk=8
var_brg=vmbr0
var_net=dhcp
var_ipv6_method=none
var_hostname=pihole
var_tags=dns,pihole,network
var_ssh=yes
var_ssh_authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... admin@workstation

Syntax Validation

The system automatically validates:

• ✅ Variable names (must be whitelisted)
• ✅ No command injection ($(...), backticks, semicolons)
• ✅ Proper key=value format
• ✅ No dangerous patterns

Rejected patterns:

# ✗ Command injection attempts
var_cpu=$(rm -rf /)
var_hostname=`whoami`
var_tags=test; rm file

# ✗ Invalid variable names
cpu=4                    # Missing var_ prefix
var_fake=value           # Not in whitelist

# ✗ Syntax errors
var_cpu = 4              # Spaces around =
var_ram:2048             # Wrong separator

---

Available Variables

Note: Only whitelisted variables can be saved to defaults files. All other variables are ignored for security.

🔧 Resources

Variable	Type	Default	Description	Example
var_cpu	Integer	1	Number of CPU cores	var_cpu=4
var_ram	Integer	1024	RAM in MB	var_ram=4096
var_disk	Integer	4	Disk size in GB	var_disk=30
var_unprivileged	Boolean	1	Unprivileged container (1) or privileged (0)	var_unprivileged=1

🌐 Network Configuration

Variable	Type	Default	Description	Example
var_net	String	dhcp	Network mode: dhcp or static	var_net=dhcp
var_brg	String	vmbr0	Network bridge name	var_brg=vmbr1
var_gateway	IP Address	Auto	Gateway IP address	var_gateway=192.168.1.1
var_ipv6_method	String	none	IPv6 mode: auto, dhcp, static, none, disable	var_ipv6_method=disable
var_vlan	Integer	-	VLAN tag	var_vlan=100
var_mtu	Integer	1500	MTU size	var_mtu=9000
var_mac	MAC Address	Auto	MAC address	var_mac=02:00:00:00:00:01
var_ns	IP Address	Auto	DNS nameserver	var_ns=8.8.8.8

🏷️ Identity & Metadata

Variable	Type	Default	Description	Example
var_hostname	String	App name	Container hostname	var_hostname=myserver
var_pw	String	Random	Root password (empty = auto-login)	var_pw=SecurePass123!
var_tags	String	community-script	Container tags (comma-separated)	var_tags=production,web

🔐 SSH Access

Variable	Type	Default	Description	Example
var_ssh	Boolean	no	Enable SSH server	var_ssh=yes
var_ssh_authorized_key	String	-	SSH public key for root	var_ssh_authorized_key=ssh-rsa AAAA...

⚙️ Container Features

Variable	Type	Default	Description	Example
var_nesting	Boolean	1	Allow nested containers (required for Docker)	var_nesting=1
var_fuse	Boolean	0	Enable FUSE filesystem support	var_fuse=1
var_keyctl	Boolean	0	Enable keyctl (needed for some Docker setups)	var_keyctl=1
var_mknod	Boolean	0	Allow device node creation	var_mknod=1
var_mount_fs	String	-	Allowed mountable filesystems	var_mount_fs=nfs,cifs
var_protection	Boolean	no	Deletion protection	var_protection=yes

🖥️ System Configuration

Variable	Type	Default	Description	Example
var_timezone	String	System	Container timezone	var_timezone=Europe/Berlin
var_verbose	Boolean	no	Verbose output for debugging	var_verbose=yes
var_apt_cacher	Boolean	no	Use APT caching proxy	var_apt_cacher=yes
var_apt_cacher_ip	IP Address	-	APT cacher IP address	var_apt_cacher_ip=192.168.1.10

💾 Storage Selection

Variable	Type	Default	Description	Example
var_container_storage	String	Auto	Storage for container	var_container_storage=local-zfs
var_template_storage	String	Auto	Storage for templates	var_template_storage=local

⚠️ Input Validation

Caution: While the system validates syntax and prevents injection, incorrect values may still cause issues.

Common mistakes:

# ✗ Wrong type
var_cpu=lots              # Should be integer
var_ram=4G                # Should be MB (e.g., 4096)

# ✗ Invalid options
var_ipv6_method=disabled  # Should be 'disable'
var_ssh=1                 # Should be 'yes' or 'no'

# ✓ Correct
var_cpu=4
var_ram=4096
var_ipv6_method=disable
var_ssh=yes

---

Migration from Config File

For users coming from the old config file system

What Changed?

Old System	New System
/opt/community-scripts/.settings	/usr/local/community-scripts/default.vars + app-specific files
CT_ID=100	Automatically assigned (or var_ctid ENV override)
var_os=debian + var_version=12	Built into app scripts
CT_TYPE=1	var_unprivileged=1
PW=password	var_pw=password
HN=hostname	var_hostname=hostname
DISK_SIZE=25	var_disk=25
CORE_COUNT=4	var_cpu=4
RAM_SIZE=4096	var_ram=4096
BRG=vmbr0	var_brg=vmbr0
NET=192.168.0.1/24	var_net=static (IP configured in advanced settings)
GATE=192.168.0.254	var_gateway=192.168.0.254
APT_CACHER_IP=192.168.0.2	var_apt_cacher=yes + var_apt_cacher_ip=192.168.0.2
DISABLEIP6=yes	var_ipv6_method=disable
MTU=1500	var_mtu=1500
SD=example.com	Configured in advanced settings
NS=192.168.0.100	var_ns=192.168.0.100
MAC=00:00:00:00:00:00	var_mac=00:00:00:00:00:00
VLAN=100	var_vlan=100
TAGS=dev;testing	var_tags=dev,testing (comma-separated now)
SSH=yes	var_ssh=yes
SSH_AUTHORIZED_KEY=key	var_ssh_authorized_key=key
VERB=yes	var_verbose=yes

Converting Your Old Config

Old config file:

# /opt/community-scripts/.settings
DISK_SIZE="25"
CORE_COUNT="4"
RAM_SIZE="4500"
HN="TEST"
BRG="vmbr1"
NET="10.10.10.171/24"
GATE="10.10.10.254"
VLAN="100"
SSH="yes"
TAGS="dev;testing"
SSH_AUTHORIZED_KEY="ssh-rsa AAAA..."

New default.vars:

# /usr/local/community-scripts/default.vars
var_disk=25
var_cpu=4
var_ram=4500
var_hostname=TEST
var_brg=vmbr1
var_net=static
var_gateway=10.10.10.254
var_vlan=100
var_ssh=yes
var_tags=dev,testing
var_ssh_authorized_key=ssh-rsa AAAA...

Key Improvements

✅ No more manual file path entry - Standard location
✅ Per-app configurations - Different settings per application
✅ Environment variable overrides - One-off changes without editing files
✅ Diff view - See what changes before updating
✅ Validation - Prevents invalid values
✅ No code execution - Secure parsing instead of source

---

Security Features

Why the New System is More Secure

1. No Source/Eval

Old system (dangerous):

source /opt/community-scripts/.settings  # Executes any code in file!

New system (safe):

load_vars_file() {
  # Manual parsing - no code execution
  while IFS= read -r line; do
    [[ "$line" =~ ^var_([a-z_]+)=(.*)$ ]] && echo "${BASH_REMATCH[1]}=${BASH_REMATCH[2]}"
  done < "$file"
}

2. Variable Whitelisting

Only explicitly allowed variables can be saved:

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
)

Attempt to save unlisted variable:

var_malicious_code="$(rm -rf /)"  # ✗ Rejected - not in whitelist

3. Value Sanitization

All values are checked for dangerous patterns:

_sanitize_value() {
  case "$1" in
    *'$('* | *'`'* | *';'* | *'&'* | *'<('*)
      return 1  # Reject command injection attempts
      ;;
  esac
  echo "$1"
}

Examples:

var_hostname=test           # ✓ Safe
var_hostname=$(whoami)      # ✗ Rejected
var_hostname=`id`           # ✗ Rejected
var_hostname=test;rm -rf /  # ✗ Rejected

4. File Permissions

Defaults files are readable only by root:

# Automatic permission setting
-rw-r--r-- root root /usr/local/community-scripts/default.vars
-rw-r--r-- root root /usr/local/community-scripts/defaults/*.vars

5. Safe Defaults

Secure by default:

• Unprivileged containers (var_unprivileged=1)
• No SSH unless explicitly enabled
• No root password (auto-login in console only)
• Minimal features enabled

---

Troubleshooting

Issue: Defaults Not Loading

Check if file exists:

ls -la /usr/local/community-scripts/default.vars
ls -la /usr/local/community-scripts/defaults/

Verify syntax:

cat /usr/local/community-scripts/default.vars
# Look for syntax errors (spaces around =, special characters)

Fix permissions:

sudo chown root:root /usr/local/community-scripts/default.vars
sudo chmod 644 /usr/local/community-scripts/default.vars

Issue: Variable Not Applied

Check variable name:

• Must start with var_
• Must be in whitelist (see Available Variables)

Check syntax:

# ✓ Correct
var_cpu=4

# ✗ Wrong (spaces around =)
var_cpu = 4

# ✗ Wrong (missing var_ prefix)
cpu=4

Issue: App Defaults Not Found

List available app defaults:

ls -la /usr/local/community-scripts/defaults/

Create directory if missing:

sudo mkdir -p /usr/local/community-scripts/defaults/

Issue: Environment Variable Not Overriding

Check priority:
Environment variables have highest priority and should always override.

Verify syntax:

# ✓ Correct
var_cpu=8 bash -c "$(curl -fsSL .../debian.sh)"

# ✗ Wrong (var exported separately)
export var_cpu=8
bash -c "$(curl -fsSL .../debian.sh)"

Debug Mode

Enable verbose output:

var_verbose=yes bash -c "$(curl -fsSL .../debian.sh)"

This shows:

• All loaded defaults
• Variable precedence
• Configuration decisions
• Command execution details

---

Best Practices

1. Start with Global Defaults

   • Set sensible defaults for your infrastructure
   • Adjust resources to your typical needs

2. Use App Defaults for Repeat Deployments

   • Save time on applications you deploy often
   • Keep configurations consistent

3. Use Environment Variables for Overrides

   • One-off changes without modifying files
   • Scripting and automation

4. Version Control Your Defaults

   # Backup defaults
   tar -czf defaults-backup.tar.gz /usr/local/community-scripts/

5. Document Custom Configurations

   • Add comments to .vars files
   • Keep notes on why specific settings were chosen

6. Test Before Production

   • Create test containers with your defaults
   • Verify all settings work as expected

7. Use Protection for Critical Containers

   var_protection=yes  # Prevents accidental deletion

---

Examples Repository

Minimal Container

var_cpu=1 var_ram=512 var_disk=4 \
  bash -c "$(curl -fsSL .../debian.sh)"

High-Performance Container

var_cpu=16 var_ram=32768 var_disk=200 var_unprivileged=0 \
  bash -c "$(curl -fsSL .../debian.sh)"

Secure Web Server

var_ssh=yes \
var_ssh_authorized_key="$(cat ~/.ssh/id_rsa.pub)" \
var_protection=yes \
var_tags=production,webserver \
  bash -c "$(curl -fsSL .../debian.sh)"

Development Environment

var_hostname=dev-environment \
var_cpu=4 \
var_ram=8192 \
var_nesting=1 \
var_fuse=1 \
var_tags=development,testing \
  bash -c "$(curl -fsSL .../docker.sh)"

[wommy]

var_dns_domain var_dns_server? im guessing var_gateway and var_ns?

var_gpu_passthrough

[michelroegl-brunner]

What exactly is your question? I cant follow you here.

[MickLesk]

What?