'\" t
.\"     Title: usbguard
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/23/2024
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "USBGUARD" "1" "09/23/2024" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
usbguard \- USBGuard command\-line interface
.SH "SYNOPSIS"
.sp
usbguard [OPTIONS]\ \&<subcommand>\ \&[SUBCOMMAND\-OPTIONS]\ \&\&...
.sp
usbguard get\-parameter \fIname\fR
.sp
usbguard set\-parameter \fIname\fR \fIvalue\fR
.sp
usbguard list\-devices
.sp
usbguard\ \&allow\-device\ \&\fIid\fR | \fIrule\fR | \fIpartial\-rule\fR
.sp
usbguard\ \&block\-device\ \&\fIid\fR | \fIrule\fR | \fIpartial\-rule\fR
.sp
usbguard\ \&reject\-device\ \&\fIid\fR | \fIrule\fR | \fIpartial\-rule\fR
.sp
usbguard\ \&list\-rules
.sp
usbguard\ \&append\-rule\ \&\fIrule\fR
.sp
usbguard\ \&remove\-rule\ \&\fIid\fR
.sp
usbguard\ \&generate\-policy
.sp
usbguard\ \&watch
.sp
usbguard read\-descriptor \fIfile\fR
.sp
usbguard add\-user \fIname\fR
.sp
usbguard remove\-user \fIname\fR
.SH "DESCRIPTION"
.sp
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\&.
.SH "SUBCOMMANDS"
.SS "get\-parameter [\fIOPTIONS\fR] \fIname\fR"
.sp
Get the value of a runtime parameter\&. Parameter \fIname\fR is one of \fIInsertedDevicePolicy\fR and \fIImplicitPolicyTarget\fR\&.
.sp
Available options:
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "set\-parameter [\fIOPTIONS\fR] \fIname\fR \fIvalue\fR"
.sp
Set the value of a runtime parameter\&. Parameter \fIname\fR is one of \fIInsertedDevicePolicy\fR and \fIImplicitPolicyTarget\fR\&.
.sp
Available options:
.PP
\fB\-v, \-\-verbose\fR
.RS 4
Print the previous and new attribute value\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "list\-devices [\fIOPTIONS\fR]"
.sp
List all USB devices recognized by the USBGuard daemon\&.
.sp
Available options:
.PP
\fB\-a, \-\-allowed\fR
.RS 4
List allowed devices\&.
.RE
.PP
\fB\-b, \-\-blocked\fR
.RS 4
List blocked devices\&.
.RE
.PP
\fB\-t, \-\-tree\fR
.RS 4
List devices in a tree format\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "allow\-device [\fIOPTIONS\fR] < \fIid\fR | \fIrule\fR | \fIpartial\-rule\fR >"
.sp
Authorize a device to interact with the system\&. The device can be identified by either a device \fIid\fR, \fIrule\fR or \fIpartial\-rule\fR (rule without target)\&. Both \fIrule\fR and \fIpartial\-rule\fR can be used to allow multiple devices at once\&. Note that \fIid\fR refers to the internal device\-rule ID (the very first number of the list\-devices command output) rather than the device\(cqs ID attribute\&.
.sp
Available options:
.PP
\fB\-p, \-\-permanent\fR
.RS 4
Make the decision permanent\&. A device specific allow rule will be appended to the current policy\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "block\-device [\fIOPTIONS\fR] < \fIid\fR | \fIrule\fR | \fIpartial\-rule\fR >"
.sp
Deauthorize a device\&. The device can be identified by either a device \fIid\fR, \fIrule\fR or \fIpartial\-rule\fR (rule without target)\&. Both \fIrule\fR and \fIpartial\-rule\fR can be used to block multiple devices at once\&. Note that \fIid\fR refers to the internal device\-rule ID (the very first number of the list\-devices command output) rather than the device\(cqs ID attribute\&.
.sp
Available options:
.PP
\fB\-p, \-\-permanent\fR
.RS 4
Make the decision permanent\&. A device specific block rule will be appended to the current policy\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "reject\-device [\fIOPTIONS\fR] < \fIid\fR | \fIrule\fR | \fIpartial\-rule\fR >"
.sp
Deauthorize and remove a device\&. The device can be identified by either a device \fIid\fR, \fIrule\fR or \fIpartial\-rule\fR (rule without target)\&. Both \fIrule\fR and \fIpartial\-rule\fR can be used to reject multiple devices at once\&. Note that \fIid\fR refers to the internal device\-rule ID (the very first number of the list\-devices command output) rather than the device\(cqs ID attribute\&.
.sp
Available options:
.PP
\fB\-p, \-\-permanent\fR
.RS 4
Make the decision permanent\&. A device specific reject rule will be appended to the current policy\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "list\-rules [\fIOPTIONS\fR]"
.sp
List the rule set (policy) used by the USBGuard daemon\&.
.sp
Available options:
.PP
\fB\-d, \-\-show\-devices\fR
.RS 4
Show all devices which are affected by the specific rule\&.
.RE
.PP
\fB\-l, \-\-label\fR \fIlabel\fR
.RS 4
Only show rules having a specific label\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "append\-rule [\fIOPTIONS\fR] \fIrule\fR"
.sp
Append the \fIrule\fR to the current rule set\&.
.sp
Available options:
.PP
\fB\-a, \-\-after\fR \fIid\fR
.RS 4
Append the new rule after a rule with the specified rule
\fIid\fR\&.
.RE
.PP
\fB\-t, \-\-temporary\fR
.RS 4
Make the decision temporary\&. The rule policy file will not be updated\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "remove\-rule [\fIOPTIONS\fR] \fIid\fR"
.sp
Remove a rule identified by the rule \fIid\fR from the rule set\&.
.sp
Available options:
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "generate\-policy [\fIOPTIONS\fR]"
.sp
Generate a rule set (policy) which authorizes the currently connected USB devices\&.
.sp
Available options:
.PP
\fB\-p, \-\-with\-ports\fR
.RS 4
Generate port specific rules for all devices\&. By default, port specific rules are generated only for devices which do not export an iSerial value\&.
.RE
.PP
\fB\-P, \-\-no\-ports\-sn\fR
.RS 4
Don\(cqt 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\(cqt 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\&.
.RE
.PP
\fB\-d, \-\-devpath\fR \fIdevpath\fR
.RS 4
Only generate a rule for the device at the specified sub path of /sys\&.
.RE
.PP
\fB\-t, \-\-target\fR \fItarget\fR
.RS 4
Generate an explicit "catch all" rule with the specified target\&. The target can be one of the following values:
\fBallow\fR,
\fBblock\fR,
\fBreject\fR
.RE
.PP
\fB\-X, \-\-no\-hashes\fR
.RS 4
Don\(cqt generate a hash attribute for each device\&.
.RE
.PP
\fB\-H, \-\-hash\-only\fR
.RS 4
Generate a hash\-only policy\&.
.RE
.PP
\fB\-L, \-\-ldif\fR
.RS 4
Generate a ldif policy for LDAP\&.
.RE
.PP
\fB\-b, \-\-usbguardbase\fR \fIbase\fR
.RS 4
Generate a ldif policy for LDAP with this base\&. This option is required when \-\-ldif was specified\&.
.RE
.PP
\fB\-o, \-\-objectclass\fR \fIobjectclass\fR
.RS 4
Generate a ldif policy for LDAP with this objectClass\&.
.RE
.PP
\fB\-n, \-\-name\-prefix\fR \fIprefix\fR
.RS 4
Generate a ldif policy for LDAP with this name prefix\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "watch [\fIOPTIONS\fR]"
.sp
Watch the IPC interface events and print them to stdout\&.
.sp
Available options:
.PP
\fB\-w, \-\-wait\fR
.RS 4
Wait for IPC connection to become available\&.
.RE
.PP
\fB\-o, \-\-once\fR
.RS 4
Wait only when starting, if needed\&. Exit when the connection is lost\&.
.RE
.PP
\fB\-e, \-\-exec\fR \fIpath\fR
.RS 4
Run an executable file located at
\fIpath\fR
for every event\&. Pass event data to the process via environment variables\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "read\-descriptor [\fIOPTIONS\fR] \fIfile\fR"
.sp
Read a USB descriptor from a file and print it in human\-readable form\&.
.sp
Available options:
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SS "add\-user \fIname\fR [\fIOPTIONS\fR]"
.sp
Create an IPC access control file allowing the user/group identified by \fIname\fR to use the USBGuard IPC bus\&. The change takes effect only after restarting the usbguard\-daemon(8) instance\&.
.sp
Available options:
.PP
\fB\-u, \-\-user\fR
.RS 4
The specified
\fIname\fR
represents a username or UID (default)\&.
.RE
.PP
\fB\-g, \-\-group\fR
.RS 4
The specified
\fIname\fR
represents a groupname or GID\&.
.RE
.PP
\fB\-p, \-\-policy\fR \fIprivileges\fR
.RS 4
Policy related privileges\&.
.RE
.PP
\fB\-d, \-\-devices\fR \fIprivileges\fR
.RS 4
Device related privileges\&.
.RE
.PP
\fB\-e, \-\-exceptions\fR \fIprivileges\fR
.RS 4
Exceptions related privileges\&.
.RE
.PP
\fB\-P, \-\-parameters\fR \fIprivileges\fR
.RS 4
Run\-time parameter related privileges\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.sp
Privileges:
.sp
The \fIprivileges\fR are expected to be in the form of a list separated by a colon:
.sp
.if n \{\
.RS 4
.\}
.nf
    $ sudo usbguard add\-user joe \-\-devices=listen,modify
.fi
.if n \{\
.RE
.\}
.sp
Consult the usbguard\-daemon\&.conf(5) man\-page for a detailed list of available privileges in each section\&. You can also use \fIALL\fR instead of \fIprivileges\fR to automatically assign all relevant privileges to a given section\&.
.SS "remove\-user \fIname\fR [\fIOPTIONS\fR]"
.sp
Remove an IPC access control file associated with the user/group identified by \fIname\fR\&. The change takes effect only after restarting the usbguard\-daemon(8) instance\&.
.sp
Available options:
.PP
\fB\-u, \-\-user\fR
.RS 4
The specified
\fIname\fR
represents a username or UID (default)\&.
.RE
.PP
\fB\-g, \-\-group\fR
.RS 4
The specified
\fIname\fR
represents a groupname or GID\&.
.RE
.PP
\fB\-h, \-\-help\fR
.RS 4
Show help\&.
.RE
.SH "EXAMPLES"
.sp
Generating an initial policy:
.sp
.if n \{\
.RS 4
.\}
.nf
    $ 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
.fi
.if n \{\
.RE
.\}
.sp
Allow device(s):
.sp
.if n \{\
.RS 4
.\}
.nf
    # 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 \e"Dell Wired Multimedia Keyboard\e"
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
usbguard\-daemon(8), usbguard\-daemon\&.conf(5), usbguard\-rules\&.conf(5)
.SH "BUGS"
.sp
If you find a bug in this software or if you\(cqd like to request a feature to be implemented, please file a ticket at https://github\&.com/USBGuard/usbguard/issues/new\&.
.SH "AUTHOR"
.sp
USBGuard was originally written by Daniel Kopeček\&. Many people have contributed to it\&.
.SH "RESOURCES"
.sp
Main web site: https://usbguard\&.github\&.io/
.SH "COPYING"
.sp
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\&.