Skip to content

Deploying Restic on OpenStack Flex with User Data

Restic is an open-source backup tool that focuses on providing secure, efficient, and easy-to-use backups. This blog post will show you how to automatically install and configure Restic on a fresh OpenStack VM using user data (cloud-init).

Here’s what you’ll accomplish:

  1. Install Restic to /usr/local/bin.
  2. Configure a systemd service and timer that runs every 12 hours to back the /home directory.
  3. Store backups in Swift using application credentials.

Prerequisites

This blog post was written with the following environment assumptions already existing

  • Network: tenant-net
  • Key Pair: tenant-key

If the project isn't setup completely, checkout the getting started guide.

  • OpenStack project where you can create and manage new VM instances.

  • Application credentials to authenticate with Swift. You’ll typically have two pieces of information from your OpenStack environment: OS_APPLICATION_CREDENTIAL_ID and OS_APPLICATION_CREDENTIAL_SECRET.

  • A container created in Swift to hold the Restic backups.

High-Level Workflow Overview

Below is an example diagram that illustrates the high-level workflow of how Restic operates with Swift as the storage backend.

Explanation

User / Agent: This is either a person or an automated process that invokes Restic commands (backup, restore, etc.).

Restic CLI / Service: The Restic binary or service running on your machine. It manages your backups, handles data deduplication, and encrypts your data before sending it to storage.

Swift Storage: Your Swift endpoint in OpenStack, storing the actual backup objects. Restic uses application credentials to authenticate.

Restic Repository: The structure Restic maintains within Swift to hold snapshots, indexes, and data packs.

This diagram demonstrates how Restic takes in your backup or restore request, works with Swift to store or retrieve deduplicated data, and confirms a successful backup or returns the restored data back to the user.

Steps Overview

  1. Write the cloud-init (user data) script – The script:
  2. Downloads/installs Restic.
  3. Creates an environment file for Swift credentials.
  4. Creates systemd service and timer units for automated backups.

  5. Starts the timer.

  6. Launch a new VM using the provided user data script.

  7. Verify that Restic is installed and backups run automatically.

Generate the Application Credentials

Before you can use Restic with Swift, you need to create application credentials in OpenStack. These credentials will allow Restic to authenticate with Swift and store backups in your container.

For the purpose of this example, use the openstack cli to generate the credentials with a minimum set of roles required for Restic to function.

openstack --os-cloud default application credential create \
          --restricted \
          --role creator \
          --role reader \
          --description "Restic APP Creds" \
          --access-rules '[
            {"path": "/**", "service": "object-store", "method": "GET"},
            {"path": "/**", "service": "object-store", "method": "HEAD"},
            {"path": "/**", "service": "object-store", "method": "POST"},
            {"path": "/**", "service": "object-store", "method": "PUT"},
            {"path": "/**", "service": "object-store", "method": "DELETE"}
          ]' \
          restic

Application Credential Output

+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Field        | Value                                                                                                                                                                                                                    |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| id           | 12345678901234567890123456789012345678                                                                                                                                                                                   |
| name         | restic                                                                                                                                                                                                                   |
| description  | Restic APP Creds                                                                                                                                                                                                         |
| project_id   | 12345678901234567890123456789012                                                                                                                                                                                         |
| roles        | creator reader                                                                                                                                                                                                           |
| unrestricted | False                                                                                                                                                                                                                    |
| access_rules | [{'id': '09876543210987654321098765432109', 'service': 'object-store', 'path': '/**', 'method': 'GET'}, {'id': '09876543210987654321098765432109', 'service': 'object-store', 'path': '/**', 'method':                   |
|              | 'POST'}, {'id': '09876543210987654321098765432109', 'service': 'object-store', 'path': '/**', 'method': 'PUT'}, {'id': '09876543210987654321098765432109', 'service': 'object-store', 'path': '/**',                     |
|              | 'method': 'HEAD'}, {'id': '09876543210987654321098765432109', 'service': 'object-store', 'path': '/**', 'method': 'DELETE'}]                                                                                             |
| expires_at   | None                                                                                                                                                                                                                     |
| secret       | 12345678901234567890123456789012345678901234567890123456789012345678901234567890123456                                                                                                                                   |
+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Increase Backup Security

In the above application credentials command, the example access-rules ensures credentials are only valid with the object-store service. This is a good start, but users can further increase security by eliminating the DELETE method, which prevents any client from deleting objects from the store. Removing the DELETE method does limit some of the Restic client capabilities, but doing so ensures that the client can not be used to destory backups; which is generally good practice.

limited access rules

openstack --os-cloud default application credential create \
        --restricted \
        --role creator \
        --role reader \
        --description "Restic APP Creds, Add only." \
        --access-rules '[
            {"path": "/**", "service": "object-store", "method": "GET"},
            {"path": "/**", "service": "object-store", "method": "HEAD"},
            {"path": "/**", "service": "object-store", "method": "POST"},
            {"path": "/**", "service": "object-store", "method": "PUT"}
        ]' \
        restic-add-only

The Cloud-init Script

Below is an example user data script you can provide to your instance in the “User Data” field when launching it in the dashboard (or via the CLI with --user-data). the script will install Restic, set up a systemd service and timer to run backups every 12 hours, and store the backups in Swift.

/tmp/restic-user-data.yaml

#cloud-config
packages:
  # Installing wget, if needed, to download the latest Restic binary
  - curl
  - wget
  - bzip2
  - jq

bootcmd:
  - mkdir -p /etc/systemd/system
  - mkdir -p /usr/local/bin
  - mkdir -p /etc/restic

write_files:
  - path: /etc/systemd/system/restic-backup.service
    owner: root:root
    permissions: 0o600
    content: |
      [Unit]
      Description=Run Restic Backup
      [Service]
      Type=oneshot
      EnvironmentFile=/etc/restic/restic.env
      ExecStart=/usr/local/bin/restic backup /home --verbose --exclude-file=/etc/restic/restic.exclude
      # If you have a separate excludes file, create /etc/restic.exclude with each pattern on a new line.
      # Optionally, run a prune or check here after backups:
      # ExecStartPost=/usr/local/bin/restic forget --prune --keep-daily 7
      # ExecStartPost=/usr/local/bin/restic check
  - path: /etc/systemd/system/restic-backup.timer
    owner: root:root
    permissions: 0o600
    content: |
      [Unit]
      Description=Run Restic backup every 12 hours

      [Timer]
      OnBootSec=15min
      OnUnitActiveSec=12h
      Unit=restic-backup.service

      [Install]
      WantedBy=multi-user.target
  - path: /etc/restic/restic.env
    owner: root:root
    permissions: 0o600
    content: |
      # Swift environment variables
      OS_AUTH_URL="https://keystone.api.sjc3.rackspacecloud.com/v3"
      OS_APPLICATION_CREDENTIAL_ID="<YOUR_APP_CRED_ID>"
      OS_APPLICATION_CREDENTIAL_SECRET="<YOUR_APP_CRED_SECRET>"
      # Restic encryption password
      RESTIC_PASSWORD="<SUPER_SECURE_PASSWORD>"
  - path: /etc/restic/restic.exclude
    owner: root:root
    permissions: 0o600
    content: ""
  - path: /etc/restic/restic.exclude
    owner: root:root
    permissions: 0o600
    content: ""

runcmd:
  - >
    grep -q RESTIC_REPOSITORY /etc/restic/restic.env ||
    echo "RESTIC_REPOSITORY='swift:restic:/$(curl -s http://169.254.169.254/openstack/latest/meta_data.json | jq -r .uuid)'" |
    tee -a /etc/restic/restic.env
  - wget https://github.com/restic/restic/releases/download/v0.17.3/restic_0.17.3_linux_amd64.bz2 -O /tmp/restic.bz2
  - bzip2 -d /tmp/restic.bz2
  - mv /tmp/restic /usr/local/bin/restic
  - chmod +x /usr/local/bin/restic
  - if /usr/sbin/getenforce; then chcon -R -t bin_t /usr/local/bin; fi
  - systemctl daemon-reload
  - bash -c "export $(grep -v '^#' /etc/restic/restic.env | xargs) && /usr/local/bin/restic init"
  - systemctl enable --now restic-backup.timer
  - systemctl start restic-backup.service

Download the cloud-config script here.

Note

To use this user-data file, update it with your own Swift container name, environment variables, and desired backup paths.

Remember to update placeholder credentials and passwords from the script.

  • <YOUR_APP_CRED_ID> and <YOUR_APP_CRED_SECRET> placeholders with the application credential ID and secret you generated earlier.

  • <SUPER_SECURE_PASSWORD> value with the secret you wish to use to encrypt your backup contents.

Explanation of Key Sections

  • packages: Installs any packages needed for setup. We install curl to fetch the Restic binary.

  • Download and Install Restic We retrieve the latest official Restic binary and place it in /usr/local/bin/restic, then make it executable.

  • Environment File: /etc/restic.env This file contains your Swift credentials (OS_APPLICATION_CREDENTIAL_ID, OS_APPLICATION_CREDENTIAL_SECRET, etc.) along with the Restic repository URL and password. We protect this file with chmod 600.

  • Systemd Service: /etc/systemd/system/restic-backup.service A simple one-shot service that runs restic backup on your specified directory. It sources the environment variables from /etc/restic.env. You can add a forget --prune step or check step as you see fit.

  • Systemd Timer: /etc/systemd/system/restic-backup.timer Triggers restic-backup.service every 12 hours. Also sets a delay of 15 minutes after boot before the first run (OnBootSec=15min), ensuring the system is somewhat stable before performing the initial backup.

  • Initializing the Repository: Before using Restic for the first time, you typically run restic init.

Launch the VM with User Data

OS Compatibility

At the time of this writing, the user-data script provided is compatible with both Debian and RHEL based distributions: tested Debian, Ubuntu, CentOS, and Rocky. If you are using a different distribution, you may need to adjust the package installation commands.

The OpenStack CLI, provide the above YAML in the User Data section when creating your new instance.

openstack --os-cloud default server create app-0 \
          --flavor gp.0.1.2 \
          --network tenant-net \
          --image "Debian 12" \
          --user-data /tmp/restic-user-data.yaml \
          --key-name tenant-key

Verification

After the VM boots, you can verify that your cloud-init script ran successfully and that the systemd timer is running:

Check Restic version

restic version

Restic Version Output

restic 0.17.3 compiled with go1.23.3 on linux/amd64

Check systemd timer

systemctl status restic-backup.timer
systemctl status restic-backup.service

Ensure the timer is active and set to trigger every 12 hours.

Check Swift container

Check the swift object storage environment for the configuration and initialization of the Restic repository. In the above example, the swift container will be named restic, with the backup data matching the hostname of the VM.

openstack --os-cloud rxt-sjc-mine-free object list restic

Swift Container Output

+-----------------------------------------------------------------------------+
| Name                                                                        |
+-----------------------------------------------------------------------------+
| app-0/config                                                                |
| app-0/keys/1234567890123456789012345678901234567890123456789012345678901234 |
+-----------------------------------------------------------------------------+

Check backups

To trigger a backup manually, run:

sudo systemctl start restic-backup.service

Then, see if the snapshot was created:

export $(grep -v '^#' /etc/restic/restic.env | xargs)
restic snapshots

Restic Snapshots Output

created new cache in /root/.cache/restic
ID        Time                 Host        Tags        Paths  Size
-----------------------------------------------------------------------
9aa868eb  2025-03-27 06:29:36  app-0                   /home  4.525 KiB
-----------------------------------------------------------------------
1 snapshots

If you see snapshots listed, your backups are working and stored in Swift as intended.

Next Steps

  • Add a restic forget --prune step to remove old snapshots and manage disk usage in Swift.

  • Customize the backup paths, schedules, and retention policies to suit your needs.

  • Extend the script: Add more directories to back up and/or integrate with other services.

  • Monitor logs: Keep an eye on journalctl -u restic-backup.service for issues.

  • Read the Restic documentation: Learn more about Restic’s features and how to use it effectively.

Conclusion

By leveraging a simple cloud-init script, you can seamlessly install and configure Restic on a new OpenStack VM to back up any directory to Swift storage. Coupling Restic with Swift application credentials provides a secure, automated backup process that fits right into your OpenStack environment. With systemd timers handling schedules, you’ll have regular backups without manual intervention—ensuring your data is consistently protected.

Feel free to extend this script for pruning old backups, encrypting credentials at rest, or adopting more advanced rotation schemes. Happy backing up!