NAME

       borg-check - Check repository consistency

SYNOPSIS

       borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]

DESCRIPTION

       The check command verifies the consistency of a repository and the corresponding archives.

       check  --repair is a potentially dangerous function and might lead to data loss (for kinds
       of corruption it is not capable of dealing with). BE VERY CAREFUL!

       Pursuant to the previous warning it is also highly recommended to test the reliability  of
       the  hardware  running  this software with stress testing software such as memory testers.
       Unreliable hardware can also lead to data loss especially when  this  command  is  run  in
       repair mode.

       First, the underlying repository data files are checked:

       • For all segments, the segment magic header is checked.

       • For all objects stored in the segments, all metadata (e.g. CRC and size) and all data is
         read. The read data is checked by size and CRC. Bit rot and other  types  of  accidental
         damage can be detected this way.

       • In  repair  mode, if an integrity error is detected in a segment, try to recover as many
         objects from the segment as possible.

       • In repair mode, make sure that the index is consistent  with  the  data  stored  in  the
         segments.

       • If  checking  a  remote  repo via ssh:, the repo check is executed on the server without
         causing significant network traffic.

       • The repository check can be skipped using the --archives-only option.

       • A repository check  can  be  time  consuming.  Partial  checks  are  possible  with  the
         --max-duration option.

       Second, the consistency and correctness of the archive metadata is verified:

       • Is  the  repo manifest present? If not, it is rebuilt from archive metadata chunks (this
         requires reading and decrypting of all metadata and data).

       • Check if archive metadata chunk is present; if not, remove archive from manifest.

       • For all files (items) in the archive, for all chunks referenced by these files, check if
         chunk is present. In repair mode, if a chunk is not present, replace it with a same-size
         replacement chunk of zeroes. If a previously lost chunk  reappears  (e.g.  via  a  later
         backup),  in  repair mode the all-zero replacement chunk will be replaced by the correct
         chunk. This requires reading of archive and file metadata, but not data.

       • In repair mode, when all the archives were checked, orphaned chunks are deleted from the
         repo.  One  cause of orphaned chunks are input file related errors (like read errors) in
         the archive creation process.

       • In verify-data mode, a complete cryptographic verification of the archive data integrity
         is performed. This conflicts with --repository-only as this mode only makes sense if the
         archive checks are enabled. The full details of this mode are documented below.

       • If checking a remote repo via ssh:, the archive check is executed on the client  machine
         because  it  requires  decryption,  and this is always done client-side as key access is
         needed.

       • The  archive  checks  can  be  time  consuming;  they   can   be   skipped   using   the
         --repository-only option.

       The  --max-duration  option  can  be  used  to  split a long-running repository check into
       multiple partial checks. After the given number of seconds the check is  interrupted.  The
       next  partial  check  will  continue  where  the  previous one stopped, until the complete
       repository has been checked. Example: Assuming a full check took 7 hours, then  running  a
       daily check with --max-duration=3600 (1 hour) resulted in one full check per week.

       Attention:  Partial checks can only do way less checking than a full check (only the CRC32
       checks on segment file entries are done), and cannot be combined with the --repair option.
       Partial  checks  may  therefore  be  useful only with very large repositories where a full
       check took too long. Doing a full repository  check  aborts  a  partial  check;  the  next
       partial check will restart from the beginning.

       The  --verify-data  option  will  perform  a  full  integrity  verification (as opposed to
       checking the CRC32 of the segment)  of  data,  which  means  reading  the  data  from  the
       repository,  decrypting  and decompressing it. This is a cryptographic verification, which
       will detect (accidental) corruption. For encrypted repositories it is tamper-resistant  as
       well, unless the attacker has access to the keys. It is also very slow.

OPTIONS

       See borg-common(1) for common options of Borg commands.

   arguments
       REPOSITORY_OR_ARCHIVE
              repository or archive to check consistency of

   optional arguments
       --repository-only
              only perform repository checks

       --archives-only
              only perform archives checks

       --verify-data
              perform   cryptographic   archive   data  integrity  verification  (conflicts  with
              --repository-only)

       --repair
              attempt to repair any inconsistencies found

       --save-space
              work slower, but using less space

       --max-duration SECONDS
              do only a partial repo check for max. SECONDS seconds (Default: unlimited)

   Archive filters
       -P PREFIX, --prefix PREFIX
              only consider archive names starting with this prefix.

       -a GLOB, --glob-archives GLOB
              only consider archive names matching the glob. sh:  rules  apply,  see  "borg  help
              patterns". --prefix and --glob-archives are mutually exclusive.

       --sort-by KEYS
              Comma-separated  list of sorting keys; valid keys are: timestamp, name, id; default
              is: timestamp

       --first N
              consider first N archives after other filters were applied

       --last N
              consider last N archives after other filters were applied

SEE ALSO

       borg-common(1)

AUTHOR

       The Borg Collective

                                            2022-02-19                              BORG-CHECK(1)