DataMasque Portal

Backup and Restore

This guide covers how to back up and restore your DataMasque instance to protect against data loss during upgrades, migrations, or disaster recovery scenarios.

Overview

Before performing upgrades, downgrades, or migrations, it is strongly recommended to take a complete backup of your DataMasque instance. This ensures you can recover your configuration and data if anything goes wrong.

Important: Always test your backup and restore procedures in a non-production environment before relying on them for production systems.

Requirements

Before creating a backup, ensure you have:

  • At least 500 MB free disk space (more for larger deployments with many rulesets and run history).
  • Root or sudo access to run the backup/restore scripts.
  • DataMasque containers running.

Typical backup sizes:

Component Typical Size
Database (small deployment) 5-50 MB
Database (large deployment) 100-500 MB
Secrets (encryption keys, JWT key, instance secret) < 10 KB
License file < 10 KB
Files (seed files, uploads) Varies by usage
SSL certificates < 100 KB

Using the Backup and Restore Scripts

DataMasque includes backup and restore scripts that are installed alongside the application. These scripts provide a simple way to create complete backups and restore them when needed.

The scripts are located in the DataMasque installation directory (default: /usr/local/etc/datamasque/):

  • datamasque-backup.sh - Creates a complete backup of your DataMasque instance
  • datamasque-restore.sh - Restores a DataMasque instance from a backup

Creating a Backup

To create a complete backup of your DataMasque instance:

# Navigate to the DataMasque installation directory
# (default: /usr/local/etc/datamasque - adjust to your installation path)
cd /usr/local/etc/datamasque

# Run the backup script (creates a timestamped backup directory)
sudo ./datamasque-backup.sh

# Or specify a custom backup directory name
sudo ./datamasque-backup.sh my_backup_folder

The backup will be created in the current working directory. The script will:

  1. Check available disk space
  2. Back up the PostgreSQL database
  3. Back up the instance secret and JWT key
  4. Back up the license file
  5. Back up seed files and user uploads
  6. Back up in-flight data (if present)
  7. Back up SSL certificates (if present)
  8. Generate SHA256 checksums for verification
  9. Create a manifest file with backup metadata
  10. Encrypt the backup with a password (recommended)

Backup Encryption

After creating the backup, the script will prompt for an encryption password. Encryption is enabled by default to protect sensitive data. To skip encryption (not recommended), type skip when prompted for a password.

Encrypted backups:

  • Use AES-256-CBC encryption via openssl
  • Combine all backup files into a single encrypted archive
  • Cannot be restored without the encryption password

Security Note: The backup contains sensitive cryptographic keys. If not using encryption, the backup directory is created with restrictive permissions (700). Store backups securely and follow your organisation's data protection policies.

Restoring from a Backup

To restore DataMasque from a backup:

# Navigate to the DataMasque installation directory
cd /usr/local/etc/datamasque

# Restore from an unencrypted backup directory
sudo ./datamasque-restore.sh /path/to/datamasque_backup_20240115_120000

# Or restore from an encrypted backup file
sudo ./datamasque-restore.sh /path/to/datamasque_backup_20240115_120000.tar.gz.enc

For encrypted backups, the script will prompt for the decryption password before proceeding.

Warning: Restoring will overwrite all existing DataMasque data. The script will prompt for confirmation before proceeding.

The restore script will:

  1. Verify backup checksums (if available)
  2. Display the backup manifest
  3. Stop the DataMasque services
  4. Restore the instance secret and JWT key
  5. Restore the license file (if present in backup)
  6. Restore seed files and user uploads
  7. Restore in-flight data and SSL certificates
  8. Restore the database
  9. Restart all DataMasque services
  10. Verify the restore was successful

Verifying a Restore

After a restore completes, verify it was successful:

  1. Check the script output. The restore script performs automatic verification and reports any issues.

  2. Access the web interface and verify:

    • Your user account works.
    • Rulesets are present.
    • Database connections are configured.
    • Run history is intact.

  3. Test a masking run. If possible, run a test masking operation to confirm full functionality.

  4. Verify deterministic masking. If you use deterministic masking, verify that masked values match expected outputs from before the backup.

What Gets Backed Up

The backup script creates a directory containing:

File Description
database.sql PostgreSQL database dump (rulesets, connections, users, run history, etc.)
secrets.tar Encryption keys, JWT key, and instance secret (/.keys directory)
license.tar License file (/license directory)
files.tar Seed files and user uploads
in_flight_data.tar In-flight masking server data (if present)
certs.tar SSL certificates (if present)
checksums.sha256 SHA256 checksums for integrity verification
manifest.txt Backup manifest with metadata and DataMasque version

Backup Methods by Deployment Type

AWS EC2 Deployments

For AWS EC2 deployments, you can use either the backup scripts or create an AMI snapshot.

cd /usr/local/etc/datamasque
sudo ./datamasque-backup.sh

Creating an AMI Snapshot (full instance backup)

  1. Navigate to the EC2 Console
  2. Select your DataMasque instance
  3. Choose Actions > Image and templates > Create image
  4. Provide a name and description for the image
  5. Click Create image

Note: Creating an AMI will briefly stop the instance. Schedule backups during maintenance windows to minimise disruption.

Azure VM Deployments

For Azure deployments, you can use either the backup scripts or Azure VM snapshots.

cd /usr/local/etc/datamasque
sudo ./datamasque-backup.sh

Creating a VM Snapshot (full instance backup)

  1. Navigate to the Azure Portal
  2. Go to your DataMasque virtual machine
  3. Select Disks from the left menu
  4. Select the OS disk
  5. Click Create snapshot
  6. Provide a name and configure snapshot settings
  7. Click Create

Docker/Podman Deployments

For Docker or Podman deployments, use the included backup and restore scripts:

# Create a backup
cd /usr/local/etc/datamasque
sudo ./datamasque-backup.sh

# Restore from a backup
sudo ./datamasque-restore.sh /path/to/backup_directory

Amazon EKS Deployments

For EKS deployments, the backup process requires access to the Kubernetes cluster. The general approach is:

  1. Use kubectl exec to run backup commands in the admin-server pod
  2. Copy backup files from the pod to local storage
  3. Store backups in S3 or another persistent storage

For specific guidance on EKS backup procedures, contact support@datamasque.com.

Amazon ECS Deployments

For ECS Fargate deployments, back up both the RDS database and EFS filesystem:

Database (RDS PostgreSQL)

  1. Navigate to the RDS Console
  2. Select your DataMasque database instance
  3. Choose Actions > Take snapshot
  4. Provide a snapshot name and click Take snapshot

Alternatively, enable automated backups in RDS for continuous protection.

Files (EFS)

  1. Navigate to the AWS Backup Console
  2. Create a backup plan for your DataMasque EFS filesystem
  3. Configure backup frequency and retention as needed

Note: Ensure you back up both the RDS database and EFS filesystem together to maintain consistency. The EFS filesystem contains the instance secret required for deterministic masking.

Cohesity Deployments

For Cohesity deployments, use Cohesity's built-in protection features to create snapshots of the DataMasque app.

Contact support@datamasque.com for specific guidance on Cohesity backup procedures.

Instance Secret Considerations

The instance secret is a cryptographic key used for deterministic masking. It ensures that the same input value always produces the same masked output within a DataMasque instance.

Important points:

  • The instance secret is stored at /.keys/instance_secret.bin within the admin-server container.

Note: For EKS the admin-server pod is called masque.

  • It is not stored in the database.
  • The backup scripts automatically include the instance secret.
  • If you restore a database backup without the corresponding instance secret, deterministic masking results will differ from previous runs.
  • When migrating to a new instance, you must restore both the database and the instance secret to maintain masking consistency.

Tip: Store backups in a secure location separate from your DataMasque instance. Consider using encrypted storage and following your organisation's data retention policies.

Backup Best Practices

Backup Frequency

Scenario Recommended Frequency
Production systems Daily or before any changes
Before upgrades/downgrades Always
Before configuration changes Recommended
Development/test systems Weekly or as needed

Storage and Retention

  • Store backups on separate storage (S3, Azure Blob, NFS) to protect against instance failure.
  • Encrypt backups at rest, as they contain sensitive cryptographic keys.
  • Keep at least 3 recent backups; retain longer for compliance requirements.
  • Periodically test restore procedures in a non-production environment.

Automation

Consider automating backups with cron or your preferred scheduler:

# Add to root's crontab (sudo crontab -e)
# Example: daily backup at 2 AM
0 2 * * * cd /usr/local/etc/datamasque && ./datamasque-backup.sh backup_$(date +\%Y\%m\%d) >> /var/log/datamasque-backup.log 2>&1

Note: The backup script requires root privileges. Add this entry to root's crontab using sudo crontab -e, not a regular user's crontab.

Troubleshooting

Backup Issues

"Could not find admin-db container"

  • Ensure DataMasque is running: docker ps or podman ps
  • Check that container names include admin-db

"Insufficient disk space"

  • Free up space or specify a backup directory on a volume with more space
  • The backup script requires at least 500 MB free

"Database backup failed"

  • Check PostgreSQL logs: docker logs <admin-db-container>
  • Verify database is healthy: docker exec <admin-db-container> pg_isready -U postgres

Empty or small database.sql file

  • May indicate database connectivity issues
  • Check the database_backup.log if present in the backup directory

Restore Issues

"Checksum verification failed"

  • The backup may be corrupted or modified
  • Try restoring from a different backup
  • If you're certain the backup is valid, you can proceed (the script will ask)

"PostgreSQL failed to become ready"

  • Check database container logs: docker logs <admin-db-container>
  • Ensure no other process is using port 5432
  • Try restarting Docker/Podman service

"Database restore completed with some errors"

  • Some errors are expected (e.g., "does not exist, skipping" for DROP statements)
  • Check the reported errors; critical errors will mention "FATAL" or prevent table creation

Services don't start after restore

  • Check container logs: docker logs <container-name>
  • Verify the compose file path is correct
  • Ensure all required Docker volumes exist

Login fails after restore

  • The JWT key may not have been restored correctly
  • Try restoring again, ensuring secrets.tar is in the backup
  • As a last resort, restart all containers to regenerate the JWT key (users will need to log in again)

Deterministic masking produces different results

  • The instance secret was not restored or doesn't match
  • Ensure secrets.tar was included in the backup and restore
  • Verify the run secret matches between the original and restored instances

Getting Help

If you encounter issues not covered here, contact support@datamasque.com with:

  • The complete output from the backup or restore script
  • Contents of manifest.txt from the backup
  • Container logs: docker logs <container-name>