PIMSYNC(1) General Commands Manual PIMSYNC(1)

pimsync — همگام‌سازی caldav، carddav، webcal و دایرکتوری‌های محلی

pimsync [-c configfile] [-v loglevel] command [pair…] pimsync version

pimsync تقویم‌ها و مخاطبین را همگام‌سازی می‌کند. برای تقویم‌ها، از کار با دایرکتوری‌های محلی، سرورهای CalDAV یا URLهای Webcal پشتیبانی می‌کند. برای مخاطبین، از کار با دایرکتوری‌های محلی یا سرورهای CardDav پشتیبانی می‌کند.

واژه‌نامه اصطلاحات مربوطه:

یک رویداد، وظیفه (todo)، یادداشت روزانه یا مخاطب منفرد.
گروه‌بندی چندین مورد (item). می‌تواند یکی از موارد روبرو باشد: (۱) یک تقویم منفرد که شامل رویدادها، وظایف و/یا یادداشت‌های روزانه است، یا (۲) یک دفترچه نشانی که حاوی مخاطبین است.
مکانی که شامل چندین مجموعه (collection) است. برای مثال: یک حساب در یک سرور CalDAV، یا یک دایرکتوری محلی به همراه زیردایرکتوری‌ها، که هرکدام نشان‌دهنده یک تقویم هستند. برای جزئیات مربوط به پیاده‌سازی‌های ذخیره‌سازی پشتیبانی‌شده و پیکربندی آن‌ها، pimsync.conf(5) را ببینید.
دو فضای ذخیره‌سازی (storage) که برای همگام‌سازی با یکدیگر پیکربندی شده‌اند. یک فضای ذخیره‌سازی منفرد ممکن است بخشی از چند جفت (pair) باشد.
هنگام همگام‌سازی دو فضای ذخیره‌سازی، اگر یک مورد (item) منفرد در هر دو طرف تغییر کرده باشد اما محتوای متفاوتی در دو طرف داشته باشد، گفته می‌شود که آن مورد در تداخل (conflict) است.
صفت فراداده‌ای که به یک مجموعه (collection) اعمال می‌شود. مثال‌ها: displayname، colour، order.
یک مورد (item) یا یک مجموعه (collection). این اصطلاح بیشتر به‌صورت داخلی و در لاگ‌ها استفاده می‌شود.

configfile
فایل پیکربندی را به‌جای پیش‌فرض، از مسیر مشخص‌شده بخوانید. بخش FILES در زیر و pimsync.conf(5) را ببینید.
loglevel
سطح ثبت گزارش (logger) را روی loglevel تنظیم می‌کند، که باید یکی از مقادیر trace ، debug ، info ، warn یا error باشد. مقدار پیش‌فرض warn است. هنگام تعیین trace ، ممکن است لاگ‌ها حاوی داده‌های حساس باشند؛ بخش SECURITY CONSIDERATIONS در زیر را ببینید.

[pair…]
پیکربندی را بررسی کرده و خارج می‌شود. خود پیکربندی را اعتبارسنجی می‌کند و اطمینان حاصل می‌کند که فضای ذخیره‌سازی معتبر است. برای مثال: یک vdir باید یک دایرکتوری موجود باشد، و سرور caldav باید قابلیت‌های CalDAV را گزارش کند، و غیره.
[pair…]
فضا‌های ذخیره‌سازی را به‌طور مداوم همگام نگه می‌دارد. آرگومان -r READY_FD ممکن است برای ارائه یک توصیف‌گر فایل اعلان آمادگی استفاده شود.

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

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

[pair…]
مجموعه‌ها را شناسایی کرده و نمایش می‌دهد. این فرمان صرفاً اطلاعات ارائه می‌دهد و به هیچ وجه وضعیت داخلی pimsync را تغییر نمی‌دهد.
[pair…]
تداخل‌های بین فضا‌های ذخیره‌سازی را به‌صورت دستی برطرف می‌کند.

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

[-n [-i [pair…]]]
فضا‌های ذخیره‌سازی را یک بار همگام‌سازی کرده و خارج می‌شود. پرچم -n یک اجرای آزمایشی (dry run) انجام می‌دهد و هیچ عملیات نوشتنی انجام نخواهد داد. پرچم -i حالت تعاملی را فعال می‌کند و قبل از ادامه همگام‌سازی، تأیید برنامه را درخواست می‌کند.
[storage…]
موارد نامعتبر را تعمیر می‌کند. در حال حاضر، این فرمان فیلدهای UID ناموجود را اضافه می‌کند، اما در آینده اصلاحات دیگری نیز گنجانده خواهد شد. تعمیر هم‌زمان هر دو مجموعه از یک جفت به‌شدت نهی می‌شود؛ در عوض، یک فضای ذخیره‌سازی را تعمیر کرده و سپس آن جفت را همگام‌سازی کنید.
اطلاعات نسخه را چاپ کرده و خارج می‌شود.

اگر یک pair مشخص شده باشد، تنها روی جفت(های) با نام(های) داده‌شده عملیات انجام می‌شود..Sh "محیط (ENVIRONMENT)"

در صورت تعریف شدن، فایل پیکربندی نسبت به این دایرکتوری جستجو می‌شود. بخش فایل‌ها (FILES) در زیر را ببینید.

اگر XDG_CONFIG_HOME تعریف شده باشد، پیکربندی از این مسیر خوانده می‌شود:

$XDG_CONFIG_HOME/pimsync/pimsync.conf

در صورتی که متغیر بالا تعریف نشده باشد، فایل پیکربندی از این مسیر خوانده خواهد شد:

~/.config/pimsync/pimsync.conf

برای جزئیات مربوط به قالب فایل پیکربندی، pimsync.conf(5) را ببینید.

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

به‌محض آماده شدن سرویس، مقدار ‘READY=1’ را همراه با یک نویسه خط جدید در توصیف‌گر فایل READY_FD می‌نویسد و سپس آن را می‌بندد. این سازوکار با سازوکار اعلام آمادگی پیاده‌سازی‌شده توسط s6، dinit و systemd سازگار است.

ببینید: https://skarnet.org/software/s6/notifywhenup.html

تنها ارتباطات شبکه‌ای، با سرورهای مخازن پیکربندی‌شده و تحلیل‌گر DNS پیکربندی‌شده به صورت محلی خواهد بود.

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

داده‌های همگام‌سازی‌شده اعتبارسنجی نمی‌شوند. این یک تصمیم طراحی عامدانه است: اگر برنامه تقویم شما رویدادهایی ایجاد کند که از نظر فنی نامعتبر هستند، pimsync آن‌ها را همگام‌سازی می‌کند و شما قادر خواهید بود به دقیقاً همان داده‌ها روی میزبان‌های دیگر دسترسی داشته باشید. همچنین ممکن است برای برطرف کردن عدم اعتبار داده‌ها، نیاز به همگام‌سازی آن‌ها داشته باشید.

به منظور نگاشت آیتم‌ها بین مخازن ذخیره‌سازی، pimsync برای استخراج UID آن‌ها، تجزیه جزئی روی آیتم‌ها انجام می‌دهد. آیتم‌ها حتی در صورت نامعتبر بودن از نظر معنایی، باید مؤلفه‌هایی با نحو معتبر باشند.

به منظور تعامل با منابع CalDAV/CardDAV که در آن‌ها استخراج UID امکان‌پذیر نیست، از دستور repair جهت اصلاح ورودی‌های نامعتبر استفاده کنید، یا استفاده از davcli(1) را مد نظر قرار دهید.

هنگامی که کشف سرویس فعال باشد، نام میزبان و درگاه واقعی سرور DAV با استفاده از رکوردهای DNS تحلیل می‌شود. در این حالت از تحلیل‌گر DNS سیستم استفاده می‌شود. انتظار می‌رود که تحلیل‌گر سیستم اعتبارسنجی DNSSEC را انجام داده و نتایج نامعتبر بازنگرداند. خود pimsync اعتبارسنجی DNSSEC را انجام نمی‌دهد.

برنامه pimsync هنگام خواندن آیتم‌ها، پیوندهای نمادین (symlinks) را دنبال می‌کند. در حالتی که کاربری دسترسی نوشتن روی یک مخزن را دارد اما کاربر دیگری pimsync را روی همان مخزن اجرا می‌کند، باید احتیاط شود. این رفتار ممکن است در آینده تغییر کند.

آیتم‌ها در مخازن مختلف در صورتی یکسان در نظر گرفته می‌شوند که UID مشترکی داشته باشند. عاملی که بتواند یک آیتم واحد را در یک مخزن در هر یک از طرفین بنویسد، به‌طور بالقوه می‌تواند موجب رونویسی روی آیتم دیگری در مخزن مقابل شود. عاملی که می‌تواند در یک ورودی واحد بنویسد، باید به عنوان عاملی در نظر گرفته شود که دسترسی دستکاری کل مخزن را دارد.

برنامه pimsync اطلاعات احراز هویت را در طول تمام مدت اجرای خود در حافظه نگه می‌دارد. هر عاملی با دسترسی خواندن به فضای حافظه pimsync می‌تواند اطلاعات احراز هویت محرمانه را از آن استخراج کند. به همین ترتیب، تخلیه‌های حافظه (core dumps) حاصل از pimsync نباید با طرف‌های غیرقابل‌اعتماد به اشتراک گذاشته شوند.

هنگام ثبت لاگ با -v trace ، لاگ‌ها ممکن است حاوی اطلاعات احراز هویت، اسرار، داده‌های درون آیتم‌های مخزن و سایر اطلاعات حساس باشند..Sh "الگوریتم همگام‌سازی (SYNCHRONISATION ALGORITHM)" پس از این‌که pimsync دو فضای ذخیره‌سازی را همگام می‌کند، فراداده‌های مربوط به آیتم‌های همگام‌شده را در پایگاه‌داده وضعیت داخلی خود ذخیره می‌نماید. در طول فرایندهای همگام‌سازی آتی، اگر آیتم‌های موجود در هر دو فضای ذخیره‌سازی مطابقت نداشته باشند، از پایگاه‌داده وضعیت برای تعیین این‌که کدام طرف تغییر کرده و کدام طرف مانند دفعه قبل باقی مانده است استفاده می‌شود. سپس از این اطلاعات برای برنامه‌ریزی این‌که کدام آیتم باید نگهداری شود و روی کدام‌یک بازنویسی صورت گیرد، استفاده می‌گردد. اگر هر دو آیتم تغییر کرده باشند، گفته می‌شود که دچار تداخل هستند و تداخل باید به‌صورت دستی برطرف شود (بخش CONFLICT RESOLUTION در بالا را ببینید).

پایگاه‌داده وضعیت فراداده آیتم را با جفت مجموعه‌هایی که با یکدیگر همگام شده‌اند (که یک «نگاشت» یا «mapping» نامیده می‌شود) مرتبط می‌کند. اگر پیکربندی تغییر کند و مجموعه‌های متفاوتی با یکدیگر همگام شوند، داده‌های وضعیت برای آیتم‌های آن‌ها دیگر اعمال نخواهد شد و نادیده گرفته می‌شود. این امر از استفاده تصادفی از داده‌های نادرست هنگام پیکربندی مجدد نگاشت‌ها جلوگیری می‌کند.

این الگوریتم کاملاً بر پایه الگوریتم اصلی vdirsyncer(1) طراحی شده است. جزئیات بیشتر در https://unterwaditzer.net/2016/sync-algorithm.html در دسترس است.

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

هنگامی که تمام آیتم‌های موجود در یک مجموعه حذف شوند، pimsync(1) فرض را بر خطای کاربر می‌گذارد و از انجام عملیات روی این مجموعه خودداری می‌کند. این رفتار را می‌توان با دستورالعمل on_empty غیرفعال کرد. برای جزئیات بیشتر به pimsync.conf(5) مراجعه کنید.

برای فضاهای ذخیره‌سازی از نوع vdir, بررسی این‌که آیا یک آیتم توسط فرایندی خارجی تغییر یافته است یا خیر، دستخوش شرایط رقابتی (race conditions) است. Pimsync ابتدا بررسی می‌کند که آیتم تغییر نیافته باشد، و سپس آن را به‌روزرسانی می‌نماید. اگر برنامه‌ای خارجی همان آیتم را بین بررسی و اعمال تغییر به‌روزرسانی کند، آن تغییرات از دست خواهند رفت. این مسئله ناشی از محدودیت‌های موجود در توابع اولیه فایل‌سیستم POSIX است. بعید به نظر می‌رسد که این مشکل قابل رفع باشد.

اجرای دیمن همراه با ثبت دقیق گزارش‌ها (verbose logging):
pimsync -v info daemon
رفع تعاملی تداخل برای جفت با نام contacts:
pimsync resolve-conflicts contacts
نمایش نسخه و خروج:
pimsync version

pimsync.conf(5), pimsync-migration(7), khal(1), todoman(1) sd-ready-fd(1)

برای گزارش مشکلات و پرسش‌های کلی درباره توسعه، صفحه اصلی پروژه را که در حال حاضر در SourceHut میزبانی می‌شود ببینید: https://sr.ht/~whynothugo/pimsync

  • افزونه‌های تقویم برای WebDAV (CalDAV) همان‌طور که در IETF RFC 4791 مشخص شده، پیاده‌سازی شده است.
  • افزونه‌های vCard برای WebDAV (CardDAV) همان‌طور که در IETF RFC 4791 مشخص شده، پیاده‌سازی شده است.
  • کشف سرویس (Service discovery) همان‌طور که در IETF RFC 6764 مشخص شده، پیاده‌سازی شده است.
  • فضای ذخیره‌سازی vdir طرح‌بندی مشخص‌شده در مشخصات قالب vdir را پیاده‌سازی می‌کند: https://pimutils.org/specs/vdir

توسعه این پروژه با تأمین مالی و پشتیبانی بنیاد NLnet و برنامه NGI Zero Entrust از کمیسیون اروپا امکان‌پذیر شده است. ببینید:

یک ممیزی امنیتی توسط Radically Open Security انجام شده است:

  • https://www.radicallyopensecurity.com دستور vdirsyncer(1) نخستین بار در سال ۲۰۱۴ توسط Markus Unterwaditzer پیاده‌سازی شد. کار بر روی دستور pimsync که از vdirsyncer(1) الهام نزدیکی گرفته است، در سال ۲۰۲۲ توسط Hugo Barrera آغاز شد.

    سرواژهٔ "pim" به "personal information management" (مدیریت اطلاعات شخصی) اشاره دارد.

pimsync توسط Hugo O. Barrera <hugo@whynothugo.nl> توسعه داده می‌شود.

pimsync یک پروژه متن‌باز است که برای استفاده آزاد همگان توسعه یافته است. اگر مایل به حمایت مالی از این پروژه هستید، به https://whynothugo.nl/sponsor مراجعه کنید.

2025-04-14 PIMSYNC