Kopia 0.23.1

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick Kopia 0.23.1 on Ubuntu 24.04 as the software version, choose your Region, and select Launch through EC2. Choose m5.large, your key pair, and a security group as described in the prerequisites.

The AMI attaches the 30 GiB data volume for /var/lib/kopia automatically. Increase its size in the launch wizard's storage section to fit the data you will back up. Deduplication and compression usually make a repository much smaller than the data in it.

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=kopia}]'

Connect over SSH as the default login user for this version:

Kopia 0.23.1 on Ubuntu 24.04: log in as ubuntu

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

First boot generates the certificate, the passwords and the repository. The egress firewall, Kopia and nginx then start. Confirm that they are running:

systemctl is-active kopia nginx sac-kopia-egress
sudo test -f /var/lib/sac/data/kopia-firstboot.done && echo FIRSTBOOT_DONE

active active active FIRSTBOOT_DONE

Only SSH and nginx listen on the network. Kopia is on loopback behind nginx, and the DNS resolver listens on loopback only. Check the listeners:

sudo ss -lntp | awk 'NR>1 {print $4, $6}' | sed -E 's/pid=[0-9]+,fd=[0-9]+/.../g' | sort

0.0.0.0:22 users:(("sshd",...),("systemd",...)) 0.0.0.0:443 users:(("nginx",...),("nginx",...),("nginx",...)) 127.0.0.1:51515 users:(("kopia",...)) 127.0.0.53%lo:53 users:(("systemd-resolve",...)) 127.0.0.54:53 users:(("systemd-resolve",...)) [::]:22 users:(("sshd",...),("systemd",...)) [::]:443 users:(("nginx",...),("nginx",...),("nginx",...))

The repository is on its own volume. Confirm the size and mount point:

df -h /var/lib/kopia | awk 'NR==2 {print $2, $6}'

30G /var/lib/kopia

The credentials file is readable by root only. This command prints it with the passwords hidden. To show them, run sudo cat /root/kopia-credentials.txt:

sudo sed -E 's/^(KOPIA_[A-Z_]*PASSWORD=).*/\1<hidden>/' /root/kopia-credentials.txt

# Kopia 0.23.1 - generated on first boot by kopia-firstboot.service
# Every value below is unique to this instance; none was baked into the image. Keep this file secret.
# KOPIA_REPOSITORY_PASSWORD encrypts every backup in the repository: store a copy somewhere safe. Without it the
# repository cannot be opened, by you or by anyone else. KOPIA_URL=https://ec2-54-147-55-14.compute-1.amazonaws.com/ KOPIA_HOST=ec2-54-147-55-14.compute-1.amazonaws.com KOPIA_UI_USER=kopia KOPIA_UI_PASSWORD=<hidden> KOPIA_CONTROL_USER=server-control KOPIA_CONTROL_PASSWORD=<hidden> KOPIA_REPOSITORY=filesystem:/var/lib/kopia/repo KOPIA_REPOSITORY_PASSWORD=<hidden> KOPIA_CA_CERT=/etc/kopia/tls/kopia.crt KOPIA_CERT_SHA256=dc18ffc564a8a97838cba699bb606ebb5c0fdcc6611cf06f3256b481742079aa
#
# Web UI: https://<KOPIA_HOST>/ as KOPIA_UI_USER / KOPIA_UI_PASSWORD (the certificate is self-signed; see the guide).
# Back up another machine:
sudo kopia-add-client <user>@<host> (prints the client's connect command) # Run kopia against this repo: sudo kopia-admin snapshot list --all # New password: sudo kopia-rotate-password ui|control|repository # Change the name it serves as: sudo kopia-set-hostname <your-dns-name> # Allow a private storage host: sudo kopia-egress-allow add <cidr> # Disconnected in the web UI? sudo kopia-reconnect # User guide: https://secureanycloud.com/stacks/kopia-0-23-1/

Your instance shows its own DNS name and certificate fingerprint. Each value has a purpose:

KOPIA_UI_USER / KOPIA_UI_PASSWORD: sign in to the web UI.

KOPIA_CONTROL_USER / KOPIA_CONTROL_PASSWORD: authenticate to the server control API (/api/v1/control/), for scripts and monitoring.

KOPIA_REPOSITORY_PASSWORD: the key that encrypts the repository. Copy it to your password manager now. If the instance is lost, this password and a copy of the repository are what you need to restore.

KOPIA_CERT_SHA256: the certificate fingerprint that remote clients pin when they connect (Step 7).

The repository is open and ready:

sudo kopia-admin repository status | grep -E '^(Description|Storage type|Hash|Encryption|Splitter|Format version|Content compression)'

Description: sac Kopia server Storage type: filesystem Hash: BLAKE2B-256-128 Encryption: AES256-GCM-HMAC-SHA256 Splitter: DYNAMIC-4M-BUZHASH Format version: 3 Content compression: true

sudo kopia-admin runs the Kopia command line as the kopia service account against this repository. It passes the repository password in the environment instead of on the command line, and the same egress firewall applies as for the server.

The web UI is at KOPIA_URL from Step 4. Your browser warns about the certificate the first time, because it is self-signed for this instance. Compare the fingerprint the browser shows with KOPIA_CERT_SHA256 before you accept it, or install your own certificate (Step 10). Sign in with KOPIA_UI_USER and KOPIA_UI_PASSWORD.

To keep port 443 closed to the internet, reach the UI through SSH instead. The UI checks that a browser request comes from the name it is served as, so forward local port 443 (which needs sudo on your workstation) and browse to https://localhost/:

sudo ssh -i <your-key.pem> -N -L 443:localhost:443 ubuntu@<public-ip>

The Snapshots page lists every backed-up source in the repository, from this server and from remote clients:

Policies sets retention, compression, schedules and exclusions, globally or per source:

Repository shows the repository the server is connected to:

Tasks shows running and recent snapshot, restore and maintenance tasks:

Disconnect on the Repository page disconnects the server from its repository. The UI then offers to connect a repository instead of showing your snapshots, remote clients stop working, and after a restart Kopia stays down until it is connected again. Your backups are not touched.

If this happens, or the server was connected to a different repository and you want this instance's own back, run this on the instance:

sudo kopia-reconnect

kopia-reconnect: the server is connected to /var/lib/kopia/repo again; sign in to the web UI again

The command reconnects the server to /var/lib/kopia/repo with the repository password from the root-only /etc/kopia/server.env. The password is passed in Kopia's environment, never on a command line. The command restarts Kopia and waits until it reports the repository connected. All snapshots are back as they were, and the UI and client passwords are unchanged.

The server's own snapshots run as the kopia user, so they can read and write under /var/lib/kopia (the data volume). This command creates a small directory, snapshots it and lists the result:

sudo install -d -o kopia -g kopia -m 0750 /var/lib/kopia/demo echo "hello from sac" | sudo -u kopia tee /var/lib/kopia/demo/hello.txt >/dev/null
sudo kopia-admin snapshot create /var/lib/kopia/demo 2>&1 | tail -2 sudo kopia-admin snapshot list /var/lib/kopia/demo

Snapshotting kopia@ip-172-31-95-206:/var/lib/kopia/demo ... Created snapshot with root k60f7173849620b39fccffb529572bada and ID b6425124868ea0513164c7d653350432 in 0s kopia@ip-172-31-95-206:/var/lib/kopia/demo 2026-11-07 19:31:40 UTC k60f7173849620b39fccffb529572bada 20 B drwxr-x--- files:1 dirs:1 (latest-1,hourly-1,daily-1,weekly-1,monthly-1,annual-1)

Restore the latest snapshot to a new directory and read the file back:

ID=$(sudo kopia-admin snapshot list /var/lib/kopia/demo --json | jq -r '.[-1].id')
sudo kopia-admin snapshot restore "$ID" /var/lib/kopia/restore-demo 2>&1 | grep -v '^$' | tail -2 sudo cat /var/lib/kopia/restore-demo/hello.txt

Restoring to local filesystem (/var/lib/kopia/restore-demo) with parallelism=8... Restored 1 files, 1 directories and 0 symbolic links (20 B). hello from sac

The snapshot also appears on the web UI's Snapshots page. It can take a few seconds, so reload the page. The main use of this server is backing up other machines (Step 7).

Each machine you back up gets its own repository user, <user>@<host>, with its own password. Add one on the server:

sudo kopia-add-client alice@laptop

kopia-add-client: added alice@laptop; password in /root/kopia-clients/alice@laptop.password On the client (copy the password over a secure channel first): KOPIA_PASSWORD="$(cat alice@laptop.password)" kopia repository connect server --url=https://ec2-54-147-55-14.compute-1.amazonaws.com:443 \
  --server-cert-fingerprint=dc18ffc564a8a97838cba699bb606ebb5c0fdcc6611cf06f3256b481742079aa --override-username=alice --override-hostname=laptop

The server prints its own name and fingerprint (KOPIA_HOST and KOPIA_CERT_SHA256 from Step 4). It never prints the password. The password is in /root/kopia-clients/<user>@<host>.password (root only). Copy it to the client over a secure channel, for example with sudo cat in an SSH session.

On your client, install Kopia. In the directory that holds the password file, run the command that kopia-add-client printed. The server answers on its DNS name (KOPIA_HOST) and on its IP addresses, which are all in its certificate. The client pins the server's certificate by its fingerprint, so it needs no other trust setup. The connection fails if the fingerprint does not match. Then take snapshots as usual:

KOPIA_PASSWORD="$(cat alice@laptop.password)" kopia repository connect server --url=https://<public-ip>:443 \
  --server-cert-fingerprint=<KOPIA_CERT_SHA256> --override-username=alice --override-hostname=laptop rm alice@laptop.password kopia snapshot create ~/Documents kopia snapshot list

Every chunk the client uploads is deduplicated against everything already in the repository. The first snapshot of a machine takes longest, and later ones send only what changed. A client can see and restore its own snapshots only. To list every user on the server, or to remove one, run:

sudo kopia-admin server user list
sudo kopia-admin server user delete alice@laptop

The repository on the data volume is your primary copy. Keep a second copy somewhere else. EBS snapshots of the data volume are the simplest option.

To copy the repository to an S3 bucket in your account, give Kopia an access key for a user or role that can write that bucket only. Kopia cannot use an instance profile on this image, because it cannot reach the instance metadata service.

Pass the key in the environment, never on the command line. In your SSH session on the instance:

• Read the key into the shell without echoing it: read -rs AWS_ACCESS_KEY_ID; read -rs AWS_SECRET_ACCESS_KEY; export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY (type or paste each value and press Enter).
• Copy the repository: sudo --preserve-env=AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY kopia-admin repository sync-to s3 --bucket=<your-bucket> --region=<region>
• Clear the key from the shell: unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

The copy stays encrypted with the repository password, so the bucket only ever holds ciphertext. To keep the copy current, run the sync again, for example from a root cron job that reads the key from a root-only file. Only new blobs are sent.

Everything except the health check needs a password. The metrics endpoint is not served, a request for a host name the instance does not serve is dropped without an answer, and nothing answers on port 80. Verify each behaviour:

H=$(sudo sed -n 's/^KOPIA_HOST=//p' /root/kopia-credentials.txt) C=/etc/kopia/tls/kopia.crt
sudo curl -s --cacert $C -o /dev/null -w 'web UI, no password -> HTTP %{http_code}\n' https://$H/ printf 'user = "kopia:not-the-password"\n' | sudo curl -s --cacert $C -K - -o /dev/null -w 'wrong password -> HTTP %{http_code}\n' https://$H/
sudo curl -s --cacert $C -o /dev/null -w 'metrics -> HTTP %{http_code}\n' https://$H/metrics
sudo curl -s --cacert $C -o /dev/null -w 'health check -> HTTP %{http_code}\n' https://$H/healthz curl -sk -H 'Host: other.example' -o /dev/null -w 'unknown host -> %{http_code}\n' https://127.0.0.1/healthz || true curl -s -o /dev/null -w 'plain http :80 -> %{http_code}\n' --connect-timeout 3 http://127.0.0.1/ || true

web UI, no password -> HTTP 401 wrong password -> HTTP 401 metrics -> HTTP 404 health check -> HTTP 200 unknown host -> 000 plain http :80 -> 000

000 means no answer. nginx closes the connection for a host name it does not serve, and nothing listens on port 80. Only root and Kopia can read the certificate directory, which is why the commands use sudo curl.

The UI password opens the UI. The control password opens the control API only, which reports the server's state:

sudo bash -c ' H=$(sed -n "s/^KOPIA_HOST=//p" /root/kopia-credentials.txt) P=$(sed -n "s/^KOPIA_UI_PASSWORD=//p" /root/kopia-credentials.txt) printf "user = \"kopia:%s\"\n" "$P" | curl -s --cacert /etc/kopia/tls/kopia.crt -K - -o /dev/null -w "web UI with password -> HTTP %{http_code}\n" https://$H/ P=$(sed -n "s/^KOPIA_CONTROL_PASSWORD=//p" /root/kopia-credentials.txt) printf "user = \"server-control:%s\"\n" "$P" | curl -s --cacert /etc/kopia/tls/kopia.crt -K - https://$H/api/v1/control/status | jq "{connected, description, storage}"'

web UI with password -> HTTP 200 { "connected": true, "description": "sac Kopia server", "storage": "filesystem" }

The commands hand the passwords to curl on standard input, so they never appear in the process list.

The certificate is a leaf certificate for the instance's names:

sudo openssl x509 -noout -ext subjectAltName,basicConstraints,keyUsage,extendedKeyUsage -in /etc/kopia/tls/kopia.crt

X509v3 Subject Alternative Name: DNS:ec2-54-147-55-14.compute-1.amazonaws.com, IP Address:54.147.55.14, IP Address:172.31.95.206, IP Address:127.0.0.1, DNS:localhost X509v3 Basic Constraints: critical CA:FALSE X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Extended Key Usage: TLS Web Server Authentication

The egress firewall applies to every process running as the kopia user. Loopback is allowed. Link-local (including the metadata service), carrier-grade NAT, private and 0.0.0.0/8 addresses are refused:

sudo iptables -S OUTPUT | grep SAC
sudo iptables -S SAC-KOPIA-EGRESS | grep -E '^-A' | grep -v icmp

-A OUTPUT -m owner --uid-owner 997 -j SAC-KOPIA-EGRESS -A SAC-KOPIA-EGRESS -d 127.0.0.0/8 -o lo -j RETURN -A SAC-KOPIA-EGRESS -d 169.254.0.0/16 -p tcp -j REJECT --reject-with tcp-reset -A SAC-KOPIA-EGRESS -d 0.0.0.0/8 -p tcp -j REJECT --reject-with tcp-reset -A SAC-KOPIA-EGRESS -d 100.64.0.0/10 -p tcp -j REJECT --reject-with tcp-reset -A SAC-KOPIA-EGRESS -d 10.0.0.0/8 -p tcp -j REJECT --reject-with tcp-reset -A SAC-KOPIA-EGRESS -d 172.16.0.0/12 -p tcp -j REJECT --reject-with tcp-reset -A SAC-KOPIA-EGRESS -d 192.168.0.0/16 -p tcp -j REJECT --reject-with tcp-reset

Refused connections are reset at once instead of being dropped silently, so a storage URL that names an internal address fails immediately. Test this as the kopia user. The metadata service and a private address are refused, and Amazon S3 is reachable:

for t in http://169.254.169.254/latest/meta-data/ http://10.0.0.1/ https://s3.amazonaws.com/; do if code=$(sudo setpriv --reuid=kopia --regid=kopia --clear-groups -- curl -s -m 10 -o /dev/null -w '%{http_code}' "$t"); then echo "$t -> HTTP $code"; else echo "$t -> refused"; fi done

http://169.254.169.254/latest/meta-data/ -> refused http://10.0.0.1/ -> refused https://s3.amazonaws.com/ -> HTTP 307

Kopia runs as the unprivileged kopia user. Its service also carries the same ranges as a cgroup IPAddressDeny list, a second block that does not depend on iptables. nginx and the first-boot service cannot reach the metadata service:

ps -o user:8=,args= -C kopia | cut -c1-60 systemctl show kopia nginx kopia-firstboot -p Id -p IPAddressDeny

kopia /opt/kopia/kopia server start --address=https://127 IPAddressDeny=::ffff:0.0.0.0/96 0.0.0.0/8 fc00::/7 168.63.129.16/32 100.64.0.0/10 169.254.0.0/16 172.16.0.0/12 64:ff9b:1::/48 fe80::/10 10.0.0.0/8 64:ff9b::/96 192.168.0.0/16 Id=kopia.service IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32 Id=nginx.service IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32 Id=kopia-firstboot.service

sac-kopia-egress.service applies the rules in one atomic iptables-restore transaction per address family. A reload replaces the chain in a single step, a failed reload leaves the previous rules in place, and stopping the unit does not remove them. sudo systemctl reload sac-kopia-egress re-applies them.

Storage on a private address. If you point a repository or a sync at storage inside your network, such as a MinIO server or a NAS over WebDAV or SFTP, allow that host first. kopia-egress-allow accepts a private address or network inside the refused ranges above. Allow the single host, /32, rather than a whole range. The command refuses the metadata service, link-local addresses and anything that is not private. It updates both the iptables rules and the cgroup block, then restarts Kopia:

sudo kopia-egress-allow add 10.20.30.40/32
sudo kopia-egress-allow list
sudo kopia-egress-allow remove 10.20.30.40/32

sudo kopia-rotate-password ui, control or repository replaces that password with a new random one, writes it to /root/kopia-credentials.txt and applies it at once. The old password stops working.

• ui and control: Kopia restarts with the new password. Sign in to the web UI again.
• repository: changes the repository password (kopia repository change-password; the backups themselves are not rewritten) and restarts the server with it. If the change fails, the old password is kept. Store the new password where you kept the old one. Remote clients are not affected, because they use their own passwords.

sudo kopia-rotate-password ui

To use your own DNS name, point a DNS record at the instance, then set the name it is served as. This creates a new self-signed leaf certificate for the name (and the instance's IP addresses), updates nginx and the URL in the credentials file, and keeps the name across reboots. The certificate fingerprint changes, so reconnect remote clients with the new KOPIA_CERT_SHA256 afterwards:

sudo kopia-set-hostname <your-domain>

Components and their paths:

Kopia application: /opt/kopia/kopia (read-only, owner root)

Licence and build provenance: /usr/share/doc/kopia/

Repository, server configuration, cache and logs: /var/lib/kopia (data volume; repository in /var/lib/kopia/repo)

Server passwords (environment file): /etc/kopia/server.env (mode 0600)

Service units: kopia.service, sac-kopia-egress.service and kopia-firstboot.service in /etc/systemd/system/

Egress rules: /usr/local/sbin/kopia-egress-apply (--print shows the ruleset), with allowed hosts in /etc/sac/kopia-egress-allow

nginx site: /etc/nginx/sites-available/sac-kopia

Certificate and key: /etc/kopia/tls/

Helpers: /usr/local/sbin/kopia-admin, kopia-add-client, kopia-reconnect, kopia-rotate-password, kopia-set-hostname, kopia-egress-allow and kopia-guard

Credentials: /root/kopia-credentials.txt (mode 0600), with client passwords in /root/kopia-clients/

/opt/kopia/kopia --version grep -E '^(source|toolchain|changes)' /usr/share/doc/kopia/BUILD-PROVENANCE.txt | cut -c1-120 nginx -v 2>&1

0.23.1 build: 72ec08fd8edb86c67ed27099bf1b955e1f308ffa from: kopia/kopia source: https://github.com/kopia/kopia/archive/refs/tags/v0.23.1.tar.gz (tag commit 72ec08fd8edb86c67ed27099bf1b955e1 toolchain: go1.27.3 linux/amd64 (https://go.dev/dl/go1.27.3.linux-amd64.tar.gz, sha256 65efbc80fdc1fa2cd2631cad5b481777a changes: dependency raise only (go.mod, no source patch): github.com/klauspost/compress@v1.20.2 golang.org/x/net@v0.62 nginx version: nginx/1.24.0 (Ubuntu)

Logs: sudo journalctl -u kopia for the server, and /var/log/nginx/access.log for requests, with the real client address.

• Allow port 22 in the security group from your own networks only. Allow port 443 only from the machines you back up and your administrators' networks, or use the SSH tunnel (Step 5) for the web UI.
• Store KOPIA_REPOSITORY_PASSWORD outside the instance. Without it, no one, including SecureAnyCloud, can open the repository.
• Give each machine its own client user (Step 7), and delete the user when the machine is retired.
• Keep a second copy of the repository: EBS snapshots of the data volume, or a sync to S3 (Step 8).
• Run sudo kopia-admin snapshot verify --verify-files-percent=1 from time to time to check that backups can be read back.
• Use your own DNS name (Step 10), and rotate passwords when someone leaves or a password may have been exposed.
• Keep the operating system patched. Unattended security upgrades are on, and sudo apt-get update && sudo apt-get upgrade applies everything else.