mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2025-12-16 20:23:32 +01:00
add comprehensive documentation (#9537)
This commit is contained in:
CanbiZ
347
docs/misc/error_handler.func/ERROR_HANDLER_FLOWCHART.md
Normal file
347
docs/misc/error_handler.func/ERROR_HANDLER_FLOWCHART.md
Normal file
@ -0,0 +1,347 @@
|
||||
# error_handler.func Execution Flowchart
|
||||
|
||||
## Main Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Handler Initialization │
|
||||
│ Entry point when error_handler.func is sourced by other scripts │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ CATCH_ERRORS() │
|
||||
│ Initialize error handling traps and strict mode │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Trap Setup Sequence │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ Set Strict │ │ Set Error │ │ Set Signal │ │
|
||||
│ │ Mode │ │ Trap │ │ Traps │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • -Ee │ │ • ERR trap │ │ • EXIT trap │ │
|
||||
│ │ • -o pipefail │ │ • error_handler │ │ • INT trap │ │
|
||||
│ │ • -u (if │ │ function │ │ • TERM trap │ │
|
||||
│ │ STRICT_UNSET) │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handler Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ERROR_HANDLER() Flow │
|
||||
│ Main error handler triggered by ERR trap or manual call │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Error Information Collection │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Get Exit │ │ Get Command │ │ Get Line │ │ │
|
||||
│ │ │ Code │ │ Information │ │ Number │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • From $? or │ │ • From │ │ • From │ │ │
|
||||
│ │ │ parameter │ │ BASH_COMMAND │ │ BASH_LINENO[0] │ │ │
|
||||
│ │ │ • Store in │ │ • Clean $STD │ │ • Default to │ │ │
|
||||
│ │ │ exit_code │ │ references │ │ "unknown" │ │ │
|
||||
│ │ │ │ │ • Store in │ │ • Store in │ │ │
|
||||
│ │ │ │ │ command │ │ line_number │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Success Check │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Exit Code Validation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Exit │ │ Success │ │ Error │ │
|
||||
│ │ │ Code │ │ Path │ │ Path │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • If exit_code │ │ • Return 0 │ │ • Continue to │ │
|
||||
│ │ │ == 0 │ │ • No error │ │ error handling │ │
|
||||
│ │ │ • Success │ │ processing │ │ • Process error │ │
|
||||
│ │ │ • No error │ │ │ │ information │ │
|
||||
│ │ │ handling │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Processing │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Error Explanation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Get Error │ │ Display Error │ │ Log Error │ │ │
|
||||
│ │ │ Explanation │ │ Information │ │ Information │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Call │ │ • Show error │ │ • Write to debug │ │
|
||||
│ │ │ explain_exit_ │ │ message │ │ log if enabled │ │
|
||||
│ │ │ code() │ │ • Show line │ │ • Include │ │
|
||||
│ │ │ • Get human- │ │ number │ │ timestamp │ │
|
||||
│ │ │ readable │ │ • Show command │ │ • Include exit │ │
|
||||
│ │ │ message │ │ • Show exit │ │ code │ │
|
||||
│ │ │ │ │ code │ │ • Include command │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Silent Log Integration │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Silent Log Display │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Silent │ │ Display Log │ │ Exit with │ │
|
||||
│ │ │ Log File │ │ Content │ │ Error Code │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Check if │ │ • Show last 20 │ │ • Exit with │ │
|
||||
│ │ │ SILENT_ │ │ lines │ │ original exit │ │
|
||||
│ │ │ LOGFILE set │ │ • Show file │ │ code │ │
|
||||
│ │ │ • Check if │ │ path │ │ • Terminate script │ │
|
||||
│ │ │ file exists │ │ • Format │ │ execution │ │
|
||||
│ │ │ • Check if │ │ output │ │ │ │
|
||||
│ │ │ file has │ │ │ │ │ │
|
||||
│ │ │ content │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Signal Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Signal Handler Flow │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Signal Detection │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ SIGINT │ │ SIGTERM │ │ EXIT │ │ │
|
||||
│ │ │ (Ctrl+C) │ │ (Termination) │ │ (Script End) │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • User │ │ • System │ │ • Normal script │ │
|
||||
│ │ │ interruption │ │ termination │ │ completion │ │
|
||||
│ │ │ • Graceful │ │ • Graceful │ │ • Error exit │ │
|
||||
│ │ │ handling │ │ handling │ │ • Signal exit │ │
|
||||
│ │ │ • Exit code │ │ • Exit code │ │ • Cleanup │ │
|
||||
│ │ │ 130 │ │ 143 │ │ operations │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ON_INTERRUPT() Flow │
|
||||
│ Handles SIGINT (Ctrl+C) signals │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Interrupt Processing │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ User Interruption Handling │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Display │ │ Cleanup │ │ Exit with │ │ │
|
||||
│ │ │ Message │ │ Operations │ │ Code 130 │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Show │ │ • Stop │ │ • Exit with │ │
|
||||
│ │ │ interruption │ │ processes │ │ SIGINT code │ │
|
||||
│ │ │ message │ │ • Clean up │ │ • Terminate script │ │
|
||||
│ │ │ • Use red │ │ temporary │ │ execution │ │
|
||||
│ │ │ color │ │ files │ │ │ │
|
||||
│ │ │ • Clear │ │ • Remove lock │ │ │ │
|
||||
│ │ │ terminal │ │ files │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Exit Handler Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ ON_EXIT() Flow │
|
||||
│ Handles script exit cleanup │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Exit Cleanup │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Cleanup Operations │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Lock File │ │ Temporary │ │ Exit with │ │ │
|
||||
│ │ │ Cleanup │ │ File │ │ Original Code │ │ │
|
||||
│ │ │ │ │ Cleanup │ │ │ │
|
||||
│ │ │ • Check if │ │ • Remove │ │ • Exit with │ │
|
||||
│ │ │ lockfile │ │ temporary │ │ original exit │ │
|
||||
│ │ │ variable set │ │ files │ │ code │ │
|
||||
│ │ │ • Check if │ │ • Clean up │ │ • Preserve exit │ │
|
||||
│ │ │ lockfile │ │ process │ │ status │ │
|
||||
│ │ │ exists │ │ state │ │ • Terminate │ │
|
||||
│ │ │ • Remove │ │ │ │ execution │ │
|
||||
│ │ │ lockfile │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Code Explanation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ EXPLAIN_EXIT_CODE() Flow │
|
||||
│ Converts numeric exit codes to human-readable explanations │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Error Code Classification │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Error Code Categories │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Generic/ │ │ Package │ │ Node.js │ │ │
|
||||
│ │ │ Shell │ │ Manager │ │ Errors │ │ │
|
||||
│ │ │ Errors │ │ Errors │ │ │ │
|
||||
│ │ │ │ │ │ │ • 243: Out of │ │
|
||||
│ │ │ • 1: General │ │ • 100: APT │ │ memory │ │
|
||||
│ │ │ error │ │ package │ │ • 245: Invalid │ │
|
||||
│ │ │ • 2: Shell │ │ error │ │ option │ │
|
||||
│ │ │ builtin │ │ • 101: APT │ │ • 246: Parse │ │
|
||||
│ │ │ misuse │ │ config error │ │ error │ │
|
||||
│ │ │ • 126: Cannot │ │ • 255: DPKG │ │ • 247: Fatal │ │
|
||||
│ │ │ execute │ │ fatal error │ │ error │ │
|
||||
│ │ │ • 127: Command │ │ │ │ • 248: Addon │ │
|
||||
│ │ │ not found │ │ │ │ failure │ │
|
||||
│ │ │ • 128: Invalid │ │ │ │ • 249: Inspector │ │
|
||||
│ │ │ exit │ │ │ │ error │ │
|
||||
│ │ │ • 130: SIGINT │ │ │ │ • 254: Unknown │ │
|
||||
│ │ │ • 137: SIGKILL │ │ │ │ fatal error │ │
|
||||
│ │ │ • 139: Segfault │ │ │ │ │ │
|
||||
│ │ │ • 143: SIGTERM │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Python │ │ Database │ │ Proxmox │ │ │
|
||||
│ │ │ Errors │ │ Errors │ │ Custom │ │ │
|
||||
│ │ │ │ │ │ │ Errors │ │
|
||||
│ │ │ • 210: Virtual │ │ • PostgreSQL: │ │ • 200: Lock file │ │
|
||||
│ │ │ env missing │ │ 231-234 │ │ failed │ │
|
||||
│ │ │ • 211: Dep │ │ • MySQL: 241- │ │ • 203: Missing │ │
|
||||
│ │ │ resolution │ │ 244 │ │ CTID │ │
|
||||
│ │ │ • 212: Install │ │ • MongoDB: 251- │ │ • 204: Missing │ │
|
||||
│ │ │ aborted │ │ 254 │ │ PCT_OSTYPE │ │
|
||||
│ │ │ │ │ │ │ • 205: Invalid │ │
|
||||
│ │ │ │ │ │ │ CTID │ │
|
||||
│ │ │ │ │ │ │ • 209: Container │ │
|
||||
│ │ │ │ │ │ │ creation failed │ │
|
||||
│ │ │ │ │ │ │ • 210: Cluster │ │
|
||||
│ │ │ │ │ │ │ not quorate │ │
|
||||
│ │ │ │ │ │ │ • 214: No storage │ │
|
||||
│ │ │ │ │ │ │ space │ │
|
||||
│ │ │ │ │ │ │ • 215: CTID not │ │
|
||||
│ │ │ │ │ │ │ listed │ │
|
||||
│ │ │ │ │ │ │ • 216: RootFS │ │
|
||||
│ │ │ │ │ │ │ missing │ │
|
||||
│ │ │ │ │ │ │ • 217: Storage │ │
|
||||
│ │ │ │ │ │ │ not supported │ │
|
||||
│ │ │ │ │ │ │ • 220: Template │ │
|
||||
│ │ │ │ │ │ │ path error │ │
|
||||
│ │ │ │ │ │ │ • 222: Template │ │
|
||||
│ │ │ │ │ │ │ download failed │ │
|
||||
│ │ │ │ │ │ │ • 223: Template │ │
|
||||
│ │ │ │ │ │ │ not available │ │
|
||||
│ │ │ │ │ │ │ • 231: LXC stack │ │
|
||||
│ │ │ │ │ │ │ upgrade failed │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Default Case │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Unknown Error Handling │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check for │ │ Return │ │ Log Unknown │ │ │
|
||||
│ │ │ Unknown │ │ Generic │ │ Error │ │ │
|
||||
│ │ │ Code │ │ Message │ │ │ │
|
||||
│ │ │ │ │ │ │ • Log to debug │ │
|
||||
│ │ │ • If no match │ │ • "Unknown │ │ file if enabled │ │
|
||||
│ │ │ found │ │ error" │ │ • Include error │ │
|
||||
│ │ │ • Use default │ │ • Return to │ │ code │ │
|
||||
│ │ │ case │ │ caller │ │ • Include │ │
|
||||
│ │ │ │ │ │ │ timestamp │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Debug Logging Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Debug Log Integration │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Debug Log Writing │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Debug │ │ Write Error │ │ Format Log │ │ │
|
||||
│ │ │ Log File │ │ Information │ │ Entry │ │ │
|
||||
│ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Check if │ │ • Timestamp │ │ • Error separator │ │
|
||||
│ │ │ DEBUG_LOGFILE │ │ • Exit code │ │ • Structured │ │
|
||||
│ │ │ set │ │ • Explanation │ │ format │ │
|
||||
│ │ │ • Check if │ │ • Line number │ │ • Easy to parse │ │
|
||||
│ │ │ file exists │ │ • Command │ │ • Easy to read │ │
|
||||
│ │ │ • Check if │ │ • Append to │ │ │ │
|
||||
│ │ │ file writable │ │ file │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With core.func
|
||||
- **Silent Execution**: Provides error explanations for silent() function
|
||||
- **Color Variables**: Uses color variables for error display
|
||||
- **Log Integration**: Integrates with SILENT_LOGFILE
|
||||
|
||||
### With Other Scripts
|
||||
- **Error Traps**: Sets up ERR trap for automatic error handling
|
||||
- **Signal Traps**: Handles SIGINT, SIGTERM, and EXIT signals
|
||||
- **Cleanup**: Provides cleanup on script exit
|
||||
|
||||
### External Dependencies
|
||||
- **None**: Pure Bash implementation
|
||||
- **Color Support**: Requires color variables from core.func
|
||||
- **Log Files**: Uses standard file operations
|
||||
@ -0,0 +1,424 @@
|
||||
# error_handler.func Functions Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive alphabetical reference of all functions in `error_handler.func`, including parameters, dependencies, usage examples, and error handling.
|
||||
|
||||
## Function Categories
|
||||
|
||||
### Error Explanation Functions
|
||||
|
||||
#### `explain_exit_code()`
|
||||
**Purpose**: Convert numeric exit codes to human-readable explanations
|
||||
**Parameters**:
|
||||
- `$1` - Exit code to explain
|
||||
**Returns**: Human-readable error explanation string
|
||||
**Side Effects**: None
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Supported Exit Codes**:
|
||||
- **Generic/Shell**: 1, 2, 126, 127, 128, 130, 137, 139, 143
|
||||
- **Package Manager**: 100, 101, 255
|
||||
- **Node.js**: 243, 245, 246, 247, 248, 249, 254
|
||||
- **Python**: 210, 211, 212
|
||||
- **PostgreSQL**: 231, 232, 233, 234
|
||||
- **MySQL/MariaDB**: 241, 242, 243, 244
|
||||
- **MongoDB**: 251, 252, 253, 254
|
||||
- **Proxmox Custom**: 200, 203, 204, 205, 209, 210, 214, 215, 216, 217, 220, 222, 223, 231
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
explanation=$(explain_exit_code 127)
|
||||
echo "Error 127: $explanation"
|
||||
# Output: Error 127: Command not found
|
||||
```
|
||||
|
||||
**Error Code Examples**:
|
||||
```bash
|
||||
explain_exit_code 1 # "General error / Operation not permitted"
|
||||
explain_exit_code 126 # "Command invoked cannot execute (permission problem?)"
|
||||
explain_exit_code 127 # "Command not found"
|
||||
explain_exit_code 130 # "Terminated by Ctrl+C (SIGINT)"
|
||||
explain_exit_code 200 # "Custom: Failed to create lock file"
|
||||
explain_exit_code 999 # "Unknown error"
|
||||
```
|
||||
|
||||
### Error Handling Functions
|
||||
|
||||
#### `error_handler()`
|
||||
**Purpose**: Main error handler triggered by ERR trap or manual call
|
||||
**Parameters**:
|
||||
- `$1` - Exit code (optional, defaults to $?)
|
||||
- `$2` - Command that failed (optional, defaults to BASH_COMMAND)
|
||||
**Returns**: None (exits with error code)
|
||||
**Side Effects**:
|
||||
- Displays detailed error information
|
||||
- Logs error to debug file if enabled
|
||||
- Shows silent log content if available
|
||||
- Exits with original error code
|
||||
**Dependencies**: `explain_exit_code()`
|
||||
**Environment Variables Used**: `DEBUG_LOGFILE`, `SILENT_LOGFILE`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
# Automatic error handling via ERR trap
|
||||
set -e
|
||||
trap 'error_handler' ERR
|
||||
|
||||
# Manual error handling
|
||||
error_handler 127 "command_not_found"
|
||||
```
|
||||
|
||||
**Error Information Displayed**:
|
||||
- Error message with color coding
|
||||
- Line number where error occurred
|
||||
- Exit code with explanation
|
||||
- Command that failed
|
||||
- Silent log content (last 20 lines)
|
||||
- Debug log entry (if enabled)
|
||||
|
||||
### Signal Handling Functions
|
||||
|
||||
#### `on_interrupt()`
|
||||
**Purpose**: Handle SIGINT (Ctrl+C) signals gracefully
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits with code 130)
|
||||
**Side Effects**:
|
||||
- Displays interruption message
|
||||
- Exits with SIGINT code (130)
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
# Set up interrupt handler
|
||||
trap on_interrupt INT
|
||||
|
||||
# User presses Ctrl+C
|
||||
# Handler displays: "Interrupted by user (SIGINT)"
|
||||
# Script exits with code 130
|
||||
```
|
||||
|
||||
#### `on_terminate()`
|
||||
**Purpose**: Handle SIGTERM signals gracefully
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits with code 143)
|
||||
**Side Effects**:
|
||||
- Displays termination message
|
||||
- Exits with SIGTERM code (143)
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
# Set up termination handler
|
||||
trap on_terminate TERM
|
||||
|
||||
# System sends SIGTERM
|
||||
# Handler displays: "Terminated by signal (SIGTERM)"
|
||||
# Script exits with code 143
|
||||
```
|
||||
|
||||
### Cleanup Functions
|
||||
|
||||
#### `on_exit()`
|
||||
**Purpose**: Handle script exit cleanup
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits with original exit code)
|
||||
**Side Effects**:
|
||||
- Removes lock file if set
|
||||
- Exits with original exit code
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `lockfile`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
# Set up exit handler
|
||||
trap on_exit EXIT
|
||||
|
||||
# Set lock file
|
||||
lockfile="/tmp/my_script.lock"
|
||||
|
||||
# Script exits normally or with error
|
||||
# Handler removes lock file and exits
|
||||
```
|
||||
|
||||
### Initialization Functions
|
||||
|
||||
#### `catch_errors()`
|
||||
**Purpose**: Initialize error handling traps and strict mode
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Sets strict error handling mode
|
||||
- Sets up error traps
|
||||
- Sets up signal traps
|
||||
- Sets up exit trap
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `STRICT_UNSET`
|
||||
|
||||
**Strict Mode Settings**:
|
||||
- `-E`: Exit on command failure
|
||||
- `-e`: Exit on any error
|
||||
- `-o pipefail`: Exit on pipe failure
|
||||
- `-u`: Exit on unset variables (if STRICT_UNSET=1)
|
||||
|
||||
**Trap Setup**:
|
||||
- `ERR`: Calls `error_handler` on command failure
|
||||
- `EXIT`: Calls `on_exit` on script exit
|
||||
- `INT`: Calls `on_interrupt` on SIGINT
|
||||
- `TERM`: Calls `on_terminate` on SIGTERM
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
# Initialize error handling
|
||||
catch_errors
|
||||
|
||||
# Script now has full error handling
|
||||
# All errors will be caught and handled
|
||||
```
|
||||
|
||||
## Function Call Hierarchy
|
||||
|
||||
### Error Handling Flow
|
||||
```
|
||||
Command Failure
|
||||
├── ERR trap triggered
|
||||
├── error_handler() called
|
||||
│ ├── Get exit code
|
||||
│ ├── Get command info
|
||||
│ ├── Get line number
|
||||
│ ├── explain_exit_code()
|
||||
│ ├── Display error info
|
||||
│ ├── Log to debug file
|
||||
│ ├── Show silent log
|
||||
│ └── Exit with error code
|
||||
```
|
||||
|
||||
### Signal Handling Flow
|
||||
```
|
||||
Signal Received
|
||||
├── Signal trap triggered
|
||||
├── Appropriate handler called
|
||||
│ ├── on_interrupt() for SIGINT
|
||||
│ ├── on_terminate() for SIGTERM
|
||||
│ └── on_exit() for EXIT
|
||||
└── Exit with signal code
|
||||
```
|
||||
|
||||
### Initialization Flow
|
||||
```
|
||||
catch_errors()
|
||||
├── Set strict mode
|
||||
│ ├── -E (exit on failure)
|
||||
│ ├── -e (exit on error)
|
||||
│ ├── -o pipefail (pipe failure)
|
||||
│ └── -u (unset variables, if enabled)
|
||||
└── Set up traps
|
||||
├── ERR → error_handler
|
||||
├── EXIT → on_exit
|
||||
├── INT → on_interrupt
|
||||
└── TERM → on_terminate
|
||||
```
|
||||
|
||||
## Error Code Reference
|
||||
|
||||
### Generic/Shell Errors
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 1 | General error / Operation not permitted |
|
||||
| 2 | Misuse of shell builtins (e.g. syntax error) |
|
||||
| 126 | Command invoked cannot execute (permission problem?) |
|
||||
| 127 | Command not found |
|
||||
| 128 | Invalid argument to exit |
|
||||
| 130 | Terminated by Ctrl+C (SIGINT) |
|
||||
| 137 | Killed (SIGKILL / Out of memory?) |
|
||||
| 139 | Segmentation fault (core dumped) |
|
||||
| 143 | Terminated (SIGTERM) |
|
||||
|
||||
### Package Manager Errors
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 100 | APT: Package manager error (broken packages / dependency problems) |
|
||||
| 101 | APT: Configuration error (bad sources.list, malformed config) |
|
||||
| 255 | DPKG: Fatal internal error |
|
||||
|
||||
### Node.js Errors
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 243 | Node.js: Out of memory (JavaScript heap out of memory) |
|
||||
| 245 | Node.js: Invalid command-line option |
|
||||
| 246 | Node.js: Internal JavaScript Parse Error |
|
||||
| 247 | Node.js: Fatal internal error |
|
||||
| 248 | Node.js: Invalid C++ addon / N-API failure |
|
||||
| 249 | Node.js: Inspector error |
|
||||
| 254 | npm/pnpm/yarn: Unknown fatal error |
|
||||
|
||||
### Python Errors
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 210 | Python: Virtualenv / uv environment missing or broken |
|
||||
| 211 | Python: Dependency resolution failed |
|
||||
| 212 | Python: Installation aborted (permissions or EXTERNALLY-MANAGED) |
|
||||
|
||||
### Database Errors
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 231 | PostgreSQL: Connection failed (server not running / wrong socket) |
|
||||
| 232 | PostgreSQL: Authentication failed (bad user/password) |
|
||||
| 233 | PostgreSQL: Database does not exist |
|
||||
| 234 | PostgreSQL: Fatal error in query / syntax |
|
||||
| 241 | MySQL/MariaDB: Connection failed (server not running / wrong socket) |
|
||||
| 242 | MySQL/MariaDB: Authentication failed (bad user/password) |
|
||||
| 243 | MySQL/MariaDB: Database does not exist |
|
||||
| 244 | MySQL/MariaDB: Fatal error in query / syntax |
|
||||
| 251 | MongoDB: Connection failed (server not running) |
|
||||
| 252 | MongoDB: Authentication failed (bad user/password) |
|
||||
| 253 | MongoDB: Database not found |
|
||||
| 254 | MongoDB: Fatal query error |
|
||||
|
||||
### Proxmox Custom Errors
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 200 | Custom: Failed to create lock file |
|
||||
| 203 | Custom: Missing CTID variable |
|
||||
| 204 | Custom: Missing PCT_OSTYPE variable |
|
||||
| 205 | Custom: Invalid CTID (<100) |
|
||||
| 209 | Custom: Container creation failed |
|
||||
| 210 | Custom: Cluster not quorate |
|
||||
| 214 | Custom: Not enough storage space |
|
||||
| 215 | Custom: Container ID not listed |
|
||||
| 216 | Custom: RootFS entry missing in config |
|
||||
| 217 | Custom: Storage does not support rootdir |
|
||||
| 220 | Custom: Unable to resolve template path |
|
||||
| 222 | Custom: Template download failed after 3 attempts |
|
||||
| 223 | Custom: Template not available after download |
|
||||
| 231 | Custom: LXC stack upgrade/retry failed |
|
||||
|
||||
## Environment Variable Dependencies
|
||||
|
||||
### Required Variables
|
||||
- **`lockfile`**: Lock file path for cleanup (set by calling script)
|
||||
|
||||
### Optional Variables
|
||||
- **`DEBUG_LOGFILE`**: Path to debug log file for error logging
|
||||
- **`SILENT_LOGFILE`**: Path to silent execution log file
|
||||
- **`STRICT_UNSET`**: Enable strict unset variable checking (0/1)
|
||||
|
||||
### Internal Variables
|
||||
- **`exit_code`**: Current exit code
|
||||
- **`command`**: Failed command
|
||||
- **`line_number`**: Line number where error occurred
|
||||
- **`explanation`**: Error explanation text
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### Automatic Error Handling
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Initialize error handling
|
||||
catch_errors
|
||||
|
||||
# All commands are now monitored
|
||||
# Errors will be automatically caught and handled
|
||||
```
|
||||
|
||||
### Manual Error Handling
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Manual error handling
|
||||
if ! command -v required_tool >/dev/null 2>&1; then
|
||||
error_handler 127 "required_tool not found"
|
||||
fi
|
||||
```
|
||||
|
||||
### Custom Error Codes
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Use custom error codes
|
||||
if [[ ! -f /required/file ]]; then
|
||||
echo "Error: Required file missing"
|
||||
exit 200 # Custom error code
|
||||
fi
|
||||
```
|
||||
|
||||
### Signal Handling
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Set up signal handling
|
||||
trap on_interrupt INT
|
||||
trap on_terminate TERM
|
||||
trap on_exit EXIT
|
||||
|
||||
# Script handles signals gracefully
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### With core.func
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Silent execution uses error_handler for explanations
|
||||
silent apt-get install -y package
|
||||
# If command fails, error_handler provides explanation
|
||||
```
|
||||
|
||||
### With build.func
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
source error_handler.func
|
||||
source build.func
|
||||
|
||||
# Container creation with error handling
|
||||
# Errors are caught and explained
|
||||
```
|
||||
|
||||
### With tools.func
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
source error_handler.func
|
||||
source tools.func
|
||||
|
||||
# Tool operations with error handling
|
||||
# All errors are properly handled and explained
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Error Handling Setup
|
||||
1. Source error_handler.func early in script
|
||||
2. Call catch_errors() to initialize traps
|
||||
3. Use appropriate exit codes for different error types
|
||||
4. Provide meaningful error messages
|
||||
|
||||
### Signal Handling
|
||||
1. Always set up signal traps
|
||||
2. Provide graceful cleanup on interruption
|
||||
3. Use appropriate exit codes for signals
|
||||
4. Clean up temporary files and processes
|
||||
|
||||
### Error Reporting
|
||||
1. Use explain_exit_code() for user-friendly messages
|
||||
2. Log errors to debug files when needed
|
||||
3. Provide context information (line numbers, commands)
|
||||
4. Integrate with silent execution logging
|
||||
|
||||
### Custom Error Codes
|
||||
1. Use Proxmox custom error codes (200-231) for container/VM errors
|
||||
2. Use standard error codes for common operations
|
||||
3. Document custom error codes in script comments
|
||||
4. Provide clear error messages for custom codes
|
||||
512
docs/misc/error_handler.func/ERROR_HANDLER_INTEGRATION.md
Normal file
512
docs/misc/error_handler.func/ERROR_HANDLER_INTEGRATION.md
Normal file
@ -0,0 +1,512 @@
|
||||
# error_handler.func Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes how `error_handler.func` integrates with other components in the Proxmox Community Scripts project, including dependencies, data flow, and API surface.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External Dependencies
|
||||
|
||||
#### Required Commands
|
||||
- **None**: Pure Bash implementation
|
||||
|
||||
#### Optional Commands
|
||||
- **None**: No external command dependencies
|
||||
|
||||
### Internal Dependencies
|
||||
|
||||
#### core.func
|
||||
- **Purpose**: Provides color variables for error display
|
||||
- **Usage**: Uses `RD`, `CL`, `YWB` color variables
|
||||
- **Integration**: Called automatically when core.func is sourced
|
||||
- **Data Flow**: Color variables → error display formatting
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With core.func
|
||||
|
||||
#### Silent Execution Integration
|
||||
```bash
|
||||
# core.func silent() function uses error_handler.func
|
||||
silent() {
|
||||
local cmd="$*"
|
||||
local caller_line="${BASH_LINENO[0]:-unknown}"
|
||||
|
||||
# Execute command
|
||||
"$@" >>"$SILENT_LOGFILE" 2>&1
|
||||
local rc=$?
|
||||
|
||||
if [[ $rc -ne 0 ]]; then
|
||||
# Load error_handler.func if needed
|
||||
if ! declare -f explain_exit_code >/dev/null 2>&1; then
|
||||
source error_handler.func
|
||||
fi
|
||||
|
||||
# Get error explanation
|
||||
local explanation
|
||||
explanation="$(explain_exit_code "$rc")"
|
||||
|
||||
# Display error with explanation
|
||||
printf "\e[?25h"
|
||||
echo -e "\n${RD}[ERROR]${CL} in line ${RD}${caller_line}${CL}: exit code ${RD}${rc}${CL} (${explanation})"
|
||||
echo -e "${RD}Command:${CL} ${YWB}${cmd}${CL}\n"
|
||||
|
||||
exit "$rc"
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
#### Color Variable Usage
|
||||
```bash
|
||||
# error_handler.func uses color variables from core.func
|
||||
error_handler() {
|
||||
# ... error handling logic ...
|
||||
|
||||
# Use color variables for error display
|
||||
echo -e "\n${RD}[ERROR]${CL} in line ${RD}${line_number}${CL}: exit code ${RD}${exit_code}${CL} (${explanation}): while executing command ${YWB}${command}${CL}\n"
|
||||
}
|
||||
|
||||
on_interrupt() {
|
||||
echo -e "\n${RD}Interrupted by user (SIGINT)${CL}"
|
||||
exit 130
|
||||
}
|
||||
|
||||
on_terminate() {
|
||||
echo -e "\n${RD}Terminated by signal (SIGTERM)${CL}"
|
||||
exit 143
|
||||
}
|
||||
```
|
||||
|
||||
### With build.func
|
||||
|
||||
#### Container Creation Error Handling
|
||||
```bash
|
||||
# build.func uses error_handler.func for container operations
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Container creation with error handling
|
||||
create_container() {
|
||||
# Set up error handling
|
||||
catch_errors
|
||||
|
||||
# Container creation operations
|
||||
silent pct create "$CTID" "$TEMPLATE" \
|
||||
--hostname "$HOSTNAME" \
|
||||
--memory "$MEMORY" \
|
||||
--cores "$CORES"
|
||||
|
||||
# If creation fails, error_handler provides explanation
|
||||
}
|
||||
```
|
||||
|
||||
#### Template Download Error Handling
|
||||
```bash
|
||||
# build.func uses error_handler.func for template operations
|
||||
download_template() {
|
||||
# Template download with error handling
|
||||
if ! silent curl -fsSL "$TEMPLATE_URL" -o "$TEMPLATE_FILE"; then
|
||||
# error_handler provides detailed explanation
|
||||
exit 222 # Template download failed
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
### With tools.func
|
||||
|
||||
#### Maintenance Operations Error Handling
|
||||
```bash
|
||||
# tools.func uses error_handler.func for maintenance operations
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Maintenance operations with error handling
|
||||
update_system() {
|
||||
catch_errors
|
||||
|
||||
# System update operations
|
||||
silent apt-get update
|
||||
silent apt-get upgrade -y
|
||||
|
||||
# Error handling provides explanations for failures
|
||||
}
|
||||
|
||||
cleanup_logs() {
|
||||
catch_errors
|
||||
|
||||
# Log cleanup operations
|
||||
silent find /var/log -name "*.log" -mtime +30 -delete
|
||||
|
||||
# Error handling provides explanations for permission issues
|
||||
}
|
||||
```
|
||||
|
||||
### With api.func
|
||||
|
||||
#### API Operations Error Handling
|
||||
```bash
|
||||
# api.func uses error_handler.func for API operations
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# API operations with error handling
|
||||
api_call() {
|
||||
catch_errors
|
||||
|
||||
# API call with error handling
|
||||
if ! silent curl -k -H "Authorization: PVEAPIToken=$API_TOKEN" \
|
||||
"$API_URL/api2/json/nodes/$NODE/lxc"; then
|
||||
# error_handler provides explanation for API failures
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
### With install.func
|
||||
|
||||
#### Installation Process Error Handling
|
||||
```bash
|
||||
# install.func uses error_handler.func for installation operations
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Installation with error handling
|
||||
install_package() {
|
||||
local package="$1"
|
||||
|
||||
catch_errors
|
||||
|
||||
# Package installation
|
||||
silent apt-get install -y "$package"
|
||||
|
||||
# Error handling provides explanations for installation failures
|
||||
}
|
||||
```
|
||||
|
||||
### With alpine-install.func
|
||||
|
||||
#### Alpine Installation Error Handling
|
||||
```bash
|
||||
# alpine-install.func uses error_handler.func for Alpine operations
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Alpine installation with error handling
|
||||
install_alpine_package() {
|
||||
local package="$1"
|
||||
|
||||
catch_errors
|
||||
|
||||
# Alpine package installation
|
||||
silent apk add --no-cache "$package"
|
||||
|
||||
# Error handling provides explanations for Alpine-specific failures
|
||||
}
|
||||
```
|
||||
|
||||
### With alpine-tools.func
|
||||
|
||||
#### Alpine Tools Error Handling
|
||||
```bash
|
||||
# alpine-tools.func uses error_handler.func for Alpine tools
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Alpine tools with error handling
|
||||
alpine_tool_operation() {
|
||||
catch_errors
|
||||
|
||||
# Alpine-specific tool operations
|
||||
silent alpine_command
|
||||
|
||||
# Error handling provides explanations for Alpine tool failures
|
||||
}
|
||||
```
|
||||
|
||||
### With passthrough.func
|
||||
|
||||
#### Hardware Passthrough Error Handling
|
||||
```bash
|
||||
# passthrough.func uses error_handler.func for hardware operations
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Hardware passthrough with error handling
|
||||
configure_gpu_passthrough() {
|
||||
catch_errors
|
||||
|
||||
# GPU passthrough operations
|
||||
silent lspci | grep -i nvidia
|
||||
|
||||
# Error handling provides explanations for hardware failures
|
||||
}
|
||||
```
|
||||
|
||||
### With vm-core.func
|
||||
|
||||
#### VM Operations Error Handling
|
||||
```bash
|
||||
# vm-core.func uses error_handler.func for VM operations
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# VM operations with error handling
|
||||
create_vm() {
|
||||
catch_errors
|
||||
|
||||
# VM creation operations
|
||||
silent qm create "$VMID" \
|
||||
--name "$VMNAME" \
|
||||
--memory "$MEMORY" \
|
||||
--cores "$CORES"
|
||||
|
||||
# Error handling provides explanations for VM creation failures
|
||||
}
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Input Data
|
||||
|
||||
#### Environment Variables
|
||||
- **`DEBUG_LOGFILE`**: Path to debug log file for error logging
|
||||
- **`SILENT_LOGFILE`**: Path to silent execution log file
|
||||
- **`STRICT_UNSET`**: Enable strict unset variable checking (0/1)
|
||||
- **`lockfile`**: Lock file path for cleanup (set by calling script)
|
||||
|
||||
#### Function Parameters
|
||||
- **Exit codes**: Passed to `explain_exit_code()` and `error_handler()`
|
||||
- **Command information**: Passed to `error_handler()` for context
|
||||
- **Signal information**: Passed to signal handlers
|
||||
|
||||
#### System Information
|
||||
- **Exit codes**: Retrieved from `$?` variable
|
||||
- **Command information**: Retrieved from `BASH_COMMAND` variable
|
||||
- **Line numbers**: Retrieved from `BASH_LINENO[0]` variable
|
||||
- **Process information**: Retrieved from system calls
|
||||
|
||||
### Processing Data
|
||||
|
||||
#### Error Code Processing
|
||||
- **Code classification**: Categorize exit codes by type
|
||||
- **Explanation lookup**: Map codes to human-readable messages
|
||||
- **Context collection**: Gather command and line information
|
||||
- **Log preparation**: Format error information for logging
|
||||
|
||||
#### Signal Processing
|
||||
- **Signal detection**: Identify received signals
|
||||
- **Handler selection**: Choose appropriate signal handler
|
||||
- **Cleanup operations**: Perform necessary cleanup
|
||||
- **Exit code setting**: Set appropriate exit codes
|
||||
|
||||
#### Log Processing
|
||||
- **Debug logging**: Write error information to debug log
|
||||
- **Silent log integration**: Display silent log content
|
||||
- **Log formatting**: Format log entries for readability
|
||||
- **Log analysis**: Provide log analysis capabilities
|
||||
|
||||
### Output Data
|
||||
|
||||
#### Error Information
|
||||
- **Error messages**: Human-readable error explanations
|
||||
- **Context information**: Line numbers, commands, timestamps
|
||||
- **Color formatting**: ANSI color codes for terminal display
|
||||
- **Log content**: Silent log excerpts and debug information
|
||||
|
||||
#### System State
|
||||
- **Exit codes**: Returned from functions
|
||||
- **Log files**: Created and updated for error tracking
|
||||
- **Cleanup status**: Lock file removal and process cleanup
|
||||
- **Signal handling**: Graceful signal processing
|
||||
|
||||
## API Surface
|
||||
|
||||
### Public Functions
|
||||
|
||||
#### Error Explanation
|
||||
- **`explain_exit_code()`**: Convert exit codes to explanations
|
||||
- **Parameters**: Exit code to explain
|
||||
- **Returns**: Human-readable explanation string
|
||||
- **Usage**: Called by error_handler() and other functions
|
||||
|
||||
#### Error Handling
|
||||
- **`error_handler()`**: Main error handler function
|
||||
- **Parameters**: Exit code (optional), command (optional)
|
||||
- **Returns**: None (exits with error code)
|
||||
- **Usage**: Called by ERR trap or manually
|
||||
|
||||
#### Signal Handling
|
||||
- **`on_interrupt()`**: Handle SIGINT signals
|
||||
- **`on_terminate()`**: Handle SIGTERM signals
|
||||
- **`on_exit()`**: Handle script exit cleanup
|
||||
- **Parameters**: None
|
||||
- **Returns**: None (exits with signal code)
|
||||
- **Usage**: Called by signal traps
|
||||
|
||||
#### Initialization
|
||||
- **`catch_errors()`**: Initialize error handling
|
||||
- **Parameters**: None
|
||||
- **Returns**: None
|
||||
- **Usage**: Called to set up error handling traps
|
||||
|
||||
### Internal Functions
|
||||
|
||||
#### None
|
||||
- All functions in error_handler.func are public
|
||||
- No internal helper functions
|
||||
- Direct implementation of all functionality
|
||||
|
||||
### Global Variables
|
||||
|
||||
#### Configuration Variables
|
||||
- **`DEBUG_LOGFILE`**: Debug log file path
|
||||
- **`SILENT_LOGFILE`**: Silent log file path
|
||||
- **`STRICT_UNSET`**: Strict mode setting
|
||||
- **`lockfile`**: Lock file path
|
||||
|
||||
#### State Variables
|
||||
- **`exit_code`**: Current exit code
|
||||
- **`command`**: Failed command
|
||||
- **`line_number`**: Line number where error occurred
|
||||
- **`explanation`**: Error explanation text
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Standard Integration Pattern
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Standard integration pattern
|
||||
|
||||
# 1. Source core.func first
|
||||
source core.func
|
||||
|
||||
# 2. Source error_handler.func
|
||||
source error_handler.func
|
||||
|
||||
# 3. Initialize error handling
|
||||
catch_errors
|
||||
|
||||
# 4. Use silent execution
|
||||
silent command
|
||||
|
||||
# 5. Errors are automatically handled
|
||||
```
|
||||
|
||||
### Minimal Integration Pattern
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Minimal integration pattern
|
||||
|
||||
source error_handler.func
|
||||
catch_errors
|
||||
|
||||
# Basic error handling
|
||||
command
|
||||
```
|
||||
|
||||
### Advanced Integration Pattern
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Advanced integration pattern
|
||||
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Set up comprehensive error handling
|
||||
export DEBUG_LOGFILE="/tmp/debug.log"
|
||||
export SILENT_LOGFILE="/tmp/silent.log"
|
||||
lockfile="/tmp/script.lock"
|
||||
touch "$lockfile"
|
||||
|
||||
catch_errors
|
||||
trap on_interrupt INT
|
||||
trap on_terminate TERM
|
||||
trap on_exit EXIT
|
||||
|
||||
# Advanced error handling
|
||||
silent command
|
||||
```
|
||||
|
||||
## Error Handling Integration
|
||||
|
||||
### Automatic Error Handling
|
||||
- **ERR Trap**: Automatically catches command failures
|
||||
- **Error Explanation**: Provides human-readable error messages
|
||||
- **Context Information**: Shows line numbers and commands
|
||||
- **Log Integration**: Displays silent log content
|
||||
|
||||
### Manual Error Handling
|
||||
- **Custom Error Codes**: Use Proxmox custom error codes
|
||||
- **Error Recovery**: Implement retry logic with error handling
|
||||
- **Conditional Handling**: Different handling for different error types
|
||||
- **Error Analysis**: Analyze error patterns and trends
|
||||
|
||||
### Signal Handling Integration
|
||||
- **Graceful Interruption**: Handle Ctrl+C gracefully
|
||||
- **Clean Termination**: Handle SIGTERM signals
|
||||
- **Exit Cleanup**: Clean up resources on script exit
|
||||
- **Lock File Management**: Remove lock files on exit
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Error Handling Overhead
|
||||
- **Minimal Impact**: Error handling adds minimal overhead
|
||||
- **Trap Setup**: Trap setup is done once during initialization
|
||||
- **Error Processing**: Error processing is only done on failures
|
||||
- **Log Writing**: Log writing is only done when enabled
|
||||
|
||||
### Memory Usage
|
||||
- **Minimal Footprint**: Error handler uses minimal memory
|
||||
- **Variable Reuse**: Global variables reused across functions
|
||||
- **No Memory Leaks**: Proper cleanup prevents memory leaks
|
||||
- **Efficient Processing**: Efficient error code processing
|
||||
|
||||
### Execution Speed
|
||||
- **Fast Error Detection**: Quick error detection and handling
|
||||
- **Efficient Explanation**: Fast error code explanation lookup
|
||||
- **Minimal Delay**: Minimal delay in error handling
|
||||
- **Quick Exit**: Fast exit on error conditions
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Error Information Disclosure
|
||||
- **Controlled Disclosure**: Only necessary error information is shown
|
||||
- **Log Security**: Log files have appropriate permissions
|
||||
- **Sensitive Data**: Sensitive data is not logged
|
||||
- **Error Sanitization**: Error messages are sanitized
|
||||
|
||||
### Signal Handling Security
|
||||
- **Signal Validation**: Only expected signals are handled
|
||||
- **Cleanup Security**: Secure cleanup of temporary files
|
||||
- **Lock File Security**: Secure lock file management
|
||||
- **Process Security**: Secure process termination
|
||||
|
||||
### Log File Security
|
||||
- **File Permissions**: Log files have appropriate permissions
|
||||
- **Log Rotation**: Log files are rotated to prevent disk filling
|
||||
- **Log Cleanup**: Old log files are cleaned up
|
||||
- **Log Access**: Log access is controlled
|
||||
|
||||
## Future Integration Considerations
|
||||
|
||||
### Extensibility
|
||||
- **New Error Codes**: Easy to add new error code explanations
|
||||
- **Custom Handlers**: Easy to add custom error handlers
|
||||
- **Signal Extensions**: Easy to add new signal handlers
|
||||
- **Log Formats**: Easy to add new log formats
|
||||
|
||||
### Compatibility
|
||||
- **Bash Version**: Compatible with different Bash versions
|
||||
- **System Compatibility**: Compatible with different systems
|
||||
- **Script Compatibility**: Compatible with different script types
|
||||
- **Error Code Compatibility**: Compatible with different error codes
|
||||
|
||||
### Performance
|
||||
- **Optimization**: Error handling can be optimized for better performance
|
||||
- **Caching**: Error explanations can be cached for faster lookup
|
||||
- **Parallel Processing**: Error handling can be parallelized
|
||||
- **Resource Management**: Better resource management for error handling
|
||||
625
docs/misc/error_handler.func/ERROR_HANDLER_USAGE_EXAMPLES.md
Normal file
625
docs/misc/error_handler.func/ERROR_HANDLER_USAGE_EXAMPLES.md
Normal file
@ -0,0 +1,625 @@
|
||||
# error_handler.func Usage Examples
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides practical usage examples for `error_handler.func` functions, covering common scenarios, integration patterns, and best practices.
|
||||
|
||||
## Basic Error Handling Setup
|
||||
|
||||
### Standard Script Initialization
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Standard error handling setup
|
||||
|
||||
# Source error handler
|
||||
source error_handler.func
|
||||
|
||||
# Initialize error handling
|
||||
catch_errors
|
||||
|
||||
# Your script code here
|
||||
# All errors will be automatically caught and handled
|
||||
echo "Script running..."
|
||||
apt-get update
|
||||
apt-get install -y package
|
||||
echo "Script completed successfully"
|
||||
```
|
||||
|
||||
### Minimal Error Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Minimal error handling setup
|
||||
|
||||
source error_handler.func
|
||||
catch_errors
|
||||
|
||||
# Simple script with error handling
|
||||
echo "Starting operation..."
|
||||
command_that_might_fail
|
||||
echo "Operation completed"
|
||||
```
|
||||
|
||||
## Error Code Explanation Examples
|
||||
|
||||
### Basic Error Explanation
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Explain common error codes
|
||||
echo "Error 1: $(explain_exit_code 1)"
|
||||
echo "Error 127: $(explain_exit_code 127)"
|
||||
echo "Error 130: $(explain_exit_code 130)"
|
||||
echo "Error 200: $(explain_exit_code 200)"
|
||||
```
|
||||
|
||||
### Error Code Testing
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Test all error codes
|
||||
test_error_codes() {
|
||||
local codes=(1 2 126 127 128 130 137 139 143 100 101 255 200 203 204 205)
|
||||
|
||||
for code in "${codes[@]}"; do
|
||||
echo "Code $code: $(explain_exit_code $code)"
|
||||
done
|
||||
}
|
||||
|
||||
test_error_codes
|
||||
```
|
||||
|
||||
### Custom Error Code Usage
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Use custom error codes
|
||||
check_requirements() {
|
||||
if [[ ! -f /required/file ]]; then
|
||||
echo "Error: Required file missing"
|
||||
exit 200 # Custom error code
|
||||
fi
|
||||
|
||||
if [[ -z "$CTID" ]]; then
|
||||
echo "Error: CTID not set"
|
||||
exit 203 # Custom error code
|
||||
fi
|
||||
|
||||
if [[ $CTID -lt 100 ]]; then
|
||||
echo "Error: Invalid CTID"
|
||||
exit 205 # Custom error code
|
||||
fi
|
||||
}
|
||||
|
||||
check_requirements
|
||||
```
|
||||
|
||||
## Signal Handling Examples
|
||||
|
||||
### Interrupt Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Set up interrupt handler
|
||||
trap on_interrupt INT
|
||||
|
||||
echo "Script running... Press Ctrl+C to interrupt"
|
||||
sleep 10
|
||||
echo "Script completed normally"
|
||||
```
|
||||
|
||||
### Termination Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Set up termination handler
|
||||
trap on_terminate TERM
|
||||
|
||||
echo "Script running... Send SIGTERM to terminate"
|
||||
sleep 10
|
||||
echo "Script completed normally"
|
||||
```
|
||||
|
||||
### Complete Signal Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Set up all signal handlers
|
||||
trap on_interrupt INT
|
||||
trap on_terminate TERM
|
||||
trap on_exit EXIT
|
||||
|
||||
echo "Script running with full signal handling"
|
||||
sleep 10
|
||||
echo "Script completed normally"
|
||||
```
|
||||
|
||||
## Cleanup Examples
|
||||
|
||||
### Lock File Cleanup
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Set up lock file
|
||||
lockfile="/tmp/my_script.lock"
|
||||
touch "$lockfile"
|
||||
|
||||
# Set up exit handler
|
||||
trap on_exit EXIT
|
||||
|
||||
echo "Script running with lock file..."
|
||||
sleep 5
|
||||
echo "Script completed - lock file will be removed"
|
||||
```
|
||||
|
||||
### Temporary File Cleanup
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Create temporary files
|
||||
temp_file1="/tmp/temp1.$$"
|
||||
temp_file2="/tmp/temp2.$$"
|
||||
touch "$temp_file1" "$temp_file2"
|
||||
|
||||
# Set up cleanup
|
||||
cleanup() {
|
||||
rm -f "$temp_file1" "$temp_file2"
|
||||
echo "Temporary files cleaned up"
|
||||
}
|
||||
|
||||
trap cleanup EXIT
|
||||
|
||||
echo "Script running with temporary files..."
|
||||
sleep 5
|
||||
echo "Script completed - temporary files will be cleaned up"
|
||||
```
|
||||
|
||||
## Debug Logging Examples
|
||||
|
||||
### Basic Debug Logging
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Enable debug logging
|
||||
export DEBUG_LOGFILE="/tmp/debug.log"
|
||||
catch_errors
|
||||
|
||||
echo "Script with debug logging"
|
||||
apt-get update
|
||||
apt-get install -y package
|
||||
```
|
||||
|
||||
### Debug Log Analysis
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Enable debug logging
|
||||
export DEBUG_LOGFILE="/tmp/debug.log"
|
||||
catch_errors
|
||||
|
||||
# Function to analyze debug log
|
||||
analyze_debug_log() {
|
||||
if [[ -f "$DEBUG_LOGFILE" ]]; then
|
||||
echo "Debug log analysis:"
|
||||
echo "Total errors: $(grep -c "ERROR" "$DEBUG_LOGFILE")"
|
||||
echo "Recent errors:"
|
||||
tail -n 5 "$DEBUG_LOGFILE"
|
||||
else
|
||||
echo "No debug log found"
|
||||
fi
|
||||
}
|
||||
|
||||
# Run script
|
||||
echo "Running script..."
|
||||
apt-get update
|
||||
|
||||
# Analyze results
|
||||
analyze_debug_log
|
||||
```
|
||||
|
||||
## Silent Execution Integration
|
||||
|
||||
### With core.func Silent Execution
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Silent execution with error handling
|
||||
echo "Installing packages..."
|
||||
silent apt-get update
|
||||
silent apt-get install -y nginx
|
||||
|
||||
echo "Configuring service..."
|
||||
silent systemctl enable nginx
|
||||
silent systemctl start nginx
|
||||
|
||||
echo "Installation completed"
|
||||
```
|
||||
|
||||
### Silent Execution Error Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Function with silent execution and error handling
|
||||
install_package() {
|
||||
local package="$1"
|
||||
|
||||
echo "Installing $package..."
|
||||
if silent apt-get install -y "$package"; then
|
||||
echo "$package installed successfully"
|
||||
return 0
|
||||
else
|
||||
echo "Failed to install $package"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Install multiple packages
|
||||
packages=("nginx" "apache2" "mysql-server")
|
||||
for package in "${packages[@]}"; do
|
||||
if ! install_package "$package"; then
|
||||
echo "Stopping installation due to error"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Advanced Error Handling Examples
|
||||
|
||||
### Conditional Error Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Conditional error handling based on environment
|
||||
setup_error_handling() {
|
||||
if [[ "${STRICT_MODE:-0}" == "1" ]]; then
|
||||
echo "Enabling strict mode"
|
||||
export STRICT_UNSET=1
|
||||
fi
|
||||
|
||||
catch_errors
|
||||
echo "Error handling configured"
|
||||
}
|
||||
|
||||
setup_error_handling
|
||||
```
|
||||
|
||||
### Error Recovery
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Error recovery pattern
|
||||
retry_operation() {
|
||||
local max_attempts=3
|
||||
local attempt=1
|
||||
|
||||
while [[ $attempt -le $max_attempts ]]; do
|
||||
echo "Attempt $attempt of $max_attempts"
|
||||
|
||||
if silent "$@"; then
|
||||
echo "Operation succeeded on attempt $attempt"
|
||||
return 0
|
||||
else
|
||||
echo "Attempt $attempt failed"
|
||||
((attempt++))
|
||||
|
||||
if [[ $attempt -le $max_attempts ]]; then
|
||||
echo "Retrying in 5 seconds..."
|
||||
sleep 5
|
||||
fi
|
||||
fi
|
||||
done
|
||||
|
||||
echo "Operation failed after $max_attempts attempts"
|
||||
return 1
|
||||
}
|
||||
|
||||
# Use retry pattern
|
||||
retry_operation apt-get update
|
||||
retry_operation apt-get install -y package
|
||||
```
|
||||
|
||||
### Custom Error Handler
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Custom error handler for specific operations
|
||||
custom_error_handler() {
|
||||
local exit_code=${1:-$?}
|
||||
local command=${2:-${BASH_COMMAND:-unknown}}
|
||||
|
||||
case "$exit_code" in
|
||||
127)
|
||||
echo "Custom handling: Command not found - $command"
|
||||
echo "Suggestions:"
|
||||
echo "1. Check if the command is installed"
|
||||
echo "2. Check if the command is in PATH"
|
||||
echo "3. Check spelling"
|
||||
;;
|
||||
126)
|
||||
echo "Custom handling: Permission denied - $command"
|
||||
echo "Suggestions:"
|
||||
echo "1. Check file permissions"
|
||||
echo "2. Run with appropriate privileges"
|
||||
echo "3. Check if file is executable"
|
||||
;;
|
||||
*)
|
||||
# Use default error handler
|
||||
error_handler "$exit_code" "$command"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# Set up custom error handler
|
||||
trap 'custom_error_handler' ERR
|
||||
|
||||
# Test custom error handling
|
||||
nonexistent_command
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### With build.func
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Integration with build.func
|
||||
|
||||
source core.func
|
||||
source error_handler.func
|
||||
source build.func
|
||||
|
||||
# Container creation with error handling
|
||||
export APP="plex"
|
||||
export CTID="100"
|
||||
|
||||
# Errors will be caught and explained
|
||||
# Silent execution will use error_handler for explanations
|
||||
```
|
||||
|
||||
### With tools.func
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Integration with tools.func
|
||||
|
||||
source core.func
|
||||
source error_handler.func
|
||||
source tools.func
|
||||
|
||||
# Tool operations with error handling
|
||||
# All errors are properly handled and explained
|
||||
```
|
||||
|
||||
### With api.func
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Integration with api.func
|
||||
|
||||
source core.func
|
||||
source error_handler.func
|
||||
source api.func
|
||||
|
||||
# API operations with error handling
|
||||
# Network errors and API errors are properly handled
|
||||
```
|
||||
|
||||
## Best Practices Examples
|
||||
|
||||
### Comprehensive Error Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Comprehensive error handling example
|
||||
|
||||
source error_handler.func
|
||||
|
||||
# Set up comprehensive error handling
|
||||
setup_comprehensive_error_handling() {
|
||||
# Enable debug logging
|
||||
export DEBUG_LOGFILE="/tmp/script_debug.log"
|
||||
|
||||
# Set up lock file
|
||||
lockfile="/tmp/script.lock"
|
||||
touch "$lockfile"
|
||||
|
||||
# Initialize error handling
|
||||
catch_errors
|
||||
|
||||
# Set up signal handlers
|
||||
trap on_interrupt INT
|
||||
trap on_terminate TERM
|
||||
trap on_exit EXIT
|
||||
|
||||
echo "Comprehensive error handling configured"
|
||||
}
|
||||
|
||||
setup_comprehensive_error_handling
|
||||
|
||||
# Script operations
|
||||
echo "Starting script operations..."
|
||||
# ... script code ...
|
||||
echo "Script operations completed"
|
||||
```
|
||||
|
||||
### Error Handling for Different Scenarios
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Different error handling for different scenarios
|
||||
handle_package_errors() {
|
||||
local exit_code=$1
|
||||
case "$exit_code" in
|
||||
100)
|
||||
echo "Package manager error - trying to fix..."
|
||||
apt-get --fix-broken install
|
||||
;;
|
||||
101)
|
||||
echo "Configuration error - checking sources..."
|
||||
apt-get update
|
||||
;;
|
||||
*)
|
||||
error_handler "$exit_code"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
handle_network_errors() {
|
||||
local exit_code=$1
|
||||
case "$exit_code" in
|
||||
127)
|
||||
echo "Network command not found - checking connectivity..."
|
||||
ping -c 1 8.8.8.8
|
||||
;;
|
||||
*)
|
||||
error_handler "$exit_code"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# Use appropriate error handler
|
||||
if [[ "$1" == "package" ]]; then
|
||||
trap 'handle_package_errors $?' ERR
|
||||
elif [[ "$1" == "network" ]]; then
|
||||
trap 'handle_network_errors $?' ERR
|
||||
else
|
||||
catch_errors
|
||||
fi
|
||||
```
|
||||
|
||||
### Error Handling with Logging
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Error handling with detailed logging
|
||||
setup_logging_error_handling() {
|
||||
# Create log directory
|
||||
mkdir -p /var/log/script_errors
|
||||
|
||||
# Set up debug logging
|
||||
export DEBUG_LOGFILE="/var/log/script_errors/debug.log"
|
||||
|
||||
# Set up silent logging
|
||||
export SILENT_LOGFILE="/var/log/script_errors/silent.log"
|
||||
|
||||
# Initialize error handling
|
||||
catch_errors
|
||||
|
||||
echo "Logging error handling configured"
|
||||
}
|
||||
|
||||
setup_logging_error_handling
|
||||
|
||||
# Script operations with logging
|
||||
echo "Starting logged operations..."
|
||||
# ... script code ...
|
||||
echo "Logged operations completed"
|
||||
```
|
||||
|
||||
## Troubleshooting Examples
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Enable debug mode
|
||||
export DEBUG_LOGFILE="/tmp/debug.log"
|
||||
export STRICT_UNSET=1
|
||||
|
||||
catch_errors
|
||||
|
||||
echo "Debug mode enabled"
|
||||
# Script operations
|
||||
```
|
||||
|
||||
### Error Analysis
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Function to analyze errors
|
||||
analyze_errors() {
|
||||
local log_file="${1:-$DEBUG_LOGFILE}"
|
||||
|
||||
if [[ -f "$log_file" ]]; then
|
||||
echo "Error Analysis:"
|
||||
echo "Total errors: $(grep -c "ERROR" "$log_file")"
|
||||
echo "Error types:"
|
||||
grep "ERROR" "$log_file" | awk '{print $NF}' | sort | uniq -c
|
||||
echo "Recent errors:"
|
||||
tail -n 10 "$log_file"
|
||||
else
|
||||
echo "No error log found"
|
||||
fi
|
||||
}
|
||||
|
||||
# Run script with error analysis
|
||||
analyze_errors
|
||||
```
|
||||
|
||||
### Error Recovery Testing
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Test error recovery
|
||||
test_error_recovery() {
|
||||
local test_cases=(
|
||||
"nonexistent_command"
|
||||
"apt-get install nonexistent_package"
|
||||
"systemctl start nonexistent_service"
|
||||
)
|
||||
|
||||
for test_case in "${test_cases[@]}"; do
|
||||
echo "Testing: $test_case"
|
||||
if silent $test_case; then
|
||||
echo "Unexpected success"
|
||||
else
|
||||
echo "Expected failure handled"
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
test_error_recovery
|
||||
```
|
||||
228
docs/misc/error_handler.func/README.md
Normal file
228
docs/misc/error_handler.func/README.md
Normal file
@ -0,0 +1,228 @@
|
||||
# error_handler.func Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The `error_handler.func` file provides comprehensive error handling and signal management for Proxmox Community Scripts. It offers detailed error code explanations, graceful error recovery, and proper cleanup mechanisms.
|
||||
|
||||
## Purpose and Use Cases
|
||||
|
||||
- **Error Code Explanation**: Provides human-readable explanations for exit codes
|
||||
- **Signal Handling**: Manages SIGINT, SIGTERM, and other signals gracefully
|
||||
- **Error Recovery**: Implements proper cleanup and error reporting
|
||||
- **Debug Logging**: Records error information for troubleshooting
|
||||
- **Silent Execution Support**: Integrates with core.func silent execution
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Key Function Groups
|
||||
- **Error Explanation**: `explain_exit_code()` - Convert exit codes to human-readable messages
|
||||
- **Error Handling**: `error_handler()` - Main error handler with detailed reporting
|
||||
- **Signal Handlers**: `on_interrupt()`, `on_terminate()` - Graceful signal handling
|
||||
- **Cleanup**: `on_exit()` - Cleanup on script exit
|
||||
- **Trap Setup**: `catch_errors()` - Initialize error handling traps
|
||||
|
||||
### Dependencies
|
||||
- **External**: None (pure Bash implementation)
|
||||
- **Internal**: Uses color variables from core.func
|
||||
|
||||
### Integration Points
|
||||
- Used by: All scripts via core.func silent execution
|
||||
- Uses: Color variables from core.func
|
||||
- Provides: Error explanations for core.func silent function
|
||||
|
||||
## Documentation Files
|
||||
|
||||
### 📊 [ERROR_HANDLER_FLOWCHART.md](./ERROR_HANDLER_FLOWCHART.md)
|
||||
Visual execution flows showing error handling processes and signal management.
|
||||
|
||||
### 📚 [ERROR_HANDLER_FUNCTIONS_REFERENCE.md](./ERROR_HANDLER_FUNCTIONS_REFERENCE.md)
|
||||
Complete alphabetical reference of all functions with parameters, dependencies, and usage details.
|
||||
|
||||
### 💡 [ERROR_HANDLER_USAGE_EXAMPLES.md](./ERROR_HANDLER_USAGE_EXAMPLES.md)
|
||||
Practical examples showing how to use error handling functions and common patterns.
|
||||
|
||||
### 🔗 [ERROR_HANDLER_INTEGRATION.md](./ERROR_HANDLER_INTEGRATION.md)
|
||||
How error_handler.func integrates with other components and provides error handling services.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Error Code Categories
|
||||
- **Generic/Shell Errors**: Exit codes 1, 2, 126, 127, 128, 130, 137, 139, 143
|
||||
- **Package Manager Errors**: APT/DPKG errors (100, 101, 255)
|
||||
- **Node.js Errors**: JavaScript runtime errors (243-249, 254)
|
||||
- **Python Errors**: Python environment and dependency errors (210-212)
|
||||
- **Database Errors**: PostgreSQL, MySQL, MongoDB errors (231-254)
|
||||
- **Proxmox Custom Errors**: Container and VM specific errors (200-231)
|
||||
|
||||
### Signal Handling
|
||||
- **SIGINT (Ctrl+C)**: Graceful interruption handling
|
||||
- **SIGTERM**: Graceful termination handling
|
||||
- **EXIT**: Cleanup on script exit
|
||||
- **ERR**: Error trap for command failures
|
||||
|
||||
### Error Reporting
|
||||
- **Detailed Messages**: Human-readable error explanations
|
||||
- **Context Information**: Line numbers, commands, timestamps
|
||||
- **Log Integration**: Silent log file integration
|
||||
- **Debug Logging**: Optional debug log file support
|
||||
|
||||
## Common Usage Patterns
|
||||
|
||||
### Basic Error Handling Setup
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Basic error handling setup
|
||||
|
||||
source error_handler.func
|
||||
|
||||
# Initialize error handling
|
||||
catch_errors
|
||||
|
||||
# Your script code here
|
||||
# Errors will be automatically handled
|
||||
```
|
||||
|
||||
### Manual Error Explanation
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Get error explanation
|
||||
explanation=$(explain_exit_code 127)
|
||||
echo "Error 127: $explanation"
|
||||
# Output: Error 127: Command not found
|
||||
```
|
||||
|
||||
### Custom Error Handling
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source error_handler.func
|
||||
|
||||
# Custom error handling
|
||||
if ! command -v required_tool >/dev/null 2>&1; then
|
||||
echo "Error: required_tool not found"
|
||||
exit 127
|
||||
fi
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Debug Variables
|
||||
- `DEBUG_LOGFILE`: Path to debug log file for error logging
|
||||
- `SILENT_LOGFILE`: Path to silent execution log file
|
||||
- `STRICT_UNSET`: Enable strict unset variable checking (0/1)
|
||||
|
||||
### Internal Variables
|
||||
- `lockfile`: Lock file path for cleanup (set by calling script)
|
||||
- `exit_code`: Current exit code
|
||||
- `command`: Failed command
|
||||
- `line_number`: Line number where error occurred
|
||||
|
||||
## Error Categories
|
||||
|
||||
### Generic/Shell Errors
|
||||
- **1**: General error / Operation not permitted
|
||||
- **2**: Misuse of shell builtins (syntax error)
|
||||
- **126**: Command invoked cannot execute (permission problem)
|
||||
- **127**: Command not found
|
||||
- **128**: Invalid argument to exit
|
||||
- **130**: Terminated by Ctrl+C (SIGINT)
|
||||
- **137**: Killed (SIGKILL / Out of memory)
|
||||
- **139**: Segmentation fault (core dumped)
|
||||
- **143**: Terminated (SIGTERM)
|
||||
|
||||
### Package Manager Errors
|
||||
- **100**: APT package manager error (broken packages)
|
||||
- **101**: APT configuration error (bad sources.list)
|
||||
- **255**: DPKG fatal internal error
|
||||
|
||||
### Node.js Errors
|
||||
- **243**: JavaScript heap out of memory
|
||||
- **245**: Invalid command-line option
|
||||
- **246**: Internal JavaScript parse error
|
||||
- **247**: Fatal internal error
|
||||
- **248**: Invalid C++ addon / N-API failure
|
||||
- **249**: Inspector error
|
||||
- **254**: npm/pnpm/yarn unknown fatal error
|
||||
|
||||
### Python Errors
|
||||
- **210**: Virtualenv/uv environment missing or broken
|
||||
- **211**: Dependency resolution failed
|
||||
- **212**: Installation aborted (permissions or EXTERNALLY-MANAGED)
|
||||
|
||||
### Database Errors
|
||||
- **PostgreSQL (231-234)**: Connection, authentication, database, query errors
|
||||
- **MySQL/MariaDB (241-244)**: Connection, authentication, database, query errors
|
||||
- **MongoDB (251-254)**: Connection, authentication, database, query errors
|
||||
|
||||
### Proxmox Custom Errors
|
||||
- **200**: Failed to create lock file
|
||||
- **203**: Missing CTID variable
|
||||
- **204**: Missing PCT_OSTYPE variable
|
||||
- **205**: Invalid CTID (<100)
|
||||
- **209**: Container creation failed
|
||||
- **210**: Cluster not quorate
|
||||
- **214**: Not enough storage space
|
||||
- **215**: Container ID not listed
|
||||
- **216**: RootFS entry missing in config
|
||||
- **217**: Storage does not support rootdir
|
||||
- **220**: Unable to resolve template path
|
||||
- **222**: Template download failed after 3 attempts
|
||||
- **223**: Template not available after download
|
||||
- **231**: LXC stack upgrade/retry failed
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Error Handling Setup
|
||||
1. Source error_handler.func early in script
|
||||
2. Call catch_errors() to initialize traps
|
||||
3. Use proper exit codes for different error types
|
||||
4. Provide meaningful error messages
|
||||
|
||||
### Signal Handling
|
||||
1. Always set up signal traps
|
||||
2. Provide graceful cleanup on interruption
|
||||
3. Use appropriate exit codes for signals
|
||||
4. Clean up temporary files and processes
|
||||
|
||||
### Error Reporting
|
||||
1. Use explain_exit_code() for user-friendly messages
|
||||
2. Log errors to debug files when needed
|
||||
3. Provide context information (line numbers, commands)
|
||||
4. Integrate with silent execution logging
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
1. **Missing Error Handler**: Ensure error_handler.func is sourced
|
||||
2. **Trap Not Set**: Call catch_errors() to initialize traps
|
||||
3. **Color Variables**: Ensure core.func is sourced for colors
|
||||
4. **Lock Files**: Clean up lock files in on_exit()
|
||||
|
||||
### Debug Mode
|
||||
Enable debug logging for detailed error information:
|
||||
```bash
|
||||
export DEBUG_LOGFILE="/tmp/debug.log"
|
||||
source error_handler.func
|
||||
catch_errors
|
||||
```
|
||||
|
||||
### Error Code Testing
|
||||
Test error explanations:
|
||||
```bash
|
||||
source error_handler.func
|
||||
for code in 1 2 126 127 128 130 137 139 143; do
|
||||
echo "Code $code: $(explain_exit_code $code)"
|
||||
done
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [core.func](../core.func/) - Core utilities and silent execution
|
||||
- [build.func](../build.func/) - Container creation with error handling
|
||||
- [tools.func](../tools.func/) - Extended utilities with error handling
|
||||
- [api.func](../api.func/) - API operations with error handling
|
||||
|
||||
---
|
||||
|
||||
*This documentation covers the error_handler.func file which provides comprehensive error handling for all Proxmox Community Scripts.*
|
||||
Reference in New Issue
Block a user