guestmount(1) Virtualization Support guestmount(1) نام (NAME) guestmount - مونت کردن سیستم‌فایل‌های ماشین مجازی روی سیستم میزبان با FUSE و libguestfs خلاصه دستور (SYNOPSIS) guestmount [--options] -a disk.img -m device [--ro] mountpoint guestmount [--options] -a disk.img -i [--ro] mountpoint guestmount [--options] -d Guest -i [--ro] mountpoint هشدار (WARNING) استفاده از "guestmount" در حالت نوشتنی روی ماشین‌های مجازی فعال و روشن، یا همزمان با سایر ابزارهای ویرایش دیسک، می‌تواند خطرناک باشد و به خرابی داده‌های دیسک منجر شود. ماشین مجازی باید پیش از استفاده از این دستور خاموش شود، و ایمیج‌های دیسک نباید به صورت همزمان ویرایش شوند. در صورتی که ایمیج دیسک یا ماشین مجازی ممکن است روشن باشد، از گزینه --ro (فقط‌خواندنی) استفاده کنید تا "guestmount" به صورت ایمن اجرا شود. در صورت اجرای همزمان با سایر تغییرات ممکن است نتایج عجیب یا ناهماهنگی مشاهده کنید، اما با این گزینه با خطر خرابی دیسک مواجه نخواهید شد. توضیحات (DESCRIPTION) برنامه guestmount برای مونت کردن سیستم‌فایل‌های ماشین‌های مجازی و سایر ایمیج‌های دیسک روی سیستم میزبان به کار می‌رود. این برنامه از libguestfs برای دسترسی به سیستم‌فایل ماشین مجازی، و از FUSE (سامانه سیستم‌فایل در فضای کاربری) برای نمایش آن به صورت یک دستگاه قابل مونت استفاده می‌کند. در کنار سایر گزینه‌ها، باید دست‌کم یک دستگاه (گزینه -a) یا دامنه libvirt (گزینه -d)، و حداقل یک نقطه مونت (گزینه -m) مشخص کنید یا از گزینه بازرسی -i استفاده نمایید. نحوه عملکرد این بخش در صفحه راهنمای guestfish(1) یا با مشاهده مثال‌های زیر بهتر توضیح داده شده است. قابلیت FUSE امکان مونت کردن سیستم‌فایل‌ها را بدون دسترسی ریشه (non-root) فراهم می‌کند. نقطه مونت باید متعلق به شما باشد. سیستم‌فایل برای سایر کاربران قابل مشاهده نخواهد بود مگر اینکه تنظیمات را تغییر دهید؛ بخش «نکات» را در زیر ببینید. برای آن‌مونت کردن سیستم‌فایل، از دستور guestunmount(1) استفاده کنید. مثال‌ها (EXAMPLES) برای یک ماشین ویندوزی معمولی که سیستم‌فایل اصلی آن روی پارتیشن اول قرار دارد: 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 نکات (NOTES) به‌طور پیش‌فرض سایر کاربران نمی‌توانند سیستم‌فایل را ببینند اگر سیستم‌فایلی را با یک کاربر (مثلاً root) مونت کنید، سایر کاربران به طور پیش‌فرض قادر به مشاهده آن نخواهند بود. راه حل اضافه کردن گزینه FUSE به نام "allow_other" هنگام مونت کردن است: sudo guestmount [...] -o allow_other /mnt و فعال‌سازی این گزینه در فایل /etc/fuse.conf. فعال‌سازی FUSE در برخی از توزیع‌ها، ممکن است لازم باشد پیش از استفاده از هر سیستم‌فایل FUSE، خود را به گروه خاصی (مانند "fuse") اضافه کنید. این کار در دبیان و توزیع‌های مشتق از آن ضروری است. در سایر توزیع‌ها به گروه خاصی نیاز نیست. در فدورا یا Red Hat Enterprise Linux نیازی به این کار نیست. خطای fusermount: "Device or resource busy" ممکن است زمانی این خطا را مشاهده کنید که پردازش دیگری روی سیستم وارد نقطه مونتی که تازه ایجاد کرده‌اید شده و آن را باز نگه داشته باشد و مانع از آن‌مونت شدن آن شود. عامل معمول این مشکل برنامه‌های مختلف «نمایه‌سازی» (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) را ببینید)، نوشتن برنامه‌ای ایمن و عاری از شرایط رقابت بسیار ساده‌تر خواهد بود. گزینه‌ها (OPTIONS) -a IMAGE --add IMAGE افزودن یک دستگاه بلوکی یا ایمیج ماشین مجازی. فرمت ایمیج دیسک به طور خودکار تشخیص داده می‌شود. برای لغو این حالت و اجبار به استفاده از یک فرمت خاص، از گزینه --format=.. استفاده کنید. -a URI --add URI افزودن یک دیسک دوردست. بخش "ADDING REMOTE STORAGE" را در guestfish(1) ببینید. --blocksize=512 --blocksize=4096 --blocksize این پارامتر اندازه سکتور ایمیج دیسک را تعیین می‌کند. این مقدار بر تمامی دیسک‌هایی که پس از این پارامتر به صورت صریح اضافه شوند تأثیر می‌گذارد. استفاده از --blocksize بدون آرگومان، اندازه سکتور دیسک را به مقدار پیش‌فرض که معمولاً ۵۱۲ بایت است تغییر می‌دهد. همچنین به "guestfs_add_drive_opts" در guestfs(3) مراجعه کنید. -c URI --connect URI هنگامی که همراه با گزینه -d استفاده شود، نشانی اینترنتی (URI) اتصال libvirt را مشخص می‌کند. حالت پیش‌فرض استفاده از اتصال پیش‌فرض libvirt است. -d LIBVIRT-DOMAIN --domain LIBVIRT-DOMAIN افزودن دیسک‌ها از دامنه نام‌برده libvirt. اگر از گزینه --ro نیز استفاده شود، می‌توان هر دامنه libvirt را مشخص کرد. با این حال در حالت نوشتنی، فقط دامنه‌های libvirt که خاموش هستند می‌توانند در اینجا نام برده شوند. به جای نام‌ها می‌توان از UUID دامنه‌ها نیز استفاده کرد. --dir-cache-timeout N تنظیم مدت زمان انقضای حافظه موقت (کش) readdir بر حسب N ثانیه که پیش‌فرض آن ۶۰ ثانیه است. کش readdir [در واقع چندین کش نیمه‌مستقل وجود دارد] پس از فراخوانی readdir(2) با اطلاعات stat و ویژگی‌های گسترش‌یافته فایل‌های درون دایرکتوری پر می‌شود، با این فرض که به زودی مورد درخواست قرار خواهند گرفت. کش ویژگی دیگری نیز وجود دارد که توسط FUSE پیاده‌سازی شده است (گزینه FUSE به نام -o attr_timeout را ببینید)، اما کش FUSE درخواست‌های آتی را پیش‌بینی نمی‌کند و فقط موارد موجود را کش می‌کند. --echo-keys هنگام درخواست کلیدها و گذرواژه‌ها، guestfish معمولاً نمایش کاراکترها را غیرفعال می‌کند تا آنچه تایپ می‌کنید دیده نشود. اگر نگران حملات تمپست (Tempest) نیستید و فرد دیگری در اتاق حضور ندارد، می‌توانید این گزینه را مشخص کنید تا آنچه تایپ می‌کنید را ببینید. --fd=FD مشخص کردن توصیف‌کننده فایل پایپ یا eventfd. هنگامی که نقطه مونت آماده استفاده باشد، guestmount یک بایت منفرد در این توصیف‌کننده فایل می‌نویسد. این گزینه می‌تواند همراه با --no-fork استفاده شود تا guestmount زیر نظر پردازش دیگری اجرا شود. --format=raw|qcow2|.. --format حالت پیش‌فرض برای گزینه -a تشخیص خودکار فرمت ایمیج دیسک است. استفاده از این گزینه، فرمت دیسک را برای گزینه‌های -a که پس از آن در خط فرمان می‌آیند اجبار می‌کند. استفاده از --format بدون آرگومان، وضعیت را به تشخیص خودکار برای گزینه‌های -a بعدی بازمی‌گرداند. اگر ایمیج‌های دیسک خام (raw) با منبع غیرقابل اعتماد دارید، باید از این گزینه برای مشخص کردن فرمت دیسک استفاده کنید. این کار از یک مشکل امنیتی احتمالی توسط ماشین‌های مخرب جلوگیری می‌کند (CVE-2010-3851). همچنین به "guestfs_add_drive_opts" در guestfs(3) مراجعه کنید. --fuse-help نمایش راهنمای گزینه‌های ویژه FUSE (به -o در زیر مراجعه کنید). --help نمایش راهنمای مختصر و خروج. -i --inspector با استفاده از کدهای virt-inspector(1)، دیسک‌ها را برای یافتن سیستم‌عامل بازرسی کرده و سیستم‌فایل‌ها را همان‌گونه که روی ماشین مجازی واقعی مونت می‌شدند، مونت می‌کند. --key SELECTOR مشخص کردن یک کلید برای LUKS، جهت بازگشایی خودکار دستگاه رمزنگاری‌شده LUKS هنگام استفاده از بازرسی. --key NAME:key:KEY_STRING --key UUID:key:KEY_STRING --key all:key:KEY_STRING "NAME" نام دستگاه در libguestfs است (مانند "/dev/sda1"). "UUID" شناسه یکتای دستگاه (UUID) است. "all" به معنای آزمودن کلید روی تمامی دستگاه‌های رمزنگاری‌شده است. استفاده از "KEY_STRING" مشخص‌شده به عنوان گذرواژه. --key NAME:file:FILENAME --key UUID:file:FILENAME --key all:file:FILENAME خواندن گذرواژه از فایل FILENAME. --key NAME:clevis --key UUID:clevis --key all:clevis تلاش برای بازگشایی بدون گذرواژه دستگاه از طریق Clevis روی شبکه. لطفاً برای اطلاعات بیشتر درباره رمزنگاری دیسک مبتنی بر شبکه (NBDE) به بخش "ENCRYPTED DISKS" در guestfs(3) مراجعه کنید. توجه داشته باشید که در صورت وجود چنین گزینه‌ای در خط فرمان، شبکه کاربری QEMU به طور خودکار برای تجهیزات libguestfs فعال خواهد شد. --keys-from-stdin خواندن پارامترهای کلید یا گذرواژه از ورودی استاندارد (stdin). حالت پیش‌فرض تلاش برای خواندن گذرواژه‌ها از کاربر با باز کردن /dev/tty است. اگر چند دستگاه رمزنگاری‌شده وجود داشته باشد، ممکن است نیاز باشد چندین کلید را در ورودی استاندارد، هر کدام در یک خط وارد کنید. -m dev[:mountpoint[:options[:fstype]] --mount dev[:mountpoint[:options[:fstype]]] مونت کردن پارتیشن یا حجم منطقی نام‌برده روی نقطه مونت مشخص‌شده درون ماشین مجازی (این مورد ارتباطی با نقاط مونت در سیستم میزبان ندارد). در صورت حذف نقطه مونت، مقدار پیش‌فرض آن / خواهد بود. شما باید حتماً چیزی را روی / مونت کنید. بخش سوم (که به ندرت استفاده می‌شود) از پارامتر mount، فهرست گزینه‌های مونت مورد استفاده برای سیستم‌فایل زیرین است. اگر این بخش مشخص نشود، گزینه‌های مونت یا رشته خالی یا "ro" خواهد بود (مورد اخیر در صورتی است که فلگ --ro استفاده شده باشد). با تعیین گزینه‌های مونت، این انتخاب پیش‌فرض را لغو می‌کنید. احتمالاً تنها زمانی از این گزینه استفاده می‌کنید که بخواهید در صورت پشتیبانی سیستم‌فایل، ACLها یا ویژگی‌های گسترش‌یافته را فعال کنید: -m /dev/sda1:/:acl,user_xattr بخش چهارم پارامتر، درایور سیستم‌فایل مورد استفاده است، مانند "ext3" یا "ntfs". این بخش به ندرت نیاز می‌شود، اما زمانی مفید است که چندین درایور برای یک سیستم‌فایل معتبر باشند (مانند: "ext2" و "ext3")، یا اگر libguestfs سیستم‌فایل را اشتباه تشخیص دهد. --no-fork عدم اجرای پس‌زمینه (یا عدم انشعاب به صورت دیمن در پس‌زمینه). -n --no-sync به طور پیش‌فرض، هنگام آن‌مونت شدن نقطه مونت FUSE، تلاش می‌کنیم دیسک ماشین مجازی را همگام‌سازی (sync) کنیم. اگر این گزینه را مشخص کنید، تلاشی برای همگام‌سازی دیسک انجام نخواهد شد. به توضیحات autosync در صفحه راهنمای guestfs(3) مراجعه کنید. -o OPTION --option OPTION ارسال گزینه‌های اضافی به FUSE. برای دریافت فهرست تمامی گزینه‌های اضافی پشتیبانی‌شده توسط FUSE، از دستور زیر استفاده کنید. توجه داشته باشید که تنها گزینه‌های -o مربوط به FUSE قابل ارسال هستند، و تنها استفاده از برخی از آن‌ها ایده خوبی است. guestmount --fuse-help برخی از گزینه‌های بالقوه مفید FUSE: -o allow_other اجازه به سایر کاربران برای مشاهده سیستم‌فایل. این گزینه هیچ تأثیری ندارد مگر اینکه آن را به صورت سراسری در /etc/fuse.conf فعال کرده باشید. -o attr_timeout=N فعال‌سازی کش ویژگی‌ها توسط FUSE و تنظیم مدت زمان انقضا به N ثانیه. -o kernel_cache اجازه به هسته برای کش کردن فایل‌ها (کاهش تعداد خواندن‌هایی که باید از طریق رابط کاربری guestfs(3) انجام شوند). این کار عموماً ایده خوبی است در صورتی که بتوانید حافظه مصرفی اضافه را تأمین کنید. -o uid=N -o gid=N استفاده از این گزینه‌ها برای نگاشت تمامی UIDها و GIDهای درون سیستم‌فایل ماشین مجازی به مقادیر انتخاب‌شده. -o use_ino حفظ شماره‌های اینود (inode) از سیستم‌فایل زیرین. بدون این گزینه، FUSE شماره‌های اینود اختصاصی خود را تولید می‌کند. شماره‌های اینودی که در stat(2)، "ls -i" و غیره می‌بینید، شماره‌های اینود سیستم‌فایل زیرین نخواهند بود. توجه این گزینه در صورتی که سیستم‌فایل زیرین شامل چندین نقطه مونت باشد بالقوه خطرناک است، زیرا ممکن است شماره‌های اینود تکراری از طریق FUSE مشاهده شوند. استفاده از این گزینه می‌تواند برخی نرم‌افزارها را دچار سردرگمی کند. --pid-file FILENAME نوشتن شناسه پردازش (PID) پردازش کارگر guestmount در "filename". -r --ro افزودن دستگاه‌ها و مونت کردن همه‌چیز به صورت فقط‌خواندنی. همچنین نوشتن را ممنوع کرده و دیسک را برای FUSE به صورت فقط‌خواندنی نمایش می‌دهد. در صورتی که قصد ویرایش دیسک ماشین مجازی را ندارید، استفاده از این گزینه به شدت توصیه می‌شود. اگر ماشین مجازی در حال اجرا باشد و این گزینه ارائه نشود، خطر جدی خرابی دیسک در ماشین وجود خواهد داشت. ما تلاش می‌کنیم از این اتفاق جلوگیری کنیم، اما همیشه امکان‌پذیر نیست. همچنین به بخش "OPENING DISKS FOR READ AND WRITE" در guestfish(1) مراجعه کنید. --selinux این گزینه برای سازگاری با نسخه‌های پیشین فراهم شده و کاری انجام نمی‌دهد. -v --verbose فعال‌سازی پیام‌های پرجزئیات از libguestfs زیرین. -V --version نمایش نسخه برنامه و خروج. -w --rw این گزینه عملکرد گزینه‌های -a، -d و -m را تغییر می‌دهد تا دیسک‌ها به صورت خواندنی-نوشتنی اضافه و مونت شوند. به بخش "OPENING DISKS FOR READ AND WRITE" در guestfish(1) مراجعه کنید. -x --trace ردیابی فراخوانی‌های libguestfs و ورود به هر تابع FUSE. این گزینه همچنین از رفتن دیمن به پس‌زمینه جلوگیری می‌کند (گزینه --no-fork را ببینید). فایل‌ها (FILES) $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) مراجعه کنید. وضعیت خروج (EXIT STATUS) این برنامه در صورت موفقیت مقدار 0 و در صورت بروز خطا مقداری غیر صفر برمی‌گرداند. همچنین ببینید (SEE ALSO) 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 نویسندگان (AUTHORS) Richard W.M. Jones ("rjones at redhat dot com") حق نشر (COPYRIGHT) Copyright (C) 2009-2025 Red Hat Inc. مجوز (LICENSE) این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط مجوز عمومی همگانی گنو (GNU General Public License) همان‌طور که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است؛ چه نسخه ۲ مجوز و یا (به انتخاب خودتان) هر نسخه پس از آن، بازتوزیع کرده یا تغییر دهید. این برنامه به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف مشخص. برای جزئیات بیشتر به مجوز عمومی همگانی گنو مراجعه کنید. شما باید همراه با این برنامه یک نسخه از مجوز عمومی همگانی گنو را دریافت کرده باشید؛ در غیر این صورت به نشانی زیر مکاتبه کنید: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. اشکالات (BUGS) برای دریافت فهرستی از اشکالات ثبت‌شده برای libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools برای گزارش یک اشکال جدید در libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools هنگام گزارش یک اشکال، لطفاً موارد زیر را ارائه دهید: • نسخه libguestfs. • محلی که libguestfs را از آن دریافت کرده‌اید (مانند توزیع لینوکس، کامپایل‌شده از سورس، و غیره). • توصیف دقیق اشکال و ارائه راهی برای بازتولید آن. • دستور libguestfs-test-tool(1) را اجرا کرده و خروجی کامل و دست‌نخورده آن را درون گزارش اشکال قرار دهید. libguestfs-1.60.1 2026-07-14 guestmount(1)