usbguard(1)
===========
:doctype: manpage


== 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:

include::example-initial-policy.adoc[]

Allow device(s):

include::example-allow-device.adoc[]


== SEE ALSO
link:usbguard-daemon.8.adoc#name[usbguard-daemon(8)],
link:usbguard-daemon.conf.5.adoc#name[usbguard-daemon.conf(5)],
link:usbguard-rules.conf.5.adoc#name[usbguard-rules.conf(5)]


include::footer.adoc[]
