djipko / gbackup-rs

Fast and configurable CLI tool to back-up your GMail data - written in Rust

gbackup-rs - Backup your GMail

gbackup-rs is yet another tool for backing up your GMail account with a few features worth calling out:

• It does incremental backups
• Uses an easy to understand config format and can handle multiple GMail accounts
• Backup is transactional, meaning less likelihood of corrupt backups
• It will pull email down in parallel which can result in a 5x + speed-up of the initial backup
• Written in Rust meaning more likely to be fast and secure

It uses a custom schema (a sqlite db) by default to store email - and tools to export to commonly used formats (such as, say, mbox) are separate (adhering to good ol' unix philosophy of doing only one thing)

Design

gbackup-rs uses IMAP to sync email but does not aim to replicate all of your Gmail mailbox layout. Its main goal is to back data up, and not be a full-fledged IMAP e-mail client. This may change in the future if it turns out to be useful, but for now the main goal of the design is to allow for fast backups and prevent data-loss, should you lose access to your Gmail account for whatever reason (after ~15 years of using GMail - I personally have invaluable data from several stages of life that would be really hard to replace).

Installing

The easiest way to install this software is using cargo. If you have cargo installed, simply run:

 cargo install gbackup-rs

Installing cargo itself can be done by following the guide to installing the Rust environment using rustup as described here.

Usage

gbackup-rs is driven by a single configuration file. This is best explained with a simple example - there is an example of a config file in the top level directory. A simple and rather self-explanatory config would look something like:

[[accounts]]
    username = "[email protected]"
    [accounts.password]
        type = "EnvVar"
        name = "GMAIL_PASSWORD"
    [accounts.backup]
        type = "Sqlite"
        backup_dir = "/Users/firstname/gmail_backup_test/"
    [accounts.export]
        type = "Mbox"
        path = "/Users/firstname/gmail.mbox"

and by default it's expected to be stored in a file called .gbackup.toml in the working directory (but is configurable via the -c option). Then you would simply run:

 GMAIL_PASSWORD="mysecretpass" gbackup-rs -w 10

This is recommended for the first back-up as it will pull down email using 10 parallel IMAP connections. This results in a significant speed up! On a ~4Gb mailbox - a single connection backup took ~19 minutes and 5 minutes with 10 parallel connections. Since subsequent backups are incremental - running with a single worker (the default) should be fine for low volume personal accounts.

The resulting backup can then be found in the configured directory as backup.sqlite

NOTE that you will need to set up an app password for you gmail account here

Exporting the data to a widely used format such as mbox can be done by running with the export subcommand

gbackup-rs -c ~/.gbackup.toml export

This will in turn run any export engines configured for each account in the config, if any.

Future features

gbackup-rs is highly experimental at this point and many things are likely to change (hopefully for the better). Check out the issues tracker to see some of the stuff that's been worked on.

gbackup-rs's Issues

Fails to compile on 1.53.0 and later Rust version

This seems to be caused by the lexical-core transitive dependency (imap crate depends on this via imap-proto). The root cause seems to be explained here rust-lang/rust#76904 - stabilisation of integer::BITS. This has since been fixed in the relevant library (more details in the issue) but imap latest stable (2.4.1) still pins a bad version of imap-proto.

The newer 3.x version of IMAP crate seems to be ahead of this - so I will create an issue to test and upgrade to that (especially once it's been actually released to crates.io).

However - until then - I should probably pin the toolchain to 1.52.0 so that this project continues to build normally.