guestfs-testing(1) Virtualization Support guestfs-testing(1)

guestfs-testing - آزمون دستی libguestfs؛ شما هم می‌توانید کمک کنید!

این صفحه شامل آزمون‌های دستی است که می‌توانید بر روی libguestfs امتحان کنید. هر فرد ترکیب اندکی متفاوتی از پلتفرم، سخت‌افزار و ماشین‌های مهمان دارد، بنابراین این آزمون‌ها بسیار ارزشمند هستند. از کمک شما سپاسگزاریم!

آزمون‌هایی که با علامت ستاره (*) مشخص شده‌اند، در صورت بی‌دقتی می‌توانند داده‌ها را نابود کنند. سایر آزمون‌ها ایمن هستند و چیزی را تغییر نمی‌دهند.

این آزمون‌ها به libguestfs ≥ 1.22 نیاز دارند.

می‌توانید اشکالاتی را که پیدا می‌کنید از طریق این پیوند گزارش دهید:

https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

یا در فهرست پستی مطرح کنید (ثبت‌نام الزامی نیست، اما اگر ثبت‌نام نکرده باشید باید منتظر بمانید تا مدیر به صورت دستی پیام شما را تأیید کند):

https://lists.libguestfs.org

دستور زیر را اجرا کنید:

libguestfs-test-tool

این دستور یک آزمون بسیار ساده و غیرمخرب انجام می‌دهد تا بررسی کند کارکردهای پایه libguestfs به درستی کار می‌کنند. نیازی به اجرای آن با دسترسی ریشه (root) ندارید.

اگر عبارت "===== TEST FINISHED OK =====" چاپ نشد، آن را به عنوان یک اشکال گزارش کنید. بسیار مهم است که خروجی کامل و دست‌نخورده دستور "libguestfs-test-tool" را در گزارش اشکال خود بگنجانید. به بخش "اشکالات (BUGS)" در انتهای این صفحه مراجعه کنید.

اگر میزبان شما شتاب‌دهنده سخت‌افزاری مجازی‌سازی دارد، با یک حافظه پنهان گرم (hot cache) باید بتواند libguestfs را در چند ثانیه راه‌اندازی کند. دستور زیر را چند بار اجرا نمایید:

time guestfish -a /dev/null run

پس از چند بار اجرا، زمان باید روی چند ثانیه تثبیت شود (زیر ۳ ثانیه در سخت‌افزارهای سریع ۶۴ بیتی).

اگر دستور بالا اصلاً کار نکرد، از libguestfs-test-tool(1) استفاده کنید.

به خروجی "libguestfs-test-tool" نگاه کرده و موارد زیر را بررسی کنید:

  • از کدام نسخه libguestfs استفاده می‌شود؟ در نزدیکی ابتدای خروجی خطی مانند این خواهید دید:
    library version: 1.22.0fedora=19,release=1.fc19,libvirt
  • آیا از libvirt استفاده می‌شود؟ با نگاه کردن به بک‌اند می‌توانید تفاوت را تشخیص دهید:
    guestfs_get_backend: direct

    یا:

    guestfs_get_backend: libvirt
  • از کدام نسخه qemu استفاده می‌شود؟ ممکن است چاپ شده باشد:
    libguestfs: qemu version 1.5
  • از کدام هسته (کرنل) استفاده می‌شود؟ ابزار supermin(1) تلاش خواهد کرد جدیدترین کرنل نصب‌شده روی سیستم شما را انتخاب کند. می‌توانید نسخه را در خروجی اپلاینس مشاهده کنید، به عنوان مثال:
    [    0.000000] Linux version 3.9.2-200.fc18.x86_64 [...]

برای این آزمون می‌توانید از هر ایمیج دیسک مهمانی استفاده کنید. اطمینان حاصل کنید که از گزینه "--ro" استفاده می‌کنید تا guestfish(1) ایمیج دیسک را به صورت فقط‌خواندنی باز کند.

guestfish --ro -a /path/to/disk.img -i

اگر دستور با موفقیت اجرا شود، باید نام سیستم‌عامل مهمان را چاپ کند و شما را در اعلان خط فرمان "><fs>" در guestfish قرار دهد. می‌توانید از دستورات guestfish مانند "ll /" برای بررسی داخل ایمیج دیسک استفاده کنید. برای خروج، عبارت "exit" را تایپ کنید.

اگر خطایی دریافت کردید، اشکال‌زدایی را فعال کنید (گزینه "-v" را به خط فرمان اضافه کنید). همچنین مطمئن شوید که libguestfs-test-tool(1) با موفقیت اجرا می‌شود.

همچنین ممکن است لازم باشد با تنظیم متغیر زیر، libvirt را غیرفعال کنید:

export LIBGUESTFS_BACKEND=direct

اگر ایمیج دیسکی در بستر HTTP/FTP در دسترس دارید، سعی کنید آن را باز کنید:

guestfish --ro -i --format=raw -a http://www.example.com/disk.img

برای SSH باید اطمینان حاصل کنید که ssh-agent تنظیم شده است تا برای ورود به ماشین راه دور نیازی به گذرواژه نداشته باشید. سپس دستوری مشابه دستور زیر باید کار کند:

guestfish --ro -i --format=raw \
  -a ssh://remote.example.com/path/to/disk.img

اگر با خطایی روبرو شدید، اشکال‌زدایی را فعال کنید (افزودن "-v" به خط فرمان). همچنین مطمئن شوید که libguestfs-test-tool(1) با موفقیت به پایان می‌رسد.

دستور virt-alignment-scan(1) را روی مهمان‌ها یا ایمیج‌های دیسک اجرا کنید:

virt-alignment-scan -a /path/to/disk.img

یا:

virt-alignment-scan -d Guest

آیا گزارش تراز با نحوه تراز بودن پارتیشن‌های مهمان مطابقت دارد؟

ابزار virt-cat(1) می‌تواند فایل‌های موجود در ماشین‌های مهمان را نمایش دهد. برای یک مهمان لینوکسی، این دستور را امتحان کنید:

virt-cat LinuxGuest /etc/passwd

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

virt-cat WindowsGuest 'c:\windows\win.ini'

یک آزمون حتی بهتر این است که یک ماشین مهمان ویندوزی با چند درایو داشته باشید. آیا مسیرهایی نظیر "D:"، "E:" و غیره به درستی کار می‌کنند؟

ابزار virt-copy-in(1) می‌تواند فایل‌ها و پوشه‌ها را به صورت بازگشتی درون یک مهمان یا ایمیج دیسک کپی کند.

virt-copy-in -d Guest /etc /tmp

این دستور باید دایرکتوری محلی /etc را در مسیر /tmp/etc داخل ماشین مهمان (به صورت بازگشتی) کپی کند. اگر مهمان را بوت کنید، آیا می‌توانید تمام فایل‌ها و پوشه‌های کپی‌شده را ببینید؟

مهمان را خاموش کرده و کپی چندین فایل و دایرکتوری را امتحان کنید:

virt-copy-in -d Guest /home /etc/issue /tmp

ابزار virt-copy-out(1) می‌تواند فایل‌ها و پوشه‌ها را به صورت بازگشتی به خارج از یک ماشین مهمان یا ایمیج دیسک کپی کند.

virt-copy-out -d Guest /home .

توجه داشته باشید که فاصله و نقطه پایانی در دستور یک غلط املایی نیست.

این دستور باید مسیر /home را از مهمان به دایرکتوری جاری کپی کند.

ابزار virt-df(1) فضای دیسک را فهرست می‌کند. دستور زیر را اجرا کنید:

virt-df

می‌توانید نتایج این دستور را با خروجی df(1) داخل ماشین مهمان مقایسه کنید، اما شروطی وجود دارد:

  • مهمان باید در حالت بیکار (idle) باشد.
  • دیسک‌های مهمان باید با استفاده از sync(1) همگام‌سازی شده باشند.
  • هر عملی مانند بوت کردن مهمان باعث نوشتن فایل‌های لاگ و در نتیجه تغییر اعداد می‌شود.

ما تضمین نمی‌کنیم که حتی تحت این شرایط نیز ارقام دقیقاً یکسان باشند. اما باید شبیه به هم باشند. دیدن تفاوت‌های بسیار بزرگ نشان‌دهنده یک اشکال خواهد بود.

دستور زیر را اجرا کنید:

virt-df --csv > /tmp/report.csv

اکنون سعی کنید این خروجی را در صفحه‌گسترده یا پایگاه‌داده دلخواه خود بارگذاری کنید. آیا نتایج به طور دقیق در صفحه‌گسترده/پایگاه‌داده بازتولید می‌شوند؟

http://www.postgresql.org/docs/8.1/static/sql-copy.html http://dev.mysql.com/doc/refman/5.1/en/load-data.html

ابزار virt-edit(1) می‌تواند فایل‌ها را در مهمان‌ها ویرایش کند. این دستور را روی یک مهمان RHEL یا Fedora امتحان کنید:

virt-edit LinuxGuest /etc/sysconfig/network

در سایر مهمان‌های لینوکسی، ویرایش فایل‌های دیگر را امتحان کنید مانند:

virt-edit LinuxGuest /etc/motd

آیا تغییرات پس از بوت‌شدن ماشین مهمان درون آن دیده می‌شوند؟

ابزار virt-filesystems(1) می‌تواند برای نمایش سیستم‌های فایل در یک مهمان استفاده شود. این دستور را روی هر ایمیج دیسک یا ماشین مهمانی امتحان کنید:

virt-filesystems -a /path/to/disk.img --all --long -h

یا:

virt-filesystems -d Guest --all --long -h

آیا نتایج با آنچه درون ماشین مهمان دیده می‌شود مطابقت دارند؟

از virt-inspector(1) برای دریافت گزارشی درباره تمام ماشین‌های مهمان یا ایمیج‌های دیسک خود استفاده کنید:

virt-inspector -a /path/to/disk.img | less

یا:

virt-inspector -d Guest | less

آیا نتایج با آنچه واقعاً درون ماشین مهمان قرار دارد مطابقت دارند؟

اگر یک مهمان نامتعارف دارید (یک توزیع نادر لینوکس، نسخه بسیار جدیدی از ویندوز)، آیا virt-inspector آن را شناسایی می‌کند؟ اگر نه، احتمالاً یک اشکال است.

فهرست کردن تمام برنامه‌های setuid یا setgid در یک ماشین مجازی لینوکس:

virt-ls -lR -d Guest / | grep '^- [42]'

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

virt-ls -lR -d Guest / | grep '^d ...7'

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

virt-ls -lR -d Guest / | grep '^s'

فهرست کردن تمام فایل‌های معمولی که نام آن‌ها به ‘.png’ ختم می‌شود:

virt-ls -lR -d Guest / | grep -i '^-.*\.png$'

نمایش فایل‌های بزرگ‌تر از 10MB در پوشه‌های خانگی (home):

virt-ls -lR -d Guest /home | awk '$3 > 10*1024*1024'

یافتن هر آنچه در ۷ روز گذشته تغییر یافته است:

virt-ls -lR -d Guest --time-days / | awk '$6 <= 7'

یافتن فایل‌های معمولی تغییریافته در ۲۴ ساعت گذشته:

virt-ls -lR -d Guest --time-days / | grep '^-' | awk '$6 < 1'

آیا نتایج با آنچه درون ماشین مهمان است مطابقت دارند؟

از virt-make-fs(1) برای ایجاد یک ایمیج دیسک از هر فایل tarball که در اختیار دارید استفاده کنید:

virt-make-fs --partition=mbr --type=vfat /any/tarball.tar.gz output.img

فایل ‘output.img’ را به عنوان یک دیسک خام (raw) به یک ماشین مهمان موجود اضافه کنید. بررسی کنید که آیا مهمان می‌تواند فایل‌ها را ببیند. این آزمون به ویژه اگر آن را با یک ماشین مهمان ویندوزی امتحان کنید بسیار مفید است.

طرح‌های پارتیشن‌بندی دیگر را نیز امتحان کنید، مثلاً --partition=gpt.

سایر قالب‌های سیستم‌فایل را نیز آزمایش کنید، مثلاً --type=ntfs، --type=ext2.

از virt-rescue(1) برای بررسی، نجات یا تعمیر یک ماشین مهمان یا ایمیج دیسک خاموش استفاده کنید:

virt-rescue -a /path/to/disk.img

یا:

virt-rescue -d Guest

آیا می‌توانید از دستورات معمولی شل برای بررسی ماشین مهمان استفاده کنید؟

از virt-resize(1) برای افزودن فضای دیسک بیشتر به یک ماشین مهمان استفاده کنید. برای نمونه اگر ایمیج دیسکی دارید که کوچک‌تر از 30G است، با دستورات زیر آن را به 30G افزایش دهید:

truncate -s 30G newdisk.img
virt-filesystems -a /path/to/olddisk.img --all --long -h
virt-resize /path/to/olddisk.img newdisk.img --expand /dev/sda1
qemu-kvm -m 1024 -hda newdisk.img

آیا ماشین مهمان هنوز بوت می‌شود؟ گسترش پارتیشن‌های دیگر را نیز امتحان کنید.

با استفاده از virt-sparsify(1)، ایمیج دیسک را تنک‌تر (کم‌حجم‌تر) کنید:

virt-sparsify /path/to/olddisk.img newdisk.img

آیا فایل newdisk.img پس از تنک‌سازی هنوز قابل بوت است؟ آیا حجم فایل ایمیج دیسک کوچک‌تر شده است (برای بررسی از "du" استفاده کنید)؟

با استفاده از virt-builder(1)، یک ماشین مهمان از فهرست انتخاب کنید:

virt-builder -l

آن را بسازید:

virt-builder -o disk.img [os-version from list above]

و آن را بوت کنید:

qemu-kvm -cpu host -m 2048 -drive file=disk.img,format=raw

آیا بوت می‌شود؟

توجه داشته باشید که این کار واقعاً پیکربندی مهمان موجود را به هم می‌ریزد، بنابراین بهتر است پیش از امتحان آن، یک کلون از ماشین مهمان تهیه کنید.

virt-sysprep --hostname newhost.example.com -a /path/to/disk.img

آیا sysprep موفقیت‌آمیز بود؟ پس از بوت شدن، چه تغییراتی اعمال شدند و آیا موفق بودند؟

از virt-win-reg(1) برای استخراج ریجستری ویندوز از هر مهمان ویندوزی که دارید استفاده کنید.

virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\Software' |
  less
virt-win-reg --unsafe-printable-strings WindowsGuest 'HKLM\System' |
  less

آیا خروجی با اجرای "regedit" در داخل مهمان مطابقت دارد؟

یکی از امکانات جدید، قابلیت استخراج ریجستری کاربران است، بنابراین این مورد را امتحان کنید و به جای username نام یک کاربر محلی در مهمان را قرار دهید:

virt-win-reg --unsafe-printable-strings WindowsGuest 'HKEY_USERS\username' |
  less

guestfs(3), guestfish(1), guestfs-examples(3), http://libguestfs.org

Richard W.M. Jones ("rjones at redhat dot com")

Copyright (C) 2011-2025 Red Hat Inc.

این کتابخانه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «مجوز عمومی همگانی کاهش‌یافته گنو» (GNU Lesser General Public License) طبق آنچه توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، بازتوزیع کرده و/یا تغییر دهید؛ چه نسخه ۲ مجوز یا (به انتخاب خودتان) هر نسخه پس از آن.

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

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

برای دریافت فهرستی از اشکالات 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) را اجرا کرده و خروجی کامل و دست‌نخورده آن را درون گزارش اشکال جای‌گذاری کنید.
2026-07-14 libguestfs-1.60.1