zydronium/imapsync
1
0
Fork 0
mirror of https://github.com/imapsync/imapsync.git synced 2025-08-04 16:01:29 +02:00
Code Issues Projects Releases Packages Wiki Activity

1.882

Browse source
This commit is contained in:
Nick Bebout 2018-05-07 09:04:23 -05:00
parent 65f8552a91
commit 9a927be251
292 changed files with 53540 additions and 39537 deletions
Download patch file Download diff file Expand all files Collapse all files

94
doc/TUTORIAL_Unix.html
View file

@ -6,8 +6,8 @@
</HEAD><BODY BGCOLOR="white" TEXT="black">
<CENTER>
<H1>Imapsync tutorial</H1>
<FONT SIZE="4"><I>Gilles LAMIRAL gilles.lamiral@laposte.net</I></FONT><BR>
<FONT SIZE="4">$Id: TUTORIAL_Unix.t2t,v 1.23 2017/09/07 12:09:15 gilles Exp gilles $ </FONT>
<FONT SIZE="4"><I>Gilles LAMIRAL gilles@lamiral.info</I></FONT><BR>
<FONT SIZE="4">$Id: TUTORIAL_Unix.t2t,v 1.25 2018/05/05 22:39:12 gilles Exp gilles $ </FONT>
</CENTER>
<P></P>
@ -29,7 +29,7 @@
<LI><A HREF="#toc10">4. Imapsync presentation</A>
<LI><A HREF="#toc11">5. Conventions</A>
<LI><A HREF="#toc12">6. Why start with a test account on destination host2?</A>
<LI><A HREF="#toc13">7. Imapsync default behaviour</A>
<LI><A HREF="#toc13">7. Imapsync default behavior</A>
<LI><A HREF="#toc14">8. To go further with imapsync</A>
</UL>
@ -52,7 +52,7 @@ verify it will do what you expect it to do in your context, all of that
without much pain. So try imapsync with a real account at the source, aka host1,
and a test account at the destination, aka host2.
<P></P>
<LI>Next, once familiar and satified by the result on the host2 test account,
<LI>Next, once familiar and satisfied by the result on the host2 test account,
change to a real user account on host2 or just stop consider it a test one.
</UL>
@ -66,7 +66,7 @@ change to a real user account on host2 or just stop consider it a test one.
Open a terminal and go to the imapsync directory.
The imapsync directory is the directory created by extraction
of the tarball (.tgz), its name is <CODE>imapsync-1.xxx</CODE> where <CODE>1.xxx</CODE>
is imapsync release number (1.836 at the time of this writing).
is imapsync release number (1.882 at the time of this writing).
</P>
<PRE>
@ -82,7 +82,7 @@ Verify imapsync runs on your system
</PRE>
<P>
It should outpout the help message.
It should output the help message.
</P>
<P>
If the previous command fails then there is an installation issue.
@ -91,7 +91,7 @@ and read and apply the installation file corresponding to your
system and drop me an email about your issue.
</P>
<P>
Next, verify imapsync runs live tests. This check needs an internet
Next, verify imapsync runs live tests. This check needs an Internet
access. It does a simple sync between two real dedicated
imap maiboxes located at the host test.lamiral.info
</P>
@ -101,7 +101,7 @@ imap maiboxes located at the host test.lamiral.info
</PRE>
<P>
Now verify the script examples/imapsync_example.sh runs
Now verify that the script examples/imapsync_example.sh runs fine:
</P>
<PRE>
@ -110,7 +110,7 @@ Now verify the script examples/imapsync_example.sh runs
<P>
This script does the same thing than "<CODE>imapsync --testslive</CODE>" but it
uses explicitely the 6 parameters so it'll a good start
uses explicitly the 6 parameters so it will be a good start
for your future own script.
</P>
@ -118,7 +118,7 @@ for your future own script.
<H2>2.2. Working with your data</H2>
<P>
You're still in the imapsync directory.
I consider you're still in the imapsync top directory.
</P>
<P>
Make a copy of the script <CODE>examples/imapsync_example.sh</CODE>
@ -166,7 +166,7 @@ Since imapsync job is to sync two imap accounts we need 3 + 3 = 6 parameters:
<H2>2.4. Take a real user account as source</H2>
<P>
Even to learn and get familiar with imapsync, you can take a
Even during the learning time with imapsync, you can take a
real user account as a source. There is also no problem if this account is
currently used by a user. By default, this account will only be read, no change will
be made by imapsync on it.
@ -194,8 +194,8 @@ the first times you play with imapsync.
</P>
<P>
If you really can't afford a test account on host2, it's ok,
imapsync is not that bad but you may have some work to do to fix some unwanted behaviour.
Unwanted behaviour is mostly folders names that you don't want to be the same on both sides.
imapsync is not that bad but you may have some work to do to fix some unwanted behavior.
Unwanted behavior is mostly folders names that you don't want to be the same on both sides.
</P>
<P>
Assuming that the imap destination server name host2 is <B>destiny.example.com</B>,
@ -228,9 +228,10 @@ Since the <CODE>mysync</CODE> script is a copy of <CODE>examples/imapsync_exampl
your first run with your data should include three other options
<CODE>--automap</CODE> <CODE>--justfolders</CODE> <CODE>--dry</CODE>.
With <CODE>--dry</CODE> option, nothing will really be done on host2
but yet it will test whether the credentials are ok on both sides
or not, by a successful login or a failure. You will also observe
if the folders mapping is ok.
but yet it will test whether the credentials are ok on both sides.
You'll encounter two successful logins, or one failure on host1,
or a successful login on host1 but a failure on host2.
If the login are ok, you will also observe if the folders mapping is ok.
</P>
<P>
If a login fails then double-check all three values that identify
@ -238,14 +239,14 @@ the account, which are the host, the login name, and the password.
</P>
<P>
If the folders mapping proposed is not ok then you can fix it with
option <CODE>--f1f2</CODE>, like the following example mapping source folder
option <CODE>--f1f2</CODE>. The following example maps the source folder
"Sent Messages" to the destination folder "Sent". The double-quotes
are not part of the folders names but they should be used when special
characters like blanks are in the folders names:
</P>
<PRE>
... --f1f2 "Sent Messages=Sent"
./imapsync ... --f1f2 "Sent Messages=Sent"
</PRE>
<P>
@ -257,7 +258,7 @@ As explained in the inline help or in the README:
</PRE>
<P>
You're ready for a real test on your accounts, resticted to
You're ready for a real test on your accounts, restricted to
folders. Remove <CODE>--dry</CODE> from the <CODE>mysync</CODE> script and rerun <CODE>mysync</CODE>:
</P>
@ -274,17 +275,23 @@ POP3, IMAP, HTTP.
</P>
<P>
The oldest protocol still used to access mailboxes is POP3, the Post Office Protocol.
POP3 gives access to only one main box called INBOX.
With POP3, messages have no flags at all, no Seen/UnSeen, Forwarded, or Flagged labels.
It's not systematic but messages are often removed from the POP3 server
POP3 gives access to only one main box called INBOX.
</P>
<P>
With POP3, messages have no flags at all, no Seen/UnSeen, Forwarded, or Flagged labels.
</P>
<P>
It's not systematic but messages are often removed from a POP3 server
each time a software client looks into it,
so messages only appear on the client host that fetched them,
then they are unavailable from any other system located elsewhere.
they are unavailable from any other system located elsewhere.
</P>
<P>
The second protocol to deal with email messages is IMAP, Internet Message Access Protocol.
IMAP gives access to a hierarchy of mailboxes also called folders. Other IMAP features are
concurrent accesses, tagging with flags, search by many criterium like date, subject, size etc.
concurrent accesses, tagging with flags, search by many criterium like date, subject, size etc.
</P>
<P>
The IMAP protocol presents most of the features POP lacks.
Messages stay on the imap server so any client on the network can access them
at any time from anywhere, the same messages with the same flags.
@ -292,12 +299,16 @@ at any time from anywhere, the same messages with the same flags.
<P>
The third protocol to access email messages is HTTP, HyperText Transfer Protocol.
HTTP is the protocol to browse the web.
</P>
<P>
Web browsers like Google Chrome, Mozilla Firefox, Internet Explorer and Safari
are HTTP client softwares. You already know that so what's the point with HTTP mailboxes?
are HTTP client software tools. You already know that so what's the point with HTTP mailboxes?
HTTP mailboxes are called webmails.
Webmails often offer the same features as imap servers do
because webmails underlying storage systems are often imap servers.
So webmails systems like Gmail, Yahoo, Exchange, Zimbra or Office365 are also accessible via imap.
Webmails often offer the same features than imap servers
because webmails underlying storage systems are often imap servers.
</P>
<P>
Webmails systems like Gmail, Yahoo, Exchange, Zimbra or Office365 are also accessible via imap.
</P>
<P>
The conclusion of this protocol review is that mailboxes can be
@ -306,7 +317,8 @@ Here comes imapsync.
</P>
<P>
In case the source mailbox is only accessible by the POP protocol,
you can use the tool <CODE>pop2imap</CODE> located at <A HREF="http://www.linux-france.org/prj/pop2imap/">http://www.linux-france.org/prj/pop2imap/</A>
you can use the tool <CODE>pop2imap</CODE> to sync them.
<CODE>pop2imap</CODE> is located at <A HREF="http://www.linux-france.org/prj/pop2imap/">http://www.linux-france.org/prj/pop2imap/</A>
</P>
<A NAME="toc10"></A>
@ -328,19 +340,25 @@ the main values in those files and adapt them to your context.
Don't be afraid, the mouse won't be forsaken.
You can still use the mouse to launch an editor,
select/copy/paste complete examples,
and run the little script with a doubleclick.
and run the little script with a double-click.
</P>
<P>
Imapsync runs on Linux, Windows and OS X (Macintosh world).
Imapsync is written in the Perl language and thanks to the
Perl developpers, Perl runs mostly everywhere, so does imapsync.
Imapsync is written in the Perl language and, thanks to the
Perl developers, Perl runs mostly everywhere. So does imapsync.
</P>
<P>
While operating systems have a lot in common, they sometimes differ,
especially within syntax. I won't blame anyone, historically Windows
especially within their syntax. I won't blame anyone, historically Windows
came after Unix. The marvelous designers in this old times
decided it would be very cool to not share exactly the same syntax
for doing the same things. Thanks guys, great thinking!
for doing the same things.
</P>
<P>
To designate an end of line, Unix uses the character \n
Windows uses two characters \r\n and Mac use \r.
Thanks guys, great great thinking!
Fifty years later, we still suffer from this...daily.
</P>
<P>
To avoid you some headaches with systems no one masters
@ -422,9 +440,9 @@ It isn't a safe behavior on a real account. So don't use a real user account
to test imapsync. Learn to use it and see what it does on a test account at host2.
</P>
<P>
What can badly happen? The most common bad behaviour is
What can badly happen? The most common bad behavior is
the folders mapping won't be what you expect because it is strictly
reproduced from host1 to host2. The second bad behaviour is
reproduced from host1 to host2. The second bad behavior is
duplicates on second run and after, it's rare but it can happen
when a imap server software changes headers "<CODE>Message-Id</CODE>" or "<CODE>Received</CODE>".
Solutions to avoid duplicates are often easy (There's a FAQ called <CODE>FAQ.Duplicates.txt</CODE> about that).
@ -433,10 +451,10 @@ users won't like that you mess up their mailboxes.
</P>
<A NAME="toc13"></A>
<H1>7. Imapsync default behaviour</H1>
<H1>7. Imapsync default behavior</H1>
<P>
By default, unless explicitely told to do something else:
By default, unless explicitly told to do something else:
</P>
<UL>