ProxmoxVE/docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md

tools.func Functions Reference

Complete alphabetical reference of all functions in tools.func with parameters, usage, and examples.

Function Index

Package Management

• pkg_install() - Install packages safely with retry
• pkg_update() - Update package lists with retry
• pkg_remove() - Remove packages cleanly

Repository Management

• setup_deb822_repo() - Add repository in modern deb822 format
• cleanup_repo_metadata() - Clean GPG keys and old repositories
• check_repository() - Verify repository accessibility

Tool Installation Functions (30+)

Programming Languages:

• setup_nodejs(VERSION) - Install Node.js and npm
• setup_php(VERSION) - Install PHP-FPM and CLI
• setup_python(VERSION) - Install Python 3 with pip
• setup_ruby(VERSION) - Install Ruby with gem
• setup_golang(VERSION) - Install Go programming language

Databases:

• setup_mariadb() - Install MariaDB server (distro packages by default)
• setup_postgresql(VERSION) - Install PostgreSQL
• setup_mongodb(VERSION) - Install MongoDB
• setup_redis(VERSION) - Install Redis cache

Web Servers:

• setup_nginx() - Install Nginx
• setup_apache() - Install Apache HTTP Server
• setup_caddy() - Install Caddy
• setup_traefik() - Install Traefik proxy

Containers:

• setup_docker() - Install Docker
• setup_podman() - Install Podman

Development:

• setup_git() - Install Git
• setup_docker_compose() - Install Docker Compose
• setup_composer() - Install PHP Composer
• setup_build_tools() - Install build-essential

Monitoring:

• setup_grafana() - Install Grafana
• setup_prometheus() - Install Prometheus
• setup_telegraf() - Install Telegraf

System:

• setup_wireguard() - Install WireGuard VPN
• setup_netdata() - Install Netdata monitoring
• setup_tailscale() - Install Tailscale
• (+ more...)

---

Core Functions

install_packages_with_retry()

Install one or more packages safely with automatic retry logic (3 attempts), APT refresh, and lock handling.

Signature:

install_packages_with_retry PACKAGE1 [PACKAGE2 ...]

Parameters:

• PACKAGE1, PACKAGE2, ... - Package names to install

Returns:

• 0 - All packages installed successfully
• 1 - Installation failed after all retries

Features:

• Automatically sets DEBIAN_FRONTEND=noninteractive
• Handles DPKG lock errors with dpkg --configure -a
• Retries on transient network or APT failures

Example:

install_packages_with_retry curl wget git

---

upgrade_packages_with_retry()

Upgrades installed packages with the same robust retry logic as the installation helper.

Signature:

upgrade_packages_with_retry

Returns:

• 0 - Upgrade successful
• 1 - Upgrade failed

---

fetch_and_deploy_gh_release()

The primary tool for downloading and installing software from GitHub Releases. Supports binaries, tarballs, and Debian packages.

Signature:

fetch_and_deploy_gh_release APPREPO TYPE [VERSION] [DEST] [ASSET_PATTERN]

Parameters:

• APPREPO: GitHub repository (e.g., owner/repo)
• TYPE: Asset type (binary, tarball, prebuild, singlefile, binary_tarball)
• VERSION: Specific tag or latest (Default: latest)
• DEST: Target directory (Default: /opt/$APP)
• ASSET_PATTERN: Regex or string pattern to match the release asset

Environment Variables:

• CLEAN_INSTALL=1: Removes the destination directory before extracting.

Example:

fetch_and_deploy_gh_release "muesli/duf" "binary" "latest" "/opt/duf" "duf_.*_linux_amd64.tar.gz"

---

check_for_gh_release()

Checks if a newer version is available on GitHub compared to the installed version.

Signature:

check_for_gh_release APP REPO

Example:

if check_for_gh_release "nodejs" "nodesource/distributions"; then
  # update logic
fi

---

prepare_repository_setup()

Performs safe repository preparation by cleaning up old files, keyrings, and ensuring the APT system is in a working state.

Signature:

prepare_repository_setup REPO_NAME [REPO_NAME2 ...]

Example:

prepare_repository_setup "mariadb" "mysql"

---

verify_tool_version()

Validates if the installed major version matches the expected version.

Signature:

verify_tool_version NAME EXPECTED INSTALLED

Example:

verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"

---

setup_deb822_repo()

Add repository in modern deb822 format.

Signature:

setup_deb822_repo NAME GPG_URL REPO_URL SUITE COMPONENT [ARCHITECTURES] [ENABLED]

Parameters:

• NAME - Repository name (e.g., "nodejs")
• GPG_URL - URL to GPG key (e.g., https://example.com/key.gpg)
• REPO_URL - Main repository URL (e.g., https://example.com/repo)
• SUITE - Repository suite (e.g., "jammy", "bookworm")
• COMPONENT - Repository component (e.g., "main", "testing")
• ARCHITECTURES - Optional Comma-separated list of architectures (e.g., "amd64,arm64")
• ENABLED - Optional "true" or "false" (default: "true")

Returns:

• 0 - Repository added successfully
• 1 - Repository setup failed

Example:

setup_deb822_repo \
  "nodejs" \
  "https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
  "https://deb.nodesource.com/node_20.x" \  
  "jammy" \
  "main"

---

cleanup_repo_metadata()

Clean up GPG keys and old repository configurations.

Signature:

cleanup_repo_metadata

Parameters: None

Returns:

• 0 - Cleanup complete

Example:

cleanup_repo_metadata
>>>>>>> origin/main

---

Tool Installation Functions

setup_nodejs(VERSION)

Install Node.js and npm from official repositories.

Signature:

setup_nodejs VERSION

Parameters:

• VERSION - Node.js version (e.g., "20", "22", "lts")

Returns:

• 0 - Installation successful
• 1 - Installation failed

Creates:

• /opt/nodejs_version.txt - Version file

Example:

setup_nodejs "20"

---

setup_php(VERSION)

Install PHP-FPM, CLI, and common extensions.

Signature:

setup_php VERSION

Parameters:

• VERSION - PHP version (e.g., "8.2", "8.3")

Returns:

• 0 - Installation successful
• 1 - Installation failed

Creates:

• /opt/php_version.txt - Version file

Example:

setup_php "8.3"

---

setup_mariadb()

Install MariaDB server and client utilities.

Signature:

setup_mariadb                         # Uses distribution packages (recommended)
MARIADB_VERSION="11.4" setup_mariadb  # Uses official MariaDB repository

Variables:

• MARIADB_VERSION - (optional) Specific MariaDB version
  • Not set or "latest": Uses distribution packages (most reliable, avoids mirror issues)
  • Specific version (e.g., "11.4", "12.2"): Uses official MariaDB repository

Returns:

• 0 - Installation successful
• 1 - Installation failed

Creates:

• /opt/mariadb_version.txt - Version file

Example:

# Recommended: Use distribution packages (stable, no mirror issues)
setup_mariadb

# Specific version from official repository
MARIADB_VERSION="11.4" setup_mariadb

---

setup_postgresql(VERSION)

Install PostgreSQL server and client utilities.

Signature:

setup_postgresql VERSION

Parameters:

• VERSION - PostgreSQL version (e.g., "14", "15", "16")

Returns:

• 0 - Installation successful
• 1 - Installation failed

Creates:

• /opt/postgresql_version.txt - Version file

Example:

setup_postgresql "16"

---

setup_docker()

Install Docker and Docker CLI.

Signature:

setup_docker

Parameters: None

Returns:

• 0 - Installation successful
• 1 - Installation failed

Creates:

• /opt/docker_version.txt - Version file

Example:

setup_docker

---

setup_composer()

Install PHP Composer (dependency manager).

Signature:

setup_composer

Parameters: None

Returns:

• 0 - Installation successful
• 1 - Installation failed

Creates:

• /usr/local/bin/composer - Composer executable

Example:

setup_composer

---

setup_build_tools()

Install build-essential and development tools (gcc, make, etc.).

Signature:

setup_build_tools

Parameters: None

Returns:

• 0 - Installation successful
• 1 - Installation failed

Example:

setup_build_tools

---

System Configuration

setting_up_container()

Display setup message and initialize container environment.

Signature:

setting_up_container

Example:

setting_up_container
# Output: ⏳ Setting up container...

---

motd_ssh()

Configure SSH daemon and MOTD for container.

Signature:

motd_ssh

Example:

motd_ssh
# Configures SSH and creates MOTD

---

customize()

Apply container customizations and final setup.

Signature:

customize

Example:

customize

---

cleanup_lxc()

Final cleanup of temporary files and logs.

Signature:

cleanup_lxc

Example:

cleanup_lxc
# Removes temp files, finalizes installation

---

Usage Patterns

Basic Installation Sequence

#!/usr/bin/env bash
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"

pkg_update                    # Update package lists
setup_nodejs "20"             # Install Node.js
setup_mariadb                 # Install MariaDB (distribution packages)

# ... application installation ...

motd_ssh                      # Setup SSH/MOTD
customize                     # Apply customizations
cleanup_lxc                   # Final cleanup

Tool Chain Installation

#!/usr/bin/env bash
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"

# Install full web stack
pkg_update
setup_nginx
setup_php "8.3"
setup_mariadb  # Uses distribution packages
setup_composer

With Repository Setup

#!/usr/bin/env bash
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"

pkg_update

# Add Node.js repository
setup_deb822_repo \
  "https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
  "nodejs" \
  "jammy" \
  "https://deb.nodesource.com/node_20.x" \
  "main"

pkg_update
setup_nodejs "20"

---

Last Updated: December 2025 Total Functions: 30+ Maintained by: community-scripts team