نام (NAME)

virt-ls - فهرست کردن فایل‌ها در یک ماشین مجازی

خلاصه دستور (SYNOPSIS)

virt-ls [--options] -d domname directory [directory ...]
virt-ls [--options] -a disk.img [-a disk.img ...] directory [directory ...]

شیوه قدیمی:

 virt-ls [--options] domname directory
 virt-ls [--options] disk.img [disk.img ...] directory
"virt-ls" نام فایل‌ها، اندازه فایل‌ها، مجموع‌های کنترلی (checksums)، ویژگی‌های گسترش‌یافته (extended attributes) و موارد دیگر را از یک ماشین مجازی یا ایمیج دیسک فهرست می‌کند.

می‌توان چندین نام دایرکتوری را مشخص کرد که در این حالت خروجی هر یک به یکدیگر متصل می‌شود.

برای فهرست کردن دایرکتوری‌ها از یک مهمان libvirt از گزینه -d برای تعیین نام مهمان استفاده کنید. برای یک ایمیج دیسک، از گزینه -a استفاده کنید.

"virt-ls" می‌تواند بسیاری از فهرست‌بندی‌های ساده فایل را انجام دهد. برای موارد پیچیده‌تر ممکن است نیاز باشد از guestfish(1) استفاده کنید یا مستقیماً برنامه‌ای برای API guestfs(3) بنویسید.

مثال‌ها (EXAMPLES)

دریافت فهرستی از تمام فایل‌ها و دایرکتوری‌ها در یک ماشین مجازی:

virt-ls -R -d guest /

فهرست کردن تمام برنامه‌های دارای مجوز setuid یا setgid در یک ماشین مجازی لینوکس:

virt-ls -lR -d guest / | grep '^- [42]'

فهرست کردن تمام دایرکتوری‌های قابل نوشتن همگانی (public-writable) در یک ماشین مجازی لینوکس:

virt-ls -lR -d guest / | grep '^d ...7'

فهرست کردن تمام سوکت‌های دامنه یونیکس (Unix domain sockets) در یک ماشین مجازی لینوکس:

virt-ls -lR -d guest / | grep '^s'

فهرست کردن تمام فایل‌های عادی که نام آن‌ها به ‘.png’ ختم می‌شود:

virt-ls -lR -d guest / | grep -i '^-.*\.png$'

برای نمایش فایل‌های بزرگ‌تر از 10MB در دایرکتوری‌های home:

virt-ls -lR -d guest /home | awk '$3 > 10*1024*1024'

یافتن هر آنچه در 7 روز گذشته تغییر یافته است:

virt-ls -lR -d guest --time-days / | awk '$6 <= 7'

یافتن فایل‌های عادی تغییریافته در 24 ساعت گذشته:

virt-ls -lR -d guest --time-days / | grep '^-' | awk '$6 < 1'

تفاوت‌ها در اسنپ‌شات‌ها و فایل‌های پشتیبان (DIFFERENCES IN SNAPSHOTS AND BACKING FILES)

اگرچه می‌توان از virt-ls برای بررسی تفاوت‌ها استفاده کرد، اما از نسخه libguestfs ≥ 1.26 ابزار جدیدی به نام virt-diff(1) در دسترس است.

حالت‌های خروجی (OUTPUT MODES)

"virt-ls" دارای چهار حالت خروجی است که با ترکیب‌های مختلف گزینه‌های -l و -R کنترل می‌شوند.

فهرست‌بندی ساده (SIMPLE LISTING)

یک فهرست‌بندی ساده شبیه دستور معمول ls(1) است:

 $ virt-ls -d guest /
 bin
 boot
 [etc.]
با گزینهٔ -l (--long)، خروجی مشابه دستور "ls -l"
خواهد بود (به‌طور دقیق‌تر، مانند تابع "guestfs_ll").

$ virt-ls -l -d guest /
total 204
dr-xr-xr-x.   2 root root   4096 2009-08-25 19:06 bin
dr-xr-xr-x.   5 root root   3072 2009-08-25 19:06 boot
[etc.]

توجه داشته باشید هرچند این قابلیت برای نمایش یک دایرکتوری سودمند است، اما سعی نکنید این خروجی را در برنامه‌ای دیگر پردازش کنید. در عوض از «فهرست‌بندی تفصیلی بازگشتی (RECURSIVE LONG LISTING)» استفاده کنید.

فهرست‌بندی بازگشتی (RECURSIVE LISTING)

با گزینهٔ -R (--recursive)، دستور "virt-ls" نام‌های فایل‌ها و دایرکتوری‌ها را به‌صورت بازگشتی فهرست می‌کند:

$ virt-ls -R -d guest /tmp
foo
foo/bar
[etc.]

برای تولید این خروجی، "virt-ls" تابع "guestfs_find0" را اجرا کرده و نویسه‌های "\0" را به "\n" تبدیل می‌کند.

فهرست‌بندی تفصیلی بازگشتی (RECURSIVE LONG LISTING)

استفادهٔ هم‌زمان از گزینه‌های -lR خروجی را به‌گونه‌ای تغییر می‌دهد که دایرکتوری‌ها را به‌طور بازگشتی، همراه با مشخصات آماری فایل‌ها و به‌صورت اختیاری ویژگی‌های دیگری مانند مجموع مقابله‌ای (checksum) و خصیصه‌های گسترش‌یافته (extended attributes) نمایش دهد.

بیشتر ویژگی‌های کاربردی "virt-ls" تنها هنگام استفاده از حالت -lR در دسترس هستند.

فیلدها معمولاً با فاصله از هم جدا می‌شوند. نام‌فایل‌ها درون گیومه قرار نمی‌گیرند، بنابراین نمی‌توانید از خروجی در برنامهٔ دیگری استفاده کنید (زیرا نام‌فایل‌ها می‌توانند حاوی فاصله و دیگر نویسه‌های ناامن باشند). اگر ماشین مهمان غیرقابل‌اعتماد باشد و فردی بداند که شما از "virt-ls" برای تحلیل آن استفاده می‌کنید، می‌تواند با ساختن نام‌فایل‌هایی حاوی نویسه‌های خط جدید (newline)، شما را فریب دهد. برای پردازش امن خروجی در برنامه‌ای دیگر، از گزینهٔ --csv (مقادیر جداشده با کاما) استفاده کنید.

توجه داشته باشید که این قالب خروجی کاملاً با دستور "ls -lR" متفاوت و بی‌ارتباط است.

$ virt-ls -lR -d guest /bin
d 0555       4096 /bin
- 0755        123 /bin/alsaunmute
- 0755      28328 /bin/arch
l 0777          4 /bin/awk -> gawk
- 0755      27216 /bin/basename
- 0755     943360 /bin/bash
[etc.]

این فیلدهای اولیه همواره نمایش داده می‌شوند:

type: نوع فایل، یکی از موارد زیر: "-" (فایل عادی)، "d" (دایرکتوری)، "c" (دستگاه نویسه‌ای)، "b" (دستگاه بلوکی)، "p" (پایپ نام‌گذاری‌شده)، "l" (پیوند نمادین)، "s" (سوکت) یا "u" (ناشناخته).
permissions: مجوزهای Unix، که به‌صورت یک عدد ۴ رقمی در مبنای هشت نمایش داده می‌شوند.
size: اندازهٔ فایل. این مقدار به بایت نشان داده می‌شود، مگر اینکه گزینهٔ -h یا --human-readable مشخص شده باشد که در آن صورت به‌صورت عددی خوانا برای انسان نمایش داده خواهد شد.
path: مسیر کامل فایل یا دایرکتوری.
link: تنها برای پیوندهای نمادین، مقصد پیوند.

در حالت -lR، گزینه‌های اضافی خط فرمان امکان نمایش فیلدهای بیشتری را فراهم می‌کنند.

با پرچم --uids، این فیلدهای اضافی پیش از مسیر نمایش داده می‌شوند:

uid
gid: شناسهٔ UID و GID مالک فایل (به‌صورت عددی نمایش داده می‌شوند). توجه داشته باشید این مقادیر تنها در بستر یک مهمان شبه‌یونیکس معنادار هستند.

با پرچم --times، این فیلدهای اضافی نمایش داده می‌شوند:

atime: زمان آخرین دسترسی.
mtime: زمان آخرین تغییر محتوا.
ctime: زمان آخرین تغییر وضعیت.

فیلدهای زمانی به‌صورت تاریخ و ساعت رشته‌ای نمایش داده می‌شوند، مگر اینکه یکی از پرچم‌های --time-t، --time-relative یا --time-days داده شده باشد.

با پرچم --extra-stats، این فیلدهای اضافی نمایش داده می‌شوند:

device: دستگاهی که فایل را در بر دارد (به‌صورت major:minor نمایش می‌یابد). این ممکن است با دستگاه‌هایی که سیستم مهمان می‌شناسد مطابقت نداشته باشد.
inode: شمارهٔ inode.
nlink: تعداد پیوندهای سخت (hard links).
rdev: برای فایل‌های ویژهٔ بلوکی و نویسه‌ای، دستگاه (به‌صورت major:minor نمایش می‌یابد).
blocks: تعداد بلوک‌های ۵۱۲ بایتی تخصیص‌یافته به فایل.

با پرچم --checksum، مجموع مقابله‌ای محتویات فایل نمایش داده می‌شود (تنها برای فایل‌های عادی). محاسبهٔ مجموع مقابله‌ای فایل‌ها می‌تواند زمان قابل‌توجهی ببرد..SH "گزینه‌ها (OPTIONS)"

--help

نمایش راهنمای کوتاه.

-a file

--add file

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

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

-a URI

--add URI

افزودن یک دیسک دوردست. بخش «ADDING REMOTE STORAGE» را در guestfish(1) ببینید.

--blocksize=512

--blocksize=4096

--blocksize

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

--checksum

--checksum=crc|md5|sha1|sha224|sha256|sha384|sha512

نمایش چِک‌سام روی محتویات فایل برای فایل‌های عادی. بدون آرگومان، پیش‌فرض استفاده از md5 است. با ارائهٔ یک آرگومان، می‌توانید نوع چک‌سام مورد استفاده را انتخاب کنید.

این گزینه تنها در حالت خروجی -lR اثر دارد. بخش «RECURSIVE LONG LISTING» را در بالا ببینید.

-c URI

--connect URI

در صورت استفاده از libvirt، به URI ارائه‌شده متصل می‌شود. در صورت عدم ذکر، اتصال به هایپروایزر پیش‌فرض libvirt برقرار می‌شود.

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

--csv

نوشتن نتایج در قالب CSV (مقادیر جداشده با کاما). این قالب می‌تواند به‌راحتی در پایگاه‌های داده و صفحات گسترده وارد شود، اما بخش «NOTE ABOUT CSV FORMAT» را در ادامه بخوانید.

-d guest

--domain guest

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

--echo-keys

هنگام درخواست کلیدها و عبارات عبور، virt-ls معمولاً بازتاب ورودی را غیرفعال می‌کند تا نتوانید آنچه تایپ می‌کنید را ببینید. اگر نگران حملات Tempest نیستید و کس دیگری در اتاق نیست، می‌توانید این پرچم را تعیین کنید تا آنچه تایپ می‌کنید را ببینید.

--extra-stats

نمایش آمارهای اضافی.

این گزینه تنها در حالت خروجی -lR اثر دارد. بخش «RECURSIVE LONG LISTING» را در بالا ببینید.

--format=raw|qcow2|..

--format

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

برای مثال:

virt-ls --format=raw -a disk.img /dir

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

virt-ls --format=raw -a disk.img --format -a another.img /dir

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

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

-h

--human-readable

نمایش اندازهٔ فایل‌ها در قالبی خوانا برای انسان.

این گزینه تنها در حالت خروجی -lR اثر دارد. بخش «RECURSIVE LONG LISTING» را در بالا ببینید.

--key SELECTOR

تعیین کلید برای LUKS، جهت بازگشایی خودکار دستگاه LUKS هنگام استفاده از بازرسی (inspection).

--key NAME:key:KEY_STRING
--key UUID:key:KEY_STRING
--key all:key:KEY_STRING: "NAME" نام دستگاه در libguestfs است (مانند "/dev/sda1"). عبارت "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 است.

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

-m dev[:mountpoint[:options[:fstype]]]

--mount dev[:mountpoint[:options[:fstype]]]

پارتیشن یا حجم منطقیِ (logical volume) نام‌برده را روی نقطهٔ اتصال (mountpoint) داده‌شده سوار (mount) می‌کند.

اگر نقطهٔ اتصال ذکر نشود، مقدار پیش‌فرض / خواهد بود.

مشخص کردن هر نقطهٔ اتصالی، بازرسی ماشین مهمان و سوار کردن ریشهٔ آن و تمام نقاط اتصالش را غیرفعال می‌کند؛ بنابراین اطمینان حاصل کنید که تمام نقاط اتصال لازم برای کار با نام فایل‌های ارائه‌شده به عنوان آرگومان را سوار کرده‌اید.

اگر نمی‌دانید یک ایمیج دیسک شامل چه سیستم‌های فایلی است، می‌توانید guestfish را بدون این گزینه اجرا کرده و پارتیشن‌ها، سیستم‌های فایل و LVهای موجود را فهرست کنید (دستورهای "list-partitions"، "list-filesystems" و "lvs" را ببینید)، یا از برنامهٔ virt-filesystems(1) استفاده نمایید.

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

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

استفاده از این پرچم معادل استفاده از دستور "mount-options" است.

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

انتخاب حالت. بدون هیچ‌یک از این گزینه‌ها، "virt-ls" یک فهرست ساده و تخت از فایل‌های موجود در دایرکتوری نام‌برده تولید می‌کند. بخش "SIMPLE LISTING" را ببینید.

دستور "virt-ls -l" یک «فهرست‌بندی بلند» تولید می‌کند که جزئیات بیشتری را نشان می‌دهد. بخش "LONG LISTING" را ببینید.

دستور "virt-ls -R" یک فهرست بازگشتی از فایل‌ها را با شروع از دایرکتوری نام‌برده تولید می‌کند. بخش "RECURSIVE LISTING" را ببینید.

دستور "virt-ls -lR" یک فهرست‌بندی بلندِ بازگشتی تولید می‌کند که تجزیه (parse) کردن آن ساده‌تر است. بخش "RECURSIVE LONG LISTING" را ببینید.

--times

نمایش فیلدهای زمان.