===============
 tlsh_unittest
===============

---------------------------------------
compute TLSH digest values and distance
---------------------------------------

:Author: Jérémy Bobbio <lunar@debian.org>
:Copyright: Apache-2.0
:Manual section: 1
:Manual group: Debian

SYNOPSIS
========

 tlsh_unittest [-c <file|digest>]         -f <file>     [-T <threshold_value>] [-xlen] [-details]

 tlsh_unittest  -c <file|digest>          -d <digest>   [-T <threshold_value>] [-xlen] [-details]

 tlsh_unittest [-c <file|digest> | -xref] -r <dir>      [-T <threshold_value>] [-xlen] [-details]

 tlsh_unittest [-c <file|digest> | -xref] -l <listfile> [-T <threshold_value>] [-xlen] [-details]

 tlsh_unittest -version

DESCRIPTION
===========

tlsh_unittest can be used to compute TLSH digest values or the distance between
digest values in the following ways:

  1) To compute the TLSH digest value of a single file (`-f file`), or a
     directory of files (`-r dir`). This output can be used to create the
     listfile required by the `-l` option described below.
  2) To compute the distance between a comparison file or TLSH digest
     (`-c <file|digest>`) and the specified file (`-f file`), TLSH digest (`-d digest`),
     directory of files (`-r dir`), or list (`-l listfile`).
  3) To compute the distance between each element in a set of files (`-r dir`) or
     files/digests in a list (`-l listfile`) with every other element in that
     set, using the `-xref` flag

OPTIONS
=======

-c <file|digest>
    Specifies a filename or digest whose TLSH value will be
    compared to a specified TLSH digest (`-d`) OR the TLSH value
    of a sepcified file (`-f`) OR the TLSH values of files in a
    specified directory (`-r`) OR the TLSH values in a specified
    listfile (`-l`)

-x\ref
    Results in the calculation of distance between each
    element in the set. Used only when a set of files (`-r dir`) or TLSH values
    (`-l listfile`) is specified.

-f file
    Specifies a file whose TLSH values are to be computed, or
    used for comparison (`-c <file|digest>`)

-d digest
    Specifies a TLSH digest value that is to be compared to the specified
    comparison file or digest (`-c <file|digset>`)

-r dir
    Specifies a recursive directory search for files whose TLSH values are to
    be computed, or used for comparison (`-c <file|digset>` or `-xref`)

-l listfile
    Used for comparison purposes only (`-c <file|digset>` or `-xref`). Each line in
    listfile can contain either:

      - a TLSH digest value (comparison output will display TLSH digests)
      - a tab separated TLSH digest value and its corresponding filename
        (comparison output will display filenames)

    The tab separated listfile can be generated by running
    `tlsh_unittest` with either the `-f` or `-r` flag

-x\len
    Determines if the lengths of the compared files is to be included in
    determining the distance.

-d\etails
    Results in extra detailed output.

-T threshold_value
    Used only during comparisons (`-c <file|digset>` or `-xref`). Specifies the
    maximun distance that a comparison must generate before it is reported
    (defaults to 9999).

EXAMPLE
=======

Calculate the distance between two files:

    tlsh_unittest -c <file 1> -f <file 2>

Calculate the distance between two TLSH digest values:

    tlsh_unittest -c <TLSH digest 1> -d <TLSH digest 2>

Calculate the TLSH digest values for every file in a directory. This creates
input for the -l option:

    tlsh_unittest -r <dir>

Get the distance between a reference TLSH digest value, and a list of TLSH
digest values in a file:

    tlsh_unittest -c <TLSH digest> -l <file>

Compare the TLSH value for every file in a directory, to every other file in
that directory:

    tlsh_unittest -xref -r <dir>

NOTES
=====

This man page has been adapted from `tlsh_unittest` usage output for the Debian
project.