VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxHeadless.xml@ 103131

Last change on this file since 103131 was 99513, checked in by vboxsync, 20 months ago

manual,VBoxManage,isomaker/viso: Require all refsect1 and refsect2 elements to have @id attributes in manpages (refentry) to make these predictable and the split up topic files easier to handle for the docs team. Also requires these @id values to start with the refentry @id + '-'. Corrected a few bogus ones. Because 'controlvm' has too many sub-commands, HELP_SCOPE_ IDs will not be generated for 'See Also' and 'Examples' sections. bugref:10302

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxHeadless
4-->
5<!--
6 Copyright (C) 2006-2023 Oracle and/or its affiliates.
7
8 This file is part of VirtualBox base platform packages, as
9 available from https://www.virtualbox.org.
10
11 This program is free software; you can redistribute it and/or
12 modify it under the terms of the GNU General Public License
13 as published by the Free Software Foundation, in version 3 of the
14 License.
15
16 This program is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, see <https://www.gnu.org/licenses>.
23
24 SPDX-License-Identifier: GPL-3.0-only
25-->
26<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
27 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
28<!ENTITY % all.entities SYSTEM "all-entities.ent">
29%all.entities;
30]>
31<refentry id="man_vboxheadless" lang="en">
32 <refentryinfo>
33 <pubdate>August 2019</pubdate>
34 <title>VBoxHeadless</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxHeadless</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxHeadless</refname>
44 <refpurpose>&product-name; remote desktop server</refpurpose>
45 <refclass>Oracle VM VirtualBox</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49 <cmdsynopsis id="synopsis-vboxmanage-vboxheadless">
50 <command>VBoxHeadless</command>
51 <arg>--startvm=<group choice="req">
52 <arg choice="plain"><replaceable>uuid</replaceable></arg>
53 <arg choice="plain"><replaceable>vmname</replaceable></arg>
54 </group></arg>
55 <arg>--vrde=<group choice="plain">
56 <arg choice="plain">on</arg>
57 <arg choice="plain">off</arg>
58 <arg choice="plain">config</arg>
59 </group></arg>
60 <arg>--vrdeproperty=<replaceable>prop-name</replaceable>=<arg><replaceable>prop-value</replaceable></arg></arg>
61 <arg>--settingspw=<replaceable>password</replaceable></arg>
62 <arg>--settingspwfile=<replaceable>password-file</replaceable></arg>
63 <arg>--start-paused</arg>
64 <arg>--capture</arg>
65 <arg>--width=<replaceable>width</replaceable></arg>
66 <arg>--height=<replaceable>height</replaceable></arg>
67 <arg>--bitrate=<replaceable>bit-rate</replaceable></arg>
68 <arg>--filename=<replaceable>filename</replaceable></arg>
69 </cmdsynopsis>
70 </refsynopsisdiv>
71
72 <refsect1 id="vboxheadless-description">
73 <title>Description</title>
74 <para>
75 The <command>VBoxHeadless</command> command is an alternate front
76 end that enables you to remotely manage virtual machines (VMs).
77 The front end is a CLI rather than the VirtualBox Manager
78 graphical user interface (GUI).
79 </para>
80 <para>
81 For information about using this command, see
82 <xref linkend="vboxheadless" />.
83 </para>
84 <refsect2 id="vboxmanage-vboxheadless-command-options">
85 <title>Command Options</title>
86 <variablelist>
87 <varlistentry>
88 <term><option>--startvm=<replaceable>uuid</replaceable> | <replaceable>vmname</replaceable></option></term>
89 <listitem><para>
90 Specifies the Universally Unique Identifier (UUID) or name
91 of the VM to start.
92 </para><para>
93 Use the <command>VBoxManage list vms</command> command to
94 obtain VM information.
95 </para><para>
96 The short versions of this option is <option>-s</option>.
97 </para></listitem>
98 </varlistentry>
99 <varlistentry>
100 <term><option>--vrde=on | off | config</option></term>
101 <listitem><para>
102 Specifies how to use the VRDP server. The default value is
103 <literal>config</literal>. Valid values are as follows:
104 </para><itemizedlist>
105 <listitem><para>
106 <literal>on</literal> enables the VRDP server.
107 </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=on</screen></listitem>
108 <listitem><para>
109 <literal>off</literal> disables the VRDP server.
110 </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=off</screen></listitem>
111 <listitem><para>
112 <literal>config</literal> enables the VRDP server
113 depending on the VM configuration.
114 </para><screen>VBoxHeadless --startvm=<replaceable>vmname</replaceable> --vrde=config</screen></listitem>
115 </itemizedlist><para>
116 The short version of this option is <option>-v</option>.
117 </para></listitem>
118 </varlistentry>
119 <varlistentry>
120 <term><option>--vrdeproperty=<replaceable>prop-name</replaceable>=[<replaceable>prop-value</replaceable>]</option></term>
121 <listitem><para>
122 Specifies a value for one of the following properties:
123 </para><itemizedlist>
124 <listitem><para>
125 The <literal>TCP/Ports</literal> property value is a
126 comma-separated list of ports to which the VRDE server
127 can bind. Use a hyphen (<literal>-</literal>) between
128 two port numbers to specify a range of ports.
129 </para></listitem>
130 <listitem><para>
131 The <literal>TCP/Address</literal> property value is
132 the interface IP address to which to bind the VRDE
133 server.
134 </para></listitem>
135 </itemizedlist></listitem>
136 </varlistentry>
137 <varlistentry>
138 <term><option>--settingspw=<replaceable>password</replaceable></option></term>
139 <listitem><para>
140 Specifies a settings password to access encrypted
141 settings. If you do not specify the password on the
142 command line, <command>VBoxHeadless</command> prompts you
143 for the password.
144 </para><remark>
145 This design does not conform to Oracle's security
146 guidelines. You should not be able to specify a password
147 on the command line because the password can be seen in a
148 process listing.
149 </remark></listitem>
150 </varlistentry>
151 <varlistentry>
152 <term><option>--settingspwfile=<replaceable>password-file</replaceable></option></term>
153 <listitem><para>
154 Specifies the file that contains the settings password.
155 </para></listitem>
156 </varlistentry>
157 <varlistentry>
158 <term><option>--start-paused</option></term>
159 <listitem><para>
160 Starts the specified VM in the paused state.
161 </para></listitem>
162 </varlistentry>
163 <varlistentry>
164 <term><option>--capture</option></term>
165 <listitem><para>
166 Records the VM screen output to a file. In addition to
167 this option, you must use the <option>--filename</option>
168 option to specify the name of the file.
169 </para></listitem>
170 </varlistentry>
171 <varlistentry>
172 <term><option>--width=<replaceable>width</replaceable></option></term>
173 <listitem><para>
174 Specifies the frame width of the recording in pixels. This
175 option is associated with the <option>--capture</option>
176 option.
177 </para></listitem>
178 </varlistentry>
179 <varlistentry>
180 <term><option>--height=<replaceable>height</replaceable></option></term>
181 <listitem><para>
182 Specifies the frame height of the recording in pixels.
183 This option is associated with the
184 <option>--capture</option> option.
185 </para></listitem>
186 </varlistentry>
187 <varlistentry>
188 <term><option>--bitrate=<replaceable>bit-rate</replaceable></option></term>
189 <listitem><para>
190 Specifies the bit rate of the recording in kilobits per
191 second. This option is associated with the
192 <option>--capture</option> option.
193 </para></listitem>
194 </varlistentry>
195 <varlistentry>
196 <term><option>--filename=<replaceable>filename</replaceable></option></term>
197 <listitem><para>
198 Specifies the name of the file in which to store the
199 recording. The codec used is based on the file extension
200 that you choose. You must specify this option if you use
201 the <option>--capture</option> option.
202 </para><remark>
203 Where can we get information about the file extensions
204 that are supported?
205 </remark></listitem>
206 </varlistentry>
207 </variablelist>
208 </refsect2>
209 </refsect1>
210
211 <refsect1 id="vboxheadless-examples">
212 <title>Examples</title>
213 <remark role="help-scope" condition="GLOBAL"/>
214 <para>
215 The following command starts the <literal>ol7u4</literal> VM:
216 </para>
217<screen>$ VBoxHeadless --startvm "ol7u4"</screen>
218 <para>
219 The following command starts the <literal>ol7u6</literal> VM in
220 the Paused state.
221 </para>
222<screen>$ VBoxHeadless --startvm "ol7u6" --start-paused</screen>
223 <para>
224 The following command starts the <literal>ol7u6</literal> VM and
225 records the session. The recording is saved to the
226 <filename>ol7u6-recording</filename> WebM file.
227 </para>
228<screen>$ VBoxHeadless --startvm "ol7u6" --capture --filename ol7u6-recording.webm</screen>
229 </refsect1>
230
231 <refsect1 id="vboxheadless-see-also">
232 <title>See Also</title>
233 <para>
234 <xref linkend="vboxmanage-list" />,
235 <xref linkend="vboxmanage-startvm" />
236 </para>
237 </refsect1>
238</refentry>
Note: See TracBrowser for help on using the repository browser.

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