VirtualBox

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

最後變更 在這個檔案從102095是 99778,由 vboxsync 提交於 22 月 前

Guest Control/VBoxManage: Cleaned up command synopsis a bit more and removed the (for a lot of users) confusing "program/arg0". bugref:9320

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

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