core.func

core/core.func is the part of the engine that runs everywhere: on the host while a container is created, inside the container while the application is installed, during update, and in the standalone add-on and tool scripts. It holds colours, message output, the $STD wrapper, prompts, host checks and a few maintenance helpers.

How it is loadedCopy Anchor Link

You rarely source it yourself:

VM scripts do not load core/core.func; pve/vm-core.func carries its own copies of the message helpers.

The file guards itself with _CORE_FUNC_LOADED, exports COMPOSER_ALLOW_SUPERUSER=1, sets HOME when it is empty, and installs two default traps at the end: HUP → on_hup_keepalive and EXIT INT TERM → stop_spinner. catch_errors replaces them.

load_functionsCopy Anchor Link

load_functions

Runs color, formatting, icons, default_vars and set_std_mode once (guarded by __FUNCTIONS_LOADED). Add-on scripts call it directly, for example tools/addon/add-tailscale-lxc.sh:

source <(curl -fsSL "${COMMUNITY_SCRIPTS_CORE_URL:-https://raw.githubusercontent.com/community-scripts/core/main}/core/core.func")
# ...
load_functions

Colours, formatting and iconsCopy Anchor Link

These functions only set variables. Use the variables inside echo -e.

When dev_mode is set to anything, color turns GN, DGN and BGN red, so a dev run cannot be mistaken for a normal install.

The closing lines of ct/vaultwarden.sh show the usual use:

echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}"
echo -e "${INFO}${YW}Access it using the following URL:${CL}"
echo -e "${GATEWAY}${BGN}https://${IP}:8000${CL}"

MessagesCopy Anchor Link

Every log line is written by log_msg to the active log file with a timestamp and without colour codes.

msg_infoCopy Anchor Link

msg_info "Installing Dependencies"

Opens a step. It stops any running spinner, starts a new one in the background and returns immediately. The message is also recorded as the current step (CS_STEP), which the error handler and telemetry use to say where a run failed.

• The spinner is replaced by a static hourglass line when verbose mode is on, when the OS is Alpine, or when stderr is not a terminal (see is_verbose_mode).
• A message that is already open is not printed a second time.
• An empty message does nothing.
• With dev_mode=pause it waits for Enter after printing.

msg_okCopy Anchor Link

msg_ok "Installed Dependencies"

Closes a step: stops the spinner, clears the line and prints the message with a check mark. If an outer step is still open (a helper such as setup_nodejs opened and closed its own step inside yours), its spinner resumes.

Always pair the two, as in install/vaultwarden-install.sh:

msg_info "Installing Dependencies"
$STD apt install -y \
  build-essential \
  pkgconf \
  libssl-dev \
  libmariadb-dev-compat \
  libpq-dev \
  argon2 \
  ssl-cert
msg_ok "Installed Dependencies"

msg_errorCopy Anchor Link

msg_error "No ${APP} Installation Found!"

Prints the error and logs it. It does not exit; follow it with exit or return yourself, as ct/vaultwarden.sh does:

if [[ ! -f /etc/systemd/system/vaultwarden.service ]]; then
  msg_error "No ${APP} Installation Found!"
  exit
fi

The first msg_error of a step is kept in CS_ERROR_MSG and sent with the failure report.

msg_warnCopy Anchor Link

msg_warn "Old Installation Found, you need to migrate your data and recreate to a new container"

A non-fatal notice (example from ct/actualbudget.sh). Like msg_error, it stops the spinner and does not resume it.

msg_customCopy Anchor Link

msg_custom "<symbol>" "<colour>" "<message>"

From ct/ampache.sh:

msg_custom "⚠️" "${YW}" "Complete database update by visiting: http://${LOCAL_IP}/update.php"

msg_debugCopy Anchor Link

msg_debug "Using release $victoriametrics_release"

Prints only when var_full_verbose=1, and in that case also sets var_verbose=1. Example from ct/victoriametrics.sh.

msg_devCopy Anchor Link

msg_dev "Keep mode active - container ${CTID} preserved"

Prints only when dev_mode is non-empty. Used by the backends, not by application scripts.

fatalCopy Anchor Link

fatal "<message>"

Calls msg_error and then sends SIGINT to the script (kill -INT $$), so the run ends through the interrupt handler with exit code 130. network_check in lxc/install.func uses it when GitHub host names do not resolve. No application script calls it directly.

exit_scriptCopy Anchor Link

exit_script

Clears the screen, prints User exited script and exits. The engine's whiptail menus call it when you press Cancel.

$STD, silent and verbose modeCopy Anchor Link

$STD is the prefix you put in front of commands whose output should not clutter the screen:

$STD apt install -y nginx

set_std_mode always sets STD="silent", so the line above runs silent apt install -y nginx.

silentCopy Anchor Link

silent <command> [arguments...]

• Appends the command's stdout and stderr to the active log file.
• With VERBOSE=yes the output is shown on screen as well and still logged.
• External programs run with SIGHUP ignored and, when stdin is a terminal, with stdin from /dev/null. Closing the console does not kill a running apt or npm. Shell functions run in the current shell so their side effects are kept.
• apt is called with -o Apt::Cmd::Disable-Script-Warning=true.
• On failure it returns the command's exit status and writes <logfile>.errinfo with the exit code, line, command, calling function, current step and the output of that one command. The error handler reads this file to show what the failing command printed.
• On success it removes the .errinfo file.

silent does not exit by itself. The non-zero return triggers the ERR trap that catch_errors installed; append || true when a failure is acceptable.

$STD applies to one simple command. In $STD a | b only a is wrapped.

Verbose modeCopy Anchor Link

is_verbose_mode returns true when VERBOSE (or, if unset, var_verbose) is anything other than no, and also when stderr is not a terminal and CS_ANIMATION_OK is not 1. msg_info uses it to choose between the spinner and a static line.

set_std_mode also turns on set -x when DEV_MODE_TRACE=true.

Log filesCopy Anchor Link

get_active_logfile prints the file silent and the msg_* functions write to. The first variable that is set wins:

SpinnerCopy Anchor Link

spinner, stop_spinner and clear_line are used by the message functions. Call stop_spinner only if you print to the terminal yourself between msg_info and msg_ok. The spinner's PID is kept in SPINNER_PID and /tmp/.spinner.pid.

PromptsCopy Anchor Link

All prompt functions answer on their own when nobody can: in unattended runs they return the default at once, and interactive prompts fall back to the default after a timeout.

is_unattendedCopy Anchor Link

Returns 0 (unattended) when:

• MODE (or mode) is default, mydefaults, userdefaults or appdefaults (or 1, 3, 4);
• MODE is advanced (or 2) and pveversion is not available, which is the case inside a container;
• PHS_SILENT=1, or var_unattended / UNATTENDED is yes, true or 1;
• stdin is not a terminal.

The backend exports MODE into the container, and the install script runs through lxc-attach without a terminal on stdin. In practice an install script therefore always takes the default. Read a var_* variable first and prompt only when it is empty.

prompt_confirmCopy Anchor Link

prompt_confirm "<message>" [default] [timeout]

Returns 0 for yes and 1 for no. An empty or invalid answer uses the default. From install/shlink-install.sh:

if prompt_confirm "Install Shlink Web Client?" "y" 60; then
  msg_info "Installing Dependencies"
  $STD apt install -y nginx
  msg_ok "Installed Dependencies"
  # ...
fi

prompt_inputCopy Anchor Link

value=$(prompt_input "<message>" [default] [timeout])

Prints the answer, or the default when the answer is empty, the timeout (default 60 seconds) passes, the run is unattended or stdin is not a terminal. The prompt itself goes to stderr, so command substitution captures only the value. From install/espocrm-install.sh:

if [[ -z "${var_admin_user:-}" ]]; then
  var_admin_user=$(prompt_input "EspoCRM admin username (a-z, 0-9, @ . _ -):" "admin" 60)
fi

prompt_input_requiredCopy Anchor Link

value=$(prompt_input_required "<message>" [fallback] [timeout] [variable-name])

Interactive runs get three attempts at a non-empty answer. Whenever the fallback is used, the variable name is added to the MISSING_REQUIRED_VALUES array. No script in ProxmoxVE uses it at the moment; the example is the one in the function's own header:

token=$(prompt_input_required "Enter API Token:" "YOUR_TOKEN_HERE" 60 "var_api_token")

show_missing_values_warningCopy Anchor Link

show_missing_values_warning

Prints a box listing everything in MISSING_REQUIRED_VALUES and returns 1; returns 0 and prints nothing when the array is empty. Because it returns 1, call it as show_missing_values_warning || true under catch_errors.

prompt_selectCopy Anchor Link

choice=$(prompt_select "<message>" <default-number> <timeout> "<option 1>" "<option 2>" ...)

Shows a numbered list on stderr and prints the chosen option text. The default number is 1-based. The default option is returned in unattended runs, when /dev/tty is not readable, on timeout and on invalid input. Returns 1 when no options are given. All three leading arguments must be present because the function shifts them away. Example from the function's header (no script in ProxmoxVE uses it at the moment):

choice=$(prompt_select "Select database:" 1 30 "PostgreSQL" "MySQL" "SQLite")

prompt_passwordCopy Anchor Link

password=$(prompt_password "<message>" [default] [timeout] [min-length])

Reads without echo. Pass generate as the default to get a random 16-character alphanumeric password when nobody types one. An answer shorter than min-length is replaced by the default. From install/foldingathome-install.sh:

if [[ -z "${var_fah_token:-}" ]]; then
  var_fah_token=$(prompt_password "Folding@home account token (Enter to skip):" "" 120)
fi

random_passwordCopy Anchor Link

random_password [length]

Prints an alphanumeric (A-Za-z0-9) string from /dev/urandom, 24 characters by default. From install/adventurelog-install.sh:

SECRET_KEY="$(random_password 32)"

confirm_external_installerCopy Anchor Link

confirm_external_installer "<source>" "<installer>"

Warns that code from a third party is about to run and asks Do you want to continue? [y/N].

• var_external_installer answers the question without a prompt: y, yes or true continue, any other value declines.
• Declining, or having no terminal to answer on, exits with code 254.

From install/bunkerweb-install.sh:

confirm_external_installer "install-bunkerweb.sh" "https://github.com/bunkerity/bunkerweb/raw/v${RELEASE}/misc/install-bunkerweb.sh"

Unattended:

var_external_installer=yes mode=default bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/bunkerweb.sh)"

HeaderCopy Anchor Link

header_infoCopy Anchor Link

header_info

Clears the screen (only when stdout is a terminal and TERM is not dumb) and prints the ASCII banner for APP. Arguments are ignored; the name comes from APP, lower-cased with spaces removed. If no banner exists, a generic Community Scripts banner and the app name are printed.

get_header finds the banner in this order, for <type>/<name> and then <type>/<platform>/<name> (APP_TYPE defaults to ct; platform is pve or incus):

1. headers/ in a local engine directory (COMMUNITY_SCRIPTS_CORE_DIR),
2. the cache in /usr/local/community-scripts/headers/ (or the directory community_scripts_dir returns),
3. ${COMMUNITY_SCRIPTS_CORE_URL}/headers/, saved to the cache.

Every ct script calls it, for example ct/vaultwarden.sh:

header_info "$APP"
variables
color
catch_errors

See Headers for how banners are generated.

Host and environment checksCopy Anchor Link

install_script runs shell_check, root_check, pve_check, ensure_whiptail, arch_check, arm64_notice and ssh_check in that order before the install menu opens.

pve_checkCopy Anchor Link

pve_check

1. Not a Proxmox VE host → error, exit 232.
2. pmxcfs_check:
   • /etc/pve not mounted → offers to restart pve-cluster (when a terminal and whiptail are available); still not mounted → exit 228.
   • /etc/pve/storage.cfg not readable → exit 228.
   • /etc/pve/corosync.conf exists and pvecm status does not report Quorate: Yes → exit 210.
3. Version outside 8.0–8.9 and 9.0–9.2 → error naming the supported range, exit 1.

Exit code 105 ("Proxmox VE version not supported") is used by the VM path in pve/vm-core.func, not by pve_check. On Incus, incus/build.func replaces pve_check with its own check.

arch_check and var_arm64Copy Anchor Link

arch_check

Accepts amd64 and arm64 hosts and exits 106 on anything else. On arm64 the script's var_arm64 decides:

Scripts declare it at the top, as ct/vaultwarden.sh does:

var_arm64="${var_arm64:-yes}"

arch_resolveCopy Anchor Link

arch_resolve [amd64-value] [arm64-value]

Prints the first value on amd64 and the second on arm64. Without arguments it prints amd64 or arm64. The architecture comes from PCT_ARCH when set, otherwise from dpkg --print-architecture (or uname -m). On any other architecture it prints an error and returns 106.

From ct/agentdvr.sh, where upstream names its builds differently:

RELEASE=$(curl -fsSL "https://www.ispyconnect.com/api/Agent/DownloadLocation4?platform=$(arch_resolve "Linux64" "LinuxARM64")&fromVersion=0" | grep -o 'https://.*\.zip')

And without arguments in ct/victoriametrics.sh:

victoriametrics_filename="victoria-metrics-linux-$(arch_resolve)-${victoriametrics_release}.tar.gz"

require_pve_host, confirm_not_pve_host, require_debian_likeCopy Anchor Link

Guards for add-on scripts. A script that drives the node itself starts like tools/addon/add-tailscale-lxc.sh:

header_info
require_pve_host

A script meant to run inside a guest starts like tools/addon/coder-code-server.sh:

confirm_not_pve_host
require_debian_like

confirm_not_pve_host asks Continue anyway? (y/N) on a Proxmox VE host and exits 0 unless you answer y or yes.

Other checksCopy Anchor Link

OS dispatchCopy Anchor Link

run_os_setup and run_os_updateCopy Anchor Link

run_os_setup    # install script
run_os_update   # update_script in the ct script

Detect the OS family of the running system and call the matching function that your script defined:

If the function for the detected family is not defined, an error says so and the call returns 1. Define the functions before calling the dispatcher. ct/vaultwarden.sh:

function update_script() {
  header_info
  check_container_storage
  check_container_resources
  run_os_update
}

The dispatch looks at the running system, never at var_os.

Inside the containerCopy Anchor Link

get_lxc_ipCopy Anchor Link

get_lxc_ip

Sets and exports LOCAL_IP. It sources /run/local-ip.env if present; if LOCAL_IP is still empty it looks at eth0, then hostname -I, then the routing table, IPv4 first and IPv6 after. Returns 1 with an error when nothing is found. The container bootstrap and the update path call it, so LOCAL_IP is already set in install scripts and in update_script. Add-ons call it themselves, as tools/addon/coder-code-server.sh:

get_lxc_ip
IP="$LOCAL_IP"

cleanup_lxcCopy Anchor Link

cleanup_lxc

The last line of every install script. It:

• cleans the package manager: apk cache clean; dnf autoremove and dnf clean all; zypper clean; pacman -Sc; or apt autoremove and apt clean;
• deletes files named tmp* and tempfile* in /tmp and /var/tmp;
• removes the caches of the tools that are installed: pip, uv, npm, yarn, pnpm (pnpm store prune), Go build cache, Cargo registry cache, gem, Composer;
• prints Cleaned and sends a telemetry progress ping when POST_TO_API_DONE is set in that shell.

Failures in the cleanup are warnings and never fail the run. On updates it is called for you from the exit handler after update_script ends with status 0.

motd_ssh
customize
cleanup_lxc

motd_ssh and customizeCopy Anchor Link

These two are called next to cleanup_lxc but are defined in lxc/install.func, not in core/core.func. Neither takes arguments.

See Containers for the rest of the in-container bootstrap.

apt helpersCopy Anchor Link

apt_update_safe in ct/2fauth.sh:

apt_update_safe
$STD apt -y upgrade

The guard and the report are called by the engine (update_os, the update path and the exit handler); scripts do not call them.

Other helpersCopy Anchor Link

The update entry pointCopy Anchor Link

update inside a container is /usr/bin/update, a small generated script.

write_update_entrypointCopy Anchor Link

write_update_entrypoint "<slug>" "<script-name>" [scripts-base-url]

Writes /usr/bin/update through a temporary file and an atomic mv. The generated script exports SCRIPT_SLUG, UPDATE_SCRIPT_NAME, COMMUNITY_SCRIPTS_URL, COMMUNITY_SCRIPTS_CORE_URL and COMMUNITY_SCRIPTS_WEBSITE_URL, then runs misc/update.sh from the engine. If that helper cannot be downloaded it runs ct/<script-name>.sh directly. customize calls it at install time:

write_update_entrypoint "$app" "$update_script_name"

migrate_update_entrypointCopy Anchor Link

migrate_update_entrypoint

Run at the start of every update. It rewrites /usr/bin/update when the file does not use misc/update.sh yet, still points at git.community-scripts.org, or has no valid UPDATE_SCRIPT_NAME. The script name and base URL are read from the old file so the container keeps updating from the repository it was built from.

When a ct script runs inside a container, start performs these steps before your update_script: ensure_profile_loaded, ensure_recorded_toolchains, get_lxc_ip, migrate_update_entrypoint, the status, OS and breaking-change guards, and apt_conffile_guard. See Updates.

Testing buildsCopy Anchor Link

cs_testing_stateCopy Anchor Link

cs_testing_state

Sets and exports CS_TESTING and CS_TESTING_URL. A script is a testing build when it declares var_testurl (a plain https:// URL of at most 200 characters; anything else is ignored with a warning) or when REPO_SOURCE is DevScripts. The backend calls it before the install so motd_ssh can show the feedback link.

Internal functionsCopy Anchor Link

Names starting with _cs_, _pve or _msg are internal and can change without notice. The ones you may meet when reading the code: