# 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_= ``` **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 -- 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_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 (0 or 1) **Default:** `0` **Description:** Enable FUSE filesystem support. ```bash var_fuse=1 # FUSE enabled var_fuse=0 # 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)