mirror of
https://github.com/community-scripts/ProxmoxVED.git
synced 2026-02-25 05:57:26 +00:00
Add docs for all files in /misc
This commit is contained in:
Michel Roegl-Brunner
637
docs/misc/core.func/CORE_FUNCTIONS_REFERENCE.md
Normal file
637
docs/misc/core.func/CORE_FUNCTIONS_REFERENCE.md
Normal file
@@ -0,0 +1,637 @@
|
||||
# core.func Functions Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive alphabetical reference of all functions in `core.func`, including parameters, dependencies, usage examples, and error handling.
|
||||
|
||||
## Function Categories
|
||||
|
||||
### Initialization Functions
|
||||
|
||||
#### `load_functions()`
|
||||
**Purpose**: Main function loader that initializes all core utilities
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Sets `__FUNCTIONS_LOADED=1` to prevent reloading
|
||||
- Calls all core function groups in sequence
|
||||
- Initializes color, formatting, icons, defaults, and standard mode
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `__FUNCTIONS_LOADED`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
# Automatically called when core.func is sourced
|
||||
source core.func
|
||||
# load_functions() is called automatically
|
||||
```
|
||||
|
||||
### Color and Formatting Functions
|
||||
|
||||
#### `color()`
|
||||
**Purpose**: Set ANSI color codes for styled terminal output
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets global color variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `YW`: Yellow
|
||||
- `YWB`: Bright yellow
|
||||
- `BL`: Blue
|
||||
- `RD`: Red
|
||||
- `BGN`: Bright green
|
||||
- `GN`: Green
|
||||
- `DGN`: Dark green
|
||||
- `CL`: Clear/reset
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
color
|
||||
echo -e "${GN}Success message${CL}"
|
||||
echo -e "${RD}Error message${CL}"
|
||||
```
|
||||
|
||||
#### `color_spinner()`
|
||||
**Purpose**: Set color codes specifically for spinner output
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets spinner-specific color variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `CS_YW`: Yellow for spinner
|
||||
- `CS_YWB`: Bright yellow for spinner
|
||||
- `CS_CL`: Clear for spinner
|
||||
|
||||
#### `formatting()`
|
||||
**Purpose**: Define formatting helpers for terminal output
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets global formatting variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `BFR`: Back and forward reset
|
||||
- `BOLD`: Bold text
|
||||
- `HOLD`: Space character
|
||||
- `TAB`: Two spaces
|
||||
- `TAB3`: Six spaces
|
||||
|
||||
### Icon Functions
|
||||
|
||||
#### `icons()`
|
||||
**Purpose**: Set symbolic icons used throughout user feedback and prompts
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets global icon variables
|
||||
**Dependencies**: `formatting()` (for TAB variable)
|
||||
**Environment Variables Used**: `TAB`, `CL`
|
||||
|
||||
**Sets Variables**:
|
||||
- `CM`: Check mark
|
||||
- `CROSS`: Cross mark
|
||||
- `DNSOK`: DNS success
|
||||
- `DNSFAIL`: DNS failure
|
||||
- `INFO`: Information icon
|
||||
- `OS`: Operating system icon
|
||||
- `OSVERSION`: OS version icon
|
||||
- `CONTAINERTYPE`: Container type icon
|
||||
- `DISKSIZE`: Disk size icon
|
||||
- `CPUCORE`: CPU core icon
|
||||
- `RAMSIZE`: RAM size icon
|
||||
- `SEARCH`: Search icon
|
||||
- `VERBOSE_CROPPED`: Verbose mode icon
|
||||
- `VERIFYPW`: Password verification icon
|
||||
- `CONTAINERID`: Container ID icon
|
||||
- `HOSTNAME`: Hostname icon
|
||||
- `BRIDGE`: Bridge icon
|
||||
- `NETWORK`: Network icon
|
||||
- `GATEWAY`: Gateway icon
|
||||
- `DISABLEIPV6`: IPv6 disable icon
|
||||
- `DEFAULT`: Default settings icon
|
||||
- `MACADDRESS`: MAC address icon
|
||||
- `VLANTAG`: VLAN tag icon
|
||||
- `ROOTSSH`: SSH key icon
|
||||
- `CREATING`: Creating icon
|
||||
- `ADVANCED`: Advanced settings icon
|
||||
- `FUSE`: FUSE icon
|
||||
- `HOURGLASS`: Hourglass icon
|
||||
|
||||
### Default Variables Functions
|
||||
|
||||
#### `default_vars()`
|
||||
**Purpose**: Set default retry and wait variables for system actions
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets retry configuration variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `RETRY_NUM`: Number of retry attempts (default: 10)
|
||||
- `RETRY_EVERY`: Seconds between retries (default: 3)
|
||||
- `i`: Retry counter initialized to RETRY_NUM
|
||||
|
||||
#### `set_std_mode()`
|
||||
**Purpose**: Set default verbose mode for script execution
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets STD variable based on VERBOSE setting
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `VERBOSE`
|
||||
|
||||
**Sets Variables**:
|
||||
- `STD`: "silent" if VERBOSE != "yes", empty string if VERBOSE = "yes"
|
||||
|
||||
### Silent Execution Functions
|
||||
|
||||
#### `silent()`
|
||||
**Purpose**: Execute commands silently with detailed error reporting
|
||||
**Parameters**: `$*` - Command and arguments to execute
|
||||
**Returns**: None (exits on error)
|
||||
**Side Effects**:
|
||||
- Executes command with output redirected to log file
|
||||
- On error, displays detailed error information
|
||||
- Exits with command's exit code
|
||||
**Dependencies**: `error_handler.func` (for error explanations)
|
||||
**Environment Variables Used**: `SILENT_LOGFILE`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
silent apt-get update
|
||||
silent apt-get install -y package-name
|
||||
```
|
||||
|
||||
**Error Handling**:
|
||||
- Captures command output to `/tmp/silent.$$.log`
|
||||
- Shows error code explanation
|
||||
- Displays last 10 lines of log
|
||||
- Provides command to view full log
|
||||
|
||||
### System Check Functions
|
||||
|
||||
#### `shell_check()`
|
||||
**Purpose**: Verify that the script is running in Bash shell
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if not Bash)
|
||||
**Side Effects**:
|
||||
- Checks current shell process
|
||||
- Exits with error message if not Bash
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
shell_check
|
||||
# Script continues if Bash, exits if not
|
||||
```
|
||||
|
||||
#### `root_check()`
|
||||
**Purpose**: Ensure script is running as root user
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if not root)
|
||||
**Side Effects**:
|
||||
- Checks user ID and parent process
|
||||
- Exits with error message if not root
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
root_check
|
||||
# Script continues if root, exits if not
|
||||
```
|
||||
|
||||
#### `pve_check()`
|
||||
**Purpose**: Verify Proxmox VE version compatibility
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if unsupported version)
|
||||
**Side Effects**:
|
||||
- Checks PVE version using pveversion command
|
||||
- Exits with error message if unsupported
|
||||
**Dependencies**: `pveversion` command
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Supported Versions**:
|
||||
- Proxmox VE 8.0 - 8.9
|
||||
- Proxmox VE 9.0 (only)
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
pve_check
|
||||
# Script continues if supported version, exits if not
|
||||
```
|
||||
|
||||
#### `arch_check()`
|
||||
**Purpose**: Verify system architecture is AMD64
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if not AMD64)
|
||||
**Side Effects**:
|
||||
- Checks system architecture
|
||||
- Exits with PiMox warning if not AMD64
|
||||
**Dependencies**: `dpkg` command
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
arch_check
|
||||
# Script continues if AMD64, exits if not
|
||||
```
|
||||
|
||||
#### `ssh_check()`
|
||||
**Purpose**: Detect and warn about external SSH usage
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Checks SSH_CLIENT environment variable
|
||||
- Warns if connecting from external IP
|
||||
- Allows local connections (127.0.0.1 or host IP)
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `SSH_CLIENT`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
ssh_check
|
||||
# Shows warning if external SSH, continues anyway
|
||||
```
|
||||
|
||||
### Header Management Functions
|
||||
|
||||
#### `get_header()`
|
||||
**Purpose**: Download and cache application header files
|
||||
**Parameters**: None (uses APP and APP_TYPE variables)
|
||||
**Returns**: Header content on success, empty on failure
|
||||
**Side Effects**:
|
||||
- Downloads header from remote URL
|
||||
- Caches header locally
|
||||
- Creates directory structure if needed
|
||||
**Dependencies**: `curl` command
|
||||
**Environment Variables Used**: `APP`, `APP_TYPE`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
export APP="plex"
|
||||
export APP_TYPE="ct"
|
||||
header_content=$(get_header)
|
||||
```
|
||||
|
||||
#### `header_info()`
|
||||
**Purpose**: Display application header information
|
||||
**Parameters**: None (uses APP variable)
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Clears screen
|
||||
- Displays header content
|
||||
- Gets terminal width for formatting
|
||||
**Dependencies**: `get_header()`, `tput` command
|
||||
**Environment Variables Used**: `APP`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
export APP="plex"
|
||||
header_info
|
||||
# Displays Plex header information
|
||||
```
|
||||
|
||||
### Utility Functions
|
||||
|
||||
#### `ensure_tput()`
|
||||
**Purpose**: Ensure tput command is available for terminal control
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Installs ncurses package if tput missing
|
||||
- Works on Alpine and Debian-based systems
|
||||
**Dependencies**: `apk` or `apt-get` package managers
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
ensure_tput
|
||||
# Installs ncurses if needed, continues if already available
|
||||
```
|
||||
|
||||
#### `is_alpine()`
|
||||
**Purpose**: Detect if running on Alpine Linux
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if Alpine, 1 if not Alpine
|
||||
**Side Effects**: None
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `var_os`, `PCT_OSTYPE`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
if is_alpine; then
|
||||
echo "Running on Alpine Linux"
|
||||
else
|
||||
echo "Not running on Alpine Linux"
|
||||
fi
|
||||
```
|
||||
|
||||
#### `is_verbose_mode()`
|
||||
**Purpose**: Check if verbose mode is enabled
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if verbose mode, 1 if not verbose
|
||||
**Side Effects**: None
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `VERBOSE`, `var_verbose`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
if is_verbose_mode; then
|
||||
echo "Verbose mode enabled"
|
||||
else
|
||||
echo "Verbose mode disabled"
|
||||
fi
|
||||
```
|
||||
|
||||
#### `fatal()`
|
||||
**Purpose**: Display fatal error and terminate script
|
||||
**Parameters**: `$1` - Error message
|
||||
**Returns**: None (terminates script)
|
||||
**Side Effects**:
|
||||
- Displays error message
|
||||
- Sends INT signal to current process
|
||||
**Dependencies**: `msg_error()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
fatal "Critical error occurred"
|
||||
# Script terminates after displaying error
|
||||
```
|
||||
|
||||
### Spinner Functions
|
||||
|
||||
#### `spinner()`
|
||||
**Purpose**: Display animated spinner for progress indication
|
||||
**Parameters**: None (uses SPINNER_MSG variable)
|
||||
**Returns**: None (runs indefinitely)
|
||||
**Side Effects**:
|
||||
- Displays rotating spinner characters
|
||||
- Uses terminal control sequences
|
||||
**Dependencies**: `color_spinner()`
|
||||
**Environment Variables Used**: `SPINNER_MSG`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
SPINNER_MSG="Processing..."
|
||||
spinner &
|
||||
SPINNER_PID=$!
|
||||
# Spinner runs in background
|
||||
```
|
||||
|
||||
#### `clear_line()`
|
||||
**Purpose**: Clear current terminal line
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Clears current line using terminal control
|
||||
**Dependencies**: `tput` command
|
||||
**Environment Variables Used**: None
|
||||
|
||||
#### `stop_spinner()`
|
||||
**Purpose**: Stop running spinner and cleanup
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Kills spinner process
|
||||
- Removes PID file
|
||||
- Resets terminal settings
|
||||
- Unsets spinner variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `SPINNER_PID`, `SPINNER_MSG`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
stop_spinner
|
||||
# Stops spinner and cleans up
|
||||
```
|
||||
|
||||
### Message Functions
|
||||
|
||||
#### `msg_info()`
|
||||
**Purpose**: Display informational message with spinner
|
||||
**Parameters**: `$1` - Message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Starts spinner if not in verbose mode
|
||||
- Tracks shown messages to prevent duplicates
|
||||
- Displays message with hourglass icon in verbose mode
|
||||
**Dependencies**: `spinner()`, `is_verbose_mode()`, `is_alpine()`
|
||||
**Environment Variables Used**: `MSG_INFO_SHOWN`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_info "Installing package..."
|
||||
# Shows spinner with message
|
||||
```
|
||||
|
||||
#### `msg_ok()`
|
||||
**Purpose**: Display success message
|
||||
**Parameters**: `$1` - Success message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays green checkmark with message
|
||||
- Removes message from shown tracking
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: `MSG_INFO_SHOWN`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_ok "Package installed successfully"
|
||||
# Shows green checkmark with message
|
||||
```
|
||||
|
||||
#### `msg_error()`
|
||||
**Purpose**: Display error message
|
||||
**Parameters**: `$1` - Error message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays red cross with message
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_error "Installation failed"
|
||||
# Shows red cross with message
|
||||
```
|
||||
|
||||
#### `msg_warn()`
|
||||
**Purpose**: Display warning message
|
||||
**Parameters**: `$1` - Warning message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays yellow info icon with message
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_warn "This operation may take some time"
|
||||
# Shows yellow info icon with message
|
||||
```
|
||||
|
||||
#### `msg_custom()`
|
||||
**Purpose**: Display custom message with specified symbol and color
|
||||
**Parameters**:
|
||||
- `$1` - Custom symbol (default: "[*]")
|
||||
- `$2` - Color code (default: "\e[36m")
|
||||
- `$3` - Message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays custom formatted message
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_custom "⚡" "\e[33m" "Custom warning message"
|
||||
# Shows custom symbol and color with message
|
||||
```
|
||||
|
||||
#### `msg_debug()`
|
||||
**Purpose**: Display debug message if debug mode enabled
|
||||
**Parameters**: `$*` - Debug message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Only displays if var_full_verbose is set
|
||||
- Shows timestamp and debug prefix
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `var_full_verbose`, `var_verbose`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
export var_full_verbose=1
|
||||
msg_debug "Debug information here"
|
||||
# Shows debug message with timestamp
|
||||
```
|
||||
|
||||
### System Management Functions
|
||||
|
||||
#### `check_or_create_swap()`
|
||||
**Purpose**: Check for active swap and optionally create swap file
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if swap exists or created, 1 if skipped
|
||||
**Side Effects**:
|
||||
- Checks for active swap
|
||||
- Prompts user to create swap if none found
|
||||
- Creates swap file if user confirms
|
||||
**Dependencies**: `swapon`, `dd`, `mkswap` commands
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
if check_or_create_swap; then
|
||||
echo "Swap is available"
|
||||
else
|
||||
echo "No swap available"
|
||||
fi
|
||||
```
|
||||
|
||||
## Function Call Hierarchy
|
||||
|
||||
### Initialization Flow
|
||||
```
|
||||
load_functions()
|
||||
├── color()
|
||||
├── formatting()
|
||||
├── icons()
|
||||
├── default_vars()
|
||||
└── set_std_mode()
|
||||
```
|
||||
|
||||
### Message System Flow
|
||||
```
|
||||
msg_info()
|
||||
├── is_verbose_mode()
|
||||
├── is_alpine()
|
||||
├── spinner()
|
||||
└── color_spinner()
|
||||
|
||||
msg_ok()
|
||||
├── stop_spinner()
|
||||
└── clear_line()
|
||||
|
||||
msg_error()
|
||||
└── stop_spinner()
|
||||
|
||||
msg_warn()
|
||||
└── stop_spinner()
|
||||
```
|
||||
|
||||
### System Check Flow
|
||||
```
|
||||
pve_check()
|
||||
├── pveversion command
|
||||
└── version parsing
|
||||
|
||||
arch_check()
|
||||
├── dpkg command
|
||||
└── architecture check
|
||||
|
||||
shell_check()
|
||||
├── ps command
|
||||
└── shell detection
|
||||
|
||||
root_check()
|
||||
├── id command
|
||||
└── parent process check
|
||||
```
|
||||
|
||||
### Silent Execution Flow
|
||||
```
|
||||
silent()
|
||||
├── Command execution
|
||||
├── Output redirection
|
||||
├── Error handling
|
||||
├── error_handler.func loading
|
||||
└── Log management
|
||||
```
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### System Check Errors
|
||||
- All system check functions exit with appropriate error messages
|
||||
- Clear indication of what's wrong and how to fix it
|
||||
- Graceful exit with sleep delay for user to read message
|
||||
|
||||
### Silent Execution Errors
|
||||
- Commands executed via `silent()` capture output to log file
|
||||
- On failure, displays error code explanation
|
||||
- Shows last 10 lines of log output
|
||||
- Provides command to view full log
|
||||
|
||||
### Spinner Errors
|
||||
- Spinner functions handle process cleanup on exit
|
||||
- Trap handlers ensure spinners are stopped
|
||||
- Terminal settings are restored on error
|
||||
|
||||
## Environment Variable Dependencies
|
||||
|
||||
### Required Variables
|
||||
- `APP`: Application name for header display
|
||||
- `APP_TYPE`: Application type (ct/vm) for header paths
|
||||
- `VERBOSE`: Verbose mode setting
|
||||
|
||||
### Optional Variables
|
||||
- `var_os`: OS type for Alpine detection
|
||||
- `PCT_OSTYPE`: Alternative OS type variable
|
||||
- `var_verbose`: Alternative verbose setting
|
||||
- `var_full_verbose`: Debug mode setting
|
||||
|
||||
### Internal Variables
|
||||
- `_CORE_FUNC_LOADED`: Prevents multiple loading
|
||||
- `__FUNCTIONS_LOADED`: Prevents multiple function loading
|
||||
- `SILENT_LOGFILE`: Silent execution log file path
|
||||
- `SPINNER_PID`: Spinner process ID
|
||||
- `SPINNER_MSG`: Spinner message text
|
||||
- `MSG_INFO_SHOWN`: Tracks shown info messages
|
||||
Reference in New Issue
Block a user