virt-filesystems(1) Virtualization Support virt-filesystems(1)

virt-filesystems - کشف و فهرست‌بندی سیستم‌های فایل، پارتیشن‌ها و حجم‌های LVM در ماشین مجازی

virt-filesystems [--options] -d domname
virt-filesystems [--options] -a disk.img [-a disk.img ...]

این ابزار امکان کشف سیستم‌های فایل، پارتیشن‌ها، حجم‌های منطقی (Logical Volumes) و اندازه آن‌ها را در یک تصویر دیسک یا ماشین مجازی فراهم می‌کند. این ابزار جایگزینی برای virt-list-filesystems(1) و virt-list-partitions(1) است.

یک کاربرد این ابزار در اسکریپت‌های پوسته (Shell Scripts) برای پیمایش تمام سیستم‌های فایل موجود در یک تصویر دیسک است:

for fs in $(virt-filesystems -a disk.img); do
  # ...
done

کاربرد دیگر، فهرست‌بندی پارتیشن‌ها پیش از استفاده از ابزار دیگر برای تغییر آن‌ها است (مانند virt-resize(1)). اگر مایلید محتویات یک تصویر دیسک ناشناخته را بررسی کنید، می‌توانید از این ابزار در کنار virt-inspector(1) استفاده نمایید.

گزینه‌های مختلف خط فرمان نحوه نمایش خروجی این برنامه را کنترل می‌کنند. برای مشخص کردن تصویر دیسک یا ماشین مهمان libvirt، باید به ترتیب یکی از گزینه‌های -a یا -d را وارد کنید. اگر فقط همین گزینه را مشخص کنید، برنامه سیستم‌های فایل پیداشده را سطر به سطر نمایش می‌دهد، مانند این:

$ virt-filesystems -a disk.img
/dev/sda1
/dev/vg_guest/lv_root

اگر گزینه -l یا --long را اضافه کنید، خروجی شامل اطلاعات تکمیلی خواهد بود:

$ virt-filesystems -a disk.img -l
Name                   Type         VFS   Label  Size
/dev/sda1              filesystem   ext4  boot   524288000
/dev/vg_guest/lv_root  filesystem   ext4  root   10212081664

اگر گزینه --extra را اضافه کنید، سیستم‌های فایل غیرقابل‌سوارکردن (مانند swap یا ناشناخته) نیز نمایش داده می‌شوند:

$ virt-filesystems -a disk.img --extra
/dev/sda1
/dev/vg_guest/lv_root
/dev/vg_guest/lv_swap
/dev/vg_guest/lv_data

اگر گزینه --partitions را اضافه کنید، به جای سیستم‌های فایل، پارتیشن‌ها نمایش داده می‌شوند:

$ virt-filesystems -a disk.img --partitions
/dev/sda1
/dev/sda2

به طور مشابه می‌توانید از --logical-volumes، --volume-groups، --physical-volumes و --block-devices برای فهرست‌بندی این موارد استفاده کنید.

همچنین می‌توانید این گزینه‌ها را به صورت ترکیبی استفاده کنید (اگر ترکیبی شامل سیستم‌های فایل می‌خواهید، باید گزینه --filesystems را نیز اضافه کنید). توجه داشته باشید که برخی موارد در چند دسته‌بندی قرار می‌گیرند (مثلاً /dev/sda1 ممکن است هم یک پارتیشن و هم یک سیستم فایل باشد). این موارد چند بار فهرست می‌شوند. برای دریافت فهرستی که شامل مطلقاً همه مواردی باشد که virt-filesystems می‌شناسد، از گزینه --all استفاده کنید.

شناسه‌های UUID (به دلیل طولانی بودن) به طور پیش‌فرض نمایش داده نمی‌شوند. برای نمایش UUID دستگاه‌ها و سیستم‌های فایل در خروجی قالب بلند، گزینه --uuid را اضافه کنید.

ترکیب --all --long --uuid برای نمایش تمام اطلاعات ممکن درباره همه بخش‌ها بسیار کاربردی است.

$ virt-filesystems -a win.img --all --long --uuid -h
Name      Type       VFS  Label           Size Parent   UUID
/dev/sda1 filesystem ntfs System Reserved 100M -        F81C92571C92112C
/dev/sda2 filesystem ntfs -               20G  -        F2E8996AE8992E3B
/dev/sda1 partition  -    -               100M /dev/sda -
/dev/sda2 partition  -    -               20G  /dev/sda -
/dev/sda  device     -    -               20G  -        -

برای خروجی ماشین‌خوان، از گزینه --csv برای دریافت مقادیر جداشده با کاما (CSV) استفاده کنید.

نمایش راهنمای مختصر.
افزودن file که باید یک تصویر دیسک از یک ماشین مجازی باشد. اگر ماشین مجازی دارای چندین دستگاه بلوکی است، باید همه آن‌ها را با گزینه‌های مجزای -a مشخص کنید.

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

افزودن یک دیسک راه‌دور. به بخش "ADDING REMOTE STORAGE" در guestfish(1) مراجعه کنید.
نمایش همه موارد. این گزینه در حال حاضر معادل مشخص کردن این گزینه‌ها است: --filesystems، --extra، --partitions، --block-devices، --logical-volumes، --volume-groups و --physical-volumes. (ممکن است در آینده موارد بیشتری به این لیست اضافه شوند).

همچنین گزینه --long را ببینید.

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

اگر دستگاه‌های بلوکی مهمان را مستقیماً با (-a) مشخص کنید، libvirt اصلاً استفاده نمی‌شود.

نوشتن نتایج در قالب CSV (مقادیر جداشده با کاما). این قالب را می‌توان به سادگی به پایگاه‌های داده و صفحات گسترده وارد کرد، اما بخش "نکته‌ای درباره قالب CSV" را در ادامه مطالعه نمایید.
افزودن تمام دیسک‌ها از ماشین مهمان مشخص‌شده در libvirt. می‌توان به جای نام از شناسه UUID دامنه نیز استفاده کرد.
هنگام درخواست کلیدها و گذرواژه‌ها، virt-filesystems معمولاً انعکاس ورودی (echoing) را غیرفعال می‌کند تا آنچه تایپ می‌کنید دیده نشود. اگر نگران حملات Tempest نیستید و کس دیگری در اتاق نیست، می‌توانید این پرچم را مشخص کنید تا متن تایپ‌شده خود را ببینید.
این گزینه باعث می‌شود سیستم‌های فایلی که معمولی و قابل‌سوارکردن نیستند نیز نمایش داده شوند. این دسته شامل فضای swap و سیستم‌های فایلی است که خالی هستند یا داده‌های ناشناخته دارند.

این گزینه متضمن گزینه --filesystems است.

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

همراه با --extra، سیستم‌های فایل غیرقابل‌سوارکردن نیز نمایش داده می‌شوند.

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

برای مثال:

virt-filesystems --format=raw -a disk.img

قالب raw (بدون تشخیص خودکار) را برای disk.img اجبار می‌کند.

virt-filesystems --format=raw -a disk.img --format -a another.img

قالب raw (بدون تشخیص خودکار) را برای disk.img اجبار کرده و برای another.img به تشخیص خودکار بازمی‌گردد.

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

در حالت --long، نسخه سیستم فایل را نمایش می‌دهد. در حال حاضر این گزینه فقط روی XFS اثر دارد و مقدار 4 (برای XFS v4) یا 5 (برای XFS v5) را نمایش می‌دهد. پشتیبانی از XFS v4 در سال ۲۰۳۰ از لینوکس حذف خواهد شد.
در حالت --long، اندازه‌ها را در قالبی خوانا برای انسان نمایش می‌دهد.
خواندن کلید یا گذرواژه از ورودی استاندارد (stdin). حالت پیش‌فرض این است که با باز کردن /dev/tty تلاش شود گذرواژه‌ها از کاربر دریافت شوند.

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

نمایش ستون‌های داده اضافی («قالب بلند»).

یک ردیف عنوان اضافه می‌شود مگر اینکه گزینه --no-title را نیز مشخص کنید.

ستون‌های اضافی نمایش‌داده‌شده بستگی به خروجی انتخابی شما دارند و ممکن است ترتیب ستون‌ها در نسخه‌های بعدی تغییر کند. از ردیف عنوان، خروجی --csv و/یا csvtool(1) برای تطبیق ستون‌ها با داده‌ها در برنامه‌های خارجی استفاده کنید.

اگر می‌خواهید اندازه‌ها به صورت خوانا برای انسان نمایش داده شوند، از -h استفاده کنید. حالت پیش‌فرض نمایش اعداد خام به صورت بایت است.

از --fs-version برای نمایش نسخه‌های سیستم فایل استفاده کنید.

از --uuid برای نمایش UUIDها استفاده کنید.

نمایش حجم‌های منطقی LVM. در این حالت، این موارد بدون توجه به اینکه آیا LVها حاوی سیستم فایل هستند یا خیر نمایش داده می‌شوند.
در حالت --long، ردیف عنوان را اضافه نکن.

توجه داشته باشید که ترتیب ستون‌ها ثابت نیست و ممکن است در نسخه‌های بعدی virt-filesystems تغییر کند، بنابراین استفاده از این گزینه ممکن است باعث نتایج غیرمنتظره شود.

نمایش پارتیشن‌ها. در این حالت، این موارد صرف‌نظر از اینکه پارتیشن‌ها حاوی سیستم فایل باشند یا خیر نمایش داده می‌شوند.
نمایش حجم‌های فیزیکی LVM.
در حالت --long، شناسه‌های UUID را نیز نمایش می‌دهد.
فعال‌سازی پیام‌های پرجزئیات برای اشکال‌زدایی.
نمایش شماره نسخه و خروج.
نمایش گروه‌های حجمی LVM.
فعال‌سازی ردیابی فراخوانی‌های API در libguestfs.

توجه داشته باشید که ستون‌ها در خروجی ممکن است در نسخه‌های بعدی این ابزار تغییر کرده یا مرتب‌سازی مجدد شوند.

نام سیستم فایل، پارتیشن، دستگاه بلوکی یا LVM.

برای نام دستگاه‌ها و پارتیشن‌ها، این موارد به عنوان نام‌های رسمی libguestfs نمایش داده می‌شوند، به عنوان مثال /dev/sda2 دومین پارتیشن روی نخستین دستگاه است.

اگر گزینه --long مشخص نشده باشد، تنها ستون Name در خروجی نمایش داده می‌شود.

نوع شیء، برای مثال "filesystem"، "lv"، "device" و غیره.
اگر سیستم فایلی وجود داشته باشد، این ستون نوع سیستم فایل را در صورت قابل‌تشخیص بودن نمایش می‌دهد، مانند "ext4".
اگر شیء دارای برچسب باشد (که برای شناسایی و سوار کردن سیستم‌های فایل استفاده می‌شود)، این ستون حاوی برچسب خواهد بود.
بایت نوع پارتیشن، که به صورت یک عدد هگزادسیمال دو رقمی نمایش داده می‌شود. فهرست جامعی از انواع پارتیشن را می‌توان در اینجا یافت: http://www.win.tue.nl/~aeb/partitions/partition_types-1.html

این مورد تنها برای پارتیشن‌های DOS (MBR) کاربرد دارد.

اندازه شیء به بایت. اگر از گزینه --human استفاده شود، اندازه به صورت خوانا برای انسان نمایش داده می‌شود.
ستون والد رابطه والد-فرزندی بین اشیاء را ثبت می‌کند.

به عنوان مثال، اگر شیء یک پارتیشن باشد، این ستون حاوی نام دستگاه دربرگیرنده آن است. اگر شیء یک حجم منطقی (Logical Volume) باشد، این ستون نام گروه حجمی (Volume Group) خواهد بود.

اگر بیش از یک والد وجود داشته باشد، این ستون (درون خود ستون) یک فهرست جداشده با کاما خواهد بود، مانند "/dev/sda,/dev/sdb".

اگر شیء دارای یک UUID باشد (که برای شناسایی و سوار کردن سیستم‌های فایل و دستگاه‌های بلوکی استفاده می‌شود)، این ستون حاوی UUID به صورت رشته خواهد بود.

شناسه UUID تنها زمانی نمایش داده می‌شود که گزینه --uuid داده شده باشد.

قالب مقادیر جداشده با کاما (CSV) یک قالب فریبنده است. به نظر می‌رسد که تجزیه آن باید آسان باشد، اما مسلماً تجزیه آن ساده نیست.

باور غلط: فقط فیلدها را در محل کاماها تقسیم کنید. واقعیت: این روش به طور قابل‌اطمینان عمل نمی‌کند. این مثال دو ستون دارد:

"foo,bar",baz

باور غلط: فایل را خط به خط بخوانید. واقعیت: این روش به طور قابل‌اطمینان عمل نمی‌کند. این مثال یک ردیف دارد:

"foo
bar",baz

برای اسکریپت‌های پوسته، از "csvtool" (https://github.com/Chris00/ocaml-csv که در توزیع‌های عمده لینوکس نیز بسته‌بندی شده است) استفاده کنید.

برای سایر زبان‌ها، از یک کتابخانه پردازش CSV استفاده کنید (مانند "Text::CSV" برای Perl یا کتابخانه توکار csv در پایتون).

بیشتر صفحات گسترده و پایگاه‌های داده می‌توانند CSV را مستقیماً وارد کنند.

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

guestfs(3), guestfish(1), virt-cat(1), virt-df(1), virt-drivers(1), virt-list-filesystems(1), virt-list-partitions(1), csvtool(1), http://libguestfs.org.

Richard W.M. Jones http://people.redhat.com/~rjones

Copyright (C) 2010-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-11 guestfs-tools-1.56.0