mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-05-19 23:25:02 +00:00
cleanup: remove docs/, update README & CONTRIBUTING, fix repo config (#13770)
This commit is contained in:
CanbiZ (MickLesk)
committed by
GitHub
GitHub
parent
b2c0d7646e
commit
997e05dfb1
@@ -1,904 +0,0 @@
|
||||
# Configuration Reference
|
||||
|
||||
**Complete reference for all configuration variables and options in community-scripts for Proxmox VE.**
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Variable Naming Convention](#variable-naming-convention)
|
||||
2. [Complete Variable Reference](#complete-variable-reference)
|
||||
3. [Resource Configuration](#resource-configuration)
|
||||
4. [Network Configuration](#network-configuration)
|
||||
5. [IPv6 Configuration](#ipv6-configuration)
|
||||
6. [SSH Configuration](#ssh-configuration)
|
||||
7. [Container Features](#container-features)
|
||||
8. [Storage Configuration](#storage-configuration)
|
||||
9. [Security Settings](#security-settings)
|
||||
10. [Advanced Options](#advanced-options)
|
||||
11. [Quick Reference Table](#quick-reference-table)
|
||||
|
||||
---
|
||||
|
||||
## Variable Naming Convention
|
||||
|
||||
All configuration variables follow a consistent pattern:
|
||||
|
||||
```
|
||||
var_<setting>=<value>
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- ✅ Always starts with `var_`
|
||||
- ✅ Lowercase letters only
|
||||
- ✅ Underscores for word separation
|
||||
- ✅ No spaces around `=`
|
||||
- ✅ Values can be quoted if needed
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# ✓ Correct
|
||||
var_cpu=4
|
||||
var_hostname=myserver
|
||||
var_ssh_authorized_key=ssh-rsa AAAA...
|
||||
|
||||
# ✗ Wrong
|
||||
CPU=4 # Missing var_ prefix
|
||||
var_CPU=4 # Uppercase not allowed
|
||||
var_cpu = 4 # Spaces around =
|
||||
var-cpu=4 # Hyphens not allowed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Variable Reference
|
||||
|
||||
### var_unprivileged
|
||||
|
||||
**Type:** Boolean (0 or 1)
|
||||
**Default:** `1` (unprivileged)
|
||||
**Description:** Determines if container runs unprivileged (recommended) or privileged.
|
||||
|
||||
```bash
|
||||
var_unprivileged=1 # Unprivileged (safer, recommended)
|
||||
var_unprivileged=0 # Privileged (less secure, more features)
|
||||
```
|
||||
|
||||
**When to use privileged (0):**
|
||||
- Hardware access required
|
||||
- Certain kernel modules needed
|
||||
- Legacy applications
|
||||
- Nested virtualization with full features
|
||||
|
||||
**Security Impact:**
|
||||
- Unprivileged: Container root is mapped to unprivileged user on host
|
||||
- Privileged: Container root = host root (security risk)
|
||||
|
||||
---
|
||||
|
||||
### var_cpu
|
||||
|
||||
**Type:** Integer
|
||||
**Default:** Varies by app (usually 1-4)
|
||||
**Range:** 1 to host CPU count
|
||||
**Description:** Number of CPU cores allocated to container.
|
||||
|
||||
```bash
|
||||
var_cpu=1 # Single core (minimal)
|
||||
var_cpu=2 # Dual core (typical)
|
||||
var_cpu=4 # Quad core (recommended for apps)
|
||||
var_cpu=8 # High performance
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Start with 2 cores for most applications
|
||||
- Monitor usage with `pct exec <id> -- htop`
|
||||
- Can be changed after creation
|
||||
- Consider host CPU count (don't over-allocate)
|
||||
|
||||
---
|
||||
|
||||
### var_ram
|
||||
|
||||
**Type:** Integer (MB)
|
||||
**Default:** Varies by app (usually 512-2048)
|
||||
**Range:** 512 MB to host RAM
|
||||
**Description:** Amount of RAM in megabytes.
|
||||
|
||||
```bash
|
||||
var_ram=512 # 512 MB (minimal)
|
||||
var_ram=1024 # 1 GB (typical)
|
||||
var_ram=2048 # 2 GB (comfortable)
|
||||
var_ram=4096 # 4 GB (recommended for databases)
|
||||
var_ram=8192 # 8 GB (high memory apps)
|
||||
```
|
||||
|
||||
**Conversion Guide:**
|
||||
```
|
||||
512 MB = 0.5 GB
|
||||
1024 MB = 1 GB
|
||||
2048 MB = 2 GB
|
||||
4096 MB = 4 GB
|
||||
8192 MB = 8 GB
|
||||
16384 MB = 16 GB
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Minimum 512 MB for basic Linux
|
||||
- 1 GB for typical applications
|
||||
- 2-4 GB for web servers, databases
|
||||
- Monitor with `free -h` inside container
|
||||
|
||||
---
|
||||
|
||||
### var_disk
|
||||
|
||||
**Type:** Integer (GB)
|
||||
**Default:** Varies by app (usually 2-8)
|
||||
**Range:** 0.001 GB to storage capacity
|
||||
**Description:** Root disk size in gigabytes.
|
||||
|
||||
```bash
|
||||
var_disk=2 # 2 GB (minimal OS only)
|
||||
var_disk=4 # 4 GB (typical)
|
||||
var_disk=8 # 8 GB (comfortable)
|
||||
var_disk=20 # 20 GB (recommended for apps)
|
||||
var_disk=50 # 50 GB (large applications)
|
||||
var_disk=100 # 100 GB (databases, media)
|
||||
```
|
||||
|
||||
**Important Notes:**
|
||||
- Can be expanded after creation (not reduced)
|
||||
- Actual space depends on storage type
|
||||
- Thin provisioning supported on most storage
|
||||
- Plan for logs, data, updates
|
||||
|
||||
**Recommended Sizes by Use Case:**
|
||||
```
|
||||
Basic Linux container: 4 GB
|
||||
Web server (Nginx/Apache): 8 GB
|
||||
Application server: 10-20 GB
|
||||
Database server: 20-50 GB
|
||||
Docker host: 30-100 GB
|
||||
Media server: 100+ GB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_hostname
|
||||
|
||||
**Type:** String
|
||||
**Default:** Application name
|
||||
**Max Length:** 63 characters
|
||||
**Description:** Container hostname (FQDN format allowed).
|
||||
|
||||
```bash
|
||||
var_hostname=myserver
|
||||
var_hostname=pihole
|
||||
var_hostname=docker-01
|
||||
var_hostname=web.example.com
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Lowercase letters, numbers, hyphens
|
||||
- Cannot start or end with hyphen
|
||||
- No underscores allowed
|
||||
- No spaces
|
||||
|
||||
**Best Practices:**
|
||||
```bash
|
||||
# ✓ Good
|
||||
var_hostname=web-server
|
||||
var_hostname=db-primary
|
||||
var_hostname=app.domain.com
|
||||
|
||||
# ✗ Avoid
|
||||
var_hostname=Web_Server # Uppercase, underscore
|
||||
var_hostname=-server # Starts with hyphen
|
||||
var_hostname=my server # Contains space
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_brg
|
||||
|
||||
**Type:** String
|
||||
**Default:** `vmbr0`
|
||||
**Description:** Network bridge interface.
|
||||
|
||||
```bash
|
||||
var_brg=vmbr0 # Default Proxmox bridge
|
||||
var_brg=vmbr1 # Custom bridge
|
||||
var_brg=vmbr2 # Isolated network
|
||||
```
|
||||
|
||||
**Common Setups:**
|
||||
```
|
||||
vmbr0 → Main network (LAN)
|
||||
vmbr1 → Guest network
|
||||
vmbr2 → DMZ
|
||||
vmbr3 → Management
|
||||
vmbr4 → Storage network
|
||||
```
|
||||
|
||||
**Check available bridges:**
|
||||
```bash
|
||||
ip link show | grep vmbr
|
||||
# or
|
||||
brctl show
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_net
|
||||
|
||||
**Type:** String
|
||||
**Options:** `dhcp` or `static`
|
||||
**Default:** `dhcp`
|
||||
**Description:** IPv4 network configuration method.
|
||||
|
||||
```bash
|
||||
var_net=dhcp # Automatic IP via DHCP
|
||||
var_net=static # Manual IP configuration
|
||||
```
|
||||
|
||||
**DHCP Mode:**
|
||||
- Automatic IP assignment
|
||||
- Easy setup
|
||||
- Good for development
|
||||
- Requires DHCP server on network
|
||||
|
||||
**Static Mode:**
|
||||
- Fixed IP address
|
||||
- Requires gateway configuration
|
||||
- Better for servers
|
||||
- Configure via advanced settings or after creation
|
||||
|
||||
---
|
||||
|
||||
### var_gateway
|
||||
|
||||
**Type:** IPv4 Address
|
||||
**Default:** Auto-detected from host
|
||||
**Description:** Network gateway IP address.
|
||||
|
||||
```bash
|
||||
var_gateway=192.168.1.1
|
||||
var_gateway=10.0.0.1
|
||||
var_gateway=172.16.0.1
|
||||
```
|
||||
|
||||
**Auto-detection:**
|
||||
If not specified, system detects gateway from host:
|
||||
```bash
|
||||
ip route | grep default
|
||||
```
|
||||
|
||||
**When to specify:**
|
||||
- Multiple gateways available
|
||||
- Custom routing setup
|
||||
- Different network segment
|
||||
|
||||
---
|
||||
|
||||
### var_vlan
|
||||
|
||||
**Type:** Integer
|
||||
**Range:** 1-4094
|
||||
**Default:** None
|
||||
**Description:** VLAN tag for network isolation.
|
||||
|
||||
```bash
|
||||
var_vlan=10 # VLAN 10
|
||||
var_vlan=100 # VLAN 100
|
||||
var_vlan=200 # VLAN 200
|
||||
```
|
||||
|
||||
**Common VLAN Schemes:**
|
||||
```
|
||||
VLAN 10 → Management
|
||||
VLAN 20 → Servers
|
||||
VLAN 30 → Desktops
|
||||
VLAN 40 → Guest WiFi
|
||||
VLAN 50 → IoT devices
|
||||
VLAN 99 → DMZ
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
- Switch must support VLANs
|
||||
- Proxmox bridge configured for VLAN aware
|
||||
- Gateway on same VLAN
|
||||
|
||||
---
|
||||
|
||||
### var_mtu
|
||||
|
||||
**Type:** Integer
|
||||
**Default:** `1500`
|
||||
**Range:** 68-9000
|
||||
**Description:** Maximum Transmission Unit size.
|
||||
|
||||
```bash
|
||||
var_mtu=1500 # Standard Ethernet
|
||||
var_mtu=1492 # PPPoE
|
||||
var_mtu=9000 # Jumbo frames
|
||||
```
|
||||
|
||||
**Common Values:**
|
||||
```
|
||||
1500 → Standard Ethernet (default)
|
||||
1492 → PPPoE connections
|
||||
1400 → Some VPN setups
|
||||
9000 → Jumbo frames (10GbE networks)
|
||||
```
|
||||
|
||||
**When to change:**
|
||||
- Jumbo frames for performance on 10GbE
|
||||
- PPPoE internet connections
|
||||
- VPN tunnels with overhead
|
||||
- Specific network requirements
|
||||
|
||||
---
|
||||
|
||||
### var_mac
|
||||
|
||||
**Type:** MAC Address
|
||||
**Format:** `XX:XX:XX:XX:XX:XX`
|
||||
**Default:** Auto-generated
|
||||
**Description:** Container MAC address.
|
||||
|
||||
```bash
|
||||
var_mac=02:00:00:00:00:01
|
||||
var_mac=DE:AD:BE:EF:00:01
|
||||
```
|
||||
|
||||
**When to specify:**
|
||||
- MAC-based licensing
|
||||
- Static DHCP reservations
|
||||
- Network access control
|
||||
- Cloning configurations
|
||||
|
||||
**Best Practices:**
|
||||
- Use locally administered addresses (2nd bit set)
|
||||
- Start with `02:`, `06:`, `0A:`, `0E:`
|
||||
- Avoid vendor OUIs
|
||||
- Document custom MACs
|
||||
|
||||
---
|
||||
|
||||
### var_ipv6_method
|
||||
|
||||
**Type:** String
|
||||
**Options:** `auto`, `dhcp`, `static`, `none`, `disable`
|
||||
**Default:** `none`
|
||||
**Description:** IPv6 configuration method.
|
||||
|
||||
```bash
|
||||
var_ipv6_method=auto # SLAAC (auto-configuration)
|
||||
var_ipv6_method=dhcp # DHCPv6
|
||||
var_ipv6_method=static # Manual configuration
|
||||
var_ipv6_method=none # IPv6 enabled but not configured
|
||||
var_ipv6_method=disable # IPv6 completely disabled
|
||||
```
|
||||
|
||||
**Detailed Options:**
|
||||
|
||||
**auto (SLAAC)**
|
||||
- Stateless Address Auto-Configuration
|
||||
- Router advertisements
|
||||
- No DHCPv6 server needed
|
||||
- Recommended for most cases
|
||||
|
||||
**dhcp (DHCPv6)**
|
||||
- Stateful configuration
|
||||
- Requires DHCPv6 server
|
||||
- More control over addressing
|
||||
|
||||
**static**
|
||||
- Manual IPv6 address
|
||||
- Manual gateway
|
||||
- Full control
|
||||
|
||||
**none**
|
||||
- IPv6 stack active
|
||||
- No address configured
|
||||
- Can configure later
|
||||
|
||||
**disable**
|
||||
- IPv6 completely disabled at kernel level
|
||||
- Use when IPv6 causes issues
|
||||
- Sets `net.ipv6.conf.all.disable_ipv6=1`
|
||||
|
||||
---
|
||||
|
||||
### var_ns
|
||||
|
||||
**Type:** IP Address
|
||||
**Default:** Auto (from host)
|
||||
**Description:** DNS nameserver IP.
|
||||
|
||||
```bash
|
||||
var_ns=8.8.8.8 # Google DNS
|
||||
var_ns=1.1.1.1 # Cloudflare DNS
|
||||
var_ns=9.9.9.9 # Quad9 DNS
|
||||
var_ns=192.168.1.1 # Local DNS
|
||||
```
|
||||
|
||||
**Common DNS Servers:**
|
||||
```
|
||||
8.8.8.8, 8.8.4.4 → Google Public DNS
|
||||
1.1.1.1, 1.0.0.1 → Cloudflare DNS
|
||||
9.9.9.9, 149.112.112.112 → Quad9 DNS
|
||||
208.67.222.222 → OpenDNS
|
||||
192.168.1.1 → Local router/Pi-hole
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_ssh
|
||||
|
||||
**Type:** Boolean
|
||||
**Options:** `yes` or `no`
|
||||
**Default:** `no`
|
||||
**Description:** Enable SSH server in container.
|
||||
|
||||
```bash
|
||||
var_ssh=yes # SSH server enabled
|
||||
var_ssh=no # SSH server disabled (console only)
|
||||
```
|
||||
|
||||
**When enabled:**
|
||||
- OpenSSH server installed
|
||||
- Started on boot
|
||||
- Port 22 open
|
||||
- Root login allowed
|
||||
|
||||
**Security Considerations:**
|
||||
- Disable if not needed
|
||||
- Use SSH keys instead of passwords
|
||||
- Consider non-standard port
|
||||
- Firewall rules recommended
|
||||
|
||||
---
|
||||
|
||||
### var_ssh_authorized_key
|
||||
|
||||
**Type:** String (SSH public key)
|
||||
**Default:** None
|
||||
**Description:** SSH public key for root user.
|
||||
|
||||
```bash
|
||||
var_ssh_authorized_key=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... user@host
|
||||
var_ssh_authorized_key=ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@host
|
||||
```
|
||||
|
||||
**Supported Key Types:**
|
||||
- RSA (2048-4096 bits)
|
||||
- Ed25519 (recommended)
|
||||
- ECDSA
|
||||
- DSA (deprecated)
|
||||
|
||||
**How to get your public key:**
|
||||
```bash
|
||||
cat ~/.ssh/id_rsa.pub
|
||||
# or
|
||||
cat ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
**Multiple keys:**
|
||||
Separate with newlines (in file) or use multiple deployments.
|
||||
|
||||
---
|
||||
|
||||
### var_pw
|
||||
|
||||
**Type:** String
|
||||
**Default:** Empty (auto-login)
|
||||
**Description:** Root password.
|
||||
|
||||
```bash
|
||||
var_pw=SecurePassword123! # Set password
|
||||
var_pw= # Auto-login (empty)
|
||||
```
|
||||
|
||||
**Auto-login behavior:**
|
||||
- No password required for console
|
||||
- Automatic login on console access
|
||||
- SSH still requires key if enabled
|
||||
- Suitable for development
|
||||
|
||||
**Password best practices:**
|
||||
- Minimum 12 characters
|
||||
- Mix upper/lower/numbers/symbols
|
||||
- Use password manager
|
||||
- Rotate regularly
|
||||
|
||||
---
|
||||
|
||||
### var_nesting
|
||||
|
||||
**Type:** Boolean (0 or 1)
|
||||
**Default:** `1`
|
||||
**Description:** Allow nested containers (required for Docker).
|
||||
|
||||
```bash
|
||||
var_nesting=1 # Nested containers allowed
|
||||
var_nesting=0 # Nested containers disabled
|
||||
```
|
||||
|
||||
**Required for:**
|
||||
- Docker
|
||||
- LXC inside LXC
|
||||
- Systemd features
|
||||
- Container orchestration
|
||||
|
||||
**Security Impact:**
|
||||
- Slightly reduced isolation
|
||||
- Required for container platforms
|
||||
- Generally safe when unprivileged
|
||||
|
||||
---
|
||||
|
||||
### var_diagnostics
|
||||
|
||||
**Type:** Boolean (yes or no)
|
||||
**Default:** `yes`
|
||||
**Description:** Determines if anonymous telemetry and diagnostic data is sent to Community-Scripts API.
|
||||
|
||||
```bash
|
||||
var_diagnostics=yes # Allow telemetry (helps us improve scripts)
|
||||
var_diagnostics=no # Disable all telemetry
|
||||
```
|
||||
|
||||
**Privacy & Usage:**
|
||||
- Data is strictly anonymous (random session ID)
|
||||
- Reports success/failure of installations
|
||||
- Maps error codes (e.g., APT lock, out of RAM)
|
||||
- No user-specific data, hostnames, or secret keys are ever sent
|
||||
|
||||
---
|
||||
|
||||
### var_gpu
|
||||
|
||||
**Type:** Boolean/Toggle
|
||||
**Options:** `yes` or `no`
|
||||
**Default:** `no`
|
||||
**Description:** Enable GPU passthrough for the container.
|
||||
|
||||
```bash
|
||||
var_gpu=yes # Enable GPU passthrough (auto-detect)
|
||||
var_gpu=no # Disable GPU passthrough (default)
|
||||
```
|
||||
|
||||
**Features enabled:**
|
||||
- Auto-detects Intel (QuickSync), NVIDIA, and AMD GPUs
|
||||
- Passes through `/dev/dri` and render nodes
|
||||
- Configures appropriate container permissions
|
||||
- Crucial for media servers (Plex, Jellyfin, Immich)
|
||||
|
||||
**Prerequisites:**
|
||||
- Host drivers installed correctly
|
||||
- Hardware present and visible to Proxmox
|
||||
- IOMMU enabled (for some configurations)
|
||||
|
||||
---
|
||||
|
||||
### var_tun
|
||||
|
||||
**Type:** Boolean/Toggle
|
||||
**Options:** `yes` or `no`
|
||||
**Default:** `no`
|
||||
**Description:** Enable TUN/TAP device support.
|
||||
|
||||
```bash
|
||||
var_tun=yes # Enable TUN/TAP support
|
||||
var_tun=no # Disable TUN/TAP support (default)
|
||||
```
|
||||
|
||||
**Required for:**
|
||||
- VPN software (WireGuard, OpenVPN)
|
||||
- Network tunneling (Tailscale, ZeroTier)
|
||||
- Custom network bridges
|
||||
|
||||
---
|
||||
|
||||
### var_keyctl
|
||||
|
||||
**Type:** Boolean (0 or 1)
|
||||
**Default:** `0`
|
||||
**Description:** Enable keyctl system call.
|
||||
|
||||
```bash
|
||||
var_keyctl=1 # Keyctl enabled
|
||||
var_keyctl=0 # Keyctl disabled
|
||||
```
|
||||
|
||||
**Required for:**
|
||||
- Docker in some configurations
|
||||
- Systemd keyring features
|
||||
- Encryption key management
|
||||
- Some authentication systems
|
||||
|
||||
---
|
||||
|
||||
### var_fuse
|
||||
|
||||
**Type:** Boolean/Toggle
|
||||
**Options:** `yes` or `no`
|
||||
**Default:** `no`
|
||||
**Description:** Enable FUSE filesystem support.
|
||||
|
||||
```bash
|
||||
var_fuse=yes # FUSE enabled
|
||||
var_fuse=no # FUSE disabled
|
||||
```
|
||||
|
||||
**Required for:**
|
||||
- sshfs
|
||||
- AppImage
|
||||
- Some backup tools
|
||||
- User-space filesystems
|
||||
|
||||
---
|
||||
|
||||
### var_mknod
|
||||
|
||||
**Type:** Boolean (0 or 1)
|
||||
**Default:** `0`
|
||||
**Description:** Allow device node creation.
|
||||
|
||||
```bash
|
||||
var_mknod=1 # Device nodes allowed
|
||||
var_mknod=0 # Device nodes disabled
|
||||
```
|
||||
|
||||
**Requires:**
|
||||
- Kernel 5.3+
|
||||
- Experimental feature
|
||||
- Use with caution
|
||||
|
||||
---
|
||||
|
||||
### var_mount_fs
|
||||
|
||||
**Type:** String (comma-separated)
|
||||
**Default:** Empty
|
||||
**Description:** Allowed mountable filesystems.
|
||||
|
||||
```bash
|
||||
var_mount_fs=nfs
|
||||
var_mount_fs=nfs,cifs
|
||||
var_mount_fs=ext4,xfs,nfs
|
||||
```
|
||||
|
||||
**Common Options:**
|
||||
```
|
||||
nfs → NFS network shares
|
||||
cifs → SMB/CIFS shares
|
||||
ext4 → Ext4 filesystems
|
||||
xfs → XFS filesystems
|
||||
btrfs → Btrfs filesystems
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_protection
|
||||
|
||||
**Type:** Boolean
|
||||
**Options:** `yes` or `no`
|
||||
**Default:** `no`
|
||||
**Description:** Prevent accidental deletion.
|
||||
|
||||
```bash
|
||||
var_protection=yes # Protected from deletion
|
||||
var_protection=no # Can be deleted normally
|
||||
```
|
||||
|
||||
**When protected:**
|
||||
- Cannot delete via GUI
|
||||
- Cannot delete via `pct destroy`
|
||||
- Must disable protection first
|
||||
- Good for production containers
|
||||
|
||||
---
|
||||
|
||||
### var_tags
|
||||
|
||||
**Type:** String (comma-separated)
|
||||
**Default:** `community-script`
|
||||
**Description:** Container tags for organization.
|
||||
|
||||
```bash
|
||||
var_tags=production
|
||||
var_tags=production,webserver
|
||||
var_tags=dev,testing,temporary
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
```bash
|
||||
# Environment tags
|
||||
var_tags=production
|
||||
var_tags=development
|
||||
var_tags=staging
|
||||
|
||||
# Function tags
|
||||
var_tags=webserver,nginx
|
||||
var_tags=database,postgresql
|
||||
var_tags=cache,redis
|
||||
|
||||
# Project tags
|
||||
var_tags=project-alpha,frontend
|
||||
var_tags=customer-xyz,billing
|
||||
|
||||
# Combined
|
||||
var_tags=production,webserver,project-alpha
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_timezone
|
||||
|
||||
**Type:** String (TZ database format)
|
||||
**Default:** Host timezone
|
||||
**Description:** Container timezone.
|
||||
|
||||
```bash
|
||||
var_timezone=Europe/Berlin
|
||||
var_timezone=America/New_York
|
||||
var_timezone=Asia/Tokyo
|
||||
```
|
||||
|
||||
**Common Timezones:**
|
||||
```
|
||||
Europe/London
|
||||
Europe/Berlin
|
||||
Europe/Paris
|
||||
America/New_York
|
||||
America/Chicago
|
||||
America/Los_Angeles
|
||||
Asia/Tokyo
|
||||
Asia/Singapore
|
||||
Australia/Sydney
|
||||
UTC
|
||||
```
|
||||
|
||||
**List all timezones:**
|
||||
```bash
|
||||
timedatectl list-timezones
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_verbose
|
||||
|
||||
**Type:** Boolean
|
||||
**Options:** `yes` or `no`
|
||||
**Default:** `no`
|
||||
**Description:** Enable verbose output.
|
||||
|
||||
```bash
|
||||
var_verbose=yes # Show all commands
|
||||
var_verbose=no # Silent mode
|
||||
```
|
||||
|
||||
**When enabled:**
|
||||
- Shows all executed commands
|
||||
- Displays detailed progress
|
||||
- Useful for debugging
|
||||
- More log output
|
||||
|
||||
---
|
||||
|
||||
### var_apt_cacher
|
||||
|
||||
**Type:** Boolean
|
||||
**Options:** `yes` or `no`
|
||||
**Default:** `no`
|
||||
**Description:** Use APT caching proxy.
|
||||
|
||||
```bash
|
||||
var_apt_cacher=yes
|
||||
var_apt_cacher=no
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Faster package installs
|
||||
- Reduced bandwidth
|
||||
- Offline package cache
|
||||
- Speeds up multiple containers
|
||||
|
||||
---
|
||||
|
||||
### var_apt_cacher_ip
|
||||
|
||||
**Type:** IP Address
|
||||
**Default:** None
|
||||
**Description:** APT cacher proxy IP.
|
||||
|
||||
```bash
|
||||
var_apt_cacher=yes
|
||||
var_apt_cacher_ip=192.168.1.100
|
||||
```
|
||||
|
||||
**Setup apt-cacher-ng:**
|
||||
```bash
|
||||
apt install apt-cacher-ng
|
||||
# Runs on port 3142
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_container_storage
|
||||
|
||||
**Type:** String
|
||||
**Default:** Auto-detected
|
||||
**Description:** Storage for container.
|
||||
|
||||
```bash
|
||||
var_container_storage=local
|
||||
var_container_storage=local-zfs
|
||||
var_container_storage=pve-storage
|
||||
```
|
||||
|
||||
**List available storage:**
|
||||
```bash
|
||||
pvesm status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### var_template_storage
|
||||
|
||||
**Type:** String
|
||||
**Default:** Auto-detected
|
||||
**Description:** Storage for templates.
|
||||
|
||||
```bash
|
||||
var_template_storage=local
|
||||
var_template_storage=nfs-templates
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Table
|
||||
|
||||
| Variable | Type | Default | Example |
|
||||
|----------|------|---------|---------|
|
||||
| `var_unprivileged` | 0/1 | 1 | `var_unprivileged=1` |
|
||||
| `var_cpu` | int | varies | `var_cpu=4` |
|
||||
| `var_ram` | int (MB) | varies | `var_ram=4096` |
|
||||
| `var_disk` | int (GB) | varies | `var_disk=20` |
|
||||
| `var_hostname` | string | app name | `var_hostname=server` |
|
||||
| `var_brg` | string | vmbr0 | `var_brg=vmbr1` |
|
||||
| `var_net` | dhcp/static | dhcp | `var_net=dhcp` |
|
||||
| `var_gateway` | IP | auto | `var_gateway=192.168.1.1` |
|
||||
| `var_ipv6_method` | string | none | `var_ipv6_method=disable` |
|
||||
| `var_vlan` | int | - | `var_vlan=100` |
|
||||
| `var_mtu` | int | 1500 | `var_mtu=9000` |
|
||||
| `var_mac` | MAC | auto | `var_mac=02:00:00:00:00:01` |
|
||||
| `var_ns` | IP | auto | `var_ns=8.8.8.8` |
|
||||
| `var_ssh` | yes/no | no | `var_ssh=yes` |
|
||||
| `var_ssh_authorized_key` | string | - | `var_ssh_authorized_key=ssh-rsa...` |
|
||||
| `var_pw` | string | empty | `var_pw=password` |
|
||||
| `var_nesting` | 0/1 | 1 | `var_nesting=1` |
|
||||
| `var_keyctl` | 0/1 | 0 | `var_keyctl=1` |
|
||||
| `var_fuse` | 0/1 | 0 | `var_fuse=1` |
|
||||
| `var_mknod` | 0/1 | 0 | `var_mknod=1` |
|
||||
| `var_mount_fs` | string | - | `var_mount_fs=nfs,cifs` |
|
||||
| `var_protection` | yes/no | no | `var_protection=yes` |
|
||||
| `var_tags` | string | community-script | `var_tags=prod,web` |
|
||||
| `var_timezone` | string | host TZ | `var_timezone=Europe/Berlin` |
|
||||
| `var_verbose` | yes/no | no | `var_verbose=yes` |
|
||||
| `var_apt_cacher` | yes/no | no | `var_apt_cacher=yes` |
|
||||
| `var_apt_cacher_ip` | IP | - | `var_apt_cacher_ip=192.168.1.10` |
|
||||
| `var_container_storage` | string | auto | `var_container_storage=local-zfs` |
|
||||
| `var_template_storage` | string | auto | `var_template_storage=local` |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Defaults System Guide](DEFAULTS_GUIDE.md)
|
||||
- [Unattended Deployments](UNATTENDED_DEPLOYMENTS.md)
|
||||
- [Security Best Practices](SECURITY_GUIDE.md)
|
||||
- [Network Configuration](NETWORK_GUIDE.md)
|
||||
@@ -1,760 +0,0 @@
|
||||
# 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=dhcp # dhcp, static IP/CIDR, or IP range (see below)
|
||||
var_gateway=192.168.1.1 # Default gateway (required for static IP)
|
||||
var_mtu=1500 # MTU size
|
||||
var_vlan=100 # VLAN ID
|
||||
```
|
||||
|
||||
#### IP Range Scanning
|
||||
|
||||
You can specify an IP range instead of a static IP. The system will ping each IP in the range and automatically assign the first free IP:
|
||||
|
||||
```bash
|
||||
# Format: START_IP/CIDR-END_IP/CIDR
|
||||
var_net=192.168.1.100/24-192.168.1.200/24
|
||||
var_gateway=192.168.1.1
|
||||
```
|
||||
|
||||
This is useful for automated deployments where you want static IPs but don't want to track which IPs are already in use.
|
||||
|
||||
#### 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/ProxmoxVE/issues)
|
||||
- 💬 [Discussions](https://github.com/community-scripts/ProxmoxVE/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! 🚀**
|
||||
@@ -1,58 +0,0 @@
|
||||
# Configuration & Deployment Guides
|
||||
|
||||
This directory contains comprehensive guides for configuring and deploying Proxmox VE containers using community-scripts.
|
||||
|
||||
## 📚 Available Guides
|
||||
|
||||
### [Configuration Reference](CONFIGURATION_REFERENCE.md)
|
||||
|
||||
Complete reference for all configuration options, environment variables, and advanced settings available in the build system.
|
||||
|
||||
**Topics covered:**
|
||||
|
||||
- Container specifications (CPU, RAM, Disk)
|
||||
- Network configuration (IPv4/IPv6, VLAN, MTU)
|
||||
- Storage selection and management
|
||||
- Privilege modes and features
|
||||
- OS selection and versions
|
||||
|
||||
### [Defaults System Guide](DEFAULTS_SYSTEM_GUIDE.md)
|
||||
|
||||
Understanding and customizing default settings for container deployments.
|
||||
|
||||
**Topics covered:**
|
||||
|
||||
- Default system settings
|
||||
- Per-script overrides
|
||||
- Custom defaults configuration
|
||||
- Environment variable precedence
|
||||
|
||||
### [Unattended Deployments](UNATTENDED_DEPLOYMENTS.md)
|
||||
|
||||
Automating container deployments without user interaction.
|
||||
|
||||
**Topics covered:**
|
||||
|
||||
- Environment variable configuration
|
||||
- Batch deployments
|
||||
- CI/CD integration
|
||||
- Scripted installations
|
||||
- Pre-configured templates
|
||||
|
||||
## 🔗 Related Documentation
|
||||
|
||||
- **[CT Scripts Guide](../ct/)** - Container script structure and usage
|
||||
- **[Install Scripts Guide](../install/)** - Installation script internals
|
||||
- **[API Documentation](../api/)** - API integration and endpoints
|
||||
- **[Build Functions](../misc/build.func/)** - Build system functions reference
|
||||
- **[Tools Functions](../misc/tools.func/)** - Utility functions reference
|
||||
|
||||
## 💡 Quick Start
|
||||
|
||||
For most users, start with the **Unattended Deployments** guide to learn how to automate your container setups.
|
||||
|
||||
For advanced configuration options, refer to the **Configuration Reference**.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
If you'd like to improve these guides or add new ones, please see our [Contribution Guide](../contribution/).
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,44 +0,0 @@
|
||||
<div align="center">
|
||||
<a href="#">
|
||||
<img src="https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/images/logo.png" height="100px" />
|
||||
</a>
|
||||
</div>
|
||||
<h2 align="center">User Submitted Guides </h2>
|
||||
|
||||
<sub> In order to contribute a guide on installing with Proxmox VE Helper Scripts, you should open a pull request that adds the guide to the `USER_SUBMITTED_GUIDES.md` file. </sub>
|
||||
|
||||
[Proxmox Automation with Proxmox Helper Scripts!](https://www.youtube.com/watch?v=kcpu4z5eSEU)
|
||||
|
||||
[Installing Home Assistant OS using Proxmox 8](https://community.home-assistant.io/t/installing-home-assistant-os-using-proxmox-8/201835)
|
||||
|
||||
[How To Separate Zigbee2MQTT From Home Assistant In Proxmox](https://smarthomescene.com/guides/how-to-separate-zigbee2mqtt-from-home-assistant-in-proxmox/)
|
||||
|
||||
[How To Install Home Assistant On Proxmox: The Easy Way](https://smarthomescene.com/guides/how-to-install-home-assistant-on-proxmox-the-easy-way/)
|
||||
|
||||
[Home Assistant: Installing InfluxDB (LXC)](https://www.derekseaman.com/2023/04/home-assistant-installing-influxdb-lxc.html)
|
||||
|
||||
[Home Assistant: Proxmox Quick Start Guide](https://www.derekseaman.com/2023/10/home-assistant-proxmox-ve-8-0-quick-start-guide-2.html)
|
||||
|
||||
[Home Assistant: Installing Grafana (LXC) with Let’s Encrypt SSL](https://www.derekseaman.com/2023/04/home-assistant-installing-grafana-lxc.html)
|
||||
|
||||
[Proxmox: Plex LXC with Alder Lake Transcoding](https://www.derekseaman.com/2023/04/proxmox-plex-lxc-with-alder-lake-transcoding.html)
|
||||
|
||||
[How To Backup Home Assistant In Proxmox](https://smarthomescene.com/guides/how-to-backup-home-assistant-in-proxmox/)
|
||||
|
||||
[Running Frigate on Proxmox](https://www.homeautomationguy.io/blog/running-frigate-on-proxmox)
|
||||
|
||||
[Frigate VM on Proxmox with PCIe Coral TPU](https://www.derekseaman.com/2023/06/home-assistant-frigate-vm-on-proxmox-with-pcie-coral-tpu.html)
|
||||
|
||||
[Moving Home Assistant’s Database To MariaDB On Proxmox](https://smarthomescene.com/guides/moving-home-assistants-database-to-mariadb-on-proxmox/)
|
||||
|
||||
[How-to: Proxmox VE 7.4 to 8.0 Upgrade](https://www.derekseaman.com/2023/06/how-to-proxmox-7-4-to-8-0-upgrade.html)
|
||||
|
||||
[iGPU Transcoding In Proxmox with Jellyfin](https://www.youtube.com/watch?v=XAa_qpNmzZs)
|
||||
|
||||
[Proxmox + NetData](<https://dbt3ch.com/books/proxmox-netdata-for-better-insights-and-notifications/page/proxmox-netdata-for-better-insights-and-notifications>)
|
||||
|
||||
[Proxmox Homelab Series](<https://blog.kye.dev/proxmox-series>)
|
||||
|
||||
[The fastest installation of Docker and Portainer on Proxmox VE](https://lavr.site/en-fastest-install-docker-portainer-proxmox/)
|
||||
|
||||
[How To Setup Proxmox Backuper Server Using Helper Scripts](<https://youtu.be/6C2JOsrZZZw?si=kkrrcL_nLCDBJkOB>)
|
||||
Reference in New Issue
Block a user