DOVEADM-SYNC(1) Dovecot DOVEADM-SYNC(1)

doveadm-sync - قابلیت همگام‌سازی دوطرفهٔ صندوق‌های پستی Dovecot

doveadm [GLOBAL OPTIONS] sync [-u user | -A | -F file | --no-userdb-lookup] [-S socket_path] [-1fPR] [-l secs] [-r rawlog path] [-m mailbox] [-g mailbox guid] [-n namespace | -N] [-x exclude] [-a all mailbox] [-s state] [-T secs] [-t start date] [-e end date] [-O sync flag] [-I max size] [-p setting=value] destination

doveadm [GLOBAL OPTIONS] backup [-u user | -A | -F file | --no-userdb-lookup] [-S socket_path] [-fPR] [-l secs] [-r rawlog path] [-m mailbox] [-g mailbox guid] [-n namespace | -N] [-x exclude] [-a all mailbox] [-s state] [-T secs] [-t start date] [-e end date] [-O sync flag] [-I max size] [-p setting=value] destination

ابزار dsync (کوتاه‌شدهٔ doveadm sync) قابلیت همگام‌سازی صندوق‌های پستی Dovecot است. این ابزار می‌تواند در چندین سناریوی مختلف استفاده شود: همگام‌سازی دوطرفهٔ صندوق‌های پستی، ایجاد نسخهٔ پشتیبان از نامه‌ها، و تبدیل صندوق‌های پستی از/به قالب‌های مختلف صندوق پستی. تمام این موارد می‌توانند در یک سرور یکسان یا میان سرورهای مختلف (از طریق اتصالات ssh(1) یا tcp) استفاده شوند. صندوق‌های پستی راه دور همچنین می‌توانند از طریق پروتکل IMAP در دسترس باشند، که استفاده از dsync را برای اهداف مهاجرت صندوق پستی امکان‌پذیر می‌سازد.

می‌توانید dsync را در یکی از سه حالت اجرا کنید:

  • دستور doveadm backup همگام‌سازی یک‌طرفه انجام می‌دهد. اگر تغییری در مقصد وجود داشته باشد، بازگردانی خواهد شد تا مقصد دقیقاً شبیه مبدأ به نظر برسد.
  • دستور doveadm sync همگام‌سازی دوطرفه انجام می‌دهد. این دستور تمام تغییرات را بدون از دست دادن هیچ داده‌ای ادغام می‌کند. پس از پایان همگام‌سازی، هر دو صندوق پستی نهایتاً کاملاً یکسان خواهند بود.
  • دستور doveadm sync -1 همگام‌سازی یک‌طرفه انجام می‌دهد. اگر تغییری در مقصد وجود داشته باشد، حفظ خواهد شد و تغییرات جدید روی آن ادغام می‌شوند. این ادغام در حال حاضر بی‌نقص عمل نمی‌کند، بنابراین استفاده از آن باید محدود باشد. هدف اصلی آن این است که در طول مهاجرت صندوق پستی می‌توانید doveadm backup را چندین بار اجرا کنید، سپس تحویل نامه‌ها را به صندوق پستی جدید تغییر دهید و doveadm sync -1 را یک بار دیگر اجرا نمایید تا آخرین نامه‌های جدید از صندوق پستی قدیمی منتقل شوند.
•
الگوریتم یک‌طرفه همان الگوریتم دوعرفه‌ای dsync است، با این تفاوت که حساب کاربری مبدأ تغییر داده نمی‌شود. این الگوریتم GUID (شناسه منحصربه‌فرد سراسری) پیام را واکشی می‌کند که برای شناسایی هرگونه تعارض UID در پیام‌ها به کار می‌رود. تا زمانی که نگاشت UID<->GUID در سمت مبدأ و مقصد همخوانی داشته باشد، فرض می‌شود آن ایمیل‌ها به‌درستی همگام شده‌اند. تنها پس از اولین عدم تطابق، اعمال تغییرات آغاز خواهد شد.

مثال: صندوق پستی مبدأ دارای پیام‌هایی با UID 1..5 است؛ صندوق پستی مبدأ با استفاده از doveadm backup با مقصد همگام می‌شود. متعاقباً، UID 6 به صندوق پستی مبدأ تحویل داده شده و UID 1 از صندوق پستی مقصد پاکسازی (expunge) می‌شود. در این مثال، UID 1 در مقصد حذف‌شده باقی می‌ماند زیرا UID 1..5 دارای سرایندهای Date+Message-ID یکسانی هستند. UID 6 در مقصد وجود ندارد، بنابراین کپی می‌شود.

اگر هر دو مبدأ و مقصد دارای UID 6 باشند، اما پیام‌ها متفاوت باشند، سرایندها مطابقت نخواهند داشت و هر دو پیام در مقصد نگه داشته می‌شوند، اما به آن‌ها UIDهای جدید 7 و 8 اختصاص می‌یابد تا اطمینان حاصل شود که هیچ کلاینتی در مورد اینکه UID 6 واقعاً چه پیامی بوده سردرگم نشود. بدین ترتیب، همگام‌سازی یک‌طرفه به محض رخ دادن تغییرات در هر یک از طرفین، به‌سرعت از صندوق پستی مبدأ فاصله می‌گیرد؛ بنابراین همگام‌سازی یک‌طرفه معمولاً فقط باید در بازهٔ زمانی کوتاهی پس از اجرای دستور doveadm backup یا doveadm sync استفاده شود.

همچنین سه الگوریتم همگام‌سازی مختلف وجود دارد:

  • همگام‌سازی کامل (پارامتر -f) تمام پیام‌ها را در تمام صندوق‌های پستی بررسی و پویش می‌کند. این روش تضمین می‌کند که همه‌چیز همگام خواهد شد، اما برای همگام‌سازی افزایشی (incremental) بیش از حد کند است.
  • همگام‌سازی سریع (پیش‌فرض) ابتدا تلاش می‌کند صندوق‌های پستی تغییریافته را پیدا کرده و فقط آن‌ها را همگام کند. این کار با بررسی فراداده‌های صندوق‌های پستی (NEXTUID و HIGHESTMODSEQ) انجام می‌شود. معمولاً این روش خوب عمل می‌کند، به‌ویژه با همگام‌سازی یک‌طرفه، اما اگر هر دو طرف دقیقاً تعداد تغییرات یکسانی داشته باشند، فراداده‌ها ممکن است حتی با وجود متفاوت بودن تغییرات، حاوی مقادیر یکسانی شوند.
  • همگام‌سازی مبتنی بر وضعیت (پارامتر -s) کارآمدترین روش برای همگام‌سازی صندوق‌های پستی است. این روش به ذخیره بودن وضعیت اجرای قبلی dsync در جایی و ارسال آن به اجرای بعدی dsync متکی است. بر اساس این وضعیت، dsync می‌تواند تنها تغییراتی را ارسال کند که پس از اجرای قبلی dsync رخ داده‌اند. تا زمانی که وضعیت یا صندوق‌های پستی خراب نشده باشند، این الگوریتم باید بی‌نقص کار کند.

همگام‌سازی تا جای ممکن بی‌نقص انجام می‌شود: یک کلاینت IMAP یا POP3 نباید بتواند هیچ تفاوتی را بین دو صندوق پستی متوجه شود. همگام‌سازی دوطرفه به این معناست که انجام هر نوع تغییری در هر دو طرف ایمن است و dsync تغییرات را بدون از دست رفتن هیچ تغییری در هر یک از طرفین ادغام خواهد کرد. این ویژگی به این دلیل ممکن است که dsync می‌تواند به لاگ‌های نمایهٔ Dovecot که تغییرات را ثبت می‌کنند دسترسی داشته باشد. البته امکان وجود تعارض در هنگام ادغام هست؛ این تعارض‌ها به روشی ایمن حل‌وفصل می‌شوند. برای اطلاعات بیشتر سند dsync design را ببینید.

ابزار dsync از همان فایل‌های پیکربندی سایر بخش‌های Dovecot استفاده می‌کند (از طریق doveconf(1)). کل پیکربندی را می‌توان با دادن پارامتر -c به یک فایل پیکربندی دیگر تغییر داد، یا با استفاده از پارامتر -o تنظیمات خاصی را بازنویسی کرد. هنگام اجرای برنامهٔ راه دور dsync نیز سازوکار یکسان است: این برنامه از پیکربندی محلی خودش استفاده می‌کند.

ابزار dsync می‌تواند کاملاً مستقل اجرا شود. این ابزار به در حال اجرا بودن هیچ‌یک از پردازه‌های سرور Dovecot نیازی ندارد، مگر هنگام استفاده از پارامتر -u برای جستجوی userdb از پردازهٔ auth.

ابزار dsync می‌تواند با استفاده از پارامترهای -u یا -A یک یا چند کاربر را همگام‌سازی کند.

گزینه‌های سراسری doveadm(1):

-D

حالت پرگویی (verbosity) و پیام‌های اشکال‌زدایی را فعال می‌کند.

-O

هیچ فایل پیکربندی‌ای را نمی‌خواند، صرفاً از پیش‌فرض‌ها استفاده می‌کند. مقدار تنظیم dovecot_storage_version به‌طور پیش‌فرض روی جدیدترین نسخه قرار دارد، اما می‌توان آن را با -o بازنویسی کرد.

-k

تمام متغیرهای محیطی را برای doveadm حفظ می‌کند، نه فقط مقدار تنظیم import_environment را.

-v

حالت پرگویی را فعال می‌کند، از جمله شمارندهٔ پیشرفت را.

-i instance-name

در صورت استفاده از نمونه‌های متعدد Dovecot، فایل پیکربندی را بر اساس این نام نمونه انتخاب می‌کند.

برای اطلاعات بیشتر تنظیم instance_name را ببینید.

-c config-file

پیکربندی را از config-file داده‌شده می‌خواند. به‌طور پیش‌فرض ابتدا سوکت پیکربندی را می‌خواند و سپس در صورت عدم دسترسی به /etc/dovecot/dovecot.conf بازمی‌گردد. همچنین می‌توانید این گزینه را به سوکت پیکربندی نمونه‌ای که یک نسخهٔ سازگار را اجرا می‌کند ارجاع دهید.

-o setting=value

تنظیم پیکربندی setting را از /etc/dovecot/dovecot.conf و از userdb با value داده‌شده بازنویسی می‌کند. جهت بازنویسی چندین تنظیم، گزینهٔ -o می‌تواند چندین بار مشخص شود.

-A

اگر گزینهٔ -A وجود داشته باشد، command برای همهٔ کاربران انجام خواهد شد. استفاده از این گزینه همراه با کاربران سیستمی برگرفته از userdb { driver = passwd } توصیه نمی‌شود، زیرا شامل کاربرانی با UID کمتر از مقدار پیکربندی‌شده در تنظیم first_valid_uid نیز می‌شود.

هنگامی که ماژول SQL userdb استفاده می‌شود، اطمینان حاصل کنید که تنظیم userdb_sql_iterate_query با ساختار پایگاه‌دادهٔ شما مطابقت داشته باشد.

هنگام استفاده از ماژول LDAP userdb، اطمینان حاصل کنید که تنظیم userdb_fields و تنظیمات userdb_ldap_iterate_fields با طرحوارهٔ (schema) مربوط به LDAP شما همخوانی داشته باشند. در غیر این صورت doveadm(1) قادر نخواهد بود روی تمام کاربران پیمایش انجام دهد.

-F file

اجرای command برای تمام کاربران موجود در file. این گزینه مشابه گزینهٔ -A است، اما به‌جای دریافت فهرست کاربران از userdb، آنها از file داده‌شده خوانده می‌شوند. file در هر سطر شامل یک نام کاربری است.

-1

انجام همگام‌سازی یک‌طرفه به‌جای همگام‌سازی دوطرفه.

-f

انجام همگام‌سازی کامل.

-N

همگام‌سازی تمام فضاهای نام (namespaces) موجود. به‌طور پیش‌فرض تنها فضای نام inbox=yes همگام‌سازی می‌شود.

--no-userdb-lookup

عدم انجام جستجو در userdb. از متغیر محیطی USER برای تعیین نام کاربری استفاده کنید.

-P

اجرای doveadm-purge(1) برای فضای ذخیره‌سازی مقصد (از راه دور) پس از همگام‌سازی.

-R

انجام یک همگام‌سازی معکوس. در حالت عادی، پیام‌ها از سیستم محلی به مقصد (از راه دور) فرستاده (push) می‌شوند. این گزینه جریان کار را معکوس می‌کند و در عوض پیام‌ها را از فضای ذخیره‌سازی از راه دور به فضای محلی دریافت (pull) خواهد کرد.

-S socket_path

آرگومان این گزینه یا یک مسیر مطلق به یک UNIX domain socket محلی است، یا یک نام میزبان و درگاه (hostname:port)، به‌منظور اتصال به یک میزبان از راه دور از طریق یک سوکت TCP.

این گزینه به مدیر سیستم اجازه می‌دهد دستورهای پستی doveadm(1) را از طریق سوکت داده‌شده اجرا کند.

-T secs

تعیین مدت زمان به ثانیه که doveadm(1) باید در انتظار عملیات‌های ورودی/خروجی (I/O) متوقف‌شده بماند. مهلت زمانی پیش‌فرض ۶۰۰ ثانیه است.

-p setting=value

تنظیم پیکربندیِ setting را برای فضای ذخیره‌سازی مبدأ بازنویسی (override) می‌کند.

-g mailbox_guid

مشابه -m، اما صندوق پستیِ مورد نظر برای همگام‌سازی را به‌جای نام، با GUID آن پیدا می‌کند.

-l secs

قفل کردن dsync برای این کاربر. حداکثر به مدت secs ثانیه پیش از انصراف منتظر می‌ماند. اگر احتمال اجرای هم‌زمان dsync برای یک کاربر وجود داشته باشد، این پارامتر باید برای جلوگیری از خرابی همگام‌سازی استفاده شود.

-m mailbox

فقط همگام‌سازی این نام صندوق پستی.

-n namespace

تنها فضای نامِ مشخص‌شده را همگام‌سازی کن. این پارامتر می‌تواند چندین بار استفاده شود.

-a all mailbox

نام صندوق پستی مجازی «All mails». در صورت تعیین، تلاش می‌شود به‌جای ذخیرهٔ جداگانه، ایمیل‌ها از این صندوق پستی کپی شوند. این کار ممکن است مصرف کل فضای دیسک و همچنین ورودی/خروجی دیسک (disk IO) را کاهش دهد.

-t start date

نادیده گرفتن تمام ایمیل‌هایی که مهرزمانی دریافت (received-timestamp) آنها قدیمی‌تر از زمان مشخص‌شده است.

-e end date

نادیده گرفتن تمام نامه‌هایی که مهر زمانی دریافت (received-timestamp) آن‌ها تازه‌تر از زمان مشخص‌شده است.

-O sync flag

تنها نامه‌هایی را همگام‌سازی می‌کند که پرچم مشخص‌شده را دارند. اگر نام پرچم با «-» آغاز شود، تمام نامه‌ها به‌جز موارد دارای پرچم مشخص‌شده همگام می‌شوند.

-I max size

نادیده گرفتن تمام نامه‌های بزرگ‌تر از اندازه مشخص‌شده.

-r rawlog_path

هنگام اجرای dsync از راه دور، ترافیک ورودی/خروجی راه دور را در فایل لاگ مشخص‌شده می‌نویسد.

-s previous_state

استفاده از همگام‌سازی وابسته به وضعیت (stateful). این ویژگی با ارائه یک «رشته وضعیت همگام‌سازی» از اجرای قبلی dsync، امکان همگام‌سازی افزایشی بهینه‌شده را فراهم می‌کند. dsync از این وضعیت برای همگام‌سازی انحصاری تغییراتی که پس از ثبت آن وضعیت رخ داده‌اند استفاده خواهد کرد و بدین ترتیب از پویش کامل صندوق پستی (mailbox) جلوگیری می‌شود. اگر وضعیت قبلی نامشخص است، از یک رشته خالی استفاده کنید. در صورت تعیین این پارامتر، وضعیت جدید همیشه در خروجی استاندارد چاپ می‌شود.

-u user/mask

اجرای command تنها برای user داده‌شده. همچنین امکان استفاده از نویسه‌های عمومی (wildcard) «*» و «?» وجود دارد (مانند -u *@example.org).

-x mailbox_mask

مستثنی کردن نام یا ماسک صندوق پستی مشخص‌شده. ماسک می‌تواند شامل نویسه‌های عمومی «?» و «*****» باشد. ماسک همچنین می‌تواند یک نام با کاربرد خاص باشد (مانند \Trash). این پارامتر می‌تواند چندین بار استفاده شود.

destination

این آرگومان مقصد همگام‌سازی را مشخص می‌کند.

می‌تواند یکی از موارد زیر باشد:

mail_driver:mail_path : از فضای ذخیره‌سازی مشخص‌شده توسط mail_driver و mail_path استفاده می‌کند. برای تعیین تنظیمات بیشتر از پارامتر -p استفاده کنید.

remote: login@host : از تنظیم dsync_remote_cmd برای اتصال به میزبان راه دور (معمولاً از طریق ssh) استفاده می‌کند.

remoteprefix:login@host : همانند remote است، جز اینکه پیش از شروع پروتکل dsync عبارت «user@domain\n» ارسال می‌شود. این امر امکان پیاده‌سازی یک اسکریپت پوششی (wrapper script) معتمد را می‌دهد که doveadm dsync-server را با خواندن نام کاربری از سطر اول اجرا کند.

tcp: host[:port] : از طریق TCP به سرور راه دور doveadm متصل می‌شود. درگاه پیش‌فرض توسط تنظیم doveadm_port مشخص می‌شود.

tcps: host[:port] : همانند tcp است، اما با SSL.

command [arg1 [, arg2, ...]] : دستوری محلی را اجرا می‌کند که ورودی و خروجی استاندارد خود را به یک سرور dsync متصل می‌نماید.

دستور dsync با یکی از مقادیر زیر خارج خواهد شد:

0

همگام‌سازی بدون نقص انجام شد.

2

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

1, >2

همگام‌سازی ناموفق بود.

همچنین برای سایر کدهای خطای احتمالی، doveadm(1) را ببینید.

همگام‌سازی صندوق‌های پستی با یک کارساز دوردست. هرگونه خطا در stderr نوشته می‌شود:

doveadm sync -u username@example.com remote:server-replica.example.com

اگر برای ssh به پارامترهای پیچیده‌تری نیاز دارید، می‌توانید به عنوان مثال از این دستور استفاده کنید:

doveadm sync -u username@example.com ssh -i id_dsa.dovecot \
  mailuser@example.com doveadm dsync-server -u username@example.com

مثالی برای تبدیل ایمیل‌ها از قالب Maildir به قالب مشخص‌شده در فایل پیکربندی:

doveadm backup -u user maildir:~/Maildir

اگر می‌خواهید این کار را بدون هیچ‌گونه زمان از‌کارافتادگی (downtime) انجام دهید، می‌توانید تبدیل را کاربر به کاربر انجام دهید. در ابتدا:

  • پیکربندی از mail_driver = maildir و mail_path = ~/Maildir استفاده می‌کند
  • امکان تعیین مکان ایمیل به ازای هر کاربر را با استفاده از فیلدهای اضافی userdb راه‌اندازی کنید.

سپس برای هر کاربر:

1.
دستور doveadm sync را یک بار برای انجام تبدیل اولیه اجرا کنید.
2.
دستور doveadm sync را دوباره اجرا کنید، زیرا تبدیل اولیه ممکن است مدتی طول کشیده باشد و در طول آن تغییرات جدیدی رخ داده باشد. این بار دوم تنها تغییرات را اعمال می‌کند، بنابراین باید سریع باشد.
3.
پایگاه داده userdb را به‌روزرسانی کنید تا پیکربندی قالب ایمیل جدیدِ مورد نظر را برگرداند. برای مثال: mail_driver = mdbox و mail_path = ~/mdbox. اگر از حافظه پنهان احراز هویت (auth cache) استفاده می‌کنید، باید آن را خالی کنید، مانند doveadm auth cache flush.
4.
چند ثانیه صبر کنید و سپس تمام نشست‌های موجود imap و pop3 کاربر را (که هنوز از maildir استفاده می‌کنند) متوقف کنید (doveadm kick).
5.
دستور doveadm sync را یک بار دیگر اجرا کنید تا تغییرات نهایی که احتمالاً اعمال شده بودند اعمال شوند. پس از این نباید هیچ تغییری در Maildir وجود داشته باشد، زیرا مکان ایمیل کاربر تغییر کرده و تمام فرایندهای موجود که از آن استفاده می‌کردند خاتمه یافته‌اند.

هنگامی که همه کاربران تبدیل شدند، می‌توانید تنظیمات سراسری mail_driver و mail_path را به‌روزرسانی کرده و مکان‌های ایمیل به ازای هر کاربر را از userdb حذف کنید..SH "امنیت (SECURITY)"

این دستور نمی‌تواند توسط کاربران غیرقابل‌اعتماد به‌طور ایمن استفاده شود، مگر اینکه ورودی به‌طور دقیق پاک‌سازی شده باشد. مقصد اجازه اجرای دستورهای دلخواه را می‌دهد. در صورت استفاده از dsync_remote_cmd، نام کاربری و نام میزبان ممکن است دارای فاصله باشند یا با یک خط تیره آغاز شوند، که می‌تواند امکان انتقال پارامترهای ناامن به ssh را فراهم کند. همچنین از آنجا که ssh دستورها را از طریق پوسته اجرا می‌کند، پارامترهای حاوی مواردی مانند ; یا && می‌توانند منجر به اجرای چندین دستور شوند.

گزارش باگ‌ها، از جمله خروجی doveconf -n را به فهرست پستی Dovecot به نشانی ⟨dovecot@dovecot.org⟩ ارسال کنید. اطلاعات درباره نحوه گزارش باگ‌ها در این آدرس در دسترس است: ⟨https://dovecot.org/bugreport.html⟩

doveadm(1), doveadm-purge(1)

May 2026 e5ac02a