WARNING: The obnam project was retired in 2017!Read more here
This documentation is for reference use only, please use another backup solution instead.
Hint: Many users have migrated to restic.
Restoring from backups
The worst has happened! Your cat got confused between its litter box and your hard drive! Your goat deleted your most important document ever! Woe be you!
Let's stay calm. This is why you have backups. There's no need for exclamation marks. Take a deep breath, have a cup of tea, and all will be well.
There's two different approaches for restoring data with Obnam. One relies on a FUSE filesystem, which is a very nice piece of technology that allows Obnam to let you view your backups as just another directory. It is the preferred way, but it is not always available, so Obnam also provides a more primitive, less easy to use method.
Oh no! It's all FUSEd together
obnam mount command lets you look at your backups as if they
were just another directory. This requires that you have FUSE setup.
See the installation chapter for details on that. Most modern Linux
desktops have this out of the box.
mkdir ~/backups obnam mount --to ~/backups
Run the above command, and then look at the
You'll see something like this:
$ ls -l ~/backups total 12 drwxr-xr-x 24 root root 4096 Feb 11 21:41 2 drwxr-xr-x 24 root root 4096 Feb 11 21:41 5 lrwxr-xr-x 24 root root 4096 Feb 11 21:41 latest -> 5 $
Each directory in
~/backups is a backup generation, named after the
generation identifier Obnam invents. The
latest symbolic link points
at the latest generation.
After this, you can restore a single file very easily:
cp ~/backups/latest/home/tomjon/Documents/iloveyou.txt ~/restored.txt
You can copy any files you want from the
~/backups directory, from
any generation, or all of them if you want to. You can look at files
directly, before copying them out, too.
This is an easy way to make sure you find the right version instead of just the latest one.
You can't delete anything in
~/backups. That directory is read-only,
and you can't accidentally, or on purpose, delete or modify anything
there. This is intentional: the
obnam mount command is meant to be a
safe way for you to look at your backups, not something you need to be
Once you're done looking at your backups, you can un-mount the repository:
fusermount -u ~/backups
In addition to doing these things from the command line, you can, of course, use your favourite file manager (graphical or textual) to look at your backed up files. The mounting and un-mounting (depending on your desktop setup) may need to be done on the command line.
Restoring without FUSE
obnam mount isn't available, you can do restores directly with
just Obnam. Use
obnam generations and
obnam ls to find the right
generation to restore, and then run a command like this:
obnam restore --to /tmp/tomjon-restored /home/tomjon/Documents
This would restore just the indicated directory. If you don't tell
Obnam what to restore, it'll restore everything in the latest
generation. You can choose a different generation with
obnam restore --to /tmp/tomjon-restored --generation 2
Note that you can't restore to a directory that already exists. This is to prevent you from accidentally overwriting your live data with restored files. If you do want replace your live data with restored files, you should restore to a temporary location first, and then move the files to where you want them to be.
The file or directory you want to restore must be specified using an absolute path, i.e., starting from / and not relative to the current directory.
An actual example of a restoration
I had a corrupted gnus file, and this is how I restored it from backup.
obnam --config=/home/foobar/cron/conf/obnam.conf generations>~/cron/upload/obgen.txt
This copies all generations for the main obnam backup to obgen.txt, and this is part of that file.
1207586 2014-08-25 08:00:43 .. 2014-08-25 08:08:24 (385163 files, 175029819657 bytes) 1208367 2014-08-25 12:00:42 .. 2014-08-25 12:08:31 (385965 files, 175057598863 bytes) 1209313 2014-08-25 16:00:12 .. 2014-08-25 16:07:33 (386537 files, 175076976590 bytes) 1210254 2014-08-25 20:00:15 .. 2014-08-25 20:09:41 (386896 files, 175086483254 bytes)
And I decided to restore from generation 1208367.
This is the actual restore command.
obnam --config=/home/foobar/cron/conf/obnam.conf --generation=1208367 restore ~/News/rss/nnrss.el --to=/home/foobar/cron/upload/
This restores 'nnrss.el' to ~/cron/upload/ from where I was able to copy it back to its proper place in ~/News/rss/
Obviously you replace your user-name for foobar.
Practice makes prestores painless
You should practice doing restores. This makes you trust your backups more, and lets you be calmer if disaster were to strike. (In fancier terms, you should test your disaster recovery plan.)
Do a trial restore of a few files, or all files, until you're sure you know how to do that. Then do it again, from time to time, to be sure your backups still work. It's much less frightening to do a real restore, when data has actually gone missing, if you've done it before.
In extreme cases, particularly if you're an Obnam developer, you perhaps format your hard drive and then do complete restore, just so you know you can. If you're not an Obnam developer, this is perhaps a bit extreme: at least use a separate hard drive instead of your normal one.