mbsync(1) User Commands mbsync(1)

mbsync - همگام‌سازی صندوق‌های پستی IMAP4 و Maildir

mbsync [options ...] {{channel[:box[{,|\n}...]]|group} ...|-a}
mbsync --list-stores [options ...] [store ...]

برنامهٔ mbsync یک ابزار خط فرمانی برای همگام‌سازی صندوق‌های پستی است؛ در حال حاضر صندوق‌های پستی Maildir و IMAP4 پشتیبانی می‌شوند. پیام‌های جدید، پیام‌های حذف‌شده و تغییرات پرچم‌ها (flags) را می‌توان در هر دو جهت منتقل کرد؛ مجموعه عملیات را می‌توان با دقتی بالا و تفکیک‌شده انتخاب نمود.
همگام‌سازی بر اساس شناسه‌های یکتای پیام (UIDها) انجام می‌شود، بنابراین هیچ تداخلی در شناسایی رخ نخواهد داد (برخلاف برخی دیگر از ابزارهای همگام‌ساز ایمیل). از سوی دیگر، mbsync در برابر تغییرات اعتبار UID (شناسه UID validity) حساس است (اما اگر این تغییر بی‌اساس باشد، به‌خوبی بازیابی خواهد شد). وضعیت همگام‌سازی در یک فایل متنی محلی به ازای هر جفت صندوق پستی نگهداری می‌شود؛ این فایل‌ها در برابر اجرای هم‌زمان فرایندهای mbsync محافظت شده‌اند. صندوق‌های پستی را می‌توان در حین اجرای mbsync با اطمینان تغییر داد (برای یک استثنای جزئی، به بخش INHERENT PROBLEMS در ادامه مراجعه کنید). امکان نگهداری چندین رونوشت از هر صندوق پستی وجود دارد.

خواندن پیکربندی از file. به‌طور پیش‌فرض، پیکربندی از مسیر $XDG_CONFIG_HOME/isyncrc خوانده می‌شود، و اگر آن فایل وجود نداشته باشد، مسیر ~/.mbsyncrc بررسی می‌شود. در صورت تنظیم نشدن $XDG_CONFIG_HOME، مقدار پیش‌فرض آن ~/.config خواهد بود.
انتخاب تمام Channelهای پیکربندی‌شده. هرگونه تعیین Channel/Group در خط فرمان نادیده گرفته می‌شود.
هیچ‌چیز همگام‌سازی نشود، بلکه تنها فهرستی از تمام صندوق‌های پستی در Channelهای انتخاب‌شده نمایش داده شده و برنامه خارج شود.
هیچ‌چیز همگام‌سازی نشود، بلکه تمام صندوق‌های پستی موجود در Storeهای انتخاب‌شده فهرست شده و برنامه خارج شود. اگر هیچ Storeی مشخص نشده باشد، تمام موارد پیکربندی‌شده فهرست می‌شوند. این‌ها محتوای خام Store هستند که با Patterns هیچ Channelی فیلتر نشده‌اند. این گزینه می‌تواند برای اعتبارسنجی پیکربندی هر Store استفاده شود.
بازنویسی گزینه‌های Create مشخص‌شده در فایل پیکربندی. در ادامه را ببینید.
بازنویسی گزینه‌های Remove مشخص‌شده در فایل پیکربندی. در ادامه را ببینید.
بازنویسی گزینه‌های Expunge مشخص‌شده در فایل پیکربندی. در ادامه را ببینید.
{-n|-o|-u|-g|-f|-0|-F}, {--new|--old|--upgrade|--gone|--flags|--noop|--full}
{-L|-H}[n][o][u][g][f], {--pull|--push}[-new|-old|-upgrade|-gone|-flags]
بازنویسی گزینه‌های Sync مشخص‌شده در فایل پیکربندی. در ادامه را ببینید.
نمایش خلاصه‌ای از گزینه‌های خط فرمان.
نمایش اطلاعات نگارش.
ورود به حالت شبیه‌سازی: وضعیت Channel بررسی شده و تمام عملیات لازم تعیین می‌شوند، اما در عمل هیچ تغییری نه در صندوق‌های پستی و نه در فایل‌های وضعیت اعمال نخواهد شد.
بازگرداندن یک کد خروج گسترش‌یافته: در صورتی که هرگونه تغییری به ترتیب در سمت far یا near اعمال شده باشد، ۳۲ یا ۶۴ به کد خروج اضافه می‌شود؛ این دو مانعة‌الجمع نیستند، بنابراین اگر تغییرات هم push و هم pull شده باشند، کد خروج ممکن است ۹۶ باشد. ممکن است هم‌زمان خطایی نیز گزارش شود؛ به عنوان مثال اگر برخی تغییرات با موفقیت pull شده باشند ولی تغییرات دیگر با شکست مواجه شوند، کد ممکن است ۶۵ باشد.
فعال‌سازی حالت پرگو (verbose)، که رویدادهای در حال وقوع را نمایش می‌دهد.
فعال‌سازی دسته‌بندی‌های اشکال‌زدایی:
C, crash - استفاده از مدیر خرابی توکار (built-in crash handler)
d, driver - چاپ فراخوانی‌های درایور (فقط فراداده)
D, driver-all - چاپ فراخوانی‌های درایور (شامل پیام‌ها)
m, maildir - چاپ اطلاعات اشکال‌زدایی maildir
M, main - چاپ اطلاعات اشکال‌زدایی main
n, net - چاپ ترافیک شبکه (فقط پروتکل)
N, net-all - چاپ ترافیک شبکه (شامل محتوای داده‌ها/payloads)
s, sync - چاپ اطلاعات اشکال‌زدایی همگام‌سازی
تمام دسته‌ها به‌جز crash حالت verbose را به‌طور ضمنی فعال می‌کنند. در صورت عدم مشخص کردن دسته‌ها، تمام دسته‌ها به‌جز net-all فعال خواهند شد.
جلوگیری از نمایش شمارنده‌های پیشرفت (اگر خروجی استاندارد یک TTY نباشد، یا هر یک از دسته‌های اشکال‌زدایی فعال باشند، این حالت ضمنی است)، اعلان‌ها و خلاصه. در صورت تعیین این گزینه برای دو بار، پیام‌های هشدار نیز نمایش داده نخواهند شد. فایل پیکربندی الزامی است؛ mbsync بدون آن اجرا نخواهد شد. خطوطی که با علامت هش (#) آغاز می‌شوند توضیح بوده و به‌طور کامل نادیده گرفته می‌شوند. موارد پیکربندی کلمات کلیدی هستند که در ادامهٔ آن‌ها یک یا چند آرگومان می‌آید؛ آرگومان‌های حاوی فاصله‌نما باید در دو گیومه (") محصور شوند، و خود گیومه‌ها و بک‌اسلش‌های (\) صریح باید با بک‌اسلش گریز (escape) داده شوند. تمامی کلمات کلیدی (از جمله مواردی که به‌عنوان آرگومان استفاده می‌شوند) به حروف بزرگ و کوچک حساس نیستند. بسط دایرکتوری خانگی به سبک Bash با استفاده از علامت مد (~) در تمامی گزینه‌هایی که نمایانگر مسیرهای محلی هستند پشتیبانی می‌شود. نقطه مرجع برای مسیرهای محلی نسبی، دایرکتوریِ حاوی فایل پیکربندی است. چند گزینهٔ سراسری وجود دارد؛ سایر گزینه‌ها به بخش‌های مشخصی اعمال می‌شوند. بخش‌ها با یک کلمه کلیدی آغازگرِ بخش شروع شده و با یک خط خالی یا پایان فایل خاتمه می‌یابند. هر بخش شیئی را با یک شناسهٔ یکتا در آن کلاس شیء تعریف می‌کند.

دو کلاس شیء پایه وجود دارد: Stores و Channels. یک Store مجموعه‌ای از صندوق‌های پستی را تعریف می‌کند؛ اساساً یک پوشه، چه محلی یا از راه دور. یک Channel دو Store را به هم متصل کرده و شیوهٔ همگام‌سازی آن دو را شرح می‌دهد.
دو کلاس شیء کمکی وجود دارد: Accounts و Groups. یک Account بخش اتصال Storeهای شبکه را شرح می‌دهد تا پیکربندی‌های کارساز بتواند میان چندین Store به اشتراک گذاشته شود. یک Group چندین Channel را تجمیع می‌کند تا از تایپ مجدد در خط فرمان صرفه‌جویی شود.

مکان‌های فایل‌سیستمی (به‌ویژه Path و Inbox) از جداکننده‌های مسیر درونی Store استفاده می‌کنند که ممکن است اسلش، نقطه و غیره یا حتی ترکیبی از آن‌ها باشد.
در مقابل، نام‌های صندوق پستی همواره از جداکننده‌های مسیر متعارف که همان اسلش‌های رو به جلو به سبک یونیکس هستند استفاده می‌کنند.

این گزینه‌ها می‌توانند در تمام انواع پشتیبانی‌شدهٔ Store استفاده شوند.
اصطلاح «Store مقابل» (opposite Store) به Store دیگر درون یک Channel اشاره دارد.
صندوق پستی ویژهٔ INBOX در هر Store وجود دارد؛ مکان فیزیکی آن در فایل‌سیستم وابسته به نوع Store است.

مکان Store در فایل‌سیستم (کارساز). اگر این یک مسیر مطلق نباشد، نقطه مرجع وابسته به نوع Store خواهد بود. این رشته به ابتدای نام‌های صندوق پستیِ مورد خطاب در این Store اضافه می‌شود، اما بخشی از آن‌ها به شمار نمی‌آید؛ این موضوع برای Patterns و Create در بخش Channels اهمیت دارد. توجه داشته باشید که اگر می‌خواهید یک دایرکتوری کامل را مشخص کنید، باید یک اسلش به انتهای آن بیافزایید. (پیش‌فرض: none)
برای پیام‌های بزرگ‌تر از size تنها یک پیام جای‌نگهدار کوچک به این Store منتقل خواهد شد. این ویژگی برای جلوگیری از بارگیری پیام‌های دارای پیوست‌های حجیم مفید است، مگر اینکه واقعاً به آن‌ها نیاز باشد. برای ارتقای جای‌نگهدار به پیام کامل، باید روی پیام نشان (flag) زده شود و عملیات Upgrade اجرا گردد. هشدارها: تعیین محدودیت اندازه روی یک Store که هرگز آن را مستقیماً نمی‌خوانید (که معمولاً در مورد کارسازها صدق می‌کند) توصیه نمی‌شود، زیرا ممکن است هرگز متوجه نشوید که پیام‌های مربوطه به آن منتقل نشده‌اند. همچنین از آنجا که از نشانه‌گذاری برای درخواست ارتقا استفاده می‌شود، تغییرات در وضعیت نشان پیام تا زمان ارتقای جای‌نگهدار در هیچ سمتی منتقل نخواهد شد.
می‌توان K و M را به اندازه الحاق کرد تا به‌ترتیب کیبی‌بایت و مبی‌بایت را به جای بایت مشخص کنند. B پذیرفته می‌شود اما اضافی است. اگر size برابر با 0 باشد، حداکثر اندازه پیام unlimited (نامحدود) خواهد بود. (پیش‌فرض: 0)
یک صندوق پستی مجازی (نسبت به Path) ایجاد می‌کند که نام مستعاری برای INBOX است. این مورد همراه با Patterns در بخش Channels کاربرد دارد، هرچند با وجود یک سمت نزدیک از نوع Maildir، احتمالاً ترجیح می‌دهید Inbox را درون Path قرار دهید. این صندوق پستی مجازی از زیرپوشه‌ها پشتیبانی نمی‌کند.
سلسله‌مراتب را درون این Store با جایگزین کردن جداکنندهٔ سلسله‌مراتب متعارف / با delim هموار (تخت) می‌کند. این گزینه زمانی می‌تواند مفید باشد که MUA استفاده‌شده برای دسترسی به Store، مدیریت چندان مطلوبی روی صندوق‌های پستی سلسله‌مراتبی نداشته باشد، همان‌طور که در مورد Mutt این‌گونه است. یک انتخاب رایج برای جداکننده، . است.
توجه داشته باشید که زیرپوشه‌های هموارشدهٔ INBOX همواره در زیر Path قرار می‌گیرند، از جمله پیشوند «INBOXdelim».
صندوق پستی‌ای (نسبت به Path) را مشخص می‌کند تا پیام‌های حذف‌شده پیش از پاکسازی کامل (expunging) در آن کپی شوند. بخش‌های RECOMMENDATIONS و INHERENT PROBLEMS را در ادامه ببینید. (پیش‌فرض: none)
هنگام انتقال به زباله‌دان، فقط پیام‌هایی را کپی می‌کند که هنوز منتقل نشده‌اند. این موضوع زمانی منطقی است که Store مقابل نیز دارای یک Trash باشد (همراه با TrashNewOnly no). (پیش‌فرض: no)
هنگام پاکسازی در Store مقابل، پیام‌هایی را که هنوز منتقل نشده‌اند به Trash این Store کپی می‌کند. هنگام استفاده از این گزینه، Store مقابل اصلاً نیازی به یک Trash مجزا ندارد، در حالی که همه پیام‌ها بایگانی می‌شوند. (پیش‌فرض: no)

نقطه مرجع برای Pathهای نسبی، دایرکتوریِ حاوی فایل پیکربندی است.

از آنجا که mbsync به UIDها نیاز دارد، اما هیچ طرح ذخیره‌سازی استانداردی برای UID در Maildir وجود ندارد، mbsync از دو طرح پشتیبانی می‌کند که هرکدام مزایا و معایب خود را دارند.
طرح native از آخرین وصله‌های Maildir برای c-client برگرفته شده و بنابراین با pine سازگار است. اعتبار UID در فایلی به نام .uidvalidity ذخیره می‌شود؛ UIDها در نام فایل پیام‌ها کدگذاری می‌شوند.
طرح alternative بر اساس نگاشت UID مورد استفاده در نسخه‌های 0.8 و 0.9.x نرم‌افزار isync است. بخش‌های تغییرناپذیر نام فایل پیام‌ها به‌عنوان کلیدهایی در یک پایگاه‌داده Berkeley به نام .isyncuidmap.db استفاده می‌شوند که اعتبار UID را نیز نگهداری می‌کند.
طرح native سریع‌تر است، از نظر فضا بهینه‌تر بوده، مستقل از ترتیب بایت‌ها (endianness) و «خوانا برای انسان» است، اما اگر پیامی از صندوق پستی دیگری بدون دریافت نام فایل جدید کپی شود، دچار اختلال خواهد شد؛ این امر دیر یا زود منجر به UIDهای تکراری می‌شود که به نوبهٔ خود باعث تغییر در اعتبار UID شده و موجب شکست در همگام‌سازی می‌گردد. طرح alternative زمانی با شکست مواجه می‌شود که یک MUA نام فایل پیام را در بخشی تغییر دهد که mbsync آن را تغییرناپذیر در نظر می‌گیرد؛ این اتفاق به‌صورت حذف پیام و ثبت یک پیام جدید تفسیر خواهد شد که ترافیک غیرضروری ایجاد می‌کند.
مشخص شده است که Mutt با هر دو طرح به‌خوبی کار می‌کند.
از mdconvert برای تبدیل صندوق‌های پستی از یک طرح به طرح دیگر استفاده کنید.

مخزن Maildir با عنوان name را تعریف می‌کند و بخشی را برای پارامترهای آن می‌گشاید.
استفاده از طرح ذخیره‌سازی UID به شیوهٔ alternative برای صندوق‌های پستی در این Store. این گزینه روی صندوق‌های پستی که از پیش دارای یک طرح ذخیره‌سازی UID هستند تأثیری نمی‌گذارد؛ برای تغییر آن از mdconvert استفاده کنید. بخش RECOMMENDATIONS را در ادامه ببینید. (پیش‌فرض: no)
مکان INBOX. این مقدار نسبت به Path نیست، اما قرار دادن INBOX در داخل Path مجاز است. (پیش‌فرض: ~/Maildir)
نویسه‌ای که برای جداسازی فیلد اطلاعات (info) از نام پایهٔ یک پیام استفاده می‌شود. استاندارد Maildir این نویسه را دو نقطه تعریف می‌کند، اما این با فایل‌سیستم‌های DOS/Windows ناسازگار است. (پیش‌فرض: مقدارِ FieldDelimiter)
سبک نام‌گذاری پوشه روی دیسک برای صندوق‌های پستی سلسله‌مراتبی. این گزینه هنگام استفاده از Flatten هیچ تأثیری ندارد.
صندوق‌های پستی با مسیرهای متعارف top/sub/subsub و INBOX/sub/subsub را در نظر بگیرید؛ این سبک‌ها مسیرهای روی دیسک زیر را به دست می‌دهند:
Verbatim - Path/top/sub/subsub و Inbox/sub/subsub (این همان سبکی است که احتمالاً مایل به استفاده از آن هستید)
Maildir++ - Inbox/.top.sub.subsub و Inbox/..sub.subsub (این سبک با Courier و Dovecot سازگار است - اما توجه داشته باشید که قالب فرادادهٔ صندوق پستی سازگار نیست). توجه داشته باشید که تلاش‌ها برای تعیین Path در این حالت رد می‌شود.
Legacy - Path/top/.sub/.subsub و Inbox/.sub/.subsub (این سبک قدیمی mbsync است)
(پیش‌فرض: تنظیم‌نشده؛ هنگام مواجهه با زیرپوشه‌ها خطا خواهد داد)
حساب IMAP4 با نام name را تعریف می‌کند و بخشی را برای پارامترهای آن باز می‌نماید.
Host host
نام DNS یا نشانی IP کارساز IMAP را مشخص می‌کند.
در صورت استفاده از Tunnel، این تنظیم تنها در صورتی لازم است که TLSType برابر با None نبوده و از CertificateFile استفاده نشده باشد؛ در این حالت، نام میزبان برای اعتبارسنجی موضوع (subject) گواهی به کار می‌رود.
شماره درگاه TCP کارساز IMAP را مشخص می‌کند. (پیش‌فرض: 143 برای IMAP، و 993 برای IMAPS)
اگر از Tunnel استفاده شود، این تنظیم نادیده گرفته می‌شود.
مهلت زمانی اتصال و انتقال داده را برای کارساز IMAP بر حسب ثانیه مشخص می‌کند. مقدار صفر به معنی نامحدود است. (پیش‌فرض: 20)
نام کاربری ورود به کارساز IMAP را مشخص می‌کند.
به جای تعیین مستقیم کاربر، یک دستور شل را برای دریافت نام کاربر مشخص می‌کند. این ویژگی به شما اجازه می‌دهد دریافت نام‌های کاربری را اسکریپت‌نویسی کنید.
دستور باید دقیقاً یک خط در stdout تولید کند؛ نویسه خط جدید پایانی اختیاری است. پیشوند + را به دستور اضافه کنید تا نشان دهد که خروجی TTY تولید می‌کند (مانند یک اعلان ورودی)؛ عدم انجام این کار صرفاً خروجی نامرتب‌تری ایجاد می‌کند. به یاد داشته باشید که گیومه‌ها و بک‌اسلش‌های تعبیه‌شده در دستور را با بک‌اسلش گریزدهی (escape) کنید.
گذرواژه username را در کارساز IMAP مشخص می‌کند. توجه داشته باشید که این گزینه الزامی نیست. اگر نه گذرواژه و نه دستور گذرواژه در فایل پیکربندی مشخص نشده باشد، mbsync گذرواژه را از شما خواهد پرسید.
به جای تعیین مستقیم گذرواژه، یک دستور شل را برای دریافت آن مشخص می‌کند. این ویژگی به شما اجازه می‌دهد از فایل‌ها و عامل‌های گذرواژه (agents) استفاده کنید.
برای جزئیات بیشتر به UserCmd در بالا مراجعه کنید.
آیا از macOS Keychain برای دریافت گذرواژه استفاده شود یا خیر. (پیش‌فرض: no)
مورد لازم در keychain را می‌توان به این صورت ایجاد کرد:
security add-internet-password -r imap -s Host -a User -w password [ -T /path/to/mbsync ]
دستوری را برای اجرا جهت برقراری اتصال به جای باز کردن سوکت TCP مشخص می‌کند. این ویژگی برای مثال به شما اجازه می‌دهد یک نشست IMAP را روی یک تونل SSH اجرا کنید.
فهرست سازوکارهای احراز هویت قابل قبول. علاوه بر سازوکارهای فهرست‌شده در رجیستری SASL (پیوند زیر)، سازوکار قدیمی LOGIN مربوط به IMAP نیز شناخته شده است. نویسه عام * نشان‌دهنده تمامی سازوکارهایی است که برای تنظیمات فعلی TLSType به اندازه کافی امن تلقی می‌شوند. سازوکاری که در عمل استفاده می‌شود، امن‌ترین گزینه حاصل از اشتراک این فهرست، فهرست ارائه‌شده توسط کارساز، و ماژول‌های SASL نصب‌شده است. (پیش‌فرض: *)
روش امنیت/رمزنگاری اتصال را انتخاب می‌کند:
None - بدون امنیت. این مقدار در صورت تنظیم بودن Tunnel پیش‌فرض است، زیرا تونل‌ها معمولاً امن هستند.
STARTTLS - امنیت از طریق افزونه STARTTLS پس از اتصال به درگاه معمولی 143 کارساز IMAP برقرار می‌شود. اکثر کارسازها از این روش پشتیبانی می‌کنند، بنابراین حالت پیش‌فرض است (مگر آنکه از یک تونل استفاده شود).
IMAPS - امنیت با آغاز مذاکره TLS بلافاصله پس از اتصال به درگاه امن 993 کارساز IMAP برقرار می‌شود.
نسخه‌های مشخص‌شده TLS را به/از مجموعه‌ی انتخاب‌های قابل قبول اضافه/حذف می‌کند. تنها در صورتی از نسخه‌های قدیمی استفاده کنید که کارساز با نسخه‌های جدیدتر مشکل داشته باشد. توجه داشته باشید که نسخه‌های جدید به محض پشتیبانی توسط OpenSSL، حتی اگر mbsync هنوز آن‌ها را نشناسد، به صورت خودکار فعال می‌شوند. (پیش‌فرض: تمام نسخه‌ها از 1.2 به بالا).
مشخص می‌کند که آیا مخزن پیش‌فرض گواهی‌های CA (مرجع صدور گواهی) سیستم باید برای اعتبارسنجی زنجیره‌های اعتماد گواهی استفاده شود یا خیر. اگر می‌خواهید تنها به گواهی‌های دست‌چین‌شده اعتماد کنید، این گزینه را غیرفعال کنید. (پیش‌فرض: yes)
فایلی حاوی گواهی‌های X.509 اضافی که برای اعتبارسنجی هویت‌های کارساز به کار می‌رود. این فایل ممکن است شامل دو نوع گواهی باشد:
این گواهی‌ها تنها با خودِ گواهی دریافت شده از کارساز مطابقت داده می‌شوند. آن‌ها صرف‌نظر از معتبر بودن، همیشه مورد اعتماد هستند. یک مورد کاربرد معمول، اجبار به پذیرش یک گواهی منقضی‌شده است.
این گواهی‌ها را می‌توان با استفاده از ابزار mbsync-get-cert دریافت کرد؛ پیش از اعتماد به آن‌ها، حتماً اثر انگشتشان (fingerprint) را بررسی کنید، یا آن‌ها را به طور امن از شبکه کارساز منتقل نمایید (در صورتی که بتوان به شبکه فراتر از خود کارساز اعتماد کرد).
این گواهی‌ها هنگام ساخت زنجیره گواهی برای گواهی کارساز دریافت‌شده، به عنوان لنگرهای اعتماد (trust anchors) استفاده می‌شوند. بسته به تنظیم SystemCertificates، از آن‌ها برای جایگزینی یا تقدم بر مخزن اعتماد سیستم استفاده می‌شود؛ مشخص کردن خود مخزن اعتماد سیستم در اینجا لازم نیست و توصیه نمی‌شود. زنجیره‌های اعتماد به طور کامل اعتبارسنجی می‌شوند.
فایل حاوی گواهی کلاینت برای ارسال به کارساز. ClientKey نیز باید مشخص شود.
توجه داشته باشید که اعتبارسنجی گواهی کلاینت معمولاً الزامی نیست، بنابراین بعید است به این گزینه نیاز پیدا کنید.
فایل حاوی کلید خصوصی متناظر با ClientCertificate.
رشته رمزهای (cipher string) مربوط به OpenSSL را برای اتصال‌های ایمن‌شده با TLS تا نسخه 1.2 (به جز نسخه 1.3 و بالاتر) مشخص می‌کند. قالب آن در ciphers(1) شرح داده شده است. (پیش‌فرض: خالی، که بیانگر سیاست سراسری سیستم است).
حداکثر تعداد دستورهای IMAP که می‌توانند به طور هم‌زمان در جریان باشند. تنظیم این مقدار روی 1 قابلیت خط لوله (pipelining) را غیرفعال می‌کند. این گزینه بیشتر جنبه رفع اشکال دارد، اما ممکن است برای محدود کردن میانگین مصرف پهنای باند نیز به کار رود (در صورتی که اتصال بسیار سریعی داشته باشید ممکن است GMail به این گزینه نیاز داشته باشد)، یا برای مدارا با کارسازهای ناپایداری همچون M$ Exchange استفاده شود. (پیش‌فرض: unlimited)
استفاده از افزونه‌های خاص IMAP را غیرفعال می‌کند. از این گزینه می‌توان برای دور زدن باگ‌های موجود در کارسازها (و احتمالاً خود mbsync) استفاده کرد. (پیش‌فرض: خالی) نقطهٔ مرجع برای Pathهای نسبی هر آن چیزی است که کارساز (server) ترجیح می‌دهد؛ احتمالاً $HOME یا $HOME/Mail کاربر بر روی آن کارساز است. مکان INBOX نیز بر عهدهٔ کارساز بوده و معمولاً بی‌اهمیت است.
مخزن IMAP4 با نام name را تعریف کرده و بخشی را برای پارامترهای آن باز می‌کند.
مشخص می‌کند کدام account از IMAP4 استفاده شود. به‌جای تعریف یک Account و ارجاع به آن در اینجا، می‌توان تمام گزینه‌های Account را مستقیماً در بخش مربوط به Store مشخص کرد - این کار در صورتی منطقی است که یک Account به هر حال فقط برای یک Store استفاده شود.
انتخاب می‌کند که آیا اولین NAMESPACE «شخصی» کارساز باید به عنوان پیشوند به نام صندوق‌های پستی اضافه شود یا خیر. غیرفعال کردن این گزینه برای برخی کارسازهای خراب IMAP منطقی است. اگر یک Path مشخص شده باشد، این گزینه بی‌معنی خواهد بود. (پیش‌فرض: yes)
جداکنندهٔ سلسله‌مراتب کارساز را مشخص می‌کند. (پیش‌فرض: برگرفته از اولین NAMESPACE «شخصی» کارساز)
از این گزینه برای بازتفسیر سلسله‌مراتب سوءاستفاده نکنید. به‌جای آن از Flatten استفاده کنید.
انتخاب می‌کند که آیا تنها صندوق‌های پستی که در کارساز IMAP مشترک (subscribed) شده‌اند همگام‌سازی شوند یا خیر. از نظر فنی، در صورت تنظیم این گزینه، mbsync از دستور IMAP به نام LSUB به‌جای LIST برای یافتن صندوق‌های پستی در این Store استفاده خواهد کرد. این گزینه فقط در ترکیب با Patterns معنا دارد. (پیش‌فرض: no)

کانال name را تعریف کرده و بخشی را برای پارامترهای آن باز می‌کند.
{Far|Near} :store:[mailbox]
مخزن سمت دور (far) یا نزدیک (near) را برای اتصال توسط این Channel مشخص می‌کند. اگر Patterns مشخص شده باشد، mailbox به عنوان پیشوندی تفسیر می‌شود که با الگوها مطابقت داده نمی‌شود، و بازنویسی‌های فهرست صندوق‌های پستی بر آن تأثیری ندارد. در غیر این صورت، اگر mailbox حذف شود، INBOX فرض می‌شود.
به‌جای همگام‌سازی فقط یک جفت صندوق پستی، تمام صندوق‌های پستی را که با pattern(ها) مطابقت دارند همگام می‌کند. نام‌های صندوق پستی در سمت‌های دور و نزدیک یکسان است. الگوها از نوع الگوهای IMAP4 هستند، یعنی * با همه‌چیز مطابقت دارد و % با همه‌چیز تا جداکنندهٔ سلسله‌مراتب بعدی تطابق می‌یابد. قرار دادن ! قبل از یک الگو، آن را به یک استثنا (مستثنی‌سازی) تبدیل می‌کند. می‌توان چندین الگو را مشخص کرد (یا با ارائهٔ چندین آرگومان یا با استفاده مکرر از Pattern)؛ تطابق‌های بعدی اولویت دارند.
توجه داشته باشید که INBOX با نویسه‌های عام (wildcards) مطابقت داده نمی‌شود، مگر اینکه در زیر Path قرار داشته باشد.
فهرست صندوق‌های پستی انتخاب‌شده توسط Patterns می‌تواند توسط یک فهرست صندوق پستی در یک ارجاع Channel (یک مشخصهٔ Group یا در خط فرمان) بازنویسی (override) شود.
مثال: "Patterns % !Trash"
مشابه گزینهٔ هم‌نام در بخش Stores است، اما به‌طور یکسان بر Far و Near اعمال می‌شود. توجه داشته باشید که این گزینه عملاً Stores را تغییر می‌دهد، بنابراین دقت کنید اگر از Stores در چندین Channel استفاده می‌کنید، تنظیمات متناقض ارائه ندهید.
حداکثر تعداد پیام‌ها برای نگه‌داری در هر صندوق پستی سمت نزدیک (near) را تعیین می‌کند. این قابلیت برای صندوق‌هایی مفید است که در آن‌ها یک بایگانی کامل روی کارساز نگه‌داری می‌کنید، اما می‌خواهید فقط آخرین پیام‌ها را آینه‌سازی کنید (برای نمونه، برای فهرست‌های پستی). پیام‌هایی که زودتر از همه وارد صندوق پستی شده‌اند (مستقل از تاریخ واقعی پیام) ابتدا حذف خواهند شد. پیام‌هایی که پرچم‌دار هستند (علامت‌گذاری‌شده به عنوان مهم) و (به‌طور پیش‌فرض) پیام‌های خوانده‌نشده به‌صورت خودکار حذف نخواهند شد. اگر count برابر 0 باشد، حداکثر تعداد پیام‌ها نامحدود (unlimited) خواهد بود (پیش‌فرض سراسری: 0).
انتخاب می‌کند که آیا پیام‌های خوانده‌نشده تحت تأثیر MaxMessages قرار گیرند یا خیر. به‌طور معمول، پیام‌های خوانده‌نشده مهم تلقی می‌شوند و بنابراین هرگز منقضی نمی‌شوند. این امر تضمین می‌کند که حتی پس از یک غیبت طولانی، هیچ پیام جدیدی را از دست ندهید. با این حال، اگر بایگانی شما بر حسب طراحی شامل مقادیر زیادی پیام خوانده‌نشده باشد، مهم در نظر گرفتن آن‌ها عملاً هدف MaxMessages را خنثی می‌کند. در این حالت لازم است این گزینه را فعال کنید. (پیش‌فرض سراسری: no).
مشخص می‌کند هنگامی که MaxMessages پیکربندی شده است، پیام‌ها در کدام سمت منقضی شوند. (پیش‌فرض سراسری: Near).
عملیات(های) همگام‌سازی برای اجرا را انتخاب می‌کند:
Pull - انتشار تغییرات از سمت دور به سمت نزدیک.
Push - انتشار تغییرات از سمت نزدیک به سمت دور.
New - انتشار پیام‌های تازه ظاهر شده.
Old - انتشار پیام‌هایی که قبلاً نادیده گرفته شده، ناموفق بوده یا منقضی شده‌اند. این عمل هزینهٔ (نسبتاً) بالایی دارد و ممکن است مکرراً پیام خطا ایجاد کند، بنابراین همیشه باید به‌صورت صریح مشخص شود.
Upgrade - ارتقای جانگهدارها (placeholders) به پیام‌های کامل. فقط با یک MaxSize پیکربندی‌شده مفید است.
Gone - انتشار ناپدید شدن پیام‌ها. این عمل فقط برای پیام‌هایی اعمال می‌شود که واقعاً ناپدید شده‌اند، یعنی پاک‌سازی (expunged) شده‌اند. پیام‌های تحت تأثیر در Store مقابل فقط به عنوان حذف‌شده علامت‌گذاری می‌شوند، یعنی تا زمانی که آن Store پاک‌سازی (expunge) نشود، واقعاً حذف نخواهند شد.
Flags - انتشار تغییرات پرچم‌ها. توجه داشته باشید که Deleted/Trashed نیز یک پرچم است؛ این موضوع به‌ویژه اگر از mutt با گزینهٔ maildir_trash استفاده می‌کنید، حائز اهمیت است.
Full - نام مستعار برای "New Upgrade Gone Flags". این مقدار پیش‌فرض سراسری است.
None (همان --noop در خط فرمان) - عدم انتشار هرگونه تغییر. زمانی کاربرد دارد که تنها می‌خواهید عملیات پاک‌سازی (expunge) انجام دهید.
Pull و Push پرچم‌های جهت هستند، در حالی که New، Old، Upgrade، Gone و Flags پرچم‌های نوع می‌باشند. این دو دسته پرچم، یک ماتریس دوبعدی (یک جدول) را تشکیل می‌دهند. سلول‌های آن کنش‌های منفردی هستند که باید انجام گیرند. دو شیوه برای فعال‌سازی سلول‌ها وجود دارد:
در شیوهٔ نخست، پرچم‌ها تمام سطرها/ستون‌های ماتریس را انتخاب می‌کنند. تنها سلول‌هایی فعال می‌شوند که هم به‌صورت افقی و هم عمودی انتخاب شده باشند. مشخص نکردن جهت مانند مشخص کردن هر دو جهت است، و مشخص نکردن نوع مانند مشخص کردن Full خواهد بود. برای مثال، "Sync Pull New Flags" پیام‌های جدید و تغییرات پرچم را از سمت دور به سمت نزدیک منتشر می‌کند، "Sync New Gone" ورود پیام‌ها و حذف‌ها را در هر دو جهت منتشر می‌کند، و "Sync Push" تمامی تغییرات را از سمت نزدیک به سمت دور منتشر خواهد کرد.
در شیوهٔ دوم، پرچم‌های جهت با پرچم‌های نوع پیوند داده می‌شوند؛ هر پرچم مرکب بلافاصله یک سلول را در ماتریس فعال می‌کند. علاوه بر حداقل یک پرچم مرکب، می‌توان از پرچم‌های تکی نیز استفاده کرد، اما بر خلاف شیوهٔ نخست، آن‌ها فوراً تمامی سلول‌ها را در سطر/ستون مربوطه فعال می‌کنند (به استثنای Old). برای مثال، "Sync PullNew PullGone Push" ورود و حذف پیام‌ها را از سمت دور به نزدیک، و هرگونه تغییر (به‌جز پیام‌های قدیمی) را از سمت نزدیک به سمت دور منتشر می‌کند.
توجه داشته باشید که فعال کردن یک سلول به دو روش مختلف مجاز نیست؛ برای نمونه "Sync PullNew Pull" و "Sync PullNew Gone Push" منجر به بروز خطاهای ساختاری می‌شوند.
گزینهٔ None نباید با هیچ عملیات دیگری ترکیب شود.
ایجاد خودکار صندوق‌های پستی ناموجود [در سمت دور/نزدیک]. در غیر این صورت، در صورتی که یک صندوق پستی و وضعیت همگام‌سازی متناظر با آن وجود نداشته باشد، یک پیام خطا چاپ کرده و از آن جفت صندوق پستی صرف‌نظر می‌کند. (پیش‌فرض سراسری: None)
انتشار حذف‌های صندوق پستی [به سمت دور/نزدیک]. در غیر این صورت، در صورتی که صندوق پستی وجود نداشته باشد اما وضعیت همگام‌سازی متناظر موجود باشد، یک پیام خطا چاپ کرده و از آن جفت صندوق پستی صرف‌نظر می‌کند.
برای صندوق‌های پستی MailDir، حذف زیرپوشهٔ cur/ برای علامت‌گذاری آن‌ها به عنوان حذف‌شده کافی است. این امر سازگاری با SyncState * را تضمین می‌کند.
توجه داشته باشید که جهت حفظ ایمنی، صندوق‌های پستی غیرخالی هرگز حذف نمی‌شوند.
(پیش‌فرض سراسری: None)
حذف دائمی تمامی پیام‌ها [در سمت دور/نزدیک] که برای حذف علامت‌گذاری شده‌اند. با ExpungeSolo برای همان سمت مانعة‌الجمع (ناسازگار) است. بخش RECOMMENDATIONS را در زیر ببینید. (پیش‌فرض سراسری: None)
حذف دائمی تمامی پیام‌ها [در سمت دور/نزدیک] که هم برای حذف علامت‌گذاری شده‌اند و هم هیچ پیام متناظری در Store مقابل ندارند. همراه با Sync Gone، این گزینه امکان آینه‌سازی واقعی پاک‌سازی‌ها (expunges) را فراهم می‌سازد. با این حال توجه داشته باشید که این کار تنها زمانی منطقی است که هیچ عامل دیگری پیام‌های علامت‌گذاری‌شده برای حذف را پاک‌سازی نکند. همچنین توجه داشته باشید که این گزینه برای مخازن IMAP که از افزونهٔ UIDPLUS پشتیبانی نمی‌کنند کارایی ندارد. با Expunge برای همان سمت مانعة‌الجمع است. (پیش‌فرض سراسری: None) CopyArrivalDate {yes|no} مشخص می‌کند که آیا زمان رسیدن پیام‌ها باید همراه با خود پیام‌ها منتشر (همگام‌سازی) شود یا خیر. فعال کردن این گزینه برای دست‌نخورده ماندن مرتب‌سازی پیام‌ها بر اساس برچسب زمانی منطقی است. توجه داشته باشید که IMAP تضمین نمی‌کند برچسب زمانی (که internal date نامیده می‌شود) دقیقاً همان زمان رسیدن باشد، اما معمولاً به اندازه کافی به آن نزدیک است. (پیش‌فرض سراسری: no)

گزینه‌های Sync، Create، Remove، Expunge، ExpungeSolo، MaxMessages، ExpireUnread، ExpireSide و CopyArrivalDate می‌توانند قبل از هر بخشی برای اعمال اثر سراسری استفاده شوند. تنظیمات سراسری توسط گزینه‌های خاصِ Channel لغو می‌شوند، که آن‌ها نیز به نوبه خود با سوئیچ‌های خط فرمان بازنویسی می‌شوند.

مکان فایل‌های وضعیت همگام‌سازی این Channel را تعیین می‌کند. علامت * به این معنی است که وضعیت باید در فایلی به نام .mbsyncstate در خودِ صندوق پستی سمت نزدیک (near side) ذخیره شود؛ این کار این مزیت را دارد که در صورت حذف صندوق پستی، نیازی به رسیدگی جداگانه به فایل وضعیت نخواهید داشت، اما بدیهی است که این روش تنها با صندوق‌های پستی Maildir کار می‌کند. در غیر این صورت، این مقدار به عنوان رشته‌ای تفسیر می‌شود که به نام صندوق پستی سمت نزدیک پیشوند می‌شود تا یک مسیر کامل تشکیل شود. توجه داشته باشید اگر می‌خواهید یک دایرکتوری را مشخص کنید، باید در انتهای آن یک اسلش قرار دهید.
این گزینه می‌تواند در خارج از هر بخشی برای اعمال اثری سراسری استفاده شود. در این حالت رشته الحاقی بر اساس الگوی زیر ساخته می‌شود: :far-store:far-box_:near-store:near-box (همچنین گزینه FieldDelimiter را در زیر ببینید).
(پیش‌فرض سراسری: $XDG_STATE_HOME/isync/، به همراه بازگشت به ~/.mbsync/ در صورتی که فقط دومی وجود داشته باشد. در صورت عدم تنظیم، مقدار پیش‌فرض $XDG_STATE_HOME برابر با ~/.local/state است.)

گروه name را تعریف کرده و بخشی را برای پارامترهای آن باز می‌کند. توجه داشته باشید حتی با اینکه Groups فضای نام اختصاصی خود را دارند، در خط فرمان Channelهای همنام را «پنهان» خواهند کرد.
می‌توان یک یا چند Channel را در همان خط مشخص کرد.
اگر یک یا چند box را به یک channel اختصاص دهید، آن‌ها به جای آنچه در Patterns مربوط به Channel مشخص شده است، استفاده خواهند شد. همین کار را می‌توان در خط فرمان نیز انجام داد، با این تفاوت که در آنجا می‌توان از خطوط جدید نیز به عنوان جداکننده نام صندوق‌های پستی استفاده کرد.
افزودن Channelهای مشخص‌شده به Group. این گزینه می‌تواند چندین بار درون یک Group مشخص شود.


مشخص می‌کند که آیا mbsync عملیات تخلیه اجباری بافر (forced flushing) را انجام دهد یا خیر، که سطح ایمنی داده‌ها پس از خرابی‌های سیستم و قطعی برق را تعیین می‌کند. غیرفعال کردن آن برای سیستم‌های فایلی که با حالت data=ordered سوار (mount) شده‌اند، تا حد منطقی ایمن است. فعال کردن آن انتخابی هوشمندانه برای سیستم‌های فایلی است که با data=writeback سوار شده‌اند، به ویژه سیستم‌های مدرن مانند ext4، btrfs و xfs. تأثیر عملکردی آن بر روی سیستم‌های فایل قدیمی‌تر ممکن است نامتناسب و سنگین باشد. (پیش‌فرض: yes)
نویسه‌ای که برای جداسازی فیلدها در رشته الحاقی به یک SyncState سراسری استفاده می‌شود. mbsync ترجیح می‌دهد از دونقطه (:) استفاده کند، اما این نویسه با سیستم‌های فایل DOS/Windows ناسازگار است. بدیهی است در صورتی که SyncState برابر با * باشد، این گزینه بی‌معنی است. با این حال، پیش‌فرض InfoDelimiter را نیز تعیین می‌کند. (پیش‌فرض سراسری: ; در ویندوز، : در سایر سیستم‌ها)
میزان حافظه مصرفی لحظه‌ای به ازای هر Channel و در هر جهت، که فراتر از آن mbsync از مصرف حافظه بیشتر خودداری خواهد کرد. توجه داشته باشید که این یک محدودیت مطلق نیست، زیرا حتی یک پیام واحد نیز می‌تواند حافظه‌ای بیشتر از این مقدار مصرف کند. (پیش‌فرض: 10M)

اگر خروجی mbsync به یک کنسول متصل باشد، به‌طور پیش‌فرض شمارنده‌های پیشرفت را چاپ خواهد کرد. خروجی شبیه به این خواهد بود:


C: 1/2 B: 3/4 F: +13/13 *23/42 #0/0 -0/0 N: +0/7 *0/0 #0/0 -0/0

این نشان‌دهنده پیشرفت تجمعی به ترتیب روی Channelها، صندوق‌ها (boxes)، و پیام‌های متأثر در سمت دور (far) و نزدیک (near) است. تعداد پیام‌ها به ترتیب بیانگر پیام‌های اضافه‌شده، پیام‌هایی با پرچم‌های به‌روزشده، پیام‌های منتقل‌شده به سطل زباله، و پیام‌های پالایش‌شده (expunged) است. هیچ تلاشی برای محاسبه مقادیر کل از قبل صورت نمی‌گیرد، بنابراین با جمع‌آوری اطلاعات بیشتر، این مقادیر در طول زمان افزایش می‌یابند.

صرف‌نظر از تغییر مسیر خروجی (redirection)، mbsync پس از اتمام کار، خلاصه‌ای از موارد بالا را چاپ خواهد کرد، مگر اینکه در حالت بی‌صدا (quiet) اجرا شده باشد.

اطمینان حاصل کنید که سرور IMAP شما پیام‌های حذف‌شده را به‌طور خودکار پالایش (auto-expunge) نمی‌کند - این کار کند است و از نظر معنایی تا حدی جای تردید دارد. به‌طور خاص، Gmail باید طوری پیکربندی شود که این کار را انجام ندهد.

به‌طور پیش‌فرض، mbsync هیچ پیامی را حذف نخواهد کرد - پالایش‌ها با علامت‌گذاری پیام‌ها به عنوان حذف‌شده در Store مقابل منتقل و اعمال می‌شوند. هنگامی که از صحت کارکرد پیکربندی خود مطمئن شدید، معمولاً مایل خواهید بود که Expunge را روی Both تنظیم کنید تا حذف‌ها به مرحله عمل برسند.

قابلیت سطل زباله داخلی mbsync به این بستگی دارد که خودِ mbsync عمل پالایش پیام‌های حذف‌شده را انجام دهد. این امر زمانی محقق می‌شود که حذف پیام‌های پیش‌تر منتشرشده را منتقل کند و سطل زباله در Store مقصد (معمولاً سرور IMAP شما) قرار داشته باشد.
با این حال، هنگامی که قصد دارید mbsync پیام‌هایی را که هنوز منتقل نشده‌اند به سطل زباله منتقل کند، برنامه کاربری ایمیل (MUA) باید پیام‌ها را بدون پالایش کردن، به عنوان حذف‌شده علامت‌گذاری کند (به عنوان مثال، گزینه maildir_trash در Mutt). توجه داشته باشید که بیشتر پیام‌ها مدت‌ها قبل از حذف شدن همگام‌سازی می‌شوند، بنابراین این یک حالت خاص و نادر است که احتمالاً نیازی نیست برای آن بهینه‌سازی انجام دهید. این نکته همچنین بدین معناست که گزینه‌های TrashNewOnly و TrashRemoteNew معمولاً کاربرد چندانی ندارند.

اگر سرور شما از انتقال خودکار به سطل زباله پشتیبانی می‌کند (مانند آنچه Gmail انجام می‌دهد)، احتمالاً ایده خوبی است که به جای قابلیت سطل زباله mbsync به خود سرور اتکا کنید. در این صورت، اگر قصد دارید سطل زباله را مانند دیگر صندوق‌های پستی همگام‌سازی کنید، نباید اصلاً از گزینه Trash در mbsync استفاده نمایید.

استفاده از گزینه Trash در ارتباط با M$ Exchange 2013 به دلیل وجود یک باگ در سرور، نیازمند استفاده از گزینه DisableExtension MOVE است.

هنگام استفاده از طرح پیش‌فرض و بهینه‌ترِ نگاشت UID، مهم است که MUA هنگام جابه‌جایی فایل‌ها میان پوشه‌های Maildir، نام آن‌ها را تغییر دهد. Mutt همواره این کار را انجام می‌دهد، در حالی که mu4e نیاز به پیکربندی دارد تا این عمل را پیاده‌سازی کند:

(setq mu4e-change-filenames-when-moving t)

انتظار کلی این است که یک نام فایل کاملاً جدید ایجاد شود، درست مانند زمانی که پیام تازه ایجاد شده است؛ با این حال حذف بخش میانی ,U=xxx نیز کفایت می‌کند. تغییراتی که پس از دریافت فهرست پیام‌ها توسط mbsync ایجاد شوند، تا اجرای بعدی mbsync همگام‌سازی نخواهند شد.

استفاده از Trash در مخازن IMAP بدون افزونهٔ UIDPLUS (به‌ویژه M$ Exchange دست‌کم تا نسخهٔ ۲۰۱۰) با شرایط رقابتی (race condition) همراه است: اگر پیام‌ها پس از دریافت فهرست پیام‌ها اما پیش از پاکسازی (expunge) صندوق پستی به عنوان حذف‌شده علامت‌گذاری شوند، از دست خواهند رفت. تا زمانی که در هر لحظه تنها یک کلاینت (از جمله خود mbsync) به صندوق پستی IMAP دسترسی داشته باشد، هیچ خطری وجود ندارد.

$XDG_CONFIG_HOME/isyncrc (معمولاً ~/.config/isyncrc)
فایل پیکربندی پیش‌فرض. همچنین فایل نمونه در دایرکتوری مستندات را ببینید.
$XDG_STATE_HOME/isync/ (معمولاً ~/.local/state/isync/)
دایرکتوری حاوی فایل‌های وضعیت همگام‌سازی.
~/.mbsyncrc
فایل پیکربندی قدیمی (Legacy).
~/.mbsync/
دایرکتوری قدیمی حاوی فایل‌های وضعیت همگام‌سازی.

mdconvert(1), mutt(1), maildir(5)

اطلاعات به‌روز دربارهٔ mbsync را می‌توان در http://isync.sf.net یافت.

سازوکارهای SASL در نشانی زیر فهرست شده‌اند: http://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml

در ابتدا توسط Michael R. Elkins نوشته شد، توسط Oswald Buddenhagen بازنویسی شد و در حال حاضر نگهداری می‌شود، با مشارکت افراد بسیار دیگر؛ برای جزئیات فایل AUTHORS را ببینید.

2025-08-11 isync 1.5.1