7.33. VBoxManage guestcontrol

The guestcontrol commands enable control of the guest from the host. See Section 4.9, “Guest Control of Applications” for an introduction.

The guestcontrol command 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 following form:

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

The common options are as follows:

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

The common options for the first set of subcommands are explained in the following list.

<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 are as follows:

run: Executes a guest program, forwarding stdout, stderr, and stdin to and 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. For example: C:\Windows\System32\calc.exe.
--timeout <msec>
Specifies the maximum time, in 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, and unsets environment variables 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 or modify a variable use: <NAME>=<VALUE>. To unset a variable use: <NAME>=
Any spaces in names and values should be enclosed by quotes.
To set, modify, and unset multiple variables, use multiple instances of the --E|--putenv option.
--unquoted-args
Disables escaped double quoting, such as \"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 or waits until the guest process ends and receives its exit code and reason/flags. In the case of --wait-stdout, VBoxManage receives its stdout while the process runs. Optional.
--no-wait-stderr|--wait-stderr
Does not wait or waits until the guest process ends and receives its exit code, error messages, and flags. In the case of --wait-stderr, VBoxManage receives its stderr while the process runs. Optional.
--dos2unix
Converts output from DOS/Windows guests to UNIX/Linux-compatible line endings, CR + LF to LF. Not yet implemented. Optional.
--unix2dos
Converts output from a UNIX/Linux guests to DOS/Windows-compatible line endings, LF to CR + LF. Not yet implemented. Optional.
[-- <program/arg0> [<argument1>] ... [<argumentN>]]
Specifies the program name, followed by one or more arguments to pass to the program. Optional.
Any spaces in arguments should be enclosed by quotes.
Note
On Windows there are certain limitations for graphical applications. See Known Limitations.
Examples of using the guestcontrol run command are as follows:
```
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 Oracle VM VirtualBox 4.1.2 guest process execution by default is limited to serve up to five 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 five 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 use 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, but this is 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 as follows:
<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. For example: C:\Windows\System32\calc.exe
--timeout <msec>
Specifies the maximum time, in 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, and unsets environment variables 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 or modify a variable use: <NAME>=<VALUE>. To unset a variable use: <NAME>=
Any spaces in names and values should be enclosed by quotes.
To set, modify, or unset multiple variables, use multiple instances of the --E|--putenv option.
--unquoted-args
Disables escaped double quoting, such as \"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 the program name, followed by one or more arguments to pass to the program. Optional.
Any spaces in arguments should be enclosed by quotes.
Note
On Windows there are certain limitations for graphical applications. See Known Limitations.
Examples of using the guestcontrol start command are as follows:
```
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 Oracle VM VirtualBox 4.1.2 guest process execution by default is limited to serve up to five 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 five 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 use 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, but this is not recommended.
copyfrom: Copies files from the guest to the host file system. Only available with Guest Additions 4.0 or later installed.
```
VBoxManage guestcontrol <uuid|vmname> copyfrom [common-options]
           [--follow] [--R|recursive]
            --target-directory <host-dst-dir>
            <guest-src0> [<guest-src1> [...]] 
```
Where the parameters are as follows:
<uid|vmname>
Specifies the VM UUID or VM name. Mandatory.
--follow
Enables symlink following on the guest file system. Optional.
-R|--recursive
Enables recursive copying of files and 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. For example: C:\Temp.
<guest-src0> [<guest-src1> [...]]
Specifies the absolute paths of guest file system files to be copied. Mandatory. For example: C:\Windows\System32\calc.exe. Wildcards can be used in the expressions. For example: C:\Windows\System*\*.dll.
copyto: Copies files from the host to the guest file system. Only available with Guest Additions 4.0 or later installed.
```
VBoxManage guestcontrol <uuid|vmname> copyto [common-options]
           [--follow] [--R|recursive]
            --target-directory <guest-dst>
            <host-src0> [<host-src1> [...]] 
```
Where the parameters are as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.
--follow
Enables symlink following on the host file system. Optional.
-R|--recursive
Enables recursive copying of files and directories from the specified host file system directory. Optional.
--target-directory <guest-dst>
Specifies the absolute path of the guest file system destination directory. Mandatory. For example: C:\Temp.
<host-src0> [<host-src1> [...]]
Specifies the absolute paths of host file system files to be copied. Mandatory. For example: C:\Windows\System32\calc.exe. Wildcards can be used in the expressions. For example: C:\Windows\System*\*.dll.
md|mkdir|createdir|createdirectory: Creates one or more directories on the guest file system. Only available 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 as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.
--parents
Creates any absent parent directories of the specified directory. Optional.
For example: 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 directories, and any parents, if the --parents option is used. Currently octal modes only, such as. 0755, are supported.
<guest-dir0> [<guest-dir1> [...]]
Specifies a list of absolute paths of directories to be created on guest file system. Mandatory. For example: D:\Foo\Bar.
All parent directories must already exist unless the switch --parents is used. For example, in the above example D:\Foo. The specified user must have sufficient rights to create the specified directories, and any parents that need to be created.
rmdir|removedir|removedirectory: Deletes specified guest file system directories. Only available 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 as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.
--recursive
Recursively removes directories and contents. Optional.
<guest-dir0> [<guest-dir1> [...]]
Specifies a list of the absolute paths of directories to be deleted on guest file system. Mandatory. Wildcards are allowed. For example: D:\Foo\*Bar. The specified user must have sufficient rights to delete the specified directories.
rm|removefile: Deletes specified files on the guest file system. Only available 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 as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.
-f|--force
Enforce operation and override any requests for confirmations. Optional.
<guest-file0> [<guest-file1> [...]]
Specifies a list of absolute paths of files to be deleted on guest file system. Mandatory. Wildcards are allowed. For example: D:\Foo\Bar\text*.txt. The specified user should have sufficient rights to delete the specified files.
mv|move|ren|rename: Renames files and/or directories on the guest file system. Only available 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 as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.
<guest-source0> [<guest-source1> [...]]
Specifies absolute paths of files or a single directory to be moved and renamed on guest file system. Mandatory. Wildcards are allowed in file names. The specified user should have sufficient rights to access the specified files.
<dest>
Specifies the absolute path of the destination file or directory to which the files 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 or directory.
mktemp|createtemp|createtemporary: Creates a temporary file or directory on the guest file system, to assist subsequent copying of files from the host to the guest file systems. By default, the file or directory is created in the guest's platform specific temp directory. Not currently supported. Only available 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 as follows:
<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 and 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, such as 0755, are supported.
--tmpdir <directory>
Specifies the absolute path of the directory on the guest file system where the file or directory specified 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 of three consecutive X characters, or ending in X. Mandatory.
stat: Displays file or file system statuses on the guest.
```
VBoxManage guestcontrol <uuid|vmname> stat [common-options]
           <file0> [<file1> [...]]
```
Where the parameters are as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.
<file0> [<file1> [...]]
Specifies absolute paths of files or file systems on the guest file system. Mandatory. For example: /home/foo/a.out. The specified user should have sufficient rights to access the specified files or file systems.

The second set of subcommands is of the form:

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

The common options are as follows:

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

Details of the common options for the second set of subcommands are as follows:

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

The second set of subcommands are as follows:

list: Lists guest control configuration and status data. For example: open guest sessions, guest processes, and files.
```
VBoxManage guestcontrol <uuid|vmname> list [common-opts]
           <all|sessions|processes|files> 
```
Where the parameters are as follows:
<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 PIDs running in a guest session, specified by the session ID or name.
```
VBoxManage guestcontrol <uuid|vmname> closeprocess [common-options]
           --session-id <ID> | --session-name <name or pattern>
           <PID0> [<PID1> [...]] 
```
Where the parameters are as follows:
<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 as follows:
<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 available for 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 as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.
--source <New .ISO path>
Specifies the absolute path on the guest file system of the .ISO file for the 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: Prints current guest control activity.
```
VBoxManage guestcontrol <uuid|vmname> watch [common-options]
          
```
Where the parameters are as follows:
<uuid|vmname>
Specifies the VM UUID or VM name. Mandatory.