VirtualBox

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

Last change on this file since 103131 was 99497, checked in by vboxsync, 19 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 Author Date Id Revision
File size: 14.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage usbfilter
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-usbfilter" lang="en">
32 <refentryinfo>
33 <pubdate>$Date: 2023-04-21 01:55:02 +0000 (Fri, 21 Apr 2023) $</pubdate>
34 <title>VBoxManage usbfilter</title>
35 </refentryinfo>
36
37 <refmeta>
38 <refentrytitle>VBoxManage-usbfilter</refentrytitle>
39 <manvolnum>1</manvolnum>
40 </refmeta>
41
42 <refnamediv>
43 <refname>VBoxManage-usbfilter</refname>
44 <refpurpose>manage USB filters</refpurpose>
45 <refclass>&product-name;</refclass>
46 </refnamediv>
47
48 <refsynopsisdiv>
49<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
50 <cmdsynopsis id="synopsis-vboxmanage-usbfilter-add">
51 <command>VBoxManage usbfilter add</command>
52 <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg>
53 <arg choice="req">--target=<group choice="req">
54 <arg choice="plain"><replaceable>uuid</replaceable></arg>
55 <arg choice="plain"><replaceable>vmname</replaceable></arg>
56 <arg choice="plain">global</arg>
57 </group></arg>
58 <arg choice="req">--name=<replaceable>string</replaceable></arg>
59 <arg choice="req">--action=ignore | hold</arg>
60 <arg>--active=yes | no</arg>
61 <arg>--vendorid=<replaceable>XXXX</replaceable></arg>
62 <arg>--productid=<replaceable>XXXX</replaceable></arg>
63 <arg>--revision=<replaceable>IIFF</replaceable></arg>
64 <arg>--manufacturer=<replaceable>string</replaceable></arg>
65 <arg>--product=<replaceable>string</replaceable></arg>
66 <arg>--port=<replaceable>hex</replaceable></arg>
67 <arg>--remote=yes | no</arg>
68 <arg>--serialnumber=<replaceable>string</replaceable></arg>
69 <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg>
70 </cmdsynopsis>
71
72 <cmdsynopsis id="synopsis-vboxmanage-usbfilter-modify">
73 <command>VBoxManage usbfilter modify</command>
74 <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg>
75 <arg choice="req">--target=<group choice="req">
76 <arg choice="plain"><replaceable>uuid</replaceable></arg>
77 <arg choice="plain"><replaceable>vmname</replaceable></arg>
78 <arg choice="plain">global</arg>
79 </group></arg>
80 <arg>--name=<replaceable>string</replaceable></arg>
81 <arg>--action=ignore | hold</arg>
82 <arg>--active=yes | no</arg>
83 <arg>--vendorid=<replaceable>XXXX</replaceable> | ""</arg>
84 <arg>--productid=<replaceable>XXXX</replaceable> | ""</arg>
85 <arg>--revision=<replaceable>IIFF</replaceable> | ""</arg>
86 <arg>--manufacturer=<replaceable>string</replaceable> | ""</arg>
87 <arg>--product=<replaceable>string</replaceable> | ""</arg>
88 <arg>--port=<replaceable>hex</replaceable></arg>
89 <arg>--remote=yes | no</arg>
90 <arg>--serialnumber=<replaceable>string</replaceable> | ""</arg>
91 <arg>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></arg>
92 </cmdsynopsis>
93
94 <cmdsynopsis id="synopsis-vboxmanage-usbfilter-remove">
95 <command>VBoxManage usbfilter remove</command>
96 <arg choice="req"><replaceable>index</replaceable>,0-<replaceable>N</replaceable></arg>
97 <arg choice="req">--target=<group choice="req">
98 <arg choice="plain"><replaceable>uuid</replaceable></arg>
99 <arg choice="plain"><replaceable>vmname</replaceable></arg>
100 <arg choice="plain">global</arg>
101 </group></arg>
102 </cmdsynopsis>
103 </refsynopsisdiv>
104
105 <refsect1 id="vboxmanage-usbfilter-description">
106 <title>Description</title>
107 <para>
108 The <command>VBoxManage usbfilter</command> command enables you to
109 manage USB filters for a specific virtual machine (VM), or global
110 USB filters that affect the entire &product-name; configuration.
111 </para>
112 <para>
113 Global filters are applied before VM-specific filters. This means
114 that you can use a global filter to prevent devices from being
115 captured by any VM.
116 </para>
117 <para>
118 Global filters are applied in a particular order. Only the first
119 filter that fits a device is applied. For example, the first
120 global filter makes a specific Kingston memory stick device
121 available while the second filter ignores all Kingston devices.
122 The result of applying these filters is that the specific Kingston
123 memory stick is made available to any machine that has the
124 appropriate filter, but no other Kingston devices are made
125 available.
126 </para>
127 <refsect2 id="vboxmanage-usbfilter-common">
128 <title>Common Operand and Options</title>
129 <variablelist>
130 <varlistentry>
131 <term>index,0-<replaceable>N</replaceable></term>
132 <listitem><para>
133 Specifies a single integer that indicates the position of
134 the filter in the list. Zero (<literal>0</literal>)
135 represents the first position in the list. If a filter
136 already exists at the specified position, the existing
137 filter and any existing filters that follow are moved down
138 the list. Otherwise, the new filter is appended to the
139 list.
140 </para></listitem>
141 </varlistentry>
142 <varlistentry>
143 <term><option>--action=ignore | hold</option></term>
144 <listitem><para>
145 Specifies whether to permit VMs access to devices that fit
146 the filter description (<literal>hold</literal>) or to
147 deny them access (<literal>ignore</literal>). This option
148 applies only to global filters.
149 </para></listitem>
150 </varlistentry>
151 <varlistentry>
152 <term><option>--active=yes | no</option></term>
153 <listitem><para>
154 Specifies whether the USB filter is active or temporarily
155 disabled. Valid values are <literal>yes</literal>, which
156 activates the filter, and <literal>no</literal>, which
157 disables the filter. The default value is
158 <literal>yes</literal>.
159 </para></listitem>
160 </varlistentry>
161 <varlistentry>
162 <term><option>--manufacturer=<replaceable>string</replaceable></option></term>
163 <listitem><para>
164 Specifies a manufacturer ID filter as a string. The
165 default value is an empty string (<literal>""</literal>).
166 </para></listitem>
167 </varlistentry>
168 <varlistentry>
169 <term><option>--maskedinterfaces=<replaceable>XXXXXXXX</replaceable></option></term>
170 <listitem><para>
171 Specifies a masked interface filter that is used to hide
172 one or more USB interfaces from the guest. The value is a
173 bit mask where the set bits correspond to the USB
174 interfaces to hide, or mask off. This feature is supported
175 on Linux host systems only.
176 </para></listitem>
177 </varlistentry>
178 <varlistentry>
179 <term><option>--name=<replaceable>filter-name</replaceable></option></term>
180 <listitem><para>
181 Specifies the name of the filter.
182 </para></listitem>
183 </varlistentry>
184 <varlistentry>
185 <term><option>--port=<replaceable>hex</replaceable></option></term>
186 <listitem><para>
187 Specifies a hub port number filter as a string. The default
188 value is an empty string (<literal>""</literal>).
189 </para></listitem>
190 </varlistentry>
191 <varlistentry>
192 <term><option>--product=<replaceable>string</replaceable></option></term>
193 <listitem><para>
194 Specifies a product ID filter as a string. The default
195 value is an empty string (<literal>""</literal>).
196 </para></listitem>
197 </varlistentry>
198 <varlistentry>
199 <term><option>--productid=<replaceable>XXXX</replaceable></option></term>
200 <listitem><para>
201 Specifies a product ID filter. The string representation
202 for an exact match has the form
203 <replaceable>XXXX</replaceable>, where
204 <replaceable>X</replaceable> is a hexadecimal digit
205 including leading zeroes. The default value is an empty string
206 (<literal>""</literal>).
207 </para></listitem>
208 </varlistentry>
209 <varlistentry>
210 <term><option>--remote=yes | no</option></term>
211 <listitem><para>
212 Specifies a remote filter that indicates whether the
213 device is physically connected to a remote VRDE client or
214 to a local host system. This option applies to VM filters
215 only. The default value is an empty string
216 (<literal>""</literal>).
217 </para><remark>
218 Why is the default value an empty string when valid values
219 are <literal>yes</literal> or <literal>no</literal>?
220 </remark></listitem>
221 </varlistentry>
222 <varlistentry>
223 <term><option>--revision=<replaceable>IIFF</replaceable></option></term>
224 <listitem><para>
225 Specifies a revision ID filter. The string representation
226 for an exact match has the form
227 <replaceable>IIFF</replaceable>.
228 <replaceable>I</replaceable> is a decimal digit of the
229 integer part of the revision. <replaceable>F</replaceable>
230 is a decimal digit of its fractional part that includes
231 leading and trailing zeros. The default value is an empty
232 string (<literal>""</literal>).
233 </para><para>
234 To specify a range of revision IDs, ensure that you use
235 the hexadecimal form so that the revision is stored as a
236 16-bit packed BCD value. For example, the
237 <literal>int:0x0100-0x0199</literal> expression matches
238 any revision from 1.0 to 1.99, inclusive.
239 </para></listitem>
240 </varlistentry>
241 <varlistentry>
242 <term><option>--serialnumber=<replaceable>string</replaceable></option></term>
243 <listitem><para>
244 Specifies a serial number filter as a string. The default
245 value is an empty string (<literal>""</literal>).
246 </para></listitem>
247 </varlistentry>
248 <varlistentry>
249 <term><option>--target=<replaceable>uuid</replaceable> | <replaceable>vmname</replaceable> | global</option></term>
250 <listitem><para>
251 Specifies the VM that the filter is attached to. You can
252 specify the Universally Unique Identifier (UUID) or the
253 name of the VM. To apply the filter description to all
254 VMs, specify <literal>global</literal>.
255 </para></listitem>
256 </varlistentry>
257 <varlistentry>
258 <term><option>--vendorid=<replaceable>XXXX</replaceable></option></term>
259 <listitem><para>
260 Specifies a vendor ID filter, which is a string
261 representation of a four-digit hexadecimal number.
262 <replaceable>X</replaceable> is the hexadecimal digit
263 including leading zeroes. The default value is an empty
264 string (<literal>""</literal>).
265 </para></listitem>
266 </varlistentry>
267 </variablelist>
268 </refsect2>
269 <refsect2 id="vboxmanage-usbfilter-add">
270 <title>Add a USB Filter or a Global Filter</title>
271 <remark role="help-copy-synopsis"/>
272 <para>
273 Use the <command>VBoxManage usbfilter add</command> command to
274 create a new USB filter.
275 </para>
276 <para>
277 In addition, specify parameters by which to filter. You can use
278 the <command>VBoxManage list usbhost</command> command to view
279 the parameters for devices that are attached to your system.
280 </para>
281 </refsect2>
282 <refsect2 id="vboxmanage-usbfilter-modify">
283 <title>Modify a USB Filter or a Global Filter</title>
284 <remark role="help-copy-synopsis"/>
285 <para>
286 Use the <command>VBoxManage usbfilter modify</command> command
287 to modify a USB filter. You can use the <command>VBoxManage list
288 usbfilters</command> command to list global filter indexes and
289 the <command>VBoxManage showvminfo</command> command to list
290 indexes for a specific machine.
291 </para>
292 </refsect2>
293 <refsect2 id="vboxmanage-usbfilter-remove">
294 <title>Remove a USB Filter or a Global Filter</title>
295 <remark role="help-copy-synopsis"/>
296 <para>
297 Use the <command>VBoxManage usbfilter remove</command> command
298 to remove a USB filter entry.
299 </para>
300 </refsect2>
301 </refsect1>
302
303 <refsect1 id="vboxmanage-usbfilter-examples">
304 <title>Examples</title>
305 <remark role="help-scope" condition="GLOBAL" />
306 <para>
307 The following command lists the available USB devices on the host
308 system.
309 </para>
310<screen>$ VBoxManage list usbhost</screen>
311 <para>
312 The following command adds a USB filter called
313 <filename>filter01</filename> to the <filename>ol7</filename> VM.
314 The filter specifies a Kingston DataTraveler memory stick and is
315 placed first in the list of USB filters for the VM.
316 </para>
317<screen>$ VBoxManage usbfilter add 0 --target ol7 --name filter01 --vendorid 0x0930 --productid 0x6545</screen>
318 <para>
319 The following command removes the USB filter that is second in the
320 list for the <filename>ol7</filename> VM.
321 </para>
322<screen>$ VBoxManage usbfilter remove 1 --target ol7</screen>
323 </refsect1>
324</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