community-scripts/ProxmoxVE
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
ProxmoxVE/docs/guides/CONFIGURATION_REFERENCE.md

17 KiB
Raw Blame History

Configuration Reference

Complete reference for all configuration variables and options in community-scripts for Proxmox VE.

Table of Contents

  1. Variable Naming Convention
  2. Complete Variable Reference
  3. Resource Configuration
  4. Network Configuration
  5. IPv6 Configuration
  6. SSH Configuration
  7. Container Features
  8. Storage Configuration
  9. Security Settings
  10. Advanced Options
  11. 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:

# ✓ 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.

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.

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.

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.

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).

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:

# ✓ 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.

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:

ip link show | grep vmbr
# or
brctl show

var_net

Type: String Options: dhcp or static Default: dhcp Description: IPv4 network configuration method.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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:

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.

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).

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.

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.

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.

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.

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.

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.

var_tags=production
var_tags=production,webserver
var_tags=dev,testing,temporary

Best Practices:

# 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.

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:

timedatectl list-timezones

var_verbose

Type: Boolean Options: yes or no Default: no Description: Enable verbose output.

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.

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.

var_apt_cacher=yes
var_apt_cacher_ip=192.168.1.100

Setup apt-cacher-ng:

apt install apt-cacher-ng
# Runs on port 3142

var_container_storage

Type: String Default: Auto-detected Description: Storage for container.

var_container_storage=local
var_container_storage=local-zfs
var_container_storage=pve-storage

List available storage:

pvesm status

var_template_storage

Type: String Default: Auto-detected Description: Storage for templates.

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