b2tag.1

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