vboxmanage-intro.dita@ 105145

Last change on this file since 105145 was 99497, checked in by vboxsync, 22 months ago
manual: Split out the topics of converted manpages into separate files and generate ditamap files for each manpage to avoid needing to hardcode anything in UserManual.xml. This means that the topics inside a manpage can be supressed from the toc, but otoh, they get numbered (with 4.x). The per-topic files are named by refentry/refsect1/refsect2 @id and are currently not cleaned up by 'kmk clean'. bugref:10302
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 6.4 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE topic
3	PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
4	<topic xml:lang="en-us" id="vboxmanage-intro">
5	<title>Introduction</title>
6
7	<body>
8	<p>
9	As briefly mentioned in <xref href="frontends.dita#frontends"/>,
10	<userinput>VBoxManage</userinput> is the command-line interface to
11	Oracle VM VirtualBox. With it, you can completely control Oracle VM VirtualBox
12	from the command line of your host operating system.
13	<userinput>VBoxManage</userinput> supports all the features that the
14	graphical user interface gives you access to, but it supports a
15	lot more than that. It exposes all the features of the
16	virtualization engine, even those that cannot be accessed from the
17	GUI.
18	</p>
19	<p>
20	You will need to use the command line if you want to do the
21	following:
22	</p>
23	<ul>
24	<li>
25	<p>
26	Use a different user interface than the main GUI such as the
27	VBoxHeadless server.
28	</p>
29	</li>
30	<li>
31	<p>
32	Control some of the more advanced and experimental
33	configuration settings for a VM.
34	</p>
35	</li>
36	</ul>
37	<p>
38	There are two main things to keep in mind when using
39	<userinput>VBoxManage</userinput>. First,
40	<userinput>VBoxManage</userinput> must always be used with a specific
41	subcommand, such as <userinput>list</userinput> or
42	<userinput>createvm</userinput> or <userinput>startvm</userinput>. All the
43	subcommands that <userinput>VBoxManage</userinput> supports are
44	described in detail in <xref href="vboxmanage.dita#vboxmanage"/>.
45	</p>
46	<p>
47	Second, most of these subcommands require that you specify a
48	particular virtual machine after the subcommand. There are two
49	ways you can do this:
50	</p>
51	<ul>
52	<li>
53	<p>
54	You can specify the VM name, as it is shown in the
55	Oracle VM VirtualBox GUI. Note that if that name contains spaces,
56	then you must enclose the entire name in double quotes. This
57	is always required with command line arguments that contain
58	spaces. For example:
59	</p>
60	<pre xml:space="preserve">VBoxManage startvm "Windows XP"</pre>
61	</li>
62	<li>
63	<p>
64	You can specify the UUID, which is the internal unique
65	identifier that Oracle VM VirtualBox uses to refer to the virtual
66	machine. Assuming that the VM called "Windows XP" has the UUID
67	shown below, the following command has the same effect as the
68	previous example:
69	</p>
70	<pre xml:space="preserve">VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</pre>
71	</li>
72	</ul>
73	<p>
74	You can enter <userinput>VBoxManage list vms</userinput> to have all
75	currently registered VMs listed with all their settings, including
76	their respective names and UUIDs.
77	</p>
78	<p>
79	Some typical examples of how to control Oracle VM VirtualBox from the
80	command line are listed below:
81	</p>
82	<ul>
83	<li>
84	<p>
85	To create a new virtual machine from the command line and
86	immediately register it with Oracle VM VirtualBox, use
87	<userinput>VBoxManage createvm</userinput> with the
88	<!--option not processed within -->--register option, as follows:
89	</p>
90	<pre xml:space="preserve">$ VBoxManage createvm --name "SUSE 10.2" --register
91	VirtualBox Command Line Management Interface Version <varname>version-number</varname>
92	(C) 2005-2018 Oracle Corporation
93	All rights reserved.
94
95	Virtual machine 'SUSE 10.2' is created.
96	UUID: c89fc351-8ec6-4f02-a048-57f4d25288e5
97	Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</pre>
98	<p>
99	As can be seen from the above output, a new virtual machine
100	has been created with a new UUID and a new XML settings file.
101	</p>
102	<p>
103	For more details, see
104	<xref href="vboxmanage-createvm.dita"/>.
105	</p>
106	</li>
107	<li>
108	<p>
109	To show the configuration of a particular VM, use
110	<userinput>VBoxManage showvminfo</userinput>. See
111	<xref href="vboxmanage-showvminfo.dita"/> for details
112	and an example.
113	</p>
114	</li>
115	<li>
116	<p>
117	To change settings while a VM is powered off, use
118	<userinput>VBoxManage modifyvm</userinput>. For example:
119	</p>
120	<pre xml:space="preserve">VBoxManage modifyvm "Windows XP" --memory 512</pre>
121	<p>
122	See also <xref href="vboxmanage-modifyvm.dita"/>.
123	</p>
124	</li>
125	<li>
126	<p>
127	To change the storage configuration, such as to add a storage
128	controller and then a virtual disk, use <userinput>VBoxManage
129	storagectl</userinput> and <userinput>VBoxManage
130	storageattach</userinput>. See
131	<xref href="vboxmanage-storagectl.dita"/> and
132	<xref href="vboxmanage-storageattach.dita"/>.
133	</p>
134	</li>
135	<li>
136	<p>
137	To control VM operation, use one of the following:
138	</p>
139	<ul>
140	<li>
141	<p>
142	To start a VM that is currently powered off, use
143	<userinput>VBoxManage startvm</userinput>. See
144	<xref href="vboxmanage-startvm.dita"/>.
145	</p>
146	</li>
147	<li>
148	<p>
149	To pause or save a VM that is currently running or change
150	some of its settings, use <userinput>VBoxManage
151	controlvm</userinput>. See
152	<xref href="vboxmanage-controlvm.dita"/>.
153	</p>
154	</li>
155	</ul>
156	</li>
157	</ul>
158	</body>
159
160	</topic>

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format