Restic File-Level Backups for FreeBSD on GCP

This document outlines a simple setup process and operational commands for automated file-level backups on FreeBSD running in GCP (Google Cloud Platform) using Restic and Google Cloud Storage (Nearline).

GCP nearline storage is good for file level backups and it’s relatively inexpensive. At the time of this writing, 100GB of storage on nearline costs under $2/month. After setting up restic, we’ll create a script and a cronjob to run it daily; restic only updates the files that change.

We can use restic to restore individual files and directories. It’s a nice way to have file-level backup and restore capability and is a great addition to any system. File-level backups can work in conjunction with other data protection approaches such as snapshots of the VM which are very easy to configure in GCP on a schedule.

1. GCP Bucket & Service Account Setup

1. Create a Cloud Storage Bucket in the GCP Console and set the default class to Nearline.
2. Navigate to IAM & Admin > Service Accounts and create a service account named restic-backup.
3. Assign the Storage Object Admin role for the newly created bucket.
4. Generate and download the JSON key file. Upload it to your FreeBSD server at /etc/restic-gcp-key.json.
5. Set restrictive permissions on the key file:

chmod 600 /etc/restic-gcp-key.json

2. Installation & Configuration

Install Restic via the FreeBSD package manager:

pkg install restic

Create the environment configuration file /etc/restic.env. Update your JSON key and bucket name in the config below! And note, we prefix the variables with export so they are properly exposed to the environment when sourced by sh scripts:

export GOOGLE_APPLICATION_CREDENTIALS="/etc/restic-gcp-key.json"
export RESTIC_REPOSITORY="gs:your-bucket-name:/sys-backup"
export RESTIC_PASSWORD="YourStrongPasswordHere"

Lock down permissions and initialize the remote repository (run only once). Because FreeBSD’s default interactive shell is often csh (which does not support the . operator), wrap interactive commands in a sh -c subshell so the required variables are loaded just when the tool is run:

chmod 700 /etc/restic.env
sh -c '. /etc/restic.env && restic init'

3. Automated Backup Script

Create the backup script and located it wherever you keep you scripts, for this article we’ll put the script in /usr/local/libexec/run-restic-backup.sh. Note that even if your user shell is csh, this script natively uses #!/bin/sh, so sourcing the `.env` file directly will work normally here.

We’re going to backup all the files on the server except a few areas we need to exclude. Adjust as required if you only need to backup a subset of the entire server.

#!/bin/sh
set -e

# Load environment configuration
. /etc/restic.env

# Run full system backup targeting /
restic backup \
  --one-file-system \
  --exclude="/tmp/*" \
  --exclude="/var/tmp/*" \
  --exclude="/usr/obj/*" \
  --exclude="/dev/*" \
  --exclude="/proc/*" \
  /

# Prune old snapshots (keep 7 daily, 4 weekly)
restic forget --keep-daily 7 --keep-weekly 4 --prune

Make the script executable and schedule it via /etc/crontab:

chmod 700 /usr/local/libexec/run-restic-backup.sh

0  2  *  *  *  root  /usr/local/libexec/run-restic-backup.sh > /var/log/restic-backup.log 2>&1

4. Useful Command Reference (For Interactive csh Users)

When running these manually in a csh terminal, remember to wrap them in an sh subshell so that the /etc/restic.env gets loaded just for each restic command invocation.

Action	Command	Description
List Snapshots	sh -c '. /etc/restic.env && restic snapshots'	Displays all available backups with their IDs, times, and paths.
Full Restore	sh -c '. /etc/restic.env && restic restore latest --target /tmp/restore'	Restores the entire latest snapshot into the target directory.
Partial Restore	sh -c '. /etc/restic.env && restic restore latest --include /usr/local/etc/nginx --target /tmp/restore-nginx'	Restores ONLY the specified directory (e.g., /usr/local/etc/nginx).
Mount Backup	sh -c '. /etc/restic.env && restic mount /mnt/restic'	Requires kldload fusefs. Mounts the repository locally to browse snapshots like a filesystem.

That’s it. Monitor your logs at /var/log/restic-backup.log periodically to ensure backups are continuing automatically.