
=head1 НАЗВА

virt-ls — програма для показу списку файлів у віртуальній машині

=head1 КОРОТКИЙ ОПИС

 virt-ls [--параметри] -d назва_домену каталог [каталог ...]

 virt-ls [--параметри] -a диск.img [-a диск.img ...] каталог [каталог ...]

Старий стиль:

 virt-ls [--параметри] назва_домену каталог

 virt-ls [--параметри] диск.img [диск.img ...] каталог

=head1 ОПИС

C<virt-ls> lists filenames, file sizes, checksums, extended attributes and
more from a virtual machine or disk image.

Multiple directory names can be given, in which case the output from each is
concatenated.

To list directories from a libvirt guest use the I<-d> option to specify the
name of the guest.  For a disk image, use the I<-a> option.

C<virt-ls> can do many simple file listings.  For more complicated cases you
may need to use L<guestfish(1)>, or write a program directly to the
L<guestfs(3)> API.

=head1 ПРИКЛАДИ

Отримати список всіх файлів і каталогів у віртуальній машині:

 virt-ls -R -d guest /

Показати список всіх програм з setuid або setgid у віртуальній машині Linux:

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

Показати список всіх каталогів з відкритим для всіх доступом на запис у
віртуальній машині Linux:

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

Показати список всіх сокетів доменів Unix у віртуальній машині Linux:

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

Показати список всіх звичайних файлів, назви яких завершуються на «.png»:

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

Щоб переглянути список файлів у домашніх каталогах, розмір яких перевищує 10
МБ:

 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'

=head2 DIFFERENCES IN SNAPSHOTS AND BACKING FILES

Although it is possible to use virt-ls to look for differences, since
libguestfs E<ge> 1.26 a new tool is available called L<virt-diff(1)>.

=head1 РЕЖИМИ ВИВЕДЕННЯ ДАНИХ

C<virt-ls> has four output modes, controlled by different combinations of
the I<-l> and I<-R> options.

=head2 ПРОСТИЙ СПИСОК

Простий список, подібний до списку звичайної команди L<ls(1)>:

 $ virt-ls -d guest /
 bin
 boot
 [тощо]

=head2 ДОВГИЙ СПИСОК

With the I<-l> (I<--long>) option, the output is like the C<ls -l> command
(more specifically, like the C<guestfs_ll> function).

 $ 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
 [тощо]

Note that while this is useful for displaying a directory, do not try
parsing this output in another program.  Use L</RECURSIVE LONG LISTING>
instead.

=head2 РЕКУРСИВНИЙ СПИСОК

With the I<-R> (I<--recursive>) option, C<virt-ls> lists the names of files
and directories recursively:

 $ virt-ls -R -d guest /tmp
 foo
 foo/bar
 [тощо]

To generate this output, C<virt-ls> runs the C<guestfs_find0> function and
converts C<\0> characters to C<\n>.

=head2 РЕКУРСИВНИЙ ДОВГИЙ СПИСОК

Using I<-lR> options together changes the output to display directories
recursively, with file stats, and optionally other features such as
checksums and extended attributes.

Most of the interesting features of C<virt-ls> are only available when using
I<-lR> mode.

The fields are normally space-separated.  Filenames are B<not> quoted, so
you cannot use the output in another program (because filenames can contain
spaces and other unsafe characters).  If the guest was untrusted and someone
knew you were using C<virt-ls> to analyze the guest, they could play tricks
on you by creating filenames with embedded newline characters.  To B<safely>
parse the output in another program, use the I<--csv> (Comma-Separated
Values) option.

Note that this output format is completely unrelated to the C<ls -lR>
command.

 $ 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
 [тощо]

Ці основні поля буде показано завжди:

=over 4

=item тип

The file type, one of: C<-> (regular file), C<d> (directory), C<c>
(character device), C<b> (block device), C<p> (named pipe), C<l> (symbolic
link), C<s> (socket) or C<u> (unknown).

=item права доступу

The Unix permissions, displayed as a 4 digit octal number.

=item розмір

The size of the file.  This is shown in bytes unless I<-h> or
I<--human-readable> option is given, in which case this is shown as a
human-readable number.

=item шлях

Шлях до файла або каталогу повністю.

=item посилання

Лише для символічних посилань, призначення посилання.

=back

In I<-lR> mode, additional command line options enable the display of more
fields.

With the I<--uids> flag, these additional fields are displayed before the
path:

=over 4

=item uid

=item gid

The UID and GID of the owner of the file (displayed numerically).  Note
these only make sense in the context of a Unix-like guest.

=back

With the I<--times> flag, these additional fields are displayed:

=over 4

=item atime

Час останнього доступу.

=item mtime

Час останнього внесення змін.

=item ctime

Час останньої зміни стану.

=back

The time fields are displayed as string dates and times, unless one of the
I<--time-t>, I<--time-relative> or I<--time-days> flags is given.

With the I<--extra-stats> flag, these additional fields are displayed:

=over 4

=item пристрій

The device containing the file (displayed as major:minor).  This may not
match devices as known to the guest.

=item inode

Номер inode.

=item nlink

Кількість жорстких посилань.

=item rdev

For block and char special files, the device (displayed as major:minor).

=item блоки

Кількість 512-байтових блоків, виділених під файл.

=back

With the I<--checksum> flag, the checksum of the file contents is shown
(only for regular files).  Computing file checksums can take a considerable
amount of time.

=head1 ПАРАМЕТРИ

=over 4

=item B<--help>

Показати коротку довідку.

=item B<-a> файл

=item B<--add> файл

Add I<file> which should be a disk image from a virtual machine.  If the
virtual machine has multiple block devices, you must supply all of them with
separate I<-a> options.

Формат образу диска визначається автоматично. Щоб перевизначити його і
примусово використати певний формат, скористайтеся параметром
I<--format=..>.

=item B<-a адреса>

=item B<--add адреса>

Додати віддалений диск. Див. L<guestfish(1)/ДОДАВАННЯ ВІДДАЛЕНОГО СХОВИЩА>.

=item B<--checksum>

=item B<--checksum=crc|md5|sha1|sha224|sha256|sha384|sha512>

Display checksum over file contents for regular files.  With no argument,
this defaults to using I<md5>.  Using an argument, you can select the
checksum type to use.

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<-c> адреса

=item B<--connect> адреса

Якщо використовується libvirt, встановити з’єднання з вказаним I<URI>. Якщо
пропущено, з’єднання буде встановлено з типовим гіпервізором libvirt.

Якщо вказати блокові пристрої гостьових систем безпосередньо (I<-a>),
libvirt не буде використовуватися взагалі.

=item B<--csv>

Write out the results in CSV format (comma-separated values).  This format
can be imported easily into databases and spreadsheets, but read L</NOTE
ABOUT CSV FORMAT> below.

=item B<-d> гість

=item B<--domain> гість

Додати всі диски з вказаної гостьової системи libvirt. UUID доменів можна
використовувати замість назв.

=item B<--echo-keys>

When prompting for keys and passphrases, virt-ls normally turns echoing off
so you cannot see what you are typing.  If you are not worried about Tempest
attacks and there is no one else in the room you can specify this flag to
see what you are typing.

=item B<--extra-stats>

Показати додаткові дані.

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<--format=raw|qcow2|..>

=item B<--format>

Типовим значенням для параметра I<-a> є автоматичне визначення формату
образу диска. Використання цього параметра примусово визначає значення
параметрів I<-a> формату диска у наступному рядку команди. Використання
параметра I<--format> без аргументу перемикає програму у режим автоматичного
визначення у наступних параметрах I<-a>.

Приклад:

 virt-ls --format=raw -a диск.img /каталог

примусове встановлення формату без обробки (без автоматичного визначення)
для F<disk.img>.

 virt-ls --format=raw -a диск.img --format -a інший_диск.img /каталог

примусове встановлення формату без обробки (без автоматичного визначення)
для F<diskimg> і повернення до автоматичного визначення для F<another.img>.

Якщо ви користуєтеся ненадійними образами гостьових систем у необробленому
форматі, вам слід скористатися цим параметром для визначення формату
диска. Таким чином можна уникнути можливих проблем з захистом для
сформованих зловмисниками гостьових систем (CVE-2010-3851).

=item B<-h>

=item B<--human-readable>

Показати розміри файлів у зручному для читання форматі.

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<--keys-from-stdin>

Read key or passphrase parameters from stdin.  The default is to try to read
passphrases from the user by opening F</dev/tty>.

=item B<-m> dev[:mountpoint[:options[:fstype]]]

=item B<--mount> dev[:mountpoint[:options[:fstype]]]

Змонтувати названий розділ або логічний том до вказаної точки монтування.

If the mountpoint is omitted, it defaults to F</>.

Specifying any mountpoint disables the inspection of the guest and the mount
of its root and all of its mountpoints, so make sure to mount all the
mountpoints needed to work with the filenames given as arguments.

If you don't know what filesystems a disk image contains, you can either run
guestfish without this option, then list the partitions, filesystems and LVs
available (see L</list-partitions>, L</list-filesystems> and L</lvs>
commands), or you can use the L<virt-filesystems(1)> program.

The third (and rarely used) part of the mount parameter is the list of mount
options used to mount the underlying filesystem.  If this is not given, then
the mount options are either the empty string or C<ro> (the latter if the
I<--ro> flag is used).  By specifying the mount options, you override this
default choice.  Probably the only time you would use this is to enable ACLs
and/or extended attributes if the filesystem can support them:

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

Using this flag is equivalent to using the C<mount-options> command.

The fourth part of the parameter is the filesystem driver to use, such as
C<ext3> or C<ntfs>. This is rarely needed, but can be useful if multiple
drivers are valid for a filesystem (eg: C<ext2> and C<ext3>), or if
libguestfs misidentifies a filesystem.

=item B<-l>

=item B<--long>

=item B<-R>

=item B<--recursive>

Select the mode.  With neither of these options, C<virt-ls> produces a
simple, flat list of the files in the named directory.  See L</SIMPLE
LISTING>.

C<virt-ls -l> produces a "long listing", which shows more detail.  See
L</LONG LISTING>.

C<virt-ls -R> produces a recursive list of files starting at the named
directory.  See L</RECURSIVE LISTING>.

C<virt-ls -lR> produces a recursive long listing which can be more easily
parsed.  See L</RECURSIVE LONG LISTING>.

=item B<--times>

Показати поля часу.

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<--time-days>

Показувати поля часу у форматі днів до поточного (від’ємні значення для днів
у майбутньому).

Зауважте, що C<0> у виведених даних означає «менше 1 одного дня до поточного
моменту» або «вік файла — від 0 до 86399 секунд».

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<--time-relative>

Показувати поля часу у форматі секунд до поточного моменту (від’ємні
значення для часу у майбутньому).

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<--time-t>

Показувати поля часу у форматі секунд з моменту початку епохи UNIX.

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<--uids>

Показати поля UID і GID.

This option only has effect in I<-lR> output mode.  See L</RECURSIVE LONG
LISTING> above.

=item B<-v>

=item B<--verbose>

Увімкнути докладний показ повідомлень з метою діагностики.

=item B<-V>

=item B<--version>

Показати дані щодо версії і завершити роботу.

=item B<-x>

Увімкнути трасування викликів програмного інтерфейсу libguestfs.

=back

=head1 ПАРАМЕТРИ КОМАНДНОГО РЯДКА У ФОРМАТІ ПОПЕРЕДНІХ ВЕРСІЙ

У попередніх версіях virt-ls можна було використовувати або

 virt-ls диск.img [диск.img ...] /каталог

або

 virt-ls назва_гостьової_системи /каталог

whereas in this version you should use I<-a> or I<-d> respectively to avoid
the confusing case where a disk image might have the same name as a guest.

З міркувань зворотної сумісності передбачено підтримку запису параметрів у
застарілому форматі.

=head1 ЗАУВАЖЕННЯ ЩОДО ФОРМАТУ CSV

Comma-separated values (CSV) is a deceptive format.  It I<seems> like it
should be easy to parse, but it is definitely not easy to parse.

Myth: Just split fields at commas.  Reality: This does I<not> work
reliably.  This example has two columns:

 "foo,bar",baz

Myth: Read the file one line at a time.  Reality: This does I<not> work
reliably.  This example has one row:

 "foo
 bar",baz

For shell scripts, use C<csvtool> (L<https://github.com/Chris00/ocaml-csv>
also packaged in major Linux distributions).

For other languages, use a CSV processing library (eg. C<Text::CSV> for Perl
or Python's built-in csv library).

Most spreadsheets and databases can import CSV directly.

=head1 СТАН ВИХОДУ

Ця програма повертає значення 0 у разі успішного завершення і ненульове
значення, якщо сталася помилка.

=head1 ТАКОЖ ПЕРЕГЛЯНЬТЕ

L<guestfs(3)>, L<guestfish(1)>, L<virt-cat(1)>, L<virt-copy-out(1)>,
L<virt-diff(1)>, L<virt-tar-out(1)>, L<http://libguestfs.org/>.

=head1 АВТОР

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

=head1 АВТОРСЬКІ ПРАВА

Copyright (C) 2009-2017 Red Hat Inc.

