c0fc74bc9c
Expanded inline documentation and section headers across misc/api.func, misc/build.func, misc/core.func, misc/error_handler.func, and misc/install.func for improved maintainability and clarity. Refactored error handling to use centralized explain_exit_code and updated API telemetry/reporting logic. Enhanced modularity and structure of utility, validation, and setup functions, and improved comments for user guidance and developer onboarding.
240 lines
7.1 KiB
Plaintext
240 lines
7.1 KiB
Plaintext
# Copyright (c) 2021-2025 community-scripts ORG
|
|
# Author: michelroegl-brunner
|
|
# License: MIT | https://git.community-scripts.org/community-scripts/ProxmoxVED/raw/branch/main/LICENSE
|
|
|
|
# ==============================================================================
|
|
# API.FUNC - TELEMETRY & DIAGNOSTICS API
|
|
# ==============================================================================
|
|
#
|
|
# Provides functions for sending anonymous telemetry data to Community-Scripts
|
|
# API for analytics and diagnostics purposes.
|
|
#
|
|
# Features:
|
|
# - Container/VM creation statistics
|
|
# - Installation success/failure tracking
|
|
# - Error code mapping and reporting
|
|
# - Privacy-respecting anonymous telemetry
|
|
#
|
|
# Usage:
|
|
# source <(curl -fsSL .../api.func)
|
|
# post_to_api # Report container creation
|
|
# post_update_to_api # Report installation status
|
|
#
|
|
# Privacy:
|
|
# - Only anonymous statistics (no personal data)
|
|
# - User can opt-out via diagnostics settings
|
|
# - Random UUID for session tracking only
|
|
#
|
|
# ==============================================================================
|
|
|
|
# ==============================================================================
|
|
# SECTION 1: DEPENDENCY LOADING
|
|
# ==============================================================================
|
|
|
|
# Load error_handler.func for explain_exit_code() function
|
|
# This provides centralized error code descriptions (exit codes 1-255, shell, package managers, databases, custom Proxmox codes)
|
|
if [[ -z "${COMMUNITY_SCRIPTS_BASE_URL:-}" ]]; then
|
|
COMMUNITY_SCRIPTS_BASE_URL="https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main"
|
|
fi
|
|
|
|
if ! declare -f explain_exit_code >/dev/null 2>&1; then
|
|
source <(curl -fsSL "${COMMUNITY_SCRIPTS_BASE_URL}/misc/error_handler.func") || {
|
|
echo "Failed to load error_handler.func" >&2
|
|
return 1
|
|
}
|
|
fi
|
|
|
|
# ==============================================================================
|
|
# SECTION 2: TELEMETRY FUNCTIONS
|
|
# ==============================================================================
|
|
|
|
# ------------------------------------------------------------------------------
|
|
# post_to_api()
|
|
#
|
|
# - Sends LXC container creation statistics to Community-Scripts API
|
|
# - Only executes if:
|
|
# * curl is available
|
|
# * DIAGNOSTICS=yes
|
|
# * RANDOM_UUID is set
|
|
# - Payload includes:
|
|
# * Container type, disk size, CPU cores, RAM
|
|
# * OS type and version
|
|
# * IPv6 disable status
|
|
# * Application name (NSAPP)
|
|
# * Installation method
|
|
# * PVE version
|
|
# * Status: "installing"
|
|
# * Random UUID for session tracking
|
|
# - Anonymous telemetry (no personal data)
|
|
# ------------------------------------------------------------------------------
|
|
post_to_api() {
|
|
|
|
if ! command -v curl &>/dev/null; then
|
|
return
|
|
fi
|
|
|
|
if [ "$DIAGNOSTICS" = "no" ]; then
|
|
return
|
|
fi
|
|
|
|
if [ -z "$RANDOM_UUID" ]; then
|
|
return
|
|
fi
|
|
|
|
local API_URL="http://api.community-scripts.org/dev/upload"
|
|
local pve_version="not found"
|
|
pve_version=$(pveversion | awk -F'[/ ]' '{print $2}')
|
|
|
|
JSON_PAYLOAD=$(
|
|
cat <<EOF
|
|
{
|
|
"ct_type": $CT_TYPE,
|
|
"type":"lxc",
|
|
"disk_size": $DISK_SIZE,
|
|
"core_count": $CORE_COUNT,
|
|
"ram_size": $RAM_SIZE,
|
|
"os_type": "$var_os",
|
|
"os_version": "$var_version",
|
|
"disableip6": "$DISABLEIP6",
|
|
"nsapp": "$NSAPP",
|
|
"method": "$METHOD",
|
|
"pve_version": "$pve_version",
|
|
"status": "installing",
|
|
"random_id": "$RANDOM_UUID"
|
|
}
|
|
EOF
|
|
)
|
|
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
|
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
|
-H "Content-Type: application/json" \
|
|
-d "$JSON_PAYLOAD") || true
|
|
fi
|
|
|
|
}
|
|
|
|
# ------------------------------------------------------------------------------
|
|
# post_to_api_vm()
|
|
#
|
|
# - Sends VM creation statistics to Community-Scripts API
|
|
# - Similar to post_to_api() but for virtual machines (not containers)
|
|
# - Reads DIAGNOSTICS from /usr/local/community-scripts/diagnostics file
|
|
# - Payload differences:
|
|
# * ct_type=2 (VM instead of LXC)
|
|
# * type="vm"
|
|
# * Disk size without 'G' suffix (parsed from DISK_SIZE variable)
|
|
# - Only executes if DIAGNOSTICS=yes and RANDOM_UUID is set
|
|
# ------------------------------------------------------------------------------
|
|
post_to_api_vm() {
|
|
|
|
if [[ ! -f /usr/local/community-scripts/diagnostics ]]; then
|
|
return
|
|
fi
|
|
DIAGNOSTICS=$(grep -i "^DIAGNOSTICS=" /usr/local/community-scripts/diagnostics | awk -F'=' '{print $2}')
|
|
if ! command -v curl &>/dev/null; then
|
|
return
|
|
fi
|
|
|
|
if [ "$DIAGNOSTICS" = "no" ]; then
|
|
return
|
|
fi
|
|
|
|
if [ -z "$RANDOM_UUID" ]; then
|
|
return
|
|
fi
|
|
|
|
local API_URL="http://api.community-scripts.org/dev/upload"
|
|
local pve_version="not found"
|
|
pve_version=$(pveversion | awk -F'[/ ]' '{print $2}')
|
|
|
|
DISK_SIZE_API=${DISK_SIZE%G}
|
|
|
|
JSON_PAYLOAD=$(
|
|
cat <<EOF
|
|
{
|
|
"ct_type": 2,
|
|
"type":"vm",
|
|
"disk_size": $DISK_SIZE_API,
|
|
"core_count": $CORE_COUNT,
|
|
"ram_size": $RAM_SIZE,
|
|
"os_type": "$var_os",
|
|
"os_version": "$var_version",
|
|
"disableip6": "",
|
|
"nsapp": "$NSAPP",
|
|
"method": "$METHOD",
|
|
"pve_version": "$pve_version",
|
|
"status": "installing",
|
|
"random_id": "$RANDOM_UUID"
|
|
}
|
|
EOF
|
|
)
|
|
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
|
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
|
-H "Content-Type: application/json" \
|
|
-d "$JSON_PAYLOAD") || true
|
|
fi
|
|
}
|
|
|
|
# ------------------------------------------------------------------------------
|
|
# post_update_to_api()
|
|
#
|
|
# - Reports installation completion status to API
|
|
# - Prevents duplicate submissions via POST_UPDATE_DONE flag
|
|
# - Arguments:
|
|
# * $1: status ("success" or "failed")
|
|
# * $2: exit_code (default: 1 for failed, 0 for success)
|
|
# - Payload includes:
|
|
# * Final status (success/failed)
|
|
# * Error description via get_error_description()
|
|
# * Random UUID for session correlation
|
|
# - Only executes once per session
|
|
# - Silently returns if:
|
|
# * curl not available
|
|
# * Already reported (POST_UPDATE_DONE=true)
|
|
# * DIAGNOSTICS=no
|
|
# ------------------------------------------------------------------------------
|
|
post_update_to_api() {
|
|
|
|
if ! command -v curl &>/dev/null; then
|
|
return
|
|
fi
|
|
|
|
if [ "$POST_UPDATE_DONE" = true ]; then
|
|
return 0
|
|
fi
|
|
exit_code=${2:-1}
|
|
local API_URL="http://api.community-scripts.org/dev/upload/updatestatus"
|
|
local status="${1:-failed}"
|
|
if [[ "$status" == "failed" ]]; then
|
|
local exit_code="${2:-1}"
|
|
elif [[ "$status" == "success" ]]; then
|
|
local exit_code="${2:-0}"
|
|
fi
|
|
|
|
if [[ -z "$exit_code" ]]; then
|
|
exit_code=1
|
|
fi
|
|
|
|
error=$(explain_exit_code "$exit_code")
|
|
|
|
if [ -z "$error" ]; then
|
|
error="Unknown error"
|
|
fi
|
|
|
|
JSON_PAYLOAD=$(
|
|
cat <<EOF
|
|
{
|
|
"status": "$status",
|
|
"error": "$error",
|
|
"random_id": "$RANDOM_UUID"
|
|
}
|
|
EOF
|
|
)
|
|
if [[ "$DIAGNOSTICS" == "yes" ]]; then
|
|
RESPONSE=$(curl -s -w "%{http_code}" -L -X POST "$API_URL" --post301 --post302 \
|
|
-H "Content-Type: application/json" \
|
|
-d "$JSON_PAYLOAD") || true
|
|
fi
|
|
|
|
POST_UPDATE_DONE=true
|
|
}
|