نام (NAME)

casync - ابزار سیستم همگام‌سازی و توزیع مبتنی بر محتوا

خلاصه دستور (SYNOPSIS)

casync [OPTIONS...] make [ARCHIVE | ARCHIVE_INDEX | BLOB_INDEX] [PATH]
casync [OPTIONS...] extract [ARCHIVE | ARCHIVE_INDEX | BLOB_INDEX] [PATH]
casync [OPTIONS...] list [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
casync [OPTIONS...] mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
casync [OPTIONS...] stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
casync [OPTIONS...] digest [ARCHIVE | BLOB | ARCHIVE_INDEX | BLOB_INDEX | DIRECTORY] [PATH]
casync [OPTIONS...] mount [ARCHIVE | ARCHIVE_INDEX] PATH
casync [OPTIONS...] mkdev [BLOB | BLOB_INDEX] [NODE]
casync [OPTIONS...] gc BLOB_INDEX | ARCHIVE_INDEX ...

توضیحات (DESCRIPTION)

ابزار همگام‌سازی و توزیع داده‌ها با آدرس‌دهی مبتنی بر محتوا (Content-Addressable Data Synchronization Tool).

دستورها (COMMANDS)

casync make [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
casync make [BLOB_INDEX] FILE | DEVICE

این دستور یک بایگانی با پسوند .catar یا یک نمایه (index) با پسوند .caidx برای DIRECTORY داده‌شده، یا یک نمایه با پسوند .caibx برای FILE یا DEVICE بلوکی داده‌شده ایجاد می‌کند. نوع خروجی به صورت خودکار بر اساس پسوند فایل انتخاب می‌شود (این رفتار می‌تواند با --what= نادیده گرفته شود). تعیین DIRECTORY اختیاری است و در صورت عدم تعیین، دایرکتوری جاری استفاده خواهد شد.

هنگامی که یک فایل .caidx یا .caibx ایجاد می‌شود، یک دایرکتوری ذخیره‌سازی با پسوند .castr نیز ایجاد خواهد شد که به طور پیش‌فرض در همان دایرکتوری قرار دارد و نام آن default.castr خواهد بود مگر اینکه به صورت دیگری پیکربندی شود (گزینه --store= را ببینید).

متاداده‌های گنجانده‌شده در بایگانی توسط گزینه‌های --with-* و --without-* کنترل می‌شوند.

casync extract [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
casync extract BLOB_INDEX FILE | DEVICE

این دستور محتوای یک بایگانی .catar یا نمایه .caidx را درون DIRECTORY مشخص‌شده، یا محتوای مشخص‌شده توسط BLOB_INDEX را درون FILE یا DEVICE بلوکی تعیین‌شده استخراج می‌کند. تعیین DIRECTORY اختیاری است و به طور پیش‌فرض دایرکتوری جاری استفاده خواهد شد.

متاداده‌های بازسازی‌شده از بایگانی توسط گزینه‌های --with-* و --without-* کنترل می‌شوند.

casync list [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]

این دستور تمام فایل‌ها و دایرکتوری‌های موجود در PATH را همان‌گونه که در ARCHIVE یا ARCHIVE_INDEX یا زیر DIRECTORY یافت می‌شوند، فهرست می‌کند. هر دو آرگومان اختیاری هستند؛ آرگومان اول به طور پیش‌فرض دایرکتوری جاری و آرگومان دوم به طور پیش‌فرض مسیر سطح بالا (ریشه) بایگانی (/) در نظر گرفته می‌شود.

خروجی شامل ماسک دسترسی و نام فایل‌ها است:

$ casync list /usr/share/doc/casync
drwxr-xr-x
-rw-r--r-- README.md
-rw-r--r-- TODO

casync mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]

این دستور مشابه list است، اما اطلاعات مربوط به هر مدخل را در قالب کلید=مقدار (key=value) تعریف‌شده توسط BSD mtree(5) شامل می‌شود:

$ casync mtree /usr/share/doc/casync
. type=dir mode=0755 uid=0 gid=0 time=1500343585.721189650
README.md type=file mode=0644 size=7286 uid=0 gid=0 time=1498175562.000000000 sha256digest=af75eacac1f00abf6adaa7510a2c7fe00a4636daf9ea910d69d96f0a4ae85df4
TODO type=file mode=0644 size=2395 uid=0 gid=0 time=1498175562.000000000 sha256digest=316f11a03c08ec39f0328ab1f7446bd048507d3fbeafffe7c32fad4942244b7d

casync stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]

این دستور اطلاعات دقیق درباره فایل یا دایرکتوری PATH را همان‌گونه که در ARCHIVE یا ARCHIVE_INDEX یا زیر DIRECTORY یافت می‌شود، نمایش می‌دهد. هر دو آرگومان اختیاری هستند؛ آرگومان اول به طور پیش‌فرض دایرکتوری جاری و آرگومان دوم مسیر سطح بالا (/) است.

نمونه خروجی:

$ casync stat .
    File: .
    Mode: drwxrwxr-x
FileAttr: ----------
 FATAttr: ---
  Offset: 0
    Time: 2017-07-17 22:53:30.723304050
    User: zbyszek (1000)
   Group: zbyszek (1000)

casync digest [BLOB | BLOB_INDEX | DIRECTORY]
casync digest ARCHIVE | ARCHIVE_INDEX [PATH]

این دستور چکسام (checksum) فایل یا دایرکتوری، یا PATH داده‌شده را به صورتی که در ARCHIVE یا ARCHIVE_INDEX یافت می‌شود، محاسبه کرده و چاپ می‌کند. هر دو آرگومان اختیاری هستند؛ آرگومان اول به طور پیش‌فرض دایرکتوری جاری و آرگومان دوم به طور پیش‌فرض مسیر سطح بالای بایگانی (/) است.

مثال:

$ casync digest
d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7
$ casync digest .
d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7

casync mount [ARCHIVE | ARCHIVE_INDEX] PATH

این دستور بایگانی .catar یا نمایه .caidx مشخص‌شده را در PATH تعیین‌شده با استفاده از پروتکل FUSE سوار (mount) می‌کند.

casync mkdev [BLOB | BLOB_INDEX] [NODE]

این دستور یک گره دستگاه بلوکی NODE را با محتویات مشخص‌شده توسط BLOB_INDEX با پسوند .caibx یا صرفاً فایل یا دستگاه بلوکی BLOB با استفاده از پروتکل NBD ایجاد می‌کند.

مثال:

$ sudo casync -v mkdev README.md
Attached: /dev/nbd0
(in another terminal)
$ sudo head -n1 /dev/nbd0
# casync — Content Addressable Data Synchronizer

هنگامی که فرایند casync mkdev متوقف شود (kill شود)، دستگاه از بین می‌رود.

casync gc ARCHIVE_INDEX | BLOB_INDEX ...

این دستور تمامی قطعه‌ها (chunks) را که توسط هیچ‌یک از نمایه‌های مشخص‌شده استفاده نشده‌اند حذف می‌کند (می‌توان یک یا چند نمایه blob و archive را مشخص کرد). اگر گزینه --store تعیین نشده باشد، مخزن ذخیره‌سازی پیش‌فرض اولین نمایه استفاده خواهد شد.

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

گزینه‌ها (OPTIONS)

گزینه‌های عمومی:

--help, -h: نمایش راهنمای مختصر
--version: نمایش اطلاعات خلاصه نسخه
--log-level=<LEVEL>, -l: تنظیم سطح ثبت وقایع (debug، info، err)
--verbose, -v: نمایش وضعیت مختصر در حین اجرا
--dry-run, -n: صرفاً چاپ مواردی که با gc حذف خواهند شد (بدون اعمال تغییرات)
--store=PATH: مخزن اصلی قطعات (chunk store) برای استفاده
--extra-store=<PATH>: مخزن قطعات اضافی برای جستجوی قطعات در آن
--chunk-size=<[MIN:]AVG[:MAX]>: حداقل/میانگین/حداکثر تعداد بایت‌ها در هر قطعه
--digest=<DIGEST>: انتخاب الگوریتم خلاصه/هش (sha512-256 یا sha256)
--compression=<COMPRESSION>: انتخاب الگوریتم فشرده‌سازی (zstd، xz یا gzip)
--seed=<PATH>: فایل یا دایرکتوری اضافی برای استفاده به عنوان بذر (seed)
--cache=<PATH>: دایرکتوری مورد استفاده به عنوان کش (حافظه نهان) رمزگذار
--cache-auto, -c: انتخاب خودکار دایرکتوری کش رمزگذار
--rate-limit-bps=<LIMIT>: حداکثر پهنای باند بر حسب بایت در ثانیه برای ارتباطات شبکه از راه دور
--exclude-nodump=no: هنگام ایجاد بایگانی، فایل‌های دارای نشان nodump با پرچم +d دستور chattr(1) مستثنی نشوند
--exclude-submounts=yes: هنگام ایجاد بایگانی، سوارشدن‌های فرعی (submounts) مستثنی شوند
--exclude-file=no: به فایل‌های .caexclude در درخت فایل‌ها اعتنا نشود
--reflink=no: هنگام استخراج، از بذرها پیوند بازتابی (reflink) ایجاد نشود
--hardlink=yes: هنگام استخراج، از بذرها پیوند سخت (hardlink) ایجاد شود
--punch-holes=no: هنگام استخراج، فایل‌های کم‌پشت (sparse) ایجاد نشوند
--delete=no: پس از استخراج، فایل‌های موجود که در بایگانی فهرست نشده‌اند حذف نشوند
--undo-immutable=yes: هنگام حذف فایل‌های موجود، پرچم +i (تغییرناپذیر یا immutable) دستور chattr(1) در زمان استخراج برداشته شود
--seed-output=no: هنگام استخراج، خروجی‌های از پیش موجود به طور ضمنی به عنوان بذر افزوده نشوند
--recursive=no: فهرست‌گیری به صورت غیربازگشتی انجام شود
--mkdir=no: در صورت عدم وجود دایرکتوری محل سوار کردن (mount)، به طور خودکار ایجاد نشود
--uid-shift=<yes|SHIFT>: تغییر مکان شناسه‌های کاربری/گروهی (UID/GID)
--uid-range=<RANGE>: محدود کردن UID/GID به یک دامنه مشخص

انتخاب‌گر ورودی/خروجی:

--what=archive: عملیات روی فایل بایگانی
--what=archive-index: عملیات روی فایل نمایه بایگانی
--what=blob: عملیات روی فایل داده خام (blob)
--what=blob-index: عملیات روی فایل نمایه داده خام (blob index)
--what=directory: عملیات روی دایرکتوری
--what=help: چاپ فهرستی از مقادیر مجاز (و خروج از برنامه)

فعال‌سازی مجموعه‌های ویژگی‌های بایگانی:

--with=best: ذخیره دقیق‌ترین و کامل‌ترین اطلاعات
--with=unix: ذخیره اطلاعات پایه یونیکس
--with=fat: ذخیره اطلاعات سیستم‌فایل FAT
--with=chattr: ذخیره ویژگی‌های فایل chattr(1)
--with=fat-attrs: ذخیره ویژگی‌های فایل FAT
--with=privileged: ذخیره داده‌های فایلی که بازیابی آن‌ها نیازمند دسترسی‌های ویژه است
--with=fuse: ذخیره داده‌های فایلی که می‌توانند مجدداً از طریق 'casync mount' عرضه شوند

برای غیرفعال کردن (off) ویژگی‌های بایگانی، می‌توان از --without=… استفاده کرد، مانند --without=fat-attrs، --without=privileged و غیره. برای غیرفعال کردن تمامی ویژگی‌های اختیاری، می‌توان از --without=all استفاده کرد. (حالت مثبت --with=all منطقی نیست، زیرا برخی ویژگی‌ها با یکدیگر تداخل دارند. برای فعال‌سازی حداکثر مجموعه اطلاعات، از --with=best استفاده فرمایید.)

ویژگی‌های مجزای بایگانی:

--with=<16bit-uids>: ذخیره اطلاعات تقلیل‌یافته ۱۶ بیتی UID/GID
--with=<32bit-uids>: ذخیره اطلاعات کامل ۳۲ بیتی UID/GID
--with=<user-names>: ذخیره نام‌های کاربری/گروهی
--with=<sec-time>: ذخیره برچسب‌های زمانی با دقت ۱ ثانیه
--with=<usec-time>: ذخیره برچسب‌های زمانی با دقت ۱ میکروثانیه (µs)
--with=<nsec-time>: ذخیره برچسب‌های زمانی با دقت ۱ نانوثانیه (ns)
--with=<2sec-time>: ذخیره برچسب‌های زمانی با دقت ۲ ثانیه
--with=<read-only>: ذخیره پرچم فقط‌خواندنی به ازای هر فایل
--with=<permissions>: ذخیره کامل مجوزهای دسترسی فایل یونیکس
--with=<symlinks>: ذخیره پیوندهای نمادین
--with=<device-nodes>: ذخیره گره‌های دستگاه بلوکی و کاراکتری
--with=<fifos>: ذخیره گره‌های لوله نام‌گذاری‌شده (FIFO)
--with=<sockets>: ذخیره گره‌های سوکت سیستم‌فایل AF_UNIX
--with=<flag-hidden>: ذخیره پرچم فایل پنهان "hidden" در FAT
--with=<flag-system>: ذخیره پرچم فایل سیستمی "system" در FAT
--with=<flag-archive>: ذخیره پرچم فایل بایگانی "archive" در FAT
--with=<flag-append>: ذخیره پرچم فایل فقط‌الحاقی "append-only"
--with=<flag-noatime>: ذخیره پرچم فایل غیرفعال‌سازی زمان دسترسی "disable access time"
--with=<flag-compr>: ذخیره پرچم فایل فعال‌سازی فشرده‌سازی "enable compression"
--with=<flag-nocow>: ذخیره پرچم فایل غیرفعال‌سازی کپی هنگام نوشتن "disable copy-on-write"
--with=<flag-nodump>: ذخیره پرچم فایل غیرفعال‌سازی تخلیه "disable dumping"
--with=<flag-dirsync>: ذخیره پرچم دایرکتوری همگام "synchronous"
--with=<flag-immutable>: ذخیره پرچم فایل تغییرناپذیر "immutable"
--with=<flag-sync>: ذخیره پرچم فایل همگام "synchronous"
--with=<flag-nocomp>: ذخیره پرچم فایل غیرفعال‌سازی فشرده‌سازی "disable compression"
--with=<flag-projinherit>: ذخیره پرچم وراثت سهمیه پروژه "project quota inheritance"
--with=<subvolume>: ذخیره اطلاعات زیرحجم (subvolume) سامانه فایل btrfs
--with=<subvolume-ro>: ذخیره ویژگی فقط‌خواندنی زیرحجم btrfs
--with=<xattrs>: ذخیره ویژگی‌های گسترش‌یافته فایل (xattrs)
--with=<acl>: ذخیره فهرست‌های کنترل دسترسی فایل (ACL)
--with=<selinux>: ذخیره برچسب‌های فایل SElinux
--with=<fcaps>: ذخیره قابلیت‌های فایل (file capabilities)
--with=<quota-projid>: ذخیره شناسه پروژه سهمیه‌بندی ext4/XFS

(و موارد مشابه: --without=16bit-uids، --without=32bit-uids، ...)

ویژگی‌های بایگانی (ARCHIVE FEATURES)

پارامترهای گوناگون --with= و --without= مجموعه دقیق متاداده‌های ذخیره‌شده در بایگانی یا بازیابی‌شده در هنگام استخراج را کنترل می‌کنند. این پرچم‌ها تنها در صورتی اعمال می‌شوند که casync در سطح سیستم فایل کار کند.

مستثنی کردن فایل‌ها و دایرکتوری‌ها از بایگانی‌سازی (EXCLUDING FILES AND DIRECTORIES FROM ARCHIVING)

هنگام ایجاد یک بایگانی یا نمایه از درخت دایرکتوری سیستم‌فایل، برخی فایل‌ها و دایرکتوری‌ها به طور پیش‌فرض مستثنی می‌شوند و برخی دیگر را می‌توان به صورت اختیاری مستثنی کرد:

1.: فایل‌ها و دایرکتوری‌های سیستم‌فایل‌های API مجازی ارائه شده توسط هسته (یعنی procfs، sysfs، cgroupfs، devpts و... — به جز tmpfs/devtmpfs) بدون قید و شرط مستثنی می‌شوند.
2.: بسته به اینکه پیوندهای نمادین، گره‌های دستگاه، لوله‌های FIFO و سوکت‌ها با استفاده از --with= و --without= برای بایگانی‌سازی فعال شده باشند یا خیر، گره‌های فایل از این نوع مستثنی می‌شوند.
3.: به طور پیش‌فرض، فایل‌ها و دایرکتوری‌هایی با پرچم +d دستور chattr(1) مستثنی می‌شوند؛ با این حال این رفتار را می‌توان با --exclude-nodump=no غیرفعال کرد.
4.: به صورت اختیاری، در صورتی که --exclude-submounts=yes مشخص شده باشد، فایل‌ها و دایرکتوری‌های موجود در نقاط سوارشدن فرعی (submounts) درخت سیستم‌فایل مشخص‌شده مستثنی خواهند شد.
5.: به طور پیش‌فرض، هر فایل و دایرکتوری فهرست‌شده در فایل‌های .caexclude در سلسله‌مراتب فایل‌ها مستثنی می‌شود؛ با این حال بررسی و پردازش این فایل‌ها را می‌توان با --exclude-file=no غیرفعال کرد. این فایل‌ها عملکردی مشابه با مفهوم .gitignore در ابزار git دارند: آن‌ها به عنوان فایل متنی خوانده می‌شوند که هر خط آن یا خالی است / با # شروع می‌شود (که در این صورت تاثیری نداشته و می‌تواند برای نوشتن توضیحات به کار رود)، یا یک الگوی مسیر تطبیق نام (globbing) از فایل‌ها/دایرکتوری‌های نادیده‌گرفتنی را فهرست می‌کند. اگر خطی حاوی نویسه / نباشد، آن خط برای دایرکتوری محل قرارگیری فایل .caexclude و همچنین تمامی دایرکتوری‌های فرزند آن اعمال می‌شود. اگر شامل حداقل یک نویسه / باشد، کاملاً نسبت به دایرکتوری محل قرارگیری فایل .caexclude نسبی در نظر گرفته می‌شود. فایل‌های .caexclude ممکن است در هر دایرکتوری از درخت سیستم‌فایلی که بایگانی می‌شود قرار گیرند؛ با این وجود قرار دادن آن‌ها در دایرکتوری‌هایی که قبلاً توسط فایل‌های .caexclude بالاتر در درخت دایرکتوری برای مستثنی شدن علامت‌گذاری شده‌اند، بی‌اثر خواهد بود. هنگامی که یک خط با نویسه / پایان می‌یابد، صرفاً برای دایرکتوری‌ها اعمال می‌شود و شامل فایل‌های عادی یا سایر انواع گره‌های فایل نخواهد شد. اگر خطی با نویسه ! شروع شود، فایل‌های منطبق از شمول مستثنی‌سازی خارج می‌شوند؛ به این معنی که اثر سایر خطوط منطبق که با این علامت شروع نشده‌اند برای این فایل‌ها لغو می‌شود. خطوط دارای علامت ! بدون قید و شرط بر خطوط فاقد این علامت تقدم دارند. علاوه بر این، خطوطی که با ! شروع می‌شوند اثر الگوهای موجود در فایل‌های .caexclude در دایرکتوری‌های بالاتر درخت را نیز لغو می‌کنند.