[pbs-devel] [PATCH proxmox-backup] docs/technical-overview: add troubleshooting section

[pbs-devel] [PATCH proxmox-backup] docs/technical-overview: add troubleshooting section

[Hannes Laimer]

---
 docs/technical-overview.rst | 58 +++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/technical-overview.rst b/docs/technical-overview.rst
index 0468397b..0958290c 100644
--- a/docs/technical-overview.rst
+++ b/docs/technical-overview.rst
@@ -164,3 +164,61 @@ Verification of encrypted chunks
 For encrypted chunks, only the checksum of the original (plaintext) data is
 available, making it impossible for the server (without the encryption key), to
 verify its content against it. Instead only the CRC-32 checksum gets checked.
+
+Troubleshooting
+---------------
+
+Index files(.fidx, .didx) contain information about how to rebuild a file, more precisely, they
+contain an ordered list of references to the chunks the original file was split up
+in. If there is something wrong with a snapshot it might be useful to find out
+which chunks are referenced in this specific snapshot, and check wheather all of
+them are present and intact. The command for getting the list of referenced chunks
+could look something like this:
+
+.. code-block:: console
+
+    # proxmox-backup-debug inspect file drive-scsi0.img.fidx
+
+The same command can be used to look at .blob file, without ``--decode`` just the size
+and the encryption type, if any, is printed. If ``--decode`` is set the blob file is
+decoded into the specified file('-' will decode it directly into stdout).
+
+.. code-block:: console
+
+    # proxmox-backup-debug inspect file qemu-server.conf.blob --decode -
+
+would print the decoded contents of `qemu-server.conf.blob`. If the file you're
+trying to inspect is encrypted, a path to the keyfile has to be provided using
+``--keyfile``.
+
+Checking in which index files a specific chunk file is referenced can be done
+with:
+
+.. code-block:: console
+
+    # proxmox-backup-debug inspect chunk b531d3ffc9bd7c65748a61198c060678326a431db7eded874c327b7986e595e0 --reference-filter ../../
+
+Here ``--reference-filter`` specifies where index files should be searched, this can be an
+arbitrary path. If, for some reason, the filename of the chunk was changed you can explicitly
+specify the digest using ``--digest``, by default the chunk filename is used as the digest
+to look for. Specifying no ``--reference-filter`` will just print the CRC and encryption status
+of the chunk. You can also decode chunks, to do so ``--decode`` has to be set. If the chunk
+is encrypted a ``--keyfile`` has to be provided for decoding.
+
+Restore without a running PBS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to restore snapshots even without a running PBS, assuming you have
+access to the index and chunk files, if encrypted you'll also need the keyfile
+it was encrypted with.
+
+.. code-block:: console
+
+    # proxmox-backup-debug recover index drive-scsi0.img.fidx ../../../.chunks
+
+where `../../../.chunks` is the path to the directory that contains contains the
+chunks and `drive-scsi0.img.fidx` is the index-file of the file you'd lile to
+restore. Both paths can be absolute or relative. With ``--skip-crc`` it is possible to
+disable the crc checks of the chunks, this will speed up the process, however should
+probably only be used for testing.
+
-- 
2.30.2

[pbs-devel] applied: [PATCH proxmox-backup] docs/technical-overview: add troubleshooting section

[Thomas Lamprecht]

On 20.09.21 11:18, Hannes Laimer wrote:
> ---
>  docs/technical-overview.rst | 58 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 58 insertions(+)
> 
>

applied, thanks!

I reformated the text and adapted it also a bit wording/grammar wise, but it'd be great
if Dylan could take another look.

I also changed thew use of relative paths in the examples to absolute ones with some
meaning encoded, IMO that is easier for a non-involved user to understand what's going
on.

In the recovery example I tried to convey that skip-crc is also useful for trying to
restore partially corrupted files.
There it'd be still good to add a sentence to where the files will be restored too, as
those are rather big and thus it may be relevant to know and maybe even have an optional
param for that (if not already there?)

Also, while reading over this I though again that a `diff` command would be interesting,
i.e., one that allows to pass two snapshots and outputs the amount of differing chunks
(or even the full list + positions with a --verbose option).