diff options
Diffstat (limited to 'docs/usage/debug.rst')
-rw-r--r-- | docs/usage/debug.rst | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/docs/usage/debug.rst b/docs/usage/debug.rst new file mode 100644 index 000000000..0dc54ae39 --- /dev/null +++ b/docs/usage/debug.rst @@ -0,0 +1,34 @@ +Debugging Facilities +-------------------- + +There is a ``borg debug`` command that has some subcommands which are all +**not intended for normal use** and **potentially very dangerous** if used incorrectly. + +For example, ``borg debug put-obj`` and ``borg debug delete-obj`` will only do +what their name suggests: put objects into repo / delete objects from repo. + +Please note: + +- they will not update the chunks cache (chunks index) about the object +- they will not update the manifest (so no automatic chunks index resync is triggered) +- they will not check whether the object is in use (e.g. before delete-obj) +- they will not update any metadata which may point to the object + +They exist to improve debugging capabilities without direct system access, e.g. +in case you ever run into some severe malfunction. Use them only if you know +what you are doing or if a trusted Borg developer tells you what to do. + +Borg has a ``--debug-topic TOPIC`` option to enable specific debugging messages. Topics +are generally not documented. + +A ``--debug-profile FILE`` option exists which writes a profile of the main program's +execution to a file. The format of these files is not directly compatible with the +Python profiling tools, since these use the "marshal" format, which is not intended +to be secure (quoting the Python docs: "Never unmarshal data received from an untrusted +or unauthenticated source."). + +The ``borg debug profile-convert`` command can be used to take a Borg profile and convert +it to a profile file that is compatible with the Python tools. + +Additionally, if the filename specified for ``--debug-profile`` ends with ".pyprof" a +Python compatible profile is generated. This is only intended for local use by developers. |