Donate to Postulo/postulo

• https://buymeacoffee.com/tiagoagueda

---

See the documentation for more details on donation links.

Send each verified backup to a destination plugin, encrypted with age (#325) #1071

Merged

tiagoagueda merged 1 commit from 325-backup-destinations into main 2026-10-28 15:33:54 +00:00

Conversation 0 Commits 1 Files changed 117 +20484 -174

tiagoagueda commented 2026-10-27 17:41:39 +00:00

Owner

• Copy link
• Copy Markdown

A copy of the instance on the same disk is no help the day the disk goes, and the core gave
a plugin no way to receive one: no kind was about backups, and the only instance-level
plugin settings were the transports'. This adds that kind and everything around it.

The kind: backup-destination, entry-point group postulo.backups, with
BackupDestinationPlugin (config_fields, test, send, list, delete; validate optional, as
for a connected plugin), BackupArchive, BackupManifest and BackupRef on
postulo.plugins.api. It is ungoverned, like a transport, and wired into GROUPS, LABELS and
TONES. postulo.plugins.testing publishes assert_is_a_backup_destination, which sends,
lists and deletes one archive through a destination: what retention relies on.

Settings: a trio on SiteSettings like the transports' (plugin name, JSON configuration,
secrets under the field key), drawn from the plugin's FieldSpecs on a page of its own under
Server settings -> Backups, secrets masked and kept when left blank, a log line naming who
changed the destination. A destination is refused without an age recipient.

Encryption: the core encrypts each archive with pyrage (MIT, abi3 wheels for linux amd64 and
aarch64, maintained; 1.2.0-1.2.2 had GHSA-47h8-jmp3-9f28, so the floor is 1.4) to an X25519
recipient, the only kind accepted: a plugin recipient names a program for age to run. Only
the public key is stored. The encrypted copy is a scratch file deleted after the send.

Sending: an archive verified into POSTULO_BACKUP_DIR (schedule, Back up now, or
manage.py backup unless --no-send) queues an OffsiteBackup row. The scheduler sends it
after its pass's own work, in the worker when there is one, as document copies are sent:
claim with a lease, retry with a doubling wait, six attempts, then an administrator's Send.
The upload runs inside a deadline that ends before the lease. Remote retention follows only
a confirmed send, keeps the newest N (its own number, the local one when blank, 0 for none)
and deletes only references the plugin's list() returned and Postulo itself sent. Local
retention never rotates an archive still waiting for the destination.

What staff see: Sent/Waiting/Failed (in the plugin's words) per archive, a Send button, a
failed send on Overview, and postulo_backup_offsite_last_success_timestamp_seconds and
postulo_backup_offsite_failures_total. Every new address is staff only and a 404 otherwise;
each send and remote delete is logged. THREAT-MODEL gains the destination as an attacker.

Closes #325

Notes for review

• The maintainer's decisions (the issue's recommendations):
  • The destination is a transport-style trio on SiteSettings.
  • The core encrypts every archive to an age recipient before any destination sees it, and refuses a destination without one.
  • manage.py backup queues a send, with --no-send to skip.
• Encryption: pyrage>=1.4,<2.
  • MIT, maintained, abi3 wheels for linux amd64 and aarch64.
  • GHSA-47h8-jmp3-9f28 affects only 1.2.1–1.2.2, below the floor.
  • Only X25519 recipients are accepted.
• Sending:
  • Modelled on document copies: a 4-hour lease, a doubling wait from 10 minutes, and 6 attempts until staff press Send.
  • The upload runs under a deadline 15 minutes inside the lease.
  • Without a worker, at most one archive is sent per pass, after the pass's own work.
• Decisions the issue left open:
  • Remote retention deletes only what list() returned and Postulo itself sent, so a destination's other files are never touched.
  • Local retention keeps an archive the destination has not received yet.
  • Changing the destination clears its settings, and queued rows for the old one are no longer sent.
• No destination plugin ships with this. postulo/postulo-dav#6 is the first.
• Migration: core 0039_backup_destination.
• Wiki: Writing a plugin, Backups and your data and Health, metrics and logs are applied when this merges.

🤖 Generated with Claude Code

A copy of the instance on the same disk is no help the day the disk goes, and the core gave a plugin no way to receive one: no kind was about backups, and the only instance-level plugin settings were the transports'. This adds that kind and everything around it. The kind: `backup-destination`, entry-point group `postulo.backups`, with `BackupDestinationPlugin` (config_fields, test, send, list, delete; validate optional, as for a connected plugin), `BackupArchive`, `BackupManifest` and `BackupRef` on `postulo.plugins.api`. It is ungoverned, like a transport, and wired into GROUPS, LABELS and TONES. `postulo.plugins.testing` publishes `assert_is_a_backup_destination`, which sends, lists and deletes one archive through a destination: what retention relies on. Settings: a trio on SiteSettings like the transports' (plugin name, JSON configuration, secrets under the field key), drawn from the plugin's FieldSpecs on a page of its own under Server settings -> Backups, secrets masked and kept when left blank, a log line naming who changed the destination. A destination is refused without an age recipient. Encryption: the core encrypts each archive with pyrage (MIT, abi3 wheels for linux amd64 and aarch64, maintained; 1.2.0-1.2.2 had GHSA-47h8-jmp3-9f28, so the floor is 1.4) to an X25519 recipient, the only kind accepted: a plugin recipient names a program for age to run. Only the public key is stored. The encrypted copy is a scratch file deleted after the send. Sending: an archive verified into POSTULO_BACKUP_DIR (schedule, Back up now, or `manage.py backup` unless --no-send) queues an OffsiteBackup row. The scheduler sends it after its pass's own work, in the worker when there is one, as document copies are sent: claim with a lease, retry with a doubling wait, six attempts, then an administrator's Send. The upload runs inside a deadline that ends before the lease. Remote retention follows only a confirmed send, keeps the newest N (its own number, the local one when blank, 0 for none) and deletes only references the plugin's list() returned and Postulo itself sent. Local retention never rotates an archive still waiting for the destination. What staff see: Sent/Waiting/Failed (in the plugin's words) per archive, a Send button, a failed send on Overview, and postulo_backup_offsite_last_success_timestamp_seconds and postulo_backup_offsite_failures_total. Every new address is staff only and a 404 otherwise; each send and remote delete is logged. THREAT-MODEL gains the destination as an attacker. Closes #325 ## Notes for review - **The maintainer's decisions (the issue's recommendations):** - The destination is a transport-style trio on `SiteSettings`. - The core encrypts every archive to an age recipient before any destination sees it, and refuses a destination without one. - `manage.py backup` queues a send, with `--no-send` to skip. - **Encryption:** `pyrage>=1.4,<2`. - MIT, maintained, abi3 wheels for linux amd64 and aarch64. - GHSA-47h8-jmp3-9f28 affects only 1.2.1–1.2.2, below the floor. - Only X25519 recipients are accepted. - **Sending:** - Modelled on document copies: a 4-hour lease, a doubling wait from 10 minutes, and 6 attempts until staff press *Send*. - The upload runs under a deadline 15 minutes inside the lease. - Without a worker, at most one archive is sent per pass, after the pass's own work. - **Decisions the issue left open:** - Remote retention deletes only what `list()` returned **and** Postulo itself sent, so a destination's other files are never touched. - Local retention keeps an archive the destination has not received yet. - Changing the destination clears its settings, and queued rows for the old one are no longer sent. - **No destination plugin ships with this.** postulo/postulo-dav#6 is the first. - **Migration:** `core 0039_backup_destination`. - **Wiki:** *Writing a plugin*, *Backups and your data* and *Health, metrics and logs* are applied when this merges. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

tiagoagueda added 1 commit 2026-10-27 17:41:39 +00:00

Send each verified backup to a destination plugin, encrypted with age (#325) ... a63b47d31f

A copy of the instance on the same disk is no help the day the disk goes, and the core gave
a plugin no way to receive one: no kind was about backups, and the only instance-level
plugin settings were the transports'. This adds that kind and everything around it.

The kind: `backup-destination`, entry-point group `postulo.backups`, with
`BackupDestinationPlugin` (config_fields, test, send, list, delete; validate optional, as
for a connected plugin), `BackupArchive`, `BackupManifest` and `BackupRef` on
`postulo.plugins.api`. It is ungoverned, like a transport, and wired into GROUPS, LABELS and
TONES. `postulo.plugins.testing` publishes `assert_is_a_backup_destination`, which sends,
lists and deletes one archive through a destination: what retention relies on.

Settings: a trio on SiteSettings like the transports' (plugin name, JSON configuration,
secrets under the field key), drawn from the plugin's FieldSpecs on a page of its own under
Server settings -> Backups, secrets masked and kept when left blank, a log line naming who
changed the destination. A destination is refused without an age recipient.

Encryption: the core encrypts each archive with pyrage (MIT, abi3 wheels for linux amd64 and
aarch64, maintained; 1.2.0-1.2.2 had GHSA-47h8-jmp3-9f28, so the floor is 1.4) to an X25519
recipient, the only kind accepted: a plugin recipient names a program for age to run. Only
the public key is stored. The encrypted copy is a scratch file deleted after the send.

Sending: an archive verified into POSTULO_BACKUP_DIR (schedule, Back up now, or
`manage.py backup` unless --no-send) queues an OffsiteBackup row. The scheduler sends it
after its pass's own work, in the worker when there is one, as document copies are sent:
claim with a lease, retry with a doubling wait, six attempts, then an administrator's Send.
The upload runs inside a deadline that ends before the lease. Remote retention follows only
a confirmed send, keeps the newest N (its own number, the local one when blank, 0 for none)
and deletes only references the plugin's list() returned and Postulo itself sent. Local
retention never rotates an archive still waiting for the destination.

What staff see: Sent/Waiting/Failed (in the plugin's words) per archive, a Send button, a
failed send on Overview, and postulo_backup_offsite_last_success_timestamp_seconds and
postulo_backup_offsite_failures_total. Every new address is staff only and a 404 otherwise;
each send and remote delete is logged. THREAT-MODEL gains the destination as an attacker.

Closes #325

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tiagoagueda force-pushed 325-backup-destinations from a63b47d31f to abc968c2e8 2026-10-27 22:40:29 +00:00 Compare

tiagoagueda force-pushed 325-backup-destinations from abc968c2e8 to a8fda0cd0b 2026-10-28 07:44:54 +00:00 Compare

tiagoagueda force-pushed 325-backup-destinations from a8fda0cd0b to ffec2c933f 2026-10-28 15:30:20 +00:00 Compare

tiagoagueda merged commit db472555cd into main 2026-10-28 15:33:54 +00:00

tiagoagueda referenced this pull request from a commit 2026-10-28 15:33:55 +00:00

Send each verified backup to a destination plugin, encrypted with age (#325) (#1071)

tiagoagueda deleted branch 325-backup-destinations 2026-10-28 15:33:57 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

accessibility

Usable by everyone, including people with disabilities: one of the project's stated missions

  

authentication

Signing in, and proving who you are

  

breaking change

Changes behaviour or data in a way operators must act on

  

bug

Something does not do what it says it does

  

documentation

The wiki, the docs, or the words in the interface

  

enhancement

An improvement or a new capability

  

interface

The shape of the pages: what is where, and how it reads

  

internationalisation

Languages, regions, and the formats and symbols that go with them

  

observability

What an operator can see about a running instance: metrics, logs, health

  

performance

Uses fewer resources, or is more reliable, with no loss of features or accessibility

  

security

Keeping the code and the data secure: one of the project's stated missions

  

tier

1

Easy: small, self-contained, no prerequisites

  

tier

2

High-severity security: account access, personal data, the boundaries

  

tier

3

Foundations: prerequisite work that unblocks other issues

  

tier/4

Later: large features and long-horizon work

No labels

accessibility

authentication

breaking change

bug

documentation

enhancement

interface

internationalisation

observability

performance

security

tier

1

tier

2

tier

3

tier/4

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Postulo/postulo!1071

No description provided.