| DOVEADM-BACKUP(1) | Dovecot | DOVEADM-BACKUP(1) |
نام (NAME)
doveadm-backup - قابلیت همگام‌سازی یک‌طرفهٔ صندوق پستی در Dovecot
خلاصه دستور (SYNOPSIS)
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
توضیحات (DESCRIPTION)
ابزار dsync (کوتاه‌شدهٔ doveadm sync) قابلیت همگام‌سازی صندوق پستی در Dovecot است. از این ابزار می‌توان برای چندین سناریوی کاربردی مختلف استفاده کرد: همگام‌سازی دوطرفهٔ صندوق‌های پستی، تهیهٔ نسخهٔ پشتیبان از ایمیل‌ها، و تبدیل صندوق‌های پستی از/به قالب‌های مختلف. همهٔ این موارد می‌توانند در همان سرور یا میان سرورهای مختلف (از طریق ssh(1) یا اتصالات tcp) به کار روند. صندوق‌های پستی دوردست همچنین می‌توانند از طریق پروتکل IMAP در دسترس قرار گیرند، که امکان استفاده از dsync را برای اهداف مهاجرت صندوق پستی فراهم می‌سازد.
شما می‌توانید dsync را در یکی از سه حالت اجرا کنید:
- دستور doveadm backup همگام‌سازی یک‌طرفه را انجام می‌دهد. اگر هرگونه تغییری در مقصد وجود داشته باشد بازگردانی خواهد شد، به طوری که مقصد دقیقاً شبیه به مبدأ خواهد بود.
- دستور doveadm sync همگام‌سازی دوطرفه را انجام می‌دهد. تمام تغییرات را بدون از دست رفتن هیچ داده‌ای ادغام می‌کند. پس از اتمام همگام‌سازی، هر دو صندوق پستی کاملاً یکسان خواهند بود.
- دستور doveadm sync -1 همگام‌سازی یک‌طرفه را انجام می‌دهد. اگر تغییری در مقصد وجود داشته باشد، حفظ خواهد شد و تغییرات جدید بر روی آن‌ها ادغام می‌شوند. این ادغام در حال حاضر کاملاً بی‌نقص عمل نمی‌کند، بنابراین استفاده از آن باید محدود باشد. هدف اصلی آن این است که در هنگام مهاجرت صندوق پستی می‌توانید doveadm backup را چندین بار اجرا کنید، سپس تحویل ایمیل‌ها را به صندوق پستی جدید تغییر دهید و doveadm sync -1 را یک بار دیگر اجرا کنید تا آخرین ایمیل‌های جدید از صندوق پستی قدیمی منتقل شوند.
- •
- الگوریتم یک‌طرفه مشابه الگوریتم دsync دوطرفه است، با این تفاوت که حساب مبدأ دستخوش تغییر نمی‌شود. این الگوریتم شناسهٔ GUID پیام (Global UID) را واکشی می‌کند که برای شناسایی هرگونه تعارض 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) تمامی پیام‌ها را در تمام صندوق‌های پستی پیمایش می‌کند. این کار تضمین می‌کند که همه چیز همگام خواهد شد، اما برای همگام‌سازی افزایشی بیش از حد کند است.
- همگام‌سازی سریع (پیش‌فرض) ابتدا تلاش می‌کند صندوق‌های پستی تغییریافته را بیابد، و تنها آن‌ها را همگام‌سازی کند. این کار با بررسی فراداده‌های صندوق‌های پستی (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 یک یا چند کاربر را همگام‌سازی کند.
گزینه‌های عمومی (GLOBAL OPTIONS)
گزینه‌های عمومی doveadm(1):
-D
پیام‌های اشکال‌زدایی (debug) و پرگویی (verbosity) را فعال می‌کند.
-O
هیچ فایل پیکربندی‌ای را نمی‌خواند و صرفاً از مقادیر پیش‌فرض استفاده می‌کند. تنظیم dovecot_storage_version به‌طور پیش‌فرض روی جدیدترین نسخه قرار دارد، اما می‌توان آن را با -o بازنویسی کرد.
-k
تمام محیط را برای doveadm حفظ می‌کند، نه فقط تنظیم import_environment را.
-v
پرگویی (verbosity)، از جمله شمارندهٔ پیشرفت را فعال می‌کند.
-i instance-name
در صورت استفاده از چندین نمونه (instance) از Dovecot، فایل پیکربندی را بر اساس این نام نمونه انتخاب می‌کند.
برای اطلاعات بیشتر به تنظیم instance_name مراجعه کنید.
-c config-file
پیکربندی را از config-file داده‌شده می‌خواند. به‌طور پیش‌فرض ابتدا سوکت پیکربندی را می‌خواند و در صورت در دسترس نبودن به /etc/dovecot/dovecot.conf بازمی‌گردد. همچنین می‌توانید این مقدار را به سوکت پیکربندی نمونه‌ای که نسخه‌ای سازگار را اجرا می‌کند هدایت کنید.
-o setting=value
تنظیم پیکربندی setting را از /etc/dovecot/dovecot.conf و از userdb با مقدار داده‌شدهٔ value بازنویسی می‌کند. جهت بازنویسی چندین تنظیم، می‌توان گزینهٔ -o را چندین بار مشخص کرد.
گزینه‌ها (OPTIONS)
-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) باید منتظر عملیات‌های ورودی/خروجی معلق بماند. مهلت زمانی پیش‌فرض ۶۰۰ ثانیه است.
-p setting=value
تنظیم پیکربندی setting را برای فضای ذخیره‌سازی مبدأ بازنویسی می‌کند.
-g mailbox_guid
مشابه -m است، اما صندوق پستی مورد نظر برای همگام‌سازی را به‌جای نام، بر اساس شناسهٔ یکتای GUID آن پیدا می‌کند.
-l secs
ابزار dsync را برای این کاربر قفل می‌کند. حداکثر به مدت secs ثانیه پیش از انصراف منتظر می‌ماند. این پارامتر باید برای جلوگیری از خرابی همگام‌سازی در حالتی استفاده شود که احتمال اجرای هم‌زمان dsync برای همان کاربر وجود دارد.
-m mailbox
تنها این نام صندوق پستی را همگام‌سازی می‌کند.
-n namespace
تنها فضای نام مشخص‌شده را همگام‌سازی می‌کند. از این پارامتر می‌توان چندین بار استفاده کرد.
-a all mailbox
نامی برای صندوق پستی مجازی "All mails". در صورت تعیین شدن، تلاش می‌شود پیام‌ها به جای ذخیرهٔ جداگانه، از این صندوق پستی کپی شوند. این کار می‌تواند مصرف کل فضای دیسک و همچنین ورودی/خروجی (IO) دیسک را کاهش دهد.
-t start date
ایمیل‌هایی را که برچسب زمانی دریافت آن‌ها قدیمی‌تر از زمان مشخص‌شده است نادیده می‌گیرد.
-e end date
ایمیل‌هایی را که برچسب زمانی دریافت آن‌ها جدیدتر از زمان مشخص‌شده است نادیده می‌گیرد.
-O sync flag
تنها ایمیل‌هایی را همگام‌سازی می‌کند که پرچم مشخص‌شده را دارند. اگر نام پرچم با "-" آغاز شود، تمام ایمیل‌ها به جز آن‌هایی که پرچم مشخص‌شده را دارند همگام‌سازی می‌شوند.
-I max size
ایمیل‌های بزرگ‌تر از اندازهٔ مشخص‌شده را نادیده می‌گیرد.
-r rawlog_path
هنگام اجرای دوردست dsync، ترافیک ورودی/خروجی دوردست را در فایل گزارش مشخص‌شده می‌نویسد.
-s previous_state
از همگام‌سازی مبتنی بر وضعیت استفاده می‌کند. این امکان همگام‌سازی افزایشی بهینه‌شده را با ارائهٔ یک "رشته وضعیت همگام‌سازی" از اجرای قبلی dsync فراهم می‌سازد. ابزار dsync از این وضعیت استفاده می‌کند تا تنها تغییراتی را که از زمان ثبت آن وضعیت رخ داده‌اند همگام‌سازی کند و از پویش کامل صندوق پستی اجتناب نماید. اگر وضعیت قبلی ناشناخته باشد، از یک رشتهٔ خالی استفاده کنید. در صورت تعیین این پارامتر، وضعیت جدید همیشه در خروجی استاندارد چاپ می‌شود.
-u user/mask
دستور (command) را تنها برای user داده‌شده اجرا می‌کند. همچنین امکان استفاده از نویسه‌های عام (wildcards) '*' و '?' وجود دارد (مانند -u *@example.org).
-x mailbox_mask
نام/الگوی صندوق پستی مشخص‌شده را مستثنی می‌کند. این الگو می‌تواند شامل نویسه‌های عام "?" و "*****" باشد. همچنین می‌تواند یک نام کاربرد ویژه (مانند \Trash) باشد. از این پارامتر می‌توان چندین بار استفاده کرد.
آرگومان‌ها (ARGUMENTS)
destination
این آرگومان مقصد همگام‌سازی را مشخص می‌کند.
می‌تواند یکی از موارد زیر باشد:
mail_driver:mail_path : از فضای ذخیره‌سازی مشخص‌شده توسط mail_driver و mail_path استفاده می‌کند. از پارامتر -p برای تعیین تنظیمات اضافی استفاده کنید.
remote: login@host : از تنظیم dsync_remote_cmd برای اتصال به میزبان دوردست استفاده می‌کند (معمولاً از طریق ssh)
remoteprefix:login@host : این مورد مشابه remote است، با این تفاوت که "user@domain\n" پیش از شروع پروتکل dsync ارسال می‌شود. این امکان پیاده‌سازی یک اسکریپت پوششی قابل اعتماد را فراهم می‌کند که doveadm dsync-server را با خواندن نام کاربری از خط اول اجرا می‌نماید.
tcp: host[:port] : از طریق TCP به کارساز doveadm دوردست متصل می‌شود. درگاه پیش‌فرض با تنظیم doveadm_port مشخص می‌شود.
tcps: host[:port] : مشابه tcp است، اما همراه با SSL.
command [arg1 [, arg2, ...]] : یک دستور محلی را اجرا می‌کند که ورودی و خروجی استاندارد خود را به یک کارساز dsync متصل می‌نماید.
وضعیت خروج (EXIT STATUS)
ابزار dsync با یکی از مقادیر زیر خارج خواهد شد:
0
همگام‌سازی به طور کامل و بی‌نقص انجام شد.
2
همگام‌سازی بدون خطا انجام شد، اما برخی تغییرات اعمال نشد، بنابراین صندوق‌های پستی کاملاً همگام نشده‌اند. اجرای مجدد dsync معمولاً این مشکل را برطرف می‌کند. این حالت معمولاً برای توالی تغییر پیام در صندوق‌های پستی تازه ایجاد شده رخ می‌دهد. همچنین می‌تواند در صورتی رخ دهد که یکی از صندوق‌های پستی در حین همگام‌سازی تغییر کند.
1, >2
همگام‌سازی با شکست مواجه شد.
برای سایر کدهای خطای احتمالی به doveadm(1) نیز مراجعه کنید.
مثال (EXAMPLE)
همگام‌سازی (SYNCHRONIZATION)
همگام‌سازی صندوق‌های پستی با یک سرور دوردست. هرگونه خطا در خروجی خطای استاندارد (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
تبدیل (CONVERTING)
مثال برای تبدیل ایمیل‌ها از قالب 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 موجود کاربر را متوقف کنید (با استفاده از doveadm kick) (که هنوز از maildir استفاده می‌کنند).
- 5.
- دستور doveadm sync را یک بار دیگر اجرا کنید تا تغییرات نهایی که احیاناً انجام شده‌اند اعمال شوند. پس از این نباید هیچ تغییری در Maildir ایجاد شود، زیرا مکان ایمیل کاربر تغییر یافته و تمام فرآیندهای موجود که از آن استفاده می‌کردند متوقف شده‌اند.
پس از اینکه تمام کاربران تبدیل شدند، می‌توانید تنظیمات سراسری mail_driver و mail_path را به‌روزرسانی کرده و مکان‌های ایمیل به ازای هر کاربر را از userdb حذف کنید.
امنیت (SECURITY)
این دستور نمی‌تواند به طور ایمن توسط کاربران غیرقابل اعتماد استفاده شود، مگر اینکه ورودی به دقت پاکسازی و اعتبارسنجی (sanitize) شود. مقصد اجازهٔ اجرای دستورات دلخواه را می‌دهد. در صورت استفاده از dsync_remote_cmd، نام کاربری و نام میزبان ممکن است حاوی فاصله باشند یا با یک خط تیره شروع شوند که می‌تواند امکان ارسال پارامترهای ناامن به ssh را فراهم کند. همچنین از آنجا که ssh دستورات را از طریق پوسته (shell) اجرا می‌کند، پارامترهای حاوی مثلاً ; یا && می‌توانند منجر به اجرای چندین دستور شوند.
گزارش باگ‌ها (REPORTING BUGS)
گزارش باگ‌ها، شامل خروجی doveconf -n را به فهرست پستی Dovecot به نشانی ⟨dovecot@dovecot.org⟩ ارسال کنید. اطلاعات درباره نحوه گزارش باگ‌ها در این نشانی در دسترس است: ⟨https://dovecot.org/bugreport.html⟩
همچنین ببینید (SEE ALSO)
doveadm(1), doveadm-purge(1)
| May 2026 | e5ac02a |