How to configure and use Brebis

You need two files in order to use Brebis.

Configuration of the backup checking session

The first one contains general information about the backup checking session. Here is an example with all the currently supported parameters:
[main]    
name=mybackup-checking-session
type=archive    
path=tests/expected_mode/foos.tar.gz
files_list=tests/expected_mode/files-list
delimiter=|
  • [main] is mandatory.
  • name is the name of your backup checking session. If you have several backup checking sessions, they MUST use a different name.
  • type is the type of your backup. Currently you only have archive (tar, tar.gz, tar.bz2, zip files) and tree for a tree of directories and files.
  • path is the path to the archive or the top directory of your files tree. Relative or absolute paths are accepted.
  • files_list is the path to the file containing the information about the archive, the tree or the files inside your backups. Relative or absolute paths are accepted.
  • delimiter (optional field) is the string to use in the list of files to mark the end of the key and the beginning of the value. Default is | (pipe).
  • sha512 (optional field) provides the sha512 hash sum of the list of files, in order to check if this file is the expected one.

Archive checking setup

Understanding the parameters of the list of files in order to write it by yourself

The second file you need is the list containing the information about the archive, the tree or the files inside your backups. Here is an example with the full list of the parameters available for now:

[archive]
size| <5m
mode| 755
uid| 5000
gid| 5001
sha1| e0f58dcc57caad2182f701eb63f0c81f347d3fe5

[files]
foos/foo|
foos/foo1| >105k type|f mode|755 uid|5022 gid|5023 unexpected md5|3718422a0bf93f7fc46cff6b5e660ff8
foos/foo2| target|../foo

The [archive] section hosts the parameter for the archive itself. This section is not mandatory if you do not need it.
  • size defines what the archive size should be. You can specify <,> or =. Default value is expressed in bytes, also available are (k)ilo, (m)ega, (g)iga, (p)eta,(e)xa, (z)etta and (y)ottabyte.
  • mode is for the expected mode of the archive.
  • uid is for the expected uid of the archive.
  • gid is for the expected gid of the archive.
  • sha1 is for the expected md5 hash sum of the archive. Also available is sha1, sha224, sha256, sha384, sha512.

The [files] section stands for the files inside the archive or the tree of directories and files. This section is not mandatory if you do not need it.

  • foos/foo| means this file has to exist in the backup, whatever it is.
  • foos/foo1| >105k defines that the file size of foos/foo1 in the archive should be strictly bigger than 105 kilobytes. You can specify <,> or =. Default value is expressed in bytes, also available are (k)ilo, (m)ega, (g)iga, (p)eta,(e)xa, (z)etta and (y)ottabyte.
  • foos/foo1| type|f means the file foos/foo1 is expected to be of type f. Several types are allowed : f for files, d for directory, s for symbolic link, k for socket, b for block, c for character.
  • foos/foo1| mode|755 means the file foos/foo1 is expected to have the mode 755 (meaning read, write and execute for the owner, read and execute for the group owner, read and execute for the others). All values respecting this octal representation (including values with setuid bit on four digits) is allowed.
  • foos/foo1| uid|5022 means the file foos/foo1 is expected to have a uid of 5022.
  • foos/foo1| gid|5023 means the file foos/foo1 is expected to have a gid of 5023.
  • foo/bar| unexpected means that foo/bar is unexpected in this archive of tree of directories and files and that an alert should be launched about it.
  • foos/foo1| md5|hashsum means the file foos/foo1 is expected to have a md5 hash sum of "hashsum". Also available is sha1, sha224, sha256, sha384, sha512.
  • foos/foo2| target|../foo means that the link (hard link or symbolic link) foos/foo2 targets the file located at ../foo. If not, the program will trigger a warning.

Generate a list of files within a backup

Starting from 0.4, Brebis is able to generate a list of files within a backup. You only have to reuse this file later, including it in your configuration file.

Use the following command to generate the list of files:

$ brebis -g mybackup.tar.gz
$ ls
mybackup.tar.gz mybackup.list

Starting with the version 0.7, you can use the -G option in order to generate both the configuration file AND the list of files inside your archive or your tree of files:

Use the following command to generate both the configuration file AND the list of files:

$ brebis -G logs-05092012.tar.gz
$ ls
logs-05092012.tar.gz logs-05092012.conf logs-05092012.list

Unsupported parameters for a given kind of archive

Given the very nature of the different kind of archive formats, some parameters are not supported for a given archive type (e.g for a bzip2 file, original rights and mode of the file inside the archive are not saved). An explicit warning will appear in the brebis log file if you are using an unsupported feature for a given type of archive.

Launching Brebis

You launch Brebis from the command line:

$ brebis -c myconfs/

The parameter -c or --configpath specifies a path to a directory where your Brebis configurations are stored. If any alert is triggered, it will appear in the your current working directory in a file named a.out. Relative or absolute paths are accepted.

You can also specify your own output file:

$ brebis -c myconfs/ -l output/brebis.log

The option -l or --log specifies your own output file.