README

B2TAG(1)                         User Commands                        B2TAG(1)

NAME
       b2tag - detect data corruption with checksums in extended attributes.

SYNOPSIS
       b2tag [OPTION]... <FILE>...

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)