API Documentation¶
-
class
borg.archive.Archive(repository, key, manifest, name, cache=None, create=False, checkpoint_interval=300, numeric_owner=False, noatime=False, noctime=False, progress=False, chunker_params=(19, 23, 21, 4095), start=None, start_monotonic=None, end=None)[source]¶ -
-
exception
Archive.IncompatibleFilesystemEncodingError(*args)[source]¶ Failed to encode filename “{}” into file system encoding “{}”. Consider configuring the LANG environment variable.
-
Archive.duration¶
-
Archive.fpr¶
-
Archive.restore_attrs(path, item, symlink=False, fd=None)[source]¶ Restore filesystem attributes on path (fd) from item.
Does not access the repository.
-
Archive.ts¶ Timestamp of archive creation (start) in UTC
-
Archive.ts_end¶ Timestamp of archive creation (end) in UTC
-
exception
-
class
borg.archive.ArchiveChecker[source]¶
-
exception
borg.archive.BackupOSError(os_error)[source]¶ Wrapper for OSError raised while accessing backup files.
Borg does different kinds of IO, and IO failures have different consequences. This wrapper represents failures of input file or extraction IO. These are non-critical and are only reported (exit code = 1, warning).
Any unwrapped IO error is critical and aborts execution (for example repository IO failure).
-
class
borg.archive.ChunkBuffer(key, chunker_params=(15, 19, 17, 4095))[source]¶ -
BUFFER_SIZE= 1048576¶
-
-
class
borg.archive.DownloadPipeline(repository, key)[source]¶ -
-
unpack_many(ids, filter=None, preload=False)[source]¶ Return iterator of items.
ids is a chunk ID list of an item stream. filter is a callable to decide whether an item will be yielded. preload preloads the data chunks of every yielded item.
Warning: if preload is True then all data chunks of every yielded item have to be retrieved, otherwise preloaded chunks will accumulate in RemoteRepository and create a memory leak.
-
-
class
borg.archive.RobustUnpacker(validator, item_keys)[source]¶ A restartable/robust version of the streaming msgpack unpacker
-
borg.archive.valid_msgpacked_dict(d, keys_serialized)[source]¶ check if the data <d> looks like a msgpacked dict
-
class
borg.archiver.Archiver(lock_wait=None)[source]¶ -
-
do_break_lock(args, repository)[source]¶ Break the repository lock (e.g. in case it was left by a dead borg.
-
do_change_passphrase(args, repository, manifest, key)[source]¶ Change repository key file passphrase
-
do_debug_dump_archive_items(args, repository, manifest, key)[source]¶ dump (decrypted, decompressed) archive items metadata (not: data)
-
do_debug_dump_repo_objs(args, repository, manifest, key)[source]¶ dump (decrypted, decompressed) repo objects
-
do_debug_get_obj(args, repository)[source]¶ get object contents from the repository and write it into file
-
do_debug_refcount_obj(args, repository, manifest, key, cache)[source]¶ display refcounts for the objects with the given IDs
-
do_info(args, repository, manifest, key, archive, cache)[source]¶ Show archive details such as disk space used
-
do_mount(args, repository, manifest, key)[source]¶ Mount archive or an entire repository as a FUSE filesystem
-
do_prune(args, repository, manifest, key)[source]¶ Prune repository archives according to specified rules
-
do_upgrade(args, repository, manifest=None, key=None)[source]¶ upgrade a repository from a previous version
-
get_args(argv, cmd)[source]¶ usually, just returns argv, except if we deal with a ssh forced command for borg serve.
-
helptext= OrderedDict([('patterns', "\nExclusion patterns support four separate styles, fnmatch, shell, regular\nexpressions and path prefixes. By default, fnmatch is used. If followed\nby a colon (':') the first two characters of a pattern are used as a\nstyle selector. Explicit style selection is necessary when a\nnon-default style is desired or when the desired pattern starts with\ntwo alphanumeric characters followed by a colon (i.e. `aa:something/*`).\n\n`Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`\n\n This is the default style. These patterns use a variant of shell\n pattern syntax, with '*' matching any number of characters, '?'\n matching any single character, '[...]' matching any single\n character specified, including ranges, and '[!...]' matching any\n character not specified. For the purpose of these patterns, the\n path separator ('\\' for Windows and '/' on other systems) is not\n treated specially. Wrap meta-characters in brackets for a literal\n match (i.e. `[?]` to match the literal character `?`). For a path\n to match a pattern, it must completely match from start to end, or\n must match from the start to just before a path separator. Except\n for the root path, paths will never end in the path separator when\n matching is attempted. Thus, if a given pattern ends in a path\n separator, a '*' is appended before matching is attempted.\n\nShell-style patterns, selector `sh:`\n\n Like fnmatch patterns these are similar to shell patterns. The difference\n is that the pattern may include `**/` for matching zero or more directory\n levels, `*` for matching zero or more arbitrary characters with the\n exception of any path separator.\n\nRegular expressions, selector `re:`\n\n Regular expressions similar to those found in Perl are supported. Unlike\n shell patterns regular expressions are not required to match the complete\n path and any substring match is sufficient. It is strongly recommended to\n anchor patterns to the start ('^'), to the end ('$') or both. Path\n separators ('\\' for Windows and '/' on other systems) in paths are\n always normalized to a forward slash ('/') before applying a pattern. The\n regular expression syntax is described in the `Python documentation for\n the re module <https://docs.python.org/3/library/re.html>`_.\n\nPrefix path, selector `pp:`\n\n This pattern style is useful to match whole sub-directories. The pattern\n `pp:/data/bar` matches `/data/bar` and everything therein.\n\nExclusions can be passed via the command line option `--exclude`. When used\nfrom within a shell the patterns should be quoted to protect them from\nexpansion.\n\nThe `--exclude-from` option permits loading exclusion patterns from a text\nfile with one pattern per line. Lines empty or starting with the number sign\n('#') after removing whitespace on both ends are ignored. The optional style\nselector prefix is also supported for patterns loaded from a file. Due to\nwhitespace removal paths with whitespace at the beginning or end can only be\nexcluded using regular expressions.\n\nExamples::\n\n # Exclude '/home/user/file.o' but not '/home/user/file.odt':\n $ borg create -e '*.o' backup /\n\n # Exclude '/home/user/junk' and '/home/user/subdir/junk' but\n # not '/home/user/importantjunk' or '/etc/junk':\n $ borg create -e '/home/*/junk' backup /\n\n # Exclude the contents of '/home/user/cache' but not the directory itself:\n $ borg create -e /home/user/cache/ backup /\n\n # The file '/home/user/cache/important' is *not* backed up:\n $ borg create -e /home/user/cache/ backup / /home/user/cache/important\n\n # The contents of directories in '/home' are not backed up when their name\n # ends in '.tmp'\n $ borg create --exclude 're:^/home/[^/]+\\.tmp/' backup /\n\n # Load exclusions from file\n $ cat >exclude.txt <<EOF\n # Comment line\n /home/*/junk\n *.tmp\n fm:aa:something/*\n re:^/home/[^/]\\.tmp/\n sh:/home/*/.thumbnails\n EOF\n $ borg create --exclude-from exclude.txt backup /\n\n"), ('placeholders', "\n Repository (or Archive) URLs, --prefix and --remote-path values support these\n placeholders:\n\n {hostname}\n\n The (short) hostname of the machine.\n\n {fqdn}\n\n The full name of the machine.\n\n {now}\n\n The current local date and time.\n\n {utcnow}\n\n The current UTC date and time.\n\n {user}\n\n The user name (or UID, if no name is available) of the user running borg.\n\n {pid}\n\n The current process ID.\n\n {borgversion}\n\n The version of borg, e.g.: 1.0.8rc1\n\n {borgmajor}\n\n The version of borg, only the major version, e.g.: 1\n\n {borgminor}\n\n The version of borg, only major and minor version, e.g.: 1.0\n\n {borgpatch}\n\n The version of borg, only major, minor and patch version, e.g.: 1.0.8\n\nExamples::\n\n borg create /path/to/repo::{hostname}-{user}-{utcnow} ...\n borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...\n borg prune --prefix '{hostname}-' ...\n\n")])¶
-
-
borg.archiver.argument(args, str_or_bool)[source]¶ If bool is passed, return it. If str is passed, retrieve named attribute from args.
-
borg.archiver.sig_info_handler(sig_no, stack)[source]¶ search the stack for infos about the currently processed file and print them
-
borg.archiver.with_repository(fake=False, invert_fake=False, create=False, lock=True, exclusive=False, manifest=True, cache=False)[source]¶ Method decorator for subcommand-handling methods: do_XYZ(self, args, repository, …)
If a parameter (where allowed) is a str the attribute named of args is used instead. :param fake: (str or bool) use None instead of repository, don’t do anything else :param create: create repository :param lock: lock repository :param exclusive: (str or bool) lock repository exclusively (for writing) :param manifest: load manifest and key, pass them as keyword arguments :param cache: open cache, pass it as keyword argument (implies manifest)
-
class
borg.cache.Cache(repository, key, manifest, path=None, sync=True, do_files=False, warn_if_unencrypted=True, lock_wait=None)[source]¶ Client Side cache
-
exception
Cache.EncryptionMethodMismatch(*args)[source]¶ Repository encryption method changed since last access, refusing to continue
-
exception
Cache.RepositoryIDNotUnique(*args)[source]¶ Cache is newer than repository - do you have multiple, independently updated repos with same ID?
-
exception
Cache.RepositoryReplay(*args)[source]¶ Cache is newer than repository - this is either an attack or unsafe (multiple repos with same ID)
-
Cache.sync()[source]¶ Re-synchronize chunks cache with repository.
Maintains a directory with known backup archive indexes, so it only needs to fetch infos from repo and build a chunk index once per backup archive. If out of sync, missing archive indexes get added, outdated indexes get removed and a new master chunks index is built by merging all archive indexes.
-
exception
-
class
borg.chunker.Chunker¶ -
chunkify()¶ Cut a file into chunks.
Parameters: - fd – Python file object
- fh – OS-level file handle (if available), defaults to -1 which means not to use OS-level fd.
-
-
borg.chunker.buzhash()¶
-
borg.chunker.buzhash_update()¶
-
borg.compress.get_compressor()¶
-
class
borg.compress.Compressor¶ compresses using a compressor with given name and parameters decompresses everything we can handle (autodetect)
-
compress()¶
-
decompress()¶
-
-
class
borg.compress.CompressorBase¶ base class for all (de)compression classes, also handles compression format auto detection and adding/stripping the ID header (which enable auto detection).
-
ID= b'\xff\xff'¶
-
compress()¶
-
decompress()¶
-
detect()¶
-
name= 'baseclass'¶
-
A thin OpenSSL wrapper
This could be replaced by PyCrypto maybe?
-
class
borg.crypto.AES¶ A thin wrapper around the OpenSSL EVP cipher API
-
decrypt()¶
-
encrypt()¶
-
iv¶
-
reset()¶
-
-
borg.crypto.bytes16_to_int()¶
-
borg.crypto.bytes_to_int¶
-
borg.crypto.bytes_to_long¶
-
borg.crypto.hkdf_hmac_sha512()¶ Compute HKDF-HMAC-SHA512 with input key material ikm, salt and info to produce output_length bytes.
This is the “HMAC-based Extract-and-Expand Key Derivation Function (HKDF)” (RFC 5869) instantiated with HMAC-SHA512.
output_length must not be greater than 64 * 255 bytes.
-
borg.crypto.increment_iv()¶ Increment the IV by the given amount (default 1).
Parameters: - iv – input IV, 16 bytes (128 bit)
- amount – increment value
Returns: input_IV + amount, 16 bytes (128 bit)
-
borg.crypto.int_to_bytes16()¶
-
borg.crypto.long_to_bytes¶
-
borg.crypto.num_aes_blocks()¶ Return the number of AES blocks required to encrypt/decrypt length bytes of data. Note: this is only correct for modes without padding, like AES-CTR.
-
class
borg.fuse.FuseOperations(key, repository, manifest, archive, cached_repo)[source]¶ Export archive as a fuse filesystem
-
allow_damaged_files= False¶
-
-
class
borg.hashindex.ChunkIndex¶ Mapping of 32 byte keys to (refcount, size, csize), which are all 32-bit unsigned.
The reference count cannot overflow. If an overflow would occur, the refcount is fixed to MAX_VALUE and will neither increase nor decrease by incref(), decref() or add().
Prior signed 32-bit overflow is handled correctly for most cases: All values from UINT32_MAX (2**32-1, inclusive) to MAX_VALUE (exclusive) are reserved and either cause silent data loss (-1, -2) or will raise an AssertionError when accessed. Other values are handled correctly. Note that previously the refcount could also reach 0 by increasing it.
Assigning refcounts in this reserved range is an invalid operation and raises AssertionError.
-
add()¶
-
decref()¶ Decrease refcount for ‘key’, return (refcount, size, csize)
-
incref()¶ Increase refcount for ‘key’, return (refcount, size, csize)
-
iteritems()¶
-
merge()¶
-
summarize()¶
-
value_size= 12¶
-
-
class
borg.hashindex.ChunkKeyIterator¶
-
class
borg.hashindex.NSKeyIterator¶
-
class
borg.helpers.Buffer(allocator, size=4096, limit=None)[source]¶ provide a thread-local buffer
-
exception
borg.helpers.ErrorWithTraceback(*args)[source]¶ like Error, but show a traceback also
-
traceback= True¶
-
-
exception
borg.helpers.ExtensionModuleError(*args)[source]¶ The Borg binary extension modules do not seem to be properly installed
-
class
borg.helpers.FnmatchPattern(pattern)[source]¶ Shell glob patterns to exclude. A trailing slash means to exclude the contents of a directory, but not the directory itself.
-
PREFIX= 'fm'¶
-
-
class
borg.helpers.Location(text='')[source]¶ Object representing a repository / archive location
-
abs_path_re= '\n (?P<path>(/([^:]|(:(?!:)))+)) # start with /, then any chars, but no "::"\n '¶
-
archive= None¶
-
env_re= re.compile(' # the repo part is fetched from BORG_REPO\n (?:::$) # just "::" is ok (when a pos. arg is required, no archive)\n , re.VERBOSE)¶
-
file_re= re.compile('\n (?P<proto>file):// # file://\n \n (?!(:|//|ssh://)) # not starting with ":" or // or ssh://\n (?P<pat, re.VERBOSE)¶
-
host= None¶
-
optional_archive_re= '\n (?:\n :: # "::" as separator\n (?P<archive>[^/]+) # archive name must not contain "/"\n )?$'¶
-
optional_user_re= '\n (?:(?P<user>[^@:/]+)@)?\n '¶
-
path= None¶
-
path_re= '\n (?!(:|//|ssh://)) # not starting with ":" or // or ssh://\n (?P<path>([^:]|(:(?!:)))+) # any chars, but no "::"\n '¶
-
port= None¶
-
proto= None¶
-
scp_re= re.compile('\n (\n \n (?:(?P<user>[^@:/]+)@)?\n # user@ (optional)\n (?P<host>[^:/]+): # host: (don\'t match / in host to , re.VERBOSE)¶
-
ssh_re= re.compile('\n (?P<proto>ssh):// # ssh://\n \n (?:(?P<user>[^@:/]+)@)?\n # user@ (optional)\n (?P<host>[^:/]+)(?::(?P<port, re.VERBOSE)¶
-
user= None¶
-
-
class
borg.helpers.Manifest(key, repository, item_keys=None)[source]¶ -
MANIFEST_ID= b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'¶
-
-
class
borg.helpers.PathPrefixPattern(pattern)[source]¶ Literal files or directories listed on the command line for some operations (e.g. extract, but not create). If a directory is specified, all paths that start with that path match as well. A trailing slash makes no difference.
-
PREFIX= 'pp'¶
-
-
class
borg.helpers.PatternBase(pattern)[source]¶ Shared logic for inclusion/exclusion patterns.
-
PREFIX= NotImplemented¶
-
-
class
borg.helpers.PatternMatcher(fallback=None)[source]¶
-
class
borg.helpers.ProgressIndicatorPercent(total, step=5, start=0, same_line=False, msg='%3.0f%%', file=None)[source]¶
-
class
borg.helpers.ShellPattern(pattern)[source]¶ Shell glob patterns to exclude. A trailing slash means to exclude the contents of a directory, but not the directory itself.
-
PREFIX= 'sh'¶
-
-
class
borg.helpers.Statistics[source]¶ -
csize_fmt¶
-
osize_fmt¶
-
summary= ' Original size Compressed size Deduplicated size\n{label:15} {stats.osize_fmt:>20s} {stats.csize_fmt:>20s} {stats.usize_fmt:>20s}'¶
-
usize_fmt¶
-
-
borg.helpers.dir_is_cachedir(path)[source]¶ Determines whether the specified path is a cache directory (and therefore should potentially be excluded from the backup) according to the CACHEDIR.TAG protocol (http://www.brynosaurus.com/cachedir/spec.html).
-
borg.helpers.dir_is_tagged(path, exclude_caches, exclude_if_present)[source]¶ Determines whether the specified path is excluded by being a cache directory or containing user-specified tag files. Returns a list of the paths of the tag files (either CACHEDIR.TAG or the matching user-specified files).
-
borg.helpers.format_file_size(v, precision=2)[source]¶ Format file size into a human friendly format
-
borg.helpers.get_security_dir(repository_id=None)[source]¶ Determine where to store local security information.
-
borg.helpers.int_to_bigint(value)[source]¶ Convert integers larger than 64 bits to bytearray
Smaller integers are left alone
-
borg.helpers.load_excludes(fh)[source]¶ Load and parse exclude patterns from file object. Lines empty or starting with ‘#’ after stripping whitespace on both line ends are ignored.
-
borg.helpers.log_multi(*msgs, *, level=20)[source]¶ log multiple lines of text, each line by a separate logging call for cosmetic reasons
each positional argument may be a single or multiple lines (separated by newlines) of text.
-
borg.helpers.normalized(func)[source]¶ Decorator for the Pattern match methods, returning a wrapper that normalizes OSX paths to match the normalized pattern on OSX, and returning the original method on other platforms
-
borg.helpers.parse_pattern(pattern, fallback=<class 'borg.helpers.FnmatchPattern'>)[source]¶ Read pattern from string and return an instance of the appropriate implementation class.
-
borg.helpers.posix_acl_use_stored_uid_gid(acl)[source]¶ Replace the user/group field with the stored uid/gid
-
borg.helpers.remove_surrogates(s, errors='replace')[source]¶ Replace surrogates generated by fsdecode with ‘?’
-
borg.helpers.safe_decode(s, coding='utf-8', errors='surrogateescape')[source]¶ decode bytes to str, with round-tripping “invalid” bytes
-
borg.helpers.safe_encode(s, coding='utf-8', errors='surrogateescape')[source]¶ encode str to bytes, with round-tripping “invalid” bytes
-
borg.helpers.signal_handler(sig, handler)[source]¶ when entering context, set up signal handler <handler> for signal <sig>. when leaving context, restore original signal handler.
<sig> can bei either a str when giving a signal.SIGXXX attribute name (it won’t crash if the attribute name does not exist as some names are platform specific) or a int, when giving a signal number.
<handler> is any handler value as accepted by the signal.signal(sig, handler).
-
borg.helpers.update_excludes(args)[source]¶ Merge exclude patterns from files with those on command line.
-
borg.helpers.yes(msg=None, false_msg=None, true_msg=None, default_msg=None, retry_msg=None, invalid_msg=None, env_msg='{} (from {})', falsish=('No', 'NO', 'no', 'N', 'n', '0'), truish=('Yes', 'YES', 'yes', 'Y', 'y', '1'), defaultish=('Default', 'DEFAULT', 'default', 'D', 'd', ''), default=False, retry=True, env_var_override=None, ofile=None, input=<built-in function input>)[source]¶ - Output <msg> (usually a question) and let user input an answer.
Qualifies the answer according to falsish, truish and defaultish as True, False or <default>. If it didn’t qualify and retry is False (no retries wanted), return the default [which defaults to False]. If retry is True let user retry answering until answer is qualified.
If env_var_override is given and this var is present in the environment, do not ask the user, but just use the env var contents as answer as if it was typed in. Otherwise read input from stdin and proceed as normal. If EOF is received instead an input or an invalid input without retry possibility, return default.
param msg: introducing message to output on ofile, no - is added [None]
param retry_msg: retry message to output on ofile, no - is added [None]
param false_msg: message to output before returning False [None] param true_msg: message to output before returning True [None] param default_msg: message to output before returning a <default> [None] param invalid_msg: message to output after a invalid answer was given [None] param env_msg: message to output when using input from env_var_override [‘{} (from {})’], needs to have 2 placeholders for answer and env var name param falsish: sequence of answers qualifying as False param truish: sequence of answers qualifying as True param defaultish: sequence of answers qualifying as <default> param default: default return value (defaultish answer was given or no-answer condition) [False] param retry: if True and input is incorrect, retry. Otherwise return default. [True] param env_var_override: environment variable name [None] param ofile: output stream [sys.stderr] param input: input function [input from builtins] return: boolean answer value, True or False
-
class
borg.key.AESKeyBase(repository)[source]¶ Common base class shared by KeyfileKey and PassphraseKey
Chunks are encrypted using 256bit AES in Counter Mode (CTR)
Payload layout: TYPE(1) + HMAC(32) + NONCE(8) + CIPHERTEXT
To reduce payload size only 8 bytes of the 16 bytes nonce is saved in the payload, the first 8 bytes are always zeros. This does not affect security but limits the maximum repository capacity to only 295 exabytes!
-
PAYLOAD_OVERHEAD= 41¶
-
-
exception
borg.key.PassphraseWrong(*args)[source]¶ passphrase supplied in BORG_PASSPHRASE is incorrect
-
exception
borg.key.RepoKeyNotFoundError(*args)[source]¶ No key entry found in the config of repository {}.
-
exception
borg.key.TAMRequiredError(*args)[source]¶ Manifest is unauthenticated, but it is required for this repository.
This either means that you are under attack, or that you modified this repository with a Borg version older than 1.0.9 after TAM authentication was enabled.
In the latter case, use “borg upgrade –tam –force ‘{}’” to re-authenticate the manifest.
-
traceback= False¶
-
-
exception
borg.key.TAMUnsupportedSuiteError(*args)[source]¶ Could not verify manifest: Unsupported suite {!r}; a newer version is needed.
-
traceback= False¶
-
-
exception
borg.key.UnsupportedManifestError(*args)[source]¶ Unsupported manifest envelope. A newer version is required to access this repository.
-
exception
borg.key.UnsupportedPayloadError(*args)[source]¶ Unsupported payload type {}. A newer version is required to access this repository.
-
exception
borg.keymanager.NotABorgKeyFile(*args)[source]¶ This file is not a borg key backup, aborting.
-
exception
borg.keymanager.RepoIdMismatch(*args)[source]¶ This key backup seems to be for a different backup repository, aborting.
-
exception
borg.keymanager.UnencryptedRepo(*args)[source]¶ Keymanagement not available for unencrypted repositories.
-
class
borg.locking.ExclusiveLock(path, timeout=None, sleep=None, id=None)[source]¶ An exclusive Lock based on mkdir fs operation being atomic.
If possible, try to use the contextmanager here like:
with ExclusiveLock(...) as lock: ...
This makes sure the lock is released again if the block is left, no matter how (e.g. if an exception occurred).
-
class
borg.locking.Lock(path, exclusive=False, sleep=None, timeout=None, id=None)[source]¶ A Lock for a resource that can be accessed in a shared or exclusive way. Typically, write access to a resource needs an exclusive lock (1 writer, noone is allowed reading) and read access to a resource needs a shared lock (multiple readers are allowed).
If possible, try to use the contextmanager here like:
with Lock(...) as lock: ...
This makes sure the lock is released again if the block is left, no matter how (e.g. if an exception occurred).
-
class
borg.locking.LockRoster(path, id=None)[source]¶ A Lock Roster to track shared/exclusive lockers.
Note: you usually should call the methods with an exclusive lock held, to avoid conflicting access by multiple threads/processes/machines.
-
exception
borg.locking.NotMyLock(*args)[source]¶ Failed to release the lock {} (was/is locked, but not by me).
-
class
borg.locking.TimeoutTimer(timeout=None, sleep=None)[source]¶ A timer for timeout checks (can also deal with no timeout, give timeout=None [default]). It can also compute and optionally execute a reasonable sleep time (e.g. to avoid polling too often or to support thread/process rescheduling).
logging facilities
The way to use this is as follows:
each module declares its own logger, using:
from .logger import create_logger logger = create_logger()
then each module uses logger.info/warning/debug/etc according to the level it believes is appropriate:
logger.debug(‘debugging info for developers or power users’) logger.info(‘normal, informational output’) logger.warning(‘warn about a non-fatal error or sth else’) logger.error(‘a fatal error’)
... and so on. see the logging documentation for more information
console interaction happens on stderr, that includes interactive reporting functions like help, info and list
...except
input()is special, because we can’t control the stream it is using, unfortunately. we assume that it won’t clutter stdout, because interaction would be broken then anywayswhat is output on INFO level is additionally controlled by commandline flags
-
borg.logger.create_logger(name=None)[source]¶ lazily create a Logger object with the proper path, which is returned by find_parent_module() by default, or is provided via the commandline
this is really a shortcut for:
logger = logging.getLogger(__name__)we use it to avoid errors and provide a more standard API.
We must create the logger lazily, because this is usually called from module level (and thus executed at import time - BEFORE setup_logging() was called). By doing it lazily we can do the setup first, we just have to be careful not to call any logger methods before the setup_logging() call. If you try, you’ll get an exception.
-
borg.logger.find_parent_module()[source]¶ find the name of a the first module calling this module
if we cannot find it, we return the current module’s name (__name__) instead.
-
borg.logger.setup_logging(stream=None, conf_fname=None, env_var='BORG_LOGGING_CONF', level='info', is_serve=False)[source]¶ setup logging module according to the arguments provided
if conf_fname is given (or the config file name can be determined via the env_var, if given): load this logging configuration.
otherwise, set up a stream handler logger on stderr (by default, if no stream is provided).
if is_serve == True, we configure a special log format as expected by the borg client log message interceptor.
-
borg.platform_linux.acl_get()¶ Saves ACL Entries
If numeric_owner is True the user/group field is not preserved only uid/gid
-
borg.platform_linux.acl_set()¶ Restore ACL Entries
If numeric_owner is True the stored uid/gid is used instead of the user/group names
-
borg.platform_linux.acl_use_local_uid_gid()¶ Replace the user/group field with the local uid/gid if possible
-
borg.platform_linux.umount()¶
-
class
borg.remote.RemoteRepository(location, create=False, exclusive=False, lock_wait=None, lock=True, append_only=False, args=None)[source]¶ -
-
RemoteRepository.extra_test_args= []¶
-
-
class
borg.remote.RepositoryCache(repository)[source]¶ A caching Repository wrapper
Caches Repository GET operations using a local temporary Repository.
-
THRESHOLD= 65536¶
-
-
class
borg.remote.RepositoryNoCache(repository)[source]¶ A not caching Repository wrapper, passes through to repository.
Just to have same API (including the context manager) as RepositoryCache.
-
class
borg.remote.RepositoryServer(restrict_to_paths, append_only)[source]¶ -
-
rpc_methods= ('__len__', 'check', 'commit', 'delete', 'destroy', 'get', 'list', 'negotiate', 'open', 'put', 'rollback', 'save_key', 'load_key', 'break_lock')¶
-
-
exception
borg.remote.UnexpectedRPCDataFormatFromClient(*args)[source]¶ Borg {}: Got unexpected RPC data format from client.
-
exception
borg.remote.UnexpectedRPCDataFormatFromServer(data)[source]¶ Got unexpected RPC data format from server: {}
-
class
borg.repository.LoggedIO(path, limit, segments_per_dir, capacity=90)[source]¶ -
COMMIT= b'@\xf4<%\t\x00\x00\x00\x02'¶
-
LoggedIO.crc_fmt= <Struct object>¶
-
LoggedIO.header_fmt= <Struct object>¶
-
LoggedIO.header_no_crc_fmt= <Struct object>¶
-
LoggedIO.put_header_fmt= <Struct object>¶
-
-
class
borg.repository.Repository(path, create=False, exclusive=False, lock_wait=None, lock=True, append_only=False)[source]¶ Filesystem based transactional key value store
On disk layout: dir/README dir/config dir/data/<X / SEGMENTS_PER_DIR>/<X> dir/index.X dir/hints.X
-
exception
Repository.CheckNeeded(*args)[source]¶ Inconsistency detected. Please run “borg check {}”.
-
Repository.DEFAULT_MAX_SEGMENT_SIZE= 5242880¶
-
Repository.DEFAULT_SEGMENTS_PER_DIR= 10000¶
-
exception
Repository.InvalidRepository(*args)[source]¶ {} is not a valid repository. Check repo config.
-
Repository.check(repair=False, save_space=False)[source]¶ Check repository consistency
This method verifies all segment checksums and makes sure the index is consistent with the data stored in the segments.
-
exception
-
borg.shellpattern.translate(pat)[source]¶ Translate a shell-style pattern to a regular expression.
The pattern may include
**<sep>(<sep> stands for the platform-specific path separator; “/” on POSIX systems) for matching zero or more directory levels and “*” for matching zero or more arbitrary characters with the exception of any path separator. Wrap meta-characters in brackets for a literal match (i.e. “[?]” to match the literal character ”?”).This function is derived from the “fnmatch” module distributed with the Python standard library.
Copyright (C) 2001-2016 Python Software Foundation. All rights reserved.
TODO: support {alt1,alt2} shell-style alternatives
A basic extended attributes (xattr) implementation for Linux, FreeBSD and MacOS X.
-
exception
borg.xattr.BufferTooSmallError[source]¶ the buffer given to an xattr function was too small for the result.