1OFFLINEIMAP(1)                                                  OFFLINEIMAP(1)
2
3
4

NAME

6       offlineimap - Synchronize mailboxes and Maildirs both ways or one
7       either way.
8

SYNOPSIS

10       offlineimap (options)
11

DESCRIPTION

13       Synchronize the accounts configured in the configuration file via IMAP.
14       Each account has two sides. One of the side must be an IMAP server. The
15       other side can either be a Maildir or another IMAP server.
16
17       Works with Python 2.
18

OPTIONS

20       -h, --help
21           Display summary of options.
22
23       --version
24           Output version.
25
26       -V
27           Output offlineimap version and additional imaplib2 information.
28
29       --dry-run
30           Run in dry run mode.
31
32           Do not actually modify any store but check and print what
33           synchronization actions would be taken if a sync would be
34           performed. It will not precisely give the exact information what
35           will happen. If e.g. we need to create a folder, it merely outputs
36           Would create folder X, but not how many and which mails it would
37           transfer.
38
39       --info
40           Output information on the configured email repositories.
41
42           Useful for debugging and bug reporting. Use in conjunction with the
43           ‘-a’ option to limit the output to a single account. This mode will
44           prevent any actual sync to occur and exits after it output the
45           debug information.
46
47       -1
48           Limit multithreading operations and run solely a single-thread
49           sync.
50
51           This effectively sets the maxsyncaccounts and all maxconnections
52           configuration file variables to 1 (the number).
53
54       -P <directory>
55           Set OfflineIMAP into profile mode.
56
57           The program will create DIR (it must not already exist). As it
58           runs, Python profiling information about each thread is logged into
59           profiledir. Please note: This option is present for debugging and
60           optimization only, and should NOT be used unless you have a
61           specific reason to do so. It will significantly decrease program
62           performance, may reduce reliability, and can generate huge amounts
63           of data. This option implies the ‘-1’ option.
64
65       -a <account1[,account2[,...]]>
66           Overrides the accounts section in the config file.
67
68           Allows one to specify a particular account or set of accounts to
69           sync without having to edit the config file.
70
71       -c <path/to/configuration_file>
72           Specifies a configuration file to use.
73
74       -d <type1[,type2[,...]]>
75           Enables debugging for OfflineIMAP.
76
77           This is useful if you are to track down a malfunction or figure out
78           what is going on under the hood. This option requires one or more
79           debugtypes, separated by commas. These define what exactly will be
80           debugged, and so far include options: "imap", "thread", "maildir"
81           or "ALL". The imap option will enable IMAP protocol stream and
82           parsing debugging. Note that the output may contain passwords, so
83           take care to remove that from the debugging output before sending
84           it to anyone else. The maildir option will enable debugging for
85           certain Maildir operations. The use of any debug option (unless
86           "thread" is included), implies the single-thread option ‘-1’.
87
88       -l <path/to/file.log>
89           Send logs to <file.log>.
90
91       -s
92           Send logs to syslog.
93
94       -f <folder1[,folder1[,...]]>
95           Only sync the specified folders.
96
97           The folder names are the untranslated foldernames of the remote
98           repository. This command-line option overrides any folderfilter and
99           folderincludes options in the configuration file.
100
101       -k <[section:]option=value
102           Override any configuration file option.
103
104           If "section" is omitted, it defaults to "general". Any underscores
105           in the section name are replaced with spaces: for instance, to
106           override option "autorefresh" in the "[Account Personal]" section
107           in the config file one would use ‘-k
108           Account_Personal:autorefresh=30’. Repeat this option as much as
109           necessary to redefine multiple options.
110
111       -o
112           Run only once.
113
114           Ignore any autorefresh setting in the configuration file.
115
116       -q
117           Run only quick synchronizations.
118
119           Ignore any flag updates on IMAP servers. If a flag on the remote
120           IMAP changes, and we have the message locally, it will be left
121           untouched in a quick run. This option is ignored if maxage is set.
122
123       -u <UI>
124           Specifies an alternative user interface to use.
125
126           This overrides the default specified in the configuration file. The
127           UI specified with ‘-u’ will be forced to be used, even if checks
128           determine that it is not usable. Possible interface choices are:
129           quiet, basic, syslog, ttyui, blinkenlights, machineui.
130
131       --delete-folder
132           Delete a folder on the remote repository.
133
134           Only one account must be specified/configured for this feature to
135           work or you must provide one account with -a. The folder name must
136           be provided with the remote separators (likely /) in UTF-8 if
137           utf8foldernames is enabled or in IMAP otherwise. E.g.:
138           "Remote/folder/name".
139
140       --migrate-fmd5-using-nametrans
141           Migrate FMD5 hashes from versions prior to 6.3.5.
142
143           The way that FMD5 hashes are calculated was changed in version
144           6.3.5 (now using the nametrans folder name) introducing a
145           regression which may lead to re-uploading all messages. Try and fix
146           the above regression by calculating the correct FMD5 values and
147           renaming the corresponding messages.
148
149           Caution
150           Since the FMD5 part of the filename changes, this may lead to UID
151           conflicts. Ensure to dispose a proper backup of both the cache and
152           the Maildir before running this fix as well as verify the results
153           using the ‘--dry-run’ flag first.
154
155       --mbnames-prune
156           Remove dangling entries for removed accounts or if mbnames is not
157           enabled/used anymore.
158
159           Internally, offlineimap build intermediate mbnames files. They are
160           added automatically when mbnames is enabled. However, disabling
161           accounts so they are not synced anymore does not necessarily means
162           they should be removed from the file built by mbnames. It is
163           required to start offlineimap with this CLI option each time
164           accounts are removed. When run, any account not in the accounts
165           configuration option are removed in the mbnames file.
166
167           It is possible to manually remove intermediate files in
168           <metadata>/mbnames/.
169
170           Notice this option honors --dry-run.
171

SYNCHRONIZATION PERFORMANCE

173       By default, we use fairly conservative settings that are safe for
174       syncing but that might not be the best performing one. Once you got
175       everything set up and running, you might want to look into speeding up
176       your synchronization. Here are a couple of hints and tips on how to
177       achieve this.
178
179        1. Synchronize more than one account.
180
181           By default we only use one connection to an IMAP server. Using 2 or
182           even 3 speeds things up considerably in most cases. In order to
183           synchronize more than one account concurrently, consider starting
184           one instance of offlineimap per account.
185
186               Warning
187               enabling the maxsyncaccounts and maxconnections options is
188               deprecated since it’s known to have race conditions.
189
190        2. Use folderfilters.
191
192           The quickest sync is a sync that can ignore some folders. I sort my
193           inbox into monthly folders, and ignore every folder that is more
194           than 2-3 months old, this lets me only inspect a fraction of my
195           Mails on every sync. If you haven’t done this yet, do it :). See
196           the folderfilter section in offlineimap.conf.
197
198        3. The sqlite cache.
199
200           OfflineImap caches the state of the synchronisation to e.g. be able
201           to determine if a mail has been added or deleted on either side.
202
203           The historical status cache was a plain text file that was writing
204           out the complete file for each single new message (or even changed
205           flag) to a temporary file. If there was plenty of files in a folder
206           this was bound to make things slow. The latest status cache is
207           sqlite. This saves plenty of disk activity.
208
209           The historical plain status cache is not supported anymore but
210           migrating from a very old installation using the plain text cache
211           is still supported. In this case, you may want to delete the old
212           cache directory in <metadata>/Account-<account>/LocalStatus
213           manually (the sqlite cache stands in the LocalStatus-sqlite
214           folder). First, make sure you have run the new version of
215           offlineimap for all your accounts so that the status cache was
216           migrated.
217
218        4. Use quick sync.
219
220           A regular sync will request all flags and all UIDs of all mails in
221           each folder which takes quite some time. A quick sync only compares
222           the number of messages in a folder on the IMAP side (it will detect
223           flag changes on the Maildir side of things though). A quick sync on
224           my smallish account will take 7 seconds rather than 40 seconds.
225           E.g. run a cron script that does a regular sync once a day, and
226           does quick syncs ‘-q’ only synchronizing the ‘-f INBOX’ in between.
227
228        5. Turn off fsync.
229
230           In the [general] section you can set fsync to True or False. If you
231           want to play 110% safe and wait for all operations to hit the disk
232           before continuing, you can set this to True. If you set it to
233           False, you lose some of that safety, trading it for speed.
234

SECURITY AND SSL

236       By default, OfflineIMAP will connect using any method that openssl
237       supports, that is SSLv2, SSLv3, or TLSv1.
238
239       Do note that SSLv2 is notoriously insecure and deprecated.
240       Unfortunately, python2 does not offer easy ways to disable SSLv2. It is
241       recommended you test your setup and make sure that the mail server does
242       not use an SSLv2 connection. Use e.g. "openssl s_client -host
243       mail.server -port 443" to find out the connection that is used by
244       default.
245
246       •   Certificate checking
247
248           Unfortunately, by default we will not verify the certificate of an
249           IMAP TLS/SSL server we connect to, so connecting by SSL is no
250           guarantee against man-in-the-middle attacks. While verifying a
251           server certificate checking the fingerprint is recommended. There
252           is currently only one safe way to ensure that you connect to the
253           correct server in an encrypted manner: you can specify a
254           sslcacertfile setting in your repository section of
255           offlineimap.conf pointing to a file that contains (among others) a
256           CA Certificate in PEM format which validating your server
257           certificate. In this case, we will check that:
258
259            1. The server SSL certificate is validated by the CA Certificate.
260
261            2. The server host name matches the SSL certificate.
262
263            3. The server certificate is not past its expiration date.
264
265       The FAQ has an entry on how to create your own certificate and CA
266       certificate.
267
268       •   StartTLS
269
270           If you have not configured your account to connect via SSL anyway,
271           OfflineImap will still attempt to set up an SSL connection via the
272           STARTTLS function, in case the imap server supports it.
273
274           There is no certificate or fingerprint checking involved at all,
275           when using STARTTLS (the underlying imaplib library does not
276           support this yet). This means that you will be protected against
277           passively listening eavesdroppers and they will not be able to see
278           your password or email contents. However, this will not protect you
279           from active attacks, such as Man-In-The-Middle attacks which cause
280           you to connect to the wrong server and pretend to be your mail
281           server.
282
283           DO NOT RELY ON STARTTLS AS A SAFE CONNECTION GUARANTEEING THE
284           AUTHENTICITY OF YOUR IMAP SERVER!
285

UNIX SIGNALS

287       OfflineImap listens to the unix signals SIGUSR1, SIGUSR2, SIGTERM,
288       SIGINT, SIGHUP, SIGQUIT.
289
290       •   If sent a SIGUSR1 it will abort any current (or next future) sleep
291           of all accounts that are configured to autorefresh. In effect, this
292           will trigger a full sync of all accounts to be performed as soon as
293           possible.
294
295       •   If sent a SIGUSR2 or SIGABRT, it will stop autorefresh mode for all
296           accounts. That is, accounts will abort any current sleep and will
297           exit after a currently running synchronization has finished. This
298           signal can be used to gracefully exit out of a running offlineimap
299           "daemon".
300
301       •   SIGTERM, SIGINT, SIGHUP are all treated to gracefully terminate as
302           soon as possible. This means it will finish syncing the current
303           folder in each account, close keep alive connections, remove locks
304           on the accounts and exit.
305
306           It may take up to 10 seconds, if autorefresh option is used.
307
308           More than one SIGTERM will behave like SIGQUIT.
309
310       •   If sent SIGQUIT, dumps stack traces for all threads and tries to
311           dump process core.
312

KNOWN ISSUES

314       •   Deletions.
315
316           While in usual run the deletions are propagated. To prevent from
317           data loss, removing a folder makes offlineimap re-sync the folder.
318           However, propagating the removal of the whole content of a folder
319           can happen in the two following cases:
320
321           •   The whole content of a folder is deleted but the folder
322               directory still exists.
323
324           •   The parent directory of the folder was deleted.
325
326       •   SSL3 write pending.
327
328           Users enabling SSL may hit a bug about "SSL3 write pending". If so,
329           the account(s) will stay unsynchronised from the time the bug
330           appeared. Running OfflineIMAP again can help. We are still working
331           on this bug. Patches or detailed bug reports would be appreciated.
332           Please check you’re running the last stable version and send us a
333           report to the mailing list including the full log.
334
335       •   IDLE support is incomplete and experimental. Bugs may be
336           encountered.
337
338           •   No hook exists for "run after an IDLE response".
339
340               Email will show up, but may not be processed until the next
341               refresh cycle.
342
343           •   nametrans may not be supported correctly.
344
345           •   IMAP IDLE <→ IMAP IDLE doesn’t work yet.
346
347           •   IDLE might stop syncing on a system suspend/resume.
348
349           •   IDLE may only work "once" per refresh.
350
351               If you encounter this bug, please send a report to the list!
352
353       •   Maildir support in Windows drive.
354
355           Maildir uses colon character (:) in message file names. Colon is
356           however forbidden character in windows drives. There are several
357           workarounds for that situation:
358
359            1. Enable file name character translation in windows registry (not
360               tested).
361
362http://support.microsoft.com/kb/289627
363
364            2. Use cygwin managed mount (not tested).
365
366               •   not available anymore since cygwin 1.7
367
368            3. Use "maildir-windows-compatible = yes" account OfflineIMAP
369               configuration.
370
371               •   That makes OfflineIMAP to use exclamation mark (!) instead
372                   of colon for storing messages. Such files can be written to
373                   windows partitions. But you will probably loose
374                   compatibility with other programs trying to read the same
375                   Maildir.
376
377               •   Exclamation mark was chosen because of the note in
378                   http://docs.python.org/library/mailbox.html
379
380               •   If you have some messages already stored without this
381                   option, you will have to re-sync them again
382
383       •   OfflineIMAP confused after system suspend.
384
385           When resuming a suspended session, OfflineIMAP does not cleanly
386           handles the broken socket(s) if socktimeout option is not set. You
387           should enable this option with a value like 10.
388
389       •   OfflineIMAP confused when mails change while in a sync.
390
391           When OfflineIMAP is syncing, some events happening since the
392           invocation on remote or local side are badly handled. OfflineIMAP
393           won’t track for changes during the sync.
394
395       •   Sharing a maildir with multiple IMAP servers.
396
397           Generally a word of caution mixing IMAP repositories on the same
398           Maildir root. You have to be careful that you never use the same
399           maildir folder for 2 IMAP servers. In the best case, the folder MD5
400           will be different, and you will get a loop where it will upload
401           your mails to both servers in turn (infinitely!) as it thinks you
402           have placed new mails in the local Maildir. In the worst case, the
403           MD5 is the same (likely) and mail UIDs overlap (likely too!) and it
404           will fail to sync some mails as it thinks they are already
405           existent.
406
407           I would create a new local Maildir Repository for the Personal
408           Gmail and use a different root to be on the safe side here. You
409           could e.g. use
410
411               `~/mail/Pro' as Maildir root for the ProGmail and
412               `~/mail/Personal' as root for the personal one.
413
414           If you then point your local mutt, or whatever MUA you use to
415           ‘~/mail/’ as root, it should still recognize all folders.
416
417       •   Edge cases with maxage causing too many messages to be synced.
418
419           All messages from at most maxage days ago (+/- a few hours,
420           depending on timezones) are synced, but there are cases in which
421           older messages can also be synced. This happens when a message’s
422           UID is significantly higher than those of other messages with
423           similar dates, e.g. when messages are added to the local folder
424           behind offlineimap’s back, causing them to get assigned a new UID,
425           or when offlineimap first syncs a pre-existing Maildir. In the
426           latter case, it could appear as if a noticeable and random subset
427           of old messages are synced.
428
429       •   Offlineimap hangs.
430
431           When having unexpected hangs it’s advised to set
432           ‘singlethreadperfolder’ to yes, especially when in IMAP/IMAP mode
433           (no maildir).
434
435       •   Passwords in netrc.
436
437           Offlineimap doesn’t know how to retrieve passwords when more than
438           one account is stored in the netrc file. See
439           https://github.com/OfflineIMAP/offlineimap/issues/295.
440
441       •   XOAUTH2
442
443           XOAUTH2 might be a bit tricky to set up. Make sure you’ve followed
444           the step to step guide in offlineimap.conf. The known bugs about
445           Gmail are tracked at
446           https://github.com/OfflineIMAP/offlineimap/labels/Gmail.
447
448           Sometimes, you might hit one of the following error:
449
450           •   [imap]: xoauth2handler: response "{u’error': u’invalid_grant'}"
451
452           •   oauth2handler got: {u’error': u’invalid_grant'}
453
454           In such case, we had reports that generating a new refresh token
455           from the same client ID and secret can help.
456
457           Google documentation on "invalid_grant".
458
459               When you try to use a refresh token, the following returns you an
460               invalid_grant error:
461
462                 - Your server's clock is not in sync with network time protocol - NTP.
463                 - The refresh token limit has been exceeded.
464
465           Token expiration.
466
467               It is possible that a granted token might no longer work. A token might stop
468               working for one of these reasons:
469
470                 - The user has revoked access.
471                 - The token has not been used for six months.
472                 - The user changed passwords and the token contains Gmail scopes.
473                 - The user account has exceeded a certain number of token requests.
474
475               There is currently a limit of 50 refresh tokens per user account per client. If
476               the limit is reached, creating a new token automatically invalidates the oldest
477               token without warning. This limit does not apply to service accounts.
478
479
480           See
481           https://developers.google.com/analytics/devguides/config/mgmt/v3/authorization
482           and
483           https://developers.google.com/identity/protocols/OAuth2#expiration
484           to know more.
485
486       •   "does not have message with UID" with Microsoft servers
487
488               `ERROR: IMAP server 'Server ### Remote' does not have a message with UID 'xxx'`
489
490           Microsoft IMAP servers are not compliant with the RFC. It is
491           currently required to folderfilter some faulting folders. See
492           http://www.offlineimap.org/doc/FAQ.html#exchange-and-office365 for
493           a detailed list.
494

MAIN AUTHORS

496           John Goerzen, Sebastian Spaetz, Eygene Ryabinkin, Nicolas Sebrecht.
497

SEE ALSO

499           offlineimapui(7), openssl(1), signal(7), sqlite3(1).
500           http://www.offlineimap.org
501
502
503
504                                  07/08/2023                    OFFLINEIMAP(1)
Impressum