8.34. VBoxManage guestcontrol

Oracle VM VirtualBox

previous page next page

8.34. VBoxManage guestcontrol

The guestcontrol commands enable control of the guest from the host. Please see Section 4.8, “Guest control” for an introduction.

guestcontrol has two sets of subcommands. The first set requires guest credentials to be specified, the second does not.

The first set of subcommands is of the form:

VBoxManage guestcontrol <uuid|vmname> <sub-command>
            [--username <name> ]
            [--passwordfile <file> | --password <password>]
            [--domain <domain> ]
            [-v|--verbose] [-q|quiet] ...

The "common-options" are:

           [--username <name> ]
           [--passwordfile <file> | --password <password>]
           [--domain <domain> ]
           [-v|--verbose] [-q|quiet]

Where details of the common options for the first set of subcommands are:

<uuid|vmname>: Specifies the VM UUID or VM name. Mandatory.
--username <name>: Specifies the user name on guest OS under which the process should run. This user name must already exist on the guest OS. If unspecified, the host user name is used. Optional
--passwordfile <file>|--password: Specifies the absolute path on guest file system of password file containing the password for the specified user account or password for the specified user account. Optional. If both are omitted, empty password is assumed.
--domain <domain>: User domain for Windows guests. Optional.
-v|--verbose: Makes the subcommand execution more verbose. Optional
-q|--quiet: Makes the subcommand execution quieter. Optional.

The first set of subcommands:

run Executes a guest program - forwarding stdout, stderr and stdin to/from the host until it completes.
```
VBoxManage guestcontrol <uuid|vmname> run [common-options]
            --exe <path to executable> [--timeout <msec>]
           [-E|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
           [--ignore-operhaned-processes] [--profile]
           [--no-wait-stdout|--wait-stdout]
           [--no-wait-stderr|--wait-stderr]
           [--dos2unix] [--unix2dos]
            -- <program/arg0> [argument1] ... [argumentN]]
          
```
<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--exe <path to executable>

Specifies the absolute path of the executable on the guest OS file system. Mandatory. e.g.: C:\Windows\System32\calc.exe.

--timeout <msec>

Specifies the maximum time (microseconds) that the executable can run, during which VBoxManage receives its output. Optional. If unspecified, VBoxManage waits indefinitely for the process to end, or an error occurs.

-E|--putenv <NAME>=<VALUE>

Sets/modifies/unsets environment variable(s) in the environment in which the program will run. Optional.

The guest process is created with the standard default guest OS environment. Use this option to modify that default environment. To set/modify a variable use: <NAME>=<VALUE>. To unset a variable use: <NAME>=

Any spaces in names/values should be enclosed by quotes.

To set/modify/unset multiple variables, use multiple instances of the --E|--putenv option.

--unquoted-args

Disables escaped double quoting (e.g. \"fred\") on arguments passed to the executed program. Optional.

--ignore-operhaned-processes

Ignore orphaned processes. Not yet implemented. Optional.

--profile

Use Profile. Not yet implemented. Optional.

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

Does not wait/waits until the guest process ends and receives its exit code and reason/flags. In the case of --wait-stdout - while the process runs, VBoxManage receives its stdout. Optional.

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

Does not wait/waits until the guest process ends and receives its exit code and reason/flags. In case of --wait-stderr - while the process runs, VBoxManage receives its stderr. Optional.

--dos2unix

Converts output from DOS/Windows guests to UNIX/Linux-compatible line endings (CR + LF → LF). Not yet implemented. Optional.

--unix2dos

Converts output from a UNIX/Linux guests to DOS/Windows-compatible line endings (LF → CR + LF). Not yet implemented. Optional.

[-- <program/arg0> [<argument1>] ... [<argumentN>]]

Specifies program name, followed by one or more arguments to pass to the program. Optional.

Note: Any spaces in arguments should be enclosed by quotes.

Note

On Windows there are certain limitations for graphical applications; please see Chapter 14, Known limitations for more information.

Examples:
```
VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls"
          --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr
```
```
VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe"
          --username foo --passwordfile bar.txt --wait-exit --wait-stdout
```
Note that the double backslashes in the second example are only required on Unix hosts.

Note

For certain commands a user name of an existing user account on the guest must be specified; anonymous executions are not supported for security reasons. A user account password, however, is optional and depends on the guest's OS security policy or rules. If no password is specified for a given user name, an empty password will be used. On certain OSes like Windows the security policy may needs to be adjusted in order to allow user accounts with an empty password set. Also, global domain rules might apply and therefore cannot be changed.

Starting at VirtualBox 4.1.2 guest process execution by default is limited to serve up to 5 guest processes at a time. If a new guest process gets started which would exceed this limit, the oldest not running guest process will be discarded in order to be able to run that new process. Also, retrieving output from this old guest process will not be possible anymore then. If all 5 guest processes are still active and running, starting a new guest process will result in an appropriate error message.

To raise or lower the guest process execution limit, either the guest property /VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept or VBoxService' command line by specifying --control-procs-max-kept needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited guest processes, a value of 0 needs to be set (not recommended).
start Executes a guest program until it completes.
```
VBoxManage guestcontrol <uuid|vmname> start [common-options]
           [--exe <path to executable>] [--timeout <msec>]
           [-E|--putenv <NAME>[=<VALUE>]] [--unquoted-args]
           [--ignore-operhaned-processes] [--profile]
            -- <program/arg0> [argument1] ... [argumentN]]
          
```
Where the options are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--exe <path to executable>

Specifies the absolute path of the executable on the guest OS file system. Mandatory. e.g.: C:\Windows\System32\calc.exe

--timeout <msec>

Specifies the maximum time (microseconds) that the executable can run. Optional. If unspecified, VBoxManage waits indefinitely for the process to end, or an error occurs.

-E|--putenv <NAME>=<VALUE>

Sets/modifies/unsets environment variable(s) in the environment in which the program will run. Optional.

The guest process is created with the standard default guest OS environment. Use this option to modify that default environment. To set/modify a variable use: <NAME>=<VALUE>. To unset a variable use: <NAME>=

Any spaces in names/values should be enclosed by quotes.

To set/modify/unset multiple variables, use multiple instances of the --E|--putenv option.

--unquoted-args

Disables escaped double quoting (e.g. \"fred\") on arguments passed to the executed program. Optional.

--ignore-operhaned-processes

Ignores orphaned processes. Not yet implemented. Optional.

--profile

Use a profile. Not yet implemented. Optional.

[-- <program/arg0> [<argument1>] ... [<argumentN>]]

Specifies program name, followed by one or more arguments to pass to the program. Optional.

Note: Any spaces in arguments should be enclosed by quotes.

Note

On Windows there are certain limitations for graphical applications; please see Chapter 14, Known limitations for more information.

Examples:
```
VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls"
          --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr
```
```
VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe"
          --username foo --passwordfile bar.txt --wait-exit --wait-stdout
```
Note that the double backslashes in the second example are only required on Unix hosts.

Note

For certain commands a user name of an existing user account on the guest must be specified; anonymous executions are not supported for security reasons. A user account password, however, is optional and depends on the guest's OS security policy or rules. If no password is specified for a given user name, an empty password will be used. On certain OSes like Windows the security policy may needs to be adjusted in order to allow user accounts with an empty password set. Also, global domain rules might apply and therefore cannot be changed.

Starting at VirtualBox 4.1.2 guest process execution by default is limited to serve up to 5 guest processes at a time. If a new guest process gets started which would exceed this limit, the oldest not running guest process will be discarded in order to be able to run that new process. Also, retrieving output from this old guest process will not be possible anymore then. If all 5 guest processes are still active and running, starting a new guest process will result in an appropriate error message.

To raise or lower the guest process execution limit, either the guest property /VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept or VBoxService' command line by specifying --control-procs-max-kept needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited guest processes, a value of 0 needs to be set (not recommended).
copyfrom Copies files from the guest to the host file system. (Note - only with Guest Additions 4.0 or later installed).
```
VBoxManage guestcontrol <uuid|vmname> copyfrom [common-options]
           [--dryrun] [--follow] [--R|recursive]
            --target-directory <host-dst-dir>
            <guest-src0> [<guest-src1> [...]] 
```
Where the parameters are:

<uid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--dryrun

Instructs VBoxManage to perform a dry run instead of an actual file copying operation. Optional.

--follow

Enables symlink following on the guest file system. Optional.

-R|--recursive

Enables recursive copying of files/directories from the specified guest file system directory. Optional.

--target-directory <host-dst-dir>

Specifies the absolute path of the host file system destination directory. Mandatory. e.g. C:\Temp.

<guest-src0> [<guest-src1> [...]]

Specifies the absolute path(s) of guest file system file(s) to be copied. Mandatory. e.g. C:\Windows\System32\calc.exe. Wildcards can be used in the expression(s), e.g. C:\Windows\System*\*.dll.
copyto Copies files from the host to the guest file system. (Note - only with Guest Additions 4.0 or later installed).
```
VBoxManage guestcontrol <uuid|vmname> copyto [common-options]
           [--dryrun] [--follow] [--R|recursive]
            --target-directory <guest-dst>
            <host-src0> [<host-src1> [...]] 
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--dryrun

Instructs VBoxManage to perform a dry run instead of an actual file copying operation. Optional.

--follow

Enables symlink following on the host file system. Optional.

-R|--recursive

Enables recursive copying of files/directories from the specified host file system directory(ies). Optional.

--target-directory <guest-dst>

Specifies the absolute path of the guest file system destination directory. Mandatory. e.g. C:\Temp.

<host-src0> [<host-src1> [...]]

Specifies the absolute path(s) of host file system file(s) to be copied. Mandatory. e.g. C:\Windows\System32\calc.exe. Wildcards can be used in the expression(s), e.g. C:\Windows\System*\*.dll.
md|mkdir|createdir|createdirectory Creates one or more directory(ies) on the guest file system. (Note - only with Guest Additions 4.0 or later installed).
```
VBoxManage guestcontrol <uuid|vmname>  md|mkdir|createdir|createdirectory [common-options]
            [--parents] [--mode <mode>]
            <guest-dir0> [<guest-dir1> [...]] 
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--parents

Creates any absent parent directory(ies) of the specified directory. Optional.

e.g. If specified directory is D:\Foo\Bar and D:\Foo is absent, it will be created. In such a case, had the --parents option not been used, this command would have failed.

--mode <mode>

Specifies the permission mode on the specified directory(ies) (and any parents, where --parents option used). Currently octal modes (e.g. 0755) only are supported.

<guest-dir0> [<guest-dir1> [...]]

Specifies list of absolute path(s) of directory(ies) to be created on guest file system. Mandatory. e.g. D:\Foo\Bar.

All parent directories must already exist unless switch --parents used. (e.g. in the above example D:\Foo). The specified user must have sufficient rights to create the specified directory(ies), and any parents that need to be created.
rmdir|removedir|removedirectory Deletes specified guest file system directories. (Only with installed Guest Additions 4.3.2 and later).
```
VBoxManage guestcontrol <uuid|vmname> rmdir|removedir|removedirectory [common-options]
           [--recursive|-R]
            <guest-dir0> [<guest-dir1> [...]]
          
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--recursive

Recursively removes directories and contents. Optional.

<guest-dir0> [<guest-dir1> [...]]

Specifies list of the absolute path(s) of directory(ies) to be deleted on guest file system. Mandatory. Wildcards are allowed. e.g. D:\Foo\*Bar. The specified user must have sufficient rights to delete the specified directory(ies).
rm|removefile Deletes specified files on the guest file system. (Only with installed Guest Additions 4.3.2 and later).
```
VBoxManage guestcontrol <uuid|vmname> rm|removefile [common-options]
           [-f|--force]
            <guest-file0> [<guest-file1> [...]] 
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

-f|--force

Enforce operation (override any requests for confirmations). Optional.

<guest-file0> [<guest-file1> [...]]

Specifies list of absolute path(s) of file(s) to be deleted on guest file system. Mandatory. Wildcards are allowed. e.g. D:\Foo\Bar\text*.txt. The specified user should have sufficient rights to delete the specified file(s).
mv|move|ren|rename This subcommand renames file(s) and/or directory(ies) on the guest file system. (Only with installed Guest Additions 4.3.2 and later).
```
VBoxManage guestcontrol <uuid|vmname> mv|move|ren|rename [common-options]
           <guest-source0> [<guest-source1> [...]] <guest-dest>
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

<guest-source0> [<guest-source1> [...]]

Specifies absolute path(s) of file(s) and/or single directory to be moved/renamed on guest file system. Mandatory. Wildcards are allowed in file names(s). The specified user should have sufficient rights to access the specified file(s).

<dest>

Specifies the absolute path of the destination file/directory to which the file(s) are to be moved. Mandatory. If only one file to be moved, <dest> can be file or directory, else it must be a directory. The specified user must have sufficient rights to access the destination file/directory.
mktemp|createtemp|createtemporary Creates a temporary file/directory on the guest file system, to assist subsequent copying of files from the host to the guest file systems. By default, the file/directory is created in the guest's platform specific temp directory. Not currently supported. (Only with installed Guest Additions 4.2 and later).
```
VBoxManage guestcontrol <uuid|vmname> mktemp|createtemp|createtemporary [common-options]
           [--directory] [--secure] [--mode <mode>] [--tmpdir <directory>]
            <template>
            
```
The parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--directory

Creates a temporary directory instead of a file, specified by the <template> parameter. Optional.

--secure

Enforces secure file/directory creation. Optional. The permission mode is set to 0755. Operation fails if it cannot be performed securely.

--mode <mode>

Specifies the permission mode of the specified directory. Optional. Currently only octal modes (e.g. 0755) are supported.

--tmpdir <directory>

Specifies the absolute path of the directory on the guest file system into which the file/directory specified in will be created. Optional. If unspecified, the platform-specific temp directory is used.

<template>

Specifies a file name without a directory path, containing at least one sequence comprising three consecutive 'X' characters, or ending in 'X'. Mandatory.
stat Displays file or file system status(es) on the guest.
```
VBoxManage guestcontrol <uuid|vmname> stat [common-options]
           <file0> [<file1> [...]]
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

<file0> [<file1> [...]]

Specifies absolute path(s) of file(s) and/or file system(s) on guest file system. Mandatory. e.g. /home/foo/a.out. The specified user should have sufficient rights to access the specified file(s)/file system(s).

The second set of subcommands is of the form:

VBoxManage guestcontrol <uuid|vmname> <sub-command>
           [-v|--verbose] [-q|quiet] ...

The "common-options" are:

            [-v|--verbose] [-q|--quiet]

Where details of the common options for the second set of subcommands are:

-v|--verbose: Makes the sub-command execution more verbose. Optional.
-q|--quiet: Makes the sub-command execution quieter. Optional.

The second set of subcommands:

list Lists guest control configuration and status data, e.g. open guest sessions, guest processes and files.
```
VBoxManage guestcontrol <uuid|vmname> list [common-opts]
           <all|sessions|processes|files> 
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

all|sessions|processes|files

Indicates whether to list all available data or guest sessions, processes or files. Mandatory.
closeprocess Terminates guest processes specified by PID(s))running in guest session(s), specified by the session ID or name(s).
```
VBoxManage guestcontrol <uuid|vmname> closeprocess [common-options]
           --session-id <ID> | --session-name <name or pattern>
           <PID0> [<PID1> [...]] 
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--session-id <ID>

Specifies the guest session by its ID. Optional.

--session-name <name or pattern>

Specifies the guest session by its name, or multiple sessions using a pattern containing wildcards. Optional.

<PID0> [<PID1> [...]]

Specifies a list of process identifiers (PIDs) of guest processes to be terminated. Mandatory.
closesession Closes specified guest sessions, specified either by session ID or name.
```
VBoxManage guestcontrol <uuid|vmname> closesession [common-options]
           --session-id <ID> | --session-name <name or pattern> | --all 
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--session-id <ID>

Specifies the guest session to be closed by ID. Optional.

--session-name <name or pattern>

Specifies the guest session to be closed by name. Optional. Multiple sessions can be specified by using a pattern containing wildcards.

--all

Close all guest sessions. Optional.
updatega|updateadditions|updateguestadditions Ugrades Guest Additions already installed on the guest. (Only already installed Guest Additions 4.0 and later).
```
VBoxManage guestcontrol <uuid|vmname> updatega|updateadditions|updateguestadditions [common-options]
           [--source <New .ISO path>]
           [--wait-start]
           [-- <argument0> [<argument1> [...]]]
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

--source <New .ISO path>

Specifies the absolute path on guest file system of the .ISO file for Guest Additions update. Mandatory.

--wait-start

Indicates that VBoxManage starts the usual updating process on the guest and then waits until the actual Guest Additions updating begins, at which point VBoxManage self-terminates. Optional.

Default behavior is that VBoxManage waits for completion of the Guest Additions update before terminating. Use of this option is sometimes necessary, as a running VBoxManage can affect the interaction between the installer and the guest OS.

[-- <argument0> [<argument1> [...]]]

Specifies optional command line arguments to be supplied to the Guest Additions updater. Useful for retrofitting features which are not currently installed.

Arguments containing spaces should be enclosed by quotes.
watch This subcommand prints current guest control activity.
```
VBoxManage guestcontrol <uuid|vmname> watch [common-options]
          
```
Where the parameters are:

<uuid|vmname>

Specifies the VM UUID or VM name. Mandatory.

previous page start next page

8.34. VBoxManage guestcontrol

Oracle VM VirtualBox

8.34. VBoxManage guestcontrol

Note

Note

Note

Note