Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,24 @@ current uv-based install, development, and release instructions.

## [Unreleased]

## [2.0.5] - 2026-10-22

### Fixed

- Central cloud retention honors an explicitly configured positive deletion
grace period instead of imposing a thirty-day minimum. Thirty days remains
the recommended profile; shorter grace reduces historical protection and
does not establish a thirty-day recovery guarantee. Live aged reclamation
remains unqualified under issue #25.

### Changed

- Issues #23–#26 were canceled and closed as not planned. Their implementations
remain experimental and unqualified. This release adds no new live provider
qualification; the existing workstation results remain historical.
- Stable support remains at the v2.0.4 tested core scope; the retention policy
change adds no provider or recovery qualification.

## [2.0.4] - 2026-10-21

### Added
Expand Down Expand Up @@ -653,7 +671,8 @@ are still under development. See [implementation status](docs/development/versio

The `Unreleased` comparison is a live `HEAD` link for navigation, not an immutable historical citation.

[Unreleased]: https://github.com/CruxExperts/BestBackup/compare/v2.0.4...HEAD
[Unreleased]: https://github.com/CruxExperts/BestBackup/compare/v2.0.5...HEAD
[2.0.5]: https://github.com/CruxExperts/BestBackup/compare/v2.0.4...v2.0.5
[2.0.4]: https://github.com/CruxExperts/BestBackup/compare/v2.0.3...v2.0.4
[2.0.3]: https://github.com/CruxExperts/BestBackup/compare/v2.0.2...v2.0.3
[2.0.2]: https://github.com/CruxExperts/BestBackup/compare/v2.0.1...v2.0.2
Expand Down
20 changes: 10 additions & 10 deletions INSTALL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Install bbackup

This guide covers stable v2.0.4 for its tested file, database, dashboard, and AMD64 package scope. New cloud and Linux recovery workflows are experimental and unqualified; B2/AWS, native Docker, ARM64 package functionality, and broader recovery guarantees remain outside the qualified scope. The retained 1.x tag remains available as v1.8.6.
This guide covers stable v2.0.5 for its tested file, database, dashboard, and AMD64 package scope. New cloud and Linux recovery workflows are experimental and unqualified; B2/AWS, native Docker, ARM64 package functionality, and broader recovery guarantees remain outside the qualified scope. The retained 1.x tag remains available as v1.8.6.

## Version 2 stable release

Expand All @@ -9,24 +9,24 @@ The stable release uses Python 3.12 or newer and the `restic` executable. Instal
Install the pinned stable release with uv:

```bash
uv tool install --force 'git+https://github.com/CruxExperts/BestBackup.git@v2.0.4'
uv tool install --force 'git+https://github.com/CruxExperts/BestBackup.git@v2.0.5'
bbackup --version
bbackup production --help
```

The command is pinned to the `v2.0.4` source tag. To inspect or modify the source, use the development checkout below.
The command is pinned to the `v2.0.5` source tag. To inspect or modify the source, use the development checkout below.

### Optional native database clients

PostgreSQL capture requires `pg_dump` and `psql` for source metadata; restoring into PostgreSQL requires `psql` and `pg_restore`. MySQL capture requires `mysql` and `mysqldump`, or the compatible MariaDB clients. Database clients are not installed by the Python package. MySQL/MariaDB capture requires an explicit read-lock policy and pauses database writes during the dump.

### Optional systemd scheduling

Version 2.0.4 supports explicit user-level installation through `service install`, with activation only when `--activate` is supplied. Scheduled file capture/copy/restore, missed-timer catch-up, and abrupt interruption without replay passed isolated Ubuntu 24.04/26.04 AMD64 guest drills; this does not qualify every host configuration or the root-owned Debian templates. Review [the quick start](QUICKSTART.md#apply-a-schedule-deliberately) and the [development candidate reboot qualification](docs/development/version-2.md#development-candidate-rebootable-systemd-qualification) before enabling a schedule. A user timer needs a user systemd manager and may need administrator-managed lingering to run after logout or at boot.
Version 2.0.5 supports explicit user-level installation through `service install`, with activation only when `--activate` is supplied. Scheduled file capture/copy/restore, missed-timer catch-up, and abrupt interruption without replay passed isolated Ubuntu 24.04/26.04 AMD64 guest drills; this does not qualify every host configuration or the root-owned Debian templates. Review [the quick start](QUICKSTART.md#apply-a-schedule-deliberately) and the [development candidate reboot qualification](docs/development/version-2.md#development-candidate-rebootable-systemd-qualification) before enabling a schedule. A user timer needs a user systemd manager and may need administrator-managed lingering to run after logout or at boot.

### Cloud repositories

Restic repositories can use local storage, Backblaze B2 through the S3 API, or Amazon S3. Cloud providers are configurable but not production-qualified in v2.0.4. Configure credentials in the supervised process environment. Do not place credentials in portable JSON policy or a repository URL. See [cloud storage](docs/cloud-storage.md) for experimental provider setup and limits.
Restic repositories can use local storage, Backblaze B2 through the S3 API, or Amazon S3. Cloud providers are configurable but not production-qualified in v2.0.5. Configure credentials in the supervised process environment. Do not place credentials in portable JSON policy or a repository URL. See [cloud storage](docs/cloud-storage.md) for experimental provider setup and limits.

## Existing 1.x release

Expand Down Expand Up @@ -81,7 +81,7 @@ sudo env \
UV_TOOL_DIR=/opt/uv/tools \
UV_TOOL_BIN_DIR=/usr/local/bin \
"$UV" tool install --force \
'git+https://github.com/CruxExperts/BestBackup.git@v2.0.4'
'git+https://github.com/CruxExperts/BestBackup.git@v2.0.5'

bbackup --version
```
Expand Down Expand Up @@ -113,12 +113,12 @@ Install a newer release tag with `uv tool install --force` and the exact tag. Pr

## Debian package installation

Native Ubuntu packages target Ubuntu 24.04 with Python 3.12 and Ubuntu 26.04 with Python 3.14, on amd64 or arm64. The v2.0.4 production-qualified package scope is amd64 only; ARM64 artifacts, if built, are unqualified pending functional capture/restore smoke tests. Use a package built natively for the target release, architecture, and Python version; the package builder refuses cross-build labels.
Native Ubuntu packages target Ubuntu 24.04 with Python 3.12 and Ubuntu 26.04 with Python 3.14, on amd64 or arm64. The v2.0.5 production-qualified package scope is amd64 only; ARM64 artifacts, if built, are unqualified pending functional capture/restore smoke tests. Use a package built natively for the target release, architecture, and Python version; the package builder refuses cross-build labels.

Inspect the package, contents, manifest, and checksum before installing. For the Ubuntu 24.04 AMD64 artifact:

```bash
PACKAGE=dist/deb/bbackup_2.0.4_ubuntu24.04_amd64.deb
PACKAGE=dist/deb/bbackup_2.0.5_ubuntu24.04_amd64.deb
(cd "$(dirname "$PACKAGE")" && sha256sum -c "$(basename "${PACKAGE%.deb}.sha256")")
dpkg-deb --info "$PACKAGE"
dpkg-deb --contents "$PACKAGE"
Expand All @@ -130,13 +130,13 @@ cat "$REVIEW_DIR/usr/share/doc/bbackup/build-manifest.json"
Install only after reviewing that output:

```bash
sudo apt install ./dist/deb/bbackup_2.0.4_ubuntu24.04_amd64.deb
sudo apt install ./dist/deb/bbackup_2.0.5_ubuntu24.04_amd64.deb
bbackup --version
bbman --help
```

The release build matrix targets four uniquely named native packages: `bbackup_<version>_ubuntu24.04_amd64.deb`, `bbackup_<version>_ubuntu24.04_arm64.deb`, `bbackup_<version>_ubuntu26.04_amd64.deb`, and `bbackup_<version>_ubuntu26.04_arm64.deb`. A configured matrix is not evidence that all four artifacts have been built or qualified. Each package contains the versioned Python package, its locked dependencies, and the verified restic binary. Installation does not install Python packages into system Python, access a package index at runtime, enable or start services, or remove configuration, private bindings, credentials, repositories, or backup state.
The v2.0.4 release workflow also builds ARM64 packages, but its install smoke does not qualify backup/restore functionality on ARM64. Treat those packages as experimental.
The v2.0.5 release workflow also builds ARM64 packages, but its install smoke does not qualify backup/restore functionality on ARM64. Treat those packages as experimental.

Package upgrades and removals refuse while either command is active. A root-owned marker blocks both launchers while package files are changing. Successful configuration verifies the installed payload checksum manifest before clearing the marker. On abort, a marker requires the exclusive process lock and complete payload validation before removal. Without a marker, the abort hook takes a shared lock, verifies the payload and launchers, and returns without clearing anything; existing clients can continue while transition writers remain excluded.

Expand Down
2 changes: 1 addition & 1 deletion QUICKSTART.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Your first backup and verified restore

This guide covers v2.0.4 and its schema-3 policy. For an older v2.0.2 installation, use its [versioned quick start](https://github.com/CruxExperts/BestBackup/blob/v2.0.2/QUICKSTART.md) until you migrate. Keep an independently retrievable copy of each repository password.
This guide covers v2.0.5 and its schema-3 policy. For an older v2.0.2 installation, use its [versioned quick start](https://github.com/CruxExperts/BestBackup/blob/v2.0.2/QUICKSTART.md) until you migrate. Keep an independently retrievable copy of each repository password.

## Start with the guided dashboard

Expand Down
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

bbackup is an encrypted, restic-based backup tool for Linux system administrators, homelab and self-hosted operators, and small infrastructure teams. It brings local file backups, selected database workflows, verified file restores, and observable scheduled jobs into one operator workflow.

[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](LICENSE) [![Version 2.0.4](https://img.shields.io/badge/version-2.0.4-22c55e?style=flat-square)](https://github.com/CruxExperts/BestBackup/releases/latest)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](LICENSE) [![Version 2.0.5](https://img.shields.io/badge/version-2.0.5-22c55e?style=flat-square)](https://github.com/CruxExperts/BestBackup/releases/latest)

![bbackup: encrypted snapshot layers, an additional copy, and a restored document](docs/assets/bbackup-banner-v2.png)

Expand All @@ -22,25 +22,28 @@ Use bbackup when you want to know what a job captured, whether each repository c

![Real bbackup dashboard with disposable example data and illustrative capacity](docs/assets/bbackup-dashboard-preview.svg)

## v2.0.4 tested scope
## v2.0.5 tested scope

The qualified scope covers local file capture and restore; live capture and restore for PostgreSQL 17.11, MySQL 8.4.12, and MariaDB 11.8.9; headless dashboard happy paths; and AMD64 Ubuntu 24.04/26.04 packages. A separate real-guest user-timer reboot drill covers only the components and conditions recorded in the [qualification evidence](docs/development/version-2.md#development-candidate-rebootable-systemd-qualification).
The qualified scope is unchanged from v2.0.4: local file capture and restore; live capture and restore for PostgreSQL 17.11, MySQL 8.4.12, and MariaDB 11.8.9; headless dashboard happy paths; and AMD64 Ubuntu 24.04/26.04 packages. A separate real-guest user-timer reboot drill covers only the components and conditions recorded in the [qualification evidence](docs/development/version-2.md#development-candidate-rebootable-systemd-qualification).

B2/AWS, native Docker, ARM64 backup/restore, cross-application-version upgrades and rollback, root-owned systemd package templates, and cloud or off-host protection remain unqualified. ARM64 packages may be built, but build or package-install smoke checks alone do not qualify backup/restore. Keep an independently retrievable copy of repository passwords; a second repository on the same host does not protect against host loss. See [installation](INSTALL.md) for prerequisites and release install instructions.

Recent live B2 evidence covers a small interrupted maintenance run
whose prune outcome remained uncertain, and a separate lifecycle-overlap guard
that made central retention refuse the configured bucket. Neither test proves
prune completion, elapsed lifecycle expiry, physical reclamation, or provider
protection. These workflows ship in v2.0.4 as experimental and remain
protection. These workflows ship in v2.0.5 as experimental and remain
unqualified. See the [maintenance interruption record](docs/development/version-2.md#live-b2-central-maintenance-interruption-trial)
and [lifecycle guard evidence](docs/cloud-storage.md#b2-lifecycle-overlap-guard-experimental).
Requests #23–#26 remain open; the qualified core scope is unchanged from v2.0.3.
Issues #23–#26 were canceled and closed as not planned. Cancellation does not
qualify the experimental B2 workflow. This release adds no new live provider
qualification; the existing workstation results remain historical.
The qualified core scope is unchanged from v2.0.4.

## Start with the guided workflow

Experimental restricted cloud credentials, central recovery and retention,
bounded remote-primary capture, and reviewed Linux coverage ship in v2.0.4 and
bounded remote-primary capture, and reviewed Linux coverage ship in v2.0.5 and
are [documented with their limits](docs/development/version-2.md#experimental-cloud-and-machine-recovery-features).
The reviewed Linux coverage work includes an experimental manual PostgreSQL
path. These features do not expand the tested stable scope.
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This policy covers security issues in bbackup's source code and the packaged com

## Version status

Version 2.0.3 includes the reviewed safety and schema-3 enrollment changes. Supported scope and historical release boundaries are recorded in [release evidence](docs/development/version-2.md); reports for released and development code are welcome.
Version 2.0.5 includes the reviewed safety and schema-3 enrollment changes and the configurable central-retention grace fix. Supported scope and historical release boundaries are recorded in [release evidence](docs/development/version-2.md); reports for released and development code are welcome.

Security fixes are prepared for the latest published release. The project does not promise backports to older versions.

Expand Down
2 changes: 1 addition & 1 deletion SUPPORT.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ Use [GitHub Issues](https://github.com/CruxExperts/BestBackup/issues) for bugs a

For a bug report, include the bbackup version, Linux distribution, Python version, command, storage type, and a short description of the expected and observed behavior. Remove passwords, access keys, repository URLs with credentials, personal data, and sensitive file paths before posting configuration or output. Never attach host bindings or credential files.

Version 2.0.3 is supported only for its documented tested paths, including the bounded user-level scheduled file-backup guest drills. B2/AWS provider protection and independent host-loss recovery remain unqualified; see [release evidence and limits](docs/development/version-2.md). For development builds, include the commit and policy schema version.
Version 2.0.5 is supported only for its documented tested paths, including the bounded user-level scheduled file-backup guest drills. B2/AWS provider protection and independent host-loss recovery remain unqualified; see [release evidence and limits](docs/development/version-2.md). For development builds, include the commit and policy schema version.

For a security vulnerability, do not open a public issue. Follow the private process in [SECURITY.md](SECURITY.md).
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.0.4
2.0.5
2 changes: 1 addition & 1 deletion bbackup/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
Encrypted restic-based workflows; legacy Docker commands remain available.
"""

__version__ = "2.0.4"
__version__ = "2.0.5"
__author__ = "Slavic Kozyuk / Crux Experts LLC"
3 changes: 1 addition & 2 deletions bbackup/cloud.py
Original file line number Diff line number Diff line change
Expand Up @@ -1227,7 +1227,6 @@ def reconcile_central_retention(
"mutation_outcome_uncertain",
"policy_or_grant_expired",
]
_MIN_RETENTION_GRACE_SECONDS = 30 * 24 * 60 * 60
_PRIVATE_JSON_LIMIT = 16 * 1024 * 1024
_RETENTION_PLAN_FIELDS = {
"schema_version",
Expand Down Expand Up @@ -1658,7 +1657,7 @@ def _validate_retention_policy(
if any(type(counts[name]) is not int or counts[name] < 0 for name in counts):
raise CloudError("Central retention checkpoint counts are invalid")
for name, minimum in (
("grace_seconds", _MIN_RETENTION_GRACE_SECONDS),
("grace_seconds", 1),
("plan_max_age_seconds", 1),
("max_apply_objects", 1),
("max_apply_bytes", 1),
Expand Down
2 changes: 1 addition & 1 deletion bbackup/data/cli-skills.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CLI skills catalog

> Generated from the bbackup/bbman CLI metadata. Version: 2.0.4. This catalog is authoritative for this version.
> Generated from the bbackup/bbman CLI metadata. Version: 2.0.5. This catalog is authoritative for this version.
> Source: `bbackup/cli_metadata.py` rendered by `scripts/generate_cli_skills.py`; run the generator's `--check` mode before publishing.

## bbackup
Expand Down
4 changes: 2 additions & 2 deletions docs/PUBLISHING_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ Use this checklist before changing public project metadata or publishing a relea

## Version 2 tested-scope claims

- [ ] Describe v2.0.4 as qualified only for local file capture/restore, live PostgreSQL 17.11 / MySQL 8.4.12 / MariaDB 11.8.9 capture/restore, headless dashboard happy paths, and AMD64 Ubuntu 24.04/26.04 packages; this is the v2.0.3 tested core scope.
- [ ] Describe new v2.0.4 cloud and Linux workflows as experimental and unqualified; keep requests #23–#26 open and do not claim a guaranteed thirty-day window, off-host custody, final remote-server qualification, or complete-machine recovery.
- [ ] Describe v2.0.5 as qualified only for local file capture/restore, live PostgreSQL 17.11 / MySQL 8.4.12 / MariaDB 11.8.9 capture/restore, headless dashboard happy paths, and AMD64 Ubuntu 24.04/26.04 packages; this scope is unchanged from v2.0.4.
- [ ] Describe new v2.0.5 cloud and Linux workflows as experimental and unqualified; issues #23–#26 were canceled and closed as not planned. This release adds no new live provider qualification. Do not claim a guaranteed thirty-day window, off-host custody, final remote-server qualification, or complete-machine recovery.
- [ ] Keep B2/AWS, native Docker, ARM64 backup/restore, cross-application-version upgrades/rollback, root-owned systemd package templates, and cloud/off-host protection explicitly unqualified; describe the separate user-timer guest drills with their exact limits.
- [ ] State that ARM64 packages may be built by the release matrix but are not functionally qualified by package-install smoke alone.
- [ ] Keep native B2 capability inspection distinct from backup transfer; inspection is read-only and always reports `protection_qualified: false`.
Expand Down
Loading
Loading