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:
- Install Restic to
/usr/local/bin. - Configure a systemd service and timer that runs every 12 hours to back the
/homedirectory. - 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_IDandOS_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.
sequenceDiagram
participant U as User / Agent
participant R as Restic CLI / Service
participant S as Swift Storage
participant Repo as Restic Repository
U->>R: 1) Initiates backup or restore command
note right of R: Restic reads config/env<br> (credentials, repository URL, etc.)
alt Backup Workflow
R->>R: Deduplicate & encrypt data chunks
R->>S: Send encrypted data to Swift
S->>Repo: Swift stores data in Restic repository
Repo->>R: Confirm successful storage
end
alt Restore Workflow
R->>S: Request encrypted data chunks
S->>Repo: Retrieve data from Restic repository
Repo->>R: Return encrypted data
R->>R: Decrypt data chunks
R->>U: Provide restored files to user
end
note over R,S: Communication with Swift uses<br> OpenStack application credentials.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
- Write the cloud-init (user data) script – The script:
- Downloads/installs Restic.
- Creates an environment file for Swift credentials.
- Creates systemd service and timer units for automated backups.
-
Starts the timer.
-
Launch a new VM using the provided user data script.
-
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 installcurlto 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.envThis 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 withchmod 600. -
Systemd Service:
/etc/systemd/system/restic-backup.serviceA simple one-shot service that runsrestic backupon your specified directory. It sources the environment variables from/etc/restic.env. You can add aforget --prunestep orcheckstep as you see fit. -
Systemd Timer:
/etc/systemd/system/restic-backup.timerTriggersrestic-backup.serviceevery 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
Check systemd timer
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.
Swift Container Output
+-----------------------------------------------------------------------------+
| Name |
+-----------------------------------------------------------------------------+
| app-0/config |
| app-0/keys/1234567890123456789012345678901234567890123456789012345678901234 |
+-----------------------------------------------------------------------------+
Check backups
To trigger a backup manually, run:
Then, see if the snapshot was created:
Restic Snapshots Output
If you see snapshots listed, your backups are working and stored in Swift as intended.
Next Steps
-
Add a
restic forget --prunestep 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.servicefor 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!