The "guestcontrol" commands allow you to control certain things inside a guest from the host. Please see Section 4.7, “Guest control” for an introduction.
Generally, the syntax is as follows:
VBoxManage guestcontrol <command>
The following subcommands are available (where
<vm>
, in each case, can either be a
VM name or a VM UUID, as with the other VBoxManage commands):
execute
, which allows for
executing a program/script (process) which is already installed and
runnable on the guest. This command only works while a VM is up and
running and has the following syntax:
VBoxManage guestcontrol exec[ute] <vmname>|<uuid> <path to program> --username <name> --password <password> [--arguments "<arguments>"] [--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"] [--flags <flags>] [--timeout <msec>] [--verbose] [--wait-for exit,stdout,stderr||]
where the parameters mean:
The VM UUID or VM name. Mandatory.
Absolute path and process name of process to execute
in the guest, e.g.
C:\Windows\System32\calc.exe
One or more arguments to pass to the process being executed.
Arguments containing spaces must be enclosed in
quotation marks. More than one
--arguments
at a time can
be specified to keep the command line tidy.
One or more environment variables to be set or unset.
By default, the new process in the guest will be
created with the standard environment of the guest OS. This
option allows for modifying that environment. To set/modify
a variable, a pair of
NAME=VALUE
must be
specified; to unset a certain variable, the name with no
value must set, e.g.
NAME=
.
Arguments containing spaces must be enclosed in
quotation marks. More than one
--environment
at a time can
be specified to keep the command line tidy.
Additional flags to set. This is not used at the moment.
Value (in milliseconds) that specifies the time how long the started process is allowed to run and how long VBoxManage waits for getting output from that process. If no timeout is specified, VBoxManage will wait forever until the started process ends or an error occured.
Name of the user the process should run under. This user must exist on the guest OS.
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
Tells VBoxManage to be more verbose.
Tells VBoxManage to wait for a certain action to happen and react to it. The following actions are available:
Waits until the process ends and outputs its exit code along with the exit reason/flags.
Waits until the process ends and outputs its exit code along with the exit reason/flags. After that VBoxManage retrieves the output collected from the guest process's stdout and stderr.
On Windows there are certain limitations for graphical applications; please see Chapter 14, Known limitations for more information.
Examples:
VBoxManage --nologo guestcontrol execute "My VM" "/bin/ls" --arguments "-l /usr" --username foo --password bar --wait-for stdout
VBoxManage --nologo guestcontrol execute "My VM" "c:\\windows\\system32\\ipconfig.exe" --username foo --password bar --wait-for stdout
Note that the double backslashes in the second example are only required on Unix hosts.
copyto
, which allows copying
files from the host to the guest (only with installed Guest
Additions 4.0 and later).
VBoxManage copyto|cp <vmname>|<uuid> <source on host> <destination on guest> --username <name> --password <password> [--dryrun] [--follow] [--recursive] [--verbose]
where the parameters mean:
The VM UUID or VM name. Mandatory.
Absolute path of source file(s) on host to copy over
to the guest, e.g.
C:\Windows\System32\calc.exe
.
This also can be a wildcard expression, e.g.
C:\Windows\System32\*.dll
Absolute destination path on the guest, e.g.
C:\Temp
Name of the user the copy process should run under. This user must exist on the guest OS.
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
Tells VBoxManage to only perform a dry run instead of really copying files to the guest.
Enables following symlinks on the host's source.
Recursively copies files/directories of the specified source.
Tells VBoxManage to be more verbose.
Additional flags to set. This is not used at the moment.
createdirectory
, which allows
copying files from the host to the guest (only with installed Guest
Additions 4.0 and later).
VBoxManage createdir[ectory]|mkdir|md <vmname>|<uuid> <directory to create on guest> [--username "<name>"] [--password "<password>"] [--parents] [--mode <mode>] [--verbose]
where the parameters mean:
The VM UUID or VM name. Mandatory.
Absolute path of directory/directories to create on
guest, e.g. D:\Foo\Bar
.
Parent directories need to exist (e.g. in this example
D:\Foo
) when switch
--parents
is omitted. The
specified user must have appropriate rights to create the
specified directory.
Name of the user the copy process should run under. This user must exist on the guest OS.
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
Also creates not yet existing parent directories of
the specified directory, e.g. if the directory
D:\Foo
of
D:\Foo\Bar
does not exist
yet it will be created. Without specifying
--parent
the action would
have failed.
Sets the permission mode of the specified directory.
Only octal modes (e.g.
0755
) are supported right
now.
Tells VBoxManage to be more verbose.
updateadditions
, which allows
for updating an already installed Guest Additions version on the
guest (only already installed Guest Additions 4.0 and later).
VBoxManage guestcontrol updateadditions <vmname>|<uuid> [--source "<guest additions .ISO file to use>"] [--verbose]
where the parameters mean:
The VM UUID or VM name. Mandatory.
Full path to an alternative VirtualBox Guest Additions .ISO file to use for the Guest Additions update.
Tells VBoxManage to be more verbose.