man_VBoxManage-bandwidthctl.xml@ 105298

Last change on this file since 105298 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: 12.5 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!--
3	manpage, user manual, usage: VBoxManage bandwidthctl
4	-->
5	<!--
6	Copyright (C) 2006-2023 Oracle and/or its affiliates.
7
8	This file is part of VirtualBox base platform packages, as
9	available from https://www.virtualbox.org.
10
11	This program is free software; you can redistribute it and/or
12	modify it under the terms of the GNU General Public License
13	as published by the Free Software Foundation, in version 3 of the
14	License.
15
16	This program is distributed in the hope that it will be useful, but
17	WITHOUT ANY WARRANTY; without even the implied warranty of
18	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19	General Public License for more details.
20
21	You should have received a copy of the GNU General Public License
22	along with this program; if not, see <https://www.gnu.org/licenses>.
23
24	SPDX-License-Identifier: GPL-3.0-only
25	-->
26	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
27	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
28	<!ENTITY % all.entities SYSTEM "all-entities.ent">
29	%all.entities;
30	]>
31	<refentry id="vboxmanage-bandwidthctl" lang="en">
32	<refentryinfo>
33	<pubdate>$Date: 2023-04-21 21:59:02 +0000 (Fri, 21 Apr 2023) $</pubdate>
34	<title>VBoxManage bandwidthctl</title>
35	</refentryinfo>
36
37	<refmeta>
38	<refentrytitle>VBoxManage-bandwidthctl</refentrytitle>
39	<manvolnum>1</manvolnum>
40	</refmeta>
41
42	<refnamediv>
43	<refname>VBoxManage-bandwidthctl</refname>
44	<refpurpose>manage bandwidth groups</refpurpose>
45	<refclass>&product-name;</refclass>
46	</refnamediv>
47
48	<refsynopsisdiv>
49	<cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-add">
50	<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
51	<command>VBoxManage bandwidthctl</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">add</arg>
57	<arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg>
58	<arg choice="req">--limit=<replaceable>bandwidth-limit</replaceable>[k\|m\|g\|K\|M\|G]</arg>
59	<arg choice="req">--type=<group choice="plain">
60	<arg choice="plain">disk</arg>
61	<arg choice="plain">network</arg>
62	</group></arg>
63	</cmdsynopsis>
64
65	<cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-list">
66	<command>VBoxManage bandwidthctl</command>
67	<group choice="req">
68	<arg choice="plain"><replaceable>uuid</replaceable></arg>
69	<arg choice="plain"><replaceable>vmname</replaceable></arg>
70	</group>
71	<arg choice="plain">list</arg>
72	<arg>--machinereadable</arg>
73	</cmdsynopsis>
74
75	<cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-remove">
76	<command>VBoxManage bandwidthctl</command>
77	<group choice="req">
78	<arg choice="plain"><replaceable>uuid</replaceable></arg>
79	<arg choice="plain"><replaceable>vmname</replaceable></arg>
80	</group>
81	<arg choice="plain">remove</arg>
82	<arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg>
83	</cmdsynopsis>
84
85	<cmdsynopsis id="synopsis-vboxmanage-bandwidthctl-set">
86	<command>VBoxManage bandwidthctl</command>
87	<group choice="req">
88	<arg choice="plain"><replaceable>uuid</replaceable></arg>
89	<arg choice="plain"><replaceable>vmname</replaceable></arg>
90	</group>
91	<arg choice="plain">set</arg>
92	<arg choice="req"><replaceable>bandwidth-group-name</replaceable></arg>
93	<arg choice="req">--limit=<replaceable>bandwidth-limit</replaceable>[k\|m\|g\|K\|M\|G]</arg>
94	</cmdsynopsis>
95	</refsynopsisdiv>
96
97	<refsect1 id="vboxmanage-bandwidthctl-description">
98	<title>Description</title>
99	<para>
100	The <command>VBoxManage bandwidthctl</command> command enables you
101	to manage bandwidth groups for virtual machines (VMs). A bandwidth
102	group specifies the bandwidth limit for the disks or for the
103	network adapters of a VM.
104	</para>
105	<para>
106	Note that a network bandwidth limit applies only to the outbound
107	traffic from the VM. The inbound traffic is unlimited.
108	</para>
109	<refsect2 id="vboxmanage-bandwidthctl-add">
110	<title>Create a Bandwidth Group</title>
111	<remark role="help-copy-synopsis"/>
112	<para>
113	The <command>VBoxManage bandwidthctl add</command> command
114	creates a bandwidth group for the specified VM. You must specify
115	whether the bandwidth group is for disks or for networks, and
116	specify the bandwidth limit.
117	</para>
118	<variablelist>
119	<varlistentry>
120	<term><option><replaceable>uuid</replaceable> \| <replaceable>vmname</replaceable></option></term>
121	<listitem><para>
122	Specifies the Universally Unique Identifier (UUID) or the
123	name of the VM.
124	</para></listitem>
125	</varlistentry>
126	<varlistentry>
127	<term><option><replaceable>bandwidth-group-name</replaceable></option></term>
128	<listitem><para>
129	Specifies the name of the bandwidth group.
130	</para></listitem>
131	</varlistentry>
132	<varlistentry>
133	<term><option>--type=disk\|network</option></term>
134	<listitem><para>
135	Specifies the type of the bandwidth group:
136	<literal>disk</literal> and <literal>network</literal>.
137	For more information, see
138	<xref linkend="storage-bandwidth-limit" /> or
139	<xref linkend="network_bandwidth_limit" />.
140	</para></listitem>
141	</varlistentry>
142	<varlistentry>
143	<term><option>--limit=<replaceable>bandwidth-limit</replaceable>[k\|m\|g\|K\|M\|G]</option></term>
144	<listitem><para>
145	Specifies the bandwidth limit for a bandwidth group. The
146	default unit is megabytes per second. You can modify this
147	value while the VM is running.
148	</para><para>
149	You can change the unit by appending one of the following
150	unit specifiers to the bandwidth limit:
151	</para><itemizedlist>
152	<listitem><para>
153	<literal>k</literal> – kilobits per second
154	</para></listitem>
155	<listitem><para>
156	<literal>m</literal> – megabits per second
157	</para></listitem>
158	<listitem><para>
159	<literal>g</literal> – gigabits per second
160	</para></listitem>
161	<listitem><para>
162	<literal>K</literal> – kilobytes per second
163	</para></listitem>
164	<listitem><para>
165	<literal>M</literal> – megabytes per second
166	</para></listitem>
167	<listitem><para>
168	<literal>G</literal> – gigabytes per second
169	</para></listitem>
170	</itemizedlist></listitem>
171	</varlistentry>
172	</variablelist>
173	</refsect2>
174	<refsect2 id="vboxmanage-bandwidthctl-list">
175	<title>List Bandwidth Groups</title>
176	<remark role="help-copy-synopsis"/>
177	<para>
178	The <command>VBoxManage bandwidthctl list</command> command
179	lists the all the bandwidth groups that have been defined for
180	the specified VM. Use the <option>--machinereadable</option>
181	option to produce the output in a machine-readable format, which
182	uses name-value pairs.
183	</para>
184	<variablelist>
185	<varlistentry>
186	<term><option><replaceable>uuid</replaceable> \| <replaceable>vmname</replaceable></option></term>
187	<listitem><para>
188	Specifies the UUID or the name of the VM.
189	</para></listitem>
190	</varlistentry>
191	<varlistentry>
192	<term><option>--machinereadable</option></term>
193	<listitem><para>
194	Outputs the information about the bandwidth groups in
195	name-value pairs.
196	</para></listitem>
197	</varlistentry>
198	</variablelist>
199	</refsect2>
200	<refsect2 id="vboxmanage-bandwidthctl-remove">
201	<title>Remove a Bandwidth Group</title>
202	<remark role="help-copy-synopsis"/>
203	<para>
204	The <command>VBoxManage bandwidthctl remove</command> command
205	removes a bandwidth group.
206	</para>
207	<note>
208	<para>
209	To successfully remove a bandwidth group, ensure that it is
210	not referenced by any disk or adapter in the running VM.
211	</para>
212	</note>
213	<variablelist>
214	<varlistentry>
215	<term><option><replaceable>uuid</replaceable> \| <replaceable>vmname</replaceable></option></term>
216	<listitem><para>
217	Specifies the UUID or the name of the VM.
218	</para></listitem>
219	</varlistentry>
220	<varlistentry>
221	<term><option><replaceable>bandwidth-group-name</replaceable></option></term>
222	<listitem><para>
223	Specifies the name of the bandwidth group.
224	</para></listitem>
225	</varlistentry>
226	</variablelist>
227	</refsect2>
228	<refsect2 id="vboxmanage-bandwidthctl-set">
229	<title>Modify the Bandwidth Limit of a Bandwidth Group</title>
230	<remark role="help-copy-synopsis"/>
231	<para>
232	The <command>VBoxManage bandwidthctl set</command> command
233	modifies the bandwidth limit for a bandwidth group.
234	</para>
235	<variablelist>
236	<varlistentry>
237	<term><option><replaceable>uuid</replaceable> \| <replaceable>vmname</replaceable></option></term>
238	<listitem><para>
239	Specifies the UUID or the name of the VM.
240	</para></listitem>
241	</varlistentry>
242	<varlistentry>
243	<term><option><replaceable>bandwidth-group-name</replaceable></option></term>
244	<listitem><para>
245	Specifies the name of the bandwidth group.
246	</para></listitem>
247	</varlistentry>
248	<varlistentry>
249	<term><option>--limit=<replaceable>bandwidth-limit</replaceable>[k\|m\|g\|K\|M\|G]</option></term>
250	<listitem><para>
251	Specifies the bandwidth limit for a bandwidth group. The
252	default unit is megabytes per second. You can modify this
253	value while the VM is running.
254	</para><para>
255	You can change the unit by appending one of the following
256	unit specifiers to the bandwidth limit:
257	</para><itemizedlist>
258	<listitem><para>
259	<literal>k</literal> – kilobits per second
260	</para></listitem>
261	<listitem><para>
262	<literal>m</literal> – megabits per second
263	</para></listitem>
264	<listitem><para>
265	<literal>g</literal> – gigabits per second
266	</para></listitem>
267	<listitem><para>
268	<literal>K</literal> – kilobytes per second
269	</para></listitem>
270	<listitem><para>
271	<literal>M</literal> – megabytes per second
272	</para></listitem>
273	<listitem><para>
274	<literal>G</literal> – gigabytes per second
275	</para></listitem>
276	</itemizedlist></listitem>
277	</varlistentry>
278	</variablelist>
279	</refsect2>
280	</refsect1>
281
282	<refsect1 id="vboxmanage-bandwidthctl-examples">
283	<title>Examples</title>
284	<remark role="help-scope" condition="GLOBAL"/>
285	<para>
286	The following example shows how to use the <command>VBoxManage
287	bandwidthctl</command> command to create the
288	<literal>Limit</literal> bandwidth group and set the limit to 20
289	Mbps. Then use the <command>VBoxManage modifyvm</command> command
290	to assign this bandwidth group to the first and second adapters of
291	the <literal>vm1</literal> VM.
292	</para>
293	<screen>$ VBoxManage bandwidthctl "vm1" add Limit --type network --limit 20m
294	$ VBoxManage modifyvm "vm1" --nicbandwidthgroup1 Limit
295	$ VBoxManage modifyvm "vm1" --nicbandwidthgroup2 Limit</screen>
296	<para>
297	You can dynamically modify the limit of a bandwidth group while
298	the VM is running. The following example shows how to modify the
299	limit for the <literal>Limit</literal> bandwidth group from 20
300	Mbps to 100 kbps:
301	</para>
302	<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 100k</screen>
303	<para>
304	The following command disables shaping for all adapters in the
305	<literal>Limit</literal> bandwidth group by specifying a limit of
306	zero (<literal>0</literal>):
307	</para>
308	<screen>$ VBoxManage bandwidthctl "vm1" set Limit --limit 0</screen>
309	</refsect1>
310	</refentry>

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

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-bandwidthctl.xml@ 105298

Download in other formats: