> For the complete documentation index, see [llms.txt](https://docs.eazybackup.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eazybackup.com/e3-object-storage/connect-apps-and-tools/how-to-use-restic-with-eazybackup-e3-object-storage.md).

# How to use Restic with eazyBackup e3 Object Storage

Install Restic, connect it to eazyBackup e3 Object Storage, create an encrypted backup, and verify that it can be restored.

[Restic](https://restic.net/) is an encrypted, deduplicating backup tool. It encrypts your data before uploading it to e3 Object Storage, so you need the Restic repository password to read or restore a backup.

This guide configures Restic for the e3 S3-compatible endpoint:

```
https://s3.ca-central-1.eazybackup.com
```

## Before you begin

You need:

* An active **e3 Object Storage** service
* An e3 access key and secret key for the owner of your bucket
* A bucket dedicated to Restic, or an empty prefix in an existing bucket
* Root or sudo access on the Linux host you want to back up

{% hint style="danger" %}
Do not lose or share your Restic repository password. eazyBackup cannot use your e3 access keys to decrypt a Restic repository. Store the password in an approved password manager or another secure recovery location.
{% endhint %}

## 1. Create your e3 bucket and access key

1. Sign in at [accounts.eazybackup.ca](https://accounts.eazybackup.ca/).
2. Open **e3 Object Storage** in the sidebar.
3. Open **Access Keys** and copy the **Service URL**. It should be `s3.ca-central-1.eazybackup.com`.
4. Click **Create your first key** or **Create new key**, confirm with your account password, and save the **Access Key ID** and **Secret Access Key** immediately.
5. Open **Buckets** and click **Create Bucket**.
6. Enter a globally unique bucket name using lowercase letters, numbers, and hyphens.
7. Choose the bucket owner, then click **Create Bucket**.

The access key must belong to the same owner as the bucket. A Root user key cannot access a User's bucket, and a User key cannot access Root or another User's bucket.

{% hint style="warning" %}
The secret access key is shown only once. Store it securely when you create or rotate the key. Rotating a Root key revokes the previous key immediately.
{% endhint %}

For a more detailed portal walkthrough, see [Create your first key and bucket](/e3-object-storage/getting-started/create-your-first-key-and-bucket.md). You can also review the canonical [Connection details](/e3-object-storage/getting-started/connection-details.md).

## 2. Install Restic

On Ubuntu or Debian:

```bash
sudo apt-get update
sudo apt-get install -y restic
restic version
```

For the latest upstream release or another operating system, download the appropriate package from the [official Restic releases](https://github.com/restic/restic/releases). Verify the published checksum before installing it.

## 3. Create a protected configuration

This example keeps the configuration outside `/root`, so a backup of `/root` does not include your credentials. Replace every placeholder before continuing.

```bash
sudo install -d -m 700 /etc/restic
sudoedit /etc/restic/e3.env
```

Add the following to `/etc/restic/e3.env`:

```bash
export RESTIC_REPOSITORY='s3:https://s3.ca-central-1.eazybackup.com/YOUR_BUCKET/restic'
export RESTIC_PASSWORD='USE_A_LONG_UNIQUE_REPOSITORY_PASSWORD'
export AWS_ACCESS_KEY_ID='YOUR_E3_ACCESS_KEY'
export AWS_SECRET_ACCESS_KEY='YOUR_E3_SECRET_KEY'
export RESTIC_CACHE_DIR='/var/cache/restic-e3'
```

The `/restic` suffix is an optional repository prefix. Keep it if the bucket may contain other data. Omit it only when the bucket is reserved exclusively for this Restic repository.

Restrict the configuration file and create the cache directory:

```bash
sudo chmod 600 /etc/restic/e3.env
sudo install -d -m 700 /var/cache/restic-e3
```

{% hint style="danger" %}
Never commit this file to source control or paste real keys and passwords into a ticket, shell history, or chat.
{% endhint %}

## 4. Initialize the repository

Load the protected configuration and initialize the repository once:

```bash
sudo -i
source /etc/restic/e3.env
restic -o s3.region=ca-central-1 -o s3.bucket-lookup=dns init
```

The `s3.bucket-lookup=dns` option tells Restic to use virtual-hosted-style bucket addressing, where the bucket name is part of the hostname. This matches the recommended addressing style for e3 Object Storage and the style commonly used by AWS S3.

If the repository has already been initialized, do not run `init` again. Confirm that Restic can read it:

```bash
restic -o s3.region=ca-central-1 -o s3.bucket-lookup=dns snapshots
```

Type `exit` when you are ready to leave the root shell.

## 5. Optional convenience command

You can use small wrapper to keep you from having to retype the endpoint options.

```bash
sudoedit /usr/local/bin/restic-e3
```

Add:

```bash
#!/usr/bin/env bash
set -euo pipefail
source /etc/restic/e3.env
exec restic -o s3.region=ca-central-1 -o s3.bucket-lookup=dns "$@"
```

Make sure to protect this:

```bash
sudo chmod 700 /usr/local/bin/restic-e3
```

Now on our examples will use `restic-e3`. If you skip the wrapper, first source `/etc/restic/e3.env`, then add the two `-o s3...` options shown above to each Restic command.

## 6. Create a backup

Back up a directory:

```bash
sudo restic-e3 backup --tag server --tag daily /home
```

Back up `/root` without including any other filesystems mounted inside it

```bash
sudo restic-e3 backup --one-file-system --tag root-backup /root
```

To back up the root filesystem while excluding temporary and virtual filesystems:

```bash
sudo restic-e3 backup / --one-file-system \
  --exclude /proc --exclude /sys --exclude /dev --exclude /run \
  --exclude /tmp --exclude /var/cache
```

Avoid backing up a Restic cache directory or any file containing credentials. Run the same backup a second time to see deduplication in action. Unchanged files should be reported as unmodified, with very little new data uploaded.

{% hint style="info" %}
A command that ends with `snapshot ... saved` and exit code `0` completed successfully. Monitor exit codes when you automate backups.
{% endhint %}

## 7. Schedule a daily backup with systemd

Restic does not include a built-in scheduler. On Ubuntu and Debian, you can use a systemd timer to run backups automatically. This example backs up `/home` every day at 2:00 AM.

This example uses the `restic-e3` wrapper from step 5. Create that wrapper before continuing.

First, create the service:

```bash
sudoedit /etc/systemd/system/restic-e3-backup.service
```

Add:

```ini
[Unit]
Description=Back up /home to e3
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
User=root
ExecStart=/usr/local/bin/restic-e3 backup --one-file-system --tag scheduled --tag daily /home
```

Change `/home` in `ExecStart` if you want to back up a different path. You can also add the exclusions used in step 6.

Next, create the timer:

```bash
sudoedit /etc/systemd/system/restic-e3-backup.timer
```

Add:

```ini
[Unit]
Description=Run the e3 Restic backup daily

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true
Unit=restic-e3-backup.service

[Install]
WantedBy=timers.target
```

`Persistent=true` runs a missed backup after the computer starts again. A systemd service cannot start a second copy while the first copy is still running, which can help prevent overlapping backups.

Load the new units and enable the timer:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now restic-e3-backup.timer
```

Confirm when the next backup will run:

```bash
systemctl list-timers restic-e3-backup.timer
```

Test the backup service now instead of waiting until 2:00 AM:

```bash
sudo systemctl start restic-e3-backup.service
sudo systemctl status restic-e3-backup.service --no-pager
```

Review recent backup logs:

```bash
sudo journalctl -u restic-e3-backup.service -n 50 --no-pager
```

{% hint style="warning" %}
Run the service manually and confirm that it creates a new snapshot before relying on the schedule.
{% endhint %}

## 8. Inspect and test a restore

List snapshots and view the size of the latest snapshot:

```bash
sudo restic-e3 snapshots
sudo restic-e3 stats latest
```

View paths in a snapshot:

```bash
sudo restic-e3 ls latest /home
```

Restore the latest snapshot to a new, empty directory:

```bash
sudo install -d -m 700 /restore/restic-test
sudo restic-e3 restore latest --target /restore/restic-test
```

For a smaller test restore of one directory:

```bash
sudo restic-e3 restore latest --target /restore/restic-test \
  --include /home/USER/Documents
```

Review the restored permissions and content before copying anything back into a live path. To restore a different snapshot, replace `latest` with an ID from `restic-e3 snapshots`.

## 9. Verify backup health

Run a metadata and repository structure check regularly:

```bash
sudo restic-e3 check
```

To also read and verify a random sample of encrypted backup data:

```bash
sudo restic-e3 check --read-data-subset=5%
```

For the most thorough check, read all pack data. This can take a while and can download a large amount of data:

```bash
sudo restic-e3 check --read-data
```

Periodically perform a test restore and compare the restored files with the originals. A successful `check` confirms repository consistency. A restore test also confirms that your recovery steps work.

## 10. Set retention and maintain the repository

Preview a retention policy before deleting snapshots:

```bash
sudo restic-e3 forget --keep-daily 7 --keep-weekly 4 \
  --keep-monthly 12 --dry-run
```

Apply the policy and reclaim unreferenced data:

```bash
sudo restic-e3 forget --keep-daily 7 --keep-weekly 4 \
  --keep-monthly 12 --prune
```

For a non-destructive preview while troubleshooting storage usage:

```bash
sudo restic-e3 prune --dry-run
```

{% hint style="warning" %}
Use `forget` and `prune` carefully. They can permanently remove snapshots and unreferenced backup data.
{% endhint %}

For more Restic commands and scheduling, see the [official Restic documentation](https://restic.readthedocs.io/en/stable/).