This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Core.func Wiki

The foundational utility library providing colors, formatting, validation checks, message output, and execution helpers used across all Community-Scripts ecosystem projects.

Overview

Core.func provides essential utilities for consistent behavior across all Community-Scripts:

✅ ANSI color codes for styled terminal output
✅ Standard icons and formatting for UI consistency
✅ System validation checks (root, PVE version, architecture)
✅ Colored message functions (info, ok, error, warn)
✅ Silent command execution with log redirection
✅ Spinner animations for long-running operations
✅ Development mode support (trace, breakpoint, dry-run)
✅ Guard clauses to prevent reloading

Integration Pattern

#!/bin/bash
source <(curl -fsSL https://git.community-scripts.org/.../core.func)
load_functions     # Initialize all color/formatting/defaults
root_check         # Validate prerequisites
pve_check          # Check Proxmox VE version

Initialization Functions

`load_functions()`

Purpose: Initializes all core utility function groups. Must be called once before using any core utilities.

Signature:

load_functions()

Parameters: None

Returns: No explicit return value (sets global variables)

Guard Mechanism:

[[ -n "${__FUNCTIONS_LOADED:-}" ]] && return  # Prevent re-loading
_CORE_FUNC_LOADED=1  # Mark as loaded

Initializes (in order):

color() - ANSI color codes
formatting() - Text formatting helpers
icons() - Emoji/symbol constants
default_vars() - Retry and timeout settings
set_std_mode() - Verbose/silent mode

Usage Examples:

# Example 1: Typical initialization
source <(curl -fsSL .../core.func)
load_functions      # Safe to call multiple times
msg_info "Starting setup"  # Now colors are available

# Example 2: Safe multiple sourcing
source <(curl -fsSL .../core.func)
load_functions
source <(curl -fsSL .../tools.func)
load_functions      # Silently returns (already loaded)

`color()`

Purpose: Defines ANSI escape codes for colored terminal output.

Signature:

color()

Color Variables Defined:

Variable	Code	Effect	Use Case
`YW`	`\033[33m`	Yellow	Warnings, secondary info
`YWB`	`\e[93m`	Bright Yellow	Emphasis, bright warnings
`BL`	`\033[36m`	Cyan/Blue	Hostnames, IPs, values
`RD`	`\033[01;31m`	Bright Red	Errors, critical alerts
`GN`	`\033[1;92m`	Bright Green	Success, OK status
`DGN`	`\033[32m`	Dark Green	Background, secondary success
`BGN`	`\033[4;92m`	Green with underline	Highlights
`CL`	`\033[m`	Clear	Reset to default

Usage Examples:

# Example 1: Colored output
color
echo -e "${RD}Error: File not found${CL}"
# Output: "Error: File not found" (in red)

# Example 2: Multiple colors on one line
echo -e "${YW}Warning:${CL} ${BL}$HOSTNAME${CL} is running low on ${RD}RAM${CL}"

# Example 3: In functions
print_status() {
  echo -e "${GN}✓${CL} Operation completed"
}

`formatting()`

Purpose: Defines formatting helpers for terminal output.

Signature:

formatting()

Formatting Variables Defined:

Variable	Escape Code	Purpose
`BFR`	`\r\033[K`	Backspace and clear line
`BOLD`	`\033[1m`	Bold text
`HOLD`	(space)	Spacing
`TAB`	(2 spaces)	Indentation
`TAB3`	(6 spaces)	Larger indentation

Usage Examples:

# Example 1: Overwrite previous line (progress)
for i in {1..10}; do
  echo -en "${BFR}Progress: $i/10"
  sleep 1
done

# Example 2: Bold emphasis
echo -e "${BOLD}Important:${CL} This requires attention"

# Example 3: Structured indentation
echo "Main Item:"
echo -e "${TAB}Sub-item 1"
echo -e "${TAB}Sub-item 2"

`icons()`

Purpose: Defines symbolic emoji and icon constants used for UI consistency.

Signature:

icons()

Icon Variables Defined:

Variable	Icon	Use
`CM`	✔️	Success/checkmark
`CROSS`	✖️	Error/cross
`INFO`	💡	Information
`OS`	🖥️	Operating system
`CONTAINERTYPE`	📦	Container
`DISKSIZE`	💾	Disk/storage
`CPUCORE`	🧠	CPU
`RAMSIZE`	🛠️	RAM
`HOSTNAME`	🏠	Hostname
`BRIDGE`	🌉	Network bridge
`NETWORK`	📡	Network
`GATEWAY`	🌐	Gateway
`CREATING`	🚀	Creating
`ADVANCED`	🧩	Advanced/options
`HOURGLASS`	⏳	Wait/timer

`default_vars()`

Purpose: Sets default retry and timing variables for system operations.

Signature:

default_vars()

Variables Set:

RETRY_NUM=10 - Maximum retry attempts
RETRY_EVERY=3 - Seconds between retries
i=$RETRY_NUM - Counter for retry loops

Usage Examples:

# Example 1: Retry loop with defaults
RETRY_NUM=10
RETRY_EVERY=3
i=$RETRY_NUM
while [ $i -gt 0 ]; do
  if check_network; then
    break
  fi
  echo "Retrying... ($i attempts left)"
  sleep $RETRY_EVERY
  i=$((i - 1))
done

# Example 2: Custom retry values
RETRY_NUM=5  # Try 5 times
RETRY_EVERY=2  # Wait 2 seconds between attempts

`set_std_mode()`

Purpose: Configures output verbosity and optional debug tracing based on environment variables.

Signature:

set_std_mode()

Behavior:

If VERBOSE=yes: STD="" (show all output)
If VERBOSE=no: STD="silent" (suppress output via silent() wrapper)
If DEV_MODE_TRACE=true: Enable set -x bash tracing

Variables Set:

STD - Command prefix for optional output suppression

Usage Examples:

# Example 1: Verbose output
VERBOSE="yes"
set_std_mode
$STD apt-get update  # Shows all apt output
# Output: All package manager messages displayed

# Example 2: Silent output
VERBOSE="no"
set_std_mode
$STD apt-get update  # Silently updates, logs to file
# Output: Only progress bar or errors shown

# Example 3: Debug tracing
DEV_MODE_TRACE="true"
set_std_mode
# bash shows every command before executing: +(script.sh:123): function_name(): cmd

`parse_dev_mode()`

Purpose: Parses comma-separated dev_mode string to enable development features.

Signature:

parse_dev_mode()

Parameters: None (uses $dev_mode environment variable)

Supported Flags:

motd - Setup SSH/MOTD before installation
keep - Never delete container on failure
trace - Enable bash set -x tracing
pause - Pause after each msg_info step
breakpoint - Open shell on error instead of cleanup
logs - Persist logs to /var/log/community-scripts/
dryrun - Show commands without executing

Environment Variables Set:

DEV_MODE_MOTD=false|true
DEV_MODE_KEEP=false|true
DEV_MODE_TRACE=false|true
DEV_MODE_PAUSE=false|true
DEV_MODE_BREAKPOINT=false|true
DEV_MODE_LOGS=false|true
DEV_MODE_DRYRUN=false|true

Usage Examples:

# Example 1: Enable debugging
dev_mode="trace,logs"
parse_dev_mode
# Enables bash tracing and persistent logging

# Example 2: Keep container on error
dev_mode="keep,breakpoint"
parse_dev_mode
# Container never deleted on error, opens shell at breakpoint

# Example 3: Multiple modes
dev_mode="motd,keep,trace,pause"
parse_dev_mode
# All four development modes active

Color & Formatting

Color Codes

Standard Colors:

${YW}   # Yellow (warnings)
${RD}   # Red (errors)
${GN}   # Green (success)
${BL}   # Blue/Cyan (values)
${CL}   # Clear (reset)

Example Combinations:

echo -e "${YW}Warning:${CL} ${RD}Critical${CL} at ${BL}$(date)${CL}"
# Output: "Warning: Critical at 2024-12-01 10:30:00" (colored appropriately)

Validation Checks

`shell_check()`

Purpose: Verifies script is running under Bash (not sh, dash, etc.).

Signature:

shell_check()

Parameters: None

Returns: 0 if Bash; exits with error if not

Behavior:

Checks ps -p $$ -o comm= (current shell command)
Exits with error message if not "bash"
Clears screen for better error visibility

Usage Examples:

#!/bin/bash
source <(curl -fsSL .../core.func)
load_functions
shell_check  # Exits if run with: sh script.sh or dash script.sh

# If run correctly: bash script.sh - continues
# If run with sh: Displays error and exits

`root_check()`

Purpose: Verifies script is running with root privileges directly (not via sudo).

Signature:

root_check()

Parameters: None

Returns: 0 if root directly; exits with error if not

Checks:

id -u must be 0 (root)
Parent process ($PPID) must not be "sudo"

Why: Some scripts require genuine root context, not sudo-elevated user shell.

Usage Examples:

#!/bin/bash
# Must run as root directly, not via sudo
source <(curl -fsSL .../core.func)
load_functions
root_check  # Will fail if: sudo bash script.sh

# Correct: bash script.sh (from root shell on Proxmox)

`pve_check()`

Purpose: Validates Proxmox VE version compatibility.

Signature:

pve_check()

Parameters: None

Returns: 0 if supported version; exits with error if not

Supported Versions:

PVE 8.0 - 8.9
PVE 9.0 - 9.1

Version Detection:

PVE_VER=$(pveversion | awk -F'/' '{print $2}' | awk -F'-' '{print $1}')
# Example: "pveversion" → "pve-manager/8.2.2/550e8400-e29b"
#          Extracted: "8.2.2" → "8"

Usage Examples:

# Example 1: On supported PVE 8.2
bash ct/app.sh
# Passes: 8.2 is in range 8.0-8.9

# Example 2: On unsupported PVE 7.4
bash ct/app.sh
# Error: "This version of Proxmox VE is not supported"

# Example 3: On future unsupported PVE 10.0
bash ct/app.sh
# Error: "This version of Proxmox VE is not yet supported"

`arch_check()`

Purpose: Validates system architecture is amd64/x86_64 (not ARM/PiMox).

Signature:

arch_check()

Parameters: None

Returns: 0 if amd64; exits with error if not

Behavior:

Checks dpkg --print-architecture
Exits if not "amd64"
Provides link to ARM64-compatible scripts

Usage Examples:

# Example 1: On x86_64 server
arch_check
# Passes silently

# Example 2: On PiMox (ARM64)
arch_check
# Error: "This script will not work with PiMox!"
# Suggests: https://github.com/asylumexp/Proxmox

`ssh_check()`

Purpose: Detects SSH connection and warns if connecting remotely (recommends Proxmox console).

Signature:

ssh_check()

Parameters: None

Returns: No explicit return value (warning only, does not exit)

Behavior:

Checks $SSH_CLIENT environment variable
Analyzes client IP to determine if local or remote
Skips warning for local/same-subnet connections
Warns for external connections

Usage Examples:

# Example 1: Local SSH (Proxmox WebUI console)
ssh_check
# No warning: Client is localhost (127.0.0.1)

# Example 2: External SSH over Internet
ssh -l root 1.2.3.4 "bash script.sh"
# Warning: "Running via external SSH (client: 1.2.3.4)"
# Recommends Proxmox Shell (Console) instead

Message Output Functions

`msg_info()`

Purpose: Displays informational message with icon and yellow color.

Signature:

msg_info()

Parameters:

$@ - Message text (concatenated with spaces)

Format: [ℹ️] Message text (yellow)

Usage Examples:

msg_info "Starting container setup"
# Output: ℹ️  Starting container setup

msg_info "Updating OS packages" "for debian:12"
# Output: ℹ️  Updating OS packages for debian:12

`msg_ok()`

Purpose: Displays success message with checkmark and green color.

Signature:

msg_ok()

Parameters:

$@ - Message text

Format: [✔️] Message text (green)

Usage Examples:

msg_ok "Container created"
# Output: ✔️  Container created (in green)

msg_ok "Network Connected: 10.0.3.50"
# Output: ✔️  Network Connected: 10.0.3.50

`msg_error()`

Purpose: Displays error message with cross icon and red color. Does not exit.

Signature:

msg_error()

Parameters:

$@ - Message text

Format: [✖️] Message text (red)

Usage Examples:

msg_error "Container ID already in use"
# Output: ✖️  Container ID already in use (in red)

`msg_warn()`

Purpose: Displays warning message with yellow color.

Signature:

msg_warn()

Parameters:

$@ - Message text

Format: [⚠️] Message text (yellow/orange)

Usage Examples:

msg_warn "This will delete all data"
# Output: ⚠️  This will delete all data

Execution Helpers

`silent()`

Purpose: Executes command with output redirected to log file. On error: displays last 10 lines of log and exits.

Signature:

silent()

Parameters:

$@ - Command and arguments to execute

Returns: 0 on success; exits with original error code on failure

Environment Effects:

Temporarily disables set -e and error trap to capture exit code
Re-enables after command completes
Logs to $BUILD_LOG or $INSTALL_LOG

Log Display On Error:

--- Last 10 lines of silent log ---
[log output]
-----------------------------------

Usage Examples:

# Example 1: Suppress package manager output
silent apt-get update
# Output: suppressed, logged to file

# Example 2: Conditional display on error
silent curl -fsSL https://api.example.com
# If curl fails: shows last 10 log lines and exits

# Example 3: Verbose mode shows everything
VERBOSE="yes"
silent apt-get update  # Shows all output (STD is empty)

`spinner()`

Purpose: Displays animated spinner with rotating characters during long operations.

Signature:

spinner()

Parameters: None (uses $SPINNER_MSG environment variable)

Animation:

⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏ (repeating)

Environment Variables:

SPINNER_MSG - Text to display with spinner

Lifecycle:

# Start spinner in background
SPINNER_MSG="Downloading..."
spinner &
SPINNER_PID=$!

# ... do long operation ...

# Stop spinner
stop_spinner

echo "Done!"

Usage Examples:

# Example 1: Long operation with spinner
SPINNER_MSG="Building container..."
spinner &
SPINNER_PID=$!

sleep 10  # Simulate work

stop_spinner
msg_ok "Container created"

`clear_line()`

Purpose: Clears current terminal line and moves cursor to beginning.

Signature:

clear_line()

Parameters: None

Implementation: Uses tput or ANSI escape codes

Usage Examples:

for file in *.sh; do
  echo -n "Processing $file..."
  process_file "$file"
  clear_line
done
# Each file overwrites previous line

`stop_spinner()`

Purpose: Stops running spinner process and cleans up temporary files.

Signature:

stop_spinner()

Parameters: None (reads $SPINNER_PID or /tmp/.spinner.pid)

Cleanup:

Graceful kill of spinner process
Force kill (-9) if needed
Removes /tmp/.spinner.pid temp file
Resets terminal state

Usage Examples:

# Example 1: Simple stop
spinner &
SPINNER_PID=$!
sleep 5
stop_spinner

# Example 2: In trap handler
trap 'stop_spinner' EXIT
spinner &

Development Mode

Enabling Development Features

Via Environment Variable:

dev_mode="trace,keep,breakpoint" bash ct/myapp.sh

Via Script Header:

#!/bin/bash
export dev_mode="trace,logs,pause"
source <(curl -fsSL .../core.func)
load_functions
parse_dev_mode

Available Modes

Mode	Effect
`trace`	Enable bash -x tracing (verbose command logging)
`keep`	Never delete container on error (for debugging)
`logs`	Persist all logs to /var/log/community-scripts/
`pause`	Pause after each msg_info step (manual stepping)
`breakpoint`	Open shell on error instead of immediate cleanup
`motd`	Configure SSH/MOTD before installation starts
`dryrun`	Show commands without executing them

Best Practices

1. Always Call load_functions() First

#!/bin/bash
set -Eeuo pipefail

source <(curl -fsSL .../core.func)
load_functions  # MUST be before using any color variables

msg_info "Starting setup"  # Now safe to use

2. Use Message Functions Consistently

msg_info "Starting step"
# Do work...
msg_ok "Step completed"

# Or on error:
if ! command; then
  msg_error "Command failed"
  exit 1
fi

3. Combine Validation Checks

#!/bin/bash
source <(curl -fsSL .../core.func)
load_functions

shell_check   # Exits if wrong shell
root_check    # Exits if not root
pve_check     # Exits if unsupported version
arch_check    # Exits if wrong architecture

# All checks passed, safe to proceed
msg_ok "Pre-flight checks passed"

4. Use Verbose Mode for Debugging

VERBOSE="yes" bash ct/myapp.sh
# Shows all silent() command output for troubleshooting

5. Log Important Operations

silent apt-get update        # Suppress unless error
msg_ok "Packages updated"    # Show success
silent systemctl start nginx # Suppress unless error
msg_ok "Nginx started"       # Show success

Contributing

Adding New Message Functions

Follow existing pattern:

msg_custom() {
  local icon="$1"
  local color="$2"
  local message="$3"
  echo -e "${TAB}${icon}${TAB}${color}${message}${CL}"
}

Adding Color Support

New colors should follow semantic naming:

BG_ERROR=$'\e[41m'   # Red background for errors
BG_SUCCESS=$'\e[42m' # Green background for success

Testing Color Output

bash
source <(curl -fsSL .../core.func)
load_functions

echo -e "${YW}Yellow${CL} ${RD}Red${CL} ${GN}Green${CL} ${BL}Blue${CL}"

Notes

Core.func is designed to be sourced once and loaded everywhere
All color variables are ANSI escape codes (work in all terminals)
Messages use emoji icons for visual consistency
Validation checks use standard exit codes (0 for success, 1 for error)
The module is lightweight and loads instantly