guestmount(1)

НАЗВА
guestmount — монтування файлової системи гостьової операційної системи у основній системі за допомогою FUSE і libguestfs

КОРОТКИЙ ОПИС
 guestmount [--параметри] -a диск.img -m пристрій [--ro] точка монтування

 guestmount [--параметри] -a диск.img -i [--ro] точка_монтування

 guestmount [--параметри] -d Гостьова_система -i [--ro] точка_монтування

ОПИС
Програмою guestmount можна скористатися для монтування файлових систем віртуальної машини та інших образів дисків у основній системі. Програма використовує libguestfs для доступу до гостьової файлової системи і FUSE («файлову систему у просторі користувача») так, що змонтована система з'являється у основній системі як додатковий змонтований пристрій.

Along with other options, you have to give at least one device (-a option) or libvirt domain (-d option), and at least one mountpoint (-m option) or use the -i inspection option. How this works is better explained in the guestfish(1) manual page, or by looking at the examples below.

FUSE надає вам змогу монтувати файлові системи від імені звичайного користувача. Власником точки монтування має бути ваш користувач. Файлова система лишатиметься невидимою для усіх інших користувачів, якщо ви не внесете змін до налаштувань. Див. "ПРИМІТКИ" нижче.

Для демонтування файлової системи скористайтеся програмою guestunmount(1).

ПРИКЛАДИ
Для типової гостьової системи Windows, основна файлова система якої розміщується на першому розділі:

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

Для типової гостьової системи Linux із файловою системою /boot на першому розділі і кореневою файловою системою на логічному томі:

 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), інші користувачі типово не зможуть її бачити. Щоб виправити цей недолік, додайте під час монтування параметр "allow_other" FUSE:

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

та для вмикання цього параметра у /etc/fuse.conf.

  Вмикання FUSE
У деяких дистрибутивах користувача потрібно додати до спеціальної групи (наприклад "fuse"), перш ніж він зможе користуватися файловими системами FUSE. Так, зокрема, влаштовано систему доступу у Debian та похідних від нього дистрибутивах.

У інших дистрибутивах, зокрема Fedora та Red Hat Enterprise Linux, членство у групі не є обов'язковим.

  Помилка fusermount: «Device or resource busy»
Ви можете побачити це повідомлення про помилку, коли інший процес у системі починає використовувати щойно створену вами точку монтування, утримуючи її відкритою і заважаючи вам її демонтувати. Звичними «винуватцями» таких проблем є різноманітні програми для індексування даних.

Популярним способом обійти цю проблему є повторні спроби виконати "fusermount -u" декілька разів, аж доки потрібну дію не буде виконано (guestunmount(1) робити це за вас). На жаль, цей спосіб не є універсальним. Він не спрацює, якщо, наприклад, змонтована файлова система є доволі великою Unfortunately this isn't a reliable fix if (for example) the mounted filesystem is particularly large and the intruding program particularly persistent.

Належним вирішенням є використання приватної точки монтування шляхом створення простору назв монтування за допомогою специфічного для Linux прапорця clone(2)/unshare(2) "CLONE_NEWNS". На жаль, у поточній версії це потребує прав доступу root. Крім того, нам, ймовірно, потрібно буде додати цю можливість до guestmount.

  Під час розірвання з'єднання можливий конфлікт через конкуренцію потоків обробки
Коли guestunmount(1)/fusermount(1) завершує роботу, guestmount усе ще може працювати над вилученням точки монтування. Образ диска у такому випадку може вийти незавершеним.

Це означає, що скрипти, подібні до наведеного нижче, містять небезпечний потенційний конфлікт потоків обробки через конкуренцію:

 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

 # ...
 # ...

 # Зберегти PID 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" безпосередньо (див. "ЛОКАЛЬНЕ МОНТУВАННЯ" in guestfs(3)), набагато простіше буде написати безпечну, позбавлену конфліктів програму.

ПАРАМЕТРИ

-a ОБРАЗ
--add ОБРАЗ
    Додати блоковий пристрій або образ віртуальної машини.

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

-a адреса
--add адреса
    Додати віддалений диск. Див. "ДОДАВАННЯ ВІДДАЛЕНОГО СХОВИЩА" in guestfish(1).

--blocksize=512
--blocksize=4096
--blocksize
    Цей параметр встановлює розмір сектора образу диска. Ви стосується усіх явним чином доданих після цього параметра дисків. Використання --blocksize без аргументів перемикає розмір сектора диска на типове значення, яким, зазвичай, є 512 байтів. Див. також "guestfs_add_drive_opts" in guestfs(3).

-c адреса
--connect адреса
    Якщо використано у поєднанні із параметром -d, визначає адресу libvirt, якою слід скористатися. Типово, використовується типове з'єднання libvirt.

-d ДОМЕН_LIBVIRT
--domain ДОМЕН_LIBVIRT
    Додати диски із названого домену libvirt. Якщо також використано параметр --ro, може бути використано будь-який домен libvirt. Втім, у режимі запису тут можна вказати лише домени libvirt, які вимкнено.

    Замість назв можна використовувати UUID доменів.

--dir-cache-timeout N
    Встановити час застарівання кешу readdir у значення N секунд. Типовим значенням є 60 секунд. Кеш readdir [насправді, існує декілька напівнезалежних кешів] заповнюється після виклику readdir(2) статистикою і розширеними атрибутами файлів у каталозі у сподіванні, що вони невдовзі знову знадобляться.

    Існує також інший кеш атрибутів, реалізований за допомогою FUSE (див. параметр FUSE -o attr_timeout), але кеш FUSE не розрахований на наступні виклики — його призначено лише для кешування наявних.

--echo-keys
    Типово, якщо guestfish попросить вас ввести ключ або пароль, програма не відтворюватиме введені символи на екрані. Якщо ви не боїтеся TEMPEST-нападів, або у вашій кімнаті нікого, окрім вас, немає, ви можете скористатися цим прапорцем, щоб бачити, які саме символи ви вводите.

--fd=ДФ
    Вказати канал або дескриптор файла eventfd. Коли точка монтування буде готова до використання, guestmount запише один байт до цього дескриптора файла. Цим можна скористатися, у поєднанні із --no-fork, щоб запустити guestmount у межах іншого процесу.

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

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

--fuse-help
    Вивести довідку щодо спеціальних параметрів FUSE (див. -o нижче).

--help
    Показати короткі довідкові дані і завершити роботу.

-i
--inspector
    Використовуючи код virt-inspector(1), виконати інспектування дисків, шукаючи операційну систему і монтуючи файлові системи так, як їх мало б бути змонтовано у справжній віртуальній машині.

--key ВАРІАНТ
    Specify a key for LUKS, to automatically open a LUKS device when using the inspection.

    --key NAME:key:KEY_STRING
    --key UUID:key:KEY_STRING
    --key all:key:KEY_STRING
        "NAME" is the libguestfs device name (eg. "/dev/sda1"). "UUID" is the device UUID. "all" means try the key against any encrypted device.

        Використовувати вказаний "РЯДОК_КЛЮЧА" як пароль.

    --key NAME:file:FILENAME
    --key UUID:file:FILENAME
    --key all:file:FILENAME
        Прочитати пароль з файла НАЗВА_ФАЙЛА.

    --key NAME:clevis
    --key UUID:clevis
    --key all:clevis
        Attempt passphrase-less unlocking for the device with Clevis, over the network. Please refer to "ENCRYPTED DISKS" in guestfs(3) for more information on network-bound disk encryption (NBDE).

        Note that if any such option is present on the command line, QEMU user networking will be automatically enabled for the libguestfs appliance.

--keys-from-stdin
    Прочитати параметри ключа або пароля із джерела стандартного введення. Типово програма намагається читати паролі від користувача відкриттям /dev/tty.

    If there are multiple encrypted devices then you may need to supply multiple keys on stdin, one per line.

-m пристрій[:точка_монтування[:параметри[:тип_файлової_системи]]]
--mount пристрій[:точка_монтування[:параметри[:тип_файлової_системи]]]
    Змонтувати вказаний за назвою розділ або логічний том до вказаної точки монтування у гостьовій системі (немає нічого спільного із точками монтування у основній системі).

    Якщо точку монтування не вказано, типовим значенням є /. Вам слід змонтувати щось до /.

    Третьою (і нечасто використовуваною) частиною параметра монтування є список параметрів монтування, які використовуються для того, щоб змонтувати підлеглу файлову систему. Якщо такий список не буде задано, параметрами монтування вважатиметься або порожній рядок, або "ro" (другий варіант використовується, якщо використано прапорець --ro). Заданням параметрів монтування ви перевизначаєте типовий варіант. Ймовірно, єдиним випадком, коли вам може знадобитися це, є випадок вмикання списків керування доступом (ACL) і/або розширених атрибутів, якщо у файловій системі передбачено їхню підтримку:

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

    Четвертою частиною параметра є назва драйвера файлової системи, якою слід скористатися, зокрема "ext3" або "ntfs". У визначенні цієї частини параметра рідко виникає потреба, але вона може бути корисною, якщо для файлової системи можна скористатися декількома драйверами (приклад: "ext2" і "ext3"), або libguestfs визначає файлову систему помилково.

--no-fork
    Не створювати фонової служби (або відгалуження у фоновий режим).

-n
--no-sync
    Типово, під час демонтування точки монтування FUSE буде виконано спробу синхронізувати диск гостьової операційної системи. Якщо ви вкажете цей параметр, спроби синхронізуватися не виконуватиметься. Див. обговорення автоматичної синхронізації на сторінці підручника guestfs(3).

-o ПАРАМЕТР
--option ПАРАМЕТР
    Передати додаткові параметри FUSE.

    Щоб отримати список усіх додаткових параметрів, підтримку яких передбачено у FUSE, скористайтеся наведеною нижче командою. Зауважте, що можна передавати лише параметри FUSE -o і що лише деякі з них варто насправді передавати.

     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 створюватиме власні номери inode. Номери inode, які ви зазвичай бачите у stat(2), "ls -i" тощо, не є номерами inode у базовій файловій системі.

        Зауваження: використання цього параметра є потенційно небезпечним, якщо у базова файлова система складається з декількох точок монтування, оскільки у такому випадку можливе дублювання номерів inode через FUSE. Використання цього параметра може призвести до неналежної роботи частини програм.

--pid-file НАЗВА_ФАЙЛА
    Записати PID робочого процесу guestmount до файла "назва_файла".

-r
--ro
    Додавати пристрої і монтування лише у режимі читання. Це заборонить запис, а диск у FUSE буде показано як придатний лише до читання.

    Наполегливо рекомендуємо скористатися цим параметром, якщо ви не маєте намірів щодо редагування диска гостьової системи. Якщо гостьова система працює, а цей параметр не вказано, існує дуже висока ймовірність пошкодити дані на диску. Ми намагаємося запобігати такому пошкодженню, але це не завжди можливо.

    Див. також "OPENING DISKS FOR READ AND WRITE" in guestfish(1).

--selinux
    Цей параметр призначено для забезпечення зворотної сумісності, його використання не матиме жодних наслідків.

-v
--verbose
    Уможливити докладні повідомлення від підлеглої частини libguestfs.

-V
--version
    Показати дані щодо версії програми, потім вийти.

-w
--rw
    Змінює дію параметрів -a, -d і -m таким чином, що диски додаються і монтуються у режимі читання і запису.

    Див. "OPENING DISKS FOR READ AND WRITE" in guestfish(1).

-x
--trace
    Трасувати виклики 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), "ЛОКАЛЬНЕ МОНТУВАННЯ" 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.

LICENSE
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

BUGS
To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

•   The version of libguestfs.

•   Where you got libguestfs (eg. which Linux distro, compiled from source, etc)

•   Describe the bug accurately and give a way to reproduce it.

•   Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report.