.Dd 2025-04-14
.Dt PIMSYNC.CONF 5
.\" TODO: replace the following line with the version at build time.
.Os PIMSYNC
.Sh "نام (NAME)"
.Nm pimsync.conf
.Nd فایل پیکربندی برای ابزار pimsync
.Sh "توضیحات (DESCRIPTION)"
.Nm
به سه نوع بخش اصلی تقسیم می‌شود:
.Bl -tag -width xxxx
.It Sx "پیکربندی سراسری (GLOBAL CONFIGURATION)"
تنظیمات سراسری برای pimsync.
.It Sx "بخش‌های فضای ذخیره‌سازی (STORAGE SECTIONS)"
پیکربندی برای فضاهای ذخیره‌سازی مجزا.
.It Sx "بخش‌های جفت (PAIR SECTIONS)"
قوانین همگام‌سازی جفت‌های فضای ذخیره‌سازی.
.El
.Pp
برای اطلاع از جزئیات مسیر پیش‌فرض فایل پیکربندی و نحوه تعیین مسیر جایگزین، به
.Xr pimsync 1
مراجعه کنید.
.Sh "پیکربندی سراسری (GLOBAL CONFIGURATION)"
تنظیمات زیر را می‌توان به صورت سراسری پیکربندی کرد:
.Bl -tag -width xxxx
.It Ic status_path Pa path
مسیر دایرکتوری‌ای که پایگاه‌داده وضعیت مورد استفاده داخلی
.Nm
در آن نگهداری خواهد شد.
.El
.\" Defaults to *XDG_DATA_HOME/pimsync/status/*.
.Sh "بخش‌های فضای ذخیره‌سازی (STORAGE SECTIONS)"
یک فضای ذخیره‌سازی (storage)، مکانی را توصیف می‌کند که تقویم‌ها یا مخاطبین در آن ذخیره می‌شوند. هر فضای ذخیره‌سازی در بخش اختصاصی خود تعریف می‌شود و هر بخش ذخیره‌سازی با اعلان نام آن فضا آغاز می‌گردد.
.Bl -tag -width xxxx
.It Ic storage Ar name Brq …
اعلان یک فضای ذخیره‌سازی با نام
.Ar name .
.El
.Pp
دستورالعمل‌ها در داخل آکولادها برای هر بخش و در هر سطر یک دستورالعمل تعریف می‌شوند. دستورالعمل‌های زیر برای تمامی انواع فضاهای ذخیره‌سازی اعمال می‌شوند:
.Bl -tag -width xxxx
.It Ic type Ar type
که در آن
.Ar type
می‌تواند یکی از موارد زیر باشد:
.Bl -tag -width xxxx
.It Ic vdir/icalendar
دایرکتوری‌ای که هر زیردایرکتوری آن نشان‌دهنده یک تقویم است. هر یک از این زیردایرکتوری‌ها شامل فایل‌های مجزای icalendar هستند که هر کدام نشان‌دهنده یک رویداد (یا یک سری رویدادهای تکرارشونده)، کار (todo) یا یادداشت روزانه (journal entry) می‌باشند.
.It Ic vdir/vcard
دایرکتوری‌ای که هر زیردایرکتوری آن نشان‌دهنده یک دفترچه نشانی است. هر یک از این زیردایرکتوری‌ها شامل فایل‌های مجزای vcard هستند که هر کدام نشان‌دهنده یک مخاطب است.
.It Ic caldav
یک سرور CalDAV شامل تقویم‌هایی با رویدادها، کارها و/یا یادداشت‌های روزانه.
.It Ic carddav
یک سرور CardDAV شامل دفترچه‌های نشانی با مخاطبین.
.It Ic webcal
یک منبع HTTP یا HTTPS که یک فایل منفرد iCalendar را ارائه می‌دهد و ممکن است شامل صفر یا چند رویداد، کار یا یادداشت روزانه باشد. این فضای ذخیره‌سازی فقط‌خواندنی است.
.It Ic jmap/icalendar
یک سرور JMAP با پشتیبانی از تقویم. این فضای ذخیره‌سازی آزمایشی است و ممکن است همچنان دارای اشکالات جدی باشد!
.It Ic jmap/vcard
یک سرور JMAP با پشتیبانی از مخاطبین. این فضای ذخیره‌سازی آزمایشی است و ممکن است همچنان دارای اشکالات جدی باشد!
.El
.It Ic interval Ar seconds
زمانی که پایش یک فضای ذخیره‌سازی امکان‌پذیر نباشد، تغییرات را در هر بازه زمانی مشخص‌شده بر حسب ثانیه بررسی می‌کند. مقدار پیش‌فرض ۳۰۰ ثانیه است.
.It Ic read_only
هیچ عملیات نوشتنی روی این فضای ذخیره‌سازی انجام نشود. این دستورالعمل هیچ آرگومانی نمی‌پذیرد.
.El
.Pp
فضاهای ذخیره‌سازی از نوع
.Ic vdir
دستورالعمل‌های زیر را می‌پذیرند:
.\" TODO: should point to docs for *vdir*.
.Bl -tag -width xxxx
.It Ic path Ar path
مسیر دایرکتوری ذخیره‌کننده یک vdir. علامت تیلدا (~) در ابتدای مسیر به دایرکتوری خانگی کاربر جاری گسترش می‌یابد.
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.It Ic fileext Ar extension
اختیاری. پسوند فایل برای آیتم‌های ذخیره‌شده در این vdir. در صورت عدم تعیین،
.Cm ics
برای فضاهای ذخیره‌سازی تقویم و
.Cm vcf
برای فضاهای ذخیره‌سازی دفترچه نشانی استفاده می‌شود.
.El
.Pp
فضاهای ذخیره‌سازی از نوع
.Ic caldav
یا
.Ic carddav
دستورالعمل‌های زیر را می‌پذیرند:
.Bl -tag -width xxxx
.It Ic url Ar url
نشانی URL سرور Dav. اگر این نشانی قابلیت‌های مناسب DAV را گزارش نکند، کشف سرویس (service discovery) برای این URL و دامنه آن انجام می‌شود تا مکان دقیق سرور و مجموعه خانگی (home set collection) پیدا شود.
.Pp
نشانی‌های URL باید طرح‌واره
.Cm http ،
.Cm https
یا
.Cm unix
را مشخص کنند. نشانی‌های شروع‌شونده با
.Ar unix://
به عنوان مسیر سوکت دامین یونیکس تلقی خواهند شد.
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.It Ic username Ar username
اختیاری. نام کاربری برای احراز هویت اولیه HTTP (Basic Auth).
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.It Ic password Ar password
اختیاری. گذرواژه برای احراز هویت اولیه HTTP (Basic Auth).
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.It Ic collection_id_segment Cm last | second-last
اختیاری. بخش مسیر URL برای استفاده به عنوان شناسه مجموعه. مقادیر معتبر عبارتند از
.Cm last
(پیش‌فرض) یا
.Cm second-last .
برای جزئیات بیشتر به مستندات استفاده پیشرفته مراجعه کنید.
.\" TODO: directive to service discovery
.El
.Pp
فضاهای ذخیره‌سازی از نوع
.Ic webcal
دستورالعمل‌های زیر را می‌پذیرند:
.Bl -tag -width xxxx
.It Ic url Ar url
نشانی URL یک فایل icalendar. این فایل ممکن است شامل چندین آیتم تقویم باشد. طرح‌واره پروتکل باید
.Cm http
یا
.Cm https
باشد.
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.It Ic collection_id Ar name
نامی که هنگام نگاشت این مجموعه به مجموعه‌ای دیگر در فضای ذخیره‌سازی طرف مقابل استفاده می‌شود.
.El
.Pp
فضاهای ذخیره‌سازی از نوع
.Ic jmap
دستورالعمل‌های زیر را می‌پذیرند:
.Bl -tag -width xxxx
.It Ic url Ar url
نشانی URL پایه سرور JMAP.
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.It Ic username Ar username
اختیاری. نام کاربری برای احراز هویت اولیه HTTP (Basic Auth).
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.It Ic password Ar password
اختیاری. گذرواژه برای احراز هویت اولیه HTTP (Basic Auth).
.Pp
از
.Sx "پارامترهای پویا (DYNAMIC PARAMETERS)"
پشتیبانی می‌کند (بخش زیر را ببینید).
.El
.Pp
فضاهای ذخیره‌سازی از نوع
.Cm caldav ،
.Cm carddav ،
.Cm webcal
و
.Cm jmap
همچنین دستورالعمل‌های زیر را می‌پذیرند:
.Bl -tag -width xxxx
.It Ic user_agent Ar user_agent
اختیاری. تنظیم هدر User-Agent به
.Ar user_agent
برای درخواست‌های HTTP خروجی. پیش‌فرض از
.Dq pimsync/
به همراه شماره نسخه جاری استفاده می‌کند. به عنوان مثال:
.Ar pimsync/1.0.0 .
.It Ic tls_root Ar path
اختیاری. استفاده از مخزن ریشه گواهی در
.Ar path
هنگام بررسی گواهی TLS سرور. این گزینه بررسی گواهی در برابر مرجع‌های صدور گواهی (CA) سیستم را غیرفعال می‌کند. بخش
.Ic tls_fingerprint
در زیر را ببینید.
.It Ic tls_fingerprint Ar fingerprint
اختیاری. پذیرش گواهی در صورتی که اثر انگشت آن با
.Ar fingerprint
مطابقت داشته باشد. اگر همراه با دستورالعمل
.Ic tls_root
مشخص شود، گواهی با ریشه مشخص‌شده اعتبارسنجی می‌شود. اگر
.Ic tls_root
مشخص نشود، گواهی سرور در برابر هیچ ریشه‌ای اعتبارسنجی نمی‌شود و تنها بررسی اثر انگشت انجام می‌پذیرد.
.It Ic auth_cert Ar certificate Ar key
اختیاری. استفاده از
.Ar certificate
و
.Ar key
ارائه‌شده برای احراز هویت کلاینت TLS.
.It Ic auth_cert Ar pem_bundle
اختیاری. استفاده از گواهی و کلید موجود در بسته مشخص‌شده برای احراز هویت کلاینت TLS.
.El
.Sh "پارامترهای پویا (DYNAMIC PARAMETERS)"
فیلدهای
.Ic url ،
.Ic username ،
.Ic password
و
.Ic path
می‌توانند در فایل پیکربندی تعریف شوند، یا می‌توانند یک بلوک به همراه یک دستور را برای دریافت این مقدار از یک سیستم خارجی مشخص کنند. هنگام تعیین یک دستور خارجی، به جای تعریف مقدار مستقیم برای دستورالعمل، یک بلوک جدید با یک دستورالعمل منفرد
.Ic cmd
مشخص کنید.
.Pp
برای مثال، برای خواندن گذرواژه از طریق دستور خارجی
.Ar secret-store --get-caldav-password ،
از ساختار نحوی زیر استفاده کنید:
.Bd -literal -offset indent
password {
	cmd secret-store --get-caldav-password
}
.Ed
.Pp
همچنین می‌توان یک اسکریپت شل را مشخص کرد که از طریق
.Ql sh -c
اجرا می‌شود. به عنوان مثال:
.Bd -literal -offset indent
password {
	shell pass show communication/migadu.com | head -1
}
.Ed
.Pp
توصیه می‌شود اطلاعات هویتی و سایر مقادیر حساس در یک سرویس ذخیره‌سازی محرمانه نگهداری شوند.
.Sh "بخش‌های جفت (PAIR SECTIONS)"
یک جفت (pair) نحوه همگام‌سازی دو فضای ذخیره‌سازی با یکدیگر را اعلام می‌کند. هر بخش جفت با اعلان نام جفت آغاز می‌شود:
.Bl -tag -width xxxx
.It Ic pair Ar name Brq …
اعلان یک جفت با نام
.Ar name .
.El
.Pp
هر جفت توسط بلوکی از دستورالعمل‌ها، یک دستور در هر خط، محصور در آکولادها تعریف می‌شود:
.Bl -tag -width xxxx
.It Ic storage_a Ar name
نام (
.Ar name
) اولین فضای ذخیره‌سازی برای همگام‌سازی با دیگری.
.It Ic storage_b Ar name
نام (
.Ar name
) دومین فضای ذخیره‌سازی برای همگام‌سازی با دیگری.
.It Ic collections Cm all
همگام‌سازی تمام مجموعه‌های یافت‌شده در هر دو فضای ذخیره‌سازی. مجموعه‌ها با موارد دارای شناسه منطبق در طرف دیگر همگام‌سازی خواهند شد. اگر صرفاً می‌خواهید تمام مجموعه‌ها را از هر دو فضای ذخیره‌سازی همگام کنید، این مقدار پیشنهادی است.
.It Ic collections Cm from a
همگام‌سازی تمام مجموعه‌های یافت‌شده در
.Ar storage_a .
هر مجموعه با مجموعه‌ای که همان شناسه را در
.Ar storage_b
دارد همگام‌سازی خواهد شد.
.It Ic collections Cm from b
همگام‌سازی تمام مجموعه‌های یافت‌شده در
.Ar storage_b .
هر مجموعه با مجموعه‌ای که همان شناسه را در
.Ar storage_a
دارد همگام‌سازی خواهد شد.
.It Ic collection Ar id
همگام‌سازی مجموعه با شناسه
.Ar id .
می‌توان بیش از یک بار این دستورالعمل را مشخص کرد.
.It Ic collection Ar Brq …
همگام‌سازی مجموعه تعریف‌شده توسط قوانین داده‌شده. به بخش
.Sx "بخش‌های مجموعه (COLLECTION SECTIONS)"
در زیر مراجعه کنید. می‌تواند بیش از یک بار مشخص شود.
.It Ic on_empty Cm skip
هنگامی که یک مجموعه در یک طرف کاملاً خالی شد، از آن صرف‌نظر شود. این حالت پیش‌فرض است.
.It Ic on_empty Cm sync
هنگامی که یک مجموعه در یک طرف کاملاً خالی شد، همتای آن در طرف دیگر نیز خالی شود. هنگام استفاده از این گزینه احتیاط کنید. اگر یک مجموعه را در یک طرف کاملاً حذف کنید،
.Nm
آن را بازیابی نخواهد کرد؛ بلکه همان مجموعه (و تمامی موارد آن) را در طرف دیگر نیز حذف می‌کند.
.It Ic on_delete Cm sync
هنگامی که خود یک مجموعه در یک طرف حذف شد، در طرف دیگر نیز حذف شود. این مورد تنها در صورتی اعمال می‌شود که مجموعه از قبل خالی باشد. این حالت پیش‌فرض است و عموماً ایمن می‌باشد، به‌ویژه زمانی که با
.Cm on_empty skip
ترکیب شود.
.It Ic on_delete Cm skip
هنگامی که خود یک مجموعه در یک طرف حذف شد، از آن صرف‌نظر شود.
.It Ic one_way
همگام‌سازی آیتم‌ها فقط از
.Ar storage_a
به
.Ar storage_b .
تغییرات در
.Ar storage_b
با داده‌های
.Ar storage_a
بازنویسی می‌شوند. آیتم‌های ایجادشده در
.Ar storage_b
که در
.Ar storage_a
وجود ندارند حذف خواهند شد. این حالت هرگز تداخل (conflict) ایجاد نمی‌کند. این دستورالعمل هیچ پارامتری نمی‌پذیرد.
.El
.Pp
دستورالعمل
.Ic conflict_resolution
مشخص می‌کند در صورتی که یک آیتم در هر دو طرف تغییر کرده باشد چه اقدامی باید انجام گیرد. این دستورالعمل هنگام همگام‌سازی یک‌طرفه تأثیری ندارد.
.Bl -tag -width xxxx
.It Ic conflict_resolution Cm cmd Ar command Op Ar args
اجرای دستور
.Ar command
برای حل تداخل میان هر دو طرف.
.Ar args
به عنوان آرگومان‌ها ارسال می‌شوند و به دنبال آن مسیر دو فایل قرار می‌گیرد؛ یکی حاوی داده‌های موجود در storage a و دیگری حاوی داده‌های storage b. تداخل تنها در صورتی حل‌شده تلقی می‌شود که پس از خروج دستور، هر دو فایل یکسان باشند و دستور با کد خروج صفر خاتمه یابد.
.It Ic conflict_resolution Cm keep a
در صورت بروز تداخل، نسخه مربوط به storage a حفظ شود.
.It Ic conflict_resolution Cm keep b
در صورت بروز تداخل، نسخه مربوط به storage b حفظ شود.
.El
.Sh "بخش‌های مجموعه (COLLECTION SECTIONS)"
یک بلوک collections نگاشتی را میان دو مجموعه که قرار است همگام شوند تعریف می‌کند؛ یکی از آن‌ها در
.Ar storage_a
و دیگری در
.Ar storage_b .
.Pp
این بخش‌ها تنها در پیکربندی‌های پیشرفته‌ای استفاده می‌شوند که نیاز دارند مجموعه‌های موجود را بدون تغییر مکان در هر یک از دو طرف، به یکدیگر نگاشت کنند.
.Pp
هر بلوک باید شامل یک نام مستعار (alias) باشد:
.Bl -tag -width xxxx
.It Ic alias Ar name
یک نام مستعار برای این جفت مجموعه که برای هر خروجی استفاده خواهد شد.
.El
.Pp
دقیقاً یک ارجاع به مجموعه‌ای در
.Ar storage_a
باید گنجانده شود:
.Bl -tag -width xxxx
.It Ic id_a Ar id
استفاده از مجموعه با شناسه
.Ar id .
.It Ic href_a Ar href
استفاده از مجموعه با مسیر
.Ar href .
.El
.Pp
دقیقاً یک ارجاع به مجموعه‌ای در
.Ar storage_b
باید گنجانده شود:
.Bl -tag -width xxxx
.It Ic id_b Ar id
استفاده از مجموعه با شناسه
.Ar id .
.It Ic href_b Ar href
استفاده از مجموعه با مسیر
.Ar href .
.El
.Pp
برای مثال، جهت همگام‌سازی مجموعه‌ای با شناسه
.Ar work
با مجموعه‌ای دیگر در مسیر
.Ar /calendars/mine/work/ ،
از ساختار زیر استفاده کنید:
.Bd -literal -offset indent
collection {
	alias work
	id_a work
	href_b /calendars/mine/work/
}
.Ed
تعیین هم‌زمان id و href برای یک فضای ذخیره‌سازی مجاز نیست.
.Sh "شناسه مجموعه (COLLECTION ID)"
شناسه یک مجموعه مفهومی مختص به
.Xr pimsync 1
و
.Xr vdirsyncer 1
است.
.Pp
برای فضاهای ذخیره‌سازی
.Ic vdir ،
شناسه یک مجموعه همان نام دایرکتوری متناظر با آن است.
.Pp
برای فضاهای ذخیره‌سازی
.Ic caldav
یا
.Ic carddav ،
شناسه یک مجموعه به صورت پیش‌فرض آخرین مؤلفه نشانی URL آن است. این رفتار را می‌توان از طریق دستورالعمل پیکربندی
.Ic collection_id_segment
به استفاده از مؤلفه یکی مانده به آخر تغییر داد.
.Pp
برای فضاهای ذخیره‌سازی
.Ic webcal ،
شناسه باید صریحاً از طریق دستورالعمل پیکربندی
.Ic collection_id
مشخص گردد.
.Pp
مگر اینکه به گونه‌ای دیگر پیکربندی شده باشد، مجموعه‌های دارای شناسه یکسان در هر دو فضای ذخیره‌سازی با یکدیگر همگام می‌شوند.
.Sh "مثال‌ها (EXAMPLES)"
این مثال دو فضای ذخیره‌سازی حاوی دفترچه‌های نشانی را همگام‌سازی می‌کند. اولی مجموعه‌ای محلی از دایرکتوری‌ها شامل فایل‌های vCard و دومی یک سرور راه دور CardDAV است. اطلاعات ورود از طریق ابزار خط فرمان
.Xr hiq 1
تأمین می‌شوند.
.\" TODO: link vdir man page above
.Bd -literal -offset indent
status_path "~/.local/share/pimsync/status/"

pair contacts {
	storage_a contacts_local
	storage_b contacts_remote
	collections all
	conflict_resolution cmd nvim -d
}

storage contacts_local {
	type vdir/vcard
	path ~/.local/share/contacts/cards/
	fileext vcf
	interval 30
}

storage contacts_remote {
	type carddav
	url https://carddav.example.com
	username hugo@example.com
	password {
		cmd hiq -dFpassword proto=carddavs username=hugo@example.com
	}
	interval 30
}
.Ed
.Pp
مثال زیر دو فضای ذخیره‌سازی با داده‌های تقویم را همگام می‌کند. اولی دایرکتوری‌های محلی با فایل‌های iCalendar و دومی یک سرور راه دور CalDAV است.
.Bd -literal -offset indent
status_path "~/.local/share/pimsync/status/"

pair calendars {
	storage_a calendars_local
	storage_b calendars_remote
	collections from b
	conflict_resolution cmd nvim -d
}

storage calendars_local {
	type vdir/icalendar
	path ~/.local/share/calendars/
	fileext ics
	interval 30
}

storage calendars_remote {
	type caldav
	url https://caldav.example.com
	username hugo@example.com
	password {
	 cmd hiq -dFpassword proto=caldavs username=hugo@example.com
	}
	interval 30
}
.Ed
.Pp
مثال زیر دو فضای ذخیره‌سازی با داده‌های تقویم را همگام‌سازی می‌کند. اولی یک دایرکتوری محلی به نام "italki" با فایل‌های تقویم است و دومی یک سرور http که یک فایل iCalendar را منتشر می‌کند.
.Pp
توجه داشته باشید که فضای ذخیره‌سازی اول مشابه مورد بالا است و در صورتی که هر دو پیکربندی در یک فایل مشخص شده باشند، باید تنها یک بار تعریف شود.
.Pp
نشانی دقیق فایل iCalendar ارائه‌شده از طریق http با ابزار
.Xr hiq 1
دریافت می‌شود که برای پرس‌وجو از مخزن امنیتی
.Xr himitsu 7
به کار می‌رود.
.Bd -literal -offset indent
status_path "~/.local/share/pimsync/status/"

pair study_calendars {
	storage_a calendars_local
	storage_b calendars_italki
	collection italki
}

storage calendars_local {
	type vdir/icalendar
	path ~/.local/share/calendars/
	fileext ics
	interval 30
}

storage calendars_italki {
	type webcal
	collection_id italki
	url {
		cmd hiq -dFurl proto=webcal alias=italki-mine
	}
}
.Ed
.Pp
این مثال دو فضای ذخیره‌سازی را همگام می‌کند. اولی یک سرور CardDAV است که از طریق یک سوکت دامین یونیکس در دسترس است. دومی از فایل‌سیستم محلی با فایل‌های vCard استفاده می‌کند.
.Bd -literal -offset indent
status_path "~/.local/share/pimsync/status/"

pair unixtest {
	storage_a unix_a
	storage_b unix_b
	collections all
}

storage unix_a {
	type carddav
	url unix:///tmp/xandikos.sock
}

storage unix_b {
	type vdir/vcard
	path /tmp/test_storage/
	fileext vcf
}
.Ed
.Sh "همچنین ببینید (SEE ALSO)"
.Xr pimsync 1 ,
.Xr pimsync-migration 7
.Pp
فایل پیکربندی از ساختار نحوی scfg پیروی می‌کند. ببینید:
https://git.sr.ht/~emersion/scfg