nbdcopy(1) LIBNBD nbdcopy(1)

nbdcopy - کپی سریع و موازی داده‌ها بین دیسک‌ها و سرورهای NBD

nbdcopy [--allocated] [--blkhash=DIGEST] [--blkhash-file=FILE]
        [-C N|--connections=N]
        [--destination-is-zero|--target-is-zero] [--flush]
        [--no-extents] [-p|--progress|--progress=FD]
        [--queue-size=N] [--request-size=N] [-R N|--requests=N]
        [-S N|--sparse=N] [--synchronous] [-T N|--threads=N]
        [-v|--verbose]
        SOURCE DESTINATION
SOURCE, DESTINATION := - | FILE | DEVICE | NBD-URI | [ CMD ARGS ... ]
DESTINATION += null:
nbdcopy --help
nbdcopy -V|--version

این دستور تمام داده‌ها را از سرور NBD در "example.com" به یک فایل محلی با نام local.img کپی می‌کند.

این دستور بخش ابتدایی دیسک روی سرور NBD در "example.com" را به دستور file(1) هدایت (استریم) می‌کند. توجه داشته باشید که در اینجا "-" به معنای استریم به خروجی استاندارد (stdout) است (و در نتیجه از طریق پایپ به دستور file ارسال می‌شود).

دستور nbdinfo(1) روش دیگری برای بررسی محتوای یک سرور NBD است.

کپی کل دیسک سخت محلی "/dev/sdX" به سرور NBD که روی سوکت یونیکس (Unix domain socket) در مسیر /tmp/unixsock گوش می‌دهد. با استفاده از گزینه -p یک نوار پیشرفت نمایش داده می‌شود.

کپی کامل یک دیسک از یک سرور NBD به سرور NBD دیگر.

کپی کامل دیسک از یک سرور NBD به سرور NBD دیگر، همراه با محاسبه blkhash (مشابه چک‌سام) دیسک و چاپ آن در پایان.

-'>https://example.com/disk.qcow2 ] -

اجرای qemu-nbd(8) به عنوان یک زیرپردازش برای باز کردن نشانی "https://example.com/disk.qcow2"، که سپس به خروجی استاندارد ("-") استریم شده و به بلوک‌هایی با قالب داده خام (raw) تبدیل می‌شود. توجه داشته باشید که علامت "--" برای جلوگیری از تفسیر فلگ‌های qemu-nbd به عنوان فلگ‌های nbdcopy استفاده شده است.

الحاق دو ایمیج دیسک با قالب raw به یک فایل qcow2 با نام output.qcow2. فایل خروجی باید از قبل ایجاد شده باشد.

خواندن محتوای سرور NBD با حداکثر سرعت ممکن و دور ریختن آن (نوشتن روی یک دستگاه مجازی تهی یا null). این کار برای بنچمارک و سنجش کارایی سرورهای NBD یا ابزار nbdcopy مفید است.

دستور nbdcopy داده‌ها را به/از یک سرور NBD کپی می‌کند. این ابزار می‌تواند یک فایل محلی را روی سرور NBD آپلود کند، یا محتوای یک سرور NBD را در یک فایل محلی، دستگاه یا ورودی/خروجی استاندارد (stdin/stdout) دانلود نماید. همچنین امکان کپی مستقیم بین دو سرور NBD وجود دارد.

فایل محلی می‌تواند یک فایل معمولی، یک دستگاه بلوکی (مانند "/dev/cdrom") یا علامت "-" باشد که به معنای خواندن از ورودی استاندارد (stdin) یا نوشتن در خروجی استاندارد (stdout) است.

سرور NBD را می‌توان با یک URI مربوط به NBD (مانند "nbd://localhost") مشخص کرد. سرور NBD می‌تواند محلی یا راه‌دور باشد، و در صورتی که libnbd با پشتیبانی از رمزنگاری کامپایل شده باشد، امکان استفاده از رمزنگاری وجود دارد. همچنین می‌توانید با قرار دادن دستورات qemu-nbd(8) یا nbdkit(1) در میان براکت‌های مربعی، سرور NBD را به عنوان زیرپردازش nbdcopy اجرا کنید.

مقصد می‌تواند عبارت ویژه "null:" باشد تا داده‌های خروجی دور ریخته شوند.

برای عملیات کپی پیچیده‌تر، از جمله تبدیل بین قالب‌های مختلف دیسک، از دستور "qemu-img convert" استفاده کنید؛ صفحه راهنمای qemu-img(1) را ببینید.

نمایش راهنمای خلاصه خط فرمان و خروج.
به طور معمول، اگر مقصد پشتیبانی کند، nbdcopy تلاش می‌کند خروجی خلوت یا اسپارس (همراه با حفره یا hole) ایجاد نماید. این کار به دو روش انجام می‌شود: یا با استفاده از اطلاعات گستره (extent) از منبع برای کپی حفره‌ها (گزینه --no-extents را ببینید)، یا با تشخیص توالی صفرها (گزینه -S را ببینید). اگر از --allocated استفاده کنید، nbdcopy خروجی کاملاً تخصیص‌یافته و غیراسپارس در مقصد ایجاد می‌کند.
محاسبه مقدار blkhash ایمیج دیسک در حین کپی و چاپ آن در پایان عملیات. الگوریتم Blkhash (https://gitlab.com/nirs/blkhash) مشابه چک‌سام است با این تفاوت که قابلیت محاسبه به صورت موازی را دارد. توجه داشته باشید که این مقدار با خروجی برنامه‌هایی مانند cksum(1) یا sha256sum(1) سازگار نیست. استفاده از این گزینه سرعت nbdcopy را کاهش می‌دهد.

می‌توانید تابع خلاصه‌ساز (digest) را از بین "md5"، "sha1"، "sha256" (پیشنهادی)، یا "sha512" انتخاب کنید. همچنین می‌توانید اندازه بلوک را مشخص کنید که مقدار پیش‌فرض آن "64k" (پیشنهادی) است.

گزینه --blkhash بدون پارامتر، حالت sha256/64k را انتخاب می‌کند.

برای محاسبه blkhash یک فایل بدون کپی کردن آن، می‌توانید دستور زیر را اجرا کنید:

nbdcopy --blkhash -- disk.raw null:

یا اگر قالب فایل qcow2 باشد:

nbdcopy --blkhash -- [ qemu-nbd -f qcow2 disk.qcow2 ] null:
در صورت انتخاب --blkhash، تعیین محل چاپ blkhash. پیش‌فرض خروجی استاندارد (stdout) است.
تنظیم حداکثر تعداد اتصال‌های NBD ("اتصال چندگانه" یا multi-conn). به صورت پیش‌فرض، اگر سرور NBD پشتیبانی کند، nbdcopy تلاش می‌کند از multi-conn با حداکثر ۴ اتصال استفاده کند. در صورت کپی بین دو سرور NBD، اگر هر یک از آن‌ها از multi-conn پشتیبانی نکند، nbdcopy نمی‌تواند از اتصال چندگانه استفاده کند.
فرض بر اینکه مقصد از قبل با صفر پر شده است. این کار به nbdcopy امکان می‌دهد از کپی کردن بلوک‌های صفر از مبدأ به مقصد صرف‌نظر کند.

این گزینه تنها در صورتی ایمن است که دستگاه مقصد واقعاً با صفر پر شده باشد. می‌توانید ابتدا از nbddiscard(1) یا nbdzero(1) استفاده کنید.

نام مستعار --target-is-zero برای سازگاری با qemu-img(1) در نظر گرفته شده است.

تخلیه بافر نوشتن‌ها (Flush) برای اطمینان از ذخیره کامل داده‌ها روی حافظه پایدار پیش از خروج nbdcopy.
به طور معمول nbdcopy از متادیتای گستره (extent) برای رد شدن از بخش‌هایی از دیسک مبدأ که حاوی حفره هستند استفاده می‌کند. با این فلگ، nbdcopy اطلاعات گستره را نادیده گرفته و تمام داده‌ها را می‌خواند که معمولاً کندتر است. این فلگ در دو حالت کاربرد دارد: زمانی که سرور NBD مبدأ اطلاعات متادیتای نادرستی ارائه دهد، یا زمانی که پرس‌وجوی گستره‌ها در مبدأ بسیار کند باشد به‌طوری‌که خواندن ساده تمام داده‌ها سریع‌تر تمام شود.
نمایش نوار پیشرفت.
نوشتن نوار پیشرفت در توصیف‌کننده فایل "FD" (یک عدد) در قالبی که پردازش آن توسط برنامه‌های دیگر آسان باشد. nbdcopy به طور دوره‌ای رشته "N/100\n" (که N عدد صحیحی بین ۰ تا ۱۰۰ است) را در توصیف‌کننده فایل می‌نویسد.

برای اینکه nbdcopy نوار پیشرفت را در یک فایل بنویسد، می‌توانید از دستورات پوسته زیر استفاده کنید:

exec 3>/tmp/progress
nbdcopy --progress=3 ...
exec 3>&-
تنظیم حداکثر تعداد بایت‌های مجاز در صف برای درخواست‌های در حال انجام. مقدار پیش‌فرض 16 MiB است که امکان ارسال تا ۶۴ درخواست 256k را به ازای هر اتصال NBD فراهم می‌کند. اگر از --request-size بزرگ‌تری استفاده می‌کنید، ممکن است بخواهید این مقدار را افزایش دهید.
تنظیم حداکثر اندازه درخواست بر حسب بایت. بیشترین مقدار مجاز که توسط پروتکل NBD تعیین شده، 32 MiB است.
تنظیم حداکثر تعداد درخواست‌های همزمان در حال انجام (in flight) به ازای هر اتصال NBD.
تشخیص تمام بلوک‌های صفر با اندازه N (بایت) و ایجاد آن‌ها به صورت اسپارس (حفره) در خروجی. همچنین می‌توانید با -S 0 تشخیص حالت اسپارس را غیرفعال کنید. مقدار پیش‌فرض ۴۰۹۶ بایت یا اندازه بلوک ترجیحی مقصد است (هرکدام بزرگ‌تر باشد).
اجبار به کپی همگام (Synchronous) با استفاده از API همگام ("سطح بالا") در libnbd(3). این حالت کند است اما ممکن است برای برخی از سرورهای معیوب NBD که توانایی پردازش چندین درخواست همزمان را ندارند ضروری باشد. این حالت همچنین هنگام استریم داده‌ها به/از stdio، پایپ‌ها و سوکت‌ها استفاده می‌شود.
استفاده از حداکثر N رشته (thread) برای کپی. به صورت پیش‌فرض این مقدار برابر با تعداد هسته‌های پردازنده موجود در سیستم تنظیم می‌شود.

توجه داشته باشید که --threads=0 به معنای تشخیص خودکار و --threads=1 به معنای استفاده از یک رشته منفرد است.

خروجی با جزئیات کامل (Verbose). این گزینه اشکال‌زدایی در libnbd را فعال می‌کند (صفحه راهنمای nbd_set_debug(3) را ببینید) و اطلاعات مفید دیگری را نیز چاپ می‌نماید.
نمایش نام و نسخه بسته و خروج.

سه گزینه --connections، --threads و --requests با یکدیگر مرتبط هستند و میزان موازی‌سازی در دسترس را کنترل می‌کنند. مقادیر پیش‌فرض در صورت امکان سطح مناسبی از موازی‌سازی را تضمین می‌کنند و نیازی به تغییر آن‌ها نیست، اما این بخش به تشریح سازوکار آن‌ها می‌پردازد.

نخست، اگر هر یک از طرفین عملیات کپی در حال استریم به/از stdio، پایپ یا سوکت باشد، یا اگر از گزینه --synchronous استفاده کنید، nbdcopy در حالت همگام و بدون هیچ‌گونه موازی‌سازی عمل می‌کند و سایر موارد این بخش اعمال نخواهند شد.

گزینه --connections=N ویژگی multi-conn در NBD را کنترل می‌کند (بخش "Multi-conn" در libnbd(3) را ببینید) و حداکثر N اتصال را به سرور NBD (یا به هر دو سرور در صورت کپی بین سرورهای NBD) باز می‌نماید. مقدار پیش‌فرض ۴ است. سرورهای NBD باید از multi-conn پشتیبانی و آن را اعلان کنند. در nbdkit(1) در دسترس بودن multi-conn ممکن است به پلاگین مورد استفاده بستگی داشته باشد. می‌توانید با دستور nbdinfo(1) بررسی کنید که آیا سرور NBD قابلیت multi-conn را اعلان می‌کند یا خیر. اگر سرور NBD پشتیبانی از multi-conn را اعلان نکند، صرف‌نظر از فلگ --connections، تنها یک اتصال باز خواهد شد.

هنگام کپی بین دو سرور NBD، تعداد اتصالات به حداقل مقدار multi-conn پشتیبانی‌شده در هر دو سمت محدود می‌شود. برای این محاسبات، می‌توانید فایل‌های محلی و دستگاه‌های بلوکی را دارای پشتیبانی نامحدود از multi-conn در نظر بگیرید.

هنگامی که سرور NBD را به عنوان یک زیرپردازش (با نحو "[ ... ]") اجرا می‌کنید، نمی‌توان از multi-conn استفاده کرد.

گزینه --threads=N به nbdcopy امکان می‌دهد تا N رشته را راه‌اندازی کند (پیش‌فرض برابر تعداد هسته‌ها است). با این حال، nbdcopy نمی‌تواند بیش از تعداد اتصال‌های NBD از رشته‌ها استفاده کند.

گزینه --requests=N حداکثر تعداد درخواست‌های در حال انجام (in flight) را روی هر اتصال NBD کنترل می‌کند. این ویژگی سرور NBD را قادر می‌سازد تا حتی در صورت عدم دسترسی به multi-conn یا هنگام استفاده از یک رشته منفرد، درخواست‌ها را به صورت موازی پردازش کند. مقدار پیش‌فرض به‌گونه‌ای انتخاب شده است که سطح مناسبی از موازی‌سازی را بدون مصرف بیش از حد حافظه فراهم آورد.

به دلیل این پردازش موازی، nbdcopy بلوک‌ها را به ترتیب متوالی نمی‌خواند و نمی‌نویسد. اگر به هر دلیلی نیاز دارید که بلوک‌ها با ترتیبی دقیق و متوالی کپی شوند، باید از گزینه --synchronous استفاده نمایید.

به جای اتصال به سروری که از قبل در حال اجراست با استفاده از URI، می‌توانید سرور NBD را به عنوان یک زیرپردازش با قالب زیر اجرا کنید:

nbdcopy -- [ CMD ARGS ... ] ...

این قابلیت مستلزم آن است که سرور از فعال‌سازی سوکت systemd پشتیبانی کند؛ قابلیتی که هر دو برنامه qemu-nbd(8) و nbdkit(1) از آن پشتیبانی می‌کنند (صفحه راهنمای nbd_connect_systemd_socket_activation(3) را نیز ببینید).

عبارت‌های "[" و "]" باید پارامترهای خط فرمان مجزا باشند. معمولاً باید از "--" استفاده کنید تا از تفسیر فلگ‌های سرور NBD به عنوان فلگ‌های nbdcopy جلوگیری شود. مبدأ و مقصد هر دو می‌توانند زیرپردازش باشند. nbdcopy زیرپردازش را هنگام خروج پاکسازی و متوقف می‌کند.

چند مثال در ادامه آمده است.

در این مثال، qemu-nbd(8) به عنوان یک زیرپردازش اجرا می‌شود. زیرپردازش فایل disk.qcow2 را باز کرده و آن را به عنوان NBD برای nbdcopy ارائه می‌دهد. سپس nbdcopy این داده‌ها را به خروجی استاندارد ("-") استریم کرده و به درون پایپی می‌ریزد که توسط hexdump(1) خوانده می‌شود. (صفحه راهنمای nbddump(1) را نیز ببینید)

دو زیرپردازش ایجاد می‌شوند: qemu-nbd(8) به عنوان مبدأ و nbdkit(1) به عنوان مقصد. فایل qcow2 به قالب raw تبدیل شده و موقتاً در دیسک RAM ذخیره می‌شود (nbdkit-memory-plugin(1)).

هنگام خروج nbdcopy هر دو سرور متوقف شده و دیسک RAM از بین می‌رود؛ بنابراین این دستور تأثیر دائمی ندارد اما برای تست و ارزیابی بسیار مفید است.

libnbd(3)، nbddiscard(1)، nbddump(1)، nbdfuse(1)، nbdinfo(1)، nbdsh(1)، nbdublk(1)، nbdzero(1)، nbdkit(1)، qemu-img(1)، https://gitlab.com/nirs/blkhash، blksum(1).

Richard W.M. Jones

Copyright Red Hat

این کتابخانه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «مجوز عمومی جامع‌تر گنو» (GNU LGPL) که توسط «بنیاد نرم‌افزارهای آزاد» منتشر شده است—یا نسخه ۲ مجوز، یا (به انتخاب خودتان) هر نسخه بالاتر دیگری—مجدداً توزیع کرده و/یا تغییر دهید.

این کتابخانه به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر به «مجوز عمومی جامع‌تر گنو» مراجعه کنید.

شما باید همراه با این کتابخانه نسخه‌ای از «مجوز عمومی جامع‌تر گنو» را دریافت کرده باشید؛ در غیر این صورت، به آدرس زیر مکاتبه کنید:

Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

2026-07-16 libnbd-1.24.3