VirtualBox

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

Last change on this file since 103131 was 99513, checked in by vboxsync, 19 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> &ndash; kilobits per second
154 </para></listitem>
155 <listitem><para>
156 <literal>m</literal> &ndash; megabits per second
157 </para></listitem>
158 <listitem><para>
159 <literal>g</literal> &ndash; gigabits per second
160 </para></listitem>
161 <listitem><para>
162 <literal>K</literal> &ndash; kilobytes per second
163 </para></listitem>
164 <listitem><para>
165 <literal>M</literal> &ndash; megabytes per second
166 </para></listitem>
167 <listitem><para>
168 <literal>G</literal> &ndash; 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> &ndash; kilobits per second
260 </para></listitem>
261 <listitem><para>
262 <literal>m</literal> &ndash; megabits per second
263 </para></listitem>
264 <listitem><para>
265 <literal>g</literal> &ndash; gigabits per second
266 </para></listitem>
267 <listitem><para>
268 <literal>K</literal> &ndash; kilobytes per second
269 </para></listitem>
270 <listitem><para>
271 <literal>M</literal> &ndash; megabytes per second
272 </para></listitem>
273 <listitem><para>
274 <literal>G</literal> &ndash; 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.

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