- Timestamp:
- Mar 13, 2022 7:36:57 PM (3 years ago)
- Location:
- trunk
- Files:
-
- 7 edited
-
doc/manual/Config.kmk (modified) (1 diff)
-
doc/manual/en_US/man_VBoxManage-usbfilter.xml (modified) (2 diffs)
-
doc/manual/en_US/user_VBoxManage.xml (modified) (1 diff)
-
src/VBox/Frontends/VBoxManage/VBoxManage.cpp (modified) (1 diff)
-
src/VBox/Frontends/VBoxManage/VBoxManage.h (modified) (2 diffs)
-
src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (modified) (1 diff)
-
src/VBox/Frontends/VBoxManage/VBoxManageUSB.cpp (modified) (6 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/manual/Config.kmk
r94206 r94207 76 76 man_VBoxManage-setextradata.xml \ 77 77 man_VBoxManage-getextradata.xml \ 78 man_VBoxManage-setproperty.xml 78 man_VBoxManage-setproperty.xml \ 79 man_VBoxManage-usbfilter.xml 79 80 80 81 ## List of user manual XML files. -
trunk/doc/manual/en_US/man_VBoxManage-usbfilter.xml
r93737 r94207 20 20 <refentry id="vboxmanage-usbfilter" lang="en"> 21 21 <refentryinfo> 22 <pubdate> September 2019</pubdate>22 <pubdate>$Date$</pubdate> 23 23 <title>VBoxManage usbfilter</title> 24 24 </refentryinfo> … … 32 32 <refname>VBoxManage-usbfilter</refname> 33 33 <refpurpose>manage USB filters</refpurpose> 34 <refclass> Oracle VM VirtualBox</refclass>34 <refclass>&product-name;</refclass> 35 35 </refnamediv> 36 36 -
trunk/doc/manual/en_US/user_VBoxManage.xml
r94206 r94207 1107 1107 <xi:include href="user_man_VBoxManage-setproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> 1108 1108 1109 <sect1 id="vboxmanage-usbfilter"> 1110 1111 <title>VBoxManage usbfilter add/modify/remove</title> 1112 1113 <screen>VBoxManage usbfilter add <index,0-N> 1114 --target <uuid|vmname>global 1115 --name <string> 1116 --action ignore|hold (global filters only) 1117 [--active yes|no (yes)] 1118 [--vendorid <XXXX> (null)] 1119 [--productid <XXXX> (null)] 1120 [--revision <IIFF> (null)] 1121 [--manufacturer <string> (null)] 1122 [--product <string> (null)] 1123 [--remote yes|no (null, VM filters only)] 1124 [--serialnumber <string> (null)] 1125 [--maskedinterfaces <XXXXXXXX>] 1126 </screen> 1127 1128 <screen>VBoxManage usbfilter modify <index,0-N> 1129 --target <uuid|vmname>global 1130 [--name <string>] 1131 [--action ignore|hold (global filters only)] 1132 [--active yes|no] 1133 [--vendorid <XXXX>] 1134 [--productid <XXXX>] 1135 [--revision <IIFF>] 1136 [--manufacturer <string>] 1137 [--product <string>] 1138 [--remote yes|no (null, VM filters only)] 1139 [--serialnumber <string>] 1140 [--maskedinterfaces <XXXXXXXX>] 1141 </screen> 1142 1143 <screen>VBoxManage usbfilter remove <index,0-N> 1144 --target <uuid|vmname>global 1145 </screen> 1146 1147 <para> 1148 The <command>usbfilter</command> commands are used for working 1149 with USB filters in virtual machines, or global filters which 1150 affect the whole &product-name; setup. Global filters are applied 1151 before machine-specific filters, and may be used to prevent 1152 devices from being captured by any virtual machine. Global filters 1153 are always applied in a particular order, and only the first 1154 filter which fits a device is applied. For example, if the first 1155 global filter says to hold, or make available, a particular 1156 Kingston memory stick device and the second filter says to ignore 1157 all Kingston devices. That particular Kingston memory stick will 1158 be available to any machine with the appropriate filter, but no 1159 other Kingston device will. 1160 </para> 1161 1162 <para> 1163 When creating a USB filter using <command>usbfilter add</command>, 1164 you must supply three or four mandatory parameters. The index 1165 specifies the position in the list at which the filter should be 1166 placed. If there is already a filter at that position, then it and 1167 the following ones will be shifted back one place. Otherwise, the 1168 new filter will be added onto the end of the list. The 1169 <computeroutput>target</computeroutput> parameter selects the 1170 virtual machine that the filter should be attached to or use 1171 <computeroutput>global</computeroutput> to apply it to all virtual 1172 machines. <computeroutput>name</computeroutput> is a name for the 1173 new filter. For global filters, 1174 <computeroutput>action</computeroutput> says whether to allow VMs 1175 access to devices that fit the filter description (hold) or not to 1176 give them access (ignore). In addition, you should specify 1177 parameters to filter by. You can find the parameters for devices 1178 attached to your system using <command>VBoxManage list 1179 usbhost</command>. Finally, you can specify whether the filter 1180 should be active. For local filters, whether they are for local 1181 devices, remote devices over an RDP connection, or either. 1182 </para> 1183 1184 <para> 1185 When you modify a USB filter using <command>usbfilter 1186 modify</command>, you must specify the filter by index and by 1187 target, which is either a virtual machine or 1188 <computeroutput>global</computeroutput>. See the output of 1189 <command>VBoxManage list usbfilters</command> to find global 1190 filter indexes and <command>VBoxManage showvminfo</command> to 1191 find indexes for individual machines. The properties which can be 1192 changed are the same as for <command>usbfilter add</command>. To 1193 remove a filter, use <command>usbfilter remove</command> and 1194 specify the index and the target. 1195 </para> 1196 1197 <para> 1198 The following is a list of the additional <command>usbfilter 1199 add</command> and <command>usbfilter modify</command> options, 1200 with details of how to use them. 1201 </para> 1202 1203 <itemizedlist> 1204 1205 <listitem> 1206 <para> 1207 <computeroutput>--action ignore|hold</computeroutput>: 1208 Specifies whether devices that fit the filter description are 1209 allowed access by machines (hold), or have access denied 1210 (ignore). Applies to global filters only. 1211 </para> 1212 </listitem> 1213 1214 <listitem> 1215 <para> 1216 <computeroutput>--active yes|no</computeroutput>: Specifies 1217 whether the USB Filter is active or temporarily disabled. For 1218 <computeroutput>usbfilter create</computeroutput> the default 1219 is active. 1220 </para> 1221 </listitem> 1222 1223 <listitem> 1224 <para> 1225 <computeroutput>--vendorid <XXXX>|""</computeroutput>: 1226 Specifies a vendor ID filter. The string representation for an 1227 exact match has the form XXXX, where X is the hexadecimal 1228 digit, including leading zeroes. 1229 </para> 1230 </listitem> 1231 1232 <listitem> 1233 <para> 1234 <computeroutput>--productid <XXXX>|""</computeroutput>: 1235 Specifies a product ID filter. The string representation for 1236 an exact match has the form XXXX, where X is the hexadecimal 1237 digit, including leading zeroes. 1238 </para> 1239 </listitem> 1240 1241 <listitem> 1242 <para> 1243 <computeroutput>--revision <IIFF>|""</computeroutput>: 1244 Specifies a revision ID filter. The string representation for 1245 an exact match has the form IIFF, where I is the decimal digit 1246 of the integer part of the revision, and F is the decimal 1247 digit of its fractional part, including leading and trailing 1248 zeros. Note that for interval filters, it is best to use the 1249 hexadecimal form, because the revision is stored as a 16-bit 1250 packed BCD value. Therefore, the expression int:0x0100-0x0199 1251 will match any revision from 1.0 to 1.99 inclusive. 1252 </para> 1253 </listitem> 1254 1255 <listitem> 1256 <para> 1257 <computeroutput>--manufacturer 1258 <string>|""</computeroutput>: Specifies a manufacturer 1259 ID filter, as a string. 1260 </para> 1261 </listitem> 1262 1263 <listitem> 1264 <para> 1265 <computeroutput>--product <string>|""</computeroutput>: 1266 Specifies a product ID filter, as a string. 1267 </para> 1268 </listitem> 1269 1270 <listitem> 1271 <para> 1272 <computeroutput>--remote yes|no""</computeroutput>: Specifies 1273 a remote filter, indicating whether the device is physically 1274 connected to a remote VRDE client or to a local host machine. 1275 Applies to VM filters only. 1276 </para> 1277 </listitem> 1278 1279 <listitem> 1280 <para> 1281 <computeroutput>--serialnumber 1282 <string>|""</computeroutput>: Specifies a serial number 1283 filter, as a string. 1284 </para> 1285 </listitem> 1286 1287 <listitem> 1288 <para> 1289 <computeroutput>--maskedinterfaces 1290 <XXXXXXXX></computeroutput>: Specifies a masked 1291 interface filter, for hiding one or more USB interfaces from 1292 the guest. The value is a bit mask where the set bits 1293 correspond to the USB interfaces that should be hidden, or 1294 masked off. This feature only works on Linux hosts. 1295 </para> 1296 </listitem> 1297 1298 </itemizedlist> 1299 1300 </sect1> 1109 <xi:include href="user_man_VBoxManage-usbfilter.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> 1301 1110 1302 1111 <xi:include href="user_man_VBoxManage-sharedfolder.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" /> -
trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp
r94206 r94207 229 229 { "setextradata", USAGE_S_NEWCMD, HELP_CMD_SETEXTRADATA, handleSetExtraData, 0 }, 230 230 { "setproperty", USAGE_S_NEWCMD, HELP_CMD_SETPROPERTY, handleSetProperty, 0 }, 231 { "usbfilter", USAGE_ USBFILTER, VBMG_CMD_TODO, handleUSBFilter, 0 },231 { "usbfilter", USAGE_S_NEWCMD, HELP_CMD_USBFILTER, handleUSBFilter, 0 }, 232 232 { "sharedfolder", USAGE_S_NEWCMD, HELP_CMD_SHAREDFOLDER, handleSharedFolder, 0 }, 233 233 #ifdef VBOX_WITH_GUEST_PROPS -
trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h
r94206 r94207 101 101 USAGE_CREATEHOSTIF, 102 102 USAGE_REMOVEHOSTIF, 103 USAGE_USBFILTER,104 103 USAGE_I_LOADSYMS, 105 104 USAGE_I_LOADMAP, … … 139 138 140 139 141 #define HELP_SCOPE_USBFILTER_ADD RT_BIT_64(0)142 #define HELP_SCOPE_USBFILTER_MODIFY RT_BIT_64(1)143 #define HELP_SCOPE_USBFILTER_REMOVE RT_BIT_64(2)144 145 140 #ifdef VBOX_WITH_GUEST_CONTROL 146 141 # define HELP_SCOPE_GSTCTRL_RUN RT_BIT(0) -
trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp
r94206 r94207 639 639 "\n", SEP); 640 640 641 if (enmCommand == USAGE_USBFILTER || enmCommand == USAGE_S_ALL)642 {643 if (fSubcommandScope & HELP_SCOPE_USBFILTER_ADD)644 RTStrmPrintf(pStrm,645 "%s usbfilter %s add <index,0-N>\n"646 " --target <uuid|vmname>|global\n"647 " --name <string>\n"648 " --action ignore|hold (global filters only)\n"649 " [--active yes|no] (yes)\n"650 " [--vendorid <XXXX>] (null)\n"651 " [--productid <XXXX>] (null)\n"652 " [--revision <IIFF>] (null)\n"653 " [--manufacturer <string>] (null)\n"654 " [--product <string>] (null)\n"655 " [--remote yes|no] (null, VM filters only)\n"656 " [--serialnumber <string>] (null)\n"657 " [--maskedinterfaces <XXXXXXXX>]\n"658 "\n", SEP);659 660 if (fSubcommandScope & HELP_SCOPE_USBFILTER_MODIFY)661 RTStrmPrintf(pStrm,662 "%s usbfilter %s modify <index,0-N>\n"663 " --target <uuid|vmname>|global\n"664 " [--name <string>]\n"665 " [--action ignore|hold] (global filters only)\n"666 " [--active yes|no]\n"667 " [--vendorid <XXXX>|\"\"]\n"668 " [--productid <XXXX>|\"\"]\n"669 " [--revision <IIFF>|\"\"]\n"670 " [--manufacturer <string>|\"\"]\n"671 " [--product <string>|\"\"]\n"672 " [--remote yes|no] (null, VM filters only)\n"673 " [--serialnumber <string>|\"\"]\n"674 " [--maskedinterfaces <XXXXXXXX>]\n"675 "\n", SEP);676 677 if (fSubcommandScope & HELP_SCOPE_USBFILTER_REMOVE)678 RTStrmPrintf(pStrm,679 "%s usbfilter %s remove <index,0-N>\n"680 " --target <uuid|vmname>|global\n"681 "\n", SEP);682 }683 684 641 #ifdef VBOX_WITH_GUEST_PROPS 685 642 if (enmCommand == USAGE_GUESTPROPERTY || enmCommand == USAGE_S_ALL) -
trunk/src/VBox/Frontends/VBoxManage/VBoxManageUSB.cpp
r93115 r94207 176 176 /* at least: 0: command, 1: index, 2: --target, 3: <target value> */ 177 177 if (a->argc < 4) 178 return errorSyntax(U SAGE_USBFILTER, Usb::tr("Not enough parameters"));178 return errorSyntax(Usb::tr("Not enough parameters")); 179 179 180 180 /* which command? */ 181 181 cmd.mAction = USBFilterCmd::Invalid; 182 if (!strcmp(a->argv[0], "add")) cmd.mAction = USBFilterCmd::Add; 183 else if (!strcmp(a->argv[0], "modify")) cmd.mAction = USBFilterCmd::Modify; 184 else if (!strcmp(a->argv[0], "remove")) cmd.mAction = USBFilterCmd::Remove; 182 if (!strcmp(a->argv[0], "add")) 183 { 184 cmd.mAction = USBFilterCmd::Add; 185 setCurrentSubcommand(HELP_SCOPE_USBFILTER_ADD); 186 } 187 else if (!strcmp(a->argv[0], "modify")) 188 { 189 cmd.mAction = USBFilterCmd::Modify; 190 setCurrentSubcommand(HELP_SCOPE_USBFILTER_MODIFY); 191 } 192 else if (!strcmp(a->argv[0], "remove")) 193 { 194 cmd.mAction = USBFilterCmd::Remove; 195 setCurrentSubcommand(HELP_SCOPE_USBFILTER_REMOVE); 196 } 185 197 186 198 if (cmd.mAction == USBFilterCmd::Invalid) 187 return errorSyntax(U SAGE_USBFILTER, Usb::tr("Invalid parameter '%s'"), a->argv[0]);199 return errorSyntax(Usb::tr("Invalid parameter '%s'"), a->argv[0]); 188 200 189 201 /* which index? */ 190 202 if (VINF_SUCCESS != RTStrToUInt32Full(a->argv[1], 10, &cmd.mIndex)) 191 return errorSyntax(U SAGE_USBFILTER, Usb::tr("Invalid index '%s'"), a->argv[1]);203 return errorSyntax(Usb::tr("Invalid index '%s'"), a->argv[1]); 192 204 193 205 switch (cmd.mAction) … … 200 212 { 201 213 if (cmd.mAction == USBFilterCmd::Add) 202 return errorSyntax Ex(USAGE_USBFILTER, HELP_SCOPE_USBFILTER_ADD,Usb::tr("Not enough parameters"));203 204 return errorSyntax Ex(USAGE_USBFILTER, HELP_SCOPE_USBFILTER_MODIFY,Usb::tr("Not enough parameters"));214 return errorSyntax(Usb::tr("Not enough parameters")); 215 216 return errorSyntax(Usb::tr("Not enough parameters")); 205 217 } 206 218 … … 332 344 } 333 345 else 334 return errorSyntaxEx(USAGE_USBFILTER, cmd.mAction == USBFilterCmd::Add ? HELP_SCOPE_USBFILTER_ADD : HELP_SCOPE_USBFILTER_MODIFY, 335 Usb::tr("Unknown option '%s'"), a->argv[i]); 346 return errorSyntax(Usb::tr("Unknown option '%s'"), a->argv[i]); 336 347 } 337 348 … … 350 361 ) 351 362 { 352 return errorSyntax Ex(USAGE_USBFILTER, HELP_SCOPE_USBFILTER_ADD,Usb::tr("Mandatory options not supplied"));363 return errorSyntax(Usb::tr("Mandatory options not supplied")); 353 364 } 354 365 } … … 360 371 /* at least: 0: command, 1: index, 2: --target, 3: <target value> */ 361 372 if (a->argc < 4) 362 return errorSyntax Ex(USAGE_USBFILTER, HELP_SCOPE_USBFILTER_REMOVE,Usb::tr("Not enough parameters"));373 return errorSyntax(Usb::tr("Not enough parameters")); 363 374 364 375 for (int i = 2; i < a->argc; i++) … … 382 393 // mandatory options 383 394 if (!cmd.mGlobal && !cmd.mMachine) 384 return errorSyntax Ex(USAGE_USBFILTER, HELP_SCOPE_USBFILTER_REMOVE,Usb::tr("Mandatory options not supplied"));395 return errorSyntax(Usb::tr("Mandatory options not supplied")); 385 396 386 397 break;
Note:
See TracChangeset
for help on using the changeset viewer.
