Skip to content

Latest commit

 

History

History
486 lines (334 loc) · 14.7 KB

INSTALL.md

File metadata and controls

486 lines (334 loc) · 14.7 KB

ProxSave Installation Guide

📑 Table of Contents

Fast Install

Direct Install

  1. Download & start Install

    bash -c "$(curl -fsSL https://raw.githubusercontent.com/tis24dev/proxsave/main/install.sh)"

    or: if you need a fully clean reinstall use: (preserves build/, env/, and identity/)

    bash -c "$(curl -fsSL https://raw.githubusercontent.com/tis24dev/proxsave/main/install.sh)" _ --new-install

  2. Run your first backup

    ./build/proxsave

Migration

  1. Run migration installation from bash with old env file

    ./build/proxsave --env-migration

  2. Run your first backup again after migration

    ./build/proxsave

First Backup Workflow

# Dry-run test (no actual changes)
./build/proxsave --dry-run

# Real backup
./build/proxsave

# View logs
tail -f log/backup-$(hostname)-*.log

# Check backup files
ls -lh backup/

Upgrading ProxSave Binary

ProxSave provides a built-in upgrade command to update your installation to the latest release from GitHub.

Quick Upgrade

# Upgrade to latest version
./build/proxsave --upgrade

# Non-interactive upgrade (auto-confirm)
./build/proxsave --upgrade y

# Optionally update configuration template
./build/proxsave --upgrade-config

# Verify everything works
./build/proxsave --dry-run

What Gets Updated

The --upgrade command:

  • ✅ Downloads latest binary from GitHub releases
  • ✅ Verifies integrity with SHA256 checksums
  • ✅ Atomically replaces current binary
  • ✅ Updates symlinks (/usr/local/bin/proxsave, /usr/local/bin/proxmox-backup)
  • ✅ Cleans up legacy Bash script symlinks
  • ✅ Migrates cron entries to new binary while preserving entries that already point to the Go executable
  • ✅ Fixes file permissions
  • ❌ Does NOT modify your backup.env configuration

Full Upgrade Workflow

# 1. Upgrade binary
./build/proxsave --upgrade

# 2. (Optional) Update configuration with new template variables
./build/proxsave --upgrade-config

# 3. Test configuration
./build/proxsave --dry-run

# 4. Verify cron schedule
crontab -l

# 5. Run a real backup to confirm
./build/proxsave

Requirements

  • Internet connection: Must reach GitHub releases
  • Platform: Linux (amd64 or arm64)
  • Permissions: Root/sudo access recommended

Troubleshooting

If upgrade fails:

  1. Check internet connectivity: curl -I https://github.com
  2. Verify GitHub is reachable: curl -I https://api.github.com
  3. Check disk space: df -h /opt/proxsave
  4. Review logs for specific errors

For more details, see CLI Reference - Binary Upgrade.

Manual Installation

Allows you to compile your binary file from individual project files.

Prerequisites

# Install Go (if building from source)
wget https://go.dev/dl/go1.25.4.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.25.4.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Install rclone (for cloud storage)
curl https://rclone.org/install.sh | bash

# Install git
apt update && apt install -y git

# Install make
apt update && apt install -y make

# Verify installations
go version    # Should show go1.25+
rclone version  # Should show rclone v1.50+
git --version # Should show git 2.47.3+
make --version # Should show make 4.4.1+

Building from Source

# Create folder
mkdir /opt/proxsave

# Navigate to project directory
cd /opt/proxsave

# Copy from github
git clone --branch main https://github.com/tis24dev/proxsave.git .

# Download dependencies
go mod tidy

# Build binary
make build

# Verify build
./build/proxsave --version

Interactive Installation Wizard

The installation wizard creates your configuration file interactively:

./build/proxsave --install

# Or perform a clean reinstall (keeps build/, env/, and identity/)
./build/proxsave --new-install

If the configuration file already exists, the TUI wizard will ask whether to:

  • Overwrite (start from the embedded template)
  • Edit existing (use the current file as base and pre-fill the wizard fields)
  • Keep & exit (leave the file untouched and exit)

Wizard prompts:

  1. Configuration file path: Default configs/backup.env (accepts absolute or relative paths within repo)
  2. Secondary storage: Optional path for backup/log copies
  3. Cloud storage (rclone): Optional rclone configuration (supports CLOUD_REMOTE as a remote name (recommended) or legacy remote:path; CLOUD_LOG_PATH supports path-only (recommended) or otherremote:/path)
  4. Firewall rules: Optional firewall rules collection toggle (BACKUP_FIREWALL_RULES=false by default; supports iptables/nftables)
  5. Notifications: Enable Telegram (centralized) and Email notifications (wizard defaults to EMAIL_DELIVERY_METHOD=relay; you can switch to sendmail or pmf later)
  6. Encryption: AGE encryption setup (runs sub-wizard immediately if enabled)
  7. Cron schedule: Choose cron time (HH:MM) for the proxsave cron entry (TUI mode only)
  8. Post-install check (optional): Runs proxsave --dry-run and shows actionable warnings like set BACKUP_*=false to disable, allowing you to disable unused collectors and reduce WARNING noise
  9. Telegram pairing (optional): If Telegram (centralized) is enabled, shows your Server ID and lets you verify pairing with the bot (retry/skip supported)

Telegram pairing wizard (TUI)

If you enable Telegram notifications during --install (centralized bot), the installer opens an additional Telegram Setup screen after the post-install check.

It does not modify your backup.env. It only:

  • Computes/loads the Server ID and persists it (identity file)
  • Guides you through pairing with the centralized bot
  • Lets you verify pairing immediately (retry supported)

What you see:

  • Instructions: steps to start the bot and send the Server ID
  • Server ID: digits-only identifier + identity file path/persistence status
  • Status: live feedback from the pairing check
  • Actions:
    • Check: verify pairing (press again to retry)
    • Continue: available only after a successful check (centralized mode), or immediately in personal mode / when the Server ID is unavailable
    • Skip: leave without verification (in centralized mode, ESC behaves like Skip when not verified)

Where the Server ID is stored:

  • <BASE_DIR>/identity/.server_identity

If Check fails:

  • 403 / 409: start the bot, send the Server ID, then try again
  • 422: the Server ID looks invalid; re-run the installer or regenerate the identity file
  • Other errors: temporary server/network issue; retry or skip and pair later

CLI mode:

  • With --install --cli, the installer prints the Server ID and asks whether to run the check now (with a retry loop).

Features:

  • Input sanitization (no newlines/control characters)
  • Template comment preservation
  • Creates all necessary directories with proper permissions (0700)
  • Immediate AGE key generation if encryption is enabled
  • Optional post-install audit to disable unused collectors (keeps changes explicit; nothing is disabled silently)
  • Optional Telegram pairing wizard (centralized mode) that displays Server ID and verifies the bot registration (retry/skip supported)
  • Install session log under /tmp/proxsave/install-*.log (includes audit results and Telegram pairing outcome)

After completion, edit configs/backup.env manually for advanced options.

Upgrading from Previous Bash Version (v0.7.4-bash or Earlier)

If you're currently using the legacy Bash version (historically called proxmox-backup, v0.7.4-bash or earlier), you can upgrade to the Go-based proxsave release with minimal effort. The Go version offers significant performance improvements while maintaining backward compatibility for most configuration variables.

Migration Tools

Option 1: Interactive Tool

Automatic tool based on variable mapping: BACKUP_ENV_MAPPING.md (we recommend checking after migration to ensure everything went smoothly)

./build/proxsave --env-migration

You can then manually add your custom variables by referring to the mapping guide.

Option 2: Migration Reference Guide

The project includes a complete environment variable mapping guide to help you migrate your configuration:

BACKUP_ENV_MAPPING.md - Complete Bash → Go variable mapping reference

This guide categorizes every variable:

  • SAME: Variables with identical names (just copy them)
  • RENAMED: Variables with new names but automatic fallback (old names still work)
  • SEMANTIC CHANGE: Variables requiring value conversion (e.g., percentage → GB)
  • LEGACY: Bash-only variables no longer needed in Go

Quick migration workflow:

  1. Open your Bash backup.env
  2. Open your Go backup.env
  3. Refer to BACKUP_ENV_MAPPING.md while copying your values
  4. Most variables can be copied directly (SAME + RENAMED categories)
  5. Pay attention to SEMANTIC CHANGE variables for manual conversion

Upgrade Steps

  1. Run 1 minute Setup or Full manually Setup

  2. Migrate your configuration

    Option A: Automatic migration (recommended for existing users)

    # Step 1: Preview migration (recommended first step)
./build/proxsave --env-migration-dry-run

# Review the output, then execute real migration
./build/proxsave --env-migration

# The tool will:
# - Automatically map 70+ variables (SAME category)
# - Convert 16 renamed variables (RENAMED category)
# - Flag 2 variables for manual review (SEMANTIC CHANGE)
# - Skip 27 legacy variables (LEGACY category)
# - Create backup of existing config

    Option B: Manual migration using mapping guide

    # Edit with your Bash settings, using BACKUP_ENV_MAPPING.md as reference
nano configs/backup.env

  3. Test the configuration

    # Dry-run to verify configuration
./build/proxsave --dry-run

# Check the output for any warnings or errors

  4. Run a test backup

    # First real backup
./build/proxsave

# Verify results
ls -lh backup/
cat log/backup-*.log

Key Migration Notes

Automatic variable fallbacks - These old Bash variable names still work in Go:

  • LOCAL_BACKUP_PATH ? reads as BACKUP_PATH
  • ENABLE_CLOUD_BACKUP ? reads as CLOUD_ENABLED
  • PROMETHEUS_ENABLED ? reads as METRICS_ENABLED
  • And 13 more (see mapping guide for complete list)

Variables requiring conversion:

  • STORAGE_WARNING_THRESHOLD_PRIMARY="90" (% used) ? MIN_DISK_SPACE_PRIMARY_GB="1" (GB free)
  • CLOUD_BACKUP_PATH="/remote:path/folder" (full path) ? CLOUD_REMOTE="<remote>" + CLOUD_REMOTE_PATH="/folder"

New Go-only features available:

  • GFS retention policies (RETENTION_POLICY=gfs)
  • AGE encryption (ENCRYPT_ARCHIVE=true)
  • Parallel cloud uploads (CLOUD_UPLOAD_MODE=parallel)
  • Advanced security checks with auto-fix
  • Gotify and webhook notifications
  • Prometheus metrics export

Troubleshooting Migration

Problem: "Configuration variable not recognized"

  • Solution: Check BACKUP_ENV_MAPPING.md to see if the variable was renamed or is now LEGACY

Problem: Storage threshold warnings incorrect

  • Solution: Convert percentage-based thresholds to GB-based (SEMANTIC CHANGE variables)

Problem: Cloud path not working

  • Solution: Split CLOUD_BACKUP_PATH into CLOUD_REMOTE (remote name) and CLOUD_REMOTE_PATH (full path inside that remote)

Still having issues?

  • Review the complete mapping guide: BACKUP_ENV_MAPPING.md
  • Compare your Bash config with the Go template side-by-side
  • Enable debug logging: ./build/proxsave --dry-run --log-level debug

Legacy Bash Version (v0.7.4-bash)

The original Bash script (20,370 lines) has been moved to the old branch and is no longer actively developed. However, it remains available for users who need it.

Availability

  • Source code: Available in the old branch of this repository
  • Installation script: The install.sh file remains in the main branch for backward compatibility

Installing the Legacy Bash Version

The legacy Bash version can still be installed using the original installation command:

Option 1: Fast Bash Legacy Install or Update or Reinstall

bash -c "$(curl -fsSL https://raw.githubusercontent.com/tis24dev/proxsave/old/install.sh)"

Option 2: Manual

Enter the /opt directory

cd /opt

Download the repository (stable release)

wget https://github.com/tis24dev/proxsave/archive/refs/tags/v0.7.4-bash.tar.gz

Create the script directory

mkdir -p proxsave

Extract the script files into the newly created directory, then delete the archive

tar xzf v0.7.4-bash.tar.gz -C proxsave --strip-components=1 && rm v0.7.4-bash.tar.gz

Enter the script directory

cd proxsave

Start the installation (runs initial checks, creates symlinks, creates cron)

./install.sh

Customize your settings

nano env/backup.env

Run first backup

./script/proxmox-backup.sh

Important Notes:

  • Bash version only: The legacy installer (old branch) installs the Bash version (v0.7.4-bash), not the Go version.
  • For the Go version: Use the one-liner in the Fast Install section or build from source in Manual Installation.

Legacy vs Go Version

Feature Legacy Bash (v0.7.4) Go Version (v0.9.0+)
Status Maintenance mode (old branch) Active development (main branch)
Installation install.sh script Build from source
Performance Slower (shell overhead) 10-20x faster (compiled)
Code size 20,370 lines ~3,000 lines Go code
Memory usage Higher (multiple processes) Lower (single binary)
Maintenance Archived, critical fixes only Active development
Compatibility Can coexist with Go version Can coexist with Bash version