NAME

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

                                            04/01/2024                                USBGUARD(1)