guestmount(1) Virtualization Support guestmount(1)

guestmount - مونت کردن سیستم‌فایل‌های ماشین مجازی روی سیستم میزبان با FUSE و libguestfs

guestmount [--options] -a disk.img -m device [--ro] mountpoint
guestmount [--options] -a disk.img -i [--ro] mountpoint
guestmount [--options] -d Guest -i [--ro] mountpoint

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

در صورتی که ایمیج دیسک یا ماشین مجازی ممکن است روشن باشد، از گزینه --ro (فقط‌خواندنی) استفاده کنید تا "guestmount" به صورت ایمن اجرا شود. در صورت اجرای همزمان با سایر تغییرات ممکن است نتایج عجیب یا ناهماهنگی مشاهده کنید، اما با این گزینه با خطر خرابی دیسک مواجه نخواهید شد.

برنامه guestmount برای مونت کردن سیستم‌فایل‌های ماشین‌های مجازی و سایر ایمیج‌های دیسک روی سیستم میزبان به کار می‌رود. این برنامه از libguestfs برای دسترسی به سیستم‌فایل ماشین مجازی، و از FUSE (سامانه سیستم‌فایل در فضای کاربری) برای نمایش آن به صورت یک دستگاه قابل مونت استفاده می‌کند.

در کنار سایر گزینه‌ها، باید دست‌کم یک دستگاه (گزینه -a) یا دامنه libvirt (گزینه -d)، و حداقل یک نقطه مونت (گزینه -m) مشخص کنید یا از گزینه بازرسی -i استفاده نمایید. نحوه عملکرد این بخش در صفحه راهنمای guestfish(1) یا با مشاهده مثال‌های زیر بهتر توضیح داده شده است.

قابلیت FUSE امکان مونت کردن سیستم‌فایل‌ها را بدون دسترسی ریشه (non-root) فراهم می‌کند. نقطه مونت باید متعلق به شما باشد. سیستم‌فایل برای سایر کاربران قابل مشاهده نخواهد بود مگر اینکه تنظیمات را تغییر دهید؛ بخش «نکات» را در زیر ببینید.

برای آن‌مونت کردن سیستم‌فایل، از دستور guestunmount(1) استفاده کنید.

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

guestmount -a windows.img -m /dev/sda1 --ro /mnt

برای یک ماشین لینوکسی معمولی که سیستم‌فایل ‎/boot آن روی پارتیشن اول و سیستم‌فایل ریشه روی یک حجم منطقی (LVM) است:

guestmount -a linux.img -m /dev/VG/LV -m /dev/sda1:/boot --ro /mnt

برای اینکه libguestfs نقاط مونت ماشین مجازی را به طور خودکار شناسایی کند:

guestmount -a guest.img -i --ro /mnt

برای یک ماشین مجازی libvirt به نام "Guest" می‌توانید این‌گونه عمل کنید:

guestmount -d Guest -i --ro /mnt

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

virt-filesystems -d MyGuest

اگر می‌خواهید فراخوانی‌های libguestfs را بدون اطلاعات دیباگ بیش از حد ردیابی کنید، دستور زیر پیشنهاد می‌شود:

guestmount [...] --trace /mnt

اگر می‌خواهید برنامه را دیباگ کنید، پیشنهاد می‌شود:

guestmount [...] --trace --verbose /mnt

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

guestunmount /mnt

اگر سیستم‌فایلی را با یک کاربر (مثلاً root) مونت کنید، سایر کاربران به طور پیش‌فرض قادر به مشاهده آن نخواهند بود. راه حل اضافه کردن گزینه FUSE به نام "allow_other" هنگام مونت کردن است:

sudo guestmount [...] -o allow_other /mnt

و فعال‌سازی این گزینه در فایل /etc/fuse.conf.

در برخی از توزیع‌ها، ممکن است لازم باشد پیش از استفاده از هر سیستم‌فایل FUSE، خود را به گروه خاصی (مانند "fuse") اضافه کنید. این کار در دبیان و توزیع‌های مشتق از آن ضروری است.

در سایر توزیع‌ها به گروه خاصی نیاز نیست. در فدورا یا Red Hat Enterprise Linux نیازی به این کار نیست.

ممکن است زمانی این خطا را مشاهده کنید که پردازش دیگری روی سیستم وارد نقطه مونتی که تازه ایجاد کرده‌اید شده و آن را باز نگه داشته باشد و مانع از آن‌مونت شدن آن شود. عامل معمول این مشکل برنامه‌های مختلف «نمایه‌سازی» (indexing) در محیط گرافیکی هستند.

راهکار متداول برای این مشکل، تکرار چندباره دستور "fusermount -u" است تا در نهایت با موفقیت انجام شود (دستور guestunmount(1) این کار را به صورت خودکار برای شما انجام می‌دهد). متأسفانه این راهکار همیشه قابل اعتماد نیست؛ برای نمونه زمانی که سیستم‌فایل مونت‌شده بسیار بزرگ باشد و برنامه مداخله‌گر با سرسختی به کار خود ادامه دهد.

راه حل اصولی، استفاده از یک نقطه مونت خصوصی با ایجاد یک فضای نام مونت (mount namespace) جدید با استفاده از فلگ مخصوص لینوکس "CLONE_NEWNS" در clone(2)/unshare(2) است. متأسفانه در حال حاضر این کار نیاز به دسترسی ریشه دارد و احتمالاً باید به عنوان یک ویژگی به guestmount اضافه شود.

هنگامی که دستور guestunmount(1)/fusermount(1) خاتمه می‌یابد، ممکن است guestmount هنوز در حال اجرا و پاک‌سازی نقطه مونت باشد. در این حالت ایمیج دیسک هنوز کاملاً نهایی و تثبیت نشده است.

این بدان معناست که اسکریپت‌هایی مانند نمونه زیر دارای شرایط رقابت (race condition) خطرناکی هستند:

guestmount -a disk.img -i /mnt
# کپی کردن فایل‌ها به درون /mnt
guestunmount /mnt
# تلاش فوری برای استفاده از 'disk.img' ** ناایمن **

راه حل استفاده از گزینه --pid-file برای نوشتن شناسه پردازش (PID) دستور guestmount در یک فایل است، و سپس پس از guestunmount، منتظر ماندن در یک حلقه تا زمان خروج این PID است.

guestmount -a disk.img -i --pid-file guestmount.pid /mnt
# ...
# ...
# ذخیره شناسه پردازش guestmount *پیش* از فراخوانی guestunmount.
pid="$(cat guestmount.pid)"
# آن‌مونت کردن سیستم‌فایل.
guestunmount /mnt
timeout=10
count=$timeout
while kill -0 "$pid" 2>/dev/null && [ $count -gt 0 ]; do
    sleep 1
    ((count--))
done
if [ $count -eq 0 ]; then
    echo "$0: wait for guestmount to exit failed after $timeout seconds"
    exit 1
fi
# اکنون استفاده از ایمیج دیسک ایمن است.

توجه داشته باشید که اگر مستقیماً از رابط برنامه‌نویسی "guestfs_mount_local" استفاده کنید (بخش "MOUNT LOCAL" در guestfs(3) را ببینید)، نوشتن برنامه‌ای ایمن و عاری از شرایط رقابت بسیار ساده‌تر خواهد بود.

افزودن یک دستگاه بلوکی یا ایمیج ماشین مجازی.

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

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

به جای نام‌ها می‌توان از UUID دامنه‌ها نیز استفاده کرد.

تنظیم مدت زمان انقضای حافظه موقت (کش) readdir بر حسب N ثانیه که پیش‌فرض آن ۶۰ ثانیه است. کش readdir [در واقع چندین کش نیمه‌مستقل وجود دارد] پس از فراخوانی readdir(2) با اطلاعات stat و ویژگی‌های گسترش‌یافته فایل‌های درون دایرکتوری پر می‌شود، با این فرض که به زودی مورد درخواست قرار خواهند گرفت.

کش ویژگی دیگری نیز وجود دارد که توسط FUSE پیاده‌سازی شده است (گزینه FUSE به نام -o attr_timeout را ببینید)، اما کش FUSE درخواست‌های آتی را پیش‌بینی نمی‌کند و فقط موارد موجود را کش می‌کند.

هنگام درخواست کلیدها و گذرواژه‌ها، guestfish معمولاً نمایش کاراکترها را غیرفعال می‌کند تا آنچه تایپ می‌کنید دیده نشود. اگر نگران حملات تمپست (Tempest) نیستید و فرد دیگری در اتاق حضور ندارد، می‌توانید این گزینه را مشخص کنید تا آنچه تایپ می‌کنید را ببینید.
مشخص کردن توصیف‌کننده فایل پایپ یا eventfd. هنگامی که نقطه مونت آماده استفاده باشد، guestmount یک بایت منفرد در این توصیف‌کننده فایل می‌نویسد. این گزینه می‌تواند همراه با --no-fork استفاده شود تا guestmount زیر نظر پردازش دیگری اجرا شود.
حالت پیش‌فرض برای گزینه -a تشخیص خودکار فرمت ایمیج دیسک است. استفاده از این گزینه، فرمت دیسک را برای گزینه‌های -a که پس از آن در خط فرمان می‌آیند اجبار می‌کند. استفاده از --format بدون آرگومان، وضعیت را به تشخیص خودکار برای گزینه‌های -a بعدی بازمی‌گرداند.

اگر ایمیج‌های دیسک خام (raw) با منبع غیرقابل اعتماد دارید، باید از این گزینه برای مشخص کردن فرمت دیسک استفاده کنید. این کار از یک مشکل امنیتی احتمالی توسط ماشین‌های مخرب جلوگیری می‌کند (CVE-2010-3851). همچنین به "guestfs_add_drive_opts" در guestfs(3) مراجعه کنید.

نمایش راهنمای گزینه‌های ویژه FUSE (به -o در زیر مراجعه کنید).
نمایش راهنمای مختصر و خروج.
با استفاده از کدهای virt-inspector(1)، دیسک‌ها را برای یافتن سیستم‌عامل بازرسی کرده و سیستم‌فایل‌ها را همان‌گونه که روی ماشین مجازی واقعی مونت می‌شدند، مونت می‌کند.
مشخص کردن یک کلید برای LUKS، جهت بازگشایی خودکار دستگاه رمزنگاری‌شده LUKS هنگام استفاده از بازرسی.
"NAME" نام دستگاه در libguestfs است (مانند "/dev/sda1"). "UUID" شناسه یکتای دستگاه (UUID) است. "all" به معنای آزمودن کلید روی تمامی دستگاه‌های رمزنگاری‌شده است.

استفاده از "KEY_STRING" مشخص‌شده به عنوان گذرواژه.

خواندن گذرواژه از فایل FILENAME.
تلاش برای بازگشایی بدون گذرواژه دستگاه از طریق Clevis روی شبکه. لطفاً برای اطلاعات بیشتر درباره رمزنگاری دیسک مبتنی بر شبکه (NBDE) به بخش "ENCRYPTED DISKS" در guestfs(3) مراجعه کنید.

توجه داشته باشید که در صورت وجود چنین گزینه‌ای در خط فرمان، شبکه کاربری QEMU به طور خودکار برای تجهیزات libguestfs فعال خواهد شد.

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

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

مونت کردن پارتیشن یا حجم منطقی نام‌برده روی نقطه مونت مشخص‌شده درون ماشین مجازی (این مورد ارتباطی با نقاط مونت در سیستم میزبان ندارد).

در صورت حذف نقطه مونت، مقدار پیش‌فرض آن / خواهد بود. شما باید حتماً چیزی را روی / مونت کنید.

بخش سوم (که به ندرت استفاده می‌شود) از پارامتر mount، فهرست گزینه‌های مونت مورد استفاده برای سیستم‌فایل زیرین است. اگر این بخش مشخص نشود، گزینه‌های مونت یا رشته خالی یا "ro" خواهد بود (مورد اخیر در صورتی است که فلگ --ro استفاده شده باشد). با تعیین گزینه‌های مونت، این انتخاب پیش‌فرض را لغو می‌کنید. احتمالاً تنها زمانی از این گزینه استفاده می‌کنید که بخواهید در صورت پشتیبانی سیستم‌فایل، ACLها یا ویژگی‌های گسترش‌یافته را فعال کنید:

-m /dev/sda1:/:acl,user_xattr

بخش چهارم پارامتر، درایور سیستم‌فایل مورد استفاده است، مانند "ext3" یا "ntfs". این بخش به ندرت نیاز می‌شود، اما زمانی مفید است که چندین درایور برای یک سیستم‌فایل معتبر باشند (مانند: "ext2" و "ext3")، یا اگر libguestfs سیستم‌فایل را اشتباه تشخیص دهد.

عدم اجرای پس‌زمینه (یا عدم انشعاب به صورت دیمن در پس‌زمینه).
به طور پیش‌فرض، هنگام آن‌مونت شدن نقطه مونت FUSE، تلاش می‌کنیم دیسک ماشین مجازی را همگام‌سازی (sync) کنیم. اگر این گزینه را مشخص کنید، تلاشی برای همگام‌سازی دیسک انجام نخواهد شد. به توضیحات autosync در صفحه راهنمای guestfs(3) مراجعه کنید.
ارسال گزینه‌های اضافی به FUSE.

برای دریافت فهرست تمامی گزینه‌های اضافی پشتیبانی‌شده توسط FUSE، از دستور زیر استفاده کنید. توجه داشته باشید که تنها گزینه‌های -o مربوط به FUSE قابل ارسال هستند، و تنها استفاده از برخی از آن‌ها ایده خوبی است.

guestmount --fuse-help

برخی از گزینه‌های بالقوه مفید FUSE:

اجازه به سایر کاربران برای مشاهده سیستم‌فایل. این گزینه هیچ تأثیری ندارد مگر اینکه آن را به صورت سراسری در /etc/fuse.conf فعال کرده باشید.
فعال‌سازی کش ویژگی‌ها توسط FUSE و تنظیم مدت زمان انقضا به N ثانیه.
اجازه به هسته برای کش کردن فایل‌ها (کاهش تعداد خواندن‌هایی که باید از طریق رابط کاربری guestfs(3) انجام شوند). این کار عموماً ایده خوبی است در صورتی که بتوانید حافظه مصرفی اضافه را تأمین کنید.
استفاده از این گزینه‌ها برای نگاشت تمامی UIDها و GIDهای درون سیستم‌فایل ماشین مجازی به مقادیر انتخاب‌شده.
حفظ شماره‌های اینود (inode) از سیستم‌فایل زیرین.

بدون این گزینه، FUSE شماره‌های اینود اختصاصی خود را تولید می‌کند. شماره‌های اینودی که در stat(2)، "ls -i" و غیره می‌بینید، شماره‌های اینود سیستم‌فایل زیرین نخواهند بود.

توجه این گزینه در صورتی که سیستم‌فایل زیرین شامل چندین نقطه مونت باشد بالقوه خطرناک است، زیرا ممکن است شماره‌های اینود تکراری از طریق FUSE مشاهده شوند. استفاده از این گزینه می‌تواند برخی نرم‌افزارها را دچار سردرگمی کند.

نوشتن شناسه پردازش (PID) پردازش کارگر guestmount در "filename".
افزودن دستگاه‌ها و مونت کردن همه‌چیز به صورت فقط‌خواندنی. همچنین نوشتن را ممنوع کرده و دیسک را برای FUSE به صورت فقط‌خواندنی نمایش می‌دهد.

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

همچنین به بخش "OPENING DISKS FOR READ AND WRITE" در guestfish(1) مراجعه کنید.

این گزینه برای سازگاری با نسخه‌های پیشین فراهم شده و کاری انجام نمی‌دهد.
فعال‌سازی پیام‌های پرجزئیات از libguestfs زیرین.
نمایش نسخه برنامه و خروج.
این گزینه عملکرد گزینه‌های -a، -d و -m را تغییر می‌دهد تا دیسک‌ها به صورت خواندنی-نوشتنی اضافه و مونت شوند.

به بخش "OPENING DISKS FOR READ AND WRITE" در guestfish(1) مراجعه کنید.

ردیابی فراخوانی‌های libguestfs و ورود به هر تابع FUSE.

این گزینه همچنین از رفتن دیمن به پس‌زمینه جلوگیری می‌کند (گزینه --no-fork را ببینید).

$XDG_CONFIG_HOME/libguestfs/libguestfs-tools.conf
$HOME/.libguestfs-tools.rc
$XDG_CONFIG_DIRS/libguestfs/libguestfs-tools.conf
/etc/libguestfs-tools.conf
این فایل پیکربندی حالت پیش‌فرض فقط‌خواندنی یا خواندنی-نوشتنی را کنترل می‌کند (--ro یا --rw).

به libguestfs-tools.conf(5) مراجعه کنید.

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

guestunmount(1), fusermount(1), guestfish(1), virt-inspector(1), virt-cat(1), virt-edit(1), virt-tar(1), libguestfs-tools.conf(5), "MOUNT LOCAL" in guestfs(3), http://libguestfs.org, http://fuse.sf.net

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

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