Rest Server for restic on AWS User Guide

Overview

This image runs Rest Server, the open source, high performance HTTP server that implements the restic REST backend protocol. Point any restic client at it over HTTPS and it becomes a self hosted, authenticated backup repository server: read and write encrypted backup repositories exactly as you would against any restic remote, entirely within your own account. Because it speaks the standard restic REST protocol, existing restic clients and automation work unchanged.

Rest Server is an HTTP REST API backend with no web console. This image delivers it fully installed and hardened: rest-server itself binds to the loopback interface only, and nginx is the single network facing surface, terminating TLS on port 443 and fronting the entire backend with HTTP basic authentication so the server is never an open, anonymous repository. restic uploads large pack files, so nginx is configured to stream request bodies unbuffered and without a size cap.

The repository store lives on a dedicated, independently resizable EBS data volume mounted at /var/lib/restic, separate from the operating system disk, so your backups have room to grow. Rest Server 0.14.0 was installed from the official upstream release and verified against its published SHA256 checksum at build time.

Secure by default: per instance credentials

Rest Server can be run with authentication disabled, which would make it an open, anonymous repository server. This image never exposes it that way, and nothing secret is baked into the image. It runs with --htpasswd-file and --private-repos, so every request must be HTTP basic authenticated against a bcrypt password file and each user is confined to its own repository namespace. On the first boot of every instance, the rest-server-firstboot service:

• resolves the instance public IP through the EC2 Instance Metadata Service (IMDSv2),
• generates a unique self signed TLS certificate whose subject alternative names cover the instance public IP, its hostname and 127.0.0.1,
• generates a unique restic username and password and writes the bcrypt htpasswd file, and
• writes the credentials, the HTTPS endpoint URL and a ready to paste restic repository example to /root/rest-server-aws-credentials.txt (mode 0600, root only).

Every instance therefore gets its own certificate and its own password, and rest-server.service is configured to require the first boot credential generator, so it can never start without a per instance credential. Unauthenticated requests are rejected with 401.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 (SSH) from your management network and inbound port 443 (HTTPS) from the machines that will back up to the server
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Rest Server for restic. Select the cloudimg listing, choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 443 from the machines that will back up to the server. Leave the root volume at the default size or larger; the repository store lives on a separate data volume that is provisioned automatically.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Rest Server Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 and port 443.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=rest-server}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Step 4: Retrieve the per instance credentials

The unique username and password generated on first boot are in a root only file. Read them with sudo:

sudo cat /root/rest-server-aws-credentials.txt

The file contains:

• REST_SERVER_USER and REST_SERVER_PASSWORD — the restic username and password for this instance
• REST_SERVER_URL — the HTTPS endpoint, https://<instance-public-ip>/
• REST_SERVER_REPO — a ready to paste restic repository prefix

Keep this file secret; it is the credential for your backup repository server.

Step 5: Confirm the server is running

Rest Server runs as a systemd service bound to 127.0.0.1:8000 only, with nginx terminating TLS on port 443 as the single network facing surface. Confirm both services are active and that rest-server is listening on loopback only:

systemctl is-active rest-server.service nginx.service
sudo ss -ltnp | grep -E ':8000|:443|:80 '
cat /opt/rest-server/VERSION

rest-server is listening on 127.0.0.1:8000 and never on a public interface; nginx owns ports 443 and 80. This is what keeps the server from being an open, anonymous repository.

Step 6: Verify the authentication boundary

nginx fronts the entire REST backend with HTTP basic authentication, so an unauthenticated request is rejected. An unauthenticated /healthz probe is available for load balancers. Confirm the boundary:

# no credentials -> 401 Unauthorized (the server is never open)
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/restic/

# a wrong password is also rejected -> 401
curl -sk -u restic:wrong-password -o /dev/null -w '%{http_code}\n' https://127.0.0.1/restic/

# unauthenticated load-balancer liveness probe -> 200
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/healthz

Step 7: Back up to the server with restic

From any machine that has the restic client installed, point restic at this instance and run a normal backup. Because the TLS certificate is self signed per instance, either copy this instance's certificate from /etc/nginx/tls/rest-server.crt and trust it, or pass --insecure-tls. Use the username and password from your credentials file, and choose a strong repository encryption password of your own.

# from your own machine, using the per instance credentials
export RESTIC_REPOSITORY="rest:https://restic:<REST_SERVER_PASSWORD>@<public-ip>/restic/myrepo"
export RESTIC_PASSWORD="choose-a-strong-repository-encryption-password"

restic --insecure-tls init
restic --insecure-tls backup /path/to/data
restic --insecure-tls snapshots

The first restic init creates the repository under your user's namespace on the data volume; restic backup uploads deduplicated, encrypted data; and restic snapshots lists what has been stored. With --private-repos the restic user can only access repositories under its own namespace (rest:https://restic:...@<host>/restic/<repo>). The repository store is on the dedicated data volume, so you can confirm where your backups live and how much room remains:

df -h /var/lib/restic

To roll the server out across a fleet, distribute the certificate and the per instance credentials to the machines that will back up to it. For production use, replace the self signed certificate with one signed by your own certificate authority or a public CA for your domain, and add additional restic users with htpasswd.

Configuration and data layout

To add a restic user or rotate a password, update /etc/rest-server/.htpasswd with htpasswd -B and run sudo systemctl restart rest-server.service. To change the TLS certificate, replace the files under /etc/nginx/tls and run sudo systemctl reload nginx.

Support

This Rest Server image is supported 24/7 by cloudimg. For deployment help, pointing restic clients at the server from workstations, servers and CI, repository and namespace layout, append only and private repository patterns, credential rotation and adding users, nginx TLS with your own domain and certificate, data volume sizing, Rest Server version upgrades, or any other question, contact support@cloudimg.co.uk. Critical issues receive a one hour average response time.

Rest Server and restic are trademarks of their respective owners. This is a repackaged open source software product with additional charges for cloudimg support services.