VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-guestcontrol.xml@ 103068

Last change on this file since 103068 was 102749, checked in by vboxsync, 10 months ago

Guest Control/VBoxManage: Implemented a "mount" sub command for the new GetMountPoints API. bugref:10415

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 60.3 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage guestcontrol
4-->
5<!--
6 Copyright (C) 2006-2023 Oracle and/or its affiliates.
7
8 This file is part of VirtualBox base platform packages, as
9 available from https://www.virtualbox.org.
10
11 This program is free software; you can redistribute it and/or
12 modify it under the terms of the GNU General Public License
13 as published by the Free Software Foundation, in version 3 of the
14 License.
15
16 This program is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <https://www.gnu.org/licenses>.
23
24 SPDX-License-Identifier: GPL-3.0-only
25-->
26<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
27 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
28<!ENTITY % all.entities SYSTEM "all-entities.ent">
29%all.entities;
30]>
31<refentry id="vboxmanage-guestcontrol" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2024-01-03 15:17:55 +0000 (Wed, 03 Jan 2024) $</pubdate>
34 <title>VBoxManage guestcontrol</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-guestcontrol</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-guestcontrol</refname>
44 <refpurpose>control a virtual machine from the host system</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-run">
50<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51 <command>VBoxManage guestcontrol</command>
52 <group choice="req">
53 <arg choice="plain"><replaceable>uuid</replaceable></arg>
54 <arg choice="plain"><replaceable>vmname</replaceable></arg>
55 </group>
56 <arg choice="plain">run</arg>
57 <arg>--arg0=<replaceable>argument 0</replaceable></arg>
58 <arg>--domain=<replaceable>domainname</replaceable></arg>
59 <arg>--dos2unix</arg>
60 <arg>--exe=<replaceable>filename</replaceable></arg>
61 <arg>--ignore-orphaned-processes</arg>
62 <group>
63 <arg choice="plain">--no-wait-stderr</arg>
64 <arg choice="plain">--wait-stderr</arg>
65 </group>
66 <group>
67 <arg choice="plain">--no-wait-stdout</arg>
68 <arg choice="plain">--wait-stdout</arg>
69 </group>
70 <group>
71 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
72 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
73 </group>
74 <arg>--profile</arg>
75 <arg>--putenv=<replaceable>var-name</replaceable>=[<replaceable>value</replaceable>]</arg>
76 <arg>--quiet</arg>
77 <arg>--timeout=<replaceable>msec</replaceable></arg>
78 <arg>--unix2dos</arg>
79 <arg>--unquoted-args</arg>
80 <arg>--username=<replaceable>username</replaceable></arg>
81 <arg>--cwd=<replaceable>directory</replaceable></arg>
82 <arg>--verbose</arg>
83 <arg choice="req">--<arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
84 </cmdsynopsis>
85
86 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-start">
87 <command>VBoxManage guestcontrol</command>
88 <group choice="req">
89 <arg choice="plain"><replaceable>uuid</replaceable></arg>
90 <arg choice="plain"><replaceable>vmname</replaceable></arg>
91 </group>
92 <arg choice="plain">start</arg>
93 <arg>--arg0=<replaceable>argument 0</replaceable></arg>
94 <arg>--domain=<replaceable>domainname</replaceable></arg>
95 <arg>--exe=<replaceable>filename</replaceable></arg>
96 <arg>--ignore-orphaned-processes</arg>
97 <group>
98 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
99 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
100 </group>
101 <arg>--profile</arg>
102 <arg>--putenv=<replaceable>var-name</replaceable>=[<replaceable>value</replaceable>]</arg>
103 <arg>--quiet</arg>
104 <arg>--timeout=<replaceable>msec</replaceable></arg>
105 <arg>--unquoted-args</arg>
106 <arg>--username=<replaceable>username</replaceable></arg>
107 <arg>--cwd=<replaceable>directory</replaceable></arg>
108 <arg>--verbose</arg>
109 <arg choice="req">--<arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
110 </cmdsynopsis>
111
112 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyfrom">
113 <command>VBoxManage guestcontrol</command>
114 <group choice="req">
115 <arg choice="plain"><replaceable>uuid</replaceable></arg>
116 <arg choice="plain"><replaceable>vmname</replaceable></arg>
117 </group>
118 <arg choice="plain">copyfrom</arg>
119 <arg>--dereference</arg>
120 <arg>--domain=<replaceable>domainname</replaceable></arg>
121 <group>
122 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
123 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
124 </group>
125 <arg>--quiet</arg>
126 <arg>--no-replace</arg>
127 <arg>--recursive</arg>
128 <arg>--target-directory=<replaceable>host-destination-dir</replaceable></arg>
129 <arg>--update</arg>
130 <arg>--username=<replaceable>username</replaceable></arg>
131 <arg>--verbose</arg>
132 <arg choice="req"><replaceable>guest-source0</replaceable></arg>
133 <arg choice="plain"><replaceable>guest-source1</replaceable> [...]</arg>
134 <arg choice="req"><replaceable>host-destination</replaceable></arg>
135 </cmdsynopsis>
136
137 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-copyto">
138 <command>VBoxManage guestcontrol</command>
139 <group choice="req">
140 <arg choice="plain"><replaceable>uuid</replaceable></arg>
141 <arg choice="plain"><replaceable>vmname</replaceable></arg>
142 </group>
143 <arg choice="plain">copyto</arg>
144 <arg>--dereference</arg>
145 <arg>--domain=<replaceable>domainname</replaceable></arg>
146 <group>
147 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
148 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
149 </group>
150 <arg>--quiet</arg>
151 <arg>--no-replace</arg>
152 <arg>--recursive</arg>
153 <arg>--target-directory=<replaceable>guest-destination-dir</replaceable></arg>
154 <arg>--update</arg>
155 <arg>--username=<replaceable>username</replaceable></arg>
156 <arg>--verbose</arg>
157 <arg choice="req"><replaceable>host-source0</replaceable></arg>
158 <arg choice="plain"><replaceable>host-source1</replaceable> [...]</arg>
159 </cmdsynopsis>
160
161 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mkdir">
162 <command>VBoxManage guestcontrol</command>
163 <group choice="req">
164 <arg choice="plain"><replaceable>uuid</replaceable></arg>
165 <arg choice="plain"><replaceable>vmname</replaceable></arg>
166 </group>
167 <arg choice="plain">mkdir</arg>
168 <arg>--domain=<replaceable>domainname</replaceable></arg>
169 <arg>--mode=<replaceable>mode</replaceable></arg>
170 <arg>--parents</arg>
171 <group>
172 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
173 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
174 </group>
175 <arg>--quiet</arg>
176 <arg>--username=<replaceable>username</replaceable></arg>
177 <arg>--verbose</arg>
178 <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg>
179 </cmdsynopsis>
180
181 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rmdir">
182 <command>VBoxManage guestcontrol</command>
183 <group choice="req">
184 <arg choice="plain"><replaceable>uuid</replaceable></arg>
185 <arg choice="plain"><replaceable>vmname</replaceable></arg>
186 </group>
187 <arg choice="plain">rmdir</arg>
188 <arg>--domain=<replaceable>domainname</replaceable></arg>
189 <group>
190 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
191 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
192 </group>
193 <arg>--quiet</arg>
194 <arg>--recursive</arg>
195 <arg>--username=<replaceable>username</replaceable></arg>
196 <arg>--verbose</arg>
197 <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg>
198 </cmdsynopsis>
199
200 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-rm">
201 <command>VBoxManage guestcontrol</command>
202 <group choice="req">
203 <arg choice="plain"><replaceable>uuid</replaceable></arg>
204 <arg choice="plain"><replaceable>vmname</replaceable></arg>
205 </group>
206 <arg choice="plain">rm</arg>
207 <arg>--domain=<replaceable>domainname</replaceable></arg>
208 <arg>--force</arg>
209 <group>
210 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
211 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
212 </group>
213 <arg>--quiet</arg>
214 <arg>--username=<replaceable>username</replaceable></arg>
215 <arg>--verbose</arg>
216 <arg choice="req" rep="repeat"><replaceable>guest-directory</replaceable></arg>
217 </cmdsynopsis>
218
219 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mv">
220 <command>VBoxManage guestcontrol</command>
221 <group choice="req">
222 <arg choice="plain"><replaceable>uuid</replaceable></arg>
223 <arg choice="plain"><replaceable>vmname</replaceable></arg>
224 </group>
225 <arg choice="plain">mv</arg>
226 <arg>--domain=<replaceable>domainname</replaceable></arg>
227 <group>
228 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
229 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
230 </group>
231 <arg>--quiet</arg>
232 <arg>--username=<replaceable>username</replaceable></arg>
233 <arg>--verbose</arg>
234 <arg choice="req" rep="repeat"><replaceable>source</replaceable></arg>
235 <arg choice="req"><replaceable>destination-directory</replaceable></arg>
236 </cmdsynopsis>
237
238 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mktemp">
239 <command>VBoxManage guestcontrol</command>
240 <group choice="req">
241 <arg choice="plain"><replaceable>uuid</replaceable></arg>
242 <arg choice="plain"><replaceable>vmname</replaceable></arg>
243 </group>
244 <arg choice="plain">mktemp</arg>
245 <arg>--directory</arg>
246 <arg>--domain=<replaceable>domainname</replaceable></arg>
247 <arg>--mode=<replaceable>mode</replaceable></arg>
248 <group>
249 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
250 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
251 </group>
252 <arg>--quiet</arg>
253 <arg>--secure</arg>
254 <arg>--tmpdir=<replaceable>directory-name</replaceable></arg>
255 <arg>--username=<replaceable>username</replaceable></arg>
256 <arg>--verbose</arg>
257 <arg choice="req"><replaceable>template-name</replaceable></arg>
258 </cmdsynopsis>
259
260 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-mount">
261 <command>VBoxManage guestcontrol</command>
262 <group choice="req">
263 <arg choice="plain"><replaceable>uuid</replaceable></arg>
264 <arg choice="plain"><replaceable>vmname</replaceable></arg>
265 </group>
266 <arg choice="plain">mount</arg>
267 <group>
268 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
269 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
270 </group>
271 <arg>--username=<replaceable>username</replaceable></arg>
272 <arg>--verbose</arg>
273 </cmdsynopsis>
274
275 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-fsinfo">
276 <command>VBoxManage guestcontrol</command>
277 <group choice="req">
278 <arg choice="plain"><replaceable>uuid</replaceable></arg>
279 <arg choice="plain"><replaceable>vmname</replaceable></arg>
280 </group>
281 <arg choice="plain">fsinfo</arg>
282 <arg>--domain=<replaceable>domainname</replaceable></arg>
283 <group>
284 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
285 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
286 </group>
287 <arg>--human-readable</arg>
288 <arg>--quiet</arg>
289 <arg>--total</arg>
290 <arg>--username=<replaceable>username</replaceable></arg>
291 <arg>--verbose</arg>
292 <arg choice="req"><replaceable>path</replaceable></arg>
293 </cmdsynopsis>
294
295 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-stat">
296 <command>VBoxManage guestcontrol</command>
297 <group choice="req">
298 <arg choice="plain"><replaceable>uuid</replaceable></arg>
299 <arg choice="plain"><replaceable>vmname</replaceable></arg>
300 </group>
301 <arg choice="plain">stat</arg>
302 <arg>--domain=<replaceable>domainname</replaceable></arg>
303 <group>
304 <arg choice="plain">--passwordfile=<replaceable>password-file</replaceable></arg>
305 <arg choice="plain">--password=<replaceable>password</replaceable></arg>
306 </group>
307 <arg>--quiet</arg>
308 <arg>--username=<replaceable>username</replaceable></arg>
309 <arg>--verbose</arg>
310 <arg choice="req"><replaceable>filename</replaceable></arg>
311 </cmdsynopsis>
312
313 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-list">
314 <command>VBoxManage guestcontrol</command>
315 <group choice="req">
316 <arg choice="plain"><replaceable>uuid</replaceable></arg>
317 <arg choice="plain"><replaceable>vmname</replaceable></arg>
318 </group>
319 <arg choice="plain">list</arg>
320 <group choice="req">
321 <arg choice="plain">all</arg>
322 <arg choice="plain">files</arg>
323 <arg choice="plain">processes</arg>
324 <arg choice="plain">sessions</arg>
325 </group>
326 <arg>--quiet</arg>
327 <arg>--verbose</arg>
328 </cmdsynopsis>
329
330 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closeprocess">
331 <command>VBoxManage guestcontrol</command>
332 <group choice="req">
333 <arg choice="plain"><replaceable>uuid</replaceable></arg>
334 <arg choice="plain"><replaceable>vmname</replaceable></arg>
335 </group>
336 <arg choice="plain">closeprocess</arg>
337 <group>
338 <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg>
339 <arg choice="plain">--session-name=<replaceable>name-or-pattern</replaceable></arg>
340 </group>
341 <arg>--quiet</arg>
342 <arg>--verbose</arg>
343 <arg choice="req" rep="repeat"><replaceable>PID</replaceable></arg>
344 </cmdsynopsis>
345
346 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-closesession">
347 <command>VBoxManage guestcontrol</command>
348 <group choice="req">
349 <arg choice="plain"><replaceable>uuid</replaceable></arg>
350 <arg choice="plain"><replaceable>vmname</replaceable></arg>
351 </group>
352 <arg choice="plain">closesession</arg>
353 <group>
354 <arg choice="plain">--all</arg>
355 <arg choice="plain">--session-id=<replaceable>ID</replaceable></arg>
356 <arg choice="plain">--session-name=<replaceable>name-or-pattern</replaceable></arg>
357 </group>
358 <arg>--quiet</arg>
359 <arg>--verbose</arg>
360 </cmdsynopsis>
361
362 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-updatega">
363 <command>VBoxManage guestcontrol</command>
364 <group choice="req">
365 <arg choice="plain"><replaceable>uuid</replaceable></arg>
366 <arg choice="plain"><replaceable>vmname</replaceable></arg>
367 </group>
368 <arg choice="plain">updatega</arg>
369 <arg>--quiet</arg>
370 <arg>--verbose</arg>
371 <arg>--source=<replaceable>guest-additions.ISO</replaceable></arg>
372 <arg>--wait-start</arg>
373 <arg>-- <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
374 </cmdsynopsis>
375
376 <cmdsynopsis id="synopsis-vboxmanage-guestcontrol-watch">
377 <command>VBoxManage guestcontrol</command>
378 <group choice="req">
379 <arg choice="plain"><replaceable>uuid</replaceable></arg>
380 <arg choice="plain"><replaceable>vmname</replaceable></arg>
381 </group>
382 <arg choice="plain">watch</arg>
383 <arg>--quiet</arg>
384 <arg>--verbose</arg>
385 </cmdsynopsis>
386 </refsynopsisdiv>
387
388 <refsect1 id="vboxmanage-guestcontrol-description">
389 <title>Description</title>
390 <para>
391 The <command>VBoxManage guestcontrol</command> command enables you
392 to control a guest (VM) from the host system. See
393 <xref linkend="guestadd-guestcontrol" />.
394 </para>
395 <refsect2 id="vboxmanage-guestcontrol-common">
396 <title>Common Options and Operands</title>
397 <para>
398 The following options can be used by any of the
399 <command>VBoxManage guestcontrol</command> subcommands:
400 </para>
401 <variablelist>
402 <varlistentry>
403 <term><option><replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></option></term>
404 <listitem><para>
405 Specifies the Universally Unique Identifier (UUID) or name
406 of the VM.
407 </para></listitem>
408 </varlistentry>
409 <varlistentry>
410 <term><option>--quiet</option></term>
411 <listitem><para>
412 Specifies that the command produce quieter output.
413 </para><para>
414 The short form of this option is <option>-q</option>.
415 </para></listitem>
416 </varlistentry>
417 <varlistentry>
418 <term><option>--verbose</option></term>
419 <listitem><para>
420 Specifies that the command produce more detailed output.
421 </para><para>
422 The short form of this option is <option>-v</option>.
423 </para></listitem>
424 </varlistentry>
425 </variablelist>
426 <para>
427 Some of the <command>VBoxManage guestcontrol</command>
428 subcommands require that you provide guest credentials for
429 authentication. The subcommands are:
430 <command>copyfrom</command>, <command>copyto</command>,
431 <command>fsinfo</command>,
432 <command>mkdir</command>, <command>mktemp</command>,
433 <command>mount</command>,
434 <command>mv</command>, <command>rmdir</command>,
435 <command>rm</command>, <command>run</command>,
436 <command>start</command>, and <command>stat</command>.
437 </para>
438 <para>
439 While you cannot perform anonymous executions, a user account
440 password is optional and depends on the guest's OS security
441 policy. If a user account does not have an associated password,
442 specify an empty password. On OSes such as Windows, you might
443 need to adjust the security policy to permit user accounts with
444 an empty password. In additional, global domain rules might
445 apply and therefore cannot be changed.
446 </para>
447 <para>
448 The following options are used for authentication on the guest
449 VM:
450 </para>
451 <variablelist>
452 <varlistentry>
453 <term><option>--domain=<replaceable>domainname</replaceable></option></term>
454 <listitem><para>
455 Specifies the user domain for Windows guest VMs.
456 </para></listitem>
457 </varlistentry>
458 <varlistentry>
459 <term><option>--password=<replaceable>password</replaceable></option></term>
460 <listitem><para>
461 Specifies the password for the specified user. If you do
462 not specify a password on the command line or if the
463 password file is empty, the specified user needs to have
464 an empty password.
465 </para></listitem>
466 </varlistentry>
467 <varlistentry>
468 <term><option>--passwordfile=<replaceable>filename</replaceable></option></term>
469 <listitem><para>
470 Specifies the absolute path to a file on the guest OS that
471 contains the password for the specified user. If the
472 password file is empty or if you do not specify a password
473 on the command line, the specified user needs to have an
474 empty password.
475 </para></listitem>
476 </varlistentry>
477 <varlistentry>
478 <term><option>--username=<replaceable>username</replaceable></option></term>
479 <listitem><para>
480 Specifies an existing user on the guest OS that runs the
481 process. If unspecified, the host user runs the process.
482 </para></listitem>
483 </varlistentry>
484 </variablelist>
485 </refsect2>
486 <refsect2 id="vboxmanage-guestcontrol-process-restrictions">
487 <title>Guest Process Restrictions</title>
488 <para>
489 By default, you can run up to five guest processes
490 simultaneously. If a new guest process starts and would exceed
491 this limit, the oldest not-running guest process is discarded to
492 run the new process. You cannot retrieve output from a discarded
493 guest process. If all five guest processes are active and
494 running, attempting to start a new guest process fails.
495 </para>
496 <para>
497 You can modify the guest process execution limit in two ways:
498 </para>
499 <itemizedlist>
500 <listitem><para>
501 Use the <command>VBoxManage setproperty</command> command to
502 update the
503 <literal>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</literal>
504 guest property value.
505 </para></listitem>
506 <listitem><para>
507 Use the <command>VBoxService</command> command and specify
508 the
509 <option>--control-procs-max-kept=<replaceable>value</replaceable></option>
510 option.
511 </para></listitem>
512 </itemizedlist>
513 <para>
514 After you change the limit, you must restart the guest OS.
515 </para>
516 <para>
517 You can serve an unlimited number guest processes by specifing a
518 value of <literal>0</literal>, however this action is not
519 recommended.
520 </para>
521 </refsect2>
522 <refsect2 id="vboxmanage-guestcontrol-run">
523 <title>Run a Command on the guest</title>
524 <remark role="help-copy-synopsis"/>
525 <para>
526 The <command>VBoxManage guestcontrol
527 <replaceable>vmname</replaceable> run</command> command enables
528 you to execute a program on the guest VM. Standard input,
529 standard output, and standard error are redirected from the VM
530 to the host system until the program completes.
531 </para>
532 <note>
533 <para>
534 The Windows OS imposes certain limitations for graphical
535 applications. See <xref linkend="KnownIssues" />.
536 </para>
537 </note>
538 <variablelist>
539 <varlistentry>
540 <term><option>--exe=<replaceable>path-to-executable</replaceable></option></term>
541 <listitem><para>
542 Specifies the absolute path of the executable program to
543 run on the guest VM. For example:
544 <filename>C:\Windows\System32\calc.exe</filename>.
545 </para></listitem>
546 </varlistentry>
547 <varlistentry>
548 <term><option>--cwd=<replaceable>path-to-directory</replaceable></option></term>
549 <listitem><para>
550 Specifies the absolute path of a directory in which
551 to start the program. Optional. The directory must
552 exist and be accessible to the guest user. For example:
553 <filename>C:\Users\production\work_area</filename>.
554 </para><para>
555 The short form of this option is <option>-C</option>.
556 </para></listitem>
557 </varlistentry>
558 <varlistentry>
559 <term><option>--timeout=<replaceable>msec</replaceable></option></term>
560 <listitem><para>
561 Specifies the maximum amount of time, in milliseconds,
562 that the program can run. While the program runs,
563 <command>VBoxManage</command> receives its output.
564 </para><para>
565 If you do not specify a timeout value,
566 <command>VBoxManage</command> waits indefinitely for the
567 process to end, or for an error to occur.
568 </para></listitem>
569 </varlistentry>
570 <varlistentry>
571 <term><option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option></term>
572 <listitem><para>
573 Sets, modifies, and unsets environment variables in the
574 guest VM environment.
575 </para><para>
576 When you create a guest process, it runs with the default
577 standard guest OS environment. Use this option to modify
578 environment variables in that default environment.
579 </para><para>
580 Use the
581 <option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option>
582 option to set or modify the environment variable specified
583 by <replaceable>NAME</replaceable>.
584 </para><para>
585 Use the
586 <option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option>
587 option to unset the environment variable specified by
588 <replaceable>NAME</replaceable>.
589 </para><para>
590 Ensure that any environment variable name or value that
591 includes spaces is enclosed by quotes.
592 </para><para>
593 Specify a <option>--putenv</option> option for each
594 environment variable that you want to modify.
595 </para><para>
596 The short form of this option is <option>-E</option>.
597 </para></listitem>
598 </varlistentry>
599 <varlistentry>
600 <term><option>--unquoted-args</option></term>
601 <listitem><para>
602 Disables the escaped double quoting of arguments that you
603 pass to the program. For example,
604 <literal>\"fred\"</literal>.
605 </para></listitem>
606 </varlistentry>
607 <varlistentry>
608 <term><option>--ignore-orphaned-processes</option></term>
609 <listitem><para>
610 Ignores orphaned processes. Not yet implemented.
611 </para></listitem>
612 </varlistentry>
613 <varlistentry>
614 <term><option>--profile</option></term>
615 <listitem><para>
616 Uses a shell profile to specify the environment to use.
617 Not yet implemented.
618 </para></listitem>
619 </varlistentry>
620 <varlistentry>
621 <term><option>--no-wait-stdout</option></term>
622 <listitem><para>
623 Does not wait for the guest process to end or receive its
624 exit code and any failure explanation.
625 </para></listitem>
626 </varlistentry>
627 <varlistentry>
628 <term><option>--wait-stdout</option></term>
629 <listitem><para>
630 Waits for the guest process to end to receive its exit
631 code and any failure explanation. The
632 <command>VBoxManage</command> command receives the
633 standard output of the guest process while the process
634 runs.
635 </para></listitem>
636 </varlistentry>
637 <varlistentry>
638 <term><option>--no-wait-stderr</option></term>
639 <listitem><para>
640 Does not wait for the guest process to end to receive its
641 exit code, error messages, and flags.
642 </para></listitem>
643 </varlistentry>
644 <varlistentry>
645 <term><option>--wait-stderr</option></term>
646 <listitem><para>
647 Waits for the guest process to end to receive its exit
648 code, error messages, and flags. The
649 <command>VBoxManage</command> command receives the
650 standard error of the guest process while the process
651 runs.
652 </para></listitem>
653 </varlistentry>
654 <varlistentry>
655 <term><option>--dos2unix</option></term>
656 <listitem><para>
657 Transform DOS or Windows guest output to UNIX or Linux
658 output. This transformation changes CR + LF line endings
659 to LF. Not yet implemented.
660 </para></listitem>
661 </varlistentry>
662 <varlistentry>
663 <term><option>--unix2dos</option></term>
664 <listitem><para>
665 Transform UNIX or Linux guest output to DOS or Windows
666 output. This transformation changes LF line endings to CR
667 + LF.
668 </para></listitem>
669 </varlistentry>
670 <varlistentry>
671 <term><option>--[<replaceable>argument</replaceable>...]</option></term>
672 <listitem><para>
673 Specifies the name of the program and any arguments to
674 pass to the program.
675 </para><para>
676 Ensure that any command argument that includes spaces is
677 enclosed by quotes.
678 </para></listitem>
679 </varlistentry>
680 </variablelist>
681 </refsect2>
682 <refsect2 id="vboxmanage-guestcontrol-start">
683 <title>Start a Command on the guest</title>
684 <remark role="help-copy-synopsis"/>
685 <para>
686 The <command>VBoxManage guestcontrol
687 <replaceable>vmname</replaceable> start</command> command
688 enables you to execute a guest program until it completes.
689 </para>
690 <note>
691 <para>
692 The Windows OS imposes certain limitations for graphical
693 applications. See <xref linkend="KnownIssues" />.
694 </para>
695 </note>
696 </refsect2>
697 <refsect2 id="vboxmanage-guestcontrol-copyfrom">
698 <title>Copy a file from the guest to the host.</title>
699 <remark role="help-copy-synopsis"/>
700 <para>
701 The <command>VBoxManage guestcontrol
702 <replaceable>vmname</replaceable> copyfrom</command> command
703 enables you to copy a file from the guest VM to the host system.
704 </para>
705 <variablelist>
706 <varlistentry>
707 <term><option>--dereference</option></term>
708 <listitem><para>
709 Enables following of symbolic links on the guest file
710 system.
711 </para></listitem>
712 </varlistentry>
713 <varlistentry>
714 <term><option>--no-replace</option></term>
715 <listitem><para>
716 Only copies a file if it does not exist on the host yet.
717 </para><para>
718 The short form of this option is <option>-n</option>.
719 </para></listitem>
720 </varlistentry>
721 <varlistentry>
722 <term><option>--recursive</option></term>
723 <listitem><para>
724 Recursively copies files and directories from the
725 specified guest directory to the host.
726 </para><para>
727 The short form of this option is <option>-R</option>.
728 </para></listitem>
729 </varlistentry>
730 <varlistentry>
731 <term><option>--target-directory=<replaceable>host-dst-dir</replaceable></option></term>
732 <listitem><para>
733 Specifies the absolute path of the destination directory
734 on the host system. For example,
735 <filename>C:\Temp</filename>.
736 </para></listitem>
737 </varlistentry>
738 <varlistentry>
739 <term><option>--update</option></term>
740 <listitem><para>
741 Only copies a file if the guest file is newer than on the host.
742 </para><para>
743 The short form of this option is <option>-u</option>.
744 </para></listitem>
745 </varlistentry>
746 <varlistentry>
747 <term><literal><replaceable>guest-source0</replaceable> [<replaceable>guest-source1</replaceable> [...]]</literal></term>
748 <listitem><para>
749 Specifies the absolute path of one or more files to copy
750 from the guest VM. For example,
751 <filename>C:\Windows\System32\calc.exe</filename>. You can
752 use wildcards to specify multiple files. For example,
753 <filename>C:\Windows\System*\*.dll</filename>.
754 </para></listitem>
755 </varlistentry>
756 </variablelist>
757 </refsect2>
758 <refsect2 id="vboxmanage-guestcontrol-copyto">
759 <title>Copy a file from the host to the guest.</title>
760 <remark role="help-copy-synopsis"/>
761 <para>
762 The <command>VBoxManage guestcontrol
763 <replaceable>vmname</replaceable> copyto</command> command
764 enables you to copy a file from the host system to the guest VM.
765 </para>
766 <variablelist>
767 <varlistentry>
768 <term><option>--dereference</option></term>
769 <listitem><para>
770 Enables following of symbolic links on the host system.
771 </para></listitem>
772 </varlistentry>
773 <varlistentry>
774 <term><option>--no-replace</option></term>
775 <listitem><para>
776 Only copies a file if it does not exist on the guest yet.
777 </para><para>
778 The short form of this option is <option>-n</option>.
779 </para></listitem>
780 </varlistentry>
781 <varlistentry>
782 <term><option>--recursive</option></term>
783 <listitem><para>
784 Recursively copies files and directories from the
785 specified host directory to the guest.
786 </para><para>
787 The short form of this option is <option>-R</option>.
788 </para></listitem>
789 </varlistentry>
790 <varlistentry>
791 <term><option>--target-directory=<replaceable>guest-dst-dir</replaceable></option></term>
792 <listitem><para>
793 Specifies the absolute path of the destination directory
794 on the guest. For example,
795 <filename>/home/myuser/fromhost</filename>.
796 </para></listitem>
797 </varlistentry>
798 <varlistentry>
799 <term><option>--update</option></term>
800 <listitem><para>
801 Only copies a file if the host file is newer than on the guest.
802 </para><para>
803 The short form of this option is <option>-u</option>.
804 </para></listitem>
805 </varlistentry>
806 <varlistentry>
807 <term><literal><replaceable>host-source0</replaceable> [<replaceable>host-source1</replaceable> [...]]</literal></term>
808 <listitem><para>
809 Specifies the absolute path of a file to
810 copy from the host system. For example,
811 <filename>C:\Windows\System32\calc.exe</filename>. You can
812 use wildcards to specify multiple files. For example,
813 <filename>C:\Windows\System*\*.dll</filename>.
814 </para></listitem>
815 </varlistentry>
816 </variablelist>
817 </refsect2>
818 <refsect2 id="vboxmanage-guestcontrol-fsinfo">
819 <title>Show guest filesystem information.</title>
820 <remark role="help-copy-synopsis"/>
821 <para>
822 The <command>VBoxManage guestcontrol
823 <replaceable>vmname</replaceable> fsinfo</command> command
824 enables you to show filesystem information of the guest VM.
825 </para>
826 <para>
827 An alternate form of this subcommand is <command>df</command>.
828 </para>
829 <variablelist>
830 <varlistentry>
831 <term><option>--human-readable</option></term>
832 <listitem><para>
833 Shows the disk sizes in a human readable form.
834 </para>
835 </listitem>
836 </varlistentry>
837 <varlistentry>
838 <term><option>--total</option></term>
839 <listitem><para>
840 Produces a grand total of all disk sizes.
841 </para>
842 </listitem>
843 </varlistentry>
844 <varlistentry>
845 <term><literal><replaceable>guest-path</replaceable> [<replaceable>guest-path</replaceable>...]</literal></term>
846 <listitem><para>
847 Specifies an absolute path to show guest filesystem
848 information for.
849 </para></listitem>
850 </varlistentry>
851 </variablelist>
852 </refsect2>
853 <refsect2 id="vboxmanage-guestcontrol-mkdir">
854 <title>Create a directory on the guest.</title>
855 <remark role="help-copy-synopsis"/>
856 <para>
857 The <command>VBoxManage guestcontrol
858 <replaceable>vmname</replaceable> mkdir</command> command
859 enables you to create one or more directories on the guest VM.
860 </para>
861 <para>
862 Alternate forms of this subcommand are <command>md</command>,
863 <command>createdir</command>, and
864 <command>createdirectory</command>.
865 </para>
866 <variablelist>
867 <varlistentry>
868 <term><option>--parents</option></term>
869 <listitem><para>
870 Creates any of the missing parent directories of the
871 specified directory.
872 </para><para>
873 For example, if you attempt to create the
874 <filename>D:\Foo\Bar</filename> directory and the
875 <filename>D:\Foo</filename> directory does not exist,
876 using the <option>--parents</option> creates the missing
877 <filename>D:\Foo</filename> directory. However, if you
878 attempt to create the <filename>D:\Foo\Bar</filename> and
879 do not specify the <option>--parents</option> option, the
880 command fails.
881 </para></listitem>
882 </varlistentry>
883 <varlistentry>
884 <term><option>--mode=<replaceable>mode</replaceable></option></term>
885 <listitem><para>
886 Specifies the permission mode to use for the specified
887 directory. If you specify the <option>--parents</option>
888 option, the mode is used for the associated parent
889 directories, as well. <replaceable>mode</replaceable> is a
890 four-digit octal mode such as <literal>0755</literal>.
891 </para></listitem>
892 </varlistentry>
893 <varlistentry>
894 <term><literal><replaceable>guest-dir</replaceable> [<replaceable>guest-dir</replaceable>...]</literal></term>
895 <listitem><para>
896 Specifies an absolute path of one or more directories to
897 create on the guest VM. For example,
898 <filename>D:\Foo\Bar</filename>.
899 </para><para>
900 If all of the associated parent directories do not exist
901 on the guest VM, you must specify the
902 <option>--parents</option> option.
903 </para><para>
904 You must have sufficient rights on the guest VM to create
905 the specified directory and its parent directories.
906 </para></listitem>
907 </varlistentry>
908 </variablelist>
909 </refsect2>
910 <refsect2 id="vboxmanage-guestcontrol-rmdir">
911 <title>Remove a directory from the guest.</title>
912 <remark role="help-copy-synopsis"/>
913 <para>
914 The <command>VBoxManage guestcontrol
915 <replaceable>vmname</replaceable> rmdir</command> command
916 enables you to delete the specified directory from the guest VM.
917 </para>
918 <para>
919 Alternate forms of this subcommand are
920 <command>removedir</command> and
921 <command>removedirectory</command>.
922 </para>
923 <variablelist>
924 <varlistentry>
925 <term><option>--recursive</option></term>
926 <listitem><para>
927 Recursively removes directories from the specified from
928 the guest VM.
929 </para><para>
930 The short form of this option is <option>-R</option>.
931 </para></listitem>
932 </varlistentry>
933 <varlistentry>
934 <term><literal><replaceable>guest-dir</replaceable> [<replaceable>guest-dir</replaceable>...]</literal></term>
935 <listitem><para>
936 Specifies an absolute path of one or more directories to
937 remove from the guest VM. You can use wildcards to specify
938 the directory names. For example,
939 <filename>D:\Foo\*Bar</filename>.
940 </para><para>
941 You must have sufficient rights on the guest VM to remove
942 the specified directory and its parent directories.
943 </para></listitem>
944 </varlistentry>
945 </variablelist>
946 </refsect2>
947 <refsect2 id="vboxmanage-guestcontrol-rm">
948 <title>Remove a file from the guest.</title>
949 <remark role="help-copy-synopsis"/>
950 <para>
951 The <command>VBoxManage guestcontrol
952 <replaceable>vmname</replaceable> rm</command> command enables
953 you to delete the specified files from the guest VM.
954 </para>
955 <para>
956 The alternate form of this subcommand is
957 <command>removefile</command>.
958 </para>
959 <variablelist>
960 <varlistentry>
961 <term><option>--force</option></term>
962 <listitem><para>
963 Forces the operation and overrides any confirmation
964 requests.
965 </para><para>
966 The short form of this option is <option>-f</option>.
967 </para></listitem>
968 </varlistentry>
969 <varlistentry>
970 <term><literal><replaceable>guest-file</replaceable> [<replaceable>guest-file</replaceable>...]</literal></term>
971 <listitem><para>
972 Specifies an absolute path of one or more file to remove
973 from the guest VM. You can use wildcards to specify the
974 file names. For example,
975 <filename>D:\Foo\Bar\text*.txt</filename>.
976 </para><para>
977 You must have sufficient rights on the guest VM to remove
978 the specified file.
979 </para></listitem>
980 </varlistentry>
981 </variablelist>
982 </refsect2>
983 <refsect2 id="vboxmanage-guestcontrol-mv">
984 <title>Rename a file or Directory on the guest</title>
985 <remark role="help-copy-synopsis"/>
986 <para>
987 The <command>VBoxManage guestcontrol
988 <replaceable>vmname</replaceable> mv</command> command enables
989 you to rename files and directories on the guest VM.
990 </para>
991 <para>
992 Alternate forms of this subcommand are <command>move</command>,
993 <command>ren</command>, and <command>rename</command>.
994 </para>
995 <variablelist>
996 <varlistentry>
997 <term><literal><replaceable>guest-source</replaceable> [<replaceable>guest-source</replaceable>...]</literal></term>
998 <listitem><para>
999 Specifies an absolute path of a file or a single directory
1000 to move or rename on the guest VM. You can use wildcards
1001 to specify the file names.
1002 </para><para>
1003 You must have sufficient rights on the guest VM to access
1004 the specified file or directory.
1005 </para></listitem>
1006 </varlistentry>
1007 <varlistentry>
1008 <term><replaceable>dest</replaceable></term>
1009 <listitem><para>
1010 Specifies the absolute path of the renamed file or
1011 directory, or the destination directory to which to move
1012 the files. If you move only one file,
1013 <replaceable>dest</replaceable> can be a file or a
1014 directory, otherwise <replaceable>dest</replaceable> must
1015 be a directory.
1016 </para><para>
1017 You must have sufficient rights on the guest VM to access
1018 the destination file or directory.
1019 </para></listitem>
1020 </varlistentry>
1021 </variablelist>
1022 </refsect2>
1023 <refsect2 id="vboxmanage-guestcontrol-mktemp">
1024 <title>Create a Temporary File or Directory on the guest</title>
1025 <remark role="help-copy-synopsis"/>
1026 <para>
1027 The <command>VBoxManage guestcontrol
1028 <replaceable>vmname</replaceable> mktemp</command> command
1029 enables you to create a temporary file or temporary directory on
1030 the guest VM. You can use this command to assist with the
1031 subsequent copying of files from the host system to the guest
1032 VM. By default, this command creates the file or directory in
1033 the guest VM's platform-specific <filename>temp</filename>
1034 directory.
1035 </para>
1036 <para>
1037 Alternate forms of this subcommand are
1038 <command>createtemp</command> and
1039 <command>createtemporary</command>.
1040 </para>
1041 <variablelist>
1042 <varlistentry>
1043 <term><option>--directory</option></term>
1044 <listitem><para>
1045 Creates a temporary directory that is specified by the
1046 <replaceable>template</replaceable> operand.
1047 </para></listitem>
1048 </varlistentry>
1049 <varlistentry>
1050 <term><option>--secure</option></term>
1051 <listitem><para>
1052 Enforces secure file and directory creation by setting the
1053 permission mode to <literal>0755</literal>. Any operation
1054 that cannot be performed securely fails.
1055 </para></listitem>
1056 </varlistentry>
1057 <varlistentry>
1058 <term><option>--mode=<replaceable>mode</replaceable></option></term>
1059 <listitem><para>
1060 Specifies the permission mode to use for the specified
1061 directory. <replaceable>mode</replaceable> is a four-digit
1062 octal mode such as <literal>0755</literal>.
1063 </para></listitem>
1064 </varlistentry>
1065 <varlistentry>
1066 <term><option>--tmpdir=<replaceable>directory</replaceable></option></term>
1067 <listitem><para>
1068 Specifies the absolute path of the directory on the guest
1069 VM in which to create the specified file or directory. If
1070 unspecified, <replaceable>directory</replaceable> is the
1071 platform-specific <filename>temp</filename> directory.
1072 </para></listitem>
1073 </varlistentry>
1074 <varlistentry>
1075 <term><replaceable>template</replaceable></term>
1076 <listitem><para>
1077 Specifies a template file name for the temporary file,
1078 without a directory path. The template file name must
1079 contain at least one sequence of three consecutive X
1080 characters, or must end in X.
1081 </para></listitem>
1082 </varlistentry>
1083 </variablelist>
1084 </refsect2>
1085 <refsect2 id="vboxmanage-guestcontrol-mount">
1086 <title>Shows mount points on the guest</title>
1087 <remark role="help-copy-synopsis"/>
1088 <para>
1089 The <command>VBoxManage guestcontrol
1090 <replaceable>vmname</replaceable> mount</command> command
1091 enables you to the current mount points on
1092 the guest VM. For Windows guests this shows the mapped drives.
1093 </para>
1094 </refsect2>
1095 <refsect2 id="vboxmanage-guestcontrol-stat">
1096 <title>Show a file or File System Status on the guest</title>
1097 <remark role="help-copy-synopsis"/>
1098 <para>
1099 The <command>VBoxManage guestcontrol
1100 <replaceable>vmname</replaceable> stat</command> command enables
1101 you to show the status of files or file systems on the guest VM.
1102 </para>
1103 <variablelist>
1104 <varlistentry>
1105 <term><literal><replaceable>file</replaceable> [<replaceable>file</replaceable> ...]</literal></term>
1106 <listitem><para>
1107 Specifies an absolute path of a file or file system on the
1108 guest VM. For example,
1109 <filename>/home/foo/a.out</filename>.
1110 </para><para>
1111 You must have sufficient rights on the guest VM to access
1112 the specified files or file systems.
1113 </para></listitem>
1114 </varlistentry>
1115 </variablelist>
1116 </refsect2>
1117 <refsect2 id="vboxmanage-guestcontrol-list">
1118 <title>List the Configuration and Status Information for a Guest Virtual
1119 Machine</title>
1120 <remark role="help-copy-synopsis"/>
1121 <para>
1122 The <command>VBoxManage guestcontrol
1123 <replaceable>vmname</replaceable> list</command> command enables
1124 you to list guest control configuration and status information.
1125 For example, the output shows open guest sessions, guest
1126 processes, and files.
1127 </para>
1128 <variablelist>
1129 <varlistentry>
1130 <term><literal>all</literal>|<literal>sessions</literal>|<literal>processes</literal>|<literal>files</literal></term>
1131 <listitem><para>
1132 Indicates the type of information to show.
1133 <literal>all</literal> shows all available data,
1134 <literal>sessions</literal> shows guest sessions,
1135 <literal>processes</literal> shows processes, and
1136 <literal>files</literal> shows files.
1137 </para></listitem>
1138 </varlistentry>
1139 </variablelist>
1140 </refsect2>
1141 <refsect2 id="vboxmanage-guestcontrol-closeprocess">
1142 <title>Terminate a Process in a guest Session</title>
1143 <remark role="help-copy-synopsis"/>
1144 <para>
1145 The <command>VBoxManage guestcontrol
1146 <replaceable>vmname</replaceable> closeprocess</command> command
1147 enables you to terminate a guest process that runs in a guest
1148 session. Specify the process by using a process identifier (PID)
1149 and the session by using the session ID or name.
1150 </para>
1151 <variablelist>
1152 <varlistentry>
1153 <term><option>--session-id=<replaceable>ID</replaceable></option></term>
1154 <listitem><para>
1155 Specifies the ID of the guest session.
1156 </para></listitem>
1157 </varlistentry>
1158 <varlistentry>
1159 <term><option>--session-name=<replaceable>name</replaceable>|<replaceable>pattern</replaceable></option></term>
1160 <listitem><para>
1161 Specifies the name of the guest session. Use a pattern
1162 that contains wildcards to specify multiple sessions.
1163 </para></listitem>
1164 </varlistentry>
1165 <varlistentry>
1166 <term><literal><replaceable>PID</replaceable> [<replaceable>PID</replaceable> ...]</literal></term>
1167 <listitem><para>
1168 Specifies the list of PIDs of guest processes to
1169 terminate.
1170 </para></listitem>
1171 </varlistentry>
1172 </variablelist>
1173 </refsect2>
1174 <refsect2 id="vboxmanage-guestcontrol-closesession">
1175 <title>Close a guest Session</title>
1176 <remark role="help-copy-synopsis"/>
1177 <para>
1178 The <command>VBoxManage guestcontrol
1179 <replaceable>vmname</replaceable> closesession</command> command
1180 enables you to close a guest session. Specify the guest session
1181 either by session ID or by name.
1182 </para>
1183 <variablelist>
1184 <varlistentry>
1185 <term><option>--session-id=<replaceable>ID</replaceable></option></term>
1186 <listitem><para>
1187 Specifies the ID of the guest session.
1188 </para></listitem>
1189 </varlistentry>
1190 <varlistentry>
1191 <term><option>--session-name=<replaceable>name</replaceable>|<replaceable>pattern</replaceable></option></term>
1192 <listitem><para>
1193 Specifies the name of the guest session. Use a pattern
1194 that contains wildcards to specify multiple sessions.
1195 </para></listitem>
1196 </varlistentry>
1197 <varlistentry>
1198 <term><option>--all</option></term>
1199 <listitem><para>
1200 Closes all guest sessions.
1201 </para></listitem>
1202 </varlistentry>
1203 </variablelist>
1204 </refsect2>
1205 <refsect2 id="vboxmanage-guestcontrol-updatega">
1206 <title>Update the Guest Additions Software on the guest</title>
1207 <remark role="help-copy-synopsis"/>
1208 <para>
1209 The <command>VBoxManage guestcontrol
1210 <replaceable>vmname</replaceable> updatega</command> command
1211 enables you to update the Guest Additions software installed in
1212 the specified guest VM.
1213 </para>
1214 <para>
1215 Alternate forms of this subcommand are
1216 <command>updateadditions</command> and
1217 <command>updateguestadditions</command>.
1218 </para>
1219 <variablelist>
1220 <varlistentry>
1221 <term><option>--source=<replaceable>new-iso-path</replaceable></option></term>
1222 <listitem><para>
1223 Specifies the absolute path of the Guest Additions update
1224 <filename>.ISO</filename> file on the guest VM.
1225 </para></listitem>
1226 </varlistentry>
1227 <varlistentry>
1228 <term><option>--reboot</option></term>
1229 <listitem><para>
1230 Automatically reboots the guest after a successful Guest Additions
1231 update.
1232 </para></listitem>
1233 </varlistentry>
1234 <varlistentry>
1235 <term><option>--timeout=<replaceable>ms</replaceable></option></term>
1236 <listitem><para>
1237 Sets the timeout (in ms) to wait for the overall Guest Additions update
1238 to complete. By default no timeout is being used.
1239 </para></listitem>
1240 </varlistentry>
1241 <varlistentry>
1242 <term><option>--verify</option></term>
1243 <listitem><para>
1244 Verifies whether the Guest Additions were updated successfully after
1245 a successful installation. A guest reboot is mandatory.
1246 </para></listitem>
1247 </varlistentry>
1248 <varlistentry>
1249 <term><option>--wait-ready</option></term>
1250 <listitem><para>
1251 Waits for the current Guest Additions being ready to handle the
1252 Guest Additions update.
1253 </para>
1254 </listitem>
1255 </varlistentry>
1256 <varlistentry>
1257 <term><option>--wait-start</option></term>
1258 <listitem><para>
1259 Starts the <command>VBoxManage</command> update process on
1260 the guest VM and then waits for the Guest Additions update
1261 to begin before terminating the
1262 <command>VBoxManage</command> process.
1263 </para><para>
1264 By default, the <command>VBoxManage</command> command
1265 waits for the Guest Additions update to complete before it
1266 terminates. Use this option when a running
1267 <command>VBoxManage</command> process affects the
1268 interaction between the installer and the guest OS.
1269 </para></listitem>
1270 </varlistentry>
1271 <varlistentry>
1272 <term><option>-- <replaceable>argument</replaceable> [<replaceable>argument</replaceable> ...]</option></term>
1273 <listitem><para>
1274 Specifies optional command-line arguments to pass to the
1275 Guest Additions updater. You might use the
1276 <option>--</option> option to pass the appropriate updater
1277 arguments to retrofit features that are not yet installed.
1278 </para><para>
1279 Ensure that any command argument that includes spaces is
1280 enclosed by quotes.
1281 </para></listitem>
1282 </varlistentry>
1283 </variablelist>
1284 </refsect2>
1285 <refsect2 id="vboxmanage-guestcontrol-waitrunlevel">
1286 <title>Wait for a guest run level</title>
1287 <para>
1288 The <command>VBoxManage guestcontrol
1289 <replaceable>vmname</replaceable> waitrunlevel</command> command
1290 enables you to wait for a guest run level being reached.
1291 </para>
1292 <variablelist>
1293 <varlistentry>
1294 <term><option>--timeout=<replaceable>ms</replaceable></option></term>
1295 <listitem><para>
1296 Sets the timeout (in ms) to wait for reaching the run level.
1297 By default no timeout is being used.
1298 </para></listitem>
1299 </varlistentry>
1300 <varlistentry>
1301 <term><option><replaceable>system</replaceable>|<replaceable>userland</replaceable>|<replaceable>desktop</replaceable></option></term>
1302 <listitem><para>
1303 Specifies the run level to wait for.
1304 </para></listitem>
1305 </varlistentry>
1306 </variablelist>
1307 </refsect2>
1308 <refsect2 id="vboxmanage-guestcontrol-watch">
1309 <title>Show Current Guest Control Activity</title>
1310 <remark role="help-copy-synopsis"/>
1311 <para>
1312 The <command>VBoxManage guestcontrol
1313 <replaceable>vmname</replaceable> watch</command> command
1314 enables you to show current guest control activity.
1315 </para>
1316 </refsect2>
1317 </refsect1>
1318
1319 <refsect1 id="vboxmanage-guestcontrol-examples">
1320 <title>Examples</title>
1321 <remark role="help-scope" condition="GLOBAL"/>
1322 <para>
1323 The following <command>VBoxManage guestcontrol run</command>
1324 command executes the <command>ls -l /usr</command> command on the
1325 <literal>My OL VM</literal> Oracle Linux VM as the
1326 <literal>user1</literal> user.
1327 </para>
1328<screen>
1329$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/bin/ls" \
1330--username user1 --passwordfile pw.txt --wait-stdout -- -l /usr
1331</screen>
1332 <para>
1333 The <option>--exe</option> option specifies the absolute path of
1334 the command to run in the guest VM, <filename>/bin/ls</filename>.
1335 Use the <option>--</option> option to pass any arguments that
1336 follow it to the <command>ls</command> command.
1337 </para>
1338 <para>
1339 Use the <option>--username</option> option to specify the user
1340 name, <literal>user1</literal> and use the
1341 <option>--passwordfile</option> option to specify the name of a
1342 file that includes the password for the <literal>user1</literal>
1343 user, <filename>pw.txt</filename>.
1344 </para>
1345 <para>
1346 The <option>--wait-stdout</option> option waits for the
1347 <command>ls</command> guest process to complete before providing
1348 the exit code and the command output. The
1349 <option>--nologo</option> option suppresses the output of the logo
1350 information.
1351 </para>
1352 <para>
1353 The following <command>VBoxManage guestcontrol run</command>
1354 command executes the <command>ipconfig</command> command on the
1355 <literal>My Win VM</literal> Windows VM as the
1356 <literal>user1</literal> user. Standard input, standard output,
1357 and standard error are redirected from the VM to the host system
1358 until the program completes.
1359 </para>
1360<screen>
1361$ VBoxManage --nologo guestcontrol "My Win VM" run \
1362--exe "c:\\windows\\system32\\ipconfig.exe" \
1363--username user1 --passwordfile pw.txt --wait-stdout
1364</screen>
1365 <para>
1366 The <option>--exe</option> specifies the absolute path of command
1367 to run in the guest VM,
1368 <filename>c:\windows\system32\ipconfig.exe</filename>. The double
1369 backslashes shown in this example are required only on UNIX host
1370 systems.
1371 </para>
1372 <para>
1373 Use the <option>--username</option> option to specify the user
1374 name, <literal>user1</literal> and use the
1375 <option>--passwordfile</option> option to specify the name of a
1376 file that includes the password for the <literal>user1</literal>
1377 user, <filename>pw.txt</filename>.
1378 </para>
1379 <para>
1380 The <option>--wait-stdout</option> option waits for the
1381 <command>ls</command> guest process to complete before providing
1382 the exit code and the command output. The
1383 <option>--nologo</option> option to suppress the output of the
1384 logo information.
1385 </para>
1386 <para>
1387 The following <command>VBoxManage guestcontrol start</command>
1388 command executes the <command>ls -l /usr</command> command on the
1389 <literal>My OL VM</literal> Oracle Linux VM until the program
1390 completes.
1391 </para>
1392<screen>
1393$ VBoxManage --nologo guestcontrol "My Win VM" start \
1394--exe "c:\\windows\\system32\\ipconfig.exe" \
1395--username user1 --passwordfile pw.txt
1396</screen>
1397 <para>
1398 The following <command>VBoxManage guestcontrol run</command>
1399 command executes a <command>/usr/bin/busybox -l /usr</command>
1400 command on the <literal>My OL VM</literal> Oracle Linux VM as the
1401 <literal>user1</literal> user, explicitly using <literal>ls</literal>
1402 as argument 0.
1403 </para>
1404<screen>
1405$ VBoxManage --nologo guestcontrol "My OL VM" run --exe "/usr/bin/busybox" \
1406--username user1 --passwordfile pw.txt --wait-stdout --arg0 ls -- -l /usr
1407</screen>
1408 <para>
1409 The <option>--exe</option> option specifies the absolute path of
1410 the command to run in the guest VM, <filename>/usr/bin/busybox</filename>.
1411 Use the <option>--</option> option to pass any arguments that
1412 follow it to the <command>busybox</command> command.
1413 </para>
1414 <para>
1415 Use the <option>--username</option> option to specify the user
1416 name, <literal>user1</literal> and use the
1417 <option>--passwordfile</option> option to specify the name of a
1418 file that includes the password for the <literal>user1</literal>
1419 user, <filename>pw.txt</filename>.
1420 </para>
1421 <para>
1422 The <option>--wait-stdout</option> option waits for the
1423 <command>ls</command> guest process to complete before providing
1424 the exit code and the command output. The
1425 <option>--nologo</option> option suppresses the output of the logo
1426 information.
1427 </para>
1428 <para>
1429 The <option>--arg0</option> option explicitly specifies the argument 0
1430 to use for the command to execute.
1431 </para>
1432 <para>
1433 The default behavior of argument 0 is to either use
1434 the value from <option>--exe</option>, or, if not set, the first
1435 value passed after <option>--</option>.
1436 </para>
1437 </refsect1>
1438</refentry>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette