wiki/ssh-mcp/BACKUP_GUIDE.md

← Home

Backup and Restore Guide

Complete guide for using the ssh-mcp backup and restore system.

---

Overview

The backup system provides automated backup and restore capabilities for:

• MySQL databases
• PostgreSQL databases
• MongoDB databases
• Files and directories
• Scheduled automatic backups via cron

All backups are compressed by default, include metadata for easy management, and support automatic retention policies.

---

Available Tools

1. ssh_backup_create -- Create Backup

Create a one-time backup of a database or files.

Parameter	Type	Required	Description
server	string	Yes	Server name
type	enum	Yes	mysql, postgresql, mongodb, files
name	string	Yes	Backup name (e.g., production, app-data)
database	string	Cond.	Database name (required for db types)
dbUser	string	No	Database username
dbPassword	string	No	Database password
dbHost	string	No	Database host (default: localhost)
dbPort	number	No	Database port
paths	array	Cond.	File paths to backup (required for files type)
exclude	array	No	Patterns to exclude from backup
backupDir	string	No	Backup directory (default: /var/backups/ssh-manager)
retention	number	No	Retention period in days (default: 7)
compress	boolean	No	Compress backup (default: true)

Example response:

{
  "success": true,
  "backup_id": "mysql_production_2025-10-01T10-30-45-000Z_abc123de",
  "type": "mysql",
  "size": 52428800,
  "size_human": "50.00 MB",
  "location": "/var/backups/ssh-manager/mysql_production_2025-10-01T10-30-45-000Z_abc123de.gz",
  "created_at": "2025-10-01T10:30:45.000Z",
  "retention_days": 7
}

2. ssh_backup_list -- List Backups

List all available backups on a server.

Parameter	Type	Required	Description
server	string	Yes	Server name
type	enum	No	Filter by type: mysql, postgresql, mongodb, files
backupDir	string	No	Backup directory (default: /var/backups/ssh-manager)

3. ssh_backup_restore -- Restore Backup

Restore from a previous backup.

Parameter	Type	Required	Description
server	string	Yes	Server name
backupId	string	Yes	Backup ID to restore
database	string	No	Target database name (overrides original)
dbUser	string	No	Database username
dbPassword	string	No	Database password
dbHost	string	No	Database host
dbPort	number	No	Database port
targetPath	string	No	Target path for files restore (default: /)
backupDir	string	No	Backup directory

4. ssh_backup_schedule -- Schedule Automatic Backups

Schedule recurring backups using cron.

Parameter	Type	Required	Description
server	string	Yes	Server name
schedule	string	Yes	Cron schedule (e.g., "0 2 * * *" for daily at 2 AM)
type	enum	Yes	Backup type
name	string	Yes	Backup name
database	string	No	Database name (for db types)
paths	array	No	Paths to backup (for files type)
retention	number	No	Retention in days (default: 7)

---

Usage Examples

MySQL Backup

"Create a MySQL backup of the production database"

{
  "server": "production",
  "type": "mysql",
  "name": "prod-db",
  "database": "myapp_prod",
  "dbUser": "backup_user",
  "dbPassword": "secure_password"
}

PostgreSQL Backup with Custom Retention

"Backup PostgreSQL database and keep it for 30 days"

{
  "server": "staging",
  "type": "postgresql",
  "name": "staging-db",
  "database": "myapp_staging",
  "retention": 30
}

Files Backup

"Backup the /var/www/html directory, excluding cache and logs"

{
  "server": "web01",
  "type": "files",
  "name": "website-files",
  "paths": ["/var/www/html"],
  "exclude": ["cache/*", "*.log"]
}

Schedule Daily Backup at 2 AM

"Schedule daily MySQL backup of production database at 2 AM"

{
  "server": "production",
  "schedule": "0 2 * * *",
  "type": "mysql",
  "name": "daily-prod",
  "database": "myapp_prod",
  "retention": 7
}

---

Cron Schedule Reference

Schedule	Description
0 2 * * *	Daily at 2:00 AM
0 */6 * * *	Every 6 hours
0 0 * * 0	Weekly on Sunday at midnight
0 3 1 * *	Monthly on the 1st at 3:00 AM
0 1 * * 1-5	Weekdays at 1:00 AM
*/30 * * * *	Every 30 minutes

---

Database-Specific Notes

MySQL

• Uses mysqldump with --single-transaction for consistent backups.
• Includes routines and triggers.
• No table locking for InnoDB tables.
• Compressed with gzip.
• Default host: localhost, default port: 3306.

PostgreSQL

• Uses pg_dump with custom format.
• Includes --clean and --if-exists for safe restores.
• Compressed with gzip.
• Uses PGPASSWORD environment variable.
• Default host: localhost, default port: 5432.

MongoDB

• Uses mongodump for database dumps.
• Creates directory structure, then archives with tar.
• Compressed with gzip.
• Default host: localhost, default port: 27017.

---

File Backup Notes

• Uses tar with gzip compression.
• Supports multiple paths in a single backup.
• Exclude patterns use tar's --exclude syntax.
• Preserves permissions and ownership.
• Follows symlinks by default.

Common exclude patterns:

Pattern	Excludes
*.log	All log files
cache/*	Everything in cache directories
node_modules/	Node modules directory
*.tmp	All temporary files

---

Hooks Integration

The backup system integrates with the hooks system. Available hooks:

Hook	Trigger	Context Variables
pre-backup	Before backup starts	server, type, database, paths
post-backup	After backup completes	server, backupId, type, size, success, error
pre-restore	Before restore starts	server, backupId, type, database
post-restore	After restore completes	server, backupId, type, success, error

Example Hook: Slack Notification

Create ~/.ssh-manager/hooks/post-backup.sh:

#!/bin/bash
# Send Slack notification after backup

if [ "$HOOK_success" = "true" ]; then
  curl -X POST -H 'Content-type: application/json' \
    --data "{\"text\":\"Backup completed: $HOOK_backupId ($HOOK_size_human)\"}" \
    https://hooks.slack.com/services/YOUR/WEBHOOK/URL
fi

---

Best Practices

Security

• Never store passwords in code -- use environment variables or .env files.
• Use SSH keys for automated backups instead of passwords.
• Restrict backup directory permissions: chmod 700 /var/backups/ssh-manager
• Encrypt sensitive backups -- add GPG encryption for critical data.

Retention Policy Guidelines

Environment	Recommended Retention
Development	3--7 days
Staging	7--14 days
Production	30+ days
Compliance	Per regulatory requirements (GDPR, HIPAA, etc.)

Testing

• Test restores regularly -- monthly restore tests at minimum.
• Verify backup integrity -- check file sizes and metadata.
• Document restore procedures -- keep runbooks updated.
• Monitor backup success -- set up alerts for failures.

Storage

• Monitor disk space -- ensure adequate space for retention period.
• Use compression -- saves 60--80% space typically.
• Consider remote storage -- sync backups to S3/cloud storage.
• Implement 3-2-1 rule -- 3 copies, 2 different media, 1 offsite.

Scheduling

• Avoid peak hours -- schedule during low-traffic periods.
• Stagger backups -- do not backup all servers simultaneously.
• Consider backup windows -- large databases may take hours.
• Monitor backup duration -- track and optimize slow backups.

---

Troubleshooting

Backup fails with "Permission Denied"

Ensure the backup directory exists and is writable:

sudo mkdir -p /var/backups/ssh-manager
sudo chown $(whoami):$(whoami) /var/backups/ssh-manager
sudo chmod 700 /var/backups/ssh-manager

MySQL backup shows "Access Denied"

Check user permissions:

GRANT SELECT, LOCK TABLES, SHOW VIEW ON myapp_prod.* TO 'backup_user'@'localhost';
FLUSH PRIVILEGES;

Restore fails with "Database Does Not Exist"

Create the target database first:

CREATE DATABASE myapp_restored CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Scheduled backup not running

Check cron logs and permissions:

# View cron logs
sudo tail -f /var/log/syslog | grep CRON

# Check if script is executable
ls -la /usr/local/bin/ssh-manager-backup-*.sh

# Test script manually
sudo /usr/local/bin/ssh-manager-backup-production.sh

Backup size too large

• Verify compression is enabled (compress: true).
• Exclude unnecessary tables or files.
• Consider incremental backups (manual implementation).
• Archive old data before backup.

---

Monitoring Backups

"List all backups on production server"
"Execute 'crontab -l' on production"
"Execute 'df -h /var/backups' on production"
"Execute 'du -sh /var/backups/ssh-manager' on production"

---

Quick Reference

Daily Backup Workflow

1. Create backup before deployment: "Backup production MySQL database before deployment"
2. Deploy changes: "Deploy latest code to production"
3. If rollback needed: "List MySQL backups and restore the latest one"

Disaster Recovery

1. List available backups: "List all backups on production server"
2. Restore most recent backup: "Restore backup [backup-id-here]"
3. Verify restoration: "Run database integrity check on production"

---

Related Documentation

• Deployment Guide -- Deployment workflows
• Aliases and Hooks -- Automation and hooks
• Home -- Getting started

---

Repo: ssh-mcp · MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version