--- name: "usbguard" section: "1" platform: "linux" package: "usbguard" version: "1.1.4-11" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/usbguard" --- # usbguard(1) USBGuard command-line interface ## NAME usbguard - USBGuard command-line interface ## SYNOPSIS usbguard \[OPTIONS\] \ \[SUBCOMMAND-OPTIONS\] ... usbguard get-parameter *name* usbguard set-parameter *name* *value* usbguard list-devices usbguard allow-device *id* \| *rule* \| *partial-rule* usbguard block-device *id* \| *rule* \| *partial-rule* usbguard reject-device *id* \| *rule* \| *partial-rule* usbguard list-rules usbguard append-rule *rule* usbguard remove-rule *id* usbguard generate-policy usbguard watch usbguard read-descriptor *file* usbguard add-user *name* usbguard remove-user *name* ## DESCRIPTION The usbguard command provides a command-line interface (CLI) to a running [usbguard-daemon(8)](/usbguard-daemon/8.md) instance. It also provides a tool for generating initial USBGuard policies based on USB devices connected to the system. ## SUBCOMMANDS ### get-parameter \[*OPTIONS*\] *name* Get the value of a runtime parameter. Parameter *name* is one of *InsertedDevicePolicy* and *ImplicitPolicyTarget*. Available options: **-h, --help** Show help. ### set-parameter \[*OPTIONS*\] *name* *value* Set the value of a runtime parameter. Parameter *name* is one of *InsertedDevicePolicy* and *ImplicitPolicyTarget*. Available options: **-v, --verbose** Print the previous and new attribute value. **-h, --help** Show help. ### list-devices \[*OPTIONS*\] List all USB devices recognized by the USBGuard daemon. Available options: **-a, --allowed** List allowed devices. **-b, --blocked** List blocked devices. **-t, --tree** List devices in a tree format. **-h, --help** Show help. ### allow-device \[*OPTIONS*\] \< *id* \| *rule* \| *partial-rule* \> Authorize a device to interact with the system. The device can be identified by either a device *id*, *rule* or *partial-rule* (rule without target). Both *rule* and *partial-rule* can be used to allow multiple devices at once. Note that *id* refers to the internal device-rule ID (the very first number of the list-devices command output) rather than the device’s ID attribute. Available options: **-p, --permanent** Make the decision permanent. A device specific allow rule will be appended to the current policy. **-h, --help** Show help. ### block-device \[*OPTIONS*\] \< *id* \| *rule* \| *partial-rule* \> Deauthorize a device. The device can be identified by either a device *id*, *rule* or *partial-rule* (rule without target). Both *rule* and *partial-rule* can be used to block multiple devices at once. Note that *id* refers to the internal device-rule ID (the very first number of the list-devices command output) rather than the device’s ID attribute. Available options: **-p, --permanent** Make the decision permanent. A device specific block rule will be appended to the current policy. **-h, --help** Show help. ### reject-device \[*OPTIONS*\] \< *id* \| *rule* \| *partial-rule* \> Deauthorize and remove a device. The device can be identified by either a device *id*, *rule* or *partial-rule* (rule without target). Both *rule* and *partial-rule* can be used to reject multiple devices at once. Note that *id* refers to the internal device-rule ID (the very first number of the list-devices command output) rather than the device’s ID attribute. Available options: **-p, --permanent** Make the decision permanent. A device specific reject rule will be appended to the current policy. **-h, --help** Show help. ### list-rules \[*OPTIONS*\] List the rule set (policy) used by the USBGuard daemon. Available options: **-d, --show-devices** Show all devices which are affected by the specific rule. **-l, --label** *label* Only show rules having a specific label. **-h, --help** Show help. ### append-rule \[*OPTIONS*\] *rule* Append the *rule* to the current rule set. Available options: **-a, --after** *id* Append the new rule after a rule with the specified rule *id*. **-t, --temporary** Make the decision temporary. The rule policy file will not be updated. **-h, --help** Show help. ### remove-rule \[*OPTIONS*\] *id* Remove a rule identified by the rule *id* from the rule set. Available options: **-h, --help** Show help. ### generate-policy \[*OPTIONS*\] Generate a rule set (policy) which authorizes the currently connected USB devices. Available options: **-p, --with-ports** Generate port specific rules for all devices. By default, port specific rules are generated only for devices which do not export an iSerial value. **-P, --no-ports-sn** Don’t generate port specific rules for devices without an iSerial value. Without this option, the tool will add a via-port attribute to any device that doesn’t provide a serial number. This is a security measure to limit devices that cannot be uniquely identified to connect only via a specific port. This makes it harder to bypass the policy since the real device will occupy the allowed USB port most of the time. **-d, --devpath** *devpath* Only generate a rule for the device at the specified sub path of /sys. **-t, --target** *target* Generate an explicit "catch all" rule with the specified target. The target can be one of the following values: **allow**, **block**, **reject** **-X, --no-hashes** Don’t generate a hash attribute for each device. **-H, --hash-only** Generate a hash-only policy. **-L, --ldif** Generate a ldif policy for LDAP. **-b, --usbguardbase** *base* Generate a ldif policy for LDAP with this base. This option is required when --ldif was specified. **-o, --objectclass** *objectclass* Generate a ldif policy for LDAP with this objectClass. **-n, --name-prefix** *prefix* Generate a ldif policy for LDAP with this name prefix. **-h, --help** Show help. ### watch \[*OPTIONS*\] Watch the IPC interface events and print them to stdout. Available options: **-w, --wait** Wait for IPC connection to become available. **-o, --once** Wait only when starting, if needed. Exit when the connection is lost. **-e, --exec** *path* Run an executable file located at *path* for every event. Pass event data to the process via environment variables. **-h, --help** Show help. ### read-descriptor \[*OPTIONS*\] *file* Read a USB descriptor from a file and print it in human-readable form. Available options: **-h, --help** Show help. ### add-user *name* \[*OPTIONS*\] Create an IPC access control file allowing the user/group identified by *name* to use the USBGuard IPC bus. The change takes effect only after restarting the [usbguard-daemon(8)](/usbguard-daemon/8.md) instance. Available options: **-u, --user** The specified *name* represents a username or UID (default). **-g, --group** The specified *name* represents a groupname or GID. **-p, --policy** *privileges* Policy related privileges. **-d, --devices** *privileges* Device related privileges. **-e, --exceptions** *privileges* Exceptions related privileges. **-P, --parameters** *privileges* Run-time parameter related privileges. **-h, --help** Show help. Privileges: The *privileges* are expected to be in the form of a list separated by a colon: ``` $ sudo usbguard add-user joe --devices=listen,modify ``` Consult the [usbguard-daemon.conf(5)](/usbguard-daemon.conf/5.md) man-page for a detailed list of available privileges in each section. You can also use *ALL* instead of *privileges* to automatically assign all relevant privileges to a given section. ### remove-user *name* \[*OPTIONS*\] Remove an IPC access control file associated with the user/group identified by *name*. The change takes effect only after restarting the [usbguard-daemon(8)](/usbguard-daemon/8.md) instance. Available options: **-u, --user** The specified *name* represents a username or UID (default). **-g, --group** The specified *name* represents a groupname or GID. **-h, --help** Show help. ## EXAMPLES Generating an initial policy: ``` $ sudo usbguard generate-policy > rules.conf $ vi rules.conf (review/modify the rule set) $ sudo install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf $ sudo systemctl restart usbguard ``` Allow device(s): ``` # Allow a device by ID(it is the very first number from the list-devices command output) $ sudo usbguard allow-device 10 # Allow all devices named "Dell Wired Multimedia Keyboard" $ sudo usbguard allow-device name \"Dell Wired Multimedia Keyboard\" ``` ## SEE ALSO [usbguard-daemon(8)](/usbguard-daemon/8.md), [usbguard-daemon.conf(5)](/usbguard-daemon.conf/5.md), [usbguard-rules.conf(5)](/usbguard-rules.conf/5.md) ## BUGS If you find a bug in this software or if you’d like to request a feature to be implemented, please file a ticket at https://github.com/USBGuard/usbguard/issues/new. ## AUTHOR USBGuard was originally written by Daniel Kopeček. Many people have contributed to it. ## RESOURCES Main web site: https://usbguard.github.io/ ## COPYING License GPLv2+: GNU GPL version 2 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.