Technical reference
Lookup tables for the engine - which file to read for which task, load guards, the host-to-container contract and the override variables.
This page is a set of lookup tables for people who read or change the engine. The overview of what each file is for is on Architecture; the function references are under core.func and Error handling.
Where to look
| You want to know | Read | Docs |
|---|---|---|
| How a script finds the engine | core/build.func | Loading |
| What runs on the host and what in the container | pve/backend.func (build_container), lxc/install.func | Runtime |
What msg_info, $STD or a prompt does | core/core.func | core.func |
| Why a run failed and what the error line means | core/error_handler.func, api/exitcodes.func | Error handling, Exit codes |
What a dev_mode switch does | core/dev-mode.func | Dev mode |
| How the install menu and defaults work | ui/menu.func, ui/defaults.func, ui/advanced.func | Wizard |
| How a container is created on Proxmox VE or Incus | pve/backend.func, incus/backend.func | Platforms |
| What the container bootstrap does | lxc/install.func | Containers |
| Which helper installs a runtime, database or release | lib/*.func | Libraries |
| How VM scripts work | pve/vm-core.func, incus/vm-core.func, vm/common.func | VM paths |
| What telemetry sends | api/telemetry.func | Telemetry |
How update works | ui/menu.func (start), core/core.func (write_update_entrypoint), misc/update.sh | Updates |
| Where banners come from | core/core.func (get_header), headers/ | Headers |
Entry points
| You are writing | Load | Then call |
|---|---|---|
| a ct script | core/build.func (the standard loader lines) | header_info, variables, color, catch_errors, and at the end start, build_container, description |
| an install script | source /dev/stdin <<<"$FUNCTIONS_FILE_PATH" | color, verb_ip6, catch_errors, setting_up_container, network_check, update_os, and at the end motd_ssh, customize, cleanup_lxc |
| an add-on script | core/core.func, lib/tools.func, core/error_handler.func, api/api.func by URL | load_functions, catch_errors |
| a VM script | pve/vm-core.func by URL | load_functions |
Files, guards and loaders
Every file can be sourced more than once; a guard variable makes the second load a no-op. Files without a guard only define functions, or are sourced once by design.
| File | Guard variable | Loaded by |
|---|---|---|
core/build.func | _LXC_BUILD_DISPATCHED | ct script |
core/core.func | _CORE_FUNC_LOADED | ui/build-ui.func, incus/core.func, lxc/install.func, add-ons |
core/error_handler.func | none | ui/build-ui.func, lxc/install.func, add-ons |
core/dev-mode.func | _DEV_MODE_FUNC_LOADED | ui/build-ui.func, lxc/install.func (with dev_mode) |
host/source-origin.func | _CS_SOURCE_ORIGIN_LOADED | core/build.func |
host/validate.func | _VALIDATE_FUNC_LOADED | ui/build-ui.func, pve/vm-core.func, incus/vm-core.func |
host/preflight.func | _PREFLIGHT_FUNC_LOADED | run_preflight with ENABLE_PREFLIGHT=1 |
lxc/platform.func | _LXC_PLATFORM_FUNC_LOADED | core/build.func |
lxc/install.func | none | install script |
ui/build-ui.func | _BUILD_UI_FUNC_LOADED | core/build.func, incus/build.func |
ui/validate.func | _BUILD_UI_VALIDATE_LOADED | ui/build-ui.func |
ui/defaults.func | _BUILD_UI_DEFAULTS_LOADED | ui/build-ui.func |
ui/advanced.func | _BUILD_UI_ADVANCED_LOADED | ui/build-ui.func |
ui/menu.func | _BUILD_UI_MENU_LOADED | ui/build-ui.func |
pve/backend.func | _PVE_BACKEND_FUNC_LOADED | core/build.func |
pve/vm-core.func | _VM_CORE_DISPATCHED | VM script |
pve/vm-app.func | none | not loaded by the engine |
incus/build.func | _INCUS_BUILD_FUNC_LOADED | core/build.func |
incus/core.func | _INCUS_CORE_FUNC_LOADED | incus/build.func, incus/tools.func, incus/vm-core.func |
incus/backend.func | _INCUS_BACKEND_LOADED | incus/build.func |
incus/tools.func | _INCUS_TOOLS_FUNC_LOADED | incus/build.func |
incus/vm-core.func | _INCUS_VM_CORE_LOADED | pve/vm-core.func |
vm/common.func | _VM_COMMON_LOADED | pve/vm-core.func, incus/vm-core.func |
vm/cloud-init.func | none | pve/vm-core.func |
lib/tools.func | _TOOLS_FUNC_LOADED | start, update_os, add-ons |
lib/system.func | _TOOLS_SYSTEM_LOADED | lib/tools.func |
lib/forge.func | _TOOLS_FORGE_LOADED | lib/tools.func |
lib/runtime.func | _TOOLS_RUNTIME_LOADED | lib/tools.func |
lib/db.func | _TOOLS_DB_LOADED | lib/tools.func |
lib/hwaccel.func | _TOOLS_HWACCEL_LOADED | lib/tools.func |
lib/alpine.func | none | update_os on Alpine |
api/api.func | none | ui/build-ui.func, VM cores, add-ons |
api/exitcodes.func | _API_EXITCODES_LOADED | api/api.func, lxc/install.func |
api/errorlog.func | _API_ERRORLOG_LOADED | api/api.func, lxc/install.func |
api/sysinfo.func | _API_SYSINFO_LOADED | api/api.func |
api/telemetry.func | _API_TELEMETRY_LOADED | api/api.func |
lib/tools.func loads its parts in the order system, forge, runtime, db,
hwaccel. api/api.func loads exitcodes, errorlog, sysinfo, telemetry.
ui/build-ui.func loads api/api.func, core/core.func,
core/error_handler.func, core/dev-mode.func, then host/validate.func,
ui/validate.func, ui/defaults.func, ui/advanced.func, ui/menu.func.
Variables that select sources
| Variable | Meaning | Default |
|---|---|---|
COMMUNITY_SCRIPTS_CORE_URL | Raw base URL of the engine | https://raw.githubusercontent.com/community-scripts/core/main |
COMMUNITY_SCRIPTS_CORE_DIR | Local engine directory | detected from a sibling checkout, else the prefetch directory |
COMMUNITY_SCRIPTS_URL | Raw base URL of the scripts | https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main |
COMMUNITY_SCRIPTS_ROOT | Local scripts directory | detected from the running script's location |
COMMUNITY_SCRIPTS_NO_PREFETCH | 1 disables the engine prefetch | unset |
LXC_PLATFORM | pve, incus, incus-container or container | detected |
COMMUNITY_SCRIPTS_WEBSITE_URL | Website used by the generated update command and in messages | https://community-scripts.org |
COMMUNITY_SCRIPTS_STATE_DIR | Directory for defaults, diagnostics setting and cached banners | /usr/local/community-scripts, or ~/.config/community-scripts for a non-root Incus user |
Host-to-container contract
build_container exports these before it starts the install script. An
install script may read them and must not redefine them.
| Variable | Content |
|---|---|
FUNCTIONS_FILE_PATH | The text of lxc/install.func |
app | Lower-case name without spaces (NSAPP) |
APPLICATION | Display name (APP) |
APPLICATION_VERSION | var_appversion, if set |
CTID, CTTYPE | Container ID; 1 unprivileged, 0 privileged |
PCT_OSTYPE, PCT_OSVERSION, PCT_ARCH, PCT_DISK_SIZE | OS, release, architecture and disk size in GB |
var_ram | The RAM the container really got, in MiB |
PASSWORD | Root password; empty means console autologin |
SSH_ROOT, SSH_AUTHORIZED_KEY | Root SSH choice and public key |
VERBOSE | yes or no |
MODE | The install method; makes prompts in the container return their defaults |
tz | Timezone |
IPV6_METHOD | IPv6 setting; disable turns IPv6 off in verb_ip6 |
ENABLE_FUSE, ENABLE_TUN, ENABLE_GPU | Feature choices |
CACHER, CACHER_IP | APT cacher setting |
SESSION_ID, INSTALL_LOG, BUILD_LOG | Session ID and log paths; INSTALL_LOG is /root/.install-<SESSION_ID>.log |
COMMUNITY_SCRIPTS_URL, COMMUNITY_SCRIPTS_CORE_URL | Both source bases |
DIAGNOSTICS, RANDOM_UUID, EXECUTION_ID, REPO_SOURCE, REPO_SLUG, TELEMETRY_PLATFORM | Telemetry context for progress pings |
CS_TESTING, CS_TESTING_URL | Testing-build state for the login banner |
dev_mode, DEV_MODE_* | Dev-mode switches |
In the other direction the container leaves files for the host:
/root/.install-<SESSION_ID>.log, .log.errinfo, .failed, .done and
.pid. See Error handling.
Function inventories
The engine keeps a generated list of public functions next to three loaders:
lib/API.txt,
api/API.txt
and ui/API.txt.
The verify-split-files.yml workflow compares each list with the functions
the loader really defines, and checks the prefetch lists _CS_ENGINE_FILES
and _CS_CT_ENGINE_FILES against the repository. When you add, rename or
remove a top-level function in lib/, api/ or ui/, regenerate the list in
the same pull request; when you add a file, add it to the prefetch list.
core/core.func and core/error_handler.func have no inventory file. Their
public functions are the ones documented on
core.func and
Error handling; names that start with an
underscore are internal.
Rules
- Write engine paths with their folder (
lib/system.func). - In engine code, load engine files with
_cs_source_funcand read them with_cs_fetch_text. A fixed URL ignores local checkouts, forks and the prefetched copy. - Do not source individual parts of
lib/,ui/orapi/from a script. - Do not set
ERRorEXITtraps in a script;catch_errorsowns them. - The code on
mainof community-scripts/core is the authority. If a page here disagrees with it, the page is wrong.