نام (NAME)

virt-inspector - نمایش نسخه سیستم‌عامل و سایر اطلاعات مربوط به یک ماشین مجازی

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

virt-inspector [--options] -d domname
virt-inspector [--options] -a disk.img [-a disk.img ...]

شیوه قدیمی:

virt-inspector domname
virt-inspector disk.img [disk.img ...]

توضیحات (DESCRIPTION)

دستور virt-inspector یک ماشین مجازی یا ایمیج دیسک را بررسی کرده و تلاش می‌کند تا نسخه سیستم‌عامل و سایر اطلاعات ماشین مجازی را تعیین کند.

ابزار Virt-inspector خروجی XML برای استفاده در سایر برنامه‌ها تولید می‌کند.

در حالت معمول، از "virt-inspector -d domname"; استفاده کنید که در آن "domname" دامنه libvirt است (ببینید: "virsh list --all").

همچنین می‌توانید virt-inspector را مستقیماً روی ایمیج‌های دیسک متعلق به یک ماشین مجازی منفرد اجرا کنید. از دستور "virt-inspector -a disk.img"; استفاده کنید. در موارد نادری که یک دامنه دارای چندین دستگاه بلوکی است، باید چندین گزینه -a را پشت سر هم مشخص کنید، به طوری که اولین گزینه متناظر با /dev/sda مهمان، دومین گزینه متناظر با /dev/sdb مهمان و به همین ترتیب باشد.

علاوه بر این می‌توانید virt-inspector را روی دیسک‌های نصب، دیسک‌های زنده (Live CD)، حافظه‌های فلش بوتیبل USB و موارد مشابه اجرا کنید.

ابزار Virt-inspector در هر بار فقط می‌تواند یک دامنه را بازرسی و گزارش کند. برای بررسی چندین ماشین مجازی، باید virt-inspector را چندین بار اجرا کنید (به عنوان مثال، از طریق یک حلقه for در اسکریپت شل).

از آنجا که virt-inspector به دسترسی مستقیم به ایمیج‌های مهمان نیاز دارد، معمولاً از طریق اتصالات ریموت libvirt کار نمی‌کند.

تمامی اطلاعات ارائه‌شده توسط virt-inspector، از طریق API اصلی بازرسی libguestfs نیز در دسترس است (بخش "INSPECTION" در guestfs(3) را ببینید). همین اطلاعات را می‌توان با استفاده از guestfish یا از طریق بایندرهای زبان‌های برنامه‌نویسی مختلف در libguestfs نیز به دست آورد (بخش "دریافت داده‌های بازرسی از طریق API LIBGUESTFS" را ببینید).

اطلاعات تکمیلی در مورد بوت‌لودر، کرنل و درایورهای داخل سیستم مهمان را می‌توان با استفاده از virt-drivers(1) پیدا کرد.

گزینه‌ها (OPTIONS)

--help

نمایش راهنمای مختصر.

-a file

--add file

افزودن file که باید یک ایمیج دیسک از یک ماشین مجازی باشد. اگر ماشین مجازی دارای چندین دستگاه بلوکی است، باید همه آن‌ها را با گزینه‌های -a جداگانه مشخص کنید.

فرمت ایمیج دیسک به طور خودکار شناسایی می‌شود. برای لغو این حالت و اجبار به یک فرمت خاص از گزینه --format=.. استفاده کنید.

-a URI

--add URI

افزودن یک دیسک از راه دور. بخش "ADDING REMOTE STORAGE" در guestfish(1) را ببینید.

--blocksize=512

--blocksize=4096

--blocksize

این پارامتر اندازه سکتور ایمیج دیسک را تنظیم می‌کند. این مورد بر تمام دیسک‌هایی که پس از این پارامتر صراحتاً اضافه می‌شوند تأثیر می‌گذارد. استفاده از --blocksize بدون آرگومان، اندازه سکتور دیسک را به مقدار پیش‌فرض که معمولاً ۵۱۲ بایت است تغییر می‌دهد. همچنین بخش "guestfs_add_drive_opts" در guestfs(3) را ببینید.

-c URI

--connect URI

در صورت استفاده از libvirt، به URI داده‌شده متصل می‌شود. در صورت عدم تعیین، به هایپروایزر پیش‌فرض libvirt متصل می‌شویم.

تنها در صورتی از libvirt استفاده می‌شود که یک "domname" را در خط فرمان مشخص کرده باشید. اگر دستگاه‌های بلوکی مهمان را مستقیماً تعیین کنید (-a)، از libvirt به هیچ وجه استفاده نمی‌شود.

-d guest

--domain guest

افزودن تمام دیسک‌های مربوط به مهمان libvirt مشخص‌شده. به جای نام می‌توان از UUID دامنه نیز استفاده کرد.

--echo-keys

هنگام درخواست کلیدها و عبارات عبور، virt-inspector معمولاً قابلیت نمایش نویسه‌ها (echo) را غیرفعال می‌کند تا نتوانید آنچه تایپ می‌کنید را ببینید. اگر نگران حملات تمپست (Tempest) نیستید و فرد دیگری در اتاق حضور ندارد، می‌توانید این فلگ را مشخص کنید تا تایپ خود را مشاهده نمایید.

--format=raw|qcow2|..

--format

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

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

هنگام کار با ایمیج‌های دیسک مهمان غیرقابل اعتماد با فرمت خام (raw)، باید اطمینان حاصل کنید که فرمت همیشه به صراحت مشخص شده باشد.

--key SELECTOR

مشخص کردن کلید برای LUKS، به منظور بازگشایی خودکار قفل دستگاه LUKS هنگام بازرسی.

--keys-from-stdin

خواندن پارامترهای کلید یا عبارت عبور از ورودی استاندارد (stdin). رفتار پیش‌فرض این است که با باز کردن /dev/tty تلاش شود عبارت عبور از کاربر خوانده شود.

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

--no-applications

به طور پیش‌فرض، خروجی virt-inspector شامل فهرست تمام برنامه‌های نصب‌شده در سیستم مهمان (در صورت در دسترس بودن) است.

این گزینه را برای غیرفعال کردن این بخش از خروجی XML مشخص کنید.

--no-icon

به طور پیش‌فرض، خروجی virt-inspector در صورت وجود شامل نماد (آیکون) مهمان است (بخش "icon" را ببینید).

این گزینه را برای غیرفعال کردن این بخش از خروجی XML تعیین کنید.

-v

--verbose

فعال‌سازی پیام‌های پرجزئیات برای اشکال‌زدایی.

-V

--version

نمایش شماره نسخه و خروج.

-x

فعال‌سازی ردیابی فراخوانی‌های API در libguestfs.

--xpath query

اجرای یک پرس‌وجوی XPath روی XML ارائه‌شده در stdin و چاپ نتیجه روی خروجی استاندارد (stdout). در این حالت virt-inspector فقط یک کوئری XPath را اجرا می‌کند؛ تمامی سایر قابلیت‌های بازرسی غیرفعال می‌شوند. برای نمونه‌ها به بخش "پرس‌وجوهای XPATH" در ادامه مراجعه کنید.

آرگومان‌های خط فرمان به شیوه قدیمی (OLD-STYLE COMMAND LINE ARGUMENTS)

نسخه‌های قبلی virt-inspector به شما امکان می‌دادند هر یک از موارد زیر را بنویسید:

virt-inspector disk.img [disk.img ...]

یا

virt-inspector guestname

در حالی که در این نسخه باید به ترتیب از -a یا -d استفاده کنید تا از حالت گیج‌کننده‌ای که در آن یک ایمیج دیسک ممکن است هم‌نام با یک مهمان باشد جلوگیری شود.

جهت حفظ سازگاری با گذشته، شیوه قدیمی همچنان پشتیبانی می‌شود.

فرمت XML (XML FORMAT)

ساختار XML تولیدی virt-inspector به طور دقیق در فایل طرح‌واره RELAX NG با نام virt-inspector.rng که همراه با libguestfs عرضه می‌شود توصیف شده است. این بخش صرفاً یک بررسی اجمالی است.

عنصر سطح بالا <operatingsystems> است و شامل یک یا چند عنصر <operatingsystem> می‌باشد. شما تنها زمانی بیش از یک عنصر <operatingsystem> خواهید دید که ماشین مجازی دارای چند سیستم‌عامل بوت‌شدنی (Multi-boot) باشد که در دنیای واقعی ماشین‌های مجازی بسیار نادر است.

<operatingsystems>
  <operatingsystem>
    <root>/dev/sda2</root>
    <name>windows</name>
    <arch>i386</arch>
    <distro>windows</distro>
    <product_name>Windows 7 Enterprise</product_name>
    <product_variant>Client</product_variant>
    <major_version>6</major_version>
    <minor_version>1</minor_version>
    <windows_systemroot>/Windows</windows_systemroot>

<operatingsystems>
  <operatingsystem>
    ...
    <mountpoints>
      <mountpoint dev="/dev/vg_f13x64/lv_root">/</mountpoint>
      <mountpoint dev="/dev/sda1">/boot</mountpoint>
    </mountpoints>

<operatingsystems>
  <operatingsystem>
    ...
    <filesystems>
      <filesystem dev="/dev/vg_f13x64/lv_root">
        <type>ext4</type>
        <label>Fedora-13-x86_64</label>
        <uuid>e6a4db1e-15c2-477b-ac2a-699181c396aa</uuid>
      </filesystem>

<operatingsystems>
  <operatingsystem>
    ...
    <applications>
      <application>
        <name>coreutils</name>
        <version>8.5</version>
        <release>1</release>
      </application>

<operatingsystems>
  <operatingsystem>
    ...
    <drive_mappings>
      <drive_mapping name="C">/dev/sda2</drive_mapping>
      <drive_mapping name="E">/dev/sdb1</drive_mapping>
    </drive_mappings>

<operatingsystems>
  <operatingsystem>
    ...
    <icon>
      iVBORw0KGgoAAAANSUhEUgAAAGAAAABg[.......]
      [... many lines of base64 data ...]
    </icon>

base64 -i -d < icon.data > icon.png

پرس‌وجوهای XPATH (XPATH QUERIES)

ابزار Virt-inspector شامل پشتیبانی توکار برای اجرای پرس‌وجوهای XPath است. دلیل گنجاندن مستقیم پشتیبانی از XPath در virt-inspector به سادگی این است که هیچ برنامه خط فرمانی خوب و گسترده‌ای که قادر به اجرای پرس‌وجوهای XPath باشد وجود ندارد. تنها برنامه مناسب xmlstarlet(1) است که آن هم در رد هت انترپرایز لینوکس در دسترس نیست.

برای اجرای پرس‌وجوی XPath، از گزینه --xpath استفاده کنید. توجه داشته باشید که در این حالت، virt-inspector به سادگی XML را از stdin می‌خواند و نتیجه پرس‌وجو را در stdout چاپ می‌کند. تمامی قابلیت‌های دیگر بازرسی در این حالت غیرفعال هستند.

برای مثال:

$ virt-inspector -d Guest | virt-inspector --xpath '//filesystems'
<filesystems>
     <filesystem dev="/dev/vg_f13x64/lv_root">
       <type>ext4</type>
[...]
$ virt-inspector -d Guest | \
    virt-inspector --xpath "string(//filesystem[@dev='/dev/sda1']/type)"
ext4
$ virt-inspector -d Guest | \
    virt-inspector --xpath 'string(//icon)' | base64 -i -d | display -
[در صورت وجود نماد مهمان، آن را نمایش می‌دهد]

دریافت داده‌های بازرسی از طریق API LIBGUESTFS (GETTING INSPECTION DATA FROM THE LIBGUESTFS API)

در نسخه‌های اولیه libguestfs، برنامه virt-inspector یک اسکریپت بزرگ Perl بود که شامل هیوریستیک‌ها (قواعد اکتشافی) متعددی برای بازرسی مهمان‌ها می‌شد. این رویکرد چندین مشکل داشت: برای انجام بازرسی از ابزارهای دیگر (مانند guestfish) مجبور بودیم این اسکریپت پرل را صدا بزنیم؛ و همچنین به زبان Perl نسبت به سایر زبان‌های تحت پشتیبانی libguestfs برتری و اولویت می‌داد.

تا زمان انتشار libguestfs 1.8، کد Perl را به زبان C بازنویسی کردیم و تمام آن را در API هسته libguestfs ادغام نمودیم (guestfs(3)). اکنون virt-inspector صرفاً یک برنامه C سبک روی API اصلی زبان C است. تمامی اطلاعات بازرسی از تمام زبان‌های برنامه‌نویسی که libguestfs پشتیبانی می‌کند و همچنین از طریق guestfish در دسترس است.

برای مطالعه توضیحات مربوط به C inspection API، بخش "INSPECTION" در guestfs(3) را بخوانید.

برای کدهای نمونه با استفاده از C inspection API، فایل inspect-vm.c را که همراه با libguestfs عرضه می‌شود بررسی کنید.

فایل inspect-vm.c به زبان‌های دیگر نیز ترجمه شده است. برای مثال، inspect_vm.pl ترجمه پرل آن است و ترجمه‌های دیگری نیز برای OCaml، Python و غیره وجود دارد. بخش "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES" در guestfs(3) را برای فهرستی از صفحات راهنما که شامل این کد نمونه هستند ببینید.

$ guestfish --ro -a F15x32.img
><fs> run
><fs> inspect-os
/dev/vg_f15x32/lv_root

><fs> inspect-get-type /dev/vg_f15x32/lv_root
linux
><fs> inspect-get-distro /dev/vg_f15x32/lv_root
fedora
><fs> inspect-get-major-version /dev/vg_f15x32/lv_root
15
><fs> inspect-get-product-name /dev/vg_f15x32/lv_root
Fedora release 15 (Lovelock)

><fs> inspect-get-mountpoints /dev/vg_f15x32/lv_root
/: /dev/vg_f15x32/lv_root
/boot: /dev/vda1
><fs> mount-ro /dev/vg_f15x32/lv_root /
><fs> mount-ro /dev/vda1 /boot

><fs> inspect-list-applications /dev/vg_f15x32/lv_root | head -28
[0] = {
  app_name: ConsoleKit
  app_display_name:
  app_epoch: 0
  app_version: 0.4.5
  app_release: 1.fc15
  app_install_path:
  app_trans_path:
  app_publisher:
  app_url:
  app_source_package:
  app_summary:
  app_description:
}
[1] = {
  app_name: ConsoleKit-libs
  app_display_name:
  app_epoch: 0
  app_version: 0.4.5
  app_release: 1.fc15
  app_install_path:
  app_trans_path:
  app_publisher:
  app_url:
  app_source_package:
  app_summary:
  app_description:
}

><fs> inspect-get-icon /dev/vg_f15x32/lv_root | display -

نسخه‌های قدیمی VIRT-INSPECTOR (OLD VERSIONS OF VIRT-INSPECTOR)

همان‌طور که در بالا توضیح داده شد، نسخه‌های اولیه libguestfs همراه با یک برنامه متفاوت virt-inspector که با Perl نوشته شده بود عرضه می‌شدند (نسخه فعلی با C نوشته شده است). خروجی XML برنامه قدیمی پرل متفاوت بود و همچنین می‌توانست در قالب‌های دیگری مانند متن خروجی دهد.

برنامه قدیمی virt-inspector دیگر پشتیبانی نمی‌شود و همراه با libguestfs عرضه نمی‌گردد.

برای پیچیده‌تر شدن موضوع، در رد هت انترپرایز لینوکس ۶ دو نسخه از virt-inspector با نام‌های مختلف عرضه شده بود:

virt-inspector     نسخه قدیمی Perl.
virt-inspector2    نسخه جدید C.

وضعیت خروج (EXIT STATUS)

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

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

guestfs(3), guestfish(1), http://www.w3.org/TR/xpath, base64(1), xmlstarlet(1), virt-drivers(1), http://libguestfs.org.

نویسندگان (AUTHORS)

• Richard W.M. Jones http://people.redhat.com/~rjones
• Matthew Booth mbooth@redhat.com

حق نشر (COPYRIGHT)

Copyright (C) 2010-2025 Red Hat Inc.

مجوز (LICENSE)

این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط اجازه‌نامه عمومی همگانی گنو (GNU GPL) که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است؛ چه نسخه ۲ اجازه‌نامه و چه (به انتخاب خودتان) هر نسخه بعدی، بازتوزیع کرده یا تغییر دهید.

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

شما باید به همراه این برنامه یک نسخه از اجازه‌نامه عمومی همگانی گنو را دریافت کرده باشید؛ در غیر این صورت، به آدرس زیر بنویسید: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

اشکالات (BUGS)

برای مشاهده فهرست اشکالات ثبت‌شده برای libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

برای گزارش یک اشکال جدید برای libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

هنگام گزارش اشکال، لطفاً موارد زیر را ارائه دهید:

• نسخه libguestfs.
• محل تهیه libguestfs (مثلاً کدام توزیع لینوکس، کامپایل‌شده از سورس‌کد و غیره).
• شرح دقیق اشکال و ارائه راهی برای بازتولید آن.
• دستور libguestfs-test-tool(1) را اجرا کرده و خروجی کامل و ویرایش‌نشده آن را در گزارش اشکال قرار دهید.