<?xml version="1.0" encoding="utf-8"?>
<!--
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: Michael Terry
-->

<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      its:version="2.0"
      type="topic" style="task"
      id="restore-worst-case">
<info>
  <desc>What to do if you can’t restore your files</desc>
  <link type="guide" xref="index#restore"/>
  <credit type="author" its:translate="no">
    <name>Michael Terry</name>
  </credit>
  <license href="http://creativecommons.org/licenses/by-sa/4.0/"><p>Creative Commons Attribution-Share Alike 4.0 Unported License</p></license>
</info>

<title>When Everything Goes Wrong</title>

<p><app>Déjà Dup</app> may fail.  Maybe it crashes or gives you an error when you try to restore.  When you really need your data back, the last thing you want do deal with is a bug.  Consider filing a <link href="https://gitlab.gnome.org/World/deja-dup/-/issues/new">help request</link> but in the meantime, here are some approaches to workaround a misbehaving <app>Déjà Dup</app> and get your data back.</p>

<note><p>This is going to get technical.  If none of this makes sense to you, don’t be afraid to <link xref="support">ask for help</link>.</p></note>

<note><p>These instructions assume you have a command line available. Open a <app>Terminal</app> window first.</p></note>

<section id="which-backend">
<title>Restic or Duplicity?</title>

<p>Over time, <app>Déjà Dup</app> has used different backup tools under the covers. Originally, it used <app>Duplicity</app>. Nowadays, it uses <app>Restic</app>.</p>
<p>Your backup might be in either format, depending on when you created it.</p>
<p>Look in the folder where your backup is kept:</p>
<list>
  <item><p>If the filenames all start with <cmd its:translate="no">duplicity-</cmd>, then it's a <app>Duplicity</app> backup. Read the <app>Duplicity</app> sections below.</p></item>
  <item><p>If you see a <cmd its:translate="no">config</cmd> file and a few folders like <cmd its:translate="no">keys</cmd>, then it's a <app>Restic</app> backup. Read the <app>Restic</app> sections below.</p></item>
</list>
</section>

<section id="restic">
<title>Restoring with Restic</title>

<p>On the assumption that <app>Déjà Dup</app> is just not working for you right now, let’s use the command line tool <app>Restic</app> that is used by <app>Déjà Dup</app> behind the scenes to back up and restore your files.</p>

<note style="advanced"><p>If you want more information about <app>Restic</app> than presented here, run <cmd its:translate="no">restic --help</cmd>.</p></note>

<p>The first thing we’ll try is a simple restore of all your data.  Assuming your files are on an external drive mounted as <file its:translate="no">/media/backup</file> and you chose to encrypt the backup, try this:</p>
<screen its:translate="no">restic restore --repo=/media/backup --target=/tmp/restore latest</screen>

<p>If you didn’t encrypt the backup, add <cmd its:translate="no">--insecure-no-password</cmd> to the command.</p>

<p>If you need to do more advanced debugging, read their <link href="https://restic.readthedocs.io/en/stable/077_troubleshooting.html">troubleshooting guide</link>.</p>
</section>

<section id="duplicity">
<title>Restoring with Duplicity</title>

<p>On the assumption that <app>Déjà Dup</app> is just not working for you right now, let’s use the command line tool <app>duplicity</app> that is used by <app>Déjà Dup</app> behind the scenes to back up and restore your files.</p>

<note style="advanced"><p>If you want more information about <app>Duplicity</app> than presented here, read <link href="http://duplicity.gitlab.io/docs.html">its online documentation</link>.</p></note>

<p>The first thing we’ll try is a simple restore of all your data.  Assuming your files are on an external drive mounted as <file its:translate="no">/media/backup</file> and you chose to encrypt the backup, try this:</p>
<screen its:translate="no">duplicity restore file:///media/backup /tmp/restore</screen>

<p>If you didn’t encrypt the backup, add <cmd its:translate="no">--no-encryption</cmd> to the command.</p>

<section id="duplicity-locations">
<title>Other Storage Locations</title>
<p>If you backed up to a remote or cloud server, the syntax you use with <app>Duplicity</app> will be different than the external drive example above.</p>
<p>Read the <app>Duplicity</app> documentation for instructions on how to connect to your server, or try downloading all the <app>Duplicity</app> files yourself to a local folder and following the simpler example above.</p>
</section>

<section id="duplicity-by-hand">
<title>Restoring Duplicity Files by Hand</title>

<p>If even <app>duplicity</app> isn’t working for you, there may be little hope.  The backup file format is complicated and not easily manipulated.  But if you’re desperate, it’s worth a try.</p>

<p>If you used a remote or cloud server to store your backup, first download all the <app>duplicity</app> files and place them in a folder on your computer.  Then enter that folder in your terminal.</p>

<p><app>Duplicity</app> stores your data in small chunks called volumes.  Some volumes belong to the periodic ‘full’ or fresh backups and others to the ‘inc’ or incremental backups.  Starting with a full backup set of volumes at volume 1, you’ll need to restore files volume by volume.</p>

<p>If you encrypted your backup, first you must decrypt the volume with <cmd its:translate="no">gpg</cmd>.  Say you have <file its:translate="no">duplicity-full.20110127T131352Z.vol1.difftar.gpg</file>:</p>
<screen its:translate="no">gpg --output duplicity-full.20110127T131352Z.vol1.difftar --decrypt duplicity-full.20110127T131352Z.vol1.difftar.gpg</screen>

<p>Or to do all at once (make sure you have plenty of space!):</p>
<screen its:translate="no">gpg --multifile --decrypt duplicity-full.20110127T131352Z.*.difftar.gpg</screen>

<p>Now you have either a <file its:translate="no">.difftar</file> or a <file its:translate="no">.difftar.gz</file> volume (depending on whether you had to decrypt it or not).  Use <cmd its:translate="no">tar</cmd> on whichever one you have to extract the individual patch files:</p>
<screen its:translate="no">tar xf duplicity-full.20110127T131352Z.vol1.difftar</screen>

<p>Or again, to do all at once:</p>
<screen its:translate="no">for t in duplicity-full.20110127T131352Z.*.difftar; do tar xf $t; done</screen>

<p>Now the patch files will be in <file its:translate="no">multivolume_snapshot</file> and <file its:translate="no">snapshot</file> folders.  Each file that spanned multiple volumes will be in <file its:translate="no">multivolume_snapshot</file>. Let’s say you backed up <file its:translate="no">/home/jane/essay.txt</file>:</p>
<screen its:translate="no">cd multivolume_snapshot/home/jane/essay.txt
cat * > essay.txt</screen>

<p>To recover data from incremental backups, use <cmd its:translate="no">rdiff</cmd> to stitch the files together. See <cmd its:translate="no">man rdiff</cmd> for usage.</p>

</section>
</section>

</page>
