This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Obnam
As of August 7, 2017, Obnam has been retired by the author.[1] As requested, Obnam has been masked in the Gentoo repository, and switching to a different backup system is strongly advised for all current users.
obnam (obligatory name) is an easy to use, snapshot capable, FOSS backup utility that supports encryption and deduplication. obnam has built-in generation (snapshot) support. Upon running the first time it will create a full backup of whatever directory it is pointed to. After the initial creation of the backup repository, each additional time Obnam is run is counted as a generation. Generations are incremental backups; Every backup generation looks like a fresh snapshot, but is really incremental: the user does not need to worry whether it is a full backup or not. Only changed data is backed up, and if a chunk of data is already backed up in another file, that data is re-used.[2]
Obnam's features include:
- Data dedupliation;
- Encrypted backups;
- Snapshots, also known as generations (enabled by default);
- Backup checkpoints (creates a "save" every 100MBs or so);
- Multiple users can share the same repository;
- The ability to store backups to a server via SFTP;
- Python based
Installation
Kernel
Obnam is capable of mounting backup repositories using the FUSE filesystem. In order for this to work an intended, the FUSE filesystem (CONFIG_FUSE_FS) must be enabled in the kernel.
File systems ---> <*> FUSE (Filesystem in Userspace) support
When enabling the FUSE filesystem for the first time remember to reboot the system to newly compiled kernel for the changes to take effect.
Emerge Obnam
Emerge the sys-fs/fuse package so the system can have the interfaces available to mount filesystems in user space:
root #
emerge --ask sys-fs/fuse
After FUSE is installed kindly ask Portage what it thinks about emerging Obnam. It should happily emerge the package:
root #
emerge --ask app-backup/obnam
Configuration
Like most backup utilities Obnam can be controlled by configuration files. Obnam will look for configuration files in the following locations:
Global:
- /etc/obnam.conf
- /etc/obnam/*.conf
Local:
- ~/.obnam.conf
- ~/.config/obnam/*.conf
Obnam does not require any configuration file to work properly. All options defined in configuration files can be defined on the terminal.
Options can be defined configuration files for the convenience of the user. Upon typical installation of Obnam, the /etc/obnam.conf file will exist. Following the normal use of configuration files in the /etc/ folder, any configuration files located there will outline the default configurations for Obnam users globally (location 1 and 2 in the list above). If users wish to have configurations different than the global default, then individual configuration settings may be established in their home directories (locations 3 and 4 in the list above).
Usage
Local backups
The following example will be used to show new users how to create a backup of a user's home directory with Obnam. Be sure to be logged in as the user of interest, otherwise the the command will either fail or the repository will be created with the wrong permissions.
user $
mkdir $HOME/backup
user $
obnam backup --repository $HOME/backup --exclude=$HOME/backup $HOME
The last command above should work as intended and happily create a repository in the backup folder. Depending on how many files are in the user's home directory it could take quite a while for the command to complete. Obnam should output information concerning the amount of data it has processed and the time elapsed since the command was ran.
In theory it is not a good idea to create a long term backup in a primary storage location (in this case it is the user's home directory), but for the purpose of explaining some of the options Obman accepts this this example will work.
The options used to create this repository were --repository
and --exclude
. They are very descriptive of their functions:
--repository
— indicates where the repository will be stored--exclude
— tells Obnam to ignore the following file(s) or folder(s). In the above example only a single folder (backup) was excluded, however the exclude option can be specified multiple times for various file(s) and folder(s). It also supports the use of file globbing.
Navigate to the ~/backup folder and type the ls command:
user $
cd ~/backup
user $
ls
<huge_unique_number_file> chunklist chunks chunksums clientlist metadata
Some users might not expect the output from the ls command to show something other than the data file(s) and folder(s) they backed up. An important aspect to understand is that Obnam creates a repository. The files in the backup folder are the data files that were backed up, only the ls command views the data files in repository format. A normal version of ls will not work to view the files which is why the obnam ls command is available. Run the following command in the ~/backup folder:
user $
obnam ls
Ah, that output looks like what one might expect from a repository-creating backup program!
Remote backups using SFTP
A better example of using Obnam for backups would be to push the backup to an off-site location, or at least to different disk than one used for primary storage. Having a local or remote backup server in a RAID configuration is nice in a situation such as this.
Obnam supports the SFTP protocol for pushing backups over the network:
user $
obnam backup --repository sftp://your.backup.server/~/backups $HOME
Backup verification
Reading the backup and understanding how important it is to test backups that have been made, a section about backup verification is imperative. Backups should be tested and verified to make sure they working correctly before users consider their data to be safe in Obnam's hands.
user $
mkdir -p $HOME/tmp/home_dir_backup
user $
obnam restore --repository $HOME/backup --to $HOME/tmp/home_dir_backup
Navigate to the ~/tmp/home_dir_backup folder to view the restored files.
Mount Obnam repository via FUSE
Obnam can mount backup repositories using FUSE. Make sure the system has been setup accordingly (see the Kernel configuration section above).
user $
mkdir $HOME/backup_view
user $
obnam mount --repository $HOME/backup --to $HOME/backup_view
Cleaning up
If any of the Obnam example commands in this article were used for testing or experimentation be sure to clean the directories as needed. This section is simply a courtesy for the reader.
Troubleshooting
Shell expansion issues
While making this guide the author noticed certain kinds of shell expansion might not work as intended. When using the ~
(tilde) symbol as part of the --exclude
path (~/backup) Obnam was ignoring the exclude option and including the ~/backup folder in the repository. At least for now, be aware that using variables or full paths is a safer alternative to using ~/
.
See also
- SparkleShare — a cross platform, free, open source, Dropbox-like, git-based collaboration and file sharing tool. Ideal for text-based files.
- rdiff-backup — a GPL-licensed incremental backup utility based on librsync; it stores changes to files instead of entire duplications.
External resources
- man obnam or see the Official Obnam manual online