🛡️ Ancient-Backup

The most advanced backup solution for Minecraft servers

---

✨ Features

🚀 High-Performance Compression

• ZSTD Compression: 3-5x faster than traditional ZIP with better compression ratios
• Adjustable Levels: Balance between speed and file size (0-9)
• Streaming Mode: Compress and upload simultaneously with zero local disk usage

📤 Multiple Upload Destinations

• SFTP - Secure FTP with SSH encryption (recommended)
• FTPS - FTP over TLS/SSL
• OneDrive/SharePoint - Microsoft Graph API integration
• Google Drive - Direct cloud upload support

🔄 Smart Upload Management

• Parallel Uploads: Upload to multiple destinations simultaneously
• Resume Support: Automatically resume interrupted uploads (SFTP/FTPS)
• Adaptive Throttling: Reduces backup speed if server TPS drops to prevent lag
• Upload Retry: Manual /abackup uploadlast command to retry failed uploads

📊 Real-Time Progress Tracking

• Live Console Output: See compression and upload progress every 5 seconds
• Discord Webhooks: Beautiful embeds with progress bars and statistics
• Speed Monitoring: Real-time MB/s tracking for uploads and compression

🎯 Advanced Features

• File Exclusions: Skip large folders like dynmap tiles or BlueMap renders using glob patterns
• Automatic Retention: Keep only the last N backups on remote servers
• Flexible Scheduling: Run backups every X minutes or at specific times daily
• World Save Safety: Automatically disables auto-save during backups to prevent corruption
• Memory Management: Automatic RAM cleanup after backups complete
• Staff Notifications: In-game notifications for players with permission

🔒 Security & Reliability

• Strict Host Key Checking: Verify SFTP server fingerprints to prevent MITM attacks
• SSH Key Authentication: Use private keys instead of passwords
• TLS/SSL Support: Encrypted connections for FTPS
• Cancellable Backups: Stop backups mid-process with /abackup cancel

---

📋 Requirements

• Server Software: Paper/Spigot/Bukkit 1.20.6+
• Java: 21 or higher
• Permissions: ancientbackup.admin for commands, ancientbackup.notify for notifications

---

🚀 Quick Start

Installation

1. Download the latest version from Modrinth
2. Place the JAR file in your plugins/ folder
3. Restart your server
4. Configure plugins/Ancient-Backup/config.yml

Basic Configuration

backup:
  use-zstd: true          # Enable ZSTD compression (recommended)
  zip-level: 1            # 1 = fast, 9 = smallest file

schedule:
  enabled: true           # Enable automatic backups
  every-minutes: 360      # Backup every 6 hours

upload:
  sftp:
    enabled: true
    host: "your-server.com"
    port: 22
    username: "backup-user"
    password: "your-password"
    remote-folder: "/backups/minecraft"

First Backup

Run your first backup with:

/abackup start

Check status with:

/abackup status

---

📦 Commands

Command	Permission	Description
/abackup start	ancientbackup.admin	Start a new backup
/abackup cancel	ancientbackup.admin	Cancel the running backup
/abackup status	ancientbackup.admin	Check backup progress
/abackup uploadlast	ancientbackup.admin	Retry uploading the last backup
/abackup reload	ancientbackup.admin	Reload configuration

---

🎨 Discord Integration

Get beautiful real-time updates in Discord:

discord:
  enabled: true
  webhook-url: "https://discord.com/api/webhooks/..."
  notifications:
    on-backup-start: true
    on-zip-complete: true
    on-upload-start: true
    on-upload-complete: true
    on-backup-complete: true

Features:

• 📊 Color-coded embeds for different phases
• 📈 Visual progress bars
• ⚡ Real-time speed and ETA
• 🎯 Step-by-step progress tracking (1/5, 2/5, etc.)

---

⚙️ Advanced Configuration

File Exclusions

Exclude large folders to reduce backup size:

backup:
  exclude:
    - "logs/*.gz"
    - "logs/*.log.*"
    - "plugins/dynmap/web/tiles/**"
    - "plugins/BlueMap/web/**"
    - "**/cache/**"

Streaming Mode

Compress and upload simultaneously (no local file):

upload:
  streaming-compression: true  # Requires SFTP or FTPS

Benefits:

• ⚡ Faster overall backup time
• 💾 No local disk space usage
• 🔄 Real-time progress updates

Limitations:

• ⚠️ Retention policies not supported in streaming mode
• 📍 Requires SFTP or FTPS destination

Performance Tuning

Optimize for your server:

performance:
  max-memory-mb: 512          # Maximum RAM usage
  max-buffer-kb: 8192         # Buffer size for compression
  gc-after-zip: true          # Free memory after compression
  cleanup-after-backup: true  # Full memory cleanup
  tps-threshold: 18.0         # Slow down if TPS drops below this

Retention Policies

Automatically delete old backups:

retention:
  enabled: true
  keep-last: 7                # Keep only the last 7 backups
  filename-prefix: "backup-"  # Filter files by prefix
  filename-suffix: ".tar.zst" # Filter files by extension

---

🔐 SSH Key Authentication

For enhanced security, use SSH keys instead of passwords:

1. Generate an SSH key:

   ssh-keygen -t ed25519 -f ~/.ssh/minecraft_backup
   

2. Add the public key to your server:

   ssh-copy-id -i ~/.ssh/minecraft_backup.pub [email protected]
   

3. Configure Ancient-Backup:

   sftp:
     private-key-path: "plugins/Ancient-Backup/minecraft_backup"
     password: ""  # Leave empty when using key auth
   

---

📊 Performance

Benchmark Results

Tested on a 10GB Minecraft server with Paper 1.21.10:

Method	Time	CPU Usage	Disk I/O
ZSTD Level 1	2m 15s	Low	Minimal
ZIP Level 1	6m 30s	Medium	Medium
ZIP Level 9	12m 45s	High	High

Streaming Mode: Reduces total backup time by 30-40% compared to traditional mode.

---

🐛 Troubleshooting

No progress output?

• Ensure you're using the latest version
• Check that your upload destination is properly configured
• Look for error messages in the console

Upload fails?

• Use /abackup uploadlast to retry
• Check network connectivity and credentials
• Enable debug logging in config.yml

Server lags during backup?

• Lower performance.max-buffer-kb to reduce memory usage
• Reduce backup.zip-level to use less CPU
• Set performance.tps-threshold higher to trigger throttling sooner

Discord notifications not working?

• Verify webhook URL is correct
• Test webhook manually using curl or online tools
• Check that discord.enabled: true

---

🤝 Support

• Issues: GitHub Issues
• Discord: Join our Discord Server
• Documentation: Wiki

---

📝 License

This plugin is released under the MIT License. See LICENSE for details.

---

⭐ Support the Project

If you find Ancient-Backup useful, please consider:

• ⭐ Starring the project on GitHub
• 📢 Sharing it with other server owners
• 💬 Leaving a review on Modrinth
• ☕ Supporting development

---

Made with ❤️ for the Minecraft community