Configuration reference
Every var_* setting a container script accepts, its values, its default, and where it may be set.
A container script is configured through var_* shell variables and one
selector, mode. This page lists all of them as the engine reads them in
ui/defaults.func,
ui/menu.func and
pve/backend.func.
VM scripts do not read var_* or mode; they take VM_* variables. See
Virtual machines.
Where a value can come from
| Source | How | Read when |
|---|---|---|
| Command line | var_cpu=2 bash -c "$(curl ...)", or export before the command | Always |
default.vars | One var_name=value per line, for every script on the host | User Defaults (mode=mydefaults) |
defaults/<app>.vars | Same format, for one app | App Defaults (mode=appdefaults) |
| The script | var_cpu="${var_cpu:-2}" at the top of ct/<app>.sh | Always, when nothing set it earlier |
Paths, precedence and the file format are described in Defaults and install modes.
The engine sorts var_* names into four groups, and the group decides which
files may hold them:
| Group | In default.vars | In defaults/<app>.vars | Command line |
|---|---|---|---|
VAR_WHITELIST (engine settings) | yes | yes | yes |
VAR_RESERVED | no, skipped with a warning | no, skipped with a warning | yes |
VAR_PER_RUN | no, skipped silently | yes, when written by hand | yes |
Any other var_ name in lower case, digits and _ (an app's own setting) | no, skipped silently | yes | yes |
mode
install_script takes the menu choice from mode. Without it the menu opens.
The values are matched exactly as written here; Default or Advanced in
mixed case is an Invalid option and exits 1.
mode= | Same as menu entry | What it does |
|---|---|---|
default, DEFAULT, 1 | Default Install | Script defaults plus var_* from the command line. No file is loaded. |
advanced, ADVANCED, 2 | Advanced Install | Opens the wizard. |
mydefaults, MYDEFAULTS, userdefaults, USERDEFAULTS, 3 | User Defaults | Loads default.vars. |
appdefaults, APPDEFAULTS | App Defaults for the app | Loads defaults/<app>.vars. Exits 1 with No App Defaults available when the file is missing. |
settings, SETTINGS | Settings | Opens the settings menu, then the main menu. |
generated, GENERATED | none | Like default, but skips the storage step that reads default.vars. This is what the generator emits. |
The numbers 4 and 5 depend on the host: with an app defaults file present
4 is App Defaults and 5 is Settings, without one 4 is Settings. Use the
names.
Engine settings (VAR_WHITELIST)
Accepted on the command line, in default.vars and in an app file. The
"checked in files" column is what load_vars_file enforces; a value that
fails is skipped with a warning and the run continues. Values from the command
line are not checked there. Before pct create, validate_ct_settings checks
the final values from every source and exits 208 with a list of what is wrong.
Container
| Variable | Meaning | Checked in files | Default |
|---|---|---|---|
var_unprivileged | 1 unprivileged, 0 privileged | 0 or 1 | 1 |
var_os | Template family, e.g. debian, ubuntu, alpine. Upper case and spaces are removed with a warning. | not checked | set by the script; debian if empty |
var_version | OS release, e.g. 13, 24.04, 3.24. A release the host cannot provide is replaced by the nearest one, after a dialog when a terminal is attached. | not checked | set by the script; 12 if empty |
var_hostname | Hostname or FQDN. Lower-cased, spaces removed. An invalid name falls back to the app name with a warning. | labels of a-z, 0-9, -, max 63 each, 253 total | app name in lower case without spaces |
var_tags | Tags separated by ;. community-script is always added. | letters, digits, -, _, ; | set by the script |
var_protection | Proxmox protection flag against removal | yes or no | no |
var_timezone | Container timezone. host and every Etc/* zone mean the host's zone. | empty, host, UTC, or a zone or alias known to the host's zoneinfo | host timezone |
var_cmode | Console mode passed to pct as -cmode | shell, console or tty | empty (Proxmox default, tty) |
var_verbose | Show full command output during the install | yes or no | no |
Resources
| Variable | Meaning | Checked in files | Default |
|---|---|---|---|
var_cpu | CPU cores | whole number 1-128 | set by the script; 1 if empty |
var_ram | Memory in MiB | whole number, at least 256 | set by the script; 1024 if empty |
var_disk | Root disk in GB | whole number, at least 1 | set by the script; 4 if empty |
From a file these three can only raise what the script asks for. On the command
line they replace the script's value, also downwards: ct/jellyfin.sh declares
var_ram="${var_ram:-2048}", so var_ram=1024 gives the container 1024 MiB.
For every source validate_ct_settings refuses less than 128 MiB of RAM.
Network
| Variable | Meaning | Checked in files | Default |
|---|---|---|---|
var_brg | Bridge for net0. A bridge that does not exist on the node ends the run with exit 208. | must exist (ip link show) | vmbr0 |
var_sdn_vnet | SDN vnet to attach instead of the bridge | must be a configured vnet | empty |
var_net | dhcp, an address with prefix (192.168.1.50/24), or a range (192.168.1.100/24-192.168.1.200/24). From a range the first address that does not answer a ping is used; with none free the container falls back to DHCP. | one of the three forms | dhcp |
var_gateway | IPv4 gateway. Dropped with a warning when var_net is dhcp or the gateway is outside the subnet. | IPv4 address without prefix | empty |
var_ipv6_method | auto (SLAAC), dhcp, static or none. With static on the command line the address comes from IPV6_ADDR and the gateway from IPV6_GATE. | auto, dhcp, static, none | none |
var_mac | MAC address | XX:XX:XX:XX:XX:XX | empty (generated by Proxmox) |
var_mtu | Interface MTU | 576-65520 | empty |
var_vlan | VLAN tag | 1-4094 | empty |
var_ns | DNS servers, IP addresses separated by spaces or commas | not checked in files; checked before pct create | empty (host setting) |
var_searchdomain | DNS search domains | not checked in files; checked before pct create | empty (host setting) |
Storage
| Variable | Meaning | Checked in files | Default |
|---|---|---|---|
var_container_storage | Storage for the root disk. Must hold content rootdir. | not checked | none; chosen or asked, see Unattended deployments |
var_template_storage | Storage for the template. Must hold content vztmpl. Not used on Incus. | not checked | none; chosen or asked |
A name that no longer holds the content is not fatal: the storage dialog opens instead.
Access
| Variable | Meaning | Checked in files | Default |
|---|---|---|---|
var_pw | Root password. Leading - characters are removed. Empty means no password: the installer deletes it and logs root in automatically on the console. A password shorter than 5 characters exits 208. | not checked | empty |
var_ssh | Allow root login over SSH | yes or no | no |
var_ssh_authorized_key | One public key line, installed into /root/.ssh/authorized_keys when var_ssh=yes | not checked | empty |
var_github_token | Exported as GITHUB_TOKEN when that is not already set, to avoid GitHub API rate limits | not checked | empty |
Features
| Variable | Meaning | Checked in files | Default |
|---|---|---|---|
var_nesting | nesting=1 feature | 0 or 1 | 1 |
var_keyctl | Recorded and shown in the summary. On Proxmox VE build_container adds keyctl=1 to every unprivileged container and does not read this value. | 0 or 1 | 0 |
var_mknod | mknod=1 feature | 0 or 1 | 0 |
var_mount_fs | Filesystem types the container may mount, e.g. nfs,cifs. Not paths. | comma-separated names of letters and digits | empty |
var_fuse | fuse=1 feature | yes or no | no |
var_tun | Pass /dev/net/tun into the container | yes or no | no |
var_gpu | Detect and pass through GPUs | yes or no | no; media scripts such as ct/jellyfin.sh set yes |
Proxy, cache and hooks
| Variable | Meaning | Checked in files | Default |
|---|---|---|---|
var_apt_cacher | yes to use an apt-cacher-ng proxy | not checked | empty |
var_apt_cacher_ip | Host, host:port or URL of the cache. Port 3142 is assumed for a bare host. An unreachable cache is switched off for the run. | host or http(s):// URL | empty |
var_http_proxy | HTTP/HTTPS proxy for the install | http:// or https:// URL | empty |
var_http_no_proxy | NO_PROXY list | comma-separated hosts | empty |
var_inherit_host_ca | Copy the host's /usr/local/share/ca-certificates/*.crt into the container. yes copies; no and auto do not. | yes, no or auto | no |
var_post_install | Absolute path of a script on the host. Runs as root on the host after the install, with APP, NSAPP, CTID, IP, HN, STORAGE, BRG in its environment. Output goes to /var/log/community-scripts/post-install-<CTID>.log. | absolute path without ;, $(, backtick, &&, || | empty |
Command line only (VAR_RESERVED)
A line for one of these in any .vars file is skipped with
<name> in <file> is ignored: set it on the command line of the run that needs it.
| Variable | Meaning | Values |
|---|---|---|
var_ctid | Container ID. An ID already in use is replaced by the next free one with a warning. | number from 100 up, no leading zero; default is the next free ID |
var_arm64 | Whether the script runs on arm64 hosts. Declared by each script; on the command line it overrides the script. Unset on an arm64 host the script asks, and without a terminal exits 106. | yes, no |
var_external_installer | Answers the confirmation before a third-party installer runs (confirm_external_installer, e.g. install/casaos-install.sh). Any other value declines and exits 254. | yes, y, true |
var_ignore_disable | Install or update a script that is marked disabled | 1, yes, true, on |
var_ignore_os_mismatch | Update although the container OS differs from the script's | 1, yes, true, on |
var_ignore_breaking_changes | Skip the breaking-change check on update | 1, yes, true, on |
var_force_breaking_update | Continue an update past an advisory that blocks it | 1, yes, true, on |
var_ipv6_static | Copied to IPV6_STATIC by base_settings. build_container builds a static IPv6 from IPV6_ADDR and IPV6_GATE, so set those. | address with prefix |
var_testurl | Feedback link of a script under test. Declared by the script. | plain https:// URL, at most 200 characters |
var_install | Name of the install script. variables always sets it to the app name plus -install. | not user-settable |
var_bridge | Network of an Incus VM (incus/vm-core.func). Container scripts use var_brg. | network name |
Per run (VAR_PER_RUN)
Not read from default.vars, and never written when the wizard saves app
defaults. An app file loads them only if you add the line yourself.
| Variable | Meaning | Values |
|---|---|---|
var_unattended | Makes prompt_confirm and the other prompt helpers take their default instead of asking. See Unattended deployments. | yes, true, 1 |
var_full_verbose | Print debug messages with timestamps | 1 |
var_appversion | Install this release of the script's own app instead of the latest (lib/forge.func) | a release tag of the app |
An app's own settings
Any other var_ name belongs to one script, which declares and exports it.
ct/docker.sh has var_docker_socket, var_docker_compose and
var_docker_lxcfs; the installer asks only when they are empty:
var_docker_socket=n var_docker_compose=y \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/docker.sh)"These load from defaults/<app>.vars and from the command line, not from
default.vars. The script page and the generator list the ones
a script has.
On Incus the container path additionally reads var_profile (Incus profile,
default default), var_extra_disk (source of an extra disk device) and
var_extra_disk_path (its mount point, default /mnt/extra).
Examples
Override a few values for one run and keep the menu:
var_cpu=2 var_ram=2048 var_disk=12 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"Choose Default Install to use them as they are, or Advanced Install to start the wizard from them.
The same without the menu:
mode=default var_cpu=2 var_ram=2048 var_disk=12 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"A static address and a fixed ID:
mode=default var_ctid=120 var_hostname=debian-test \
var_net=192.168.1.50/24 var_gateway=192.168.1.1 var_ns=192.168.1.1 \
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"A misspelled variable name is not an error: nothing reads it, and the script default applies. Compare the summary the script prints before it creates the container with what you set.