Changeset 35285 in vbox
- Timestamp:
- Dec 22, 2010 7:54:13 AM (14 years ago)
- File:
-
- 1 edited
-
trunk/doc/manual/en_US/user_VBoxManage.xml (modified) (6 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/manual/en_US/user_VBoxManage.xml
r35278 r35285 1397 1397 cable on a physical machine, and should be avoided if possible.</para> 1398 1398 </sect1> 1399 1400 <sect1> 1401 <title>VBoxManage adoptstate</title> 1402 1403 <para>If you have a saved state file (<computeroutput>.sav</computeroutput>) 1404 that is seperate from the VM configuration, you can use this command to 1405 "adopt" the file. This will change the VM to saved state and when you 1406 start it, VirtualBox will attempt to restore it from the saved state file 1407 you indicated. This command should only be used in special setups.</para> 1408 </sect1> 1399 1409 1400 1410 <sect1> … … 1443 1453 </sect1> 1444 1454 1445 <sect1 id="vboxmanage-storagectl"> 1446 <title>VBoxManage storagectl</title> 1447 1448 <para>This command attaches/modifies/removes a storage controller. After 1449 this, virtual media can be attached to the controller with the 1450 <computeroutput>storageattach</computeroutput> command (see the next 1451 section).</para> 1452 1453 <para>The syntax is as follows:</para> 1454 1455 <screen>VBoxManage storagectl <uuid|vmname> 1456 --name <name> 1457 [--add <ide/sata/scsi/floppy>] 1458 [--controller <LsiLogic/BusLogic/IntelAhci/PIIX3/ 1459 PIIX4/ICH6/I8207>] 1460 [--sataideemulation<1-4> <1-30>] 1461 [--sataportcount <1-30>] 1462 [--hostiocache on|off] 1463 [--remove]</screen> 1464 1465 <para>where the parameters mean: <glosslist> 1466 <glossentry> 1467 <glossterm>uuid|vmname</glossterm> 1468 1469 <glossdef> 1470 <para>The VM UUID or VM Name. Mandatory.</para> 1471 </glossdef> 1472 </glossentry> 1473 1474 <glossentry> 1475 <glossterm>name</glossterm> 1476 1477 <glossdef> 1478 <para>Name of the storage controller. Mandatory.</para> 1479 </glossdef> 1480 </glossentry> 1481 1482 <glossentry> 1483 <glossterm>add</glossterm> 1484 1485 <glossdef> 1486 <para>Define the type of the system bus to which the storage 1487 controller must be connected.</para> 1488 </glossdef> 1489 </glossentry> 1490 1491 <glossentry> 1492 <glossterm>controller</glossterm> 1493 1494 <glossdef> 1495 <para>Allows to choose the type of chipset being emulated for the 1496 given storage controller.</para> 1497 </glossdef> 1498 </glossentry> 1499 1500 <glossentry> 1501 <glossterm>sataideemulation</glossterm> 1502 1503 <glossdef> 1504 <para>This specifies which SATA ports should operate in IDE 1505 emulation mode. As explained in <xref 1506 linkend="harddiskcontrollers" />, by default, this is the case for 1507 SATA ports 1-4; with this command, you can map four IDE channels 1508 to any of the 30 supported SATA ports.</para> 1509 </glossdef> 1510 </glossentry> 1511 1512 <glossentry> 1513 <glossterm>sataportcount</glossterm> 1514 1515 <glossdef> 1516 <para>This determines how many ports the SATA controller should 1517 support.</para> 1518 </glossdef> 1519 </glossentry> 1520 1521 <glossentry> 1522 <glossterm>hostiocache</glossterm> 1523 1524 <glossdef> 1525 <para>Configures the use of the host I/O cache for all disk images 1526 attached to this storage controller. For details, please see <xref 1527 linkend="iocaching" />.</para> 1528 </glossdef> 1529 </glossentry> 1530 1531 <glossentry> 1532 <glossterm>remove</glossterm> 1533 1534 <glossdef> 1535 <para>Removes the storage controller from the VM config.</para> 1536 </glossdef> 1537 </glossentry> 1538 </glosslist></para> 1455 <sect1 id="vboxmanage-closemedium"> 1456 <title>VBoxManage closemedium</title> 1457 1458 <para>This commands removes a hard disk, DVD or floppy image from a 1459 VirtualBox media registry.<footnote> 1460 <para>Before VirtualBox 4.0, it was necessary to call VBoxManage 1461 openmedium before a medium could be attached to a virtual machine; 1462 that call "registered" the medium with the global VirtualBox media 1463 registry. With VirtualBox 4.0 this is no longer necessary; media are 1464 added to media registries automatically. The "closemedium" call has 1465 been retained, however, to allow for explicitly removing a medium from 1466 a registry.</para> 1467 </footnote></para> 1468 1469 <para>Optionally, you can request that the image be deleted. You will get 1470 appropriate diagnostics that the deletion failed, however the image will 1471 become unregistered in any case.</para> 1539 1472 </sect1> 1540 1473 … … 1790 1723 </glosslist></para> 1791 1724 </sect1> 1725 1726 <sect1 id="vboxmanage-storagectl"> 1727 <title>VBoxManage storagectl</title> 1728 1729 <para>This command attaches/modifies/removes a storage controller. After 1730 this, virtual media can be attached to the controller with the 1731 <computeroutput>storageattach</computeroutput> command (see the next 1732 section).</para> 1733 1734 <para>The syntax is as follows:</para> 1735 1736 <screen>VBoxManage storagectl <uuid|vmname> 1737 --name <name> 1738 [--add <ide/sata/scsi/floppy>] 1739 [--controller <LsiLogic/BusLogic/IntelAhci/PIIX3/ 1740 PIIX4/ICH6/I8207>] 1741 [--sataideemulation<1-4> <1-30>] 1742 [--sataportcount <1-30>] 1743 [--hostiocache on|off] 1744 [--remove]</screen> 1745 1746 <para>where the parameters mean: <glosslist> 1747 <glossentry> 1748 <glossterm>uuid|vmname</glossterm> 1749 1750 <glossdef> 1751 <para>The VM UUID or VM Name. Mandatory.</para> 1752 </glossdef> 1753 </glossentry> 1754 1755 <glossentry> 1756 <glossterm>name</glossterm> 1757 1758 <glossdef> 1759 <para>Name of the storage controller. Mandatory.</para> 1760 </glossdef> 1761 </glossentry> 1762 1763 <glossentry> 1764 <glossterm>add</glossterm> 1765 1766 <glossdef> 1767 <para>Define the type of the system bus to which the storage 1768 controller must be connected.</para> 1769 </glossdef> 1770 </glossentry> 1771 1772 <glossentry> 1773 <glossterm>controller</glossterm> 1774 1775 <glossdef> 1776 <para>Allows to choose the type of chipset being emulated for the 1777 given storage controller.</para> 1778 </glossdef> 1779 </glossentry> 1780 1781 <glossentry> 1782 <glossterm>sataideemulation</glossterm> 1783 1784 <glossdef> 1785 <para>This specifies which SATA ports should operate in IDE 1786 emulation mode. As explained in <xref 1787 linkend="harddiskcontrollers" />, by default, this is the case for 1788 SATA ports 1-4; with this command, you can map four IDE channels 1789 to any of the 30 supported SATA ports.</para> 1790 </glossdef> 1791 </glossentry> 1792 1793 <glossentry> 1794 <glossterm>sataportcount</glossterm> 1795 1796 <glossdef> 1797 <para>This determines how many ports the SATA controller should 1798 support.</para> 1799 </glossdef> 1800 </glossentry> 1801 1802 <glossentry> 1803 <glossterm>hostiocache</glossterm> 1804 1805 <glossdef> 1806 <para>Configures the use of the host I/O cache for all disk images 1807 attached to this storage controller. For details, please see <xref 1808 linkend="iocaching" />.</para> 1809 </glossdef> 1810 </glossentry> 1811 1812 <glossentry> 1813 <glossterm>remove</glossterm> 1814 1815 <glossdef> 1816 <para>Removes the storage controller from the VM config.</para> 1817 </glossdef> 1818 </glossentry> 1819 </glosslist></para> 1820 </sect1> 1792 1821 1793 1822 <sect1> … … 2081 2110 "convertfromraw" command.</para> 2082 2111 </note></para> 2083 </sect1>2084 2085 <sect1 id="vboxmanage-closemedium">2086 <title>VBoxManage closemedium</title>2087 2088 <para>This commands removes a hard disk, DVD or floppy image from a2089 VirtualBox media registry.<footnote>2090 <para>Before VirtualBox 4.0, it was necessary to call VBoxManage2091 openmedium before a medium could be attached to a virtual machine;2092 that call "registered" the medium with the global VirtualBox media2093 registry. With VirtualBox 4.0 this is no longer necessary; media are2094 added to media registries automatically. The "closemedium" call has2095 been retained, however, to allow for explicitly removing a medium from2096 a registry.</para>2097 </footnote></para>2098 2099 <para>Optionally, you can request that the image be deleted. You will get2100 appropriate diagnostics that the deletion failed, however the image will2101 become unregistered in any case.</para>2102 2112 </sect1> 2103 2113 … … 2244 2254 </sect1> 2245 2255 2256 <sect1 id="vboxmanage-guestproperty"> 2257 <title>VBoxManage guestproperty</title> 2258 2259 <para>The "guestproperty" commands allow you to get or set properties of a 2260 running virtual machine. Please see <xref linkend="guestadd-guestprops" /> 2261 for an introduction. As explained there, guest properties are arbitrary 2262 key/value string pairs which can be written to and read from by either the 2263 guest or the host, so they can be used as a low-volume communication 2264 channel for strings, provided that a guest is running and has the Guest 2265 Additions installed. In addition, a number of values whose keys begin with 2266 "/VirtualBox/" are automatically set and maintained by the Guest 2267 Additions.</para> 2268 2269 <para>The following subcommands are available (where 2270 <computeroutput><vm></computeroutput>, in each case, can either be a 2271 VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist> 2272 <listitem> 2273 <para><computeroutput>enumerate <vm> [--patterns 2274 <pattern>]</computeroutput>: This lists all the guest 2275 properties that are available for the given VM, including the value. 2276 This list will be very limited if the guest's service process cannot 2277 be contacted, e.g. because the VM is not running or the Guest 2278 Additions are not installed.</para> 2279 2280 <para>If <computeroutput>--patterns <pattern></computeroutput> 2281 is specified, it acts as a filter to only list properties that match 2282 the given pattern. The pattern can contain the following wildcard 2283 characters:<itemizedlist> 2284 <listitem> 2285 <para><computeroutput>*</computeroutput> (asterisk): 2286 represents any number of characters; for example, 2287 "<computeroutput>/VirtualBox*</computeroutput>" would match 2288 all properties beginning with "/VirtualBox".</para> 2289 </listitem> 2290 2291 <listitem> 2292 <para><computeroutput>?</computeroutput> (question mark): 2293 represents a single arbitrary character; for example, 2294 "<computeroutput>fo?</computeroutput>" would match both "foo" 2295 and "for".</para> 2296 </listitem> 2297 2298 <listitem> 2299 <para><computeroutput>|</computeroutput> (pipe symbol): can be 2300 used to specify multiple alternative patterns; for example, 2301 "<computeroutput>s*|t*</computeroutput>" would match anything 2302 starting with either "s" or "t".</para> 2303 </listitem> 2304 </itemizedlist></para> 2305 </listitem> 2306 2307 <listitem> 2308 <para><computeroutput>get <vm></computeroutput>: This 2309 retrieves the value of a single property only. If the property 2310 cannot be found (e.g. because the guest is not running), this will 2311 print "No value set!".</para> 2312 </listitem> 2313 2314 <listitem> 2315 <para><computeroutput>set <vm> <property> [<value> 2316 [--flags <flags>]]</computeroutput>: This allows you to set a 2317 guest property by specifying the key and value. If 2318 <computeroutput><value></computeroutput> is omitted, the 2319 property is deleted. With <computeroutput>--flags</computeroutput> 2320 you can optionally specify additional behavior (you can combine 2321 several by separating them with commas):<itemizedlist> 2322 <listitem> 2323 <para><computeroutput>TRANSIENT</computeroutput>: the value 2324 will not be stored with the VM data when the VM exits;</para> 2325 </listitem> 2326 2327 <listitem> 2328 <para><computeroutput>RDONLYGUEST</computeroutput>: the value 2329 can only be changed by the host, but the guest can only read 2330 it;</para> 2331 </listitem> 2332 2333 <listitem> 2334 <para><computeroutput>RDONLYHOST</computeroutput>: reversely, 2335 the value can only be changed by the guest, but the host can 2336 only read it;</para> 2337 </listitem> 2338 2339 <listitem> 2340 <para><computeroutput>READONLY</computeroutput>: a combination 2341 of the two, the value cannot be changed at all.</para> 2342 </listitem> 2343 </itemizedlist></para> 2344 </listitem> 2345 2346 <listitem> 2347 <para><computeroutput>wait <vm> <pattern> --timeout 2348 <timeout></computeroutput>: This waits for a particular value 2349 described by "pattern" to change or to be deleted or created. The 2350 pattern rules are the same as for the "enumerate" subcommand 2351 above.</para> 2352 </listitem> 2353 </itemizedlist></para> 2354 </sect1> 2355 2356 <sect1 id="vboxmanage-guestcontrol"> 2357 <title>VBoxManage guestcontrol</title> 2358 2359 <para>The "guestcontrol" commands allow you to control certain things 2360 inside a guest from the host. Please see <xref 2361 linkend="guestadd-guestcontrol" /> for an introduction.</para> 2362 2363 <para>Generally, the syntax is as follows:</para> 2364 2365 <screen>VBoxManage guestcontrol <command></screen> 2366 2367 <para>The following subcommands are available (where 2368 <computeroutput><vm></computeroutput>, in each case, can either be a 2369 VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist> 2370 <listitem> 2371 <para><computeroutput>execute</computeroutput>, which allows for 2372 executing a program/script (process) which is already installed and 2373 runnable on the guest. This command only works while a VM is up and 2374 running and has the following syntax:</para> 2375 2376 <screen>VBoxManage guestcontrol exec[ute] <vmname>|<uuid> 2377 <path to program> 2378 --username <name> --password <password> 2379 [--arguments "<arguments>"] 2380 [--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"] 2381 [--flags <flags>] [--timeout <msec>] 2382 [--verbose] [--wait-for exit,stdout,stderr||]</screen> 2383 2384 <para>where the parameters mean: <glosslist> 2385 <glossentry> 2386 <glossterm>uuid|vmname</glossterm> 2387 2388 <glossdef> 2389 <para>The VM UUID or VM name. Mandatory.</para> 2390 </glossdef> 2391 </glossentry> 2392 2393 <glossentry> 2394 <glossterm>path to program</glossterm> 2395 2396 <glossdef> 2397 <para>Absolute path and process name of process to execute 2398 in the guest, e.g. 2399 <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para> 2400 </glossdef> 2401 </glossentry> 2402 2403 <glossentry> 2404 <glossterm>--arguments "<arguments>"</glossterm> 2405 2406 <glossdef> 2407 <para>One or more arguments to pass to the process being 2408 executed.</para> 2409 2410 <para>Arguments containing spaces must be enclosed in 2411 quotation marks. More than one 2412 <computeroutput>--arguments</computeroutput> at a time can 2413 be specified to keep the command line tidy.</para> 2414 </glossdef> 2415 </glossentry> 2416 2417 <glossentry> 2418 <glossterm>--environment 2419 "<NAME>=<VALUE>"</glossterm> 2420 2421 <glossdef> 2422 <para>One or more environment variables to be set or 2423 unset.</para> 2424 2425 <para>By default, the new process in the guest will be 2426 created with the standard environment of the guest OS. This 2427 option allows for modifying that environment. To set/modify 2428 a variable, a pair of 2429 <computeroutput>NAME=VALUE</computeroutput> must be 2430 specified; to unset a certain variable, the name with no 2431 value must set, e.g. 2432 <computeroutput>NAME=</computeroutput>.</para> 2433 2434 <para>Arguments containing spaces must be enclosed in 2435 quotation marks. More than one 2436 <computeroutput>--environment</computeroutput> at a time can 2437 be specified to keep the command line tidy.</para> 2438 </glossdef> 2439 </glossentry> 2440 2441 <glossentry> 2442 <glossterm>--flags <flags></glossterm> 2443 2444 <glossdef> 2445 <para>Additional flags to set. This is not used at the 2446 moment.</para> 2447 </glossdef> 2448 </glossentry> 2449 2450 <glossentry> 2451 <glossterm>--timeout <msec></glossterm> 2452 2453 <glossdef> 2454 <para>Value (in milliseconds) that specifies the time how 2455 long the started process is allowed to run and how long 2456 VBoxManage waits for getting output from that process. If no 2457 timeout is specified, VBoxManage will wait forever until the 2458 started process ends or an error occured.</para> 2459 </glossdef> 2460 </glossentry> 2461 2462 <glossentry> 2463 <glossterm>--username <name></glossterm> 2464 2465 <glossdef> 2466 <para>Name of the user the process should run under. This 2467 user must exist on the guest OS.</para> 2468 </glossdef> 2469 </glossentry> 2470 2471 <glossentry> 2472 <glossterm>--password <password></glossterm> 2473 2474 <glossdef> 2475 <para>Password of the user account specified with 2476 <computeroutput>--username</computeroutput>. If not given, 2477 an empty password is assumed.</para> 2478 </glossdef> 2479 </glossentry> 2480 2481 <glossentry> 2482 <glossterm>--verbose</glossterm> 2483 2484 <glossdef> 2485 <para>Tells VBoxManage to be more verbose.</para> 2486 </glossdef> 2487 </glossentry> 2488 2489 <glossentry> 2490 <glossterm>--wait-for <action></glossterm> 2491 2492 <glossdef> 2493 <para>Tells VBoxManage to wait for a certain action to 2494 happen and react to it. The following actions are available: 2495 <glosslist> 2496 <glossentry> 2497 <glossterm>exit</glossterm> 2498 2499 <glossdef> 2500 <para>Waits until the process ends and outputs its 2501 exit code along with the exit reason/flags.</para> 2502 </glossdef> 2503 </glossentry> 2504 2505 <glossentry> 2506 <glossterm>stdout or stderr</glossterm> 2507 2508 <glossdef> 2509 <para>Waits until the process ends and outputs its 2510 exit code along with the exit reason/flags. After 2511 that VBoxManage retrieves the output collected from 2512 the guest process's stdout and stderr.</para> 2513 </glossdef> 2514 </glossentry> 2515 </glosslist></para> 2516 </glossdef> 2517 </glossentry> 2518 </glosslist></para> 2519 2520 <para><note> 2521 <para>On Windows there are certain limitations for graphical 2522 applications; please see <xref linkend="KnownIssues" /> for more 2523 information.</para> 2524 </note> Examples: <screen>VBoxManage --nologo guestcontrol execute "My VM" "/bin/ls" --arguments "-l /usr" 2525 --username foo --password bar --wait-for stdout</screen> <screen>VBoxManage --nologo guestcontrol execute "My VM" "c:\\windows\\system32\\ipconfig.exe" 2526 --username foo --password bar --wait-for stdout</screen> Note that 2527 the double backslashes in the second example are only required on 2528 Unix hosts.</para> 2529 </listitem> 2530 2531 <listitem> 2532 <para><computeroutput>copyto</computeroutput>, which allows copying 2533 files from the host to the guest (only with installed Guest 2534 Additions 4.0 and later).</para> 2535 2536 <screen>VBoxManage copyto|cp <vmname>|<uuid> 2537 <source on host> <destination on guest> 2538 --username <name> --password <password> 2539 [--dryrun] [--follow] [--recursive] [--verbose]</screen> 2540 2541 <para>where the parameters mean: <glosslist> 2542 <glossentry> 2543 <glossterm>uuid|vmname</glossterm> 2544 2545 <glossdef> 2546 <para>The VM UUID or VM name. Mandatory.</para> 2547 </glossdef> 2548 </glossentry> 2549 2550 <glossentry> 2551 <glossterm>source on host</glossterm> 2552 2553 <glossdef> 2554 <para>Absolute path of source file(s) on host to copy over 2555 to the guest, e.g. 2556 <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. 2557 This also can be a wildcard expression, e.g. 2558 <computeroutput>C:\Windows\System32\*.dll</computeroutput></para> 2559 </glossdef> 2560 </glossentry> 2561 2562 <glossentry> 2563 <glossterm>destination on guest</glossterm> 2564 2565 <glossdef> 2566 <para>Absolute destination path on the guest, e.g. 2567 <computeroutput>C:\Temp</computeroutput></para> 2568 </glossdef> 2569 </glossentry> 2570 2571 <glossentry> 2572 <glossterm>--username <name></glossterm> 2573 2574 <glossdef> 2575 <para>Name of the user the copy process should run under. 2576 This user must exist on the guest OS.</para> 2577 </glossdef> 2578 </glossentry> 2579 2580 <glossentry> 2581 <glossterm>--password <password></glossterm> 2582 2583 <glossdef> 2584 <para>Password of the user account specified with 2585 <computeroutput>--username</computeroutput>. If not given, 2586 an empty password is assumed.</para> 2587 </glossdef> 2588 </glossentry> 2589 2590 <glossentry> 2591 <glossterm>--dryrun</glossterm> 2592 2593 <glossdef> 2594 <para>Tells VBoxManage to only perform a dry run instead of 2595 really copying files to the guest.</para> 2596 </glossdef> 2597 </glossentry> 2598 2599 <glossentry> 2600 <glossterm>--follow</glossterm> 2601 2602 <glossdef> 2603 <para>Enables following symlinks on the host's 2604 source.</para> 2605 </glossdef> 2606 </glossentry> 2607 2608 <glossentry> 2609 <glossterm>--recursive</glossterm> 2610 2611 <glossdef> 2612 <para>Recursively copies files/directories of the specified 2613 source.</para> 2614 </glossdef> 2615 </glossentry> 2616 2617 <glossentry> 2618 <glossterm>--verbose</glossterm> 2619 2620 <glossdef> 2621 <para>Tells VBoxManage to be more verbose.</para> 2622 </glossdef> 2623 </glossentry> 2624 2625 <glossentry> 2626 <glossterm>--flags <flags></glossterm> 2627 2628 <glossdef> 2629 <para>Additional flags to set. This is not used at the 2630 moment.</para> 2631 </glossdef> 2632 </glossentry> 2633 </glosslist></para> 2634 </listitem> 2635 2636 <listitem> 2637 <para><computeroutput>createdirectory</computeroutput>, which allows 2638 copying files from the host to the guest (only with installed Guest 2639 Additions 4.0 and later).</para> 2640 2641 <screen>VBoxManage createdir[ectory]|mkdir|md <vmname>|<uuid> 2642 <directory to create on guest> 2643 [--username "<name>"] [--password "<password>"] 2644 [--parents] [--mode <mode>] [--verbose]</screen> 2645 2646 <para>where the parameters mean: <glosslist> 2647 <glossentry> 2648 <glossterm>uuid|vmname</glossterm> 2649 2650 <glossdef> 2651 <para>The VM UUID or VM name. Mandatory.</para> 2652 </glossdef> 2653 </glossentry> 2654 2655 <glossentry> 2656 <glossterm>directory to create on guest</glossterm> 2657 2658 <glossdef> 2659 <para>Absolute path of directory/directories to create on 2660 guest, e.g. <computeroutput>D:\Foo\Bar</computeroutput>. 2661 Parent directories need to exist (e.g. in this example 2662 <computeroutput>D:\Foo</computeroutput>) when switch 2663 <computeroutput>--parents</computeroutput> is omitted. The 2664 specified user must have appropriate rights to create the 2665 specified directory.</para> 2666 </glossdef> 2667 </glossentry> 2668 2669 <glossentry> 2670 <glossterm>--username <name></glossterm> 2671 2672 <glossdef> 2673 <para>Name of the user the copy process should run under. 2674 This user must exist on the guest OS.</para> 2675 </glossdef> 2676 </glossentry> 2677 2678 <glossentry> 2679 <glossterm>--password <password></glossterm> 2680 2681 <glossdef> 2682 <para>Password of the user account specified with 2683 <computeroutput>--username</computeroutput>. If not given, 2684 an empty password is assumed.</para> 2685 </glossdef> 2686 </glossentry> 2687 2688 <glossentry> 2689 <glossterm>--parents</glossterm> 2690 2691 <glossdef> 2692 <para>Also creates not yet existing parent directories of 2693 the specified directory, e.g. if the directory 2694 <computeroutput>D:\Foo</computeroutput> of 2695 <computeroutput>D:\Foo\Bar</computeroutput> does not exist 2696 yet it will be created. Without specifying 2697 <computeroutput>--parent</computeroutput> the action would 2698 have failed.</para> 2699 </glossdef> 2700 </glossentry> 2701 2702 <glossentry> 2703 <glossterm>--mode <mode></glossterm> 2704 2705 <glossdef> 2706 <para>Sets the permission mode of the specified directory. 2707 Only octal modes (e.g. 2708 <computeroutput>0755</computeroutput>) are supported right 2709 now.</para> 2710 </glossdef> 2711 </glossentry> 2712 2713 <glossentry> 2714 <glossterm>--verbose</glossterm> 2715 2716 <glossdef> 2717 <para>Tells VBoxManage to be more verbose.</para> 2718 </glossdef> 2719 </glossentry> 2720 </glosslist></para> 2721 </listitem> 2722 2723 <listitem> 2724 <para><computeroutput>updateadditions</computeroutput>, which allows 2725 for updating an already installed Guest Additions version on the 2726 guest (only already installed Guest Additions 4.0 and later).</para> 2727 2728 <screen>VBoxManage guestcontrol updateadditions <vmname>|<uuid> 2729 [--source "<guest additions .ISO file to use>"] [--verbose]</screen> 2730 2731 <para>where the parameters mean: <glosslist> 2732 <glossentry> 2733 <glossterm>uuid|vmname</glossterm> 2734 2735 <glossdef> 2736 <para>The VM UUID or VM name. Mandatory.</para> 2737 </glossdef> 2738 </glossentry> 2739 2740 <glossentry> 2741 <glossterm>--source "<guest additions .ISO file to 2742 use>"</glossterm> 2743 2744 <glossdef> 2745 <para>Full path to an alternative VirtualBox Guest Additions 2746 .ISO file to use for the Guest Additions update.</para> 2747 </glossdef> 2748 </glossentry> 2749 2750 <glossentry> 2751 <glossterm>--verbose</glossterm> 2752 2753 <glossdef> 2754 <para>Tells VBoxManage to be more verbose.</para> 2755 </glossdef> 2756 </glossentry> 2757 </glosslist></para> 2758 </listitem> 2759 </itemizedlist></para> 2760 </sect1> 2761 2762 <sect1 id="vboxmanage-debugvm"> 2763 <title>VBoxManage debugvm</title> 2764 2765 <para>The "debugvm" commands are for experts who want to tinker with the 2766 exact details of virtual machine execution. Like the VM debugger described 2767 in <xref linkend="debugger" />, these commands are only useful if you are 2768 very familiar with the details of the PC architecture and how to debug 2769 software.</para> 2770 2771 <para>The subcommands of "debugvm" all operate on a running virtual 2772 machine. The following are available:<itemizedlist> 2773 <listitem> 2774 <para>With <computeroutput>dumpguestcore --filename 2775 <name></computeroutput>, you can create a system dump of the 2776 running VM, which will be written into the given file. This file 2777 will have the standard ELF core format (with custom sections); see 2778 <xref linkend="guestcoreformat" />.</para> 2779 </listitem> 2780 2781 <listitem> 2782 <para>The <computeroutput>injectnmi</computeroutput> command causes 2783 a non-maskable interrupt (NMI) in the guest, which might be useful 2784 for certain debugging scenarios. What happens exactly is dependent 2785 on the guest operating system, but an NMI can crash the whole guest 2786 operating system. Do not use unless you know what you're 2787 doing.</para> 2788 </listitem> 2789 2790 <listitem> 2791 <para>The <computeroutput>statistics</computeroutput> command can be 2792 used to display VMM statistics on the command line. The 2793 <computeroutput>--reset</computeroutput> option will reset 2794 statistics. The affected statistics can be filtered with the 2795 <computeroutput>--pattern</computeroutput> option, which accepts 2796 DOS/NT-style wildcards (<computeroutput>?</computeroutput> and 2797 <computeroutput>*</computeroutput>).</para> 2798 </listitem> 2799 </itemizedlist></para> 2800 </sect1> 2801 2246 2802 <sect1> 2247 2803 <title id="metrics">VBoxManage metrics</title> … … 2398 2954 </glosslist> 2399 2955 </sect1> 2400 2401 <sect1 id="vboxmanage-guestproperty"> 2402 <title>VBoxManage guestproperty</title> 2403 2404 <para>The "guestproperty" commands allow you to get or set properties of a 2405 running virtual machine. Please see <xref linkend="guestadd-guestprops" /> 2406 for an introduction. As explained there, guest properties are arbitrary 2407 key/value string pairs which can be written to and read from by either the 2408 guest or the host, so they can be used as a low-volume communication 2409 channel for strings, provided that a guest is running and has the Guest 2410 Additions installed. In addition, a number of values whose keys begin with 2411 "/VirtualBox/" are automatically set and maintained by the Guest 2412 Additions.</para> 2413 2414 <para>The following subcommands are available (where 2415 <computeroutput><vm></computeroutput>, in each case, can either be a 2416 VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist> 2417 <listitem> 2418 <para><computeroutput>enumerate <vm> [--patterns 2419 <pattern>]</computeroutput>: This lists all the guest 2420 properties that are available for the given VM, including the value. 2421 This list will be very limited if the guest's service process cannot 2422 be contacted, e.g. because the VM is not running or the Guest 2423 Additions are not installed.</para> 2424 2425 <para>If <computeroutput>--patterns <pattern></computeroutput> 2426 is specified, it acts as a filter to only list properties that match 2427 the given pattern. The pattern can contain the following wildcard 2428 characters:<itemizedlist> 2429 <listitem> 2430 <para><computeroutput>*</computeroutput> (asterisk): 2431 represents any number of characters; for example, 2432 "<computeroutput>/VirtualBox*</computeroutput>" would match 2433 all properties beginning with "/VirtualBox".</para> 2434 </listitem> 2435 2436 <listitem> 2437 <para><computeroutput>?</computeroutput> (question mark): 2438 represents a single arbitrary character; for example, 2439 "<computeroutput>fo?</computeroutput>" would match both "foo" 2440 and "for".</para> 2441 </listitem> 2442 2443 <listitem> 2444 <para><computeroutput>|</computeroutput> (pipe symbol): can be 2445 used to specify multiple alternative patterns; for example, 2446 "<computeroutput>s*|t*</computeroutput>" would match anything 2447 starting with either "s" or "t".</para> 2448 </listitem> 2449 </itemizedlist></para> 2450 </listitem> 2451 2452 <listitem> 2453 <para><computeroutput>get <vm></computeroutput>: This 2454 retrieves the value of a single property only. If the property 2455 cannot be found (e.g. because the guest is not running), this will 2456 print "No value set!".</para> 2457 </listitem> 2458 2459 <listitem> 2460 <para><computeroutput>set <vm> <property> [<value> 2461 [--flags <flags>]]</computeroutput>: This allows you to set a 2462 guest property by specifying the key and value. If 2463 <computeroutput><value></computeroutput> is omitted, the 2464 property is deleted. With <computeroutput>--flags</computeroutput> 2465 you can optionally specify additional behavior (you can combine 2466 several by separating them with commas):<itemizedlist> 2467 <listitem> 2468 <para><computeroutput>TRANSIENT</computeroutput>: the value 2469 will not be stored with the VM data when the VM exits;</para> 2470 </listitem> 2471 2472 <listitem> 2473 <para><computeroutput>RDONLYGUEST</computeroutput>: the value 2474 can only be changed by the host, but the guest can only read 2475 it;</para> 2476 </listitem> 2477 2478 <listitem> 2479 <para><computeroutput>RDONLYHOST</computeroutput>: reversely, 2480 the value can only be changed by the guest, but the host can 2481 only read it;</para> 2482 </listitem> 2483 2484 <listitem> 2485 <para><computeroutput>READONLY</computeroutput>: a combination 2486 of the two, the value cannot be changed at all.</para> 2487 </listitem> 2488 </itemizedlist></para> 2489 </listitem> 2490 2491 <listitem> 2492 <para><computeroutput>wait <vm> <pattern> --timeout 2493 <timeout></computeroutput>: This waits for a particular value 2494 described by "pattern" to change or to be deleted or created. The 2495 pattern rules are the same as for the "enumerate" subcommand 2496 above.</para> 2497 </listitem> 2498 </itemizedlist></para> 2499 </sect1> 2500 2501 <sect1 id="vboxmanage-guestcontrol"> 2502 <title>VBoxManage guestcontrol</title> 2503 2504 <para>The "guestcontrol" commands allow you to control certain things 2505 inside a guest from the host. Please see <xref 2506 linkend="guestadd-guestcontrol" /> for an introduction.</para> 2507 2508 <para>Generally, the syntax is as follows:</para> 2509 2510 <screen>VBoxManage guestcontrol <command></screen> 2511 2512 <para>The following subcommands are available (where 2513 <computeroutput><vm></computeroutput>, in each case, can either be a 2514 VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist> 2515 <listitem> 2516 <para><computeroutput>execute</computeroutput>, which allows for 2517 executing a program/script (process) which is already installed and 2518 runnable on the guest. This command only works while a VM is up and 2519 running and has the following syntax:</para> 2520 2521 <screen>VBoxManage guestcontrol exec[ute] <vmname>|<uuid> 2522 <path to program> 2523 --username <name> --password <password> 2524 [--arguments "<arguments>"] 2525 [--environment "<NAME>=<VALUE> [<NAME>=<VALUE>]"] 2526 [--flags <flags>] [--timeout <msec>] 2527 [--verbose] [--wait-for exit,stdout,stderr||]</screen> 2528 2529 <para>where the parameters mean: <glosslist> 2530 <glossentry> 2531 <glossterm>uuid|vmname</glossterm> 2532 2533 <glossdef> 2534 <para>The VM UUID or VM name. Mandatory.</para> 2535 </glossdef> 2536 </glossentry> 2537 2538 <glossentry> 2539 <glossterm>path to program</glossterm> 2540 2541 <glossdef> 2542 <para>Absolute path and process name of process to execute 2543 in the guest, e.g. 2544 <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para> 2545 </glossdef> 2546 </glossentry> 2547 2548 <glossentry> 2549 <glossterm>--arguments "<arguments>"</glossterm> 2550 2551 <glossdef> 2552 <para>One or more arguments to pass to the process being 2553 executed.</para> 2554 2555 <para>Arguments containing spaces must be enclosed in 2556 quotation marks. More than one 2557 <computeroutput>--arguments</computeroutput> at a time can 2558 be specified to keep the command line tidy.</para> 2559 </glossdef> 2560 </glossentry> 2561 2562 <glossentry> 2563 <glossterm>--environment 2564 "<NAME>=<VALUE>"</glossterm> 2565 2566 <glossdef> 2567 <para>One or more environment variables to be set or 2568 unset.</para> 2569 2570 <para>By default, the new process in the guest will be 2571 created with the standard environment of the guest OS. This 2572 option allows for modifying that environment. To set/modify 2573 a variable, a pair of 2574 <computeroutput>NAME=VALUE</computeroutput> must be 2575 specified; to unset a certain variable, the name with no 2576 value must set, e.g. 2577 <computeroutput>NAME=</computeroutput>.</para> 2578 2579 <para>Arguments containing spaces must be enclosed in 2580 quotation marks. More than one 2581 <computeroutput>--environment</computeroutput> at a time can 2582 be specified to keep the command line tidy.</para> 2583 </glossdef> 2584 </glossentry> 2585 2586 <glossentry> 2587 <glossterm>--flags <flags></glossterm> 2588 2589 <glossdef> 2590 <para>Additional flags to set. This is not used at the 2591 moment.</para> 2592 </glossdef> 2593 </glossentry> 2594 2595 <glossentry> 2596 <glossterm>--timeout <msec></glossterm> 2597 2598 <glossdef> 2599 <para>Value (in milliseconds) that specifies the time how 2600 long the started process is allowed to run and how long 2601 VBoxManage waits for getting output from that process. If no 2602 timeout is specified, VBoxManage will wait forever until the 2603 started process ends or an error occured.</para> 2604 </glossdef> 2605 </glossentry> 2606 2607 <glossentry> 2608 <glossterm>--username <name></glossterm> 2609 2610 <glossdef> 2611 <para>Name of the user the process should run under. This 2612 user must exist on the guest OS.</para> 2613 </glossdef> 2614 </glossentry> 2615 2616 <glossentry> 2617 <glossterm>--password <password></glossterm> 2618 2619 <glossdef> 2620 <para>Password of the user account specified with 2621 <computeroutput>--username</computeroutput>. If not given, 2622 an empty password is assumed.</para> 2623 </glossdef> 2624 </glossentry> 2625 2626 <glossentry> 2627 <glossterm>--verbose</glossterm> 2628 2629 <glossdef> 2630 <para>Tells VBoxManage to be more verbose.</para> 2631 </glossdef> 2632 </glossentry> 2633 2634 <glossentry> 2635 <glossterm>--wait-for <action></glossterm> 2636 2637 <glossdef> 2638 <para>Tells VBoxManage to wait for a certain action to 2639 happen and react to it. The following actions are available: 2640 <glosslist> 2641 <glossentry> 2642 <glossterm>exit</glossterm> 2643 2644 <glossdef> 2645 <para>Waits until the process ends and outputs its 2646 exit code along with the exit reason/flags.</para> 2647 </glossdef> 2648 </glossentry> 2649 2650 <glossentry> 2651 <glossterm>stdout or stderr</glossterm> 2652 2653 <glossdef> 2654 <para>Waits until the process ends and outputs its 2655 exit code along with the exit reason/flags. After 2656 that VBoxManage retrieves the output collected from 2657 the guest process's stdout and stderr.</para> 2658 </glossdef> 2659 </glossentry> 2660 </glosslist></para> 2661 </glossdef> 2662 </glossentry> 2663 </glosslist></para> 2664 2665 <para><note> 2666 <para>On Windows there are certain limitations for graphical 2667 applications; please see <xref linkend="KnownIssues" /> for more 2668 information.</para> 2669 </note> Examples: <screen>VBoxManage --nologo guestcontrol execute "My VM" "/bin/ls" --arguments "-l /usr" 2670 --username foo --password bar --wait-for stdout</screen> <screen>VBoxManage --nologo guestcontrol execute "My VM" "c:\\windows\\system32\\ipconfig.exe" 2671 --username foo --password bar --wait-for stdout</screen> Note that 2672 the double backslashes in the second example are only required on 2673 Unix hosts.</para> 2674 </listitem> 2675 2676 <listitem> 2677 <para><computeroutput>copyto</computeroutput>, which allows copying 2678 files from the host to the guest (only with installed Guest 2679 Additions 4.0 and later).</para> 2680 2681 <screen>VBoxManage copyto|cp <vmname>|<uuid> 2682 <source on host> <destination on guest> 2683 --username <name> --password <password> 2684 [--dryrun] [--follow] [--recursive] [--verbose]</screen> 2685 2686 <para>where the parameters mean: <glosslist> 2687 <glossentry> 2688 <glossterm>uuid|vmname</glossterm> 2689 2690 <glossdef> 2691 <para>The VM UUID or VM name. Mandatory.</para> 2692 </glossdef> 2693 </glossentry> 2694 2695 <glossentry> 2696 <glossterm>source on host</glossterm> 2697 2698 <glossdef> 2699 <para>Absolute path of source file(s) on host to copy over 2700 to the guest, e.g. 2701 <computeroutput>C:\Windows\System32\calc.exe</computeroutput>. 2702 This also can be a wildcard expression, e.g. 2703 <computeroutput>C:\Windows\System32\*.dll</computeroutput></para> 2704 </glossdef> 2705 </glossentry> 2706 2707 <glossentry> 2708 <glossterm>destination on guest</glossterm> 2709 2710 <glossdef> 2711 <para>Absolute destination path on the guest, e.g. 2712 <computeroutput>C:\Temp</computeroutput></para> 2713 </glossdef> 2714 </glossentry> 2715 2716 <glossentry> 2717 <glossterm>--username <name></glossterm> 2718 2719 <glossdef> 2720 <para>Name of the user the copy process should run under. 2721 This user must exist on the guest OS.</para> 2722 </glossdef> 2723 </glossentry> 2724 2725 <glossentry> 2726 <glossterm>--password <password></glossterm> 2727 2728 <glossdef> 2729 <para>Password of the user account specified with 2730 <computeroutput>--username</computeroutput>. If not given, 2731 an empty password is assumed.</para> 2732 </glossdef> 2733 </glossentry> 2734 2735 <glossentry> 2736 <glossterm>--dryrun</glossterm> 2737 2738 <glossdef> 2739 <para>Tells VBoxManage to only perform a dry run instead of 2740 really copying files to the guest.</para> 2741 </glossdef> 2742 </glossentry> 2743 2744 <glossentry> 2745 <glossterm>--follow</glossterm> 2746 2747 <glossdef> 2748 <para>Enables following symlinks on the host's 2749 source.</para> 2750 </glossdef> 2751 </glossentry> 2752 2753 <glossentry> 2754 <glossterm>--recursive</glossterm> 2755 2756 <glossdef> 2757 <para>Recursively copies files/directories of the specified 2758 source.</para> 2759 </glossdef> 2760 </glossentry> 2761 2762 <glossentry> 2763 <glossterm>--verbose</glossterm> 2764 2765 <glossdef> 2766 <para>Tells VBoxManage to be more verbose.</para> 2767 </glossdef> 2768 </glossentry> 2769 2770 <glossentry> 2771 <glossterm>--flags <flags></glossterm> 2772 2773 <glossdef> 2774 <para>Additional flags to set. This is not used at the 2775 moment.</para> 2776 </glossdef> 2777 </glossentry> 2778 </glosslist></para> 2779 </listitem> 2780 2781 <listitem> 2782 <para><computeroutput>createdirectory</computeroutput>, which allows 2783 copying files from the host to the guest (only with installed Guest 2784 Additions 4.0 and later).</para> 2785 2786 <screen>VBoxManage createdir[ectory]|mkdir|md <vmname>|<uuid> 2787 <directory to create on guest> 2788 [--username "<name>"] [--password "<password>"] 2789 [--parents] [--mode <mode>] [--verbose]</screen> 2790 2791 <para>where the parameters mean: <glosslist> 2792 <glossentry> 2793 <glossterm>uuid|vmname</glossterm> 2794 2795 <glossdef> 2796 <para>The VM UUID or VM name. Mandatory.</para> 2797 </glossdef> 2798 </glossentry> 2799 2800 <glossentry> 2801 <glossterm>directory to create on guest</glossterm> 2802 2803 <glossdef> 2804 <para>Absolute path of directory/directories to create on 2805 guest, e.g. <computeroutput>D:\Foo\Bar</computeroutput>. 2806 Parent directories need to exist (e.g. in this example 2807 <computeroutput>D:\Foo</computeroutput>) when switch 2808 <computeroutput>--parents</computeroutput> is omitted. The 2809 specified user must have appropriate rights to create the 2810 specified directory.</para> 2811 </glossdef> 2812 </glossentry> 2813 2814 <glossentry> 2815 <glossterm>--username <name></glossterm> 2816 2817 <glossdef> 2818 <para>Name of the user the copy process should run under. 2819 This user must exist on the guest OS.</para> 2820 </glossdef> 2821 </glossentry> 2822 2823 <glossentry> 2824 <glossterm>--password <password></glossterm> 2825 2826 <glossdef> 2827 <para>Password of the user account specified with 2828 <computeroutput>--username</computeroutput>. If not given, 2829 an empty password is assumed.</para> 2830 </glossdef> 2831 </glossentry> 2832 2833 <glossentry> 2834 <glossterm>--parents</glossterm> 2835 2836 <glossdef> 2837 <para>Also creates not yet existing parent directories of 2838 the specified directory, e.g. if the directory 2839 <computeroutput>D:\Foo</computeroutput> of 2840 <computeroutput>D:\Foo\Bar</computeroutput> does not exist 2841 yet it will be created. Without specifying 2842 <computeroutput>--parent</computeroutput> the action would 2843 have failed.</para> 2844 </glossdef> 2845 </glossentry> 2846 2847 <glossentry> 2848 <glossterm>--mode <mode></glossterm> 2849 2850 <glossdef> 2851 <para>Sets the permission mode of the specified directory. 2852 Only octal modes (e.g. 2853 <computeroutput>0755</computeroutput>) are supported right 2854 now.</para> 2855 </glossdef> 2856 </glossentry> 2857 2858 <glossentry> 2859 <glossterm>--verbose</glossterm> 2860 2861 <glossdef> 2862 <para>Tells VBoxManage to be more verbose.</para> 2863 </glossdef> 2864 </glossentry> 2865 </glosslist></para> 2866 </listitem> 2867 2868 <listitem> 2869 <para><computeroutput>updateadditions</computeroutput>, which allows 2870 for updating an already installed Guest Additions version on the 2871 guest (only already installed Guest Additions 4.0 and later).</para> 2872 2873 <screen>VBoxManage guestcontrol updateadditions <vmname>|<uuid> 2874 [--source "<guest additions .ISO file to use>"] [--verbose]</screen> 2875 2876 <para>where the parameters mean: <glosslist> 2877 <glossentry> 2878 <glossterm>uuid|vmname</glossterm> 2879 2880 <glossdef> 2881 <para>The VM UUID or VM name. Mandatory.</para> 2882 </glossdef> 2883 </glossentry> 2884 2885 <glossentry> 2886 <glossterm>--source "<guest additions .ISO file to 2887 use>"</glossterm> 2888 2889 <glossdef> 2890 <para>Full path to an alternative VirtualBox Guest Additions 2891 .ISO file to use for the Guest Additions update.</para> 2892 </glossdef> 2893 </glossentry> 2894 2895 <glossentry> 2896 <glossterm>--verbose</glossterm> 2897 2898 <glossdef> 2899 <para>Tells VBoxManage to be more verbose.</para> 2900 </glossdef> 2901 </glossentry> 2902 </glosslist></para> 2903 </listitem> 2904 </itemizedlist></para> 2905 </sect1> 2906 2907 <sect1 id="vboxmanage-debugvm"> 2908 <title>VBoxManage debugvm</title> 2909 2910 <para>The "debugvm" commands are for experts who want to tinker with the 2911 exact details of virtual machine execution. Like the VM debugger described 2912 in <xref linkend="debugger" />, these commands are only useful if you are 2913 very familiar with the details of the PC architecture and how to debug 2914 software.</para> 2915 2916 <para>The subcommands of "debugvm" all operate on a running virtual 2917 machine. The following are available:<itemizedlist> 2918 <listitem> 2919 <para>With <computeroutput>dumpguestcore --filename 2920 <name></computeroutput>, you can create a system dump of the 2921 running VM, which will be written into the given file. This file 2922 will have the standard ELF core format (with custom sections); see 2923 <xref linkend="guestcoreformat" />.</para> 2924 </listitem> 2925 2926 <listitem> 2927 <para>The <computeroutput>injectnmi</computeroutput> command causes 2928 a non-maskable interrupt (NMI) in the guest, which might be useful 2929 for certain debugging scenarios. What happens exactly is dependent 2930 on the guest operating system, but an NMI can crash the whole guest 2931 operating system. Do not use unless you know what you're 2932 doing.</para> 2933 </listitem> 2934 2935 <listitem> 2936 <para>The <computeroutput>statistics</computeroutput> command can be 2937 used to display VMM statistics on the command line. The 2938 <computeroutput>--reset</computeroutput> option will reset 2939 statistics. The affected statistics can be filtered with the 2940 <computeroutput>--pattern</computeroutput> option, which accepts 2941 DOS/NT-style wildcards (<computeroutput>?</computeroutput> and 2942 <computeroutput>*</computeroutput>).</para> 2943 </listitem> 2944 </itemizedlist></para> 2956 2957 <sect1> 2958 <title>VBoxManage hostonlyif</title> 2959 2960 <para>With "hostonlyif" you can change the IP configuration of a host-only 2961 network interface. For a description of host-only networking, please 2962 refer to <xref linkend="network_hostonly" />. Each host-only interface is 2963 identified by a name and can either use the internal DHCP server or a 2964 manual IP configuration (both IP4 and IP6).</para> 2945 2965 </sect1> 2946 2966
Note:
See TracChangeset
for help on using the changeset viewer.
