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 <uuid|vmname> <command>
The following subcommands are available (where
<uuid|vmname>
, 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 <uuid|vmname> 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:
uuid|vmname
The VM UUID or VM name. Mandatory.
--image "<path to program>"
Absolute path and process name of process to execute
in the guest, e.g.
C:\Windows\System32\calc.exe
--username <name>
Name of the user the process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--dos2unix
--environment
"<NAME>=<VALUE>"
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.
--timeout <msec>
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.
--unix2dos
--verbose
Tells VBoxManage to be more verbose.
--wait-exit
Waits until the process ends and outputs its exit code along with the exit reason/flags.
--wait-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 stdout.
--wait-stderr
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.
[-- [<argument1s>] ... [<argumentNs>]]
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 <uuid|vmname> copyto|cp <guest source> <host dest> --username <name> [--passwordfile <file> | --password <password>] [--dryrun] [--follow] [--recursive] [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
source on host
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
destination on guest
Absolute destination path on the guest, e.g.
C:\Temp
--username <name>
Name of the user the copy process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--dryrun
Tells VBoxManage to only perform a dry run instead of really copying files to the guest.
--follow
Enables following symlinks on the host's source.
--recursive
Recursively copies files/directories of the specified source.
--verbose
Tells VBoxManage to be more verbose.
--flags <flags>
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 <uuid|vmname> createdir[ectory]|mkdir|md <guest directory>... --username <name> [--passwordfile <file> | --password <password>] [--parents] [--mode <mode>] [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
directory to create on guest
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.
--username <name>
Name of the user the copy process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--parents
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.
--mode <mode>
Sets the permission mode of the specified directory.
Only octal modes (e.g.
0755
) are supported right
now.
--verbose
Tells VBoxManage to be more verbose.
removedirectory
,
which allows deletion of guest directories (only with installed Guest
Additions 4.3.2 and later).
VBoxManage guestcontrol <uuid|vmname> removedir[ectory]|rmdir <guest directory>... --username <name> [--passwordfile <file> | --password <password>] [--recursive|-R|-r] [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
directory to remove on guest
Absolute path of directory/directories to remove on
guest, e.g. D:\Foo\Bar
. The
specified user must have appropriate rights to delete the
specified guest directories.
--username <name>
Name of the user the copy process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--recursive
Remove directories and their contents recursively.
--verbose
Tells VBoxManage to be more verbose.
removefile
,
which allows deletion of guest files (only with installed Guest
Additions 4.3.2 and later).
VBoxManage guestcontrol <uuid|vmname> removefile|rm <guest file>... --username <name> [--passwordfile <file> | --password <password>] [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
file to remove on guest
Absolute path of a file/files to remove on
guest, e.g. D:\Foo\Bar\text.txt
. The
specified user must have appropriate rights to delete the
specified guest files.
--username <name>
Name of the user the copy process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--verbose
Tells VBoxManage to be more verbose.
ren[ame]|mv
,
which allows renaming of guest files and/or directories (only with installed Guest
Additions 4.3.2 and later).
VBoxManage guestcontrol <uuid|vmname> ren[ame]|mv <source>... <dest> --username <name> [--passwordfile <file> | --password <password>] [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
source
Absolute path of one or more source(s) to move to destination. If more than one source is specified, destination must be an existing directory on the guest. The specified user must have appropriate rights to access source and destination files and directories.
dest
Absolute path of the destination to move the source(s) to. This can be a directory or a file, depending if one or more sources have been specified. The specified user must have appropriate rights to access the destination file and directory.
--username <name>
Name of the user the copy process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--verbose
Tells VBoxManage to be more verbose.
createtemporary
,
which allows
copying files from the host to the guest (only with installed Guest
Additions 4.2 and later).
VBoxManage guestcontrol <uuid|vmname> createtemp[orary]|mktemp <template> --username <name> [--passwordfile <file> | --password <password>] [--directory] [--secure] [--tmpdir <directory>] [--domain <domain>] [--mode <mode>] [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
template
A file name without a path and with at least three consecutive 'X' characters or ending in 'X'
--username <name>
Name of the user the copy process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--directory
Create a temporary directory instead of a file.
--secure
Secure creation. The file mode is fixed to
0755
. And the operation
will fail if it cannot performed securely.
--tmpdir <directory>
Directory where the file / directory is created. If not specified, the platform-specific temp directory is used.
--mode <mode>
Sets the permission mode of the specified directory.
Only octal modes (e.g.
0755
) are supported right
now.
--verbose
Tells VBoxManage to be more verbose.
list
,
which lists various guest control information such as open guest sessions,
guest processes and guest files.
VBoxManage guestcontrol <uuid|vmname> list <all|sessions|processes|files> [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
all|sessions|processes|files
Whether to list guest sessions, guest processes, guest files or all information available. Mandatory.
--verbose
Tells VBoxManage to be more verbose.
process kill
,
which terminates specific guest processes of a guest session, based on either the
session's ID or the session's name.
VBoxManage guestcontrol <uuid|vmname> process kill --session-id <ID> | --session-name <name or pattern> [--verbose] <PID> ... <PID n>
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
--session-id
Specifies the guest session to use by its ID.
--session-name
Specifies the guest session to use by its name. Multiple sessions can be closed when specifying * or ? wildcards.
--verbose
Tells VBoxManage to be more verbose.
<PID> ... <PID n>
List of process identifiers (PIDs) to terminate.
[p[s]]kill
,
which terminates specific guest processes of a guest session, based on either the
session's ID or the session's name.
VBoxManage guestcontrol <uuid|vmname> process kill --session-id <ID> | --session-name <name or pattern> [--verbose] <PID> ... <PID n>
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
--session-id
Specifies the guest session to use by its ID.
--session-name
Specifies the guest session to use by its name. Multiple sessions can be closed when specifying * or ? wildcards.
--verbose
Tells VBoxManage to be more verbose.
<PID> ... <PID n>
List of process identifiers (PIDs) to terminate.
session close
,
which closes specific guest sessions, based on either the session's ID or the
session's name.
VBoxManage guestcontrol <uuid|vmname> session close --session-id <ID> | --session-name <name or pattern> | --all [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
--session-id
Close a guest session specified by its ID.
--session-name
Close a guest session specified by its name. Multiple sessions can be closed when specifying * or ? wildcards.
--all
Close all guest sessions.
--verbose
Tells VBoxManage to be more verbose.
stat
,
which displays file
or file system status on the guest.
VBoxManage guestcontrol <uuid|vmname> stat <file>... --username <name> [--passwordfile <file> | --password <password>] [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
file element(s) to check on guest
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).
--username <name>
Name of the user the copy process should run under. This user must exist on the guest OS.
--passwordfile <file>
Password of the user account specified to be read from the given file. If not given, an empty password is assumed.
--password <password>
Password of the user account specified with
--username
. If not given,
an empty password is assumed.
--verbose
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 <uuid|vmname> updateadditions [--source "<guest additions .ISO file to use>"] [--verbose] [--wait-start] [-- [<argument1>] ... [<argumentN>]]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
--source
"<guest additions .ISO file to
use>"Full path to an alternative VirtualBox Guest Additions .ISO file to use for the Guest Additions update.
--verbose
Tells VBoxManage to be more verbose.
--wait-start
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.
[-- [<argument1s>] ... [<argumentNs>]]
Optional command line arguments to use for the Guest Additions installer. Useful for retrofitting features which weren't installed before on the guest.
Arguments containing spaces must be enclosed in quotation marks.
watch
,
which prints current guest control activity.
VBoxManage guestcontrol <uuid|vmname> watch [--verbose]
where the parameters mean:
uuid|vmname
The VM UUID or VM name. Mandatory.
--verbose
Tells VBoxManage to be more verbose.