Verify Files with b2sum Without Losing the Checkpoint

A file that looks fine can still be silently corrupted, and b2sum gives you a fingerprint you can check again later to prove it has not changed. You will finish with a checksum file you can rerun any time. The examples use b2sum from GNU coreutils 9.4, installed here as package version 9.4-3ubuntu6.3. Allow about ten minutes. You need a shell and read access to the files you want to fingerprint; no elevated privileges are normally needed.

b2sum computes a BLAKE2b digest. Its default is a 512-bit digest, printed as hexadecimal followed by the file name. A digest is an integrity checkpoint, not encryption and not proof that a file came from a trustworthy person.

1. Check the installed command

Confirm the binary and version before relying on output in a script. These are ordinary read-only commands:

$ command -v b2sum
/usr/bin/b2sum
$ b2sum --version
b2sum (GNU coreutils) 9.4
$ dpkg-query -W -f='${Package} ${Version}\n' coreutils
coreutils 9.4-3ubuntu6.3

Checkpoint: if the version or path is not what you expect, stop and establish which package your shell is using. Do not compare checksums produced by an unknown replacement command merely because it has the same name.

2. Create a checksum

Run b2sum with one or more files. This reads the files and writes the result to standard output without changing them:

$ b2sum /path/to/report.iso
<128 hexadecimal characters>  /path/to/report.iso

The two spaces before the file name are part of the normal output format. The marker between the digest and the name indicates text or binary input mode. On GNU systems there is no practical difference between the default text mode and --binary, but retaining the marker makes the checksum file portable to tools that distinguish them.

For a repeatable local test, make a small file and hash it:

$ printf 'hello from b2sum\n' > sample.txt
$ b2sum sample.txt
d795b9bbe68044050d1bbb2d264c91a0d9fc68da5e20a488ccf9a97c51739b15aab638126b17372954a7123648f80175b886b6591ffdd270bce57ef5fd4a685c  sample.txt

Creating sample.txt changes the current directory. If a file with that name already exists, shell redirection truncates it before printf runs. Use a new working directory or a clearly disposable name when testing.

3. Save the result beside the source

Save the output to a separate checksum file. This is the checkpoint you will carry with the file or keep in a trusted manifest:

$ b2sum sample.txt > sample.txt.b2
$ cat sample.txt.b2
d795b9bbe68044050d1bbb2d264c91a0d9fc68da5e20a488ccf9a97c51739b15aab638126b17372954a7123648f80175b886b6591ffdd270bce57ef5fd4a685c  sample.txt

The redirection overwrites an existing sample.txt.b2. That is reversible only if you have another copy, so inspect the destination first if it may contain a useful manifest. For several files, pass them all in one command or write several lines to the same manifest with >> after checking that the existing file is the one you intend to extend.

To hash standard input instead of a named file, use a pipe or the explicit file name -:

$ printf 'hello from b2sum\n' | b2sum
d795b9bbe68044050d1bbb2d264c91a0d9fc68da5e20a488ccf9a97c51739b15aab638126b17372954a7123648f80175b886b6591ffdd270bce57ef5fd4a685c  -

4. Verify the file later

Use --check with the saved manifest. It reads the recorded file names, hashes those files again, and compares the results:

$ b2sum --check sample.txt.b2
sample.txt: OK
$ printf 'exit status: %s\n' "$?"
exit status: 0

A changed file produces a failed line and a non-zero exit status. The useful automation rule is to test the status, not to search for the word OK:

$ b2sum --status sample.txt.b2
$ printf 'exit status: %s\n' "$?"
exit status: 0

--status prints nothing when verification succeeds. Combine it with --check; using it by itself is an error because it only has meaning during verification.

Before checking a manifest from someone else, inspect it. The file names in a checksum manifest control what b2sum reads, so a manifest can make a command inspect unexpected paths. Do not treat an untrusted manifest as a safe file-selection list.

5. Select a shorter digest when required

Use --length=BITS, or its short form, to request a digest length in bits. The value must be a multiple of eight and cannot exceed 512:

$ b2sum --length=256 sample.txt
e6760b5fbf45583f22f0832f2cc9725884bcb6da5441d4b7afe28680e24f9198  sample.txt

Choose the length before publishing a checksum. A 256-bit digest and a 512-bit digest for the same file are different records, so verification must use the same length that created the manifest. If you do not have a compatibility reason, leave the default at 512 bits.

6. Choose output and verification controls deliberately

--tag emits a BSD-style line, useful when another tool specifically asks for that format:

$ b2sum --tag sample.txt
BLAKE2b (sample.txt) = d795b9bbe68044050d1bbb2d264c91a0d9fc68da5e20a488ccf9a97c51739b15aab638126b17372954a7123648f80175b886b6591ffdd270bce57ef5fd4a685c

For verification, --quiet suppresses successful lines but leaves failures visible. --ignore-missing does not fail or report a missing file. That is useful for a deliberately partial manifest, but dangerous if absence should count as failure. --strict makes improperly formatted checksum lines an error; --warn reports such lines while continuing. These options do not repair a bad manifest.

--zero terminates output records with a NUL byte and disables file-name escaping. Use it only when the next program explicitly expects NUL-delimited records. It is not a general replacement for the normal newline format, and it should not be mixed casually with ordinary checksum files.

7. Diagnose the common failures

A missing input or an unreadable path gives a non-zero status. Check the path and permissions without changing them:

$ test -r sample.txt && echo readable
readable
$ ls -l sample.txt sample.txt.b2

If verification reports a mismatch, preserve the file and manifest. First check that you are in the intended directory, then compare the file's provenance, transfer method and timestamp. Do not regenerate the manifest over the mismatch: that records the new bytes and destroys the evidence of what changed.

Text and binary mode are equivalent on GNU systems, but do not assume that every non-GNU implementation treats them alike. If a manifest must be exchanged across operating systems or utilities, agree on the producer, digest length and output format first. Keep the original file until verification has passed.

Done means