Section 1 · User commands

usbguard.1

Package: usbguard

On this page

USBGUARD

NAME
SYNOPSIS
DESCRIPTION
SUBCOMMANDS
EXAMPLES
SEE ALSO
BUGS
AUTHOR
RESOURCES
COPYING

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\“

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.