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 already is installed and
runnable on the guest. This command only works while a VM is up and
running and has the following syntax:
VBoxManage guestcontrol <vmname>|<uuid> exec[ute] --image <path to program> --username <name> [--passwordfile <file> | --password <password>] [--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"] [--verbose] [--timeout <msec>] [--wait-exit] [--wait-stdout] [--wait-stderr] [--dos2unix] [--unix2dos] -- [[<argument1>] ... [<argumentN>]]
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
Name of the user the process should run under. This user must exist on the guest OS.
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
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.
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.
Tells VBoxManage to be more verbose.
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. While waiting VBoxManage retrieves the process output collected from stdout.
Waits until the process ends and outputs its exit code along with the exit reason/flags. While waiting VBoxManage retrieves the process output collected from stderr.
One or more arguments to pass to the process being executed.
Arguments containing spaces must be enclosed in quotation marks.
On Windows there are certain limitations for graphical applications; please see Chapter 14, Known limitations for more information.
Examples:
VBoxManage --nologo guestcontrol "My VM" execute --image "/bin/ls" --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr
VBoxManage --nologo guestcontrol "My VM" execute --image "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.
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).
copyto
, which allows copying
files from the host to the guest (only with installed Guest
Additions 4.0 and later).
VBoxManage guestcontrol <vmname>|<uuid> copyto|cp <guest source> <host dest> --username <name> [--passwordfile <file> | --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 to be read from the given file. If not given, an empty password is assumed.
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.
copyfrom
, which allows copying
files from the guest to the host (only with installed Guest
Additions 4.0 and later). It has the same parameters as
copyto
above.
createdirectory
, which allows
copying files from the host to the guest (only with installed Guest
Additions 4.0 and later).
VBoxManage guestcontrol <vmname>|<uuid> createdir[ectory]|mkdir|md <guest directory>... --username <name> [--passwordfile <file> | --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 to be read from the given file. If not given, an empty password is assumed.
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.
stat
, which displays file
or file system status on the guest.
VBoxManage guestcontrol <vmname>|<uuid> stat <file>... --username <name> [--passwordfile <file> | --password <password>] [--verbose]
where the parameters mean:
The VM UUID or VM name. Mandatory.
Absolute path of directory/directories to check on
guest, e.g. /home/foo/a.out
.
The specified user must have appropriate rights to access
the given file element(s).
Name of the user the copy process should run under. This user must exist on the guest OS.
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
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 <vmname>|<uuid> updateadditions [--source "<guest additions .ISO file to use>"] [--verbose] [--wait-start]
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.
Starts the regular updating process and waits until the actual Guest Additions update inside the guest was started. This can be necessary due to needed interaction with the guest OS during the installation phase.
When omitting this flag VBoxManage will wait for the whole Guest Additions update to complete.