Gniza Backup Manager - Installation & Uninstallation - Knowledgebase

1. Overview

Gniza is a backup management solution built on Restic. It provides centralized backup management for supported hosting panels and standalone Linux servers.

Supported environments:

cPanel/WHM
DirectAdmin
Standalone Linux servers without a hosting panel

Plesk is not currently listed as a supported panel.

2. System Requirements

Before installing Gniza, ensure that:

You have root SSH access to the server.
Your operating system and hosting panel are compatible with the installed release.
The server has internet access.
You have sufficient local disk space for temporary backup staging.
You have a supported backup destination.
You can securely store the recovery key and master key.

For production servers, use remote backup storage whenever possible.

3. Installation

3.1 Install Gniza

Connect to the server over SSH as root and execute:

curl -fsSL https://github.com/shukiv/gniza/releases/latest/download/get.sh | sh

The installer automatically detects the environment and installs the appropriate integration.

cPanel/WHM: Installs the WHM plugin and cPanel integration.
DirectAdmin: Installs the DirectAdmin integration.
Standalone Linux: Installs the standalone agent and associated components.

The installer verifies signed release checksums, installs Restic if necessary, and configures the Gniza service and integration hooks.

3.2 Verify the installation

Check the service:

systemctl status gniza

Review recent logs:

journalctl -u gniza -n 100 --no-pager

3.3 Open Gniza

For cPanel/WHM:

Log in to WHM as root.
Navigate to Plugins → Gniza Backups.
Confirm that the interface loads.

For DirectAdmin:

Log in to DirectAdmin.
Navigate to Admin Tools → Gniza.
Confirm that the interface loads.

For standalone Linux:

Launch the terminal interface:

gniza-agent -tui

3.4 Verify the installer before execution (optional)

Download the installer and checksum file:

curl -fsSLO https://github.com/shukiv/gniza/releases/latest/download/get.sh
curl -fsSLO https://github.com/shukiv/gniza/releases/latest/download/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

Review the script:

less get.sh

After successful verification and review, run:

sh get.sh

Do not proceed if checksum verification fails.

4. Configure a Backup Destination

Open Gniza and navigate to the destination configuration section.

Supported destination types include:

SFTP
S3-compatible storage
Restic REST
Local or mounted storage

Create a destination, enter the requested connection details, and verify that the destination is reachable.

For production servers, remote storage is recommended so that a server failure does not destroy both the original data and its backups.

4.1 Save the recovery key

When a repository is created, Gniza provides a recovery key. Save it securely when displayed.

Do not assume the recovery key can be retrieved later if lost.

4.2 Protect the master key

Gniza stores its master key at:

/etc/gniza/master.key

This key protects stored destination credentials. Keep a secure off-server copy and restrict access to authorized administrators.

The master key and repository recovery key serve different purposes. Protect both as required.

5. Configure Backup Schedules

Open the Schedules section.
Create a new schedule.
Select the accounts or data to protect.
Choose the destination.
Configure frequency and retention settings available in your version.
Save the schedule.
Run a manual backup.
Verify the result in Gniza.

A configured schedule does not guarantee that a successful backup exists. Verify the first run and investigate warnings or errors.

6. cPanel/WHM Backup Management

Gniza integrates with cPanel's account backup and restore mechanisms.

Depending on the selected workflow and configuration, backups may include:

Home directory files.
Account configuration.
Databases and related account data.
Mail and mailbox data.
Cron jobs.
Domains and DNS information.
SSL certificates and related account configuration.

Actual coverage depends on the selected workflow and applicable exclusions.

6.1 Account lifecycle integration

The cPanel integration registers hooks for account creation, modification, suspension, unsuspension, and removal.

These hooks help Gniza maintain account identity and respond to account lifecycle events.

6.2 Backup exclusions

If files are missing from a backup, check the relevant cPanel backup exclusion settings, including:

/etc/cpbackup-exclude.conf

Also check the account-specific cpbackup-exclude.conf file where applicable.

Review the schedule and backup logs before concluding that data was skipped incorrectly.

6.3 Restore cPanel accounts

Use the restore workflow provided by Gniza Backups in WHM.

Depending on the supported workflow, restoration may include whole-account recovery, deleted-account recovery, or supported item-level recovery.

Before restoring, verify the target account, selected snapshot, available disk space, and whether existing data will be overwritten.

After restoring, verify file ownership, permissions, databases, websites, mail, DNS, SSL certificates, and scheduled jobs as applicable.

7. DirectAdmin Backup Management

Gniza integrates with DirectAdmin's account backup and restore workflows.

7.1 Configure account backups

Open Admin Tools → Gniza.
Configure the backup destination.
Create a schedule.
Select the accounts or supported data.
Save the schedule.
Run a manual backup.
Verify the backup status.

7.2 DirectAdmin limitations

Not every cPanel feature is available in DirectAdmin.

Granular restore operations and some schedule exclusion features may be limited. Check the capabilities of your installed version before relying on a specific restoration workflow.

For disaster recovery, consider maintaining a separate system-level backup of important DirectAdmin configuration, CustomBuild settings, web server and PHP configuration, mail, DNS, firewall, SSH, and other server-specific settings.

8. Standalone Linux Backup Management

On a standalone Linux server, Gniza does not automatically know which data you want to protect. You must select the sources in a schedule.

Supported source categories include:

Files and directories.
MySQL databases.
PostgreSQL databases.
Docker and Podman containers and associated stacks.

8.1 Access the terminal interface

gniza-agent -tui

Use the interface to configure destinations, schedules, backup sources, logs, and restore operations.

8.2 Configure the web interface

The installer asks where the web interface should listen. The recommended default is local-only access at 127.0.0.1:8443.

Set or change the web password:

gniza-agent -web-set-password

Create an SSH tunnel from your local computer:

ssh -L 8443:127.0.0.1:8443 root@YOUR_SERVER_IP

Replace YOUR_SERVER_IP with the actual server IP address.

Then open this address in your local browser:

http://127.0.0.1:8443/

Avoid exposing the administrative interface directly to the public internet unless access has been deliberately configured and secured.

9. Restore and Disaster Recovery

9.1 Before restoring

Before starting a restore operation:

Identify the affected account or data.
Select the correct repository and restore point.
Confirm that the recovery key is available.
Check free space on the restore target.
Review whether existing data will be overwritten.
Preserve a copy of critical current data where possible.

9.2 Restore through the hosting panel

Use the restore functionality supported by the installed integration. Available operations may differ between cPanel/WHM and DirectAdmin.

After restoring, verify file ownership, permissions, database contents, website functionality, mail delivery, DNS, SSL certificates, and scheduled jobs as applicable.

9.3 Restore through Restic

For a Restic REST repository, the general command pattern is:

export RESTIC_REPOSITORY='rest:https://backup.example.com/repository'
export RESTIC_PASSWORD='YOUR_RECOVERY_KEY'

restic snapshots

After identifying the required snapshot, restore it to a separate directory:

restic restore latest --target /restore-target

Replace the example repository URL, recovery key, and target directory with the actual values. Other destination types require their appropriate repository configuration and credentials.

A Restic restore does not automatically rebuild a complete hosting server. The operating system, hosting panel, services, and configuration may need to be restored separately.

10. Troubleshooting

10.1 Gniza does not appear in WHM or DirectAdmin

Check the service:

systemctl status gniza

Inspect recent logs:

journalctl -u gniza -n 100 --no-pager

Confirm that the installer detected the correct panel and completed its integration steps.

10.2 Backup jobs fail

Check:

Destination connectivity.
Authentication credentials.
Destination permissions and storage quota.
Local staging space.
DNS and network connectivity.
Database backup errors.
Error details shown in Gniza.

Check filesystem capacity:

df -h

Check inode availability:

df -i

10.3 Insufficient local disk space

Large accounts may require temporary local staging space during backup operations, even when the final destination is remote.

Identify the filesystem running out of space before removing files. Do not delete existing backups or customer data without confirming their purpose and whether another verified copy exists.

10.4 The service does not start

Check service status and logs:

systemctl status gniza
journalctl -u gniza -n 100 --no-pager

Investigate the reported error before restarting or reinstalling the software.

10.5 Destination credentials are inaccessible

Check whether the master key exists:

ls -l /etc/gniza/master.key

Do not overwrite or delete the master key as a troubleshooting shortcut. If it is missing, preserve the existing state and recovery information.

11. Update Gniza

The installation script can be run again to upgrade an existing installation in place.

Run the installation command from Section 3 as root.

Before upgrading:

Verify that recent backups are healthy.
Secure the recovery key and master key.
Review the release notes and compatibility information.
Run the installer.
Verify the service and panel interface.

Check the service after upgrading:

systemctl status gniza

Review logs if errors occur:

journalctl -u gniza -n 100 --no-pager

12. Uninstall Gniza

Before uninstalling, confirm that your backup repositories and necessary recovery material will remain accessible.

12.1 Standard uninstall

Run as root:

sh /usr/local/share/gniza/uninstall.sh

The standard uninstall removes Gniza's service, panel integration, hooks, and program components.

Some components may be moved to a dated directory under:

/var/lib/gniza/removed/

The script reports the relevant location.

The standard uninstall preserves:

/etc/gniza/master.key
/var/lib/gniza/state.db

The Restic cache is removed and can be rebuilt if needed. Remote backup repositories are not deleted.

12.2 Complete local removal

If you intentionally want to remove the remaining local Gniza configuration and data, run:

sh /usr/local/share/gniza/uninstall.sh --everything

This removes additional local data, including the master key, state database, cache, Restic components, and moved-aside files.

The script requests confirmation. A --yes option is available for non-interactive execution.

Warning: Complete local removal can eliminate the key material needed to access stored destination credentials. Secure all necessary recovery information before proceeding.

This command does not delete remote backup repositories.

12.3 Verify uninstallation

Check the service:

systemctl status gniza

Confirm that the Gniza entry is no longer available in WHM or DirectAdmin.

Do not manually delete unrelated hosting-panel files as part of the uninstall process.

13. Plesk Compatibility

Plesk is not currently listed as a supported hosting panel in Gniza's documented integrations.

The documented environments include cPanel/WHM, DirectAdmin, and standalone Linux servers. Do not expect a Plesk extension unless explicit support is added.

14. Security Best Practices

Store backups separately from the server being protected.
Keep recovery keys and the master key in a secure off-server location.
Restrict administrative access.
Review destination credentials and permissions.
Monitor failed and partial backups.
Perform regular recovery tests.
Verify backup access before decommissioning a server.
Avoid complete local removal while required recovery material is still needed.
Document the server rebuild and disaster recovery process.

Knowledgebase

Categories

Categories