README
December 7, 2019 · View on GitHub
B2TAG(1) User Commands B2TAG(1)
NAME b2tag - detect data corruption with checksums in extended attributes.
SYNOPSIS
b2tag [OPTION]...
DESCRIPTION b2tag is a re-implementation (in C) of shatag(1), which helps detect silent data corruption using checksums and extended attributes.
b2tag writes the last modification time (mtime) and the checksum of a
file into the file's extended attributes.
When run again, b2tag compares stored mtime and checksum to the file's
current mtime and checksum. It will print the name of each file
processed along with its status.
File statuses are:
backdated checksum is wrong and mtime is older than the sha tag
corrupt checksum is wrong and mtime matches the sha tag
invalid sha tag attributes are corrupt
new sha tag attributes have not been set
ok checksum is correct and the mtime matches
hash ok checksum is correct and the mtime has changed
outdated checksum is wrong and mtime is newer than the sha tag
(the file has been updated since the last run)
b2tag will automatically store the checksums and timestamps for new
files and will update the stored checksums and timestamps for hash ok
and outdated files (unless --dry-run is specified).
b2tag will not update the stored checksums and timestamps for
backdated, corrupt, or invalid files unless --force is specified.
b2tag aims to be format-compatible with shatag and uses the same
extended attributes (see the COMPATIBILITY section).
NOTES Since b2tag operates using extended attributes, any files specified must be stored on a filesystem that supports extended user attributes. Check your filesystem's documentation for more information.
For ext2/3/4, you may need to mount the filesystem with the user_xattr
option).
OPTIONS Positional Arguments FILE Files to check and hash.
Optional Arguments -c, --check Check the hashes on all specified files. Without this option, b2tag assumes all files with the same timestamp are OK without checking their contents.
-f, --force
Update the stored hashes for backdated, corrupted, or invalid
files.
-h, --help
Output a usage message and exit.
-n, --dry-run
Don't create or update any extended attributes (no on-disk
changes). This will still read and hash the specified files.
-p, --print
Print the hashes of all specified files in the sha*sum format.
-P, --no-dereference
Don't follow symbolic links. Without this option b2tag will
follow any symbolic link and process the file that it
references.
-q, --quiet
Only print errors including checksum failures. Can be specified
multiple times to print even fewer messages. This is the
opposite of --verbose.
-r, --recursive
Process directories and their contents (not just files).
-v, --verbose
Print more verbose messages error and warnings messages. Can be
specified multiple times to print even more messages. This is
the opposite of --quiet.
-V, --version
Output version information about b2tag and exit.
Hash Algorithms --blake2b Use the Blake2b 512-bit hash algorithm (default). On 64-bit machines, blake2b is usually the fastest.
--blake2s
Use the Blake2s 256-bit hash algorithm. On 32-bit machines,
blake2s is usually the fastest.
--sha512
Use the SHA-512 hash algorithm. On 64-bit machines, sha-512 is
usually much faster than sha256.
--sha256
Use the SHA-256 hash algorithm. SHA-256 is the only hash
algorithm supported by the original shatag utility. It is
usually the slowest hash algorithm on 64-bit machines.
--sha1 Use the SHA-1 hash algorithm. SHA-1 is not secure and is not
recommended.
--md5 Use the MD5 hash algorithm. MD5 is not secure and is not
recommended.
EXAMPLES Create or update the stored hashes for a file:
b2tag example.txt
Verify that a file matches its stored attributes with the sha256 hash
algorithm:
b2tag -c --sha256 example.txt
Verify all files in a directory, and filter-out OK file messages:
b2tag -cr /example/ | grep -v ': OK$'
Print a file's stored sha512 hashes:
b2tag -p --sha512 example.txt > example.sha512
This allows you to verify the file's contents with the sha512sum
utility (e.g. after copying the files to another machine without shatag
installed):
sha512sum -c example.sha512
Copy a file to a different machine and verify its contents:
rsync -tX example.txt user@example.com:example.txt
ssh user@example.com b2tag -cn example.txt
Create and update the hashes for all files over 1 MB on the root
filesystem:
find / -xdev -type f -size +1M -print0 | xargs -r0 b2tag > b2tag.log
To remove the extended attributes from all files:
find / -xdev -type f -exec setfattr -x user.shatag.ts {} \; -exec
setfattr -x user.shatag.sha256 {} \;
EXIT STATUS 0 Success >0 An error occurred or at least 1 file is backdated, corrupt, or invalid
COMPATIBILITY The original shatag utility only supports the sha256 hash algorithm.
Additionally, b2tag writes the user.shatag.ts field with full
nanosecond precision, while python uses a floating point number for the
whole mtime. As a result, the original shatag utility is only accurate
to within about 200 ns. Because of this, b2tag treats small timestamps
(fewer than 9 fractional digits) within 1 µs as equal. Timestamps with
full nanosecond precision are compared normally.
AUTHOR Written by Jakob Unterwurzacher, and Tim Schlueter.
COPYRIGHT Copyright © 2012 Jakob Unterwurzacher. Copyright © 2018 Tim Schlueter.
License: GPLv2+ with OpenSSL exception
GNU GPL version 2 or later
<https://www.gnu.org/licenses/licenses.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
As a special exception to the GPL, you may link the code with the
OpenSSL library (see the source files for more details).
SEE ALSO shatag(1), b2sum(1), sha256sum(1), getfattr(1), setfattr(1)
The original shatag utility, written in python by Maxime Augier:
https://bitbucket.org/maugier/shatag
AVAILABILITY Up-to-date sources can be found at: https://github.com/modelrockettier/b2tag
b2tag 0.2 September 2018 B2TAG(1)