.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Podwrapper::Man 1.60.1 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "guestfs-faq 1" .TH guestfs-faq 1 2026-07-14 libguestfs-1.60.1 "Virtualization Support" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "نام (NAME)" guestfs\-faq \- پرسش‌های متداول libguestfs (FAQ) .SH "درباره LIBGUESTFS (ABOUT LIBGUESTFS)" .IX Header "ABOUT LIBGUESTFS" .SS "libguestfs چیست؟" .IX Subsection "What is libguestfs?" ابزار libguestfs روشی برای ساخت، دسترسی و تغییر ایمیج‌های دیسک است. شما می‌توانید محتوای درون ایمیج‌های دیسک را بررسی کنید، فایل‌های درون آن‌ها را تغییر دهید، آن‌ها را از ابتدا بسازید، اندازه آن‌ها را تغییر دهید و کارهای بسیار دیگری را انجام دهید. این ابزار به‌ویژه در اسکریپت‌ها، برنامه‌ها و خط فرمان بسیار کاربردی است. .PP ابزار libguestfs یک کتابخانه C است (از این‌رو پیشوند «lib\-»)، و مجموعه‌ای از ابزارهای ساخته‌شده بر پایه این کتابخانه و بایندرهایی (bindings) برای بسیاری از زبان‌های برنامه‌نویسی رایج است. .PP برای کسب اطلاعات بیشتر درباره کارهایی که libguestfs می‌تواند انجام دهد، مقدمه موجود در صفحه خانگی (http://libguestfs.org) را مطالعه کنید. .SS "ابزارهای virt چه هستند؟" .IX Subsection "What are the virt tools?" ابزارهای virt (وب‌گاه: http://virt\-tools.org) مجموعه کاملی از ابزارهای مدیریت مجازی‌سازی با هدف استفاده مدیران سیستم هستند. برخی از آن‌ها از libguestfs، برخی از libvirt و بسیاری دیگر از پروژه‌های متن‌باز دیگر می‌آیند. بنابراین virt tools یک ابرمجموعه از libguestfs محسوب می‌شود. با این حال libguestfs همراه با ابزارهای مهم بسیاری ارائه می‌شود. برای مشاهده فهرست کامل به http://libguestfs.org مراجعه کنید. .SS "آیا libguestfs به { libvirt / KVM / Red Hat / Fedora } نیاز دارد؟" .IX Subsection "Does libguestfs need { libvirt / KVM / Red Hat / Fedora }?" خیر! .PP بسته libvirt پیش‌نیازی برای libguestfs نیست. .PP ابزار libguestfs با هر ایمیج دیسکی کار می‌کند، از جمله موارد ساخته‌شده در VMware، KVM، qemu، VirtualBox، Xen و بسیاری از هایپروایزرهای دیگر، و همچنین ایمیج‌هایی که خودتان از ابتدا ساخته‌اید. .PP شرکت Red\ Hat حامی مالی توسعه libguestfs و خیل عظیمی از دیگر پروژه‌های متن‌باز است (یعنی هزینه‌های آن را می‌پردازد). اما شما می‌توانید libguestfs و ابزارهای virt را روی توزیع‌های مختلف لینوکس و Mac OS X اجرا کنید. ما تمام تلاشمان را می‌کنیم تا از همه توزیع‌های لینوکس به عنوان شهروندان درجه اول پشتیبانی کنیم. برخی از ابزارهای virt به Windows نیز پورت شده‌اند. .SS "مقایسه libguestfs با سایر ابزارها چگونه است؟" .IX Subsection "How does libguestfs compare to other tools?" .IP "\fIدر مقایسه با kpartx\fR" 4 .IX Item "vs. kpartx" ابزار Libguestfs رویکرد متفاوتی نسبت به kpartx در پیش می‌گیرد. ابزار kpartx به کاربر ریشه (root) نیاز دارد و فایل‌سیستم‌ها را روی هسته میزبان سوار (mount) می‌کند (که می‌تواند ناامن باشد \- \&\fBguestfs\-security\fR\|(1) را ببینید). Libguestfs هسته میزبان شما را از مهمان‌ها ایزوله می‌کند، انعطاف‌پذیرتر و قابل اسکریپت‌نویسی است، از LVM پشتیبانی می‌کند، به دسترسی ریشه (root) نیاز ندارد، از سایر فرایندها جدا است و پس از پایان کار تمیزکاری را انجام می‌دهد. Libguestfs چیزی فراتر از دسترسی ساده به فایل است زیرا می‌توانید با استفاده از آن ایمیج‌ها را از ابتدا بسازید. .IP "\fIدر مقایسه با vdfuse\fR" 4 .IX Item "vs. vdfuse" ابزار vdfuse مشابه kpartx است اما برای ایمیج‌های VirtualBox کاربرد دارد. مقایسه بالا با kpartx را ببینید. می‌توانید از libguestfs بر روی فایل‌های پارتیشن نمایان‌شده توسط vdfuse استفاده کنید، اگرچه این کار ضروری نیست زیرا libguestfs می‌تواند مستقیماً به ایمیج‌های VirtualBox دسترسی داشته باشد. .IP "\fIدر مقایسه با qemu\-nbd\fR" 4 .IX Item "vs. qemu-nbd" پروتکل NBD (Network Block Device) پروتکلی برای اشتراک‌گذاری دستگاه‌های بلوکی روی شبکه است. ابزار qemu\-nbd یک کارساز (سرور) NBD است که می‌تواند با هر قالب دیسک پشتیبانی‌شده توسط qemu (مانند raw، qcow2) کار کند. می‌توانید از libguestfs و qemu\-nbd یا nbdkit به همراه یکدیگر برای دسترسی به دستگاه‌های بلوکی روی شبکه استفاده کنید، برای نمونه: \f(CW\*(C`guestfish \-a nbd://remote\*(C'\fR .IP "\fIدر مقایسه با سوار کردن فایل‌سیستم‌ها در میزبان\fR" 4 .IX Item "vs. mounting filesystems in the host" سوار کردن فایل‌سیستم‌های مهمان در سیستم میزبان ناامن است و برای سیستم‌های مهمان نامعتبر باید کاملاً از آن اجتناب شود. از libguestfs برای فراهم آوردن لایه‌ای محافظ در برابر اکسپلویت‌های فایل‌سیستم استفاده کنید. همچنین \&\fBguestmount\fR\|(1) را ببینید. .IP "\fIدر مقایسه با parted\fR" 4 .IX Item "vs. parted" ابزار Libguestfs از LVM پشتیبانی می‌کند. Libguestfs از parted استفاده می‌کند و بیشتر قابلیت‌های parted را از طریق API مربوط به libguestfs ارائه می‌دهد..SH "دریافت راهنمایی و گزارش باگ‌ها (GETTING HELP AND REPORTING BUGS)" .IX Header "GETTING HELP AND REPORTING BUGS" .SS "چگونه بدانم از چه نسخه‌ای استفاده می‌کنم؟" .IX Subsection "How do I know what version I'm using?" ساده‌ترین روش عبارت است از: .PP .Vb 1 \& guestfish \-\-version .Ve .PP توسعهٔ Libguestfs در یک شاخهٔ ناپایدار (unstable) انجام می‌شود و ما به‌صورت دوره‌ای یک شاخهٔ پایدار (stable) ایجاد می‌کنیم که وصله‌های پایدار به آن بک‌پورت (backport) می‌شوند. برای اطلاعات بیشتر، بخش \(lqLIBGUESTFS VERSION NUMBERS\(rq را در \fBguestfs\fR\|(3) مطالعه کنید. .SS "چگونه می‌توانم راهنمایی بگیرم؟" .IX Subsection "How can I get help?" .SS "چه فهرست‌های ایمیل یا اتاق‌های گفتگویی در دسترس هستند؟" .IX Subsection "What mailing lists or chat rooms are available?" اگر از مشتریان Red\ Hat هستید و از Red Hat Enterprise Linux استفاده می‌کنید، لطفاً با پشتیبانی Red\ Hat تماس بگیرید: http://redhat.com/support .PP یک فهرست ایمیل (mailing list) وجود دارد که عمدتاً برای اهداف توسعه است، اما کاربران نیز می‌توانند پرسش‌های خود را دربارهٔ libguestfs و ابزارهای virt مطرح کنند: https://lists.libguestfs.org .PP همچنین می‌توانید در کانال IRC با نام \f(CW\*(C`#guestfs\*(C'\fR در Libera Chat با ما گفتگو کنید. ما همیشه حضور نداریم، بنابراین لطفاً پس از مطرح کردن پرسش خود در کانال بمانید تا شخصی به شما پاسخ دهد. .PP برای سایر ابزارهای virt (مواردی که همراه با libguestfs ارائه نمی‌شوند) یک فهرست ایمیل عمومی برای ابزارهای virt وجود دارد: https://www.redhat.com/mailman/listinfo/virt\-tools\-list .SS "چگونه باگ‌ها را گزارش کنم؟" .IX Subsection "How do I report bugs?" لطفاً از پیوند زیر برای ثبت باگ در Bugzilla استفاده کنید: .PP https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools .PP تا حد امکان جزئیات و همچنین روشی برای بازتولید مشکل ارائه دهید. .PP خروجی کامل دستور \fBlibguestfs\-test\-tool\fR\|(1) را نیز ضمیمه کنید. .SH "مشکلات رایج (COMMON PROBLEMS)" .IX Header "COMMON PROBLEMS" همچنین بخش \(lqLIBGUESTFS GOTCHAS\(rq را در \fBguestfs\fR\|(3) برای برخی نکات فنی و ظرافت‌های استفاده از API مربوط به libguestfs بررسی کنید. .SS """Could not allocate dynamic translator buffer""" .IX Subsection """Could not allocate dynamic translator buffer""" این خطای مبهم در واقع یک شکست در SELinux است. باید متغیر بولی (boolean) زیر را در SELinux فعال کنید: .PP .Vb 1 \& setsebool \-P virt_use_execmem=on .Ve .PP برای اطلاعات بیشتر ببینید: https://bugzilla.redhat.com/show_bug.cgi?id=806106 .SS """child process died unexpectedly""" .IX Subsection """child process died unexpectedly""" [این پیام خطا در libguestfs 1.21.18 به متنی گویاتر تغییر یافته است.] .PP این خطا نشان می‌دهد که qemu شکست خورده یا هستهٔ میزبان (host kernel) نتوانسته بوت شود. برای کسب اطلاعات بیشتر دربارهٔ علت خطا، باید دستور زیر را اجرا کنید: .PP .Vb 1 \& libguestfs\-test\-tool .Ve .PP اگر پس از اجرای این ابزار همچنان علت خطا را متوجه نشدید، با ما تماس بگیرید (بخش قبلی را ببینید). .SS "libguestfs: error: cannot find any suitable libguestfs supermin, fixed or old\-style appliance on LIBGUESTFS_PATH" .IX Subsection "libguestfs: error: cannot find any suitable libguestfs supermin, fixed or old-style appliance on LIBGUESTFS_PATH" .SS "febootstrap\-supermin\-helper: ext2: parent directory not found" .IX Subsection "febootstrap-supermin-helper: ext2: parent directory not found" .SS "supermin\-helper: ext2: parent directory not found" .IX Subsection "supermin-helper: ext2: parent directory not found" [این مشکل به‌صورت دائمی در libguestfs ≥ 1.26 برطرف شده است.] .PP اگر با هر یک از این خطاها در Debian/Ubuntu مواجه شدید، باید فرمان زیر را اجرا کنید: .PP .Vb 1 \& sudo update\-guestfs\-appliance .Ve .SS "خطای \(lqPermission denied\(rq هنگام اجرای libguestfs با دسترسی ریشه (root)" .IX Subsection """Permission denied"" when running libguestfs as root" هنگام باز کردن تصویر دیسک (disk image)، حتی با وجود اینکه libguestfs را با دسترسی ریشه (root) اجرا می‌کنید، خطای عدم دسترسی (permission denied) دریافت می‌کنید. .PP این مشکل از جانب libvirt رخ می‌دهد و بنابراین تنها هنگام استفاده از بک‌اند libvirt اتفاق می‌افتد. هنگامی که برنامه با دسترسی ریشه اجرا می‌شود، libvirt تصمیم می‌گیرد appliance متعلق به qemu را با کاربر \f(CW\*(C`qemu.qemu\*(C'\fR اجرا کند. متأسفانه این وضعیت معمولاً به این معنی است که qemu نمی‌تواند تصاویر دیسک را باز کند، به‌ویژه اگر مالکیت آن تصاویر متعلق به root باشد، یا در دایرکتوری‌هایی قرار داشته باشند که نیازمند دسترسی root است. .PP یک گزارش باگ برای رفع این مشکل در libvirt باز است: https://bugzilla.redhat.com/show_bug.cgi?id=1045069 .PP می‌توانید با یکی از روش‌های زیر این مشکل را دور بزنید: .IP \(bu 4 تغییر به بک‌اند مستقیم (direct backend): .Sp .Vb 1 \& export LIBGUESTFS_BACKEND=direct .Ve .IP \(bu 4 اجرا نکردن libguestfs با کاربر ریشه (root). .IP \(bu 4 تغییر سطح دسترسی (chmod) تصویر دیسک و دایرکتوری‌های والد آن به‌گونه‌ای که کاربر qemu بتواند به آن‌ها دسترسی داشته باشد. .IP \(bu 4 (روش نامطلوب) ویرایش \fI/etc/libvirt/qemu.conf\fR و تغییر مقدار تنظیم \f(CW\*(C`user\*(C'\fR. .SS "execl: /init: Permission denied" .IX Subsection "execl: /init: Permission denied" \&\fBنکته:\fR اگر این خطا هنگام استفاده از بستهٔ توزیع libguestfs (مانند Fedora، Debian و غیره) رخ دهد، یک گزارش باگ برای آن توزیع ثبت کنید. این خطایی نیست که کاربران عادی در صورت آماده‌سازی صحیح بستهٔ توزیع با آن مواجه شوند. .PP این خطا در طول مرحلهٔ بوت supermin هنگام راه‌اندازی appliance رخ می‌دهد: .PP .Vb 5 \& supermin: mounting new root on /root \& supermin: chroot \& execl: /init: Permission denied \& supermin: debug: listing directory / \& [...followed by a lot of debug output...] .Ve .PP این یک باگ پیچیده مربوط به applianceهای \fBsupermin\fR\|(1) است. این appliance با کپی کردن فایل‌هایی مانند \fI/bin/bash\fR و کتابخانه‌های متعدد از سیستم میزبان ساخته می‌شود. فایل \f(CW\*(C`hostfiles\*(C'\fR فهرستی از فایل‌هایی را که باید از سیستم میزبان به درون appliance کپی شوند تعیین می‌کند. اگر برخی از فایل‌ها روی سیستم میزبان وجود نداشته باشند نادیده گرفته می‌شوند، اما در صورتی که این فایل‌ها برای (مثلاً) اجرای \fI/bin/bash\fR ضروری باشند، خطای بالا را مشاهده خواهید کرد. .PP عیب‌یابی این مشکل نیازمند بررسی کتابخانه‌های مورد نیاز \fI/bin/bash\fR است، یعنی: .PP .Vb 1 \& ldd /bin/bash .Ve .PP و مقایسهٔ آن با \f(CW\*(C`hostfiles\*(C'\fR، با فایل‌های واقعاً موجود در فایل‌سیستم میزبان، و با خروجی اشکال‌زدایی چاپ‌شده در پیام خطا. زمانی که متوجه شدید کدام فایل مفقود شده است، آن فایل را با استفاده از مدیر بستهٔ خود نصب کرده و دوباره امتحان کنید. .PP همچنین باید بررسی کنید که فایل‌هایی مانند \fI/init\fR و \fI/bin/bash\fR (درون appliance) قابل اجرا (executable) باشند. خروجی اشکال‌زدایی، حالت‌های دسترسی فایل (file modes) را نشان می‌دهد..SH "بارگیری، نصب و کامپایل LIBGUESTFS (DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS)" .IX Header "DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS" .SS "از کجا می‌توانم آخرین فایل‌های باینری را برای ... دریافت کنم؟" .IX Subsection "Where can I get the latest binaries for ...?" .IP "Fedora ≥ 11" 4 .IX Item "Fedora ≥ 11" استفاده کنید از: .Sp .Vb 1 \& yum install \*(Aq*guestf*\*(Aq .Ve .Sp برای آخرین ساخت‌ها، ببینید: http://koji.fedoraproject.org/koji/packageinfo?packageID=8391 .IP "Red Hat Enterprise Linux" 4 .IX Item "Red Hat Enterprise Linux" .RS 4 .PD 0 .IP "RHEL 6" 4 .IX Item "RHEL 6" .IP "RHEL 7" 4 .IX Item "RHEL 7" .PD این بسته بخشی از نصب پیش‌فرض است. تنها در RHEL 6 و 7 باید \f(CW\*(C`libguestfs\-winsupport\*(C'\fR را برای دریافت پشتیبانی از مهمان Windows نصب کنید. .RE .RS 4 .RE .IP "Debian و Ubuntu" 4 .IX Item "Debian and Ubuntu" برای libguestfs < 1.26، پس از نصب libguestfs باید این دستور را اجرا کنید: .Sp .Vb 1 \& sudo update\-guestfs\-appliance .Ve .Sp (این اسکریپت در Debian/Ubuntu با libguestfs ≥ 1.26 حذف شده است و در عوض اپلاینس بنا بر تقاضا ساخته می‌شود.) .Sp تنها در Ubuntu: .Sp .Vb 1 \& sudo chmod 0644 /boot/vmlinuz* .Ve .Sp ممکن است لازم باشد خود را به گروه \f(CW\*(C`kvm\*(C'\fR اضافه کنید: .Sp .Vb 1 \& sudo usermod \-a \-G kvm yourlogin .Ve .RS 4 .IP "Debian Squeeze (6)" 4 .IX Item "Debian Squeeze (6)" ‏Hilko Bengen بسته libguestfs را در squeeze backports ساخته است: http://packages.debian.org/search?keywords=guestfs&searchon=names§ion=all&suite=squeeze\-backports .IP "Debian Wheezy و بعد از آن (+7)" 4 .IX Item "Debian Wheezy and later (7+)" ‏Hilko Bengen از libguestfs در Debian پشتیبانی می‌کند. بسته‌های رسمی Debian در دسترس هستند: http://packages.debian.org/search?keywords=libguestfs .IP Ubuntu 4 .IX Item "Ubuntu" ما نگه‌دارنده تمام‌وقتی برای Ubuntu نداریم، و بسته‌های ارائه‌شده توسط Canonical (که خارج از کنترل ما هستند) گاهی اوقات معیوب هستند. .Sp شرکت Canonical تصمیم گرفت مجوزهای هسته را طوری تغییر دهد که به جز کاربر ریشه (root) قابل خواندن نباشد. این کار کاملاً احمقانه است، اما آن‌ها آن را تغییر نخواهند داد (https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725). بنابراین هر کاربری باید این کار را انجام دهد: .Sp .Vb 1 \& sudo chmod 0644 /boot/vmlinuz* .Ve .RS 4 .IP "Ubuntu 12.04" 4 .IX Item "Ubuntu 12.04" ‏libguestfs در این نسخه از Ubuntu کار می‌کند، اما لازم است febootstrap و seabios را به آخرین نسخه‌ها به‌روزرسانی کنید. .Sp شما به febootstrap ≥ 3.14\-2 از نشانی زیر نیاز دارید: http://packages.ubuntu.com/precise/febootstrap .Sp پس از نصب یا به‌روزرسانی febootstrap، اپلاینس را بازسازی کنید: .Sp .Vb 1 \& sudo update\-guestfs\-appliance .Ve .Sp شما به seabios ≥ 0.6.2\-0ubuntu2.1 یا ≥ 0.6.2\-0ubuntu3 از نشانی‌های زیر نیاز دارید: http://packages.ubuntu.com/precise\-updates/seabios یا http://packages.ubuntu.com/quantal/seabios .Sp همچنین باید این کار را انجام دهید (بالا را ببینید): .Sp .Vb 1 \& sudo chmod 0644 /boot/vmlinuz* .Ve .RE .RS 4 .RE .RE .RS 4 .RE .IP Gentoo 4 .IX Item "Gentoo" پروژه Libguestfs در 2012\-07 توسط Andreis Vinogradovs (بخش libguestfs) و Maxim Koltsov (عمدتاً hivex) به Gentoo اضافه شد. اجرا کنید: .Sp .Vb 1 \& emerge libguestfs .Ve .IP Mageia 4 .IX Item "Mageia" پروژه Libguestfs در 2013\-08 به Mageia اضافه شد. اجرا کنید: .Sp .Vb 1 \& urpmi libguestfs .Ve .IP SuSE 4 .IX Item "SuSE" پروژه Libguestfs در سال ۲۰۱۲ توسط Olaf Hering به SuSE اضافه شد. .IP ArchLinux 4 .IX Item "ArchLinux" پروژه Libguestfs در سال ۲۰۱۰ به AUR اضافه شد. .IP "سایر توزیع‌های لینوکس" 4 .IX Item "Other Linux distro" از سورس کامپایل کنید (بخش بعدی). .IP "سایر توزیع‌های غیرلینوکسی" 4 .IX Item "Other non-Linux distro" باید آن را از سورس کامپایل کرده و پورت کنید..SS "چگونه می‌توانم libguestfs را از کد مبدأ کامپایل و نصب کنم؟" .IX Subsection "چگونه می‌توانم libguestfs را از کد مبدأ کامپایل و نصب کنم؟" شما می‌توانید libguestfs را از git یا یک tarball کد مبدأ کامپایل کنید. پیش از شروع، فایل README را بخوانید. .PP مخزن Git: https://github.com/libguestfs/libguestfs فایل‌های فشرده مبدأ (tarballs): http://libguestfs.org/download .PP دستور \f(CW\*(C`make install\*(C'\fR را اجرا نکنید! در عوض از اسکریپت \f(CW\*(C`./run\*(C'\fR استفاده کنید (README را ببینید). .SS "اگر توزیع من qemu/supermin/kernel به اندازه کافی جدید نداشته باشد، چگونه می‌توانم libguestfs را کامپایل و نصب کنم؟" .IX Subsection "اگر توزیع من qemu/supermin/kernel به اندازه کافی جدید نداشته باشد، چگونه می‌توانم libguestfs را کامپایل و نصب کنم؟" کتابخانه libguestfs به supermin 5 نیاز دارد. اگر supermin 5 برای توزیع شما پورت نشده است، پرسش زیر را بررسی کنید. .PP ابتدا qemu،‏ supermin و/یا kernel را از کد مبدأ کامپایل کنید. شما نیازی \&\fIندارید\fR که آن‌ها را \f(CW\*(C`make install\*(C'\fR کنید. .PP در دایرکتوری کد مبدأ libguestfs، دو فایل بسازید. فایل \f(CW\*(C`localconfigure\*(C'\fR باید شامل موارد زیر باشد: .PP .Vb 3 \& source localenv \& #export PATH=/tmp/qemu/x86_64\-softmmu:$PATH \& ./configure \-\-prefix /usr "$@" .Ve .PP فایل \f(CW\*(C`localconfigure\*(C'\fR را قابل اجرا کنید. .PP فایل \&\f(CW\*(C`localenv\*(C'\fR باید حاوی موارد زیر باشد: .PP .Vb 5 \& #export SUPERMIN=/tmp/supermin/src/supermin \& #export LIBGUESTFS_HV=/tmp/qemu/x86_64\-softmmu/qemu\-system\-x86_64 \& #export SUPERMIN_KERNEL=/tmp/linux/arch/x86/boot/bzImage \& #export SUPERMIN_KERNEL_VERSION=4.XX.0 \& #export SUPERMIN_MODULES=/tmp/lib/modules/4.XX.0 .Ve .PP این خطوط را بر حسب نیاز برای استفاده از برنامه‌های جایگزینی که کامپایل کرده‌اید، از حالت کامنت خارج و تنظیم کنید. .PP به جای \f(CW\*(C`./configure\*(C'\fR از \f(CW\*(C`./localconfigure\*(C'\fR استفاده کنید، اما در باقی موارد libguestfs را مانند همیشه کامپایل کنید. .PP دستور \f(CW\*(C`make install\*(C'\fR را اجرا نکنید! در عوض از اسکریپت \f(CW\*(C`./run\*(C'\fR استفاده کنید (README را ببینید). .SS "چگونه می‌توانم libguestfs را بدون supermin کامپایل و نصب کنم؟" .IX Subsection "چگونه می‌توانم libguestfs را بدون supermin کامپایل و نصب کنم؟" اگر supermin 5 از توزیع شما پشتیبانی می‌کند، اما شما تصادفاً نسخه به اندازه کافی جدیدی از supermin را نصب ندارید، پرسش پیشین را ببینید. .PP اگر supermin 5 اصلاً از توزیع شما پشتیبانی نمی‌کند، باید از «روش appliance ثابت» (fixed appliance method) استفاده کنید که در آن از یک appliance باینری از پیش کامپایل‌شده استفاده می‌شود. برای ساخت libguestfs بدون supermin، باید گزینهٔ \&\f(CW\*(C`\-\-disable\-appliance \-\-disable\-daemon\*(C'\fR را به \fI./configure\fR یا \&\fI./configure\fR ارسال کنید (بسته به این که به ترتیب از git می‌سازید یا از tarballها). سپس هنگام استفاده از libguestfs، \fBباید\fR متغیر محیطی \f(CW\*(C`LIBGUESTFS_PATH\*(C'\fR را روی دایرکتوری appliance از پیش کامپایل‌شده تنظیم کنید، همان‌طور که در بخش "FIXED APPLIANCE" در \fBguestfs\-internals\fR\|(1) نیز شرح داده شده است. .PP برای applianceهای از پیش کامپایل‌شده، همچنین ببینید: http://libguestfs.org/download/binaries/appliance .PP وصله‌ها (Patches) برای پورت کردن supermin به توزیع‌های بیشتر لینوکس با استقبال پذیرفته می‌شوند. .SS "چگونه می‌توانم پشتیبانی از sVirt را اضافه کنم؟" .IX Subsection "چگونه می‌توانم پشتیبانی از sVirt را اضافه کنم؟" \&\fBنکته برای کاربران Fedora/RHEL:\fR این پیکربندی از Fedora\ 18 و RHEL\ 7 به صورت پیش‌فرض فعال است. اگر با مشکلی مواجه شدید، لطفاً به ما اطلاع دهید یا یک باگ گزارش کنید. .PP قابلیت sVirt با استفاده از SELinux یک appliance سخت‌سازی‌شده (hardened) را فراهم می‌کند، که فرار (escape) یک ایمیج دیسک سرکش را از محیط قرنطینهٔ libguestfs و آسیب زدن به میزبان بسیار دشوار می‌سازد (منصفانه است بگوییم که حتی در حالت استاندارد libguestfs نیز این امر سخت خواهد بود، اما sVirt یک لایه حفاظتی اضافه برای میزبان ایجاد می‌کند و مهم‌تر از آن، ماشین‌های مجازی مستقر بر روی همان میزبان را از یکدیگر محافظت می‌کند). .PP در حال حاضر برای فعال کردن sVirt به libvirt نسخهٔ ۰.۱۰.۲ یا بالاتر (ترجیحاً نسخهٔ ۱.۰ یا جدیدتر)، libguestfs نسخهٔ ۱.۲۰ یا بالاتر، و خط‌مشی‌های SELinux نسخه‌های اخیر Fedora نیاز دارید. اگر از Fedora\ 18+ استفاده نمی‌کنید، باید تغییراتی در خط‌مشی SELinux خود اعمال کنید \- از طریق لیست پستی با ما در تماس باشید. .PP پس از فراهم کردن پیش‌نیازها، این دستورها را اجرا کنید: .PP .Vb 3 \& ./configure \-\-with\-default\-backend=libvirt # libguestfs >= 1.22 \& ./configure \-\-with\-default\-attach\-method=libvirt # libguestfs <= 1.20 \& make .Ve .PP سیستم SELinux را روی حالت Enforcing تنظیم کنید؛ پس از آن sVirt باید به طور خودکار به کار گرفته شود. .PP تمام، یا تقریباً تمام ویژگی‌های libguestfs باید تحت sVirt کار کنند. یک کاستی شناخته‌شده وجود دارد: \fBvirt\-rescue\fR\|(1) از libvirt (و در نتیجه sVirt) استفاده نخواهد کرد، بلکه به اجرای مستقیم qemu بازمی‌گردد. بنابراین در حال حاضر هنگام استفاده از virt\-rescue از مزایای حفاظتی sVirt بهره‌مند نخواهید شد. .PP می‌توانید با فعال کردن گزارش‌گیری libvirtd (مسیر \&\fI/etc/libvirt/libvirtd.log\fR را ببینید)، متوقف کردن و راه‌اندازی مجدد libvirtd، و بررسی فایل‌های لاگ برای پیام‌های "Setting\ SELinux\ context\ on\ ..." استفاده شدن sVirt را بررسی کنید. .PP از نظر تئوری sVirt باید از AppArmor پشتیبانی کند، اما ما آن را آزمایش نکرده‌ایم. این کار تقریباً به طور قطع نیازمند وصله زدن libvirt و نگارش یک خط‌مشی AppArmor خواهد بود. .SS "ابزار libguestfs فهرست وابستگی‌های بسیار طولانی‌ای دارد!" .IX Subsection "ابزار libguestfs فهرست وابستگی‌های بسیار طولانی‌ای دارد!" کتابخانه اصلی وابستگی‌های زیادی ندارد، اما سه دلیل برای وجود این فهرست طولانی از دیگر وابستگی‌ها وجود دارد: .IP 1. 4 ابزار libguestfs باید بتواند قالب‌های بسیار متفاوتی از دیسک را خوانده و ویرایش کند. برای مثال، پشتیبانی از XFS به ابزارهای XFS نیاز دارد. .IP 2. 4 بایندینگ‌ها (Language bindings) برای زبان‌های گوناگونی وجود دارند که همگی نیازمند ابزارهای توسعه مختص به خود هستند. تمامی بایندینگ‌های زبان‌ها (به جز C) اختیاری هستند. .IP 3. 4 برخی ویژگی‌های اختیاری در کتابخانه وجود دارند که امکان غیرفعال کردن آن‌ها هست. .PP از نسخه libguestfs ≥ 1.26 تفکیک وابستگی‌های appliance (مورد ۱ در فهرست بالا) امکان‌پذیر شده است و در نتیجه می‌توان برای پردازش ایمیج‌های دیسک XFS به عنوان نمونه \&\f(CW\*(C`libguestfs\-xfs\*(C'\fR را به عنوان یک زیربستهٔ مجزا در اختیار داشت. ما بسته‌بندهای پایین‌دست را تشویق می‌کنیم که تقسیم بسته اصلی libguestfs به زیربسته‌های کوچک‌تر را آغاز کنند..SS "خطاها هنگام راه‌اندازی در Fedora ≥ 18 و RHEL ≥ 7" .IX Subsection "خطاها هنگام راه‌اندازی در Fedora ≥ 18 و RHEL ≥ 7" در Fedora ≥ 18 و RHEL ≥ 7، libguestfs از libvirt برای مدیریت appliance استفاده می‌کند. پیش‌تر (و در upstream)، libguestfs نرم‌افزار qemu را مستقیماً اجرا می‌کرد: .PP .Vb 10 \& ┌──────────────────────────────────┐ \& │ libguestfs │ \& ├────────────────┬─────────────────┤ \& │ direct backend │ libvirt backend │ \& └────────────────┴─────────────────┘ \& ↓ ↓ \& ┌───────┐ ┌──────────┐ \& │ qemu │ │ libvirtd │ \& └───────┘ └──────────┘ \& ↓ \& ┌───────┐ \& │ qemu │ \& └───────┘ \& \& upstream Fedora 18+ \& non\-Fedora RHEL 7+ \& non\-RHEL .Ve .PP بک‌اند libvirt پیشرفته‌تر است و از SELinux/sVirt (به بالا مراجعه کنید) و موارد دیگر پشتیبانی می‌کند. با این حال، پیچیده‌تر بوده و در نتیجه پایداری کمتری دارد. .PP اگر هنگام استفاده از بک‌اند libvirt با مشکلات مجوز مواجه شدید، می‌توانید با تنظیم این متغیر محیطی: .PP .Vb 1 \& export LIBGUESTFS_BACKEND=direct .Ve .PP پیش از اجرای هر برنامه libguestfs یا ابزار virt، به بک‌اند direct سوییچ کنید. .SS "چگونه می‌توانم به یک appliance ثابت / از پیش‌ساخته سوییچ کنم؟" .IX Subsection "چگونه می‌توانم به یک appliance ثابت / از پیش‌ساخته سوییچ کنم؟" این کار ممکن است پایداری و کارایی libguestfs را در Fedora و RHEL بهبود بخشد. .PP در هر زمانی پس از نصب libguestfs، دستورهای زیر را به عنوان ریشه (root) اجرا کنید: .PP .Vb 3 \& mkdir \-p /usr/local/lib/guestfs/appliance \& libguestfs\-make\-fixed\-appliance /usr/local/lib/guestfs/appliance \& ls \-l /usr/local/lib/guestfs/appliance .Ve .PP اکنون متغیر محیطی زیر را پیش از استفاده از libguestfs یا هر ابزار virt تنظیم نمایید: .PP .Vb 1 \& export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance .Ve .PP البته می‌توانید مسیر را به هر دایرکتوری که می‌خواهید تغییر دهید. شما می‌توانید appliance را میان ماشین‌هایی با معماری یکسان (مثلاً همگی x86\-64) به اشتراک بگذارید، اما توجه داشته باشید که libvirt به دلیل مشکلات مجوز دسترسی، مانع از اشتراک‌گذاری appliance روی NFS خواهد شد (بنابراین یا به بک‌اند direct سوییچ کنید یا از NFS استفاده نکنید). .SS "چگونه می‌توانم سرعت ساخت libguestfs را افزایش دهم؟" .IX Subsection "چگونه می‌توانم سرعت ساخت libguestfs را افزایش دهم؟" با اختلاف، مهم‌ترین کاری که می‌توانید انجام دهید نصب و پیکربندی مناسب Squid است. توجه داشته باشید که پیکربندی پیش‌فرضی که همراه با Squid عرضه می‌شود بسیار ناکارآمد است، بنابراین پیکربندی آن اختیاری نیست. .PP نقطه شروع بسیار مناسب برای پیکربندی Squid در این نشانی قرار دارد: https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads .PP اطمینان حاصل کنید که Squid در حال اجرا است و متغیرهای محیطی \&\f(CW$http_proxy\fR و \f(CW$ftp_proxy\fR به آن اشاره دارند. .PP با اجرای Squid و پیکربندی درست آن، زمان ساخت appliance باید به چند دقیقه کاهش یابد. .PP \fIچگونه می‌توانم سرعت ساخت libguestfs را در دبیان (Debian) افزایش دهم؟\fR .IX Subsection "چگونه می‌توانم سرعت ساخت libguestfs را در دبیان (Debian) افزایش دهم؟" .PP هیلکو بنگن (Hilko Bengen) پیشنهاد می‌کند از "approx" که یک پروکسی آرشیو دبیان است استفاده کنید (http://packages.debian.org/approx). این ابزار در دبیان در صفحه راهنمای \fBapprox\fR\|(8) مستند شده است. .SH "سرعت و فضای دیسک مصرف‌شده توسط LIBGUESTFS (SPEED, DISK SPACE USED BY LIBGUESTFS)" .IX Header "سرعت و فضای دیسک مصرف‌شده توسط LIBGUESTFS (SPEED, DISK SPACE USED BY LIBGUESTFS)" \&\fBنکته:\fR بیشتر اطلاعات این بخش جابجا شده است: \&\fBguestfs\-performance\fR\|(1). .SS "بارگذاری یا نوشتن بسیار کُند به نظر می‌رسد." .IX Subsection "بارگذاری یا نوشتن بسیار کُند به نظر می‌رسد." اگر دیسک زیرین به طور کامل تخصیص نیافته باشد (مثلاً sparse raw یا qcow2)، عملیات نوشتن ممکن است کُند باشد چرا که سیستم‌عامل میزبان هنگام نوشتن شما، ناچار به انجام تخصیص‌های پرهزینه دیسک است. راه‌حل این است که در عوض از قالبی کاملاً تخصیص‌یافته استفاده کنید؛ یعنی non\-sparse raw، یا qcow2 همراه با گزینه \f(CW\*(C`preallocation=metadata\*(C'\fR. .SS "ابزار Libguestfs بیش از حد فضای دیسک مصرف می‌کند!" .IX Subsection "ابزار Libguestfs بیش از حد فضای دیسک مصرف می‌کند!" ابزار libguestfs یک appliance نسبتاً بزرگ را در این مسیر کش می‌کند: .PP .Vb 1 \& /var/tmp/.guestfs\- .Ve .PP اگر متغیر محیطی \f(CW\*(C`TMPDIR\*(C'\fR تعریف شده باشد، به جای آن از \&\fR\f(CI$TMPDIR\fR\fI/.guestfs\-\fR استفاده می‌شود. .PP هنگامی که از libguestfs استفاده نمی‌کنید، حذف این دایرکتوری کاملاً بی‌خطر است. .SS "به نظر می‌رسد virt\-sparsify حجم ایمیج را به اندازه کامل دیسک مجازی می‌رساند" .IX Subsection "به نظر می‌رسد virt-sparsify حجم ایمیج را به اندازه کامل دیسک مجازی می‌رساند" اگر ورودی به \fBvirt\-sparsify\fR\|(1) از نوع raw باشد، آنگاه خروجی به صورت raw sparse خواهد بود. مطمئن شوید که خروجی را با ابزاری اندازه می‌گیرید که مفهوم تنک بودن (sparseness) را متوجه می‌شود، مانند \f(CW\*(C`du \-sh\*(C'\fR. این می‌تواند تفاوت بسیار چشمگیری ایجاد کند: .PP .Vb 4 \& $ ls \-lh test1.img \& \-rw\-rw\-r\-\-. 1 rjones rjones 100M Aug 8 08:08 test1.img \& $ du \-sh test1.img \& 3.6M test1.img .Ve .PP (اندازه ظاهری \fB100M\fR را با اندازه واقعی \fB3.6M\fR مقایسه کنید) .PP اگر این موضوع برای شما گیج‌کننده است، با تعیین گزینه \fI\-\-convert\fR از یک قالب خروجی غیرتنک (non\-sparse) استفاده نمایید؛ برای نمونه: .PP .Vb 1 \& virt\-sparsify \-\-convert qcow2 disk.raw disk.qcow2 .Ve.SS "چرا virt\-resize روی ایمیج دیسک درجا (in\-place) کار نمی‌کند؟" .IX Subsection "Why doesn't virt-resize work on the disk image in-place?" تغییر اندازه یک ایمیج دیسک بسیار حساس و پیچیده است \-\- به‌ویژه اطمینان از اینکه داده‌ای از دست نرود یا به بوت‌لودر آسیبی نرسد. روش فعلی عملاً یک ایمیج دیسک جدید می‌سازد و داده‌ها به همراه بوت‌لودر را از ایمیج قدیمی کپی می‌کند. اگر مشکلی پیش بیاید، همیشه می‌توانید به نسخه اصلی بازگردید. .PP اگر قرار بود کاری کنیم که virt\-resize به صورت درجا (in\-place) کار کند، محدودیت‌هایی به وجود می‌آمد: برای نمونه، اجازه جابه‌جایی پارتیشن‌های موجود را نداشتید (زیرا جابه‌جایی داده‌ها درون همان دیسک در صورت قطعی برق یا خرابی ناگهانی سیستم، به احتمال بسیار زیاد به خراب شدن داده‌ها می‌انجامد)، و پشتیبانی از LVM بسیار دشوار می‌بود (به دلیل نگاشت تقریباً دلخواه بین محتوای LV و بلوک‌های دیسک زیرین). .PP روش دیگری که در نظر گرفته‌ایم، قرار دادن یک اسنپ‌شات روی ایمیج دیسک اصلی است تا داده‌های اصلی دست‌نخورده باقی بمانند و فقط تغییرات در اسنپ‌شات ثبت شوند. امروزه می‌توانید با استفاده از \&\f(CW\*(C`qemu\-img create\*(C'\fR + \f(CW\*(C`virt\-resize\*(C'\fR این کار را انجام دهید، اما qemu در حال حاضر آن‌قدر هوشمند نیست که تشخیص دهد چه زمانی همان بلوکی که از قبل در دیسک پشتیبان وجود دارد مجدداً روی اسنپ‌شات نوشته می‌شود، بنابراین متوجه خواهید شد که این روش هیچ فضا یا زمانی برای شما صرفه‌جویی نمی‌کند. .PP به طور خلاصه، این مسئله‌ای دشوار است، و روشی که اکنون داریم عمدتاً به درستی کار می‌کند، بنابراین تمایلی به تغییر آن نداریم. .SS "چرا virt\-sparsify روی ایمیج دیسک درجا (in\-place) کار نمی‌کند؟" .IX Subsection "Why doesn't virt-sparsify work on the disk image in-place?" در libguestfs نسخه ۱.۲۶ و جدیدتر (libguestfs ≥ 1.26)، اکنون virt\-sparsify می‌تواند روی ایمیج‌های دیسک به صورت درجا کار کند. استفاده کنید از: .PP .Vb 1 \& virt\-sparsify \-\-in\-place disk.img .Ve .PP اما ابتدا باید بخش \(lqIN\-PLACE SPARSIFICATION\(rq را در \fBvirt\-sparsify\fR\|(1) مطالعه کنید. .SH "مشکلات باز کردن ایمیج‌های دیسک (PROBLEMS OPENING DISK IMAGES)" .IX Header "PROBLEMS OPENING DISK IMAGES" .SS "مهمان‌های دوردست libvirt باز نمی‌شوند." .IX Subsection "Remote libvirt guests cannot be opened." باز کردن سیستم‌های مهمان دوردست libvirt در حال حاضر پشتیبانی نمی‌شود. برای نمونه این دستور کار نخواهد کرد: .PP .Vb 1 \& guestfish \-c qemu://remote/system \-d Guest .Ve .PP برای باز کردن دیسک‌های راه دور باید به نحوی آن‌ها را صادر (export) کنید و سپس به خروجی صادرشده متصل شوید. برای نمونه اگر تصمیم گرفتید از NBD استفاده کنید: .PP .Vb 2 \& remote$ qemu\-nbd \-t \-p 10809 guest.img \& local$ guestfish \-a nbd://remote:10809 \-i .Ve .PP امکانات دیگر شامل ssh (اگر نسخه qemu به اندازه کافی جدید باشد)، NFS یا iSCSI است. بخش \(lqREMOTE STORAGE\(rq را در \fBguestfs\fR\|(3) ببینید. .SS "چگونه می‌توانم این منبع دیسک غیرمعمول را باز کنم؟" .IX Subsection "How can I open this strange disk source?" شما یک ایمیج دیسک دارید که داخل سیستم دیگری قرار گرفته است و نیازمند دسترسی از طریق یک کتابخانه / HTTP / REST / API اختصاصی است، یا به شکلی فشرده یا آرشیو شده است. (یک نمونه، دسترسی از راه دور به ایمیج‌های glance در OpenStack بدون دانلود واقعی آن‌ها است.) .PP ما یک پروژه هم‌خانواده به نام nbdkit (https://github.com/libguestfs/nbdkit) داریم. این پروژه به شما امکان می‌دهد هر منبع دیسکی را به یک سرور NBD تبدیل کنید. Libguestfs می‌تواند مستقیماً به سرورهای NBD دسترسی داشته باشد، به عنوان مثال: .PP .Vb 1 \& guestfish \-a nbd://remote .Ve .PP پروژه nbdkit دارای مجوز آزاد و آسان‌گیر است، بنابراین می‌توانید آن را با کتابخانه‌ها و کدهای تجاری/اختصاصی پیوند داده یا درون آن‌ها بگنجانید. همچنین دارای یک API پایدار و ساده برای افزونه‌ها است، در نتیجه می‌توانید به سادگی افزونه‌هایی برای این API بنویسید که در آینده نیز به کار خود ادامه دهند. .SS "خطا در باز کردن دیسک‌های VMDK: ""uses a vmdk feature which is not supported by this qemu version: VMDK version 3""" .IX Subsection "Error opening VMDK disks: ""uses a vmdk feature which is not supported by this qemu version: VMDK version 3""" برنامه Qemu (و در نتیجه libguestfs) تنها از برخی ایمیج‌های دیسک خاص VMDK پشتیبانی می‌کند. سایر ایمیج‌ها کار نخواهند کرد و این خطا یا خطاهای مشابه را بازمی‌گردانند. .PP در حالت ایده‌آل باید کسی qemu را برای پشتیبانی از جدیدترین ویژگی‌های VMDK اصلاح کند، اما در این فاصله شما سه گزینه پیش رو دارید: .IP 1. 4 اگر مهمان روی یک سرور ESX فعال و در دسترس میزبانی می‌شود، ایمیج دیسکی به نام \fIsomename\-flat.vmdk\fR را پیدا کرده و دانلود کنید. علی‌رغم این نام، این یک ایمیج دیسک خام (raw) است و توسط هر ابزاری باز می‌شود. .Sp اگر نسخه به اندازه کافی جدیدی از qemu و libguestfs در اختیار دارید، ممکن است بتوانید با استفاده از HTTPS یا ssh به این ایمیج دیسک از راه دور دسترسی پیدا کنید. بخش \(lqREMOTE STORAGE\(rq را در \fBguestfs\fR\|(3) ببینید. .IP 2. 4 از ابزار اختصاصی vdiskmanager متعلق به VMware برای تبدیل ایمیج به قالب خام (raw) استفاده کنید. .IP 3. 4 از nbdkit به همراه افزونه اختصاصی VDDK برای صادر کردن زنده (live export) ایمیج دیسک به عنوان یک منبع NBD استفاده کنید. این کار باید به شما امکان خواندن و نوشتن روی فایل VMDK را بدهد. .SS "دیسک‌های UFS (مورد استفاده در BSD) باز نمی‌شوند." .IX Subsection "UFS disks (as used by BSD) cannot be opened." قالب سیستم‌فایل UFS گونه‌های متعددی دارد که خودشناسا (self\-identifying) نیستند. باید به هسته لینوکس مشخصاً گفته شود که از کدام گونه UFS استفاده کند، چیزی که libguestfs قادر به دانستن آن نیست. .PP هنگام سوار کردن این سیستم‌فایل‌ها باید گزینه سوار کردن مناسب \f(CW\*(C`ufstype\*(C'\fR را مشخص کنید. .PP صفحه https://www.kernel.org/doc/Documentation/filesystems/ufs.txt را ببینید. .SS "سیستم‌فایل ویندوزی Windows ReFS" .IX Subsection "Windows ReFS" سیستم‌فایل Windows ReFS نسخه مایکروسافت از روی ZFS/Btrfs است. این سیستم‌فایل هنوز مهندسی معکوس نشده و در هسته لینوکس پیاده‌سازی نشده است، بنابراین libguestfs از آن پشتیبانی نمی‌کند. در حال حاضر به نظر می‌رسد استفاده از آن در دنیای واقعی بسیار نادر باشد. .SS "نویسه‌های غیر ASCII در سیستم‌فایل‌های VFAT نمایش داده نمی‌شوند." .IX Subsection "Non-ASCII characters don’t appear on VFAT filesystems." نشانه‌های متداول این مشکل: .IP \(bu 4 هنگام ایجاد فایلی که نام آن شامل نویسه‌های غیر ASCII است، به‌ویژه نویسه‌های غیر ۸ بیتی زبان‌های آسیایی (چینی، ژاپنی و غیره) با خطا مواجه می‌شوید. سیستم‌فایل VFAT است. .IP \(bu 4 هنگامی که محتویات یک دایرکتوری را از سیستم‌فایل VFAT فهرست می‌کنید، نام فایل‌ها به صورت علامت سؤال ظاهر می‌شوند. .PP این یک نقص طراحی در سیستم گنو/لینوکس (GNU/Linux) است. .PP سیستم‌فایل VFAT نام‌های طولانی فایل‌ها را به صورت نویسه‌های UTF\-16 ذخیره می‌کند. هنگام باز کردن یا برگرداندن نام فایل‌ها، هسته لینوکس باید این نام‌ها را به نوعی از رشته‌های ۸ بیتی ترجمه کند. انتخاب بدیهی UTF\-8 خواهد بود، به استثنای کاربران لینوکسی که بر استفاده از تنظیمات محلی (locales) غیر UTF\-8 اصرار دارند (تنظیمات محلی کاربر برای هسته ناشناخته است زیرا تابعی از libc به شمار می‌رود). .PP بنابراین هنگام سوار کردن سیستم‌فایل، باید به هسته بگویید چه ترجمه‌ای را می‌خواهید انجام دهد. دو روش برای این کار وجود دارد: پارامتر \f(CW\*(C`iocharset\*(C'\fR (که به libguestfs مربوط نمی‌شود) و پرچم \f(CW\*(C`utf8\*(C'\fR. .PP بنابراین برای استفاده از یک سیستم‌فایل VFAT باید در زمان سوار کردن، پرچم \f(CW\*(C`utf8\*(C'\fR را اضافه کنید. در guestfish، استفاده کنید از: .PP .Vb 1 \& > mount\-options utf8 /dev/sda1 / .Ve .PP یا در خط فرمان guestfish: .PP .Vb 1 \& guestfish [...] \-m /dev/sda1:/:utf8 .Ve .PP یا از طریق API: .PP .Vb 1 \& guestfs_mount_options (g, "utf8", "/dev/sda1", "/"); .Ve .PP سپس هسته، نام فایل‌ها را به رشته‌های UTF\-8 و برعکس ترجمه خواهد کرد. .PP ما افزودن خودکار و شفاف این گزینه سوار کردن را در نظر گرفتیم، اما متأسفانه در انجام این کار چند مشکل وجود دارد: .IP \(bu 4 در برخی از سیستم‌های لینوکس، گزینه سوار کردن \f(CW\*(C`utf8\*(C'\fR کار نمی‌کند. ما دقیقاً نمی‌دانیم چه سیستم‌هایی یا چرا، اما این موضوع به صورت موثق توسط یک کاربر گزارش شده است. .IP \(bu 4 این کار مانع از استفاده شما از پارامتر \f(CW\*(C`iocharset\*(C'\fR می‌شود زیرا با \f(CW\*(C`utf8\*(C'\fR ناسازگار است. استفاده از این پارامتر احتمالاً ایده خوبی نیست، اما ما نمی‌خواهیم مانع از انجام آن شویم..SS "نویسه‌های غیر ASCII در سیستم‌های فایل ISO9660 به شکل زیرخط (_) نمایش داده می‌شوند." .IX Subsection "Non-ASCII characters appear as underscore (_) on ISO9660 filesystems." سیستم فایل به‌درستی با mkisofs یا genisoimage آماده نشده است. اطمینان حاصل کنید که سیستم فایل با استفاده از افزونه‌های Joliet و/یا Rock Ridge ایجاد شده باشد. libguestfs برای مدیریت سیستم فایل به هیچ گزینهٔ ویژهٔ سوار کردنی (mount) نیاز ندارد. .SS "ناتوانی در باز کردن مهمان‌های ویندوزی (Windows) که از NTFS استفاده می‌کنند." .IX Subsection "Cannot open Windows guests which use NTFS." خطاهایی شبیه به این مشاهده می‌کنید: .PP .Vb 1 \& mount: unknown filesystem type \*(Aqntfs\*(Aq .Ve .PP در Red Hat Enterprise Linux یا CentOS < 7.2، باید بستهٔ libguestfs\-winsupport را نصب کنید. در RHEL ≥ 7.2، بستهٔ \f(CW\*(C`libguestfs\-winsupport\*(C'\fR بخشی از توزیع پایهٔ RHEL است، اما پرسش بعدی را ببینید. .SS "خطای \(lqmount: unsupported filesystem type\(rq با NTFS در RHEL ≥ 7.2" .IX Subsection """mount: unsupported filesystem type"" with NTFS in RHEL ≥ 7.2" در RHEL 7.2 توانستیم \f(CW\*(C`libguestfs\-winsupport\*(C'\fR را به توزیع پایهٔ RHEL اضافه کنیم، اما مجبور شدیم قابلیت استفاده از آن برای باز کردن و ویرایش سیستم‌های فایل را غیرفعال کنیم. این قابلیت تنها هنگام استفاده با \&\fBvirt\-v2v\fR\|(1) پشتیبانی می‌شود. اگر سعی کنید از \fBguestfish\fR\|(1) یا \fBguestmount\fR\|(1) یا برخی برنامه‌های دیگر روی یک سیستم فایل NTFS استفاده کنید، این خطا را خواهید دید: .PP .Vb 1 \& mount: unsupported filesystem type .Ve .PP این یک پیکربندی پشتیبانی‌نشده است و در RHEL به کار انداخته نخواهد شد. زحمت گزارش باگ برای آن را به خود ندهید، چرا که بلافاصله وضعیت آن به \f(CW\*(C`CLOSED \-> WONTFIX\*(C'\fR تغییر خواهد کرد. .PP می‌توانید libguestfs را خودتان کامپایل کرده و این محدودیت را حذف کنید، اما این کار مورد تأیید یا پشتیبانی Red Hat نخواهد بود. .SS "ناتوانی در باز کردن یا بازرسی مهمان‌های RHEL 7." .IX Subsection "Cannot open or inspect RHEL 7 guests." .SS "ناتوانی در باز کردن مهمان‌های لینوکسی که از XFS استفاده می‌کنند." .IX Subsection "Cannot open Linux guests which use XFS." مهمان‌های RHEL 7 و هر مهمان دیگری که از XFS استفاده می‌کند توسط libguestfs قابل باز شدن هستند، اما باید بستهٔ \f(CW\*(C`libguestfs\-xfs\*(C'\fR را نصب کنید. .SH "استفاده از LIBGUESTFS در برنامه‌های خود (USING LIBGUESTFS IN YOUR OWN PROGRAMS)" .IX Header "USING LIBGUESTFS IN YOUR OWN PROGRAMS" .SS "این API صدها متد دارد، از کجا شروع کنم؟" .IX Subsection "The API has hundreds of methods, where do I start?" پیشنهاد می‌کنیم با خواندن نمای کلی API شروع کنید: \(lqAPI OVERVIEW\(rq در \fBguestfs\fR\|(3). .PP اگرچه نمای کلی API به بررسی C API می‌پردازد، اما حتی اگر قصد دارید از زبان برنامه‌نویسی دیگری استفاده کنید نیز ارزش خواندن دارد؛ زیرا این API یکسان است و تنها تغییرات منطقی ساده‌ای در نام فراخوانی‌ها اعمال شده است: .PP .Vb 6 \& C guestfs_ln_sf (g, target, linkname); \& Python g.ln_sf (target, linkname); \& OCaml g#ln_sf target linkname; \& Perl $g\->ln_sf (target, linkname); \& Shell (guestfish) ln\-sf target linkname \& PHP guestfs_ln_sf ($g, $target, $linkname); .Ve .PP پس از آشنایی با نمای کلی API، باید به این فهرست از نقاط شروع برای اتصالات (bindings) سایر زبان‌ها نگاهی بیندازید: \(lqUSING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES\(rq در \fBguestfs\fR\|(3). .SS "آیا می‌توانم از libguestfs در برنامهٔ اختصاصی / کدبسته / تجاری خود استفاده کنم؟" .IX Subsection "Can I use libguestfs in my proprietary / closed source / commercial program?" به طور کلی، بله. با این حال این یک مشاورهٔ حقوقی نیست \- مجوزی را که همراه با libguestfs ارائه می‌شود بخوانید، و اگر سؤال خاصی دارید با یک وکیل تماس بگیرید. .PP در درخت سورس‌کد، مجوز در فایل \f(CW\*(C`COPYING.LIB\*(C'\fR (مجوز LGPLv2+ برای کتابخانه و اتصالات) و \f(CW\*(C`COPYING\*(C'\fR (مجوز GPLv2+ برای برنامه‌های مستقل) قرار دارد. .SH "اشکال‌زدایی LIBGUESTFS (DEBUGGING LIBGUESTFS)" .IX Header "DEBUGGING LIBGUESTFS" .SS "کمک، کار نمی‌کند!" .IX Subsection "Help, it’s not working!" اگر به نظر می‌رسد هیچ برنامهٔ libguestfs اصلاً کار نمی‌کند، برنامهٔ زیر را اجرا کرده و خروجی \fBکامل و ویرایش‌نشده\fR را در قالب ایمیلی به \&\f(CW\*(C`guestfs@lists.libguestfs.org\*(C'\fR ارسال نمایید: .PP .Vb 1 \& libguestfs\-test\-tool .Ve .PP اگر عملیات خاصی با شکست مواجه شد، تمام اطلاعات موجود در این چک‌لیست را در ایمیلی به \f(CW\*(C`libguestfs\*(C'\fR @ \f(CW\*(C`redhat.com\*(C'\fR ارائه دهید: .IP 1. 4 قصد دارید چه کاری انجام دهید؟ .IP 2. 4 دقیقاً چه دستور(هایی) را اجرا کردید؟ .IP 3. 4 خطا یا خروجی دقیق این دستورها چه بود؟ .IP 4. 4 اشکال‌زدایی را فعال کرده، دستورها را مجدداً اجرا کنید و خروجی \fBکامل\fR را ضبط کنید. \fBخروجی را ویرایش نکنید.\fR .Sp .Vb 2 \& export LIBGUESTFS_DEBUG=1 \& export LIBGUESTFS_TRACE=1 .Ve .IP 5. 4 نسخهٔ libguestfs، نسخهٔ سیستم‌عامل و نحوهٔ نصب libguestfs (مانند از سورس‌کد، \f(CW\*(C`yum install\*(C'\fR و غیره) را قید کنید. .SS "چگونه هنگام استفاده از هر برنامه یا ابزار libguestfs (مانند virt\-customize یا virt\-df) اشکال‌زدایی کنم؟" .IX Subsection "How do I debug when using any libguestfs program or tool (eg. virt-customize or virt-df)?" دو متغیر محیطی \f(CW\*(C`LIBGUESTFS_*\*(C'\fR وجود دارند که می‌توانید برای دریافت اطلاعات بیشتر از libguestfs آنها را تنظیم کنید. .ie n .IP """LIBGUESTFS_TRACE""" 4 .el .IP \f(CWLIBGUESTFS_TRACE\fR 4 .IX Item "LIBGUESTFS_TRACE" این را روی 1 تنظیم کنید تا libguestfs هر دستور / فراخوانی API را در قالبی شبیه به دستورهای guestfish چاپ کند. .ie n .IP """LIBGUESTFS_DEBUG""" 4 .el .IP \f(CWLIBGUESTFS_DEBUG\fR 4 .IX Item "LIBGUESTFS_DEBUG" این را روی 1 تنظیم کنید تا مقادیر انبوهی از پیام‌های اشکال‌زدایی فعال شوند. اگر فکر می‌کنید مشکلی در appliance داخلی libguestfs وجود دارد، باید از این گزینه استفاده کنید. .PP برای تنظیم این‌ها از طریق شل، قبل از اجرای برنامه این کار را انجام دهید: .PP .Vb 2 \& export LIBGUESTFS_TRACE=1 \& export LIBGUESTFS_DEBUG=1 .Ve .PP برای csh/tcsh دستورهای معادل عبارتند از: .PP .Vb 2 \& setenv LIBGUESTFS_TRACE 1 \& setenv LIBGUESTFS_DEBUG 1 .Ve .PP برای کسب اطلاعات بیشتر، ببینید: \(lqENVIRONMENT VARIABLES\(rq در \fBguestfs\fR\|(3)..SS "چگونه هنگام استفاده از guestfish اشکال‌زدایی کنم؟" .IX Subsection "How do I debug when using guestfish?" می‌توانید از همان متغیرهای محیطی ذکر شده در بالا استفاده کنید. همچنین می‌توانید از گزینه‌های guestfish شامل \-x (برای ردگیری دستورات) یا \-v (برای دریافت خروجی کامل اشکال‌زدایی)، یا هر دو استفاده کنید. .PP برای اطلاعات بیشتر، ببینید: \fBguestfish\fR\|(1). .SS "چگونه هنگام استفاده از API اشکال‌زدایی کنم؟" .IX Subsection "How do I debug when using the API?" برای فعال‌سازی ردگیری دستورات، "guestfs_set_trace" در \fBguestfs\fR\|(3) و/یا برای فعال‌سازی پیام‌های اشکال‌زدایی، "guestfs_set_verbose" در \fBguestfs\fR\|(3) را فراخوانی کنید. .PP برای بهترین نتیجه، این توابع را تا حد امکان زودتر فراخوانی کنید؛ در صورت امکان درست پس از ایجاد دستگیره (handle) guestfs، و قطعاً پیش از فراخوانی launch. .SS "چگونه خروجی اشکال‌زدایی را ضبط کرده و در سیستم گزارش‌گیری‌ام قرار دهم؟" .IX Subsection "How do I capture debug output and put it into my logging system?" از API رویدادها (event API) استفاده کنید. برای نمونه‌ها، ببینید: "SETTING CALLBACKS TO HANDLE EVENTS" در \fBguestfs\fR\|(3) و برنامه \&\fIexamples/debug\-logging.c\fR در سورس‌های libguestfs. .SS "کاوش عمیق‌تر در فرایند راه‌اندازی اپلاینس." .IX Subsection "Digging deeper into the appliance boot process." اشکال‌زدایی را فعال کرده و سپس این مستندات را درباره فرایند راه‌اندازی اپلاینس بخوانید: \fBguestfs\-internals\fR\|(1). .SS "libguestfs در حین run/launch متوقف شده یا با شکست مواجه می‌شود." .IX Subsection "libguestfs hangs or fails during run/launch." اشکال‌زدایی را فعال کرده و خروجی کامل را بررسی کنید. اگر نتوانستید متوجه شوید ماجرا از چه قرار است، یک گزارش باگ ارسال کنید که شامل خروجی \fIکامل\fR \fBlibguestfs\-test\-tool\fR\|(1) باشد. .SS "اشکال‌زدایی libvirt" .IX Subsection "Debugging libvirt" اگر از بک‌اند libvirt استفاده می‌کنید و libvirt با شکست مواجه می‌شود، می‌توانید با ویرایش \fI/etc/libvirt/libvirtd.conf\fR اشکال‌زدایی را فعال کنید. .PP اگر به عنوان کاربر غیرریشه (non\-root) برنامه را اجرا می‌کنید، باید فایل دیگری را ویرایش کنید. فایل \fI~/.config/libvirt/libvirtd.conf\fR را با محتوای زیر ایجاد کنید: .PP .Vb 2 \& log_level=1 \& log_outputs="1:file:/tmp/libvirtd.log" .Ve .PP هر نشست libvirtd در حال اجرا (غیرریشه) را خاتمه دهید (kill کنید)، و دفعه بعد که دستور libguestfs را اجرا می‌کنید، حجم زیادی از اطلاعات اشکال‌زدایی مفید از libvirtd را در \fI/tmp/libvirtd.log\fR مشاهده خواهید کرد. .SS "کرنل خراب، یا آزمایش یک کرنل متفاوت." .IX Subsection "Broken kernel, or trying a different kernel." می‌توانید با مقداردهی برخی متغیرهای محیطی supermin، کرنل متفاوتی را برای اپلاینس انتخاب کنید: .PP .Vb 5 \& export SUPERMIN_KERNEL_VERSION=4.8.0\-1.fc25.x86_64 \& export SUPERMIN_KERNEL=/boot/vmlinuz\-$SUPERMIN_KERNEL_VERSION \& export SUPERMIN_MODULES=/lib/modules/$SUPERMIN_KERNEL_VERSION \& rm \-rf /var/tmp/.guestfs\-* \& libguestfs\-test\-tool .Ve .SS "qemu خراب، یا آزمایش یک qemu متفاوت." .IX Subsection "Broken qemu, or trying a different qemu." می‌توانید با تنظیم متغیر محیطی هایپروایزر، یک qemu متفاوت را انتخاب کنید: .PP .Vb 2 \& export LIBGUESTFS_HV=/path/to/qemu\-system\-x86_64 \& libguestfs\-test\-tool .Ve .SH "طراحی/ساختار درونی LIBGUESTFS (DESIGN/INTERNALS OF LIBGUESTFS)" .IX Header "DESIGN/INTERNALS OF LIBGUESTFS" همچنین ببینید: \fBguestfs\-internals\fR\|(1). .SS "چرا همه‌چیز را از طریق FUSE / رابط فایل‌سیستم انجام نمی‌دهید؟" .IX Subsection "Why don’t you do everything through the FUSE / filesystem interface?" ما دستوری به نام \fBguestmount\fR\|(1) ارائه می‌دهیم که به شما امکان می‌دهد فایل‌سیستم‌های مهمان را روی سیستم میزبان سوار (mount) کنید. این به صورت یک ماژول FUSE پیاده‌سازی شده است. چرا به جای داشتن یک API بزرگ و نسبتاً پیچیده، کل libguestfs را تنها با استفاده از این سازوکار پیاده‌سازی نکنیم؟ .PP دلایل آن دو بخش است. نخست، libguestfs فراخوانی‌های API برای انجام کارهایی مانند ایجاد و حذف پارتیشن‌ها و حجم‌های منطقی (logical volumes) ارائه می‌دهد که به سادگی درون یک مدل فایل‌سیستمی نمی‌گنجند. یا بهتر بگوییم، می‌شد آن‌ها را جا داد: به عنوان مثال، ایجاد یک پارتیشن می‌توانست به \f(CW\*(C`mkdir /fs/hda1\*(C'\fR نگاشت شود، اما آنگاه باید روشی برای تعیین اندازه پارتیشن مشخص می‌کردید (مثلاً \f(CW\*(C`echo 100M > /fs/hda1/.size\*(C'\fR)، و همین‌طور نوع پارتیشن، سکتورهای شروع و پایان و غیره؛ اما به محض انجام چنین کاری، API مبتنی بر فایل‌سیستم پیچیده‌تر از API مبتنی بر فراخوانی فعلی به نظر خواهد رسید. .PP دلیل دوم، بازدهی و کارایی است. خود FUSE تا حد قابل قبولی کارآمد است، اما تعداد زیادی فراخوانی کوچک و مستقل به درون ماژول FUSE ارسال می‌کند. در guestmount این فراخوانی‌ها باید به پیام‌هایی برای اپلاینس libguestfs ترجمه شوند که سربار زیادی (از نظر زمان و رفت‌وبرگشت‌ها) ایجاد می‌کند. به عنوان مثال، خواندن یک فایل در تکه‌های ۶۴ کیلوبایتی ناکارآمد است زیرا هر تکه به یک رفت‌وبرگشت کامل تبدیل می‌شود. در API لایبرری libguestfs، دانلود کامل یک فایل یا دایرکتوری از طریق یکی از فراخوانی‌های جریانی (streaming) مانند \&\f(CW\*(C`guestfs_download\*(C'\fR یا \f(CW\*(C`guestfs_tar_out\*(C'\fR بسیار کارآمدتر است. .SS "چرا همه‌چیز را از طریق GVFS انجام نمی‌دهید؟" .IX Subsection "Why don’t you do everything through GVFS?" مشکلات مشابه مشکلات موجود در FUSE هستند. .PP سامانه GVFS انتزاع بهتری نسبت به POSIX/FUSE ارائه می‌دهد. یک بک‌اند FTP برای GVFS وجود دارد که دلگرم‌کننده است، چرا که FTP از نظر مفهومی مشابه API مربوط به libguestfs است. با این حال، بک‌اند FTP در GVFS به منظور حفظ تعاملی بودن، چندین اتصال هم‌زمان برقرار می‌کند؛ کاری که انجام آن به سادگی با libguestfs امکان‌پذیر نیست. .SS "چرا می‌توانم روی دیسک بنویسم، با وجود اینکه آن را فقط‌خواندنی اضافه کرده‌ام؟" .IX Subsection "Why can I write to the disk, even though I added it read-only?" .ie n .SS "چرا به نظر می‌رسد ""\-\-ro"" هیچ اثری ندارد؟" .el .SS "چرا به نظر می‌رسد \f(CW\-\-ro\fP هیچ اثری ندارد؟" .IX Subsection "Why does --ro appear to have no effect?" هنگامی که یک دیسک را به صورت فقط‌خواندنی (read\-only) اضافه می‌کنید، libguestfs یک لایه روکش (overlay) قابل نوشتن روی دیسک زیرین قرار می‌دهد. عملیات نوشتن وارد این لایه روکش می‌شوند و هنگام بسته شدن دستگیره (یا خروج \f(CW\*(C`guestfish\*(C'\fR و غیره) دور ریخته می‌شوند. .PP دو دلیل برای این روش وجود دارد: نخست اینکه دیسک‌های فقط‌خواندنی در بسیاری از موارد امکان‌پذیر نیستند (برای نمونه IDE اساساً از آن‌ها پشتیبانی نمی‌کند، بنابراین نمی‌توانید یک دیسک شبیه‌سازی‌شده IDE فقط‌خواندنی داشته باشید، اگرچه این مورد در پیاده‌سازی‌های واقعی libguestfs رایج نیست). .PP دوم و مهم‌تر اینکه، حتی اگر دیسک‌های فقط‌خواندنی امکان‌پذیر بودند، شما آن‌ها را نمی‌خواستید. سوار کردن هر فایل‌سیستمی که ژورنال دارد، حتی با \f(CW\*(C`mount \-o ro\*(C'\fR، موجب نوشتن روی فایل‌سیستم می‌شود زیرا ژورنال باید بازپخش شده و فراداده‌ها به‌روزرسانی شوند. اگر دیسک واقعاً فقط‌خواندنی بود، نمی‌توانستید یک فایل‌سیستم وضعیت‌خراب/کثیف (dirty) را سوار کنید. .PP برای اینکه دیسک قابل استفاده باشد، ما لایه روکش را به عنوان مکانی برای ذخیره موقت این عملیات‌های نوشتن ایجاد می‌کنیم و سپس آن را دور می‌ریزیم. این کار تضمین می‌کند که دیسک زیرین همواره دست‌نخورده باقی بماند. .PP همچنین توجه داشته باشید که هنگام ساختن libguestfs یک آزمون رگرسیون برای این موضوع وجود دارد (در \f(CW\*(C`tests/qemu\*(C'\fR). این یکی از دلایلی است که اجرای مجموعه آزمون‌ها برای بسته‌بندها اهمیت دارد. .ie n .SS "آیا ""\-\-ro"" همه دیسک‌ها را فقط‌خواندنی می‌کند؟" .el .SS "آیا \f(CW\-\-ro\fP همه دیسک‌ها را فقط‌خواندنی می‌کند؟" .IX Subsection "Does --ro make all disks read-only?" \&\fIخیر!\fR گزینه \f(CW\*(C`\-\-ro\*(C'\fR فقط بر دیسک‌هایی تأثیر می‌گذارد که از طریق خط فرمان اضافه شده‌اند، یعنی با استفاده از گزینه‌های \f(CW\*(C`\-a\*(C'\fR و \f(CW\*(C`\-d\*(C'\fR. .PP در guestfish، اگر از دستور \f(CW\*(C`add\*(C'\fR استفاده کنید، دیسک به صورت خواندن\-نوشتن اضافه می‌شود (مگر اینکه پرچم \f(CW\*(C`readonly:true\*(C'\fR را صراحتاً همراه با دستور مشخص کنید). .ie n .SS "آیا می‌توانم از ""guestfish \-\-ro"" به عنوان روشی برای پشتیبان‌گیری از ماشین‌های مجازی‌ام استفاده کنم؟" .el .SS "آیا می‌توانم از \f(CWguestfish \-\-ro\fP به عنوان روشی برای پشتیبان‌گیری از ماشین‌های مجازی‌ام استفاده کنم؟" .IX Subsection "Can I use guestfish --ro as a way to backup my virtual machines?" معمولاً این ایده خوبی \fIنیست\fR. این پرسش با جزئیات بیشتر در این ارسال لیست پستی پاسخ داده شده است: https://www.redhat.com/archives/libguestfs/2010\-August/msg00024.html .PP همچنین پرسش بعدی را ببینید. .ie n .SS "چرا نمی‌توانم fsck را با استفاده از ""guestfish \-\-ro"" روی یک فایل‌سیستم زنده اجرا کنم؟" .el .SS "چرا نمی‌توانم fsck را با استفاده از \f(CWguestfish \-\-ro\fP روی یک فایل‌سیستم زنده اجرا کنم؟" .IX Subsection "Why can’t I run fsck on a live filesystem using guestfish --ro?" این دستور معمولاً کار \fIنخواهد کرد\fR: .PP .Vb 1 \& guestfish \-\-ro \-a /dev/vg/my_root_fs run : fsck /dev/sda .Ve .PP دلیل این موضوع آن است که qemu یک اسنپ‌شات روی فایل‌سیستم اصلی ایجاد می‌کند، اما یک اسنپ‌شات دقیق در یک نقطه زمانی مشخص (point\-in\-time) ایجاد نمی‌کند. بلوک‌های داده روی فایل‌سیستم زیرین توسط qemu در زمان‌های متفاوتی همگام با پیشرفت عملیات fsck خوانده می‌شوند، در حالی که سیستم میزبان در این میان عملیات نوشتن انجام می‌دهد. نتیجه این است که fsck خرابی‌های عظیمی (تصوری و خیالی، نه واقعی!) مشاهده کرده و با شکست مواجه می‌شود. .PP کاری که باید انجام دهید ایجاد یک اسنپ‌شات در نقطه زمانی است. اگر یک حجم منطقی است، از یک اسنپ‌شات LVM2 استفاده کنید. اگر فایل‌سیستم درون موردی مانند یک فایل btrfs/ZFS قرار دارد، از اسنپ‌شات btrfs/ZFS استفاده کنید و سپس fsck را روی آن اسنپ‌شات اجرا نمایید. در عمل نیازی به استفاده از libguestfs برای این کار ندارید \-\- فقط \fI/sbin/fsck\fR را مستقیماً اجرا کنید. .PP ایجاد اسنپ‌شات‌های نقطه زمانی از دستگاه‌ها و فایل‌های میزبان خارج از حیطه عملکرد libguestfs است، اگرچه libguestfs می‌تواند پس از ایجاد شدن، روی آن‌ها عملیات انجام دهد..SS "تفاوت بین guestfish و virt\-rescue چیست؟" .IX Subsection "تفاوت بین guestfish و virt-rescue چیست؟" بسیاری از افراد دربارهٔ دو ابزار به‌ظاهر مشابهی که ارائه می‌دهیم سردرگم می‌شوند: .PP .Vb 3 \& $ guestfish \-\-ro \-a guest.img \& > run \& > fsck /dev/sda1 \& \& $ virt\-rescue \-\-ro guest.img \& > /sbin/fsck /dev/sda1 .Ve .PP و پرسش مرتبطی که در ادامه پیش می‌آید این است که چرا در guestfish نمی‌توان دستورهای کامل شل را به همراه همهٔ \-\-options تایپ کرد (در حالی که در \fBvirt\-rescue\fR\|(1) این امکان وجود دارد). .PP \&\fBguestfish\fR\|(1) برنامه‌ای است که دسترسی ساخت‌یافته‌ای به APIِ \&\fBguestfs\fR\|(3) فراهم می‌کند. این ابزار به عنوان یک شل تعاملی مناسب نیز عمل می‌کند، اما هدف اصلی آن فراهم کردن دسترسی ساخت‌یافته از طریق اسکریپت‌های شل است. آن را بیشتر مانند یک بایندینگ زبان، شبیه بایندینگ‌های پایتون و زبان‌های دیگر، اما برای شل در نظر بگیرید. ویژگی متمایزکنندهٔ کلیدی guestfish (و به‌طور کلی APIِ libguestfs) توانایی خودکارسازی تغییرات است. .PP \&\fBvirt\-rescue\fR\|(1) روشی آزاد و بدون چارچوب ثابت برای راه‌اندازی اپلاینس libguestfs و اعمال تغییرات دلخواه روی VM شماست. این ابزار ساخت‌یافته نیست و نمی‌توانید آن را خودکارسازی کنید، اما برای انجام اصلاحات سریع و موردی (ad-hoc) روی سیستم‌های مهمان می‌تواند بسیار کاربردی باشد. .PP با این حال، libguestfs یک «در پشتی» (backdoor) نیز به درون اپلاینس دارد که امکان ارسال دستورهای دلخواه شل را به شما می‌دهد. این قابلیت به اندازهٔ virt\-rescue منعطف نیست، زیرا نمی‌توانید با دستورهای شل تعامل برقرار کنید، اما به هر حال وجود دارد: .PP .Vb 1 \& > debug sh "cmd arg1 arg2 ..." .Ve .PP توجه داشته باشید که \fBنباید\fR به این ویژگی اتکا کنید. این قابلیت ممکن است در آینده تغییر کند یا حذف شود. اگر برنامهٔ شما به عملیات خاصی نیاز دارد، لطفاً در عوض آن را به APIِ libguestfs بیفزایید. .ie n .SS "ماجرای ""guestfish \-i"" چیست؟" .el .SS "ماجرای \f(CWguestfish \-i\fP چیست؟" .IX Subsection "ماجرای guestfish -i چیست؟" .SS "چرا virt\-cat فقط روی یک ایمیج واقعی VM کار می‌کند، اما virt\-df روی هر ایمیج دیسکی کار می‌کند؟" .IX Subsection "چرا virt-cat فقط روی یک ایمیج واقعی VM کار می‌کند، اما virt-df روی هر ایمیج دیسکی کار می‌کند؟" .SS "معنی ""no root device found in this operating system image"" چیست؟" .IX Subsection "معنی no root device found in this operating system image چیست؟" این پرسش‌ها همگی در سطحی بنیادین به یکدیگر مربوط می‌شوند که ممکن است در نگاه نخست آشکار نباشد. .PP در سطح APIِ \fBguestfs\fR\|(3)، یک «ایمیج دیسک» صرفاً توده‌ای از پارتیشن‌ها و فایل‌سیستم‌ها است. .PP در مقابل، زمانی که ماشین مجازی بوت می‌شود، آن فایل‌سیستم‌ها را در یک سلسله‌مراتب سازگار سوار (mount) می‌کند، مانند: .PP .Vb 9 \& / (/dev/sda2) \& │ \& ├── /boot (/dev/sda1) \& │ \& ├── /home (/dev/vg_external/Homes) \& │ \& ├── /usr (/dev/vg_os/lv_usr) \& │ \& └── /var (/dev/vg_os/lv_var) .Ve .PP (یا حروف درایو در Windows). .PP این API در وهلهٔ اول ایمیج دیسک را در سطح «توده‌ای از فایل‌سیستم‌ها» می‌بیند. اما همچنین روشی برای بررسی (inspect) ایمیج دیسک دارد تا تشخیص دهد آیا حاوی یک سیستم‌عامل هست یا خیر، و اینکه دیسک‌ها هنگام بوت سیستم‌عامل چگونه سوار می‌شوند: به بخش "INSPECTION" در \fBguestfs\fR\|(3) مراجعه کنید. .PP کاربران انتظار دارند برخی ابزارها (مانند \fBvirt\-cat\fR\|(1)) با مسیرهای VM کار کنند: .PP .Vb 1 \& virt\-cat fedora.img /var/log/messages .Ve .PP ابزار virt\-cat چگونه درمی‌یابد که \fI/var\fR یک پارتیشن جداگانه است؟ ترفند کار این است که virt\-cat روی ایمیج دیسک عملیات بازرسی انجام می‌دهد و از آن برای ترجمهٔ صحیح مسیر بهره می‌برد. .PP برخی ابزارها (شامل \fBvirt\-cat\fR\|(1)، \fBvirt\-edit\fR\|(1) و \fBvirt\-ls\fR\|(1)) برای نگاشت مسیرهای VM از بازرسی استفاده می‌کنند. ابزارهای دیگر، مانند \fBvirt\-df\fR\|(1) و \fBvirt\-filesystems\fR\|(1)، کاملاً در سطح خام «تودهٔ بزرگ فایل‌سیستم‌ها»ی APIِ libguestfs عمل می‌کنند و بازرسی را به کار نمی‌برند. .PP ابزار \&\fBguestfish\fR\|(1) در موقعیت میانه‌ای جالب قرار دارد. اگر از گزینه‌های خط فرمان \&\fI\-a\fR و \fI\-m\fR استفاده کنید، باید دقیقاً به guestfish بگویید چگونه ایمیج‌های دیسک را بیفزاید و پارتیشن‌ها را در کجا سوار کند. این، همان سطح خام API است. .PP اگر از گزینهٔ \fI\-i\fR استفاده نمایید، libguestfs عملیات بازرسی را انجام داده و فایل‌سیستم‌ها را برای شما سوار می‌کند. .PP خطای \f(CW\*(C`no root device found in this operating system image\*(C'\fR به این موضوع مربوط می‌شود. این پیام بدان معناست که بازرسی نتوانسته است هیچ سیستم‌عاملی را درون ایمیج دیسک ارائه‌شده بیابد. در صورتی که برنامه‌هایی مانند virt\-cat را روی فایلی اجرا کنید که صرفاً یک ایمیج دیسک خام است و نه یک ایمیج ماشین مجازی، ممکن است با این پیام روبه‌رو شوید. .ie n .SS "توابع ""debug*"" و ""internal\-*"" چه می‌کنند؟" .el .SS "توابع \f(CWdebug*\fP و \f(CWinternal\-*\fP چه می‌کنند؟" .IX Subsection "توابع debug* و internal-* چه می‌کنند؟" برخی توابع وجود دارند که برای اشکال‌زدایی و مقاصد داخلی به کار می‌روند و بخشی از API پایدار \fIنیستند\fR. .PP توابع \f(CW\*(C`debug*\*(C'\fR (یا \f(CW\*(C`guestfs_debug*\*(C'\fR)، به‌ویژه "guestfs_debug" در \fBguestfs\fR\|(3) و شمار اندکی از توابع دیگر، برای اشکال‌زدایی libguestfs به کار می‌روند. اگرچه این توابع بخشی از API پایدار نیستند و بنابراین ممکن است در هر زمانی تغییر کرده یا حذف شوند، اما برخی برنامه‌ها ممکن است در حین انتظار برای افزوده‌شدن قابلیت‌ها به libguestfs مایل به فراخوانی آن‌ها باشند. .PP توابع \f(CW\*(C`internal\-*\*(C'\fR (یا \f(CW\*(C`guestfs_internal_*\*(C'\fR) صرفاً برای استفادهٔ خودِ libguestfs هستند. برنامه‌ها هیچ دلیلی برای فراخوانی آن‌ها ندارند و نباید تلاشی برای استفاده از آن‌ها به عمل آورند. به‌کارگیری آن‌ها نه تنها بخشی از API پایدار و مستند نیست، بلکه اغلب باعث بروز پیامدهای ناخواسته و مخرب خواهد شد..SH "توسعه‌دهندگان (DEVELOPERS)" .IX Header "DEVELOPERS" .SS "وصله‌ها را به کجا ارسال کنم؟" .IX Subsection "Where do I send patches?" لطفاً وصله‌ها را به فهرست رایانامه libguestfs به نشانی https://lists.libguestfs.org ارسال کنید. نیازی نیست عضو فهرست باشید، اما تا زمانی که ارسالتان به‌صورت دستی تأیید شود، تأخیری وجود خواهد داشت. .PP \&\fBلطفاً از pull requestهای github استفاده نکنید \- نادیده گرفته خواهند شد\fR. دلایل آن عبارتند از (الف) ما می‌خواهیم وصله‌ها را در فهرست رایانامه بحث و بررسی کنیم، و (ب) pull requestهای github به merge commit تبدیل می‌شوند اما ما داشتن یک تاریخچه خطی را ترجیح می‌دهیم. .SS "چگونه یک قابلیت جدید پیشنهاد دهم؟" .IX Subsection "How do I propose a feature?" قابلیت‌های جدید و بزرگی که قصد مشارکت در آن‌ها را دارید، ابتدا باید در فهرست رایانامه مورد بحث قرار گیرند (https://lists.libguestfs.org). این کار از ناامیدی و هدر رفتن زحمات، در صورتی که فکر کنیم قابلیت با پروژه libguestfs همخوانی ندارد، جلوگیری می‌کند. .PP اگر می‌خواهید قابلیت مفیدی را پیشنهاد دهید اما مایل به نوشتن کد آن نیستید، می‌توانید یک گزارش اشکال (بخش «GETTING HELP AND REPORTING BUGS» را ببینید) با عبارت \f(CW"RFE: "\fR در ابتدای خط خلاصه (Summary) ثبت کنید. .SS "چه کسانی می‌توانند در گیت libguestfs کامیت کنند؟" .IX Subsection "Who can commit to libguestfs git?" حدود ۵ نفر دسترسی commit به github دارند. وصله‌ها باید ابتدا در فهرست ارسال شده و ACK شوند. خط‌مشی ACK کردن و push کردن وصله‌ها در اینجا مشخص شده است: .PP https://www.redhat.com/archives/libguestfs/2012\-January/msg00023.html .SS "آیا می‌توانم libguestfs را فورک کنم؟" .IX Subsection "Can I fork libguestfs?" البته که می‌توانید. Git فورک کردن libguestfs را آسان می‌کند. Github آن را حتی آسان‌تر هم می‌کند. خوشحال می‌شویم اگر در فهرست رایانامه درباره فورک‌ها و دلایل آن‌ها به ما اطلاع دهید. .SH "پرسش‌های گوناگون (MISCELLANEOUS QUESTIONS)" .IX Header "MISCELLANEOUS QUESTIONS" .SS "آیا می‌توان با libguestfs فعالیت دیسک زنده یک ماشین مجازی را پایش کرد؟" .IX Subsection "Can I monitor the live disk activity of a virtual machine using libguestfs?" یک درخواست رایج این است که بتوان از libguestfs برای پایش فعالیت دیسک زنده یک مهمان استفاده کرد؛ برای نمونه، هر بار که مهمان یک فایل جدید ایجاد می‌کند مطلع شد. Libguestfs آن‌گونه که برخی تصور می‌کنند کار \fIنمی‌کند\fR، همان‌طور که در این نمودار می‌بینید: .PP .Vb 10 \& ┌─────────────────────────────────────┐ \& │ monitoring program using libguestfs │ \& └─────────────────────────────────────┘ \& ↓ \& ┌───────────┐ ┌──────────────────────┐ \& │ live VM │ │ libguestfs appliance │ \& ├───────────┤ ├──────────────────────┤ \& │ kernel (1)│ │ appliance kernel (2) │ \& └───────────┘ └──────────────────────┘ \& ↓ ↓ (r/o connection) \& ┌──────────────────────┐ \& | disk image | \& └──────────────────────┘ .Ve .PP این سناریو ایمن است (تا زمانی که هنگام افزودن درایو، پرچم \f(CW\*(C`readonly\*(C'\fR را تنظیم کنید). با این حال، هسته libguestfs appliance (2) به دو دلیل، تمام تغییرات اعمال‌شده در disk image را نمی‌بیند: .IP i. 4 .IX Item "i." هسته VM (1) می‌تواند داده‌ها را در حافظه کِش کند، بنابراین در disk image ظاهر نمی‌شوند. .IP ii. 4 .IX Item "ii." هسته libguestfs appliance (2) انتظار ندارد که disk image در زیر پای آن تغییر کند، بنابراین کِش خود آن حتی هنگامی که هسته VM (1) ایمیج دیسک را به‌روزرسانی کند، به‌طور جادویی به‌روز نمی‌شود. .PP تنها راهکار پشتیبانی‌شده این است که هر زمان می‌خواهید تغییرات disk image را ببینید، کل libguestfs appliance را مجدداً راه‌اندازی کنید. در سطح API این معادل فراخوانی \f(CW\*(C`guestfs_shutdown\*(C'\fR و پس از آن \f(CW\*(C`guestfs_launch\*(C'\fR است، که یک عملیات سنگین به شمار می‌رود (همچنین ببینید: \&\fBguestfs\-performance\fR\|(3)). .PP چنانچه راه‌اندازی مجدد appliance واقعاً بیش از حد پرهزینه باشد، چند ترفند پشتیبانی‌نشده وجود دارد که می‌توانید امتحان کنید: .IP \(bu 4 فراخوانی \f(CW\*(C`guestfs_drop_caches (g, 3)\*(C'\fR. این کار باعث می‌شود تمام داده‌های کِش‌شده توسط هسته libguestfs appliance (2) دور ریخته شوند، بنابراین به disk image رجوع می‌کند. .Sp با این حال، این کار به‌تنهایی کافی نیست، زیرا qemu نیز برخی داده‌ها را کِش می‌کند. شما همچنین باید libguestfs را وصله کنید تا حالت \f(CW\*(C`cache=none\*(C'\fR (مجدداً) فعال شود. ببینید: https://rwmj.wordpress.com/2013/09/02/new\-in\-libguestfs\-allow\-cache\-mode\-to\-be\-selected .IP \(bu 4 به جای آن از ابزاری مانند virt\-bmap استفاده کنید. .IP \(bu 4 یک agent درون مهمان اجرا کنید. .PP اگر مهمان در حال انجام تغییرات بنیادین‌تری باشد (مانند حذف فایل‌سیستم‌ها)، هیچ‌کدام کارساز نخواهد بود. برای این‌گونه موارد باید appliance را مجدداً راه‌اندازی کنید. .PP (توجه داشته باشید که مشکل سومی نیز وجود دارد؛ برای بررسی واقعی ایمیج‌های دیسک زنده، باید از اسنپ‌شات‌های سازگار (consistent snapshots) استفاده کنید، اما این یک مشکل عمومی در استفاده از libguestfs در برابر هر ایمیج دیسک زنده است.) .SH "همچنین ببینید (SEE ALSO)" .IX Header "SEE ALSO" \&\fBguestfish\fR\|(1), \&\fBguestfs\fR\|(3), http://libguestfs.org .SH "نویسندگان (AUTHORS)" .IX Header "AUTHORS" Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR) .SH "کپی‌رایت و تکثیر (COPYRIGHT)" .IX Header "COPYRIGHT" Copyright (C) 2012\-2025 Red Hat Inc. .SH "مجوز (LICENSE)" .IX Header "LICENSE" این کتابخانه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط مجوز عمومی همگانی کمتر گنو (GNU Lesser General Public License) همان‌طور که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، بازتوزیع کرده یا تغییر دهید؛ خواه نسخه ۲ مجوز، یا (به انتخاب خودتان) هر نسخه پس از آن. .PP این کتابخانه با این امید توزیع شده است که سودمند باشد، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابلیت فروش یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر به GNU Lesser General Public License مراجعه کنید. .PP شما باید همراه با این کتابخانه، رونوشتی از GNU Lesser General Public License دریافت کرده باشید؛ در غیر این صورت به نشانی زیر مکاتبه کنید: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110\-1301 USA.SH "گزارش باگ‌ها (BUGS)" .IX Header "BUGS" برای دریافت فهرستی از باگ‌های libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools .PP برای گزارش یک باگ جدید در libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools .PP هنگام گزارش باگ، لطفاً موارد زیر را ارائه دهید: .IP \(bu 4 نسخهٔ libguestfs. .IP \(bu 4 از کجا libguestfs را تهیه کرده‌اید (برای مثال کدام توزیع لینوکس، کامپایل‌شده از سورس، غیره). .IP \(bu 4 باگ را به‌دقت شرح دهید و روشی برای بازتولید آن ارائه دهید. .IP \(bu 4 دستور \fBlibguestfs\-test\-tool\fR\|(1) را اجرا کرده و خروجی \fBکامل و ویرایش‌نشدهٔ\fR آن را در گزارش باگ قرار دهید.