Upgrading to Barman 3.12 - sha256 vs md5 checksum

[Stan]

Hello,

I have a Barman 3.10 server that backups a Postgres 16 server (two separate machines).
I am planning to upgrade to Barman 3.12, so my first step was to update the software on the Postgres server. That went OK until it started archiving, and I got the following error:

ERROR: Missing checksum for file '00000001000007D60000008F' in put-wal for server 'pg_live' (SSH host: 10.0.0.1)
ERROR: Remote 'barman put-wal' command has failed!
2025-02-14 12:54:39.563 [892] LOG:  archive command failed with exit code 1
2025-02-14 12:54:39.563 [892] DETAIL:  The failed archive command was: barman-wal-archive 10.0.0.2 pg_live pg_wal/00000001000007D60000008F

That's when I came upon the following note saying that the checksum had changed from md5 to sha256: https://docs.pgbarman.org/release/3.12.0/releases/index.html
By adding the "--md5" parameter to the "barman-wal-archive" command the error is fixed, but I am not sure how to proceed from here.

If I update the Barman server to 3.12, I assume it will start using the sha256 checksum? What does that mean for any previously archived WAL files?
Is there perhaps some step-by-step tutorial on how to upgrade a Barman setup?

[Israel Barth]

Hello,

> That's when I came upon the following note saying that the checksum had changed from md5 to sha256: https://docs.pgbarman.org/release/3.12.0/releases/index.html

> By adding the "--md5" parameter to the "barman-wal-archive" command the error is fixed, but I am not sure how to proceed from here.
> 
> If I update the Barman server to 3.12, I assume it will start using the sha256 checksum? What does that mean for any previously archived WAL files?
> Is there perhaps some step-by-step tutorial on how to upgrade a Barman setup?

Right, once you update Barman in your backup host, it will start accepting sha256 as well.

About previously archived WAL files, you don't need to care about them.

The md5 or sha256 sum is used by the server only when receiving the WAL file through `barman-wal-archive`, to make sure it's receiving the expected content.

The `--md5` flag was introduced to `barman-wal-archive` as a temporary workaround for people that upgrade `barman-cli` in the Postgres host before upgrading `barman` in the Barman host.

That way, as the server would only check for md5, and the client would ship sha256 by default, you could use the flag to instruct the client to ship md5 instead, making it possible for the server to accept the WAL file.

It is worth noting that you only hit that situation if you upgrade the client before upgrading the server.

In cases where the server is upgraded first, it's able to handle both md5 and sha256, thus keeping compatibility with `barman-cli` older than 3.12.0 with no changes being required.

In any case, if you upgraded the client first and you are using `--md5` for now, it's recommended switching to sha256 once both the client and server are running 3.12.0 or newer.

Best regards,
Israel.