Images

Table of Contents

About
Image Compatibility
Creating an Image
Adding an Image from Disk
Backing Up Images
Performing a Local Backup
Performing a Remote Backup
Restoring Images
Restore an Image from a Local Disk
Performing a Remote Backup
Status
Backing Up Images Via Terminal (Advanced)
Command Syntax
Examples (Advanced)
Finding the Pool Name
Listing Your Drives Via Terminal (Advanced)
Mounting a Drive Via Terminal (Advanced)
Executing a Backup Via Terminal (Advanced)
Un-Mounting a Drive Via Terminal (Advanced)
Remote Backup Via Terminal (Advanced)

About

Images are a logical way to categorize and organize the data we wish to store in ggRock. We refer to images as such because they are not the same as the physical drives in your server, or the physical drives in any other computer system - they are mounted over the network via iSCSI.

The ggRock architecture relies on two primary categories of images:

• System Images
• Game Images

Typically, a system image can be treated like the C:\ drive or boot drive of a standard system. That is to say, it contains the operating system, settings, and any applications that require being installed to the C:\ drive.

The Game image is more specialized - it contains only what you install to it, which, in most cases, consists of games, launchers, and any other applications or utilities that can be easily installed there. Typically you would mount your games image as the G:\ drive, but it may be any drive letter you wish.

Every system in your center that has a given system image selected will boot from that system image. Every system in your center that has a given game image selected will mount that game image at boot time.

Image Compatibility

It is important to ensure that the system image and game image for a given system remain synchronized. This means that if you apply writebacks for a system image, you should do the same for the game image.

Creating an Image

NOTE:

This process should only currently be used for creating Game images, unless otherwise directed by support staff.

1. From the ggRock Web UI, click the "Images" tab.

2. From the "Images" tab, Click the "Create Image" button.

3. Within the "Create Image" dialog, fill out the following information:

• Name Text Box: Enter a name for your image.
• Image Type Drop-Down: Select "Game" as the type, unless otherwise specified by support staff.
• Make Default Checkbox: If you wish this to be the default for all systems, place a check here.
• Volume Text Box: Set a size for your new image
• Volume Size Unit Drop-Down: Select a unit type to use with your image (Bytes, Kilobytes, Megabytes, Gigabytes, or Terabytes).

Adding an Image from Disk

To import an image (VHD/VHDX) stored on an external drive:

1. Plug the drive directly into your ggRock server via USB (USB 3.0 is preferred).
2. From the ggRock Web UI, click the "Images" tab.

3. From the "Images" tab, click the "Import Image" button.

4. Within the "Import Image" dialog, click the "From .VHD" button.

4. Within the "Import image from .VHD" dialog, fill out the following information:

• Select disk drop-down: Select the physical disk on the server you wish to import the image from.
• Select VHD/VHDX Image on the disk drop-down: Select the VHD/VHDX image you wish to import from the selected disk.
• Name Text Field: Give the image a friendly name
• Image Type Drop-Down: Select the type of image to import as - System image is the likely candidate here.
• Make Default Checkbox: Check this box to make this image the default for all systems.

Backing Up Images

There are two mechanisms through which images may be backed up:

• Local - Store backups locally, either on an additional drive connected to the server, or on the root partition (not recommended for mission critical backups).
• Remote - Store backups on a backup ggRock server

Performing a Local Backup

1. Plug a drive into your ggRock server via USB, or utilize a drive installed physically in the server chassis.

2. From the ggRock Web UI, click the "Images" tab.

3. From the "Images" tab, click the "Backup/Restore" button.

4. Within the "Backup/Restore" dialog, ensure the "Backup" tab is selected and fill out the following information:

• Image Checkboxes: Place a check next to each image you wish to back up.
• Location Radio Button: Set the location to "Local".
• Select Drive Drop-Down: Select the physically-connected disk to which you wish to back up your images (it is not recommended to back up to the local filesystem unless you intend to copy the image elsewhere afterward)
• Path Text Box: Set the path on the volume to which you wish to back up your images.
• Select Button: Click this button to activate the selected drive and path for backup.
• Append Text Toggle: Turn this toggle on to enable appending a suffix to your filename.
• Append Text Text Box: Enter the suffix to append to your filename.

4. Click the "Backup" button to begin the backup operation.

Performing a Remote Backup

1. From the ggRock Web UI, click the "Images" tab.

2. From the "Images" tab, click the "Backup/Restore" button.

3. Within the "Backup/Restore" dialog, ensure the "Backup" tab is selected and fill out the following information:

• Image Checkboxes: Place a check next to each image you wish to back up.
• Location Radio Button: Set the location to "Remote".
• User Text Box: Enter the username used to log into the remote system.
• Password Text Box: Enter the password used to log into the remote system.
• Address Text Box: Enter the DNS name or IP address of the remote system.
• Test Button: Test the connection to the remote system.
• Append Text Toggle: Turn on this toggle to append a suffix to your filename.
• Append Text Text Box: Enter the suffix to append to your filename.

5. Click the "Backup" button to begin the backup operation.

Restoring Images

There are two mechanisms through which images may be restored:

• Local - Restore backups from a locally-connected drive, either from an additional drive connected to the server, or from the root partition (not recommended for mission critical backups)
• Remote - Restore backups from a backup ggRock server

Restore an Image from a Local Disk

1. Plug a drive into your ggRock server via USB, or utilize a drive installed physically in the server chassis.
2. From the ggRock Web UI, click the "Images" tab.

3. From the "Images" tab, click the "Backup/Restore" button.

4. Within the "Backup/Restore" dialog, ensure the "Restore" tab is selected and fill out the following information:

• Location Radio Button: Set the location to "Local".
• Select Drive Drop-Down: Select the physically-connected disk from which you wish to restore your images.
• Path Text Box: Set the path on the volume from which you wish to restore your images.
• Images List Box: Place a check next to the images you wish to restore to your server.
• Append Text Toggle: Turn on this toggle to append a suffix to your filename.
• Append Text Textbox: Enter the suffix to append to your filename.

5. Click the "Restore" button to begin restoring your image(s).

Restore an Image from a Remote Server

1. From the ggRock Web UI, click the "Images" tab.

2. From the "Images" tab, click the "Backup/Restore" button.

4. Within the "Backup/Restore" dialog, ensure the "Restore" tab is selected and fill out the following information:

• Location Radio Button: Set the location to "Remote".
• User Text Box: Enter the username used to log into the remote system.
• Password Text Box: Enter the password used to log into the remote system.
• Address Text Box: Enter the DNS name or IP address of the remote system.
• Test Button: Test the connection to the remote system.
• Append Text Toggle: Turn on this toggle to append a suffix to your filename.
• Append Text Text Box: Enter the suffix to append to your filename.

5. Click the "Restore" button to begin restoring your image(s).

Status

From the status tab you may view the history of any backup or restore operations that have been attempted or completed.

1. From the ggRock Web UI, click the "Images" tab.

2. From the "Images" tab, click the "Backup/Restore" button.

3. Within the "Backup/Restore" dialog, select the "History" tab to view the status of any attempted or completed backup/restore operations.

Backing Up Images Via Terminal (Advanced)

To allow you to back up your images, with all of their Writebacks and Snapshots you can use the following CLI (Console Line Interface) tool: ggrock-img

To backup your Images you can use the following console command:

ggrock-img command [command options]

Command syntax

send -p|--pool -i|--image

receive -p|--pool -i|--image

Examples (Advanced)

Backing up image to a file:

ggrock-img send -p pool0 -i games > games.img

Restoring an image from the backup file:

ggrock-img receive -p pool0 -i games < games.img

Backup an image to the file and display progress:

ggrock-img send -p pool0 -i games | pv > games.img

Restore an image from the backup file and display progress:

cat games.img | pv | ggrock-img receive -p pool0 -i games

Clone the image to another ggRock server over SSH:

ggrock-img send -p pool0 -i games | pv | ssh host2 ggrock-img receive -p pool0 -i games

Finding the Pool Name

The pool name can be found within the Backup/Restore dialog in the "PATH" column.

Listing Your Drives Via Terminal (Advanced)

Now, to get your drive actually ready to receive backups from ggRock you need to find it’s letter and mount it.

Execute the following command:

lsblk -I 8 -b -o NAME,PATH,FSTYPE,LABEL,SIZE,MODEL,SERIAL,MOUNTPOINT,RM

You will get a list of all of your drives and identify the one you inserted using the Model column:

Mounting a Drive Via Terminal (Advanced)

Identify the path value for your drive and execute the following command:

mkdir /backup && mount /dev/sde1 /backup

It will create a “folder” called backups, which will be associated with your entire drive

Executing a Local Backup Via Terminal (Advanced)

Once you have identified your pool and mounted your drive, combine the two and execute the following command:

ggrock-img send -p pool0 -i windows_10_1809 | pv > /backup/windows_10_1809.img

The template is:

ggrock-img send -p pool0 -i <image_name> | pv > /backup/<desired_backup_image_name>.img

pv displays size and speed in Mb/Gb - to estimate an ETA, multiply the size of the image (in GB) by 8 to get the size in gigabits, then divide by your observed throughput in Gb/s. Bottleneck here is usually the destination drive itself - for faster backups, we recommend USB3 SSD drives or a network backup instead.

Un-Mounting a Drive Via Terminal (Advanced)

The drive will be unmounted automatically once you pull it. However, to clean up properly, please execute:

umount /dev/sde1 && rmdir /backup

Remote Backup Via Terminal (Advanced)

Remote backup lets you keep a second ggRock server ("the destination") in sync with a primary server ("the source") over SSH, and can be automated with a cron job so the destination stays continuously up to date.

Enabling Root SSH Access on the Destination Server

ggrock-img receive runs as root on the destination server, so the source server needs a way to authenticate as root over SSH. ggRock/Debian servers ship with root SSH login restricted to key-based authentication only (PermitRootLogin prohibit-password), which blocks the password-based copy step used to install a new key for the first time.
Check the current setting on the destination server:

grep -i "^PermitRootLogin" /etc/ssh/sshd_config

If it shows prohibit-password (or is commented out) and you don't already have another way to place a public key in /root/.ssh/authorized_keys (console access, an existing sudo account, etc.), temporarily allow password login so the key can be copied over:

sed -i 's/^#*PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
systemctl restart sshd

Setting Up Key-Based Authentication

On the source server, generate a key if one doesn't already exist, then copy it to the destination:

ls -la /root/.ssh/id_ed25519 2>/dev/null && echo "key already exists" || ssh-keygen -t ed25519 -N "" -f /root/.ssh/id_ed25519
ssh-copy-id root@<destination_ip>

You will be prompted for the destination's root password one time. Once complete, confirm passwordless login works:

ssh root@<destination_ip> echo "connection ok"

You should see connection ok returned with no password prompt.

Disabling Root Password Login

Once key-based login is confirmed working, re-tighten SSH on the destination server so password-based root login is no longer accepted:

sed -i 's/^PermitRootLogin.*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config
systemctl restart sshd

prohibit-password still allows the key-based login your backups depend on, while blocking anyone from attempting a root password over SSH.

Running a One-Time Remote Backup

For a single manual sync, or to clone an image to another ggRock server for the first time:

ggrock-img send -p pool0 -i games | ssh <destination_ip> ggrock-img receive -p pool0 -i games

If the destination image already has its own independent snapshot history (for example, it was created and used separately before you started backing it up), the receive will fail with an error similar to:

cannot receive new filesystem stream: destination has snapshots (eg. pool0/ggrock/images/games@base)
must destroy them to overwrite it

ssh <destination_ip> "zfs destroy -r pool0/ggrock/images/games"
ggrock-img send -p pool0 -i games | ssh <destination_ip> ggrock-img receive -p pool0 -i games

If the destination dataset does not exist at all yet, receive will create it automatically - no destroy step needed.

Automated Incremental Remote Backups via Cron

Re-sending an entire image every night wastes bandwidth and time once you have an initial copy on the destination. ggrock-img send supports incremental sends with -I <snapshot_name>, sending only what has changed since a given snapshot.

One-time setup - initial full sync of each image (see "Running a One-Time Remote Backup" above). Do this once per image before enabling the cron job.
Script - save as /usr/local/bin/ggrock-remote-backup.sh on the source server, editing the configuration block for your image names, pool, and destination:

#!/bin/bash
# Configuration
SOURCE_POOL="pool0"
SOURCE_GAMES_IMAGE="games"
SOURCE_SYSTEM_IMAGE="windows_11_pro_uefi_25h2"
DESTINATION_HOST="10.198.2.64"
DESTINATION_POOL="pool0"
DESTINATION_GAMES_IMAGE="games"
DESTINATION_SYSTEM_IMAGE="windows_11_pro_uefi_25h2"
LOG_FILE="/var/log/ggrock-backup.log"

set -o pipefail

log() { echo "$(date '+%Y-%m-%d %H:%M:%S') - $1" >> "$LOG_FILE"; }

sync_image() {
  local src_image="$1"
  local dst_image="$2"

  local last_snap
  last_snap=$(ssh "$DESTINATION_HOST" "ggrock-img list_snapshots -p '$DESTINATION_POOL' -i '$dst_image'" | tail -n 1 | awk -F'\t' '{print $3}')

  if [ -z "$last_snap" ]; then
    log "Could not determine last snapshot for $dst_image on $DESTINATION_HOST - aborting sync for this image"
    return 1
  fi

  local source_latest
  source_latest=$(ggrock-img list_snapshots -p "$SOURCE_POOL" -i "$src_image" | tail -n 1 | awk -F'\t' '{print $3}')

  if [ -z "$source_latest" ]; then
    log "Could not determine latest snapshot for $src_image on source - aborting sync for this image"
    return 1
  fi

  if [ "$source_latest" == "$last_snap" ]; then
    log "$src_image already up to date (latest snapshot $source_latest matches destination) - skipping"
    return 0
  fi

  log "Starting incremental sync for $src_image (from $last_snap to $source_latest)"
  ggrock-img send -p "$SOURCE_POOL" -i "$src_image" -I "$last_snap" | \
    ssh "$DESTINATION_HOST" "ggrock-img receive -F -p '$DESTINATION_POOL' -i '$dst_image'"

  if [ $? -ne 0 ]; then
    log "Incremental sync FAILED for $src_image"
    return 1
  fi
  log "Incremental sync completed for $src_image"
  return 0
}

sync_image "$SOURCE_GAMES_IMAGE" "$DESTINATION_GAMES_IMAGE" || exit 1
sync_image "$SOURCE_SYSTEM_IMAGE" "$DESTINATION_SYSTEM_IMAGE" || exit 1

log "All syncs completed"
exit 0

Note the awk -F'\t' field split assumes ggrock-img list_snapshots output is tab-separated. Before relying on this in production, confirm the parsing on your own server:

ssh <destination_ip> "ggrock-img list_snapshots -p pool0 -i games" | tail -n 1 | awk -F'\t' '{print $3}'

This should print only the snapshot name (for example 2026-08-12-18-50-35) with nothing else. If it prints something else, the field separator or column position needs adjusting for your build.
Make the script executable and add it to root's crontab on the source server:

chmod +x /usr/local/bin/ggrock-remote-backup.sh
crontab -e

Add a line to run it nightly at 2 AM (adjust to taste):

0 2 * * * /usr/local/bin/ggrock-remote-backup.sh

Each run appends to /var/log/ggrock-backup.log.

Since there is no alerting built into this script, a failed run only shows up if the log is checked manually - if you need to be notified automatically on failure, add an email or webhook call inside the if [ $? -ne 0 ] blocks.

Updated on: 12/08/2026