VERITYSETUP(8) دستورهای مدیریتی و نگهداری VERITYSETUP(8)

veritysetup - ابزار پیکربندی و مدیریت دستگاههای dm-verity

veritysetup <عملکرد> [<گزینه‌ها>] <آرگومان‌های عملکرد>

دستور veritysetup ابزاری برای پیکربندی و مدیریت دستگاه‌های dm-verity هسته است.

مقصد dm-verity نگاشت‌کننده دستگاه (device-mapper) هسته، محافظت از یکپارچگی داده‌های دستگاه‌های بلوکی را به‌صورت شفاف و فقط‌خواندنی فراهم می‌کند.

هنگامی که دستگاه dm-verity را پیکربندی می‌کنید، veritysetup یک نگاشت جدید ایجاد می‌کند که برنامه‌ها می‌توانند مانند هر دستگاه ذخیره‌سازی معمولی به آن دسترسی داشته باشند. هسته با مقایسه هر بلوک با هش‌های رمزنگاری پیش‌محاسبه‌شده، اعتبارسنجی را به‌صورت شفاف انجام می‌دهد. این اعتبارسنجی از یک درخت مرکل (Merkle tree) استفاده می‌کند و به‌صورت شفاف در سطح هسته و بدون تأثیر بر برنامه‌ها انجام می‌شود.

دستگاه‌های verity را می‌توان هنگام بوت از طریق veritytab(5) که بخشی از systemd(1) است، فعال کرد.

ابزار veritysetup از عملیات زیر پشتیبانی می‌کند:

format <data_device> <hash_device>

داده‌های اعتبارسنجی هش را برای <data_device> محاسبه و به‌صورت دائمی ذخیره می‌کند. در صورتی که با گزینه --hash-offset مشخص شده باشد، ناحیه هش می‌تواند روی همان دستگاه و پس از داده‌ها قرار گیرد.

برای اعتبارسنجی یا فعال‌سازی دستگاه، باید رشته هش ریشه (root hash) را ارائه دهید. هش ریشه باید مورد اعتماد باشد.

آرگومان دستگاه داده یا دستگاه هش می‌تواند یک دستگاه بلوکی یا یک تصویر فایل (file image) باشد. اگر مسیر دستگاه هش وجود نداشته باشد، به‌صورت یک فایل ایجاد خواهد شد.

<گزینه‌ها> می‌توانند [--hash, --no-superblock, --format, --data-block-size, --hash-block-size, --data-blocks, --hash-offset, --salt, --uuid, --root-hash-file] باشند.

اگر از گزینه --root-hash-file استفاده شود، هش ریشه در قالب متن کدگذاری‌شده هگزادسیمال در <path> ذخیره می‌شود.

open <data_device> <name> <hash_device> <root_hash>
open <data_device> <name> <hash_device> --root-hash-file <path>
create <name> <data_device> <hash_device> <root_hash> (نحو منسوخ‌شده)

یک نگاشت با نام <name> با تکیه بر دستگاه <data_device> و با استفاده از <hash_device> برای اعتبارسنجی درون هسته ایجاد می‌کند.

مقدار <root_hash> یک رشته هگزادسیمال است.

<گزینه‌ها> می‌توانند [--hash-offset, --no-superblock, --ignore-corruption or --restart-on-corruption, --panic-on-corruption, --ignore-zero-blocks, --check-at-most-once, --root-hash-signature, --root-hash-file, --use-tasklets, --shared] باشند.

اگر از گزینه --root-hash-file استفاده شود، هش ریشه به جای پارامتر خط فرمان، از <path> خوانده می‌شود. انتظار می‌رود متن کدگذاری‌شده هگزادسیمال، بدون نویسه خط جدید پایانی باشد.

در صورت استفاده از --no-superblock، باید از همان گزینه‌هایی استفاده کنید که در عملیات قالب‌بندی اولیه استفاده شده بود.

verify <data_device> <hash_device> <root_hash>
verify <data_device> <hash_device> --root-hash-file <path>

داده‌های روی data_device را با استفاده از بلوک‌های هش ذخیره‌شده در hash_device اعتبارسنجی می‌کند.

این دستور اعتبارسنجی را در فضای کاربری (userspace) انجام می‌دهد؛ هیچ دستگاه هسته‌ای ایجاد نمی‌شود.

مقدار <root_hash> یک رشته هگزادسیمال است.

اگر از گزینه --root-hash-file استفاده شود، هش ریشه به جای پارامتر خط فرمان، از <path> خوانده می‌شود. انتظار می‌رود متن کدگذاری‌شده هگزادسیمال، بدون نویسه خط جدید پایانی باشد.

<گزینه‌ها> می‌توانند [--hash-offset, --no-superblock, --root-hash-file] باشند.

در صورت استفاده از --no-superblock، باید از همان گزینه‌هایی استفاده کنید که در عملیات قالب‌بندی اولیه استفاده شده بود.

close <name>
remove <name> (نحو منسوخ‌شده)

نگاشت موجود <name> را حذف می‌کند.

<گزینه‌ها> می‌توانند [--deferred] یا [--cancel-deferred] باشند.

status <name>

وضعیت نگاشت فعال verity با نام <name> را گزارش می‌دهد.

dump <hash_device>

پارامترهای دستگاه verity را از ابربلوک ذخیره‌شده روی دیسک گزارش می‌دهد.

<گزینه‌ها> می‌توانند [--hash-offset] باشند.

--batch-mode, -q

عدم درخواست تاییدیه (حالت غیرتعاملی).

--cancel-deferred

حذف معوق پیکربندی‌شده قبلی دستگاه را در دستور close لغو می‌کند.

--check-at-most-once

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

هشدار: این گزینه سطح امنیت را کاهش می‌دهد زیرا تنها دستکاری آفلاین محتوای دستگاه داده تشخیص داده خواهد شد، نه دستکاری برخط (آنلاین).

--data-blocks blocks

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

--data-block-size bytes

اندازه بلوک مورد استفاده برای دستگاه داده (بر حسب بایت). حداکثر مقدار برابر با اندازه صفحه حافظه مورد استفاده هسته است.

--debug

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

--deferred

حذف دستگاه را در دستور close تا زمانی که آخرین کاربر آن را ببندد به تعویق می‌اندازد.

--error-as-corruption

خطاهای ورودی/خروجی (I/O) دستگاه را همانند خرابی داده‌ها در نظر می‌گیرد. این گزینه باید همراه با --restart-on-corruption یا --panic-on-corruption استفاده شود.

--fec-device device

استفاده از تصحیح خطای رو به جلو (Forward Error Correction یا FEC) برای بازیابی از خرابی داده‌ها در صورت ناموفق بودن اعتبارسنجی هش. از داده‌های کدگذاری دستگاه مشخص‌شده استفاده می‌کند.

آرگومان دستگاه FEC می‌تواند یک دستگاه بلوکی یا یک تصویر فایل باشد. برای دستور format، در صورتی که مسیر دستگاه FEC وجود نداشته باشد، به‌صورت یک فایل ایجاد می‌شود.

اندازه بلوک‌ها برای دستگاه‌های داده و هش باید یکسان باشد. همچنین، اگر دستگاه داده (data_device) در verity رمزنگاری شده باشد، دستگاه fec_device نیز باید رمزنگاری شود.

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

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

در صورتی که دستگاه هش و FEC هر دو در تصویر باشند، فراداده در آفست ناحیه FEC خاتمه می‌یابد.

--fec-offset bytes

آفست (بر حسب بایت) از ابتدای دستگاه FEC تا شروع داده‌های کدگذاری است.

--fec-roots number

تعداد ریشه‌های مولد (generator roots). این مقدار برابر با تعداد بایت‌های پاریتی در داده‌های کدگذاری است. در کدگذاری RS(M, N)، تعداد ریشه‌ها برابر با M-N است. مقدار M برابر ۲۵۵ است و M-N مقداری بین ۲ تا ۲۴ (شامل هر دو) است.

--format number

نوع نسخه هش را مشخص می‌کند. فرمت نوع ۰ نسخه اصلی Chrome OS است. فرمت نوع ۱ نسخه کنونی است.

--hash hash

الگوریتم هش برای dm-verity. برای مشاهده پیش‌فرض، گزینه --help را ببینید.

--hash-block-size bytes

اندازه بلوک مورد استفاده برای دستگاه هش (بر حسب بایت). حداکثر مقدار برابر با اندازه صفحه حافظه مورد استفاده هسته است.

--hash-offset bytes

آفست ناحیه هش/ابربلوک روی hash_device (بر حسب بایت). مقدار باید با آفست سکتور دیسک تراز باشد.

--help, -?

نمایش متن راهنما و پارامترهای پیش‌فرض.

--ignore-corruption, --restart-on-corruption, --panic-on-corruption

تعیین می‌کند در صورت تشخیص مشکل یکپارچگی داده (خرابی داده‌ها)، چه اقدامی انجام شود.

بدون این گزینه‌ها، هسته عملیات ورودی/خروجی را با خطای I/O رد می‌کند. با گزینه --ignore-corruption، خرابی تنها در گزارش‌ها ثبت می‌شود. با گزینه‌های --restart-on-corruption یا --panic-on-corruption، هسته بلافاصله راه‌اندازی مجدد می‌شود (وحشت هسته / panic رخ می‌دهد). (شما باید سازوکاری برای جلوگیری از حلقه‌های راه‌اندازی مجدد فراهم کنید.)

از این گزینه‌ها فقط در موارد بسیار خاص استفاده کنید.

--ignore-zero-blocks

به هسته دستور می‌دهد بلوک‌هایی را که انتظار می‌رود حاوی صفر باشند اعتبارسنجی نکند و همیشه مستقیماً صفر برگرداند.

از این گزینه فقط در موارد بسیار خاص استفاده کنید.

--no-superblock

ایجاد یا استفاده از dm-verity بدون ابربلوک دائمی روی دیسک.

--root-hash-file file*

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

--root-hash-signature file*

مسیر فایل امضای هش ریشه مورد استفاده برای اعتبارسنجی هش ریشه (درون هسته). این ویژگی به نسخه ۵.۴ یا جدیدتر هسته لینوکس نیاز دارد.

--salt=hex string

نمک (salt) مورد استفاده برای قالب‌بندی یا اعتبارسنجی. قالب آن یک رشته هگزادسیمال است.

--shared

اجازه می‌دهد از دستگاه داده در حالت اشتراکی استفاده شود. دستگاه داده قبل از فعال‌سازی دستگاه از نظر دسترسی انحصاری بررسی نمی‌شود و ممکن است در چندین نگاشت verity نگاشت گردد.

--usage

نمایش راهنمای کوتاه گزینه‌ها.

--use-tasklets

تلاش برای استفاده از taskletهای هسته در درایور dm-verity به دلایل کارایی. این گزینه از نسخه ۶.۰ هسته لینوکس در دسترس است.

--uuid UUID

استفاده از UUID ارائه‌شده برای دستور format به جای ایجاد یک مورد جدید.

مقدار UUID باید در قالب استاندارد UUID ارائه شود، مانند 12345678-1234-1234-1234-123456789abc.

--verbose, -v

چاپ اطلاعات بیشتر در هنگام اجرای دستور.

--version, -V

نمایش نسخه برنامه.

دستور veritysetup در صورت موفقیت مقدار 0 و در صورت بروز خطا یک مقدار غیرصفر برمی‌گرداند.

کدهای خطا عبارتند از: 1 پارامترهای نادرست، 2 عدم دسترسی یا مجوز ناکافی، 3 کمبود حافظه، 4 دستگاه نادرست مشخص‌شده، 5 دستگاه از قبل وجود دارد یا دستگاه مشغول است.

veritysetup --data-blocks=256 format <data_device> <hash_device>

داده‌های اعتبارسنجی را روی hash_device برای ۲۵۶ بلوک اول (با اندازه بلوک) محاسبه و ذخیره می‌کند. اگر hash_device وجود نداشته باشد، ایجاد خواهد شد (به‌صورت یک تصویر فایل).

veritysetup format --root-hash-file <path> <data_device> <hash_device>

داده‌های اعتبارسنجی را روی hash_device برای کل data_device محاسبه و ذخیره می‌کند، و هش ریشه را به‌صورت متن کدگذاری‌شده هگزادسیمال در <path> ذخیره می‌نماید.

veritysetup --data-blocks=256 --hash-offset=1052672 format <device> <device>

داده‌های اعتبارسنجی (هش‌ها) روی همان دستگاه داده ذخیره می‌شوند (با شروع از hash-offset). آفست هش باید بزرگ‌تر از تعداد بلوک‌های موجود در ناحیه داده باشد.

veritysetup --data-blocks=256 --hash-offset=1052672 create test-device <device> <device> <root_hash>

دستگاه verity به نام test-device را فعال می‌کند. گزینه‌های --data-blocks و --hash-offset مانند دستور format هستند. مقدار <root_hash> در دستور format محاسبه شده بود.

veritysetup --data-blocks=256 --hash-offset=1052672 verify <data_device> <hash_device> <root_hash>

دستگاه را بدون فعال‌سازی اعتبارسنجی می‌کند (در فضای کاربری).

veritysetup --data-blocks=256 --hash-offset=1052672 --root-hash-file <path> verify <data_device> <hash_device>

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

veritysetup --fec-device=<fec_device> --fec-roots=10 format <data_device> <hash_device>

داده‌های اعتبارسنجی و کدگذاری را برای data_device محاسبه و ذخیره می‌کند.

مشخصات قالب روی دیسک در صفحه DMVerity https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity در دسترس است.

نخستین پیاده‌سازی veritysetup توسط نویسندگان Chrome OS نوشته شده بود.

این نسخه بر اساس کد اعتبارسنجی نوشته‌شده توسط Mikulas Patocka <mpatocka@redhat.com> است و توسط Milan Broz <gmazyland@gmail.com>. برای libcryptsetup بازنویسی شده است.

باگ‌ها را به لیست پستی cryptsetup <cryptsetup@lists.linux.dev> ارسال کنید یا در بخش مسائل پروژه https://gitlab.com/cryptsetup/cryptsetup/-/issues/new. گزارش دهید.

لطفاً خروجی دستور ناموفق را همراه با گزینه --debug پیوست کنید.

پرسش‌های متداول Cryptsetup https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions

cryptsetup(8), integritysetup(8) و veritysetup(8)

بخشی از پروژه cryptsetup https://gitlab.com/cryptsetup/cryptsetup.

2026-07-21 veritysetup 2.8.7