imapsync/doc/GOOD_PRACTICES.t2t

Good practices for imapsync
Gilles LAMIRAL   gilles@lamiral.info
% $Id: GOOD_PRACTICES.t2t,v 1.9 2018/04/10 00:15:05 gilles Exp gilles $

= Good practices for imapsync =

You are not supposed to have read the TUTORIAL documentation but it
reading it should help to understand and master the following best practices.


== Simple transfer ==

By principle, imapsync does not change any single byte of messages, 
unless --regexmess or --addheader is used.
But since imapsync identifies messages with "Message-Id" and "Received" headers, 
it ignores messages that lack those headers; 
most of the time it happens with the "Sent" folders.
A way to sync those messages is to add option --addheader. 
Before appending a message on host2, and only when needed, 
--addheader option adds a Message-Id header like "Message-Id: <123456789@imapsync>"
where 123456789 is the host1 folder message UID. Messages on host1 stay untouched.
This way, multiples runs will not generate duplicates as long as UIDs stay 
the same on host1, which is the case for most imap servers.


Unix:
```
  imapsync \
     --host1 imap.truc.org --user1 foo --password1 secret1 \
     --host2 imap.trac.org --user2 bar --password2 secret2 \
     --addheader
```
Windows:
```
  imapsync ^
     --host1 imap.truc.org --user1 foo --password1 secret1 ^
     --host2 imap.trac.org --user2 bar --password2 secret2 ^
     --addheader
```


== Exact backup ==

Assertions for this example:

- The target account at host2 is considered like inactive.
- Everything a user does on host1 will be synced, folders, messages, flags.
- Everything a user does on host2 will be erased by the sync.

Two options are good for an exact backup, --delete2 and --delete2folders.

- --delete2: deletes messages in host2 that are not in host1 server.
- --delete2folders: deletes folders in host2 that are not in host1 server. 

Unix:
```
  imapsync \
     --host1 imap.truc.org --user1 foo --password1 secret1 \
     --host2 imap.trac.org --user2 bar --password2 secret2 \
     --delete2 --delete2folders
```
Windows:
```
  imapsync ^
     --host1 imap.truc.org --user1 foo --password1 secret1 ^
     --host2 imap.trac.org --user2 bar --password2 secret2 ^
     --delete2 --delete2folders
```



Have in mind 

- Doing backups without restoring at least one time to check the process
  is like pissing in a violin or throwing away your messages.
- Manual backups are useless because manually you will never have the ones you need 
  to restore, they will always be out of date.
- Automatic backups are the way to go. They never forget to start. But they may fail.
- Automatic backups can fail. How? Hard disks get fully filled, they crash. 
  Networks fail too. 
- Monitor the backups.
- Remember you have backups.
- Document the restoring process or consider the backup is a just a lost trash.
- Think twice at least before running any restoring command. 
  Restoring is dangerous.


== Restore ==

Restoring is not the exact reverse of backupping
since between a backup and a mistake, the context has changed,
some things went wrong but not all, for examples new messages arrived. 
So synchronize an active account identical from a backup might not be the best idea.

The context can be a crash or equivalent like when a
not friendly admin or service closed definitevely access to your messages.
Even in that case an exact restore, with --delete2 --delete2folders, should not be ok,
just because new messages arrive in INBOX all the time. 


== Presync ==

Presync is like a backup except deleting folders on host2 that
are not on host1 is not always wanted. Presync means a new 
different imap server will host messages and folders.
Often this new imap server has predefined folders that 
should be kept for proper use, so I suggest to not use
option --delete2folders.


Unix:
```
  imapsync \
     --host1 imap.truc.org --user1 foo --password1 secret1 \
     --host2 imap.trac.org --user2 bar --password2 secret2 \
     --delete2
```
Windows:
```
  imapsync ^
     --host1 imap.truc.org --user1 foo --password1 secret1 ^
     --host2 imap.trac.org --user2 bar --password2 secret2 ^
     --delete2
```