man_VBoxManage-bandwidthctl.xml@ 93707

Last change on this file since 93707 was 92984, checked in by vboxsync, 3 years ago
Doc/manual: bugref:9224: Added link to detailed information. Fixed typo in the man_VBoxManage-bandwidthctl.xml
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 12.0 KB

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

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

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

Download in other formats: