In Depth


Gmvault is a user friendly command-line tool that setup most of the necessary defaults to quickly sync (backup) your gmail account or restore it to a gmail account.
It should be self-explanatory. Use gmvault -h to see the different options and how the tool works.

$./gmvault -h

usage: gmvault [-h] [-v] {restore,sync} ...

optional arguments:
  -h, --help      show this help message and exit
  -v, --version   show program's version number and exit

subcommands:
  {restore,sync}  valid subcommands.
    sync          synchronize with a given gmail account.
    restore       restore gmvault-db to a given email account.

Examples:

a) Get help for each of the individual commands

#> gmvault sync -h
#> gmvault restore --help



Gmvault is a command-oriented tool and every Gmvault call needs to contain a subcommand (sync or restore).
You will first need to setup the credential (token or password) for the different gmail accounts you want to use prior to syncing or restoring them with Gmvault.
This will allow Gmvault to automatically connect to the accounts you want to work with.

Authentication


To authenticate yourself and authorize Gmvault accessing your Gmail account, Gmvault allows users to use a Gmail XOAuth token or your Gmail login password.
The XOAuth authentication is the recommended way to access your account. This method is activated by default.
After the first authentication for a given account, the XOAuth token is stored in $HOME/.gmvault or %HOME% (c:\users\MYUSER) and will be used for consequent authentications.
The following example uses an XOAuth token for accessing a gmail account. If the token has not been created for the used Gmail account, Gmvault will automatically try to create one with your help.
Just follow the instructions given by Gmvault.

!$ ./gmvault sync myuser@gmail.com

Use gmvault-db /home/myuser/gmvault-db.
Oauth will be used for authentication.

gmvault will now open a web browser page in order for you to grant gmvault access to your Gmail.
Please make sure you're logged into the correct Gmail account (myuser@gmail.com) before granting access.
Press ENTER to open the browser. Once you've granted access you can switch back to gmvault.

Press ENTER and Gmvault will launch a browser to allow you granting access on the gmail account you want to use.
Be sure to verify that you are logged on the right account.

Grant access to Gmvault.
You should see this once you have granted access to Gmvault.

Once you have granted access to Gmvault, press one more time ENTER to let Gmvault finish its work.

You should now see the web page on your browser now.
If you don't, you can manually open:

https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=4%abdedsk-leskdkrs-QM4ZnL6tLDy

Once you've granted gmvault access, press the Enter key.

Below is a screenshot of a complete authentication session on Windows.

Grant access to Gmvault.

After that authentication session Gmvault will automatically use the XOAuth token stored under $HOME/.gmvault or %HOME% (c:\users\MYUSER) for all session with the MYUSER user.

Authentication with gmail password


If you do not want to use the Gmail XOAuth token (not recommended), you can always use Gmvault with your password.
In that case, you will have to interactively enter your password at the beginning of the Gmvault session.

$./gmvault sync myuser@gmail.com -p 

Use gmvault-db /home/myuser/gmvault-db.
Gmail password will be used for authentication.

Please enter gmail password for myuser@gmail.com and press ENTER:
Connect to Gmail server.
53432 emails to be fetched.
Process email num 0 (imap_id:1) from 2005-10.
Process email num 1 (imap_id:2) from 2005-10.
Process email num 2 (imap_id:3) from 2005-10.
Process email num 3 (imap_id:5) from 2005-10.
...

You can also if necessary store your password in $HOME/.gmvault or %HOME% (c:\users\MYUSER) with --store-passwd command.
The password will be encrypted before to be stored. Note that functionnality is provided for flexibility purposes but is not recommended.
Prefer the XOAuth authentication if you need to automate Gmvault synchronisation and restoration operations.

$./gmvault sync myuser@gmail.com -p --store-passwd

Use gmvault-db /home/myuser/gmvault-db.
Gmail password will be used for authentication.

Please enter gmail password for myuser@gmail.com and press ENTER:
Store password for myuser@gmail.com in $HOME/.gmvault.
Connect to Gmail server.
53432 emails to be fetched.
Process email num 0 (imap_id:1) from 2005-10.
Process email num 1 (imap_id:2) from 2005-10.
Process email num 2 (imap_id:3) from 2005-10.
Process email num 3 (imap_id:5) from 2005-10.
...

Finally, it is also possible to renew your stored password with --renew-passwd.

$./gmvault sync myuser@gmail.com -p --renew-passwd

Use gmvault-db /home/myuser/gmvault-db.
Gmail password will be used for authentication.

Please enter gmail password for myuser@gmail.com and press ENTER:
Store password for myuser@gmail.com in $HOME/.gmvault.
Connect to Gmail server.
53432 emails to be fetched.
Process email num 0 (imap_id:1) from 2005-10.
Process email num 1 (imap_id:2) from 2005-10.
Process email num 2 (imap_id:3) from 2005-10.
Process email num 3 (imap_id:5) from 2005-10.
...

Making a backup of your Gmail account


The sync command of Gmvault allow users to backup the Gmail account of their choice.
use gmvault sync -h to get explanations regarding all options. Examples are also provided after the options details.

$./gmvault sync -h

usage: gmvault sync [-h] [-t TYPE] [-d DB_DIR] [-o] [--renew-passwd]
                    [--store-passwd] [-p] [-r REQ] [-g REQ] [-e]
                    [-z DB_CLEANING] [-m] [--server HOSTNAME] [--port PORT]
                    [--debug]
                    email

positional arguments:
  email                 email to sync with.

optional arguments:
  -h, --help            show this help message and exit
  -t TYPE, --type TYPE  type of synchronisation: full|quick|custom. (default:
                        full)
  -d DB_DIR, --db-dir DB_DIR
                        Database root directory. (default: ./gmvault-db)

... help shortened ...

  --server HOSTNAME     Gmail imap server hostname. (default: imap.gmail.com)
  --port PORT           Gmail imap server port. (default: 993)
  --debug               Activate debugging info

Examples:

a) Full synchronisation with email and oauth login in ./gmvault-db

#> gmvault sync foo.bar@gmail.com

b) Quick daily synchronisation (only the last 2 months are scanned)

#> gmvault sync --type quick foo.bar@gmail.com

c) Custom synchronisation with an IMAP request for advance users

#> gmvault sync --type custom --imap-req 'Since 1-Nov-2011 Before 10-Nov-2011' 'foo.bar@gmail.com'

d) Custom synchronisation with an Gmail request for advance users

#> gmvault sync --type custom --gmail-req 'in:inbox from:foo' 'foo.bar@gmail.com'

e) Full synchronisation for German users that have to use googlemail instead of gmail

#> gmvault sync --imap-server imap.googlemail.com 'foo.bar@gmail.com'

gmvault sync myuser@gmail.com will backup the entire content of your gmail account from the oldest to newest email.
You will also notice that Gmvault tries to estimate how long it will take to backup your entire gmail account every 50 emails.
$./gmvault sync guillaume.aubert@gmail.com -p

Use gmvault-db /home/aubert/gmvault-db.
Gmail password will be used for authentication.

Please enter gmail password for guillaume.aubert@gmail.com and press ENTER:
Connect to Gmail server.
35965 emails to be fetched.
Process email num 0 (imap_id:1) from 2004-10.
Process email num 1 (imap_id:2) from 2004-10.
Process email num 2 (imap_id:3) from 2004-10.
...
Process email num 48 (imap_id:55) from 2004-10.
Process email num 49 (imap_id:56) from 2004-10.

== Processed 50 emails in 6s. 35915 left to be stored (time estimate 1h 11m 50s).==

Process email num 50 (imap_id:58) from 2004-10.
Process email num 51 (imap_id:59) from 2004-10.
Process email num 52 (imap_id:60) from 2004-10.
...
Gmvault will list all the emails that are backed up on disk.
Your emails will be stored in an email database created by default in $HOME/.gmvault-db.
Use the -d or --db-dir to choose where the email database is going to be created.
When you create an email database, it is automatically bonded to the email account you would like to backup.
If you try to backup a Gmail account with an email database bounded with another email, Gmvault will exit in error.
$./gmvault sync gsync.mtester@gmail.com

Use gmvault-db /home/aubert/gmvault-db.
Oauth will be used for authentication.

Use oauth credentials from /home/aubert/.gmvault/gsync.mtester@gmail.com.oauth.
Successfully read oauth credentials.

Connect to Gmail server.
Error The email database /home/aubert/gmvault-db is already associated with guillaume.aubert@gmail.com. Use option (-m, --multiple-db-owner) if you want to link it with gsync.mtester@gmail.com. For more information see log file

usage: gmvault [-h] [-v] {restore,sync} ...

optional arguments:
  -h, --help      show this help message and exit
  -v, --version   show program's version number and exit

subcommands:
  {restore,sync}  valid subcommands.
    sync          synchronize with a given gmail account.
    restore       restore gmvault-db to a given email account.

Examples:

a) Get help for each of the individual commands

#> gmvault sync -h
#> gmvault restore --help

$
If you wish to backup multiple Gmail accounts in one email database, you can use the -m or --multiple-db-owner to let Gmvault allowing it.
Gmvault provides 3 types of synchronisations with -t, --type full, quick or custom. The full synchronisation scans your complete email box and store locally on disk if the email doesn't exist already. Gmvault uses the full synchronisation type by default.
The quick type is used to daily backup your email account automatically (with a cron job for example) and it updates the local email repository with the latest additions.
The quick synchronisation goes up to two month backward in time and update your local on disk email repository to reflect the addition and deletion of emails as well the labels modifications.
The custom synchronisation allows to provide a custom imap or gmail request if you only wish to backup a subset of your emails.

Restoring your Gmail account


You can use the restore command to recreate your gmail account in case of problems. Like the sync command the restore command provides 2 types of restore with -t, --type full or quick. The full restore will try to restore completly the local email repository into the given email account while the quick restore will only restore the last 2 months of emails. Restore only upload new emails onto your given gmail account and also update the associated information such as labels but never delete an email from inbox.

a) Complete restore of your gmail account (backed up in ~/gmvault-db) into anewfoo.bar@gmail.com

$> ./gmvault restore -d ~/gmvault-db anewfoo.bar@gmail.com

b) Quick restore (restore only the last 2 months to make regular updates) of your gmail account into anewfoo.bar@gmail.com

$> ./gmvault restore --type quick -d ~/gmvault-db foo.bar@gmail.com

If it also possible to apply a given label to the current update you are performing:
$>./gmvault restore --label "20120422-gmvault-restore" -d ~/gmvault-db anewfoo.bar@gmail.com
This will apply "20120422-gmvault-restore" to all restored emails.