Linux-Server-Management-Toolkit/REFDB_FORMAT.txt

################################################################################
# SERVER TOOLKIT - CLAUDE AI CONTEXT DATABASE
################################################################################
# OPTIMIZED FOR: Claude Code AI parsing and context loading
# LAST UPDATED: 2025-11-07
# VERSION: 2.1.0
# FORMAT: Structured key-value with hierarchical sections
################################################################################

[META]
version: 2.1.0
updated: 2025-11-07
status: production_ready
base_path: /root/server-toolkit
entry_point: launcher.sh
control_panels: cPanel, Plesk, InterWorx, Standalone
repository: https://git.mull.lol/cschantz/Linux-Server-Management-Toolkit.git

[STATUS_SNAPSHOT_2025_11_07]
# What works right now (production ready)
working:
  - launcher.sh: Main menu with hierarchical structure, cleanup/reset
  - modules/diagnostics/system-health-check.sh: 22-phase diagnostics with baseline tracking
  - modules/security/bot-analyzer.sh: Threat scoring (0-100), CSF blocking, IP reputation
  - modules/security/live-attack-monitor.sh: Real-time SOC dashboard
  - modules/security/enable-cphulk.sh: cPHulk enablement with CSF whitelist import
  - modules/security/ip-reputation-manager.sh: Centralized IP tracking
  - modules/website/website-error-analyzer.sh: Intelligent error detection (filters bots)
  - modules/website/500-error-tracker.sh: Fast 500 error diagnosis
  - modules/website/wordpress-menu.sh: WordPress management submenu
  - modules/website/wordpress/wordpress-cron-manager.sh: WP cron → system cron conversion
  - modules/backup/acronis-*.sh: Complete Acronis Cyber Protect integration (16 scripts)
  - modules/performance/mysql-query-analyzer.sh: Slow query detection
  - modules/performance/hardware-health-check.sh: Hardware diagnostics
  - lib/system-detect.sh: Auto-detect cPanel/Plesk/InterWorx, OS, web server, DB, PHP
  - lib/user-manager.sh: User selection with arrow-key menus and search
  - lib/reference-db.sh: 1-hour cache with cross-module intelligence
  - lib/ip-reputation.sh: Centralized IP reputation tracking

# Recent additions (2025-11-05 to 2025-11-07)
recent_features:
  - WordPress Cron Manager: Complete wp-cron → system cron conversion
  - WordPress submenu structure: modules/website/wordpress/
  - Cancel/back options: ALL user inputs now support cancellation
  - Development guidelines: REFDB_FORMAT.txt (this file)
  - Acronis backup integration: 16 scripts for complete agent management
  - Website error analyzers: Intelligent bot filtering

# Not implemented yet
future:
  - modules/wordpress/*: Plugin/theme managers, security hardening
  - modules/monitoring/*: Additional monitoring tools
  - modules/reporting/*: Report generation

[CRITICAL_DESIGN_RULES]
# DO NOT BREAK THESE - Latest standards as of 2025-11-07

bash_strict_mode: "set -eo pipefail" (NOT -euo - -u is too strict)
cancel_buttons: MANDATORY - Every menu must have "0) Cancel", every input must accept "0"
grep_pattern: Always add "|| true" to grep/find that might not match
unbound_vars: Use ${var:-} or ${var:-default} for potentially unbound variables
arithmetic: Use current=$((current + 1)) NOT ((current++))
output_suppression: NEVER use { } >/dev/null on critical functions (breaks variable assignment)
module_isolation: Modules run in subshells with cleared SYS_* environment
press_enter: ALWAYS call press_enter at end of scripts before exit
messaging: Use print_success, print_error, print_warning, print_info (NOT echo)

[CANCEL_BUTTON_STANDARD]
# MANDATORY as of 2025-11-07 - ALL scripts must support cancellation

menu_format: |
  echo "  1) Option One"
  echo "  2) Option Two"
  echo "  0) Cancel and return to menu"    # REQUIRED
  echo ""
  read -p "Select option: " choice
  
  case $choice in
      0)
          echo "Operation cancelled."
          press_enter
          exit 0
          ;;
      # ... other options
  esac

text_input_format: |
  echo -n "Enter value (or 0 to cancel): "
  read -r value
  
  if [ -z "$value" ] || [ "$value" = "0" ]; then
      echo "Operation cancelled."
      press_enter
      exit 0
  fi

rationale: Users must NEVER be trapped in a prompt - always provide escape route

[KEY_FILES_QUICK_MAP]
# Fast reference for file locations (updated 2025-11-07)

launcher.sh: Main entry point, menu system
  Line 77-84: Subshell isolation for modules
  Line 1262-1279: WordPress/website menu handler

README.md: User-facing documentation

REFDB_FORMAT.txt: THIS FILE - developer reference (keep updated!)

lib/common-functions.sh: Core utilities
  print_banner(), print_success(), print_error(), print_warning(), print_info()
  press_enter(), show_progress(), finish_progress()

lib/system-detect.sh: Auto-detection
  Exports: SYS_CONTROL_PANEL, SYS_OS_TYPE, SYS_WEB_SERVER, etc.
  Line 433-445: Auto-initialization with exec redirect

lib/user-manager.sh: User/domain selection
  select_user_interactive() - Arrow-key menu with search (type S [text])
  get_user_domains() - Domain detection for cPanel users

lib/reference-db.sh: Session intelligence (.sysref)
  db_get_all_wordpress(), db_get_user_domains(), db_store_*()
  1-hour TTL cache, cross-module data sharing

lib/ip-reputation.sh: Centralized IP tracking
  is_known_bot(), should_filter_ip(), log_ip_threat()

modules/website/wordpress-menu.sh: WordPress submenu
  Entry point for all WordPress management tools

modules/website/wordpress/wordpress-cron-manager.sh: WP cron conversion
  Disable/enable wp-cron, add system cron jobs, staggered timing

config/settings.conf: User configuration
config/whitelist-ips.txt: IP whitelist
config/whitelist-user-agents.txt: User-Agent whitelist

[DIRECTORY_STRUCTURE_2025_11_07]
server-toolkit/
├── launcher.sh (main entry point)
├── README.md (user docs)
├── REFDB_FORMAT.txt (THIS FILE - developer reference)
├── config/
│   ├── settings.conf
│   ├── whitelist-ips.txt
│   └── whitelist-user-agents.txt
├── lib/
│   ├── common-functions.sh (print_*, press_enter, colors)
│   ├── system-detect.sh (SYS_* variables)
│   ├── user-manager.sh (select_user_interactive)
│   ├── reference-db.sh (db_* functions, .sysref)
│   ├── ip-reputation.sh (is_known_bot, log_ip_threat)
│   └── mysql-analyzer.sh (database utilities)
├── modules/
│   ├── security/
│   │   ├── bot-analyzer.sh ✓
│   │   ├── live-attack-monitor.sh ✓
│   │   ├── enable-cphulk.sh ✓
│   │   └── ip-reputation-manager.sh ✓
│   ├── website/
│   │   ├── website-error-analyzer.sh ✓
│   │   ├── 500-error-tracker.sh ✓
│   │   ├── wordpress-menu.sh ✓
│   │   └── wordpress/
│   │       └── wordpress-cron-manager.sh ✓
│   ├── backup/
│   │   ├── acronis-backup-manager.sh ✓
│   │   ├── acronis-trigger-backup.sh ✓
│   │   ├── acronis-agent-status.sh ✓
│   │   └── [13 more acronis scripts] ✓
│   ├── diagnostics/
│   │   └── system-health-check.sh ✓
│   ├── performance/
│   │   ├── mysql-query-analyzer.sh ✓
│   │   └── hardware-health-check.sh ✓
│   └── maintenance/
│       └── cleanup-toolkit-data.sh ✓
└── tools/
    └── diagnostic-report.sh

[REFERENCE_DATABASE_FORMAT]
# .sysref file format - pipe-delimited session database

location: /root/server-toolkit/.sysref
timestamp: /root/server-toolkit/.sysref.timestamp
ttl: 3600 seconds (1 hour)
format: TYPE|field1|field2|field3|...

record_types:
  SYS: System information
    format: SYS|key|value|extra
    example: SYS|CONTROL_PANEL|cpanel|11.130.0.15

  USER: User accounts
    format: USER|username|primary_domain|db_count|domain_count|disk_mb|home_dir
    example: USER|pickledperil|pickledperil.com|1|3|82|/home/pickledperil

  DB: Databases
    format: DB|db_name|owner|primary_domain|size_mb|table_count
    example: DB|pickledperil_wp_wt6lz|pickledperil|pickledperil.com|15.23|12

  DOMAIN: Domain mappings
    format: DOMAIN|domain|owner|doc_root|log_path|php_ver|is_primary|type|aliases
    example: DOMAIN|pickledperil.com|pickledperil|/home/pickledperil/public_html|/var/log/apache2/domlogs/pickledperil.com|ea-php81|yes|primary|www.pickledperil.com
    types: primary, addon, subdomain, alias, parked, remote

  WP: WordPress installations
    format: WP|domain|owner|path|db_name|db_user|version|plugin_count|theme_count
    example: WP|pickledperil.com|pickledperil|/home/pickledperil/public_html|pickledperil_wp_wt6lz|pickledperil_wp_user|6.8.3|1|3

  HEALTH: Health check baselines
    format: HEALTH|metric_name|value|date
    examples:
      HEALTH|MEMORY_TOTAL_MB|3776|2025-11-01
      HEALTH|CPU_LOAD_1MIN|2.4|2025-11-01
      HEALTH|DISK_USED_PERCENT|35|2025-11-01

query_functions:
  db_get_user(username)
  db_get_all_users()
  db_get_user_databases(username)
  db_get_user_domains(username)
  db_get_all_wordpress()
  db_store_wordpress(domain, owner, path, db_name, db_user, version, plugins, themes)

[MODULE_TEMPLATE]
# Standard template for creating new modules

file_location: /root/server-toolkit/modules/{category}/{name}.sh

template: |
  #!/bin/bash
  
  ################################################################################
  # Script Name
  ################################################################################
  # Purpose: Description
  # Features:
  # - Feature 1
  # - Feature 2
  ################################################################################
  
  # Path resolution (adjust based on depth)
  # modules/category/script.sh → ../../
  # modules/category/sub/script.sh → ../../../
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
  source "$SCRIPT_DIR/lib/common-functions.sh"
  source "$SCRIPT_DIR/lib/system-detect.sh"
  
  # Optional libraries (only if needed)
  # source "$SCRIPT_DIR/lib/user-manager.sh"
  # source "$SCRIPT_DIR/lib/reference-db.sh"
  # source "$SCRIPT_DIR/lib/ip-reputation.sh"
  
  # Root check
  if [ "$EUID" -ne 0 ]; then
      print_error "This script must be run as root"
      exit 1
  fi
  
  # Main logic
  clear
  print_banner "Script Name"
  
  echo ""
  echo "Script functionality here..."
  echo ""
  
  # ALWAYS provide cancel option
  echo "  0) Cancel and return to menu"
  echo ""
  read -p "Select option: " choice
  
  case $choice in
      0)
          echo "Operation cancelled."
          press_enter
          exit 0
          ;;
      # ... other options
  esac
  
  echo ""
  print_success "Completed"
  echo ""
  press_enter

steps_to_add_module:
  1: Create file in modules/{category}/{name}.sh
  2: chmod +x the file
  3: Add to launcher.sh in appropriate menu handler
  4: Test directly: bash /root/server-toolkit/modules/category/script.sh
  5: Test via launcher: bash /root/server-toolkit/launcher.sh
  6: Commit to git

mandatory_checklist:
  - [ ] Cancel option on ALL menus ("0) Cancel")
  - [ ] Cancel option on ALL text inputs ("or 0 to cancel")
  - [ ] press_enter() at end before exit
  - [ ] Use print_* functions (not echo for status)
  - [ ] Correct SCRIPT_DIR path resolution
  - [ ] Root check if needed
  - [ ] Error handling with proper exit codes
  - [ ] Test with bash -n (syntax check)

[WORDPRESS_CRON_MANAGER]
# New feature added 2025-11-07

location: modules/website/wordpress/wordpress-cron-manager.sh
purpose: Convert WordPress wp-cron to real system cron jobs

features:
  - Scan for all WordPress installations
  - Disable wp-cron per domain/user/server-wide
  - Add staggered system cron jobs (load distribution)
  - Revert to wp-cron
  - Check status

staggered_timing:
  purpose: Distribute cron load across 15-minute window
  pattern: Site 1=0,15,30,45 | Site 2=1,16,31,46 | Site 3=2,17,32,47
  formula: minute = (offset % 15), offset increments per site
  result: 300 sites = 20 sites per minute (manageable load)

wp-config_modification:
  function: disable_wpcron_in_config()
  location: Before "/* That's all, stop editing! */" comment (proper WordPress convention)
  fallback: After <?php tag if "stop editing" not found
  adds: define('DISABLE_WP_CRON', true);
  safety: Removes existing entries first, backup created, verification, rollback on failure
  format: User crontabs (crontab -u $user) not system crontab

domain_lookup_method:
  # Fixed 2025-11-10 - Two-step lookup process
  method_1: Check main_domain in /var/cpanel/userdata/*/main files (YAML: main_domain:)
  method_2: Fallback to search domain-specific files for servername (YAML: servername:)
  skip_files: "*.cache, */main, */cache, */cache.json"
  rationale: cPanel stores main_domain in main files, servername in domain-specific files

cron_job_format: |
  0,15,30,45 * * * * cd /home/user/public_html && /usr/bin/php -q wp-cron.php >/dev/null 2>&1

options:
  1: Scan for WordPress installations
  2: Disable wp-cron for specific domain
  3: Disable wp-cron for specific user (all their WP sites)
  4: Disable wp-cron server-wide (all WordPress sites)
  5: Check wp-cron status
  6: Re-enable wp-cron for specific domain
  7: Re-enable wp-cron for specific user
  8: Re-enable wp-cron server-wide
  0: Return to menu (cancel)

[RECENT_COMMITS]
# Latest changes (2025-11-10)

commit: 172a115
  date: 2025-11-10
  title: Fix domain lookup in WordPress Cron Manager
  files: modules/website/wordpress/wordpress-cron-manager.sh
  changes:
    - Fixed broken domain lookup (was only searching /var/cpanel/userdata/*/main for servername:)
    - Added two-step lookup: main_domain in main files, then servername in domain files
    - Applied fix to options 2, 5, 6 (all domain lookup locations)
    - Skip cache files during search
  testing: Verified with pickledperil.com - lookup now works correctly

# Latest changes (2025-11-07)

commit: 56776a1
  title: Add cancel/back options to all user input prompts
  files: website-error-analyzer.sh, 500-error-tracker.sh, wordpress-cron-manager.sh
  changes: Added "0) Cancel" to all menus, "(or 0 to cancel)" to all inputs

commit: b9ce90c
  title: Reorganize website management menu with WordPress subdirectory
  files: launcher.sh, wordpress-menu.sh, wordpress-cron-manager.sh
  changes: Created modules/website/wordpress/ subdirectory, WordPress submenu

commit: 4a1285d
  title: Add revert functionality to WordPress Cron Manager
  changes: Options 6,7,8 for reverting wp-cron changes

commit: e893171
  title: Add safe wp-config.php modification with validation
  changes: Created disable_wpcron_in_config() with backup/rollback

commit: c559bfe
  title: Add WordPress Cron Manager with intelligent load distribution
  changes: Initial WordPress cron manager implementation

[GIT_WORKFLOW]
# Standard git operations

check_status: git status
add_all: git add -A
commit_format: |
  git commit -m "$(cat <<'EOF'
  Brief summary (50 chars max)
  
  Changes:
  - Change 1
  - Change 2
  
  Tested:
  ✓ Test 1
  ✓ Test 2
  
  🤖 Generated with Claude Code
  https://claude.com/claude-code
  
  Co-Authored-By: Claude <noreply@anthropic.com>
  EOF
  )"

push: git push origin main

[BUGS_FIXED_HISTORY]
# Historical bug fixes - DO NOT REINTRODUCE

BUG_013: Brace redirection blocks variable assignment
  fix: Use exec file descriptor manipulation instead of { } >/dev/null
  location: lib/system-detect.sh:439-445

BUG_012: Cleanup not forcing fresh detection
  fix: Unset all SYS_* vars, re-source libraries
  location: launcher.sh:332-360

BUG_011: Duplicate menu display
  fix: Suppress auto-init output with exec redirect
  location: lib/system-detect.sh:433-445

BUG_010: System detection errors silently suppressed
  fix: Removed 2>/dev/null || true on critical functions
  location: lib/system-detect.sh:435

BUG_009: User list not displaying in selection
  fix: Redirect display to stderr, only username to stdout
  location: lib/user-manager.sh:330-408

BUG_008: Octal number error in timeline (hours 08/09)
  fix: Strip leading zeros with 10#$hour
  location: modules/security/bot-analyzer.sh:1154-1157

BUG_007: find -name pattern -o -name pattern syntax
  fix: find \( -name "*.log" -o -name "*access*" \)
  status: Feature disabled due to performance

BUG_006: Arithmetic operations causing exit
  fix: Changed ((current++)) to current=$((current + 1))
  files: Multiple locations

BUG_005: grep commands failing with set -e
  fix: Added || true to ALL grep in pipes
  files: lib/user-manager.sh, lib/reference-db.sh

[NEXT_PRIORITIES_2025_11_07]

immediate:
  1: Test WordPress cron manager on production server with multiple WP sites
  2: Create additional WordPress management tools (plugin/theme managers)
  3: Document all features in README.md

short_term:
  4: Implement Joomla/Drupal management menus (similar structure)
  5: Add more monitoring dashboards
  6: Expand reporting capabilities

long_term:
  7: Email/Slack alert integration
  8: Automated security scanning
  9: Performance trend analysis

[TESTING_CHECKLIST]

before_commit:
  - [ ] bash -n script.sh (syntax check)
  - [ ] Test cancel buttons (enter 0 at every prompt)
  - [ ] Test direct execution: bash /path/to/script.sh
  - [ ] Test via launcher menu navigation
  - [ ] Verify press_enter() at end
  - [ ] Check error handling
  - [ ] Confirm no debug output in production

after_commit:
  - [ ] git status (verify clean)
  - [ ] Test on fresh system (rm .sysref*)
  - [ ] Update this file (REFDB_FORMAT.txt)
  - [ ] Update README.md if user-facing feature

[FOR_NEW_CLAUDE_INSTANCES]
# Quick onboarding for new sessions

step1_read_this_section_first: |
  You are maintaining the Server Management Toolkit.
  This file (REFDB_FORMAT.txt) is your ONLY reference document.
  README.md is for users, this file is for you.

step2_understand_current_state: |
  Read [STATUS_SNAPSHOT_2025_11_07] to know what works.
  Read [CRITICAL_DESIGN_RULES] - these are mandatory.
  Read [CANCEL_BUTTON_STANDARD] - every script must have this.

step3_file_locations: |
  Use [KEY_FILES_QUICK_MAP] to find things fast.
  Use [DIRECTORY_STRUCTURE_2025_11_07] for overall layout.

step4_making_changes: |
  Follow [MODULE_TEMPLATE] for new scripts.
  Follow [GIT_WORKFLOW] for commits.
  Check [TESTING_CHECKLIST] before committing.

step5_update_this_file: |
  After making changes, update:
  - [STATUS_SNAPSHOT_2025_11_07]
  - [RECENT_COMMITS]
  - [NEXT_PRIORITIES_2025_11_07]
  - [META] updated date

critical_rules_never_break:
  - Every menu MUST have "0) Cancel"
  - Every text input MUST accept "0" to cancel
  - Always call press_enter() at script end
  - Use print_* functions not echo for status
  - Add || true to grep/find that might not match
  - Never use set -u (too strict)
  - Never use { } >/dev/null on critical functions

[SHARED_RESOURCES]

ip_reputation:
  file: lib/ip-reputation.sh
  functions: is_known_bot(), should_filter_ip(), log_ip_threat()
  purpose: Centralized IP tracking across all security modules

reference_database:
  file: lib/reference-db.sh
  storage: /root/server-toolkit/.sysref
  ttl: 1 hour
  purpose: Cross-module intelligence sharing (WordPress, domains, users, health)

user_manager:
  file: lib/user-manager.sh
  function: select_user_interactive("Prompt text")
  features: Arrow-key menu, search (type S [text]), domain display
  returns: $SELECTED_USER variable

common_functions:
  file: lib/common-functions.sh
  functions: print_banner(), print_success(), print_error(), print_warning(), print_info(), press_enter()
  colors: GREEN, RED, YELLOW, CYAN, BOLD, NC (auto-disabled if not TTY)

[END]
# This file is the ONLY developer reference document.
# README.md is for users, this file is for developers (Claude).
# Keep this updated after every significant change.
# Last updated: 2025-11-07
################################################################################