خروجی JSON (JSON output)

برای نمایش خروجی در قالب JSON (مثلاً جهت اسکریپت‌نویسی با jq(1)) پارامتر --json را اضافه کنید:

$ nbdinfo --json nbd://localhost | jq .
{
  "protocol": "newstyle-fixed",
  "TLS": false,
  "structured": true,
  "extended": false,
  "exports": [
    {
      "export-name": "",
      "content": "DOS/MBR boot sector; partition 1 : ID=0xc, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 2048, 4148704 sectors",
      "uri": "nbd://localhost:10809/",
      "is_rotational": false,
      "is_read_only": true,
      "can_cache": true,
      "can_df": true,
      "can_fast_zero": false,
      "can_flush": false,
      "can_fua": false,
      "can_multi_conn": true,
      "can_trim": false,
      "can_zero": false,
      "block_size_minimum": 1,
      "block_size_preferred": 4096,
      "block_size_maximum": 33554432,
      "export-size": 2125119488,
      "export-size-str": "2075312K"
    }
  ]
}

اندازه (Size)

برای نمایش تنها اندازه اکسپورت NBD به بایت (مفید برای اسکریپت‌نویسی)، از پارامتر --size استفاده کنید:

$ nbdinfo --size nbd://localhost
1048576

$ nbdinfo --size [ nbdkit null 1M ]
1048576

نشانی URI (URI)

برای نمایش نشانی استاندارد (canonical URI):

$ nbdinfo --uri nbd://localhost
nbd://localhost:10809/

آزمون فلگ‌ها (Test for flags)

از یکی از گزینه‌های --can، --is یا --has در زیر برای بررسی فلگ‌های NBD استفاده کنید. این دستور چیزی چاپ نمی‌کند، بلکه در صورت درست بودن با موفقیت (کد خروج 0) و در صورت نادرست بودن با شکست (کد خروج 2) خارج می‌شود. (سایر کدهای خروج نشان‌دهنده بروز خطا در استعلام فلگ هستند).

گزینه‌های --cannot، --isnt و --hasnt شرط آزمون را معکوس (نقیض) می‌کنند.

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

if nbdinfo --is read-only nbd://localhost ||
   nbdinfo --cannot trim nbd://localhost
then
    error "the device must support writing and trimming"
fi

nbdinfo --is read-only URI

بررسی اینکه آیا اکسپورت کارساز فقط‌خواندنی (read-only) است یا خیر.

nbdinfo --can write URI

برای راحتی، این گزینه معکوس --is read-only است.

nbdinfo --can read URI

تمامی کارسازهای NBD باید از خواندن پشتیبانی کنند، بنابراین این دستور همیشه با موفقیت خارج می‌شود (مگر اینکه در اتصال به URI خطایی رخ دهد).

nbdinfo --can connect URI

بررسی امکان برقراری اتصال به URI مربوط به NBD. این گزینه دست‌تکانی (handshake) پروتکل NBD را تا مرحله پردازش گزینه‌های NBD بررسی می‌کند، اما باز شدن حتمی اکسپورت را تضمین نمی‌نماید.

nbdinfo --is tls URI

بررسی اینکه آیا اتصال URI مربوط به NBD از TLS استفاده می‌کند یا خیر.

nbdinfo --has structured-reply URI

بررسی پشتیبانی کارساز از پاسخ‌های ساختاریافته (structured replies؛ که پیش‌نیاز پشتیبانی از دستورات وضعیت بلوک است).

nbdinfo --has extended-headers URI

بررسی پشتیبانی کارساز از هدرهای گسترش‌یافته (extended headers؛ که پیش‌نیاز پشتیبانی از دستورات ۶۴ بیتی است و شامل پاسخ‌های ساختاریافته نیز می‌شود).

nbdinfo --is rotational URI

بررسی اینکه آیا اکسپورت کارساز توسط رسانه‌ای شبیه به دیسک چرخان (rotational) پشتیبانی می‌شود: دسترسی به بلوک‌های مجاور ممکن است سریع‌تر از دسترسی تصادفی باشد و برای بهبود کارایی باید درخواست‌ها مرتب شوند. بسیاری از کارسازها این مورد را به درستی گزارش نمی‌دهند یا قادر به گزارش آن نیستند.

nbdinfo --can block-status-payload URI

بررسی اینکه آیا اکسپورت کارساز از ارسال پی‌لود کلاینت برای محدود کردن پاسخ به دستور وضعیت بلوک پشتیبانی می‌کند یا خیر.

nbdinfo --can cache URI

nbdinfo --can df URI

nbdinfo --can fast-zero URI

nbdinfo --can flush URI

nbdinfo --can fua URI

nbdinfo --can multi-conn URI

nbdinfo --can trim URI

nbdinfo --can zero URI

آزمون سایر مشخصات اکسپورت کارساز NBD.

در واقع گزینه‌های --can، --is و --has، و همچنین --cannot، --isnt و --hasnt مترادف یکدیگرند و می‌توانید آن‌ها را به جای هم به کار ببرید.

نقشه (Map)

برای نمایش نقشه‌ای از بخش‌های تخصیص‌یافته (allocated) و تُنُک (sparse) دیسک، از گزینه --map استفاده کنید:

$ nbdinfo --map nbd://localhost/
      0  1048576  0  data
1048576  1048576  3  hole,zero

فیلدها عبارتند از: نقطه آغاز (start)، اندازه (size)، نوع (type)، و توضیحات (description اختیاری).

فیلد نوع یک عدد صحیح است که مقدار خام پروتکل NBD را نشان می‌دهد. برای برخی نقشه‌ها، nbdinfo نحوه ترجمه نوع به یک توضیح قابل چاپ را می‌داند.

برای دریافت خروجی قابل تجزیه در قالب JSON، گزینه --json را اضافه کنید:

$ nbdinfo --map --json nbd://localhost/
[{ "offset": 0, "length": 1048576,
   "type": 0, "description": "data" },
 { "offset": 1048576, "length": 1048576,
   "type": 3, "description": "hole,zero" }]

به طور پیش‌فرض این دستور نقشه "base:allocation" را نشان می‌دهد، اما می‌توانید نقشه‌های دیگر را نیز نمایش دهید:

$ nbdinfo --map=qemu:dirty-bitmap:bitmap nbd://localhost/
0  1048576  1  dirty

برای اطلاعات بیشتر در مورد نقشه‌های NBD، به بخش Metadata querying در پروتکل NBD مراجعه کنید.

مجموع مقادیر نقشه (Map totals)

استفاده از --map --totals همان عملیات --map را انجام می‌دهد، اما خلاصه‌ای از اندازه کل هر نوع تخصیص را به بایت و به صورت درصد (از اندازه مجازی اکسپورت) نمایش می‌دهد. این امر برای تخمین میزان فضای واقعی استفاده‌شده در کارساز، یا فضای مورد نیاز هنگام کپی یک تصویر تُنُک با nbdcopy(1) مفید است.

در مثال زیر، نیمی (50.0%) از دیسک داده‌های تخصیص‌یافته و نیمی دیگر تخصیص‌نیافته است:

$ nbdinfo --map --totals nbd://localhost/
1048576  50.0%  0  data
1048576  50.0%  3  hole,zero

فیلدها عبارتند از: اندازه کل به بایت، درصد از اندازه مجازی، نوع، و توضیحات (اختیاری).

همچنین می‌توانید همین اطلاعات را به صورت ساختاریافته با استفاده از --json دریافت کنید:

$ nbdinfo --map --totals --json nbd://localhost/
[{ "size": 1048576, "percent": 50,
   "type": 0, "description": "data" },
 { "size": 1048576, "percent": 50,
   "type": 3, "description": "hole,zero" }]

همانند گزینه --map، این گزینه نیز به طور پیش‌فرض نقشه "base:allocation" را نشان می‌دهد، اما می‌توانید خلاصه سایر نقشه‌ها را نیز مشاهده کنید.

فهرست کردن تمام اکسپورت‌ها (List all exports)

برای فهرست کردن تمامی اکسپورت‌های موجود در یک کارساز NBD، از گزینه --list (-L) استفاده کنید. برای دریافت خروجی JSON قابل تجزیه، گزینه --json را اضافه نمایید.

برای نمونه:

$ nbdkit file dir=. --run 'nbdinfo --list "$uri"'
protocol: newstyle-fixed without TLS
export="Fedora-Workstation-Live-x86_64-29-1.2.iso":
    export-size: 1931476992 (1842M)
    uri: nbd://localhost:10809/Fedora-Workstation-Live-x86_64-29-1.2.iso
    [...]
export="debian-10.4.0-amd64-DVD-1.iso":
    export-size: 3955556352 (3862848K)
    uri: nbd://localhost:10809/debian-10.4.0-amd64-DVD-1.iso
    [...]

زیرپردازش (Subprocess)

دستور nbdinfo همچنین می‌تواند یک کارساز NBD را به صورت یک زیرپردازش اجرا کند. این کار به یک کارساز NBD نیاز دارد که از فعال‌سازی سوکت systemd پشتیبانی کند، مانند qemu-nbd(8) یا nbdkit(1). تمام حالت‌های معمول nbdinfo قابل استفاده هستند.

برای نمونه، جهت ارائه اطلاعات عمومی یا نمایش نقشه یک فایل qcow2:

nbdinfo -- [ qemu-nbd -r -f qcow2 file.qcow2 ]

nbdinfo --map -- [ qemu-nbd -r -f qcow2 file.qcow2 ]

توجه داشته باشید که "[ ... ]" پارامترهای مجزایی هستند و باید با فاصله احاطه شوند. "--" پارامترهای nbdinfo را از پارامترهای زیرپردازش تفکیک می‌کند.

ابزارهای جایگزین (Alternative tools)

می‌توانید از "qemu-img info" (ببینید: qemu-img(1)) برای پرس‌وجوی یک اکسپورت خاص از یک کارساز NBD استفاده کنید. دستور "qemu-nbd -L" (ببینید: qemu-nbd(8)) می‌تواند اکسپورت‌های NBD را فهرست کند. ابزار nbdsh(1) یا رابط برنامه‌نویسی libnbd(3) نیز می‌توانند برای پرس‌وجوهای پیچیده‌تر به کار روند.