usbguard - Man Page

USBGuard command-line interface

Synopsis

usbguard [OPTIONS] ​<subcommand> ​[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) 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) 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) 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) 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​.conf(5), usbguard-rules​.conf(5)

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​.

Info

09/25/2026