# VBoxManage guestcontrol

VBoxManage-guestcontrol

1

VBoxManage-guestcontrol

управляет виртуальной машиной из хост-системы

&product-name;

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          run
          --domain=имя-домена
          --dos2unix
          --exe=имя-файла
          --ignore-orphaned-processes

            --no-wait-stderr
            --wait-stderr

            --no-wait-stdout
            --wait-stdout

            --passwordfile=файл-с-паролем
            --password=пароль

          --profile
          --putenv=имя-переменной=[значение]
          --quiet
          --timeout=миллисекунды
          --unix2dos
          --unquoted-args
          --username=имя-пользователя
          --verbose
          -- программа/аргумент0 аргумент

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          start
          --domain=имя-домена
          --exe=имя-файла
          --ignore-orphaned-processes

            --passwordfile=файл-с-паролем
            --password=пароль

          --profile
          --putenv=имя-переменной=[значение]
          --quiet
          --timeout=миллисекунды
          --unquoted-args
          --username=имя-пользователя
          --verbose
          -- программа/аргумент0 аргумент

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          copyfrom
          --domain=имя-домена
          --follow

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --no-replace
          --recursive
          --target-directory=хост-директория-назначения
          --update
          --username=имя-пользователя
          --verbose
          гостевой-источник0
          гостевой-источник1 [...]

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          copyto
          --domain=имя-домена
          --follow

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --no-replace
          --recursive
          --target-directory=гостевая-директория-назначения
          --update
          --username=имя-пользователя
          --verbose
          хост-источник0
          хост-источник1 [...]

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          mkdir
          --domain=имя-домена
          --mode=режим
          --parents

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --username=имя-пользователя
          --verbose
          гостевая-директория

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          rmdir
          --domain=имя-домена

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --recursive
          --username=имя-пользователя
          --verbose
          гостевая-директория

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          rm
          --domain=имя-домена
          --force

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --username=имя-пользователя
          --verbose
          гостевая-директория

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          mv
          --domain=имя-домена

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --username=имя-пользователя
          --verbose
          источник
          директория-назначения

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          mktemp
          --directory
          --domain=имя-домена
          --mode=режим

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --secure
          --tmpdir=имя-директории
          --username=имя-пользователя
          --verbose
          имя-шаблона

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          stat
          --domain=имя-домена

            --passwordfile=файл-с-паролем
            --password=пароль

          --quiet
          --username=имя-пользователя
          --verbose
          имя-файла

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          list

            all
            files
            processes
            sessions

          --quiet
          --verbose

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          closeprocess

            --session-id=ID
            --session-name=имя-или-шаблон

          --quiet
          --verbose
          PID

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          closesession

            --all
            --session-id=ID
            --session-name=имя-или-шаблон

          --quiet
          --verbose

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          updatega
          --quiet
          --verbose
          --source=дополнения_гостевой_ос.ISO
          --wait-start
          -- аргумент

          VBoxManage guestcontrol

            uuid
            имя-ВМ

          watch
          --quiet
          --verbose

## Описание

Команда `VBoxManage guestcontrol` позволяет управлять гостевой виртуальной машиной (ВМ) из хост-системы. Смотрите guestadd-guestcontrol.

### Общие опции и операнды

Следующие опции могут быть использованы с любой подкомандой `VBoxManage guestcontrol`:

`uuid`|`имя-ВМ`

- Задает Универсальный Уникальный Идентификатор (UUID) или имя ВМ.

`--quiet`

- Указывает, что команда производит более тихий вывод.

  Краткая форма этой опции `-q`.

`--verbose`

- Указывает, что команда производит более подробный вывод.

  Краткая форма этой опции `-v`.

Некоторые подкоманды `VBoxManage guestcontrol` требуют, чтобы предоставили гостевые учетные данные для идентификации. Эти подкоманды: `copyfrom`, `copyto`, `mkdir`, `mktemp`, `mv`, `rmdir`, `rm`, `run`, `start` и `stat`.

Хотя вы не можете выполнять анонимные операции, пароль учетной записи пользователя не является обязательным и зависит от политики безопасности гостевой ОС. Если у пользователя пароль не установлен, укажите пустой пароль. В ОС, таких как Windows, возможно необходимо подстроить политику безопасности, чтобы разрешить пользовательские учетные записи с пустым паролем. В дополнение, могут применяться глобальные правила домена, и поэтому они не могут быть изменены.

Следующие опции используются для аутентификации в гостевой ВМ:

`--domain=`имя-домена``

- Задает имя домена для гостевых Windows ВМ.

`--password=`пароль``

- Задает пароль указанного пользователя. Если пароль не указан в командной строке или файл с паролем пуст, считается что у пользователя пустой пароль.

`--passwordfile=`имя-файла``

- Задает абсолютный путь к файлу в гостевой ОС, содержащему пароль для указанного пользователя. Если файл с паролем пуст или не указан пароль в командной строке, считается что у пользователя пустой пароль.

`--username=`имя-пользователя``

- Задает существующего пользователя в гостевой ОС, от имени которого запускается процесс. Если не указан, процесс запускается от имени пользователя хоста.

### Ограничения на гостевой процесс

По умолчанию, можно запустить до пяти гостевых процессов одновременно. Если запускается новый гостевой процесс, который превысил этот лимит, старый не выполняющийся процесс удаляется для запуска нового. Вы не сможете получить вывод из удаленного гостевого процесса. Если все пять гостевых процессов активны и выполняются, попытка запустить новый гостевой процесс будет неудачна.

Можно модифицировать ограничения на выполнение гостевого процесса двумя способами:

- Используя команду `VBoxManage setproperty` для обновления значения гостевого свойства `/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept`.

- Используя команду `VBoxService` и указывая опцию `--control-procs-max-kept=`value``.

Необходимо перезагрузить гостевую ОС после изменения ограничения.

Можно обслуживать неограниченное количество гостевых процессов путем указания значения `0`, однако, это не рекомендуется.

### Запуск команды в гостевой виртуальной машине

Команда `VBoxManage guestcontrol `имя-ВМ` run` позволяет исполнять программу в гостевой ВМ. Стандартные потоки ввода, вывода и ошибок перенаправляются из ВМ в хост-систему до завершения программы.

ОС Windows навязывает определенные ограничения на графические приложения. Смотрите known-issues.

`--exe=`путь-до-исполняемого-файла``

- Указывает абсолютный путь к исполняемому файлу для запуска в гостевой ВМ. Например `C:\Windows\System32\calc.exe`.

`--timeout=`миллисекунды``

- Указывает максимальное время в миллисекундах, выделенное для работы программы. Во время работы программы `VBoxManage` получает ее вывод.

  Если не указывается величина ожидания, `VBoxManage` ждет до бесконечности окончания программы или возникновения ошибки.

`--putenv=`имя`=[`значение`]`

- Устанавливает, изменяет или удаляет переменные окружения в окружении гостевой ВМ.

  Когда создается гостевой процесс, он работает в стандартной среде гостевой ОС задаваемой по умолчанию. Используйте эту опцию, чтобы изменить переменные окружения в среде по умолчанию.

  Используйте опцию `--putenv=`имя`=[`значение`]` для установки или изменения переменной окружения указываемой через `имя`.

  Используйте опцию `--putenv=`имя`=[`значения`]` для удаления переменной окружения указанной через `имя`.

  Убедитесь, что переменная или значение, содержащие пробелы должны быть заключены в кавычки.

  Необходимо указать опцию `--putenv` для каждой модифицируемой переменной окружения.

  Краткая форма этой опции `-E`.

`--unquoted-args`

- Отключает экранированные двойные кавычки аргументов, передаваемые программе. Например `\"fred\"`.

`--ignore-orphaned-processes`

- Игнорирует процессы-сироты. Еще не реализовано.

`--profile`

- Использует профиль оболочки, чтобы указать используемое окружение. Еще не реализовано.

`--no-wait-stdout`

- Не ждет завершения гостевого процесса или получения его кода завершения и каких-либо объяснений сбоя.

`--wait-stdout`

- Ждет завершения процесса, чтобы получить его код завершения и любые объяснения сбоя. Команда `VBoxManage` принимает данные со стандартного потока вывода гостевого процесса во время выполнения процесса.

`--no-wait-stderr`

- Не ждет завершения гостевого процесса, чтобы получить его код завершения, сообщения об ошибках и флаги.

`--wait-stderr`

- Ждет завершения гостевого процесса для получения его кода завершения, сообщений об ошибках и флаги. Команда `VBoxManage` принимает данные со стандартного потока ошибок гостевого процесса во время выполнения процесса.

`--dos2unix`

- Преобразует гостевой DOS или Windows вывод в UNIX или Linux вывод. Это преобразование изменяет завершения строк с CR + LF на LF. Еще не реализовано.

`--unix2dos`

- Преобразует гостевой UNIX или Linux вывод в DOS или Windows вывод. Это преобразование изменяет завершения строк с LF на CR + LF.

`-- `программа/аргумент0` [`аргумент`...]`

- Задает имя программы и любые аргументы, передаваемые программе.

  Убедитесь, что все аргументы команды, содержащие пробелы, заключены в кавычки.

### Запуск команды в гостевой виртуальной машине

Команда `VBoxManage guestcontrol `имя-ВМ` start` позволяет выполнить гостевую программу до ее завершения.

ОС Windows навязывает определенные ограничения на графические приложения. Смотрите known-issues.

### Копирование файла из гостевой виртуальной машины в директорию в хост-системы

Команда `VBoxManage guestcontrol `имя-ВМ` copyfrom` позволяет скопировать файл из гостевой ВМ в хост-систему.

`--dereference`

- Включает следование по символическим ссылкам в гостевой файловой системе.

`--no-replace`

- Only copies a file if it does not exist on the host yet.

  The short form of this option is `-n`.

`--recursive`

- Рекурсивно копирует файлы и директории из указанной директории в гостевой ВМ.

  Краткая форма этой опции `-R`.

`--target-directory=`хост-директория-назначения``

- Задает абсолютный путь к директории назначения в хост-системе. Например `C:\Temp`.

`--update`

- Only copies a file if the guest file is newer than on the host.

  The short form of this option is `-u`.

``гостевой-источник0` [`гостевой-источник1` [...]]`

- Задает абсолютный путь одного или нескольких файлов для копирования из гостевой ВМ. Например `C:\Windows\System32\calc.exe`. Можно использовать подстановочные знаки. Например `C:\Windows\System*\*.dll`.

### Копирует файл в директорию на гостевой виртуальной машине из хост-системы

Команда `VBoxManage guestcontrol `имя-ВМ` copyto` позволяет скопировать файл из хост-системы в гостевую ВМ.

`--dereference`

- Включает следование по символическим ссылкам в хост-системе.

`--no-replace`

- Only copies a file if it does not exist on the guest yet.

  The short form of this option is `-n`.

`--recursive`

- Рекурсивно копирует файлы и директории из указанной директории в хост-системе.

  Краткая форма этой опции `-R`.

`--target-directory=`гостевая-директория-назначения``

- Задает абсолютный путь директории назначения в гостевой ВМ. Например `C:\Temp`.

`--update`

- Only copies a file if the host file is newer than on the guest.

  The short form of this option is `-u`.

``хост-источник0` [`хост-источник1` [...]]`

- Задает абсолютный путь одного или нескольких файлов для копирования из хост-системы. Например `C:\Windows\System32\calc.exe`. Можно использовать подстановочные знаки для указания нескольких файлов. Например `C:\Windows\System*\*.dll`.

### Создает директорию в гостевой виртуальной машине

Команда `VBoxManage guestcontrol `имя-ВМ` mkdir` позволяет создать один или несколько директорий в гостевой ВМ.

Альтернативные формы этой подкоманды: `md`, `createdir` и `createdirectory`.

`--parents`

- Создает все отсутствующие родительские директории по отношению к указанной.

  Например, если попытаться создать директорию `D:\Foo\Bar` и директория `D:\Foo` не существует, использование `--parents` создаст отсутствующую директорию `D:\Foo`. Однако, если попытаться создать `D:\Foo\Bar` и не указать опцию `--parents`, команда завершится неудачей.

`--mode=`режим``

- Задает режим разрешений для указанной директории. Если также используется опция `--parents`, этот режим задается также для всех ее родительских директорий. `режим` - это четыре восьмеричные цифры, например `0755`.

``гостевая-директория` [`гостевая-директория`...]`

- Задает абсолютный путь к одной или нескольким директориям для создания в гостевой ВМ. Например `D:\Foo\Bar`.

  Если все относящиеся к указанной родительские директории не существуют в гостевой ВМ, необходимо использовать опцию `--parents`.

  У вас должно быть достаточно прав в гостевой ВМ, чтобы создать указанную и ее родительские директории.

### Удалить директорию из гостевой виртуальной машины

Команда `VBoxManage guestcontrol `имя-ВМ` rmdir` позволяет удалить указанную директорию из гостевой ВМ.

Альтернативные формы этой подкоманды `removedir` и `removedirectory`.

`--recursive`

- Рекурсивно удаляет директории из указанной в гостевой ВМ.

  Краткая форма этой опции `-R`.

``гостевая-директория` [`гостевая-директория`...]`

- Задает абсолютный путь к одной или нескольким директориям для удаления в гостевой ВМ. Можно использовать подстановочные знаки в именах директорий. Например `D:\Foo\*Bar`.

  У вас должно быть достаточно прав в гостевой ВМ, чтобы удалить указанную и ее родительские директории.

### Удалить файл из гостевой виртуальной машины

Команда `VBoxManage guestcontrol `имя-ВМ` rm` позволяет удалить указанный файл из гостевой ВМ.

Альтернативная форма этой подкоманды `removefile`.

`--force`

- Принудительно выполняет операцию и отменяет любые запросы подтверждения.

  Краткая форма этой опции `-f`.

``гостевой-файл` [`гостевой-файл`...]`

- Задает абсолютный путь одного или нескольких файлов для удаления из гостевой ВМ. Можно использовать подстановочные знаки в именах файлов. Например `D:\Foo\Bar\text*.txt`.

  У вас должно быть достаточно прав в гостевой ВМ, чтобы удалить указанный файл.

### Переименовать файл или директорию в гостевой виртуальной машине

Команда `VBoxManage guestcontrol `имя-ВМ` mv` позволяет переименовать файлы и директории в гостевой ВМ.

Альтернативная форма этой подкоманды `move`, `ren` и `rename`.

``гостевой-источник` [`гостевой-источник`...]`

- Задает абсолютный путь к файлу или единичной директории для перемещения или переименования в гостевой ВМ. Можно использовать подстановочные знаки в именах файлов.

  У вас должно быть достаточно прав в гостевой ВМ для доступа к указанному файлу или директории.

`назначение`

- Задает абсолютный путь к переименовываемым файлу или директории, или директории назначения, куда перемещать файлы. Если перемещается только один файл, `назначение` может быть как файлом так и директорией, иначе `назначение` должно быть директорией.

  У вас должно быть достаточно прав в гостевой ВМ для доступа к файлу или директории назначения.

### Создать временный файл или директорию в гостевой виртуальной машине

Команда `VBoxManage guestcontrol `имя-ВМ` mktemp` позволяет создать временный файл или директорию в гостевой ВМ. Можно использовать эту команду для помощи с последующим копированием файлов из хост-системы в гостевую ВМ. По умолчанию, эта команда создает файл или директорию в платформо-зависимой директории `temp` гостевой ВМ.

Альтернативные формы этой подкоманды `createtemp` и `createtemporary`.

`--directory`

- Создает временную директорию указанную в операнде `шаблон`.

`--secure`

- Обеспечивает безопасное создание файлов и каталогов, устанавливая режим разрешений `0755`. Любая операция, которая не может быть произведена безопасно приведет к неудаче.

`--mode=`режим``

- Задает режим разрешений, используемый указанной директорией. `режим` - это четыре восьмеричные цифры, например `0755`.

`--tmpdir=`директория``

- Задает абсолютный путь к директории в гостевой ВМ, где создавать указанный файл или директорию. Если не указан, `директория` - это платформо-зависимая директория `temp`.

`шаблон`

- Задает шаблон имени для временного файла без пути к директории. Шаблон имени файла должен содержать как минимум одну последовательности трех последовательных символов X или должен заканчиваться ими.

### Показать статус файла или файловой системы в гостевой виртуальной машине.

Команда `VBoxManage guestcontrol `имя-ВМ` stat` позволяет отобразить статус файлов или или файловых систем в гостевой ВМ.

``файл` [`файл` ...]`

- Задает абсолютный путь к файлу или файловой системе в гостевой ВМ. Например `/home/foo/a.out`.

  У вас должно быть достаточно прав в гостевой ВМ для доступа к указанным файлам или файловым системам.

### Показать настройки и информацию о статусе гостевой виртуальной машины

Команда `VBoxManage guestcontrol `имя-ВМ` list` позволяет показать настройки гостевого управления и информацию о статусе. Например, вывол показывает открытые гостевые сессии, гостевые процессы и файлы.

`all`|`sessions`|`processes`|`files`

- Указывает тип отображаемой информации. `all` показывает все доступные данные, `sessions` показывает гостевые сессии, `processes` показывает процессы и `files` показывает файлы.

### Завершить процесс в сессии гостевой виртуальной машины

Команда `VBoxManage guestcontrol `имя-ВМ` closeprocess` позволяет завершить гостевой процесс работающий в гостевой сессии. Указывайте процесс через идентификатор процесса (PID) и сессию, используя ID сессии или имя.

`--session-id=`ID``

- Задает ID гостевой сессии.

`--session-name=`имя`|`шаблон``

- Задает имя гостевой сессии. Используйте шаблон, содержащий подстановочные знаки для указания нескольких сессий.

``PID` [`PID` ...]`

- Задает список PID гостевых процессов для завершения.

### Закрыть сессию гостевой виртуальной машины

Команда `VBoxManage guestcontrol `имя-ВМ` closesession` позволяет закрыть гостевую сессию. Указывайте гостевую сессию или через ID сессии или через имя.

`--session-id=`ID``

- Задает ID гостевой сессии.

`--session-name=`имя`|`шаблон``

- Задает имя гостевой сессии. Используйте шаблон, содержащий подстановочные знаки для указания нескольких сессий.

`--all`

- Закрывает все гостевые сессии.

### Обновить ПО Дополнений Гостевой ОС в гостевой виртуальной машине

Команда `VBoxManage guestcontrol `имя-ВМ` updatega` позволяет обновить ПО Дополнений Гостевой ОС, установленное в указанной гостевой ВМ.

Альтернативные формы этой подкоманды `updateadditions` и `updateguestadditions`.

`--source=`новый-путь-к-iso``

- Задает абсолютный путь к `.ISO` файлу Дополнений Гостевой ОС в гостевой ВМ.

`--reboot`

- Автоматический перезагружает гостевую систему после успешного обновления Дополнений Гостевой ОС.

`--timeout=`миллисекунды``

- Задает максимальное время ожидания (в миллисекундах) заверешения полного обновления Дополнений Гостевой ОС. По умолчанию, максимальное время ожидания не используется.

`--verify`

- Проверяет, что Дополнения Гостевой ОС обновлены успешно после успешной установки. Перезагрузка гостя обязательна.

`--wait-ready`

- Ждет когда текущие Дополения Гостевой ОС готовы для обновления Дополений Гостевой ОС.

`--wait-start`

- Запускает `VBoxManage` процесс обновления в гостевой ВМ и ждет начала обновления Дополений Гостевой ОС перед завершения процесса `VBoxManage`.

  По умолчанию, команда `VBoxManage` ждет завершения обновления Дополений Гостевой ОС перед завершением. Используйте эту опцию когда работающий процесс `VBoxManage` влияет на взаимодействие между установщиком и гостевой ОС.

`-- `аргумент` [`аргумент` ...]`

- Задает необязательные аргументы командной строки, которые передаются программе обновления Дополнений Гостевой ОС. Можно использовать опцию `--` для передачи соответствующих аргументов программе обновления для модернизации еще не установленных функций.

  Убедитесь, что командные аргументы, содержащие пробелы, заключены в кавычки.

### Ждать гостевой уровень выполнения

Команда `VBoxManage guestcontrol `имя-ВМ` waitrunlevel` позволяет ожидать достижения гостевого уровня выполнения.

`--timeout=`миллисекунды``

- Задать максимальное время ожидания (в миллисекундах) достижения уровня выполнения. По умолчанию максимальное время ожидания не используется.

``system`|`userland`|`desktop``

- Задает ожидаемый уровень выполнения

### Показать текущую активность гостевого управления.

Команда `VBoxManage guestcontrol `имя-ВМ` watch` позволяет показать текущую активность гостевого управления.

## Примеры

Следующая команда `VBoxManage guestcontrol run` выполняет команду `ls -l /usr` в Oracle Linux ВМ `My OL VM` от имени пользователя `user1`.

    $ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/bin/ls" \
    --username user1 --passwordfile pw.txt --wait-stdout -- -l /usr

Опция `--exe` указывает абсолютный путь команды для запуска в гостевой ВМ, `/bin/ls`. Используйте опцию `--` для передачи любых аргументов, следующих после команды `ls`.

Используйте опцию `--username` для указания имени пользователя, `user1` и опцию `--passwordfile` для указания имения файлы, содержащего пароль для пользователя `user1`, `pw.txt`.

Опция `--wait-stdout` ожидает завершения гостевого процесса `ls` перед передачей кода заверешения и вывода команды. Опция `--nologo` подавляет вывод информации о логотипе.

Следующая команда `VBoxManage guestcontrol run` выполняет команду `ipconfig` в Windows ВМ `My Win VM` от имени пользователя `user1`. Стандартные потоки ввода, вывода и ошибок перенаправляются из ВМ в хост-систему до завершения программы.

    $ VBoxManage --nologo guestcontrol "My Win VM" run \
    --exe "c:\\windows\\system32\\ipconfig.exe" \
    --username user1 --passwordfile pw.txt --wait-stdout

Опция `--exe` задает абсолютный путь команды для запуска в гостевой ВМ, `c:\windows\system32\ipconfig.exe`. Двойные слеши показанные в этом примере требуются только в UNIX хост-системах.

Используйте опцию `--username` для указания имени пользователя, `user1` и опцию `--passwordfile` для указания имени файла, содержащего пароль для пользователя `user1`, `pw.txt`.

Опция `--wait-stdout` ожидает завершения гостевого процесса `ls` перед передачей кода заверешения и вывода команды. Опция `--nologo` подавляет вывод информации о логотипе.

Следующая команда `VBoxManage guestcontrol start` выполняет команду `ls -l /usr` в Oracle Linux ВМ `My OL VM` до завершения программы.

    $ VBoxManage --nologo guestcontrol "My Win VM" start \
    --exe "c:\\windows\\system32\\ipconfig.exe" \
    --username user1 --passwordfile pw.txt --wait-stdout