Commands‎ > ‎


Sets and displays configuration options.  These options are stored in the main database, with a history of options used for every backup.

$ hb config [-c backupdir] [-r version] [key] [value]


Display current configuration, for the next backup:
$ hb config -c backupdir

Display the configuration used for backup version 5:
$ hb config -c backupdir -r5

Set key arc-size-limit to 1gb (used for the next backup):
$ hb config -c backupdir arc-size-limit 1gb

Display key arc-size-limit:
$ hb config -c backupdir arc-size-limit

Display key arc-size-limit used for backup version 5:
$ hb config -c backupdir -r5 arc-size-limit

Config changes take effect on the next backup.  If you need config options to be sent to remotes immediately, use:
$ hb dest -c backupdir sync

Config Options (Keywords

admin-passphrase    an admin passphrase can restrict certain actions unless the passphrase is known.  This option is used
to protect the config data from changes, to protect dest.conf data stored in the database (see dest command), and with the enable-commands and disable-commands options.

arc-size-limit    specifies the maximum size of archive files.  The default is 100mb.  The minimum size is 10k, but that is only used for internal testing.  For huge, multi-TB backups with mostly large files that do not change often, a large archive size may be more efficient.

As files are removed with the retain command, it will create holes (empty space) in your archives.  If enough data is removed, archives are automatically packed to remove empty space
(see pack-percent-free, pack=free-bytes  options).  If all data from an archive is removed, the archive is deleted without needing a pack operation; this is why smaller archive files can be more efficient than larger files.  HashBackup may go slightly over the limit specified, so if you need a hard limit for some reason, specify 5-10MB less.

audit-commands    list of commands, separated by commas, that should be audited by recording details of each use.  To audit all commands, use the value all.  The hb audit command displays the audit log.  The audit log cannot be deleted or changed. 
To disable auditing, use the value '' (two single quotes).

backup-linux-attrs    when True, backup will save Linux file system attributes, also called flags in BSD Unix.    On Linux, file attributes are set with the chattr command and displayed with lsattr.  They are little used and poorly implemented on Linux, requiring an open file descriptor and an ioctl call.  This can cause permission problems, especially in shared hosting environments.  The default is False.

File attributes are not the same as extended attributes, also called xattrs.  Extended attributes are always backed up if present.  Xattrs are handled by the attr, setfattr, and setfattr commands on Linux, as well as the Linux ACL commands.

cache-size-limit  spec
ifies the maximum amount of space to use in the local backup directory to cache archive files.  By default, this is -1, meaning to keep local copies of all archive files.  Setting cache-size-limit to any other value will restrict the number of archives kept locally.  Remote destinations must be setup in dest.conf to use this config option.  The cache size limit is more of a desired goal than a hard limit.  The limit may often be exceeded by the size of 1 archive file, and may need to be greatly exceeded for restores to prevent downloading the same archive file more than once.  The mount command also ignores this limit because it is not possible to predict the size of the cache needed, and having a fixed size might require downloading the same file more than once.  A reasonable value for this limit is the average size of your incremental backups.  A reasonable minimum is the highest workers setting for any destination plus 1.  The default number of workers is 2, so the minimum would be 3.

If you can afford the disk space, keeping a copy of archives locally has many advantages: backups won't stall, restores will not have to wait for lengthy downloads, archive pack operations are faster (no download is required), and you have a redundant copy of your backup.  Total backup space is usually about half the size of the original data, even when multiple versions are maintained.

Examples of cache size limits:

  • -1 means copies of all archives are kept in the local backup directory.  This is the default setting.
  • 0 means no archives should be kept locally.  During backup, an archive is created first in the backup directory, then sent to all remotes, then deleted, then the backup continues.  This will be slow because backup waits until all remotes have received the archive before continuing, so there is no overlap between backup and network transmission.  This is only recommended when disk space is extremely limited, for example, on a tiny VPS (Virtual Private Server).
  • 1-1000 means to size the cache to hold this many full archives.  If the archive size is 100MB and the limit is set to 10, the effective cache size would be 1gb.  This is much better than using 0 as a limit because there will be overlap between network transmission and backing up.  Use workers + 1 as a minimum.
  • 10gb specifies the cache size directly.  Other suffixes can be used: mb, kb, etc.
copy-executable    when True, copy the hb program to remote destinations.  The default is False.  The hb program is always copied to the local backup directory as hb#b, where b is the build number.  The last 3 versions are kept in the local backup directory.

dbid           a read-only config option that is unique for each backup database

dbrev        a read-only config option describing the database revision level

dedup-mem    specifies the amount of RAM to be used for the dedup table, similar to the -D backup option.  The -D option overrides this config option.  See Dedup Info for more detailed information about sizing the dedup table.  The default is 0, meaning dedup is disabled.  A reasonable value is 1gb.  The dedup table does not immediately use all memory specified; it starts small and doubles in size when necessary, up to this limit.  The backup command shows how full the current dedup table is, and how full it is compared to the maximum table size.  When the dedup table is full and cannot be expanded, backups will continue to work correctly; dedup is still very effective even with a full table.

disable-commands    list of commands that should be disabled, separated by commas; all other commands are enabled.  If the admin-passphrase option is set, these commands will ask for the passphrase and run only if it is correctly entered.  If there is no admin-passphrase set, these commands refuse to run.  The upgrade and init commands cannot be disabled because when these commands execute there is no database to check whether they should be enabled or disabled.  For a backup-only config, commands to disable would be clear, config, dest, recover, rekey, rename, retain, and rm.
  To cancel this option, use the value '' (two single quotes).
SECURITY NOTE: Disabling commands without an admin passphrase is a poor configuration since commands can easily be re-enabled.

enable-commands    list of commands that should be enabled
, separated by commas; all other commands are disabled.  An example would be to enable only the backup command.  Then it would not be possible to list, restore, or remove files without the admin passphrase.  To cancel this option, use the value '' (two single quotes).
SECURITY NOTE: Disabling commands without an admin passphrase is a poor configuration since commands can easily be re-enabled.

when True, the get command will compress files on Mac OSX that were originally compressed during the backup.  The default is False because the OSX tool used to compress files is very slow: about 10x slower than a normal restore.

no-backup-ext    list of file extensions, with or without dots, separated by spaces or commas.  Files with these extensions will not be backed up.

no-backup-tag    list of filenames separated by spaces or commas.  Directories containing any of these files will not have their contents backed up, other than the tag file(s).  Typical values are .nobackup and CACHEDIR.TAG

no-compress-ext  list of file extensions of files that should not be compressed.  Most common extensions are already programmed into the backup program, but you can list less common extensions here.  Extensions may or may not have dots, and are separated by spaces or commas.

no-dedup-ext      list of file extensions of files with data that does not dedup well, for example, photos.  If exact copies are backed up, they will be still be deduped (if enabled).

pack-age-days        the minimum age of an archive before it is packed.  Some storage services charge penalties for early removal of files, for example, Amazon S3 Infrequent Access and Google Nearline.  This setting prevents packing archives until they have aged, avoiding the delete penalty charge.  All other conditions must be satisfied before an archive is packed. 
The default for pack-age-days is 30.  To disable this feature, set it to zero.  Higher numbers will increase the backup storage requirements but reduce the number of pack operations.

               the minimum free space in an archive before it is packed.  This setting prevents packing very small archives when data is removed, ie, once an archive gets down to 1MB (the default setting), it is not packed until it is empty, then is deleted.  All other conditions such as pack-percent-free must also be satisifed before the archive is packed. The default for pack-bytes-free is 1MB.  To disable this feature, set it to 4K (the minimum value).   Higher numbers will increase the backup storage requirements but reduce the number of pack operations.

pack-percent-free    when archive files have this percentage or more as free space, the archive is packed to recover disk space.  This is used by rm and retain after they have deleted backup data.  The default is 50.  If cache-size-limit is set, consider raising this percentage to avoid frequent packing.  Most storage services have very high download charges compared to their storage charge, often 8-10x higher.  If cache-size-limit is not set (the default), packing more often is okay because no download is required.    Higher numbers will increase the backup storage requirements but reduce the number of pack operations.

pack-remote-archives    if cache-size-limit is set, some archives may be local and some may only be remote.  If this option is False (the default), remote-only archives will not be downloaded and packed.  This may be important because retrieving an archive from a remote destination to pack it is often more expensive in bandwidth costs than leaving it on the remote and paying storage charges.  If this option is True, remote archives are downloaded, packed, and then uploaded to save storage costs on the remote.  The best setting for this is probably False, though it depends on your incoming and outgoing bandwidth fees, storage fees, and volatility of your backup data (how much data is removed by rm and retain).

remote-update    when set to normal, HB sends new data before deleting old data.  This preserves the integrity of remote backup areas.  However, if a remote disk becomes full, it may be necessary to delete the old data before sending new data.  To enable this behavior, set to unsafe
IMPORTANT: when set to unsafe, an interrupted HB command may leave the remote backup area temporarily inconsistent.  The next successful HB command should correct it.

simulated-backup    this keyword can be set to True before the first backup.  When set True, no arc files are created by the backup command.  This allows modeling backup options such as -B (blocks size),  -D (dedup table size), and -Z (compression level), even for very large backups, without using a lot of disk space.  Simulated backups also run faster because there is less I/O.  Incremental backups work correctly, and the stats command can be used to view statistics such as the backup space that would be used by a real backup.  The pack-remote-archives keyword controls whether the simulated arc files are packed when files are removed from the backup with rm or retain.

Differences for a simulated backup:
- must be set before the initial backup
- cannot be changed after the initial backup
- no arc files are created (not a real backup)
- no files are sent to remote destinations
- selftest is limited to -v2
- get & mount will fail with "No archive" errors
- rm, retain, and incremental backups work