wiki/ssh-mcp/BACKUP_GUIDE.md

← [Home](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:**

```json
{
  "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"
```

```json
{
  "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"
```

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

### Files Backup

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

```json
{
  "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"
```

```json
{
  "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`:

```bash
#!/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:

```bash
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:

```sql
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:

```sql
CREATE DATABASE myapp_restored CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### Scheduled backup not running

Check cron logs and permissions:

```bash
# 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_GUIDE) -- Deployment workflows
- [Aliases and Hooks](ALIASES_AND_HOOKS) -- Automation and hooks
- [Home](Home) -- Getting started

---

*Repo: [ssh-mcp](https://git.mokoconsulting.tech/MokoConsulting/ssh-mcp) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

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