System helpers

Source: lib/system.func. It is the first part loaded by lib/tools.func, see how helpers reach a script. lib/tools.func itself defines no public function, only the internal _tools_source_part that loads the parts.

The helpers are written for Debian and Ubuntu (apt, dpkg, systemd). The few that also handle other distributions say so. For Alpine install scripts see Alpine helpers.

Most commands inside these helpers run through $STD, so their output follows the script's verbose setting.

DownloadsCopy Anchor Link

curl_with_retryCopy Anchor Link

Download a URL to a file or to stdout, with retries and growing timeouts.

curl_with_retry <url> [output] [extra_curl_options]

For http:// and https:// URLs the host is resolved first. The pause between attempts starts at 1 s and doubles, capped at 30 s. curl runs with -fsSL, so an HTTP error status counts as a failure.

Returns 0 on success, 6 when the host does not resolve, 7 when all attempts failed. From install/immich-install.sh:

CURL_RETRIES=6 CURL_CONNECT_TO=30 curl_with_retry "https://download.geonames.org/export/dump/admin1CodesASCII.txt" "admin1CodesASCII.txt"

To stdout, from ct/checkmk.sh:

RELEASE=$(curl_with_retry "https://api.github.com/repos/checkmk/checkmk/tags" "-" | grep "name" | awk '{print substr($2, 3, length($2)-4) }' | tr ' ' '\n' | grep -Ev 'rc|b' | sort -V | tail -n 1)

curl_downloadCopy Anchor Link

Download a file that may be large or slow. Instead of a total time limit it aborts only when the transfer drops below 1 KB/s for 60 seconds.

curl_download <output_file> <url>

Note the argument order: the output file comes first.

Three attempts, 10 s and 20 s apart. A retry resumes where the previous attempt stopped, and the last attempt is forced over IPv4 when an IPv4 default route exists. The data is written to <output_file>.part and moved into place only when complete, so a failed download leaves an existing file untouched.

Returns 0 on success, 7 when all attempts failed. From ct/apache-guacamole.sh:

curl_download "/tmp/guacamole-auth-jdbc.tar.gz" "https://downloads.apache.org/guacamole/${LATEST_SERVER}/binary/guacamole-auth-jdbc-${LATEST_SERVER}.tar.gz"

download_fileCopy Anchor Link

Download a URL to a file with a fixed number of plain retries.

download_file <url> <output> [max_retries] [show_progress]

Returns 0 on success, 250 after the last failed attempt. From install/hev-socks5-server-install.sh:

download_file "https://raw.githubusercontent.com/heiher/hev-socks5-server/refs/heads/main/conf/main.yml" "/etc/hev-socks5-server/main.yml"

download_with_progressCopy Anchor Link

Download a URL to a file and show a pv progress bar when the server sends a Content-Length.

download_with_progress <url> <output>

Installs pv if needed, stops a running spinner (SPINNER_PID), and switches on set -o pipefail, which stays on for the rest of the script. Returns 0 on success, 7 when the download failed. No script in ProxmoxVE calls it directly.

curl_api_with_retryCopy Anchor Link

Call an HTTP API and print the status code.

curl_api_with_retry <url> [body_file] [extra_curl_options]

Prints the HTTP status code on stdout. Returns 0 on a 2xx status, 7 after the last failed attempt. No script in ProxmoxVE calls it directly.

download_gpg_keyCopy Anchor Link

Download a signing key and store it as a binary keyring.

download_gpg_key <url> <output> [mode]

The keyring gets mode 644. Returns 0 on success, 7 on failure, after a warning that names the last error. setup_deb822_repo handles the key itself, so use this only when you write the sources file yourself. From install/frigate-install.sh:

download_gpg_key "https://repositories.intel.com/gpu/intel-graphics.key" "/usr/share/keyrings/intel-graphics.gpg" "dearmor"

verify_gpg_fingerprintCopy Anchor Link

Compare the fingerprint of a key file with an expected value.

verify_gpg_fingerprint <key_file> <expected_fingerprint>

Only the first fingerprint in the file is compared. Returns 0 on a match, 65 with an error message otherwise. No script in ProxmoxVE calls it directly.

PackagesCopy Anchor Link

ensure_dependenciesCopy Anchor Link

Install the given packages unless they are already there.

ensure_dependencies <package> [package ...]

A name counts as present when a command of that name exists or a package of that name is installed. On Debian and Ubuntu apt update runs first, unless it ran in the last 5 minutes (timestamp in /var/cache/apt-update-timestamp). If the batch install fails, the packages are tried one by one to name the one that failed.

The function also works on Alpine (apk add --no-cache) and, when the engine reports that OS family, with dnf/yum, zypper, pacman and emerge.

Returns 0 on success; 100 on Debian and Ubuntu, 1 on the other distributions, when a package could not be installed. From ct/opencloud.sh:

ensure_dependencies "inotify-tools"

install_packages_with_retryCopy Anchor Link

Install packages with apt and try to repair apt between attempts.

install_packages_with_retry <package> [package ...]

Up to four attempts with --force-confdef and --force-confold. After the first failure it runs dpkg --configure -a and apt update, after the second apt --fix-broken install, and on the third retry it installs the packages one by one. When everything fails it reports which packages no configured repository offers.

Returns 0 on success, 100 otherwise. From install/immich-install.sh:

install_packages_with_retry jellyfin-ffmpeg7

upgrade_packages_with_retryCopy Anchor Link

Upgrade already installed packages (apt install --only-upgrade) with up to three attempts.

upgrade_packages_with_retry <package> [package ...]

Returns 0 on success, 100 otherwise. From ct/pricebuddy.sh:

upgrade_packages_with_retry google-chrome-stable

upgrade_packageCopy Anchor Link

Upgrade one package once, after an apt update if the last one is older than 5 minutes.

upgrade_package <package>

Returns 0 on success, 100 with a warning otherwise. No script in ProxmoxVE calls it directly.

is_package_installedCopy Anchor Link

Test whether a package is installed (dpkg, or apk on Alpine).

is_package_installed <package>

Returns 0 when installed, non-zero otherwise. From ct/technitiumdns.sh:

if ! is_package_installed "aspnetcore-runtime-10.0"; then

hold_package_version, unhold_package_versionCopy Anchor Link

Run apt-mark hold or apt-mark unhold for one package.

hold_package_version <package>
unhold_package_version <package>

A failure only prints a warning. No script in ProxmoxVE calls them directly.

verify_package_sourceCopy Anchor Link

Test whether apt-cache policy for a package mentions a version string.

verify_package_source <package> <expected_version>

Returns 0 when the string appears, 1 otherwise. No script in ProxmoxVE calls it directly.

ensure_apt_workingCopy Anchor Link

Bring apt into a usable state before packages are installed.

ensure_apt_working

It waits up to 60 s for apt locks, finishes interrupted dpkg runs, removes orphaned sources (cleanup_orphaned_sources) and runs apt update. If that fails it clears /var/lib/apt/lists and tries again. If it still fails it deletes every .sources and .list file in /etc/apt/sources.list.d except the distribution's own <id>.sources and tries a last time.

Returns 0 on success, 100 when apt update cannot be made to work. Scripts do not call it directly; the setup_* helpers and prepare_repository_setup do.

is_apt_locked, wait_for_aptCopy Anchor Link

Test for, or wait out, another process holding an apt or dpkg lock.

is_apt_locked
wait_for_apt [max_wait_seconds]

is_apt_locked returns 0 when a lock is held. wait_for_apt checks every 5 s and returns 0 once the locks are free, or 100 after max_wait_seconds (default 300). No script in ProxmoxVE calls them directly.

RepositoriesCopy Anchor Link

setup_deb822_repoCopy Anchor Link

Add an apt repository in deb822 format, including its signing key, and run apt update.

setup_deb822_repo <name> <gpg_url> <repo_url> <suite> [component] [architectures] [enabled]

Before writing, it removes older files of the same name: every .list, .sources and key file starting with <name> (see cleanup_old_repo_files), and orphaned sources.

From ct/cockpit.sh:

setup_deb822_repo "45drives" \
  "https://repo.45drives.com/key/gpg.asc" \
  "https://repo.45drives.com/enterprise/debian" \
  "$(get_os_info codename)" \
  "main" \
  "amd64"

get_fallback_suiteCopy Anchor Link

Find a suite a third-party repository actually offers when it has none for the running release yet.

get_fallback_suite <distro_id> <distro_codename> <repo_base_url>

Prints the codename itself when <repo_base_url>/dists/<codename>/Release exists. Otherwise it tries older releases of the same distribution in order (for Debian trixie: bookworm, bullseye; for Ubuntu noble: noble, jammy) and prints the first that exists, or the first candidate unverified. For distributions other than Debian and Ubuntu it prints the codename unchanged. Always returns 0.

From install/jellyfin-install.sh:

JELLYFIN_SUITE="$(get_fallback_suite "$(get_os_info id)" "$(get_os_info codename)" "$JELLYFIN_REPO_URL")"

verify_repo_availableCopy Anchor Link

Test whether a repository has a given suite.

verify_repo_available <repo_url> <suite>

Requests <repo_url>/dists/<suite>/Release with a 5 s limit. Returns 0 when it exists, 1 otherwise. Used by get_fallback_suite.

setup_nonfreeCopy Anchor Link

Add Debian's contrib, non-free and non-free-firmware components.

setup_nonfree

Writes /etc/apt/sources.list.d/debian-nonfree.sources if it does not exist and refreshes the package lists. The suites in that file are fixed to trixie, trixie-updates and trixie-security. Returns 0. From install/nzbget-install.sh:

setup_nonfree

cleanup_old_repo_filesCopy Anchor Link

Remove every repository and key file whose name starts with a given string.

cleanup_old_repo_files <name>

Deletes <name>*.list (and their .save, .distUpgrade, .dpkg-* leftovers) and <name>*.sources in /etc/apt/sources.list.d, and <name>*.gpg in /etc/apt/trusted.gpg.d and /etc/apt/keyrings. From ct/caddy.sh:

cleanup_old_repo_files "caddy"

cleanup_orphaned_sourcesCopy Anchor Link

Remove .sources files whose Signed-By: keyring no longer exists, and broken symlinks in /etc/apt/keyrings.

cleanup_orphaned_sources

The distribution's own <id>.sources is never removed. Called by setup_deb822_repo, ensure_apt_working and ensure_dependencies.

cleanup_tool_keyringsCopy Anchor Link

Remove key files by name prefix from all three keyring locations.

cleanup_tool_keyrings <prefix> [prefix ...]

Deletes <prefix>*.gpg in /usr/share/keyrings, /etc/apt/keyrings and /etc/apt/trusted.gpg.d. Used by remove_old_tool_version and prepare_repository_setup.

prepare_repository_setupCopy Anchor Link

Clear the old repository files and keys of one or more tools, then make sure apt works.

prepare_repository_setup <name> [name ...]

Runs cleanup_old_repo_files and cleanup_tool_keyrings for each name, then ensure_apt_working. Returns 0, or 100 when apt cannot be repaired. Used by the setup_* helpers in runtimes and databases.

manage_tool_repositoryCopy Anchor Link

Write the upstream apt repository for one of the tools the engine installs itself.

manage_tool_repository <tool> <version> <repo_url> [gpg_key_url]

It picks the suite for the running release, including the fallbacks each vendor needs (for example MongoDB on Debian arm64 uses the Ubuntu repository). Returns 0 on success, 65 for an unknown tool or a missing argument, 7 when the key could not be downloaded, 100 when the PHP keyring package could not be installed. Used by the setup_* helpers; scripts do not call it.

Tool versionsCopy Anchor Link

These helpers are the building blocks of the setup_* functions. Scripts rarely need them.

is_tool_installedCopy Anchor Link

Print the installed version of a known tool.

is_tool_installed <tool> [required_version]

Returns 0 when the tool is installed and, if required_version is given, the printed version equals it exactly. Returns 1 when it is not installed (nothing printed) or differs (the installed version is still printed).

should_update_toolCopy Anchor Link

Decide whether a tool has to be installed or changed to reach a target version.

should_update_tool <tool> <target_version>

Returns 0 when the tool is missing or its version does not match the target at the target's precision (8.0 matches an installed 8.0.40), 1 when it matches. From ct/paperless-gpt.sh:

if should_update_tool "node" "24"; then

remove_old_tool_versionCopy Anchor Link

Purge the packages of a tool and remove its repository and keys. Data directories are kept.

remove_old_tool_version <tool> [repo_name]

tool is one of mariadb, mysql, mongodb, node / nodejs, php, postgresql, java, ruby, rust, go / golang, clickhouse. repo_name defaults to the tool name and is passed to cleanup_old_repo_files.

Before purging it simulates the purge and refuses, with a warning and return 1, when apt would also remove packages outside the tool's own. Returns 0 otherwise.

cleanup_legacy_installCopy Anchor Link

Remove installations made by per-user version managers.

cleanup_legacy_install <tool>

verify_tool_versionCopy Anchor Link

Compare the major version of an installed tool with the expected one.

verify_tool_version <tool_name> <expected_version> <installed_version>

Returns 0 when the parts before the first dot are equal, otherwise 1 after a warning.

version_matches_specCopy Anchor Link

Test whether an installed version matches a shorter version spec.

version_matches_spec <installed> <spec>

Compares as many dot-separated parts as the spec has: 8.0.40 matches 8.0 and 8, not 8.1. Returns 0 on a match, 1 otherwise or when an argument is empty.

version_gtCopy Anchor Link

Test whether the first version is greater than the second (version sort).

version_gt <a> <b>

Returns 0 when a is greater than b, 1 when it is equal or smaller.

should_upgradeCopy Anchor Link

Test whether a target version is newer than the current one.

should_upgrade <current> <target>

Returns 0 when current is empty or target is greater, 1 otherwise.

cache_installed_version, get_cached_versionCopy Anchor Link

Remember a version outside the app's own files.

cache_installed_version <name> <version>
get_cached_version <name>

The value is stored in /var/cache/app-versions/<name>_version.txt. get_cached_version prints it and returns 0, or returns 1 when nothing is stored. The setup_* helpers record what they installed this way. This is separate from the ~/.<app> stamp the release helpers use.

OS probesCopy Anchor Link

get_os_infoCopy Anchor Link

Print a field from /etc/os-release.

get_os_info [field]

Any other field prints the id. The values are read once and cached in the exported variables _OS_ID, _OS_CODENAME, _OS_VERSION and _OS_VERSION_FULL. From ct/checkmk.sh:

curl_download "/opt/checkmk.deb" "https://download.checkmk.com/checkmk/${RELEASE}/check-mk-community-${RELEASE}_0.$(get_os_info codename)_amd64.deb"

get_os_version_major, is_debian, is_ubuntuCopy Anchor Link

Shortcuts on top of get_os_info.

get_os_version_major
is_debian
is_ubuntu

get_os_version_major prints VERSION_ID up to the first dot. is_debian and is_ubuntu return 0 when the id is debian or ubuntu. From install/immich-install.sh:

if is_debian && [[ "$(get_os_version_major)" -lt 13 ]]; then

is_lts_versionCopy Anchor Link

Return 0 on Ubuntu focal, jammy, noble and on Debian bullseye, bookworm, trixie; 1 on anything else.

is_lts_version

get_system_archCopy Anchor Link

Print the CPU architecture in Debian naming.

get_system_arch [dpkg|uname|both]

From install/firecrawl-install.sh:

FDB_ARCH="$(get_system_arch)"

get_parallel_jobsCopy Anchor Link

Print a job count for compilers that fits the container.

get_parallel_jobs

The smallest of: CPU count, memory in MB divided by 1536, and CPU count minus the current 1-minute load; reduced by a quarter inside a container; at least 1. The result is cached in the exported _PARALLEL_JOBS. From install/vaultwarden-install.sh:

CARGO_BUILD_JOBS="$(get_parallel_jobs)" CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 $STD cargo build --features "sqlite,mysql,postgresql" --release

get_default_php_version, get_default_python_version, get_default_nodejs_versionCopy Anchor Link

Print the version the engine considers the default for the running release.

get_default_php_version
get_default_python_version
get_default_nodejs_version

get_default_nodejs_version always prints 24. No script in ProxmoxVE calls these directly.

ServicesCopy Anchor Link

safe_service_restartCopy Anchor Link

Restart (or start) a systemd service and wait until it is active.

safe_service_restart <service> [timeout_seconds]

Waits up to timeout_seconds (default 30) for the service to become active. If it does not, the service is stopped and the whole step repeated, three attempts in total. Returns 0 once active, otherwise 150 after printing the first lines of systemctl status. From install/foldingathome-install.sh:

safe_service_restart fah-client

enable_and_start_serviceCopy Anchor Link

Enable and start a systemd service.

enable_and_start_service <service>

Returns 0 on success, 150 when either step fails. No script in ProxmoxVE calls it directly; scripts use systemctl enable -q --now.

is_service_enabled, is_service_runningCopy Anchor Link

Wrap systemctl is-enabled --quiet and systemctl is-active --quiet.

is_service_enabled <service>
is_service_running <service>

Return 0 when true. No script in ProxmoxVE calls them directly.

stop_all_servicesCopy Anchor Link

Stop and disable every service whose unit name matches a pattern.

stop_all_services <pattern> [pattern ...]

The pattern is an extended regular expression searched in the output of systemctl list-units, not a glob: "php.*-fpm" matches php8.4-fpm.service. Note that the services are also disabled. Used by remove_old_tool_version.

Backups and filesCopy Anchor Link

create_backup, restore_backupCopy Anchor Link

Save files and directories before an update replaces the app directory, and put them back afterwards.

create_backup <path> [path ...]
restore_backup

create_backup copies each path into the store under its absolute path and records it in a manifest. A path that is already recorded is not copied again, so after a failed update a second run keeps the good copy from the first. Missing paths and mount points are skipped with a warning. If a copy fails the script exits with status 1 before the update touches anything.

restore_backup takes no arguments: it deletes each recorded path at its origin, copies the saved version back, and removes the store. Without a store it prints a warning and returns 0.

From ct/alpine-wakapi.sh:

create_backup /opt/wakapi/config.yml /opt/wakapi/wakapi_db.db
CLEAN_INSTALL=1 fetch_and_deploy_gh_release "wakapi" "muety/wakapi" "prebuild" "latest" "/opt/wakapi" "wakapi_linux_$(arch_resolve).zip"
restore_backup

create_temp_dirCopy Anchor Link

Create a temporary directory that is removed when the script ends.

create_temp_dir

Prints the path. The cleanup trap is registered in the shell that runs the function. Captured the usual way, dir=$(create_temp_dir), that shell is the command substitution itself, and the directory is removed as soon as the substitution returns. No script in ProxmoxVE or helper in lib/ calls it; use mktemp -d and remove the directory yourself.

edit_yaml_configCopy Anchor Link

Replace the value of a key in a YAML file with sed.

edit_yaml_config <file> <key> <value>

Every line whose key matches is changed, at any indentation, so nested keys with the same name all change. The value is written as given (add quotes yourself) and a trailing comment on the line is dropped. Returns 0 on success, 1 when the file or the key does not exist. From install/fmd-server-install.sh:

edit_yaml_config config.yml "WebDir" '"/opt/fmd-server/web/dist/"'

create_self_signed_certCopy Anchor Link

Create a self-signed TLS certificate for the app.

create_self_signed_cert [app_name] [extra_san]

Writes /etc/ssl/<app>/<app>.key (mode 600) and /etc/ssl/<app>/<app>.crt (mode 644): RSA 2048, valid 365 days, CN set to the host name, SANs for the host name, localhost, the container's IP and 127.0.0.1. Does nothing when both files already exist.

Returns 0 on success, 100 when OpenSSL could not be installed, 150 when the certificate could not be created. From install/chartdb-install.sh:

create_self_signed_cert "chartdb"

ensure_usr_local_bin_persistCopy Anchor Link

Make sure /usr/local/bin is in PATH for later logins.

ensure_usr_local_bin_persist

Writes /etc/profile.d/custom_path.sh and appends an export line to /root/.bashrc unless one is already there. Does nothing on a Proxmox VE host. The runtime setup_* helpers call it; among the scripts, tools/addon/actual-budget-prometheus-exporter.sh does.

setup_local_ip_helperCopy Anchor Link

Install a hook that keeps the container's current IP in /run/local-ip.env.

setup_local_ip_helper

Installs networkd-dispatcher, writes /usr/local/community-scripts/ip-management/update_local_ip.sh and the hook /etc/networkd-dispatcher/routable.d/10-update-local-ip.sh, and enables the service. The hook writes LOCAL_IP=<address> whenever the interface becomes routable. Returns 0, or 100 when networkd-dispatcher could not be installed. No script in ProxmoxVE calls it directly.

Debugging and timingCopy Anchor Link

debug_logCopy Anchor Link

Print a [DEBUG] line to stderr when debugging is switched on.

debug_log <message>

The helpers on this page log their retries and decisions through it. The variable has to be set in the shell the helpers run in, for example inside the container before an update run:

export TOOLS_DEBUG=true

start_timer, end_timerCopy Anchor Link

Measure how long a step takes.

start=$(start_timer)
end_timer "$start" [label]

start_timer prints the current Unix time; end_timer prints <label> took <n>s, with Operation as default label. No script in ProxmoxVE calls them directly.

Internal functionsCopy Anchor Link

Names starting with _ are not part of the interface for scripts.