.Dd 2025-04-14
.Dt PIMSYNC 1
.\" TODO: replace the following line with the version at build time.
.Os PIMSYNC
.Sh "نام (NAME)"
.Nm pimsync
.Nd همگام‌سازی caldav، carddav، webcal و دایرکتوری‌های محلی
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl c Ar configfile
.Op Fl v Ar loglevel
.Ar command
.Op Ar pair…
.Nm
.Ic version
.Sh "توضیحات (DESCRIPTION)"
.Nm
تقویم‌ها و مخاطبین را همگام‌سازی می‌کند. برای تقویم‌ها، از کار با دایرکتوری‌های
محلی، سرورهای CalDAV یا URLهای Webcal پشتیبانی می‌کند. برای مخاطبین، از کار با
دایرکتوری‌های محلی یا سرورهای CardDav پشتیبانی می‌کند.
.Pp
واژه‌نامه اصطلاحات مربوطه:
.Bl -tag
.It Sy item
یک رویداد، وظیفه (todo)، یادداشت روزانه یا مخاطب منفرد.
.It Sy collection
گروه‌بندی چندین مورد (item). می‌تواند یکی از موارد روبرو باشد: (۱) یک تقویم منفرد
که شامل رویدادها، وظایف و/یا یادداشت‌های روزانه است، یا (۲) یک دفترچه نشانی که
حاوی مخاطبین است.
.It Sy storage
مکانی که شامل چندین مجموعه (collection) است. برای مثال: یک حساب در یک سرور CalDAV،
یا یک دایرکتوری محلی به همراه زیردایرکتوری‌ها، که هرکدام نشان‌دهنده یک تقویم هستند.
برای جزئیات مربوط به پیاده‌سازی‌های ذخیره‌سازی پشتیبانی‌شده و پیکربندی آن‌ها،
.Xr pimsync.conf 5
را ببینید.
.It Sy pair
دو فضای ذخیره‌سازی (storage) که برای همگام‌سازی با یکدیگر پیکربندی شده‌اند. یک فضای
ذخیره‌سازی منفرد ممکن است بخشی از چند جفت (pair) باشد.
.It Sy conflict
هنگام همگام‌سازی دو فضای ذخیره‌سازی، اگر یک مورد (item) منفرد در هر دو طرف تغییر
کرده باشد اما محتوای متفاوتی در دو طرف داشته باشد، گفته می‌شود که آن مورد در تداخل
(conflict) است.
.It Sy property
صفت فراداده‌ای که به یک مجموعه (collection) اعمال می‌شود. مثال‌ها: displayname،
colour، order.
.It Sy resource
یک مورد (item) یا یک مجموعه (collection). این اصطلاح بیشتر به‌صورت داخلی و در
لاگ‌ها استفاده می‌شود.
.El
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width Ds
.It Fl c Ar configfile
فایل پیکربندی را به‌جای پیش‌فرض، از مسیر مشخص‌شده بخوانید. بخش
.Sx FILES
در زیر و
.Xr pimsync.conf 5
را ببینید.
.It Fl v Ar loglevel
سطح ثبت گزارش (logger) را روی
.Ar loglevel
تنظیم می‌کند، که باید یکی از مقادیر
.Cm trace ،
.Cm debug ،
.Cm info ،
.Cm warn
یا
.Cm error
باشد. مقدار پیش‌فرض
.Cm warn
است. هنگام تعیین
.Cm trace ،
ممکن است لاگ‌ها حاوی داده‌های حساس باشند؛ بخش
.Sx "SECURITY CONSIDERATIONS"
در زیر را ببینید.
.El
.Sh "فرمان‌ها (COMMANDS)"
.Bl -tag -width Ds
.It Ic check Op Ar pair…
پیکربندی را بررسی کرده و خارج می‌شود. خود پیکربندی را اعتبارسنجی می‌کند و اطمینان
حاصل می‌کند که فضای ذخیره‌سازی معتبر است. برای مثال: یک
.\" FIXME: .Cm might not be correct here.
.Cm vdir
باید یک دایرکتوری موجود باشد، و سرور
.Cm caldav
باید قابلیت‌های CalDAV را گزارش کند، و غیره.
.It Ic daemon Op Ar pair…
فضا‌های ذخیره‌سازی را به‌طور مداوم همگام نگه می‌دارد. آرگومان
.Fl r Ar READY_FD
ممکن است برای ارائه یک توصیف‌گر فایل اعلان آمادگی استفاده شود.
.Pp
هنگامی که
.Nm
به وضعیت آماده خود رسید، دیمن فضا‌های ذخیره‌سازی را برای تغییرات زیر نظر می‌گیرد و
آن‌ها را همگام‌سازی می‌کند. در صورت بروز خطاهای غیرمهلک، pimsync در پس‌زمینه به
اجرا ادامه می‌دهد و عملیات ناموفق را بعداً دوباره امتحان می‌کند.
.Pp
از مواردی که همگام‌سازی آن‌ها ناموفق باشد صرف‌نظر خواهد شد.
.It Ic discover Op Ar pair…
مجموعه‌ها را شناسایی کرده و نمایش می‌دهد. این فرمان صرفاً اطلاعات ارائه می‌دهد و
به هیچ وجه وضعیت داخلی pimsync را تغییر نمی‌دهد.
.It Ic resolve-conflicts Op Ar pair…
تداخل‌های بین فضا‌های ذخیره‌سازی را به‌صورت دستی برطرف می‌کند.
.Pp
یک برنامه خارجی مشخص‌شده در فایل پیکربندی را اجرا می‌کند که عملیات حل تداخل را
برای هر مورد دارای تداخل انجام می‌دهد.
.It Ic sync Op Fl n Op Fl i Op Ar pair…
فضا‌های ذخیره‌سازی را یک بار همگام‌سازی کرده و خارج می‌شود. پرچم
.Fl n
یک اجرای آزمایشی (dry run) انجام می‌دهد و هیچ عملیات نوشتنی انجام نخواهد داد.
پرچم
.Fl i
حالت تعاملی را فعال می‌کند و قبل از ادامه همگام‌سازی، تأیید برنامه را درخواست می‌کند.
.It Ic repair Op Ar storage…
موارد نامعتبر را تعمیر می‌کند. در حال حاضر، این فرمان فیلدهای
.Va UID
ناموجود را اضافه می‌کند، اما در آینده اصلاحات دیگری نیز گنجانده خواهد شد. تعمیر
هم‌زمان هر دو مجموعه از یک جفت به‌شدت نهی می‌شود؛ در عوض، یک فضای ذخیره‌سازی را
تعمیر کرده و سپس آن جفت را همگام‌سازی کنید.
.It Ic version
اطلاعات نسخه را چاپ کرده و خارج می‌شود.
.El
.Pp
اگر یک
.Ar pair
مشخص شده باشد، تنها روی جفت(های) با نام(های) داده‌شده عملیات انجام می‌شود..Sh "محیط (ENVIRONMENT)"
.Bl -tag
.It Ev XDG_CONFIG_HOME
در صورت تعریف شدن، فایل پیکربندی نسبت به این دایرکتوری جستجو می‌شود. بخش
.Sx "فایل‌ها (FILES)"
در زیر را ببینید.
.El
.Sh "فایل‌ها (FILES)"
اگر
.Ev XDG_CONFIG_HOME
تعریف شده باشد، پیکربندی از این مسیر خوانده می‌شود:
.Bd -literal -offset indent
$XDG_CONFIG_HOME/pimsync/pimsync.conf
.Ed
.Pp
در صورتی که متغیر بالا تعریف نشده باشد، فایل پیکربندی از این مسیر خوانده خواهد شد:
.Bd -literal -offset indent
~/.config/pimsync/pimsync.conf
.Ed
.Pp
برای جزئیات مربوط به قالب فایل پیکربندی،
.Xr pimsync.conf 5
را ببینید.
.Sh "اعلام آمادگی (READINESS NOTIFICATION)"
اعلام آمادگی به یک مدیر سرویس امکان می‌دهد تا زمان شروع موفقیت‌آمیز pimsync را نظارت کند. هنگامی شروع موفق تلقی می‌شود که فایل پیکربندی تجزیه شده و تمامی اطلاعات احراز هویت تعیین تکلیف شده باشند. در این مرحله، به هیچ تعامل انسانی بیشتری نیاز نخواهد بود.
.Pp
به‌محض آماده شدن سرویس، مقدار
.Ql READY=1
را همراه با یک نویسه خط جدید در توصیف‌گر فایل
.Ar READY_FD
می‌نویسد و سپس آن را می‌بندد. این سازوکار با سازوکار اعلام آمادگی پیاده‌سازی‌شده توسط s6، dinit و systemd سازگار است.
.Pp
ببینید: https://skarnet.org/software/s6/notifywhenup.html
.Sh "حریم خصوصی (PRIVACY)"
تنها ارتباطات شبکه‌ای، با سرورهای مخازن پیکربندی‌شده و تحلیل‌گر DNS پیکربندی‌شده به صورت محلی خواهد بود.
.Pp
فایل پایگاه‌داده وضعیت، شامل فراداده مخازن پیکربندی‌شده، مجموعه‌ها و آیتم‌های آن‌ها است.
.Sh "اعتبارسنجی داده‌ها (DATA VALIDATION)"
داده‌های همگام‌سازی‌شده اعتبارسنجی نمی‌شوند. این یک تصمیم طراحی عامدانه است: اگر برنامه تقویم شما رویدادهایی ایجاد کند که از نظر فنی نامعتبر هستند، pimsync آن‌ها را همگام‌سازی می‌کند و شما قادر خواهید بود به دقیقاً همان داده‌ها روی میزبان‌های دیگر دسترسی داشته باشید. همچنین ممکن است برای برطرف کردن عدم اعتبار داده‌ها، نیاز به همگام‌سازی آن‌ها داشته باشید.
.Pp
به منظور نگاشت آیتم‌ها بین مخازن ذخیره‌سازی، pimsync برای استخراج UID آن‌ها، تجزیه جزئی روی آیتم‌ها انجام می‌دهد. آیتم‌ها حتی در صورت نامعتبر بودن از نظر معنایی، باید مؤلفه‌هایی با نحو معتبر باشند.
.Pp
به منظور تعامل با منابع CalDAV/CardDAV که در آن‌ها استخراج UID امکان‌پذیر نیست، از دستور
.Ic repair
جهت اصلاح ورودی‌های نامعتبر استفاده کنید، یا استفاده از
.Xr davcli 1
را مد نظر قرار دهید.
.Sh "ملاحظات امنیتی (SECURITY CONSIDERATIONS)"
هنگامی که کشف سرویس فعال باشد، نام میزبان و درگاه واقعی سرور DAV با استفاده از رکوردهای DNS تحلیل می‌شود. در این حالت از تحلیل‌گر DNS سیستم استفاده می‌شود. انتظار می‌رود که تحلیل‌گر سیستم اعتبارسنجی DNSSEC را انجام داده و نتایج نامعتبر بازنگرداند. خود pimsync اعتبارسنجی DNSSEC را انجام نمی‌دهد.
.Pp
برنامه pimsync هنگام خواندن آیتم‌ها، پیوندهای نمادین (symlinks) را دنبال می‌کند. در حالتی که کاربری دسترسی نوشتن روی یک مخزن را دارد اما کاربر دیگری pimsync را روی همان مخزن اجرا می‌کند، باید احتیاط شود. این رفتار ممکن است در آینده تغییر کند.
.Pp
آیتم‌ها در مخازن مختلف در صورتی یکسان در نظر گرفته می‌شوند که UID مشترکی داشته باشند. عاملی که بتواند یک آیتم واحد را در یک مخزن در هر یک از طرفین بنویسد، به‌طور بالقوه می‌تواند موجب رونویسی روی آیتم دیگری در مخزن مقابل شود. عاملی که می‌تواند در یک ورودی واحد بنویسد، باید به عنوان عاملی در نظر گرفته شود که دسترسی دستکاری کل مخزن را دارد.
.Pp
برنامه pimsync اطلاعات احراز هویت را در طول تمام مدت اجرای خود در حافظه نگه می‌دارد. هر عاملی با دسترسی خواندن به فضای حافظه pimsync می‌تواند اطلاعات احراز هویت محرمانه را از آن استخراج کند. به همین ترتیب، تخلیه‌های حافظه (core dumps) حاصل از pimsync نباید با طرف‌های غیرقابل‌اعتماد به اشتراک گذاشته شوند.
.Pp
هنگام ثبت لاگ با
.Fl v
.Cm trace ،
لاگ‌ها ممکن است حاوی اطلاعات احراز هویت، اسرار، داده‌های درون آیتم‌های مخزن و سایر اطلاعات حساس باشند..Sh "الگوریتم همگام‌سازی (SYNCHRONISATION ALGORITHM)"
پس از این‌که pimsync دو فضای ذخیره‌سازی را همگام می‌کند، فراداده‌های مربوط به آیتم‌های
همگام‌شده را در پایگاه‌داده وضعیت داخلی خود ذخیره می‌نماید. در طول فرایندهای
همگام‌سازی آتی، اگر آیتم‌های موجود در هر دو فضای ذخیره‌سازی مطابقت نداشته باشند،
از پایگاه‌داده وضعیت برای تعیین این‌که کدام طرف تغییر کرده و کدام طرف مانند دفعه قبل باقی
مانده است استفاده می‌شود. سپس از این اطلاعات برای برنامه‌ریزی این‌که کدام آیتم باید
نگهداری شود و روی کدام‌یک بازنویسی صورت گیرد، استفاده می‌گردد. اگر هر دو آیتم
تغییر کرده باشند، گفته می‌شود که دچار تداخل هستند و تداخل باید به‌صورت دستی
برطرف شود (بخش
.Sx CONFLICT RESOLUTION
در بالا را ببینید).
.Pp
پایگاه‌داده وضعیت فراداده آیتم را با جفت مجموعه‌هایی که با یکدیگر همگام
شده‌اند (که یک «نگاشت» یا «mapping» نامیده می‌شود) مرتبط می‌کند. اگر پیکربندی
تغییر کند و مجموعه‌های متفاوتی با یکدیگر همگام شوند، داده‌های وضعیت برای آیتم‌های
آن‌ها دیگر اعمال نخواهد شد و نادیده گرفته می‌شود. این امر از استفاده تصادفی
از داده‌های نادرست هنگام پیکربندی مجدد نگاشت‌ها جلوگیری می‌کند.
.Pp
این الگوریتم کاملاً بر پایه الگوریتم اصلی vdirsyncer(1) طراحی شده است. جزئیات بیشتر در
https://unterwaditzer.net/2016/sync-algorithm.html
در دسترس است.
.Pp
حذف پایگاه‌داده وضعیت،
.Nm
را وادار می‌کند تا هر دو فضای ذخیره‌سازی را طوری همگام کند که گویی اولین بار است هر
دوی آن‌ها را می‌بیند. آیتم‌هایی که در هر دو طرف وجود دارند و یکسان هستند بدون مشکل خواهند
بود، اما آیتم‌هایی که یکسان نیستند دارای تداخل در نظر گرفته می‌شوند (زیرا
.Nm
نمی‌تواند بدون ابهام تصمیم بگیرد که کدام‌یک را نگه دارد).
.Sh "سازوکارهای حفاظتی (PROTECTIONS)"
هنگامی که تمام آیتم‌های موجود در یک مجموعه حذف شوند، pimsync(1) فرض را بر خطای کاربر
می‌گذارد و از انجام عملیات روی این مجموعه خودداری می‌کند. این رفتار را می‌توان با
دستورالعمل
.Cm on_empty
غیرفعال کرد. برای جزئیات بیشتر به
.Xr pimsync.conf 5
مراجعه کنید.
.Sh "هشدارها (CAVEATS)"
برای فضاهای ذخیره‌سازی از نوع
.Cm vdir ,
بررسی این‌که آیا یک آیتم توسط فرایندی خارجی تغییر یافته است یا خیر، دستخوش شرایط رقابتی (race conditions)
است. Pimsync ابتدا بررسی می‌کند که آیتم تغییر نیافته باشد، و سپس آن را به‌روزرسانی می‌نماید.
اگر برنامه‌ای خارجی همان آیتم را بین بررسی و اعمال تغییر به‌روزرسانی کند، آن تغییرات از دست
خواهند رفت. این مسئله ناشی از محدودیت‌های موجود در توابع اولیه فایل‌سیستم POSIX است. بعید
به نظر می‌رسد که این مشکل قابل رفع باشد.
.Sh "مثال‌ها (EXAMPLES)"
.Bl -tag
.It اجرای دیمن همراه با ثبت دقیق گزارش‌ها (verbose logging):
.D1 pimsync -v info daemon
.It رفع تعاملی تداخل برای جفت با نام contacts:
.D1 pimsync resolve-conflicts contacts
.It نمایش نسخه و خروج:
.D1 pimsync version
.El
.Sh "همچنین ببینید (SEE ALSO)"
.Xr pimsync.conf 5 ,
.Xr pimsync-migration 7 ,
.Xr khal 1 ,
.Xr todoman 1
.Xr sd-ready-fd 1
.Sh "توسعه (DEVELOPMENT)"
برای گزارش مشکلات و پرسش‌های کلی درباره توسعه، صفحه اصلی پروژه را که در حال حاضر
در SourceHut میزبانی می‌شود ببینید: https://sr.ht/~whynothugo/pimsync
.Sh "استانداردها (STANDARDS)"
.Bl -bullet
.It
افزونه‌های تقویم برای WebDAV (CalDAV) همان‌طور که در IETF RFC 4791 مشخص شده، پیاده‌سازی شده است.
.It
افزونه‌های vCard برای WebDAV (CardDAV) همان‌طور که در IETF RFC 4791 مشخص شده، پیاده‌سازی شده است.
.It
کشف سرویس (Service discovery) همان‌طور که در IETF RFC 6764 مشخص شده، پیاده‌سازی شده است.
.It
فضای ذخیره‌سازی vdir طرح‌بندی مشخص‌شده در مشخصات قالب vdir را پیاده‌سازی می‌کند: https://pimutils.org/specs/vdir
.El
.Sh "سپاسگزاری (THANKS)"
توسعه این پروژه با تأمین مالی و پشتیبانی بنیاد NLnet و برنامه NGI Zero Entrust از کمیسیون اروپا امکان‌پذیر شده است.
ببینید:
.Bl -bullet
.It
https://nlnet.nl/project/vdirsyncer
.It
https://www.ngi.eu/ngi-projects/ngi-zero-entrust
.El
.Pp
یک ممیزی امنیتی توسط Radically Open Security انجام شده است:
.Bl -bullet
.It
https://www.radicallyopensecurity.com
.El.Sh "تاریخچه (HISTORY)"
دستور
.Xr vdirsyncer 1
نخستین بار در سال ۲۰۱۴ توسط Markus Unterwaditzer پیاده‌سازی شد. کار بر روی دستور
.Nm
که از
.Xr vdirsyncer 1
الهام نزدیکی گرفته است، در سال ۲۰۲۲ توسط Hugo Barrera آغاز شد.
.Pp
سرواژهٔ
.Qq pim
به
.Qq personal information management
(مدیریت اطلاعات شخصی) اشاره دارد.
.Sh "نویسندگان (AUTHORS)"
.Nm
توسط Hugo O. Barrera <hugo@whynothugo.nl> توسعه داده می‌شود.
.Pp
.Nm
یک پروژه متن‌باز است که برای استفاده آزاد همگان توسعه یافته است. اگر مایل به حمایت مالی از این پروژه هستید، به https://whynothugo.nl/sponsor مراجعه کنید.