1OFFLINEIMAP(1) OFFLINEIMAP(1)
2
6 offlineimap - Synchronize mailboxes and Maildirs both ways or one
7 either way.
8
10 offlineimap (options)
11
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 Works with Python 2.
18
20 -h, --help
21 Display summary of options.
22 --version
24 Output version.
25 -V
27 Output offlineimap version and additional imaplib2 information.
28 --dry-run
30 Run in dry run mode.
31 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 --info
40 Output information on the configured email repositories.
41 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 -1
48 Limit multithreading operations and run solely a single-thread
49 sync.
50 This effectively sets the maxsyncaccounts and all maxconnections
52 configuration file variables to 1 (the number).
53 -P <directory>
55 Set OfflineIMAP into profile mode.
56 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 -a <account1[,account2[,...]]>
66 Overrides the accounts section in the config file.
67 Allows one to specify a particular account or set of accounts to
69 sync without having to edit the config file.
70 -c <path/to/configuration_file>
72 Specifies a configuration file to use.
73 -d <type1[,type2[,...]]>
75 Enables debugging for OfflineIMAP.
76 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 -l <path/to/file.log>
89 Send logs to <file.log>.
90 -s
92 Send logs to syslog.
93 -f <folder1[,folder1[,...]]>
95 Only sync the specified folders.
96 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 -k <[section:]option=value
102 Override any configuration file option.
103 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 -o
112 Run only once.
113 Ignore any autorefresh setting in the configuration file.
115 -q
117 Run only quick synchronizations.
118 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 -u <UI>
124 Specifies an alternative user interface to use.
125 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 --delete-folder
132 Delete a folder on the remote repository.
133 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 --migrate-fmd5-using-nametrans
141 Migrate FMD5 hashes from versions prior to 6.3.5.
142 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 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 --mbnames-prune
156 Remove dangling entries for removed accounts or if mbnames is not
157 enabled/used anymore.
158 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 It is possible to manually remove intermediate files in
168 <metadata>/mbnames/.
169 Notice this option honors --dry-run.
171
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 1. Synchronize more than one account.
180 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 Warning
187 enabling the maxsyncaccounts and maxconnections options is
188 deprecated since it’s known to have race conditions.
189 2. Use folderfilters.
191 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 3. The sqlite cache.
199 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 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 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 4. Use quick sync.
219 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 5. Turn off fsync.
229 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
236 By default, OfflineIMAP will connect using any method that openssl
237 supports, that is SSLv2, SSLv3, or TLSv1.
238 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 • Certificate checking
247 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 1. The server SSL certificate is validated by the CA Certificate.
260 2. The server host name matches the SSL certificate.
262 3. The server certificate is not past its expiration date.
264 The FAQ has an entry on how to create your own certificate and CA
266 certificate.
267 • StartTLS
269 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 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 DO NOT RELY ON STARTTLS AS A SAFE CONNECTION GUARANTEEING THE
284 AUTHENTICITY OF YOUR IMAP SERVER!
285
287 OfflineImap listens to the unix signals SIGUSR1, SIGUSR2, SIGTERM,
288 SIGINT, SIGHUP, SIGQUIT.
289 • 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 • 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 • 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 It may take up to 10 seconds, if autorefresh option is used.
307 More than one SIGTERM will behave like SIGQUIT.
309 • If sent SIGQUIT, dumps stack traces for all threads and tries to
311 dump process core.
312
314 • Deletions.
315 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 • The whole content of a folder is deleted but the folder
322 directory still exists.
323 • The parent directory of the folder was deleted.
325 • SSL3 write pending.
327 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 • IDLE support is incomplete and experimental. Bugs may be
336 encountered.
337 • No hook exists for "run after an IDLE response".
339 Email will show up, but may not be processed until the next
341 refresh cycle.
342 • nametrans may not be supported correctly.
344 • IMAP IDLE <→ IMAP IDLE doesn’t work yet.
346 • IDLE might stop syncing on a system suspend/resume.
348 • IDLE may only work "once" per refresh.
350 If you encounter this bug, please send a report to the list!
352 • Maildir support in Windows drive.
354 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 1. Enable file name character translation in windows registry (not
360 tested).
361 • http://support.microsoft.com/kb/289627
363 2. Use cygwin managed mount (not tested).
365 • not available anymore since cygwin 1.7
367 3. Use "maildir-windows-compatible = yes" account OfflineIMAP
369 configuration.
370 • 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 • Exclamation mark was chosen because of the note in
378 http://docs.python.org/library/mailbox.html
379 • If you have some messages already stored without this
381 option, you will have to re-sync them again
382 • OfflineIMAP confused after system suspend.
384 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 • OfflineIMAP confused when mails change while in a sync.
390 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 • Sharing a maildir with multiple IMAP servers.
396 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 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 `~/mail/Pro' as Maildir root for the ProGmail and
412 `~/mail/Personal' as root for the personal one.
413 If you then point your local mutt, or whatever MUA you use to
415 ‘~/mail/’ as root, it should still recognize all folders.
416 • Edge cases with maxage causing too many messages to be synced.
418 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 • Offlineimap hangs.
430 When having unexpected hangs it’s advised to set
432 ‘singlethreadperfolder’ to yes, especially when in IMAP/IMAP mode
433 (no maildir).
434 • Passwords in netrc.
436 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 • XOAUTH2
442 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 Sometimes, you might hit one of the following error:
449 • [imap]: xoauth2handler: response "{u’error': u’invalid_grant'}"
451 • oauth2handler got: {u’error': u’invalid_grant'}
453 In such case, we had reports that generating a new refresh token
455 from the same client ID and secret can help.
456 Google documentation on "invalid_grant".
458 When you try to use a refresh token, the following returns you an
460 invalid_grant error:
461 - Your server's clock is not in sync with network time protocol - NTP.
463 - The refresh token limit has been exceeded.
464 Token expiration.
466 It is possible that a granted token might no longer work. A token might stop
468 working for one of these reasons:
469 - 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 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 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 • "does not have message with UID" with Microsoft servers
487 `ERROR: IMAP server 'Server ### Remote' does not have a message with UID 'xxx'`
489 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
496 John Goerzen, Sebastian Spaetz, Eygene Ryabinkin, Nicolas Sebrecht.
497
499 offlineimapui(7), openssl(1), signal(7), sqlite3(1).
500 http://www.offlineimap.org
501 07/08/2023 OFFLINEIMAP(1)