mirror of
https://github.com/imapsync/imapsync.git
synced 2024-11-17 00:02:29 +01:00
226 lines
8.3 KiB
Plaintext
226 lines
8.3 KiB
Plaintext
# $Id: README_Windows.txt,v 1.27 2022/04/05 19:45:21 gilles Exp gilles $
|
|
#
|
|
# This is the README_Windows.txt file for imapsync
|
|
# imapsync: IMAP syncing and migration tool.
|
|
|
|
=====================
|
|
Imapsync on Windows
|
|
=====================
|
|
|
|
There are two ways to install and use imapsync on Windows systems: A) or B).
|
|
|
|
Standard users should take the A) way, the simplest way.
|
|
|
|
Developers, or power users that want to build their own imapsync.exe
|
|
or modify it, have to consider the B) way, the complex and powerful way.
|
|
|
|
|
|
---------------
|
|
A) Simplest way
|
|
---------------
|
|
|
|
A.0) Preamble for visual users looking for a visual tool.
|
|
|
|
First, the visual thing I am talking about here is not the online
|
|
visual interface I call /X that you might have seen and used at the
|
|
URL https://imapsync.lamiral.info/X/
|
|
|
|
This /X visual interface is not yet available on Windows as a service
|
|
that you can install and use in your system. I plan to make a visual
|
|
tool available on Windows but, for now, I encountered technical
|
|
issues.
|
|
|
|
So what visual thing am I talking about?
|
|
|
|
Imapsync itself is not a visual tool. The visual tool is Notepad or
|
|
any text editor. Many pure visual users have succeeded in using
|
|
imapsync to transfer their email accounts. As you can guess, only the
|
|
ones that tried have succeeded, so don't give up before trying at
|
|
least once. Another assumption is that visual users can read.
|
|
|
|
Let's go for some reading!
|
|
|
|
A.1) Get imapsync.
|
|
|
|
Get imapsync at https://imapsync.lamiral.info/
|
|
You'll then have access to a zip archive file named imapsync_2.200.zip
|
|
where 2.200 is the imapsync release number.
|
|
|
|
A.2) Extract the zip file in a folder where you will work with imapsync.
|
|
|
|
You can work on the Desktop since the zip file extraction creates
|
|
a unique folder named imapsync_2.200/
|
|
|
|
Do not unzip the archive in what is called a "system" directory since
|
|
you may encounter permission issues.
|
|
|
|
Two points to have in mind:
|
|
* You don't need to be an Administrator to unzip the zip archive.
|
|
* You don't need to be an Administrator to run imapsync.
|
|
|
|
In short, any user on your system can use imapsync.
|
|
|
|
A.3) Check the folder
|
|
|
|
In the folder extracted and called imapsync_2.200, you see 7 files
|
|
and 2 directories. Those files and directories may be presented in a
|
|
different order than the following, the order is not important
|
|
anyway. There are only two important files to get your mailbox
|
|
transfer job started in a few minutes, the first two files of the
|
|
following list:
|
|
|
|
* README_Windows.txt is the current file you are reading.
|
|
* imapsync_example.bat is a simple batch file example that you will copy and edit.
|
|
|
|
* README.txt is the imapsync general document.
|
|
* FAQ.d/* FAQs are a good read when something goes wrong.
|
|
* sync_loop_windows.bat is a batch file example for syncing many accounts.
|
|
* file.txt is an input file example for syncing many accounts.
|
|
* imapsync.exe is the imapsync 64bit binary. You don't have to run it directly.
|
|
* imapsync_32bit.exe is the imapsync 32bit binary. You don't have to run it directly.
|
|
* Cook/ is the directory to build imapsync.exe from its source,
|
|
for the B) way and expert users.
|
|
|
|
You can copy or rename the file imapsync_example.bat as you wish,
|
|
as long as its extension remains ".bat", for example, mysync.bat
|
|
|
|
On Windows systems, a file name ending with a .bat extension means
|
|
"I'm a batch script". A batch script is a file containing commands,
|
|
it's a program. Don't be afraid, a program can be very simple to
|
|
modify and I hope imapsync_example.bat is one of them.
|
|
|
|
The batch scripts have to stay in the same directory as imapsync.exe
|
|
because of the way they call imapsync.exe. They use the string
|
|
".\imapsync.exe", so let them be in the same directory.
|
|
|
|
You can change the path .\ to whatever you want if you understand
|
|
what you are doing (you have to use a pathname from the script point
|
|
of view).
|
|
|
|
For the rest of this documentation, I assume you copied
|
|
imapsync_example.bat to a file named mysync.bat
|
|
|
|
If you don't know how to copy and rename a file then use
|
|
imapsync_example.bat itself, it's ok. The original file is still in
|
|
the zip file in case you want to restart from scratch.
|
|
|
|
A.4) Edit the batch file
|
|
|
|
This section describes how to edit the file mysync.bat and change
|
|
it by replacing example values with your values.
|
|
|
|
To edit mysync.bat, you have to right-click on it and select "modify"
|
|
in the list presented in the small window menu.
|
|
|
|
Notepad or Notepadd++ are very good editor candidates to modify the
|
|
script. Notepad is already installed on any Windows system,
|
|
Notepadd++ is not usually installed but if you have it, then use it.
|
|
|
|
Office Word or any powerful text processor is NOT good for that job.
|
|
Text processors transform files in a special format that is wrong to
|
|
make them stay a good batch file, so don't use them!
|
|
|
|
The documents FAQ.txt and FAQ.d/* contain many tips. They describe
|
|
some special options that are sometimes needed by specific imap
|
|
software servers like Exchange, Office365, or Gmail.
|
|
|
|
Those documents are also available online at
|
|
https://imapsync.lamiral.info/FAQ.d/
|
|
You don't have to look into them unless you encounter problems.
|
|
|
|
A.5) Run the batch file
|
|
|
|
To run imapsync with your values just double-click on the batch file
|
|
mysync.bat
|
|
|
|
There is no need to have administrator privileges to run imapsync.
|
|
|
|
The run happens in a DOS window; usually, this window is black.
|
|
|
|
If imapsync.exe returns immediately with the ERRORLEVEL -1, it may be
|
|
because you have a Group Policy in place to prevent the execution of
|
|
programs in the %TEMP% directory. Temporarily remove this restriction
|
|
and imapsync will work as expected. Thanks to Walter H. for this
|
|
input!
|
|
|
|
Technically speaking, imapsync.exe is an embedded Perl script with
|
|
also the Perl interpreter and many Perl modules, all glued together
|
|
in an archive auto-extracted at run time. So it needs write-access to
|
|
the temporary directory. The temporary directory name depends on the
|
|
user but its value is in the variable %TEMP%. You can have the value
|
|
by running the command ECHO %TEMP% in a DOS window. You can have a
|
|
DOS window by launching the command cmd.exe
|
|
|
|
A.6) Look at the sync running.
|
|
|
|
You can abort the sync at any time with a quick double ctrl-c, hit
|
|
ctrl-c twice within one second.
|
|
|
|
A single ctrl-c will reconnect to both imap servers.
|
|
|
|
You can also simply abort the sync by closing the DOS window, using
|
|
the cross situated at the up-right corner.
|
|
|
|
What you see in this DOS terminal is also put in a logfile located
|
|
in the subdirectory LOG_imapsync/
|
|
|
|
A.7) Control what happened.
|
|
|
|
When the sync is finished you can find the whole log file of the
|
|
output in the folder named "LOG_imapsync/".
|
|
|
|
The logfile name is based on the launching date, hour, minute,
|
|
second, milliseconds, plus the user1 and user2 parameters.
|
|
|
|
For example, a file name can be
|
|
LOG_imapsync\2019_11_29_14_49_36_514_tata_titi.txt
|
|
|
|
There is one log file created for each run. The log file name is
|
|
printed both at the beginning and the end of the imapsync run.
|
|
|
|
IMPORTANT: When there is a problem, the problem is very often
|
|
described at the end of the log file. It means you don't have to read
|
|
all this bloody ununderstandable verbose logfile, just read the end
|
|
first.
|
|
|
|
|
|
A.8) Loop on A.4 through A.7
|
|
|
|
* A.4) edit the batch file
|
|
* A.5) run the batch file
|
|
* A.6) look at the run and the log file
|
|
* A.7) control what happened.
|
|
|
|
Loop on the process of editing, running and controlling imapsync
|
|
until you solve all issues and the sync is over.
|
|
|
|
A good sign that the sync went very well is when the nearly last lines are like:
|
|
|
|
" The sync looks good, all 123456 identified messages in host1 are on host2.
|
|
" There is no unidentified message
|
|
" Detected 0 errors
|
|
|
|
Congratulations!
|
|
|
|
|
|
------------
|
|
B) Hard way
|
|
------------
|
|
|
|
It is the hard way because it installs all software dependencies.
|
|
This is the way for modifying imapsync.exe if needed.
|
|
|
|
B.1) Install Perl if it isn't already installed.
|
|
Strawberry Perl is a very good candidate
|
|
http://strawberryperl.com/
|
|
I use 5.32.1.1 (released 2021-01-24) but previous and later releases
|
|
should work as well (Perl 5.18 to 5.30 do).
|
|
|
|
B.2) Go into the Cook/ directory
|
|
B.3) Double-click build_exe.bat
|
|
|
|
It should create a binary imapsync.exe in the current Cook/ directory.
|
|
|
|
B.4) Move imapsync.exe in the upper directory and follow instructions
|
|
from A.3) to A.8)
|