guestfs-release-notes-1.26(1) Virtualization Support guestfs-release-notes-1.26(1)

guestfs-release-notes - یادداشت‌های انتشار libguestfs

این یادداشت‌های انتشار تنها تفاوت‌ها نسبت به تفکیک شاخه پایدار/توسعه قبلی (1.24.0) را پوشش می‌دهند. برای گزارش تغییرات تفصیلی، لطفاً مخزن git یا فایل ChangeLog توزیع‌شده در بسته tarball را بررسی کنید.

ابزارها (Tools)

ابزار virt-customize(1) ابزاری جدید برای سفارشی‌سازی ایمیج‌های دیسک ماشین مجازی است. این ابزار به شما امکان نصب بسته‌ها، ویرایش فایل‌های پیکربندی، اجرای اسکریپت‌ها، تنظیم گذرواژه‌ها و موارد دیگر را می‌دهد. ابزارهای virt-builder(1) و virt-sysprep(1) از virt-customize استفاده می‌کنند، و گزینه‌های خط فرمان در تمام این ابزارها اکنون یکسان است.

ابزار virt-diff(1) ابزاری جدید برای نمایش تفاوت‌های میان سیستم‌فایل‌های دو ماشین مجازی است. کاربرد اصلی آن نمایش فایل‌های تغییریافته میان دو تصویر لحظه‌ای (snapshot) است.

ابزار virt-builder(1) به‌طور چشمگیری بهبود یافته است. روش‌های بسیار بیشتری برای سفارشی‌سازی ماشین مجازی وجود دارد. این ابزار می‌تواند الگوها را از چندین مخزن دریافت کند. پیاده‌سازی داخلی و موازی‌شده‌ی xzcat سرعت استخراج الگوها را افزایش می‌دهد. ابزار Virt-builder از یک برنامه‌ریز بهینه‌ساز برای انتخاب سریع‌ترین روش ساخت ماشین مجازی استفاده می‌کند. اکنون استفاده از virt-builder از طریق برنامه‌های دیگر آسان‌تر شده است. پشتیبانی از بین‌المللی‌سازی به فراداده‌ها (metadata) اضافه شده است. برچسب‌گذاری مجدد SELinux روی فایل‌ها بهینه‌تر شده است. قابلیت ساخت سیستم‌های میهمان برای چندین معماری فراهم شده است. پیام‌های خطا بهبود یافته‌اند. (Pino Toscano)

ابزار virt-sparsify(1) دارای گزینه جدید --in-place است. این گزینه یک ایمیج را درجا (بدون رونوشت‌برداری از آن) تنک (sparsify) می‌کند و بسیار سریع‌تر است. (با کمک‌های بسیار از طرف Paolo Bonzini)

ابزار virt-sysprep(1) می‌تواند فایل‌ها را تحت کنترل کاربر حذف و پاکسازی (scrub) کند. شما می‌توانید حساب‌های کاربری را قفل کنید یا برای حساب‌ها گذرواژه‌های تصادفی تعیین نمایید. این ابزار می‌تواند فایل‌های گزارش (log) بیشتری را پاک کند. می‌تواند یک سیستم میهمان را از سامانه Red Hat Subscription Manager لغو اشتراک کند. روشی منعطف و جدید برای فعال و غیرفعال کردن عملیات‌ها افزوده شده است. (Wanlong Gao, Pino Toscano)

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

ابزار virt-format(1) اکنون می‌تواند فضای اضافی بازیابی‌شده را به میزبان بازگرداند.

ابزار guestfish(1) متغیرهای محیطی بیشتری دارد تا کنترل دقیقی روی خط اعلان "><fs>" ارائه دهد. Guestfish اکنون فایل پیکربندی (به‌ندرت استفاده‌شده‌ی) خود را با ترتیبی متفاوت می‌خواند تا تنظیمات محلی بر تنظیمات سراسری اولویت داشته باشند. (Pino Toscano)

ابزار virt-make-fs(1) مجدداً به زبان C بازنویسی شد، اما از نظر عملکرد و نحوه استفاده در خط فرمان بدون تغییر مانده است.

بستارهای زبان‌های برنامه‌نویسی (Language bindings)

بستارهای OCaml دارای یک ماژول جدید "Guestfs.Errno" هستند که برای بررسی شماره خطای بازگردانده‌شده توسط "Guestfs.last_errno" استفاده می‌شود.

آزمون‌های PHP اکنون به درستی کار می‌کنند. (Pino Toscano)

بازرسی (Inspection)

بخش بازرسی (Inspection) می‌تواند ایمیج‌های زنده (live images) دبیان را شناسایی کند.

معماری‌ها (Architectures)

معماری ARMv7 (نسخه ۳۲ بیتی) اکنون از شتاب‌دهنده KVM پشتیبانی می‌کند.

معماری Aarch64 (نسخه ۶۴ بیتی ARM) پشتیبانی می‌شود، اما بخش appliance هنوز کار نمی‌کند.

پشتیبانی از PPC64 اصلاح و تقویت شده است..SS "امنیت (Security)"

ممانعت از سرویس‌دهی هنگام بازرسی ایمیج‌های دیسک دارای حجم‌های آسیب‌دیده btrfs
امکان از کار انداختن libguestfs (و برنامه‌هایی که از libguestfs به عنوان یک کتابخانه استفاده می‌کنند) با ارائه یک ایمیج دیسک حاوی یک حجم آسیب‌دیده btrfs وجود داشت.

این اشکال ناشی از ارجاع به اشاره‌گر تهی (NULL pointer dereference) بود که باعث ممانعت از سرویس‌دهی (denial of service) می‌شد، و گمان نمی‌رود فراتر از این قابل بهره‌برداری باشد.

برای اصلاحیه، کامیت d70ceb4cbea165c960710576efac5a5716055486 را ببینید. این اصلاحیه در شاخه‌های پایدار libguestfs با نگارش‌های ≥ 1.26.0، ≥ 1.24.6 و ≥ 1.22.8 و همچنین در RHEL با نگارش ≥ 7.0 گنجانده شده است. نگارش‌های قبلی libguestfs آسیب‌پذیر نیستند.

تولید بهتر گذرواژه‌های تصادفی root و بذرهای تصادفی
هنگام تولید گذرواژه‌های تصادفی root و بذرهای تصادفی، دو اشکال که احتمالاً به امنیت مرتبط بودند رفع شدند. نخست، دیگر بایت‌های بیش از حد از /dev/urandom خوانده نمی‌شوند (که بیشتر آن‌ها بدون استفاده دور ریخته می‌شدند). دوم، کد را تغییر دادیم تا از انحراف پیمانه‌ای (modulo bias) جلوگیری شود. تصور نمی‌شد که این مشکلات قابل بهره‌برداری باشند. (هر دو تغییر توسط Edwin Török پیشنهاد شده است)

اکنون پارامترهای GUID هنگام ارسال به فراخوانی‌های API اعتبارسنجی می‌شوند، در حالی که پیش‌تر ارسال هر رشته‌ای امکان‌پذیر بود. (Pino Toscano)

رابط‌های برنامه‌نویسی جدید (New APIs)

"guestfs_add_drive_opts": پارامتر جدید "discard"
پارامتر جدید "discard" امکان کنترل دقیق روی پشتیبانی از discard/trim را برای یک دیسک خاص فراهم می‌کند. این امر باعث می‌شود هنگام حذف فایل‌ها یا ارسال فراخوانی APIیِ "guestfs_fstrim"، فایل میزبان تنک‌تر (sparse) (یا thin-provisioned) شود.
"guestfs_add_domain": پارامترهای جدید: "cachemode"، "discard"
این پارامترها هنگام افزودن دیسک‌های دامنه به لایه‌های زیرین منتقل می‌شوند.
"guestfs_blkdiscard"
دور ریختن (Discard) تمام بلوک‌ها روی یک دستگاه guestfs. این کار در ترکیب با پارامتر "discard" در بالا، فایل میزبان را تنک (sparse) می‌کند.
"guestfs_blkdiscardzeroes"
بررسی اینکه آیا بلوک‌های دور ریخته‌شده (discarded) به صورت صفر بازخوانی می‌شوند یا خیر.
"guestfs_compare_*"
"guestfs_copy_*"
به ازای هر ساختاری (struct) که از طریق API بازگردانده می‌شود، اکنون libguestfs توابع "guestfs_compare_*" و "guestfs_copy_*" را تولید می‌کند تا به شما امکان مقایسه و کپی کردن این ساختارها را بدهد.
"guestfs_copy_attributes"
کپی کردن ویژگی‌ها (مانند مجوزها، xattrs، مالکیت) از یک فایل به فایل دیگر. (Pino Toscano)
"guestfs_disk_create"
یک API منعطف برای ایجاد ایمیج‌های دیسک خالی از صفر. این امر نیاز به فراخوانی برنامه‌های خارجی مانند qemu-img(1) را برطرف می‌کند.
"guestfs_get_backend_settings"
"guestfs_set_backend_settings"
تنظیمات اختصاصی به ازای هر پس‌فراور (backend) (همچنین می‌تواند از طریق متغیر محیطی "LIBGUESTFS_BACKEND_SETTINGS" تنظیم شود). کاربرد اصلی این مورد، تحمیل حالت TCG در پس‌فراورهای مبتنی بر qemu است؛ به عنوان مثال: 
export LIBGUESTFS_BACKEND=direct
export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
"guestfs_part_get_name"
دریافت برچسب یا نام یک افراز (برای ایمیج‌های دیسک GPT).

بسته‌های اضافی زیر برای ساخت libguestfs 1.26 مورد نیاز هستند:

نگارش ۵ از Supermin برای ساخت این نسخه از libguestfs لازم است.
اکنون Virt-builder برای تجزیه فایل متادیتای خود از یک تجزیه‌کننده واقعی استفاده می‌کند، بنابراین این ابزارها الزامی هستند.
این مورد اکنون یک وابستگی ساخت الزامی است، در حالی که پیش‌تر (از نظر تئوری) اختیاری بود.

استخراج پیام‌های PO برای پایداری بیشتر بازنویسی شد. (Pino Toscano)

در صورتی که الگوی آرگومان --insert یا --verbatim پیدا نشود، "podwrapper" خطایی صادر می‌کند.

اکنون libguestfs در صورتی که qemu پشتیبانی کند، گزینه -enable-fips را برای فعال‌سازی FIPS به qemu ارسال می‌کند.

اگر نمی‌خواهید هایپروایزر پیش‌فرضی را تعیین کنید، می‌توانید از "./configure --without-qemu" استفاده نمایید.

لایه‌های هم‌پوشان کپی‌هنگام‌نوشتن [COW] (که به عنوان مثال برای درایوهای فقط‌خواندنی استفاده می‌شوند)، اکنون از طریق یک API داخلی پس‌فراور (".create_cow_overlay") ایجاد می‌شوند.

پس‌فراور libvirt از ماکروهای C جالبی برای تولید XML استفاده می‌کند. این ماکروها ساده‌تر و ایمن‌تر هستند.

قالب فایل ChangeLog تغییر کرده است. اکنون به جای استفاده از یک قالب سفارشی، دقیقاً مشابه با "git log" است.

راه‌اندازی اپلاینس (Appliance) تغییر کرده است:

  • اپلاینس libguestfs اکنون LVM را به همان شیوه‌ای که در ماشین‌های فیزیکی انجام می‌شود مقداردهی اولیه می‌کند.
  • اپلاینس libguestfs هنگام راه‌اندازی، رشته‌ای خالی در /proc/sys/kernel/hotplug نمی‌نویسد.

    توجه داشته باشید که باید هسته خود را طوری پیکربندی کنید که دارای "CONFIG_UEVENT_HELPER_PATH=""" باشد، در غیر این صورت با خطاهای عجیب LVM مواجه خواهید شد (این موضوع برای هر ماشین لینوکسی صادق است، نه فقط libguestfs). (Peter Rajnoha)

اکنون libguestfs می‌تواند روی معماری‌هایی ساخته شود که ocamlc(1) را دارند اما فاقد ocamlopt(1) هستند. (Hilko Bengen, Olaf Hering)

نمی‌توانید از "./configure --disable-daemon --enable-appliance" استفاده کنید. در هر حال این کار هیچ منطقی نداشت. اکنون اسکریپت configure صراحتاً از آن جلوگیری می‌کند.

فایل packagelist به جای "cpp" از "m4" برای بسط ماکروها استفاده می‌کند..SS "باگ‌های برطرف‌شده (Bugs fixed)"

بایندینگ‌های java در inspect_list_applications2 خطای java.lang.ArrayIndexOutOfBoundsException پرتاب می‌کنند:
[RFE] فعال‌سازی عملیات clean یا unregister در subscription manager برای sysprep
دستور virt-resize نام پارتیشن‌های GPT را حفظ نمی‌کند
دستور mount-local در صورت سوار نشدن ریشه (root) باید خطای واضح‌تری ارائه دهد
دستور virt-sparsify در صورت استفاده از دستگاه‌های بلوکی به‌عنوان فایل‌های خروجی، آن‌ها را بازنویسی می‌کند
libguestfs: error: invalid backend: appliance
تابع guestfs_pvs در صورت مفقود بودن یک حجم فیزیکی، عبارت “unknown device” را چاپ می‌کند
تنظیمات پیش‌فرض توصیه‌شده برای ساعت/تایمر
بسته ruby-libguestfs هنگام فراخوانی Guestfs::Guestfs.new خطای “expecting 0 or 1 arguments” صادر می‌کند
عدم امکان بازرسی کامل تصویر دیسک cirros 0.3.1
متغیر LIBVIRT_DEFAULT_URI=qemu:///system عملکرد libguestfs را مختل می‌کند
شبکه virt-builder (برای مثال --install) در صورتی که در resolv.conf مقدار nameserver روی 127.0.0.1 تنظیم شده باشد کار نمی‌کند
هنگام نصب بودن SSSD، پیکربندی libvirt نیازمند احراز هویت است، اما این موضوع برای کاربر مشخص نیست
شکست virt-make-fs در ایجاد fat/vfat روی کل دیسک: Device partition expected, not making filesystem on entire device '/dev/sda' (use -I to override)
حذف فایل‌های گزارش (logfiles) بیشتر توسط virt-sysprep
درخواست ویژگی (RFE): بخش بازرسی libguestfs سی‌دی زنده Free4NAS را شناسایی نمی‌کند
درخواست ویژگی (RFE): دستورهای virt-sysprep/virt-builder باید گزینه‌ای برای قفل کردن حساب کاربری داشته باشند
شکست libguestfs در بررسی ماشین مهمان libvirt با درایوهای ceph: rbd: image name must begin with a '/'
شکست virt-builder در صورتی که $HOME/.cache وجود نداشته باشد
ابزار libguestfs: عدم استفاده از فایل jar نسخه‌بندی‌شده
تمام عملیات‌های LVM در libguestfs روی Debian/Ubuntu با شکست مواجه می‌شوند
نیاز به به‌روزرسانی متن راهنمای خروجی در part-set-gpt-type
دستور virt-sysprep نام میزبان (hostname) را در Debian/Ubuntu به‌درستی تنظیم نمی‌کند
ابزار guestfish نویسه تحت‌اللفظی "\n" را در پیام‌های خطا چاپ می‌کند
ابزار guestmount: دستور "touch" شکست می‌خورد: touch: setting times of `timestamp': Invalid argument
[RFE] تابعی برای دریافت نام پارتیشن
دستور list-devices دستگاه‌های با انواع مختلف را خارج از ترتیب برمی‌گرداند

guestfs-examples(1), guestfs-faq(1), guestfs-performance(1), guestfs-recipes(1), guestfs-testing(1), guestfs(3), guestfish(1), http://libguestfs.org

Richard W.M. Jones

Copyright (C) 2009-2025 Red Hat Inc.

این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «پروانه عمومی همگانی گنو» (GNU 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