هیچ فضایی را در عمل تغییر نمی‌دهد، بلکه بررسی و چاپ می‌کند که در صورت انجام همگام‌سازی چه اقداماتی صورت می‌گیرد. این گزینه دقیقاً مشخص نمی‌کند چه رخ خواهد داد؛ به عنوان مثال اگر نیاز به ایجاد یک پوشه باشد، صرفاً عبارت Would create folder X را چاپ می‌کند، نه اینکه چه تعداد و کدام نامه‌ها را منتقل خواهد کرد.

برای اشکال‌زدایی و گزارش باگ مفید است. در ترکیب با گزینه ‘-a’ برای محدود کردن خروجی به یک حساب منفرد استفاده شود. این حالت از انجام هرگونه همگام‌سازی واقعی جلوگیری کرده و پس از چاپ اطلاعات اشکال‌زدایی خارج می‌شود.

این گزینه متغیرهای فایل پیکربندی شامل maxsyncaccounts و تمامی maxconnections را به 1 (عدد یک) تنظیم می‌کند.

برنامه پوشه مشخص‌شده (DIR) را ایجاد خواهد کرد (این پوشه نباید از قبل وجود داشته باشد). در حین اجرا، اطلاعات تحلیل کارایی پایتون مربوط به هر ریسمان در profiledir ثبت می‌شود. لطفاً توجه داشته باشید: این گزینه فقط برای اشکال‌زدایی و بهینه‌سازی در نظر گرفته شده است و نباید استفاده شود مگر اینکه دلیل خاصی برای آن داشته باشید. این گزینه کارایی برنامه را به میزان چشمگیری کاهش می‌دهد، ممکن است قابلیت اطمینان را کم کند و می‌تواند حجم عظیمی از داده تولید نماید. این گزینه متضمن گزینه ‘-1’ نیز هست.

امکان تعیین یک حساب یا مجموعه‌ای از حساب‌های خاص را برای همگام‌سازی بدون نیاز به ویرایش فایل پیکربندی فراهم می‌کند.

این گزینه هنگامی کاربرد دارد که بخواهید یک اشکال را پیگیری کرده یا از آنچه در پشت صحنه می‌گذرد آگاه شوید. این گزینه به یک یا چند نوع دیباگ نیاز دارد که با کاما از هم جدا می‌شوند. این انواع مشخص می‌کنند چه مواردی دیباگ خواهند شد و تاکنون شامل گزینه‌های زیر هستند: "imap"، "thread"، "maildir" یا "ALL". گزینه imap اشکال‌زدایی جریان پروتکل IMAP و تجزیه آن را فعال می‌کند. توجه داشته باشید که خروجی ممکن است حاوی گذرواژه‌ها باشد، بنابراین پیش از ارسال آن برای دیگران حتماً آن‌ها را از خروجی اشکال‌زدایی پاک کنید. گزینه maildir اشکال‌زدایی عملیات خاص Maildir را فعال می‌کند. استفاده از هر گزینه اشکال‌زدایی (مگر اینکه شامل "thread" باشد) متضمن گزینه تک‌ریسمانی ‘-1’ است.

نام پوشه‌ها همان نام‌های ترجمه‌نشده در مخزن راه دور (remote) هستند. این گزینه خط فرمان، هرگونه تنظیمات folderfilter و folderincludes در فایل پیکربندی را بازنویسی می‌کند.

اگر "section" ذکر نشود، پیش‌فرض آن "general" خواهد بود. هرگونه زیرخط (_) در نام بخش با فاصله جایگزین می‌شود؛ به عنوان مثال، برای بازنویسی گزینه "autorefresh" در بخش "[Account Personal]" در فایل پیکربندی، می‌توان از ‘-k Account_Personal:autorefresh=30’ استفاده کرد. برای بازتعریف چندین گزینه، این گزینه را به تعداد لازم تکرار کنید.

نادیده گرفتن تنظیم autorefresh در فایل پیکربندی.

نادیده گرفتن به‌روزرسانی پرچم‌ها در سرورهای IMAP. اگر پرچمی در IMAP راه دور تغییر کند و ما نامه را به صورت محلی داشته باشیم، در اجرای سریع دست‌نخورده باقی می‌ماند. در صورت تنظیم بودن maxage، این گزینه نادیده گرفته می‌شود.

این گزینه مقدار پیش‌فرض مشخص‌شده در فایل پیکربندی را بازنویسی می‌کند. رابط کاربری مشخص‌شده با ‘-u’ اجباراً استفاده خواهد شد، حتی اگر بررسی‌ها نشان دهند قابل استفاده نیست. رابط‌های کاربری ممکن عبارتند از: quiet، basic، syslog، ttyui، blinkenlights، machineui.

برای کارکرد این قابلیت باید تنها یک حساب مشخص/پیکربندی شده باشد یا باید یک حساب را با -a تعیین کنید. نام پوشه باید با جداکننده‌های راه دور (احتمالاً /) به صورت UTF-8 در صورت فعال بودن utf8foldernames یا در غیر این صورت به صورت IMAP ارائه شود؛ مانند: "Remote/folder/name".

نحوه محاسبه درهم‌سازهای FMD5 در نسخه 6.3.5 تغییر کرد (اکنون از نام پوشه nametrans استفاده می‌کند) که باعث ایجاد یک پس‌رفت شد که ممکن است منجر به بارگذاری مجدد تمام پیام‌ها گردد. تلاش برای رفع این مشکل با محاسبه مقادیر صحیح FMD5 و تغییر نام پیام‌های متناظر انجام می‌شود.

از آنجا که بخش FMD5 نام فایل تغییر می‌کند، این امر ممکن است منجر به تداخل UIDها شود. اطمینان حاصل کنید که پیش از اجرای این رفع اشکال، یک نسخه پشتیبان مناسب از کَش و Maildir تهیه کرده و ابتدا نتایج را با فلگ ‘--dry-run’ بررسی کنید.

به صورت داخلی، offlineimap فایل‌های میانی mbnames را ایجاد می‌کند. هنگامی که mbnames فعال باشد، آن‌ها به طور خودکار اضافه می‌شوند. با این حال، غیرفعال کردن حساب‌ها به طوری که دیگر همگام‌سازی نشوند، لزوماً به این معنی نیست که باید از فایل ساخته‌شده توسط mbnames حذف شوند. لازم است هر بار که حساب‌ها حذف می‌شوند، offlineimap با این گزینه خط فرمان اجرا گردد. هنگام اجرا، هر حسابی که در گزینه پیکربندی accounts وجود نداشته باشد از فایل mbnames حذف می‌شود.

امکان حذف دستی فایل‌های میانی در <metadata>/mbnames/ وجود دارد.

توجه داشته باشید که این گزینه از --dry-run پیروی می‌کند.

به طور پیش‌فرض ما تنها از یک اتصال به سرور IMAP استفاده می‌کنیم. استفاده از ۲ یا حتی ۳ اتصال در اکثر موارد کارها را به میزان قابل توجهی تسریع می‌کند. به منظور همگام‌سازی همزمان بیش از یک حساب، اجرای یک نمونه از offlineimap را به ازای هر حساب در نظر بگیرید.

سریع‌ترین همگام‌سازی، همگام‌سازی‌ای است که بتواند برخی پوشه‌ها را نادیده بگیرد. من صندوق ورودی‌ام را در پوشه‌های ماهانه مرتب می‌کنم و هر پوشه‌ای را که بیش از ۲-۳ ماه قدمت دارد نادیده می‌گیرم؛ این کار باعث می‌شود در هر بار همگام‌سازی فقط کسری از نامه‌هایم را بررسی کنم. اگر هنوز این کار را نکرده‌اید، انجامش دهید :). بخش folderfilter در offlineimap.conf را ببینید.

ابزار OfflineImap وضعیت همگام‌سازی را کَش می‌کند تا بتواند به عنوان مثال تشخیص دهد که آیا نامه‌ای در هر یک از دو سمت اضافه یا حذف شده است یا خیر.

کَش وضعیت قدیمی یک فایل متنی ساده بود که برای هر پیام جدید (یا حتی پرچم تغییر یافته) کل فایل را در یک فایل موقت بازنویسی می‌کرد. اگر فایل‌های زیادی در یک پوشه وجود داشت، این موضوع ناگزیر باعث کندی سیستم می‌شد. آخرین کَش وضعیت بر پایه sqlite است. این کار فعالیت‌های دیسک را تا حد زیادی کاهش می‌دهد.

کَش وضعیت قدیمی با متن ساده دیگر پشتیبانی نمی‌شود، اما مهاجرت از یک نصب بسیار قدیمی با استفاده از کَش متن ساده همچنان پشتیبانی می‌شود. در این حالت، ممکن است بخواهید دایرکتوری کَش قدیمی در <metadata>/Account-<account>/LocalStatus را به صورت دستی حذف کنید (کَش sqlite در پوشه LocalStatus-sqlite قرار دارد). ابتدا اطمینان حاصل کنید که نسخه جدید offlineimap را برای تمام حساب‌های خود اجرا کرده‌اید تا کَش وضعیت مهاجرت داده شده باشد.

یک همگام‌سازی عادی تمامی پرچم‌ها و شناسه‌های یکتای (UID) همه نامه‌ها را در هر پوشه درخواست می‌کند که زمان زیادی می‌برد. یک همگام‌سازی سریع فقط تعداد پیام‌ها در یک پوشه را در سمت IMAP مقایسه می‌کند (اگرچه تغییرات پرچم در سمت Maildir را تشخیص خواهد داد). یک همگام‌سازی سریع در حساب نه‌چندان بزرگ من، به جای ۴۰ ثانیه، تنها ۷ ثانیه طول می‌کشد. برای مثال، می‌توانید یک اسکریپت کران (cron) اجرا کنید که روزی یک بار همگام‌سازی عادی انجام دهد و در فواصل زمانی، همگام‌سازی‌های سریع با ‘-q’ را تنها برای همگام‌سازی ‘-f INBOX’ اجرا نماید.

در بخش [general] می‌توانید fsync را به True یا False تنظیم کنید. اگر می‌خواهید ۱۱۰٪ ایمن عمل کنید و پیش از ادامه کار منتظر بمانید تا تمامی عملیات روی دیسک اعمال شوند، می‌توانید آن را به True تنظیم نمایید. اگر آن را روی False بگذارید، مقداری از این ایمنی را از دست داده و آن را با سرعت معاوضه می‌کنید.

متأسفانه، به طور پیش‌فرض ما گواهی سرور IMAP مبتنی بر TLS/SSL که به آن متصل می‌شویم را اعتبارسنجی نمی‌کنیم، بنابراین اتصال از طریق SSL هیچ تضمینی در برابر حملات مرد میانی (man-in-the-middle) ایجاد نمی‌کند. در حین اعتبارسنجی گواهی سرور، بررسی اثر انگشت (fingerprint) توصیه می‌شود. در حال حاضر تنها یک راه امن برای اطمینان از اتصال رمزگذاری‌شده به سرور صحیح وجود دارد: می‌توانید تنظیم sslcacertfile را در بخش مخزن فایل offlineimap.conf مشخص کنید که به فایلی اشاره دارد که (در میان موارد دیگر) حاوی یک گواهی CA در قالب PEM است که گواهی سرور شما را اعتبارسنجی می‌کند. در این حالت، ما موارد زیر را بررسی خواهیم کرد:

اگر حساب خود را طوری پیکربندی نکرده باشید که از طریق SSL متصل شود، در صورتی که سرور IMAP پشتیبانی کند، OfflineImap همچنان تلاش خواهد کرد اتصالی از طریق تابع STARTTLS برقرار کند.

هنگام استفاده از STARTTLS هیچ‌گونه بررسی گواهی یا اثر انگشت انجام نمی‌شود (کتابخانه زیربنایی imaplib هنوز از این قابلیت پشتیبانی نمی‌کند). این بدان معناست که شما در برابر شنود غیرفعال محافظت خواهید شد و آن‌ها نمی‌توانند گذرواژه یا محتوای ایمیل شما را ببینند. با این حال، این کار شما را در برابر حملات فعال محافظت نمی‌کند، مانند حملات مرد میانی که باعث می‌شوند به سرور اشتباه متصل شوید و آن سرور وانمود کند سرور ایمیل شماست.

برای یک اتصال امن که اصالت سرور IMAP شما را تضمین کند، به STARTTLS اتکا نکنید!

برخی از سرورهای غیراستاندارد IMAP پس از تکمیل دست‌تکانی STARTTLS، پاسخ CAPABILITY را ارسال نمی‌کنند، در حالی که در RFC 2595 الزامی شده است. به طور پیش‌فرض، OfflineIMAP در این شرایط با خطا متوقف می‌شود تا از ادامه کار بر روی یک کانال رمزگذاری‌شده بالقوه آسیب‌دیده جلوگیری کند.

تنظیم allow_nonstandard_capabilities = yes در بخش مخزن، یک راهکار پشتیبان به کار می‌گیرد: OfflineIMAP از قابلیت‌های اعلام‌شده پیش از STARTTLS مجدداً استفاده می‌کند و LOGINDISABLED را حذف می‌کند تا احراز هویت بتواند روی اتصال رمزشده (فرضی) ادامه یابد.

هشدار: این گزینه را تنها زمانی فعال کنید که مطمئن شده باشید TLS واقعاً به درستی برقرار شده است. اگر سرور STARTTLS را به درستی اجرا نکند، فعال کردن این گزینه می‌تواند باعث ارسال اطلاعات هویتی به صورت متن ساده شود.

پیش‌فرض: no.

در صورت استفاده از گزینه autorefresh، ممکن است تا ۱۰ ثانیه طول بکشد.

ارسال بیش از یک SIGTERM رفتاری مشابه با SIGQUIT خواهد داشت.

در حین اجرای عادی، حذف‌ها منتقل می‌شوند. برای جلوگیری از دست رفتن داده‌ها، حذف یک پوشه باعث می‌شود offlineimap مجدداً آن پوشه را همگام‌سازی کند. با این حال، انتقال حذف کل محتوای یک پوشه می‌تواند در دو حالت زیر رخ دهد:

کاربرانی که SSL را فعال می‌کنند ممکن است با خطای "SSL3 write pending" مواجه شوند. در این صورت، حساب(ها) از زمان بروز این باگ همگام‌نشده باقی می‌مانند. اجرای مجدد OfflineIMAP می‌تواند کمک کند. ما همچنان در حال کار بر روی این اشکال هستیم. دریافت وصله‌ها یا گزارش‌های دقیق باگ مورد استقبال است. لطفاً بررسی کنید که آخرین نسخه پایدار را اجرا می‌کنید و گزارشی همراه با گزارش کامل لاگ به فهرست ایمیل ما ارسال کنید.

قالب Maildir از نویسه دونقطه (:) در نام فایل‌های پیام استفاده می‌کند. با این حال، دونقطه در درایوهای ویندوز یک نویسه غیرمجاز است. چندین راهکار برای این وضعیت وجود دارد:

هنگام بازگشت از یک نشست تعلیق‌شده، اگر گزینه socktimeout تنظیم نشده باشد، OfflineIMAP سوکت(های) قطع‌شده را به درستی مدیریت نمی‌کند. باید این گزینه را با مقداری مانند 10 فعال کنید.

هنگامی که OfflineIMAP در حال همگام‌سازی است، برخی رویدادهایی که از زمان فراخوانی در سمت راه دور یا محلی رخ می‌دهند به درستی مدیریت نمی‌شوند. ابزار OfflineIMAP تغییرات ایجادشده در طول همگام‌سازی را ردیابی نخواهد کرد.

به طور کلی هشداری درباره ترکیب مخازن IMAP در یک ریشه Maildir یکسان وجود دارد. باید بسیار مراقب باشید که هرگز از یک پوشه maildir برای ۲ سرور IMAP استفاده نکنید. در بهترین حالت، مقدار MD5 پوشه متفاوت خواهد بود و در چرخه‌ای گرفتار می‌شوید که نامه‌ها را به نوبت در هر دو سرور (به صورت نامحدود!) بارگذاری می‌کند، زیرا تصور می‌کند نامه‌های جدیدی در Maildir محلی قرار داده‌اید. در بدترین حالت، مقدار MD5 یکسان است (محتمل) و شناسه‌های UID نامه‌ها همپوشانی دارند (این هم محتمل است!) و در همگام‌سازی برخی نامه‌ها ناموفق خواهد بود زیرا تصور می‌کند از قبل وجود دارند.

من برای جیمیل شخصی یک مخزن Maildir محلی جدید ایجاد می‌کنم و برای اطمینان از ریشه متفاوتی استفاده می‌کنم. به عنوان مثال می‌توانید از موارد زیر استفاده کنید:

`~/mail/Pro' به عنوان ریشه Maildir برای ProGmail و
`~/mail/Personal' به عنوان ریشه برای جیمیل شخصی.

اگر سپس mutt محلی یا هر برنامه MUA دیگری را که استفاده می‌کنید به ‘~/mail/’ به عنوان ریشه تنظیم کنید، همچنان باید تمامی پوشه‌ها را شناسایی کند.

تمام پیام‌های مربوط به حداکثر maxage روز پیش (+/- چند ساعت، بسته به مناطق زمانی) همگام‌سازی می‌شوند، اما مواردی وجود دارد که در آن‌ها پیام‌های قدیمی‌تر نیز ممکن است همگام‌سازی شوند. این زمانی اتفاق می‌افتد که UID یک پیام به طور قابل توجهی بالاتر از UID سایر پیام‌های با تاریخ مشابه باشد؛ برای مثال زمانی که پیام‌ها بدون اطلاع offlineimap به پوشه محلی اضافه می‌شوند که باعث تخصیص UID جدید به آن‌ها می‌گردد، یا زمانی که offlineimap برای اولین بار یک Maildir از قبل موجود را همگام‌سازی می‌کند. در حالت اخیر، ممکن است به نظر برسد که زیرمجموعه‌ای تصادفی و قابل توجه از پیام‌های قدیمی همگام‌سازی شده‌اند.

هنگام مواجهه با قفل شدن‌های غیرمنتظره، توصیه می‌شود ‘singlethreadperfolder’ را روی yes تنظیم کنید، به ویژه در حالت IMAP/IMAP (بدون maildir).

ابزار Offlineimap در صورتی که بیش از یک حساب در فایل netrc ذخیره شده باشد، نحوه بازیابی گذرواژه‌ها را نمی‌داند. پیوند زیر را ببینید: https://github.com/OfflineIMAP/offlineimap/issues/295

راه‌اندازی XOAUTH2 ممکن است کمی دشوار باشد. اطمینان حاصل کنید که راهنمای گام‌به‌گام در offlineimap.conf را دنبال کرده‌اید. باگ‌های شناخته‌شده در مورد Gmail در نشانی زیر پیگیری می‌شوند: https://github.com/OfflineIMAP/offlineimap/labels/Gmail

گاهی اوقات، ممکن است با یکی از خطاهای زیر مواجه شوید:

در چنین حالتی، گزارش‌هایی داشته‌ایم مبنی بر اینکه ایجاد یک توکن بازخوانی (refresh token) جدید از همان کلاینت‌آیدی و کلید مخفی می‌تواند کمک‌کننده باشد.

مستندات گوگل درباره "invalid_grant".

هنگامی که تلاش می‌کنید از یک توکن بازخوانی استفاده کنید، موارد زیر باعث خطای
invalid_grant می‌شوند:
  - ساعت سرور شما با پروتکل زمان شبکه (NTP) همگام نیست.
  - محدودیت توکن بازخوانی به پایان رسیده است.

انقضای توکن (Token expiration).

این امکان وجود دارد که یک توکن اعطا شده دیگر کار نکند. یک توکن ممکن است
به یکی از دلایل زیر متوقف شود:
  - کاربر دسترسی را لغو کرده باشد.
  - توکن به مدت شش ماه استفاده نشده باشد.
  - کاربر گذرواژه را تغییر داده باشد و توکن شامل دامنه‌های Gmail باشد.
  - حساب کاربری از تعداد معینی درخواست توکن فراتر رفته باشد.
در حال حاضر محدودیت ۵۰ توکن بازخوانی به ازای هر حساب کاربری در هر کلاینت وجود دارد. اگر
محدودیت تکمیل شود، ایجاد یک توکن جدید به طور خودکار قدیمی‌ترین توکن را بدون
هشدار باطل می‌کند. این محدودیت برای حساب‌های سرویس اعمال نمی‌شود.

برای اطلاعات بیشتر ببینید: https://developers.google.com/analytics/devguides/config/mgmt/v3/authorization و https://developers.google.com/identity/protocols/OAuth2#expiration

`ERROR: IMAP server 'Server ### Remote' does not have a message with UID 'xxx'`

سرورهای IMAP مایکروسافت با استانداردهای RFC سازگار نیستند. در حال حاضر لازم است برخی از پوشه‌های دارای اشکال با folderfilter فیلتر شوند. برای فهرست دقیق ببینید: http://www.offlineimap.org/doc/FAQ.html#exchange-and-office365

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

offlineimapui(7), openssl(1), signal(7), sqlite3(1).
http://www.offlineimap.org