نام (NAME)

pimsync.conf — فایل پیکربندی برای ابزار pimsync

توضیحات (DESCRIPTION)

pimsync.conf به سه نوع بخش اصلی تقسیم می‌شود:

پیکربندی سراسری (GLOBAL CONFIGURATION)

تنظیمات سراسری برای pimsync.

بخش‌های فضای ذخیره‌سازی (STORAGE SECTIONS)

پیکربندی برای فضاهای ذخیره‌سازی مجزا.

بخش‌های جفت (PAIR SECTIONS)

قوانین همگام‌سازی جفت‌های فضای ذخیره‌سازی.

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

پیکربندی سراسری (GLOBAL CONFIGURATION)

تنظیمات زیر را می‌توان به صورت سراسری پیکربندی کرد:

status_path path

مسیر دایرکتوری‌ای که پایگاه‌داده وضعیت مورد استفاده داخلی pimsync.conf در آن نگهداری خواهد شد.

بخش‌های فضای ذخیره‌سازی (STORAGE SECTIONS)

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

storage name {…}

اعلان یک فضای ذخیره‌سازی با نام name.

دستورالعمل‌ها در داخل آکولادها برای هر بخش و در هر سطر یک دستورالعمل تعریف می‌شوند. دستورالعمل‌های زیر برای تمامی انواع فضاهای ذخیره‌سازی اعمال می‌شوند:

type type

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

vdir/icalendar

دایرکتوری‌ای که هر زیردایرکتوری آن نشان‌دهنده یک تقویم است. هر یک از این زیردایرکتوری‌ها شامل فایل‌های مجزای icalendar هستند که هر کدام نشان‌دهنده یک رویداد (یا یک سری رویدادهای تکرارشونده)، کار (todo) یا یادداشت روزانه (journal entry) می‌باشند.

vdir/vcard

دایرکتوری‌ای که هر زیردایرکتوری آن نشان‌دهنده یک دفترچه نشانی است. هر یک از این زیردایرکتوری‌ها شامل فایل‌های مجزای vcard هستند که هر کدام نشان‌دهنده یک مخاطب است.

caldav

یک سرور CalDAV شامل تقویم‌هایی با رویدادها، کارها و/یا یادداشت‌های روزانه.

carddav

یک سرور CardDAV شامل دفترچه‌های نشانی با مخاطبین.

webcal

یک منبع HTTP یا HTTPS که یک فایل منفرد iCalendar را ارائه می‌دهد و ممکن است شامل صفر یا چند رویداد، کار یا یادداشت روزانه باشد. این فضای ذخیره‌سازی فقط‌خواندنی است.

jmap/icalendar

یک سرور JMAP با پشتیبانی از تقویم. این فضای ذخیره‌سازی آزمایشی است و ممکن است همچنان دارای اشکالات جدی باشد!

jmap/vcard

یک سرور JMAP با پشتیبانی از مخاطبین. این فضای ذخیره‌سازی آزمایشی است و ممکن است همچنان دارای اشکالات جدی باشد!

interval seconds

زمانی که پایش یک فضای ذخیره‌سازی امکان‌پذیر نباشد، تغییرات را در هر بازه زمانی مشخص‌شده بر حسب ثانیه بررسی می‌کند. مقدار پیش‌فرض ۳۰۰ ثانیه است.

read_only

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

فضاهای ذخیره‌سازی از نوع vdir دستورالعمل‌های زیر را می‌پذیرند:

path path

مسیر دایرکتوری ذخیره‌کننده یک vdir. علامت تیلدا (~) در ابتدای مسیر به دایرکتوری خانگی کاربر جاری گسترش می‌یابد.

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

fileext extension

اختیاری. پسوند فایل برای آیتم‌های ذخیره‌شده در این vdir. در صورت عدم تعیین، ics برای فضاهای ذخیره‌سازی تقویم و vcf برای فضاهای ذخیره‌سازی دفترچه نشانی استفاده می‌شود.

فضاهای ذخیره‌سازی از نوع caldav یا carddav دستورالعمل‌های زیر را می‌پذیرند:

url url

نشانی URL سرور Dav. اگر این نشانی قابلیت‌های مناسب DAV را گزارش نکند، کشف سرویس (service discovery) برای این URL و دامنه آن انجام می‌شود تا مکان دقیق سرور و مجموعه خانگی (home set collection) پیدا شود.

نشانی‌های URL باید طرح‌واره http ، https یا unix را مشخص کنند. نشانی‌های شروع‌شونده با unix:// به عنوان مسیر سوکت دامین یونیکس تلقی خواهند شد.

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

username username

اختیاری. نام کاربری برای احراز هویت اولیه HTTP (Basic Auth).

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

password password

اختیاری. گذرواژه برای احراز هویت اولیه HTTP (Basic Auth).

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

collection_id_segment last | second-last

اختیاری. بخش مسیر URL برای استفاده به عنوان شناسه مجموعه. مقادیر معتبر عبارتند از last (پیش‌فرض) یا second-last. برای جزئیات بیشتر به مستندات استفاده پیشرفته مراجعه کنید.

فضاهای ذخیره‌سازی از نوع webcal دستورالعمل‌های زیر را می‌پذیرند:

url url

نشانی URL یک فایل icalendar. این فایل ممکن است شامل چندین آیتم تقویم باشد. طرح‌واره پروتکل باید http یا https باشد.

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

collection_id name

نامی که هنگام نگاشت این مجموعه به مجموعه‌ای دیگر در فضای ذخیره‌سازی طرف مقابل استفاده می‌شود.

فضاهای ذخیره‌سازی از نوع jmap دستورالعمل‌های زیر را می‌پذیرند:

url url

نشانی URL پایه سرور JMAP.

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

username username

اختیاری. نام کاربری برای احراز هویت اولیه HTTP (Basic Auth).

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

password password

اختیاری. گذرواژه برای احراز هویت اولیه HTTP (Basic Auth).

از پارامترهای پویا (DYNAMIC PARAMETERS) پشتیبانی می‌کند (بخش زیر را ببینید).

فضاهای ذخیره‌سازی از نوع caldav ، carddav ، webcal و jmap همچنین دستورالعمل‌های زیر را می‌پذیرند:

user_agent user_agent

اختیاری. تنظیم هدر User-Agent به user_agent برای درخواست‌های HTTP خروجی. پیش‌فرض از “pimsync/” به همراه شماره نسخه جاری استفاده می‌کند. به عنوان مثال: pimsync/1.0.0.

tls_root path

اختیاری. استفاده از مخزن ریشه گواهی در path هنگام بررسی گواهی TLS سرور. این گزینه بررسی گواهی در برابر مرجع‌های صدور گواهی (CA) سیستم را غیرفعال می‌کند. بخش tls_fingerprint در زیر را ببینید.

tls_fingerprint fingerprint

اختیاری. پذیرش گواهی در صورتی که اثر انگشت آن با fingerprint مطابقت داشته باشد. اگر همراه با دستورالعمل tls_root مشخص شود، گواهی با ریشه مشخص‌شده اعتبارسنجی می‌شود. اگر tls_root مشخص نشود، گواهی سرور در برابر هیچ ریشه‌ای اعتبارسنجی نمی‌شود و تنها بررسی اثر انگشت انجام می‌پذیرد.

auth_cert certificate key

اختیاری. استفاده از certificate و key ارائه‌شده برای احراز هویت کلاینت TLS.

auth_cert pem_bundle

اختیاری. استفاده از گواهی و کلید موجود در بسته مشخص‌شده برای احراز هویت کلاینت TLS.

پارامترهای پویا (DYNAMIC PARAMETERS)

فیلدهای url ، username ، password و path می‌توانند در فایل پیکربندی تعریف شوند، یا می‌توانند یک بلوک به همراه یک دستور را برای دریافت این مقدار از یک سیستم خارجی مشخص کنند. هنگام تعیین یک دستور خارجی، به جای تعریف مقدار مستقیم برای دستورالعمل، یک بلوک جدید با یک دستورالعمل منفرد cmd مشخص کنید.

برای مثال، برای خواندن گذرواژه از طریق دستور خارجی secret-store --get-caldav-password ، از ساختار نحوی زیر استفاده کنید:

password {
	cmd secret-store --get-caldav-password
}

همچنین می‌توان یک اسکریپت شل را مشخص کرد که از طریق ‘sh -c’ اجرا می‌شود. به عنوان مثال:

password {
	shell pass show communication/migadu.com | head -1
}

توصیه می‌شود اطلاعات هویتی و سایر مقادیر حساس در یک سرویس ذخیره‌سازی محرمانه نگهداری شوند.

بخش‌های جفت (PAIR SECTIONS)

یک جفت (pair) نحوه همگام‌سازی دو فضای ذخیره‌سازی با یکدیگر را اعلام می‌کند. هر بخش جفت با اعلان نام جفت آغاز می‌شود:

pair name {…}

اعلان یک جفت با نام name.

هر جفت توسط بلوکی از دستورالعمل‌ها، یک دستور در هر خط، محصور در آکولادها تعریف می‌شود:

storage_a name

نام ( name ) اولین فضای ذخیره‌سازی برای همگام‌سازی با دیگری.

storage_b name

نام ( name ) دومین فضای ذخیره‌سازی برای همگام‌سازی با دیگری.

collections all

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

collections from a

همگام‌سازی تمام مجموعه‌های یافت‌شده در storage_a. هر مجموعه با مجموعه‌ای که همان شناسه را در storage_b دارد همگام‌سازی خواهد شد.

collections from b

همگام‌سازی تمام مجموعه‌های یافت‌شده در storage_b. هر مجموعه با مجموعه‌ای که همان شناسه را در storage_a دارد همگام‌سازی خواهد شد.

collection id

همگام‌سازی مجموعه با شناسه id. می‌توان بیش از یک بار این دستورالعمل را مشخص کرد.

collection file ... {…}

همگام‌سازی مجموعه تعریف‌شده توسط قوانین داده‌شده. به بخش بخش‌های مجموعه (COLLECTION SECTIONS) در زیر مراجعه کنید. می‌تواند بیش از یک بار مشخص شود.

on_empty skip

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

on_empty sync

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

on_delete sync

هنگامی که خود یک مجموعه در یک طرف حذف شد، در طرف دیگر نیز حذف شود. این مورد تنها در صورتی اعمال می‌شود که مجموعه از قبل خالی باشد. این حالت پیش‌فرض است و عموماً ایمن می‌باشد، به‌ویژه زمانی که با on_empty skip ترکیب شود.

on_delete skip

هنگامی که خود یک مجموعه در یک طرف حذف شد، از آن صرف‌نظر شود.

one_way

همگام‌سازی آیتم‌ها فقط از storage_a به storage_b. تغییرات در storage_b با داده‌های storage_a بازنویسی می‌شوند. آیتم‌های ایجادشده در storage_b که در storage_a وجود ندارند حذف خواهند شد. این حالت هرگز تداخل (conflict) ایجاد نمی‌کند. این دستورالعمل هیچ پارامتری نمی‌پذیرد.

دستورالعمل conflict_resolution مشخص می‌کند در صورتی که یک آیتم در هر دو طرف تغییر کرده باشد چه اقدامی باید انجام گیرد. این دستورالعمل هنگام همگام‌سازی یک‌طرفه تأثیری ندارد.

conflict_resolution cmd command [args]

اجرای دستور command برای حل تداخل میان هر دو طرف. args به عنوان آرگومان‌ها ارسال می‌شوند و به دنبال آن مسیر دو فایل قرار می‌گیرد؛ یکی حاوی داده‌های موجود در storage a و دیگری حاوی داده‌های storage b. تداخل تنها در صورتی حل‌شده تلقی می‌شود که پس از خروج دستور، هر دو فایل یکسان باشند و دستور با کد خروج صفر خاتمه یابد.

conflict_resolution keep a

در صورت بروز تداخل، نسخه مربوط به storage a حفظ شود.

conflict_resolution keep b

در صورت بروز تداخل، نسخه مربوط به storage b حفظ شود.

بخش‌های مجموعه (COLLECTION SECTIONS)

یک بلوک collections نگاشتی را میان دو مجموعه که قرار است همگام شوند تعریف می‌کند؛ یکی از آن‌ها در storage_a و دیگری در storage_b.

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

هر بلوک باید شامل یک نام مستعار (alias) باشد:

alias name

یک نام مستعار برای این جفت مجموعه که برای هر خروجی استفاده خواهد شد.

دقیقاً یک ارجاع به مجموعه‌ای در storage_a باید گنجانده شود:

id_a id

استفاده از مجموعه با شناسه id.

href_a href

استفاده از مجموعه با مسیر href.

دقیقاً یک ارجاع به مجموعه‌ای در storage_b باید گنجانده شود:

id_b id

استفاده از مجموعه با شناسه id.

href_b href

استفاده از مجموعه با مسیر href.

برای مثال، جهت همگام‌سازی مجموعه‌ای با شناسه work با مجموعه‌ای دیگر در مسیر /calendars/mine/work/ ، از ساختار زیر استفاده کنید:

collection {
	alias work
	id_a work
	href_b /calendars/mine/work/
}

شناسه مجموعه (COLLECTION ID)

شناسه یک مجموعه مفهومی مختص به pimsync(1) و vdirsyncer(1) است.

برای فضاهای ذخیره‌سازی vdir ، شناسه یک مجموعه همان نام دایرکتوری متناظر با آن است.

برای فضاهای ذخیره‌سازی caldav یا carddav ، شناسه یک مجموعه به صورت پیش‌فرض آخرین مؤلفه نشانی URL آن است. این رفتار را می‌توان از طریق دستورالعمل پیکربندی collection_id_segment به استفاده از مؤلفه یکی مانده به آخر تغییر داد.

برای فضاهای ذخیره‌سازی webcal ، شناسه باید صریحاً از طریق دستورالعمل پیکربندی collection_id مشخص گردد.

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

مثال‌ها (EXAMPLES)

این مثال دو فضای ذخیره‌سازی حاوی دفترچه‌های نشانی را همگام‌سازی می‌کند. اولی مجموعه‌ای محلی از دایرکتوری‌ها شامل فایل‌های vCard و دومی یک سرور راه دور CardDAV است. اطلاعات ورود از طریق ابزار خط فرمان hiq(1) تأمین می‌شوند.

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
}

مثال زیر دو فضای ذخیره‌سازی با داده‌های تقویم را همگام می‌کند. اولی دایرکتوری‌های محلی با فایل‌های iCalendar و دومی یک سرور راه دور CalDAV است.

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
}

مثال زیر دو فضای ذخیره‌سازی با داده‌های تقویم را همگام‌سازی می‌کند. اولی یک دایرکتوری محلی به نام "italki" با فایل‌های تقویم است و دومی یک سرور http که یک فایل iCalendar را منتشر می‌کند.

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

نشانی دقیق فایل iCalendar ارائه‌شده از طریق http با ابزار hiq(1) دریافت می‌شود که برای پرس‌وجو از مخزن امنیتی himitsu(7) به کار می‌رود.

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
	}
}

این مثال دو فضای ذخیره‌سازی را همگام می‌کند. اولی یک سرور CardDAV است که از طریق یک سوکت دامین یونیکس در دسترس است. دومی از فایل‌سیستم محلی با فایل‌های vCard استفاده می‌کند.

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
}

همچنین ببینید (SEE ALSO)

pimsync(1), pimsync-migration(7)

فایل پیکربندی از ساختار نحوی scfg پیروی می‌کند. ببینید: https://git.sr.ht/~emersion/scfg