1USBGUARD(1)                                                        USBGUARD(1)
2
3
4

NAME

6       usbguard - USBGuard command-line interface
7

SYNOPSIS

9       usbguard [OPTIONS] <subcommand> [SUBCOMMAND-OPTIONS] ...
10
11       usbguard get-parameter name
12
13       usbguard set-parameter name value
14
15       usbguard list-devices
16
17       usbguard allow-device id | rule | partial-rule
18
19       usbguard block-device id | rule | partial-rule
20
21       usbguard reject-device id | rule | partial-rule
22
23       usbguard list-rules
24
25       usbguard append-rule rule
26
27       usbguard remove-rule id
28
29       usbguard generate-policy
30
31       usbguard watch
32
33       usbguard read-descriptor file
34
35       usbguard add-user name
36
37       usbguard remove-user name
38

DESCRIPTION

40       The usbguard command provides a command-line interface (CLI) to a
41       running usbguard-daemon(8) instance. It also provides a tool for
42       generating initial USBGuard policies based on USB devices connected to
43       the system.
44

SUBCOMMANDS

46   get-parameter [OPTIONS] name
47       Get the value of a runtime parameter. Parameter name is one of
48       InsertedDevicePolicy and ImplicitPolicyTarget.
49
50       Available options:
51
52       -h, --help
53           Show help.
54
55   set-parameter [OPTIONS] name value
56       Set the value of a runtime parameter. Parameter name is one of
57       InsertedDevicePolicy and ImplicitPolicyTarget.
58
59       Available options:
60
61       -v, --verbose
62           Print the previous and new attribute value.
63
64       -h, --help
65           Show help.
66
67   list-devices [OPTIONS]
68       List all USB devices recognized by the USBGuard daemon.
69
70       Available options:
71
72       -a, --allowed
73           List allowed devices.
74
75       -b, --blocked
76           List blocked devices.
77
78       -t, --tree
79           List devices in a tree format.
80
81       -h, --help
82           Show help.
83
84   allow-device [OPTIONS] < id | rule | partial-rule >
85       Authorize a device to interact with the system. The device can be
86       identified by either a device id, rule or partial-rule (rule without
87       target). Both rule and partial-rule can be used to allow multiple
88       devices at once. Note that id refers to the internal device-rule ID
89       (the very first number of the list-devices command output) rather than
90       the device’s ID attribute.
91
92       Available options:
93
94       -p, --permanent
95           Make the decision permanent. A device specific allow rule will be
96           appended to the current policy.
97
98       -h, --help
99           Show help.
100
101   block-device [OPTIONS] < id | rule | partial-rule >
102       Deauthorize a device. The device can be identified by either a device
103       id, rule or partial-rule (rule without target). Both rule and
104       partial-rule can be used to block multiple devices at once. Note that
105       id refers to the internal device-rule ID (the very first number of the
106       list-devices command output) rather than the device’s ID attribute.
107
108       Available options:
109
110       -p, --permanent
111           Make the decision permanent. A device specific block rule will be
112           appended to the current policy.
113
114       -h, --help
115           Show help.
116
117   reject-device [OPTIONS] < id | rule | partial-rule >
118       Deauthorize and remove a device. The device can be identified by either
119       a device id, rule or partial-rule (rule without target). Both rule and
120       partial-rule can be used to reject multiple devices at once. Note that
121       id refers to the internal device-rule ID (the very first number of the
122       list-devices command output) rather than the device’s ID attribute.
123
124       Available options:
125
126       -p, --permanent
127           Make the decision permanent. A device specific reject rule will be
128           appended to the current policy.
129
130       -h, --help
131           Show help.
132
133   list-rules [OPTIONS]
134       List the rule set (policy) used by the USBGuard daemon.
135
136       Available options:
137
138       -d, --show-devices
139           Show all devices which are affected by the specific rule.
140
141       -l, --label label
142           Only show rules having a specific label.
143
144       -h, --help
145           Show help.
146
147   append-rule [OPTIONS] rule
148       Append the rule to the current rule set.
149
150       Available options:
151
152       -a, --after id
153           Append the new rule after a rule with the specified rule id.
154
155       -t, --temporary
156           Make the decision temporary. The rule policy file will not be
157           updated.
158
159       -h, --help
160           Show help.
161
162   remove-rule [OPTIONS] id
163       Remove a rule identified by the rule id from the rule set.
164
165       Available options:
166
167       -h, --help
168           Show help.
169
170   generate-policy [OPTIONS]
171       Generate a rule set (policy) which authorizes the currently connected
172       USB devices.
173
174       Available options:
175
176       -p, --with-ports
177           Generate port specific rules for all devices. By default, port
178           specific rules are generated only for devices which do not export
179           an iSerial value.
180
181       -P, --no-ports-sn
182           Don’t generate port specific rules for devices without an iSerial
183           value. Without this option, the tool will add a via-port attribute
184           to any device that doesn’t provide a serial number. This is a
185           security measure to limit devices that cannot be uniquely
186           identified to connect only via a specific port. This makes it
187           harder to bypass the policy since the real device will occupy the
188           allowed USB port most of the time.
189
190       -d, --devpath devpath
191           Only generate a rule for the device at the specified sub path of
192           /sys.
193
194       -t, --target target
195           Generate an explicit "catch all" rule with the specified target.
196           The target can be one of the following values: allow, block, reject
197
198       -X, --no-hashes
199           Don’t generate a hash attribute for each device.
200
201       -H, --hash-only
202           Generate a hash-only policy.
203
204       -L, --ldif
205           Generate a ldif policy for LDAP.
206
207       -b, --usbguardbase base
208           Generate a ldif policy for LDAP with this base. This option is
209           required when --ldif was specified.
210
211       -o, --objectclass objectclass
212           Generate a ldif policy for LDAP with this objectClass.
213
214       -n, --name-prefix prefix
215           Generate a ldif policy for LDAP with this name prefix.
216
217       -h, --help
218           Show help.
219
220   watch [OPTIONS]
221       Watch the IPC interface events and print them to stdout.
222
223       Available options:
224
225       -w, --wait
226           Wait for IPC connection to become available.
227
228       -o, --once
229           Wait only when starting, if needed. Exit when the connection is
230           lost.
231
232       -e, --exec path
233           Run an executable file located at path for every event. Pass event
234           data to the process via environment variables.
235
236       -h, --help
237           Show help.
238
239   read-descriptor [OPTIONS] file
240       Read a USB descriptor from a file and print it in human-readable form.
241
242       Available options:
243
244       -h, --help
245           Show help.
246
247   add-user name [OPTIONS]
248       Create an IPC access control file allowing the user/group identified by
249       name to use the USBGuard IPC bus. The change takes effect only after
250       restarting the usbguard-daemon(8) instance.
251
252       Available options:
253
254       -u, --user
255           The specified name represents a username or UID (default).
256
257       -g, --group
258           The specified name represents a groupname or GID.
259
260       -p, --policy privileges
261           Policy related privileges.
262
263       -d, --devices privileges
264           Device related privileges.
265
266       -e, --exceptions privileges
267           Exceptions related privileges.
268
269       -P, --parameters privileges
270           Run-time parameter related privileges.
271
272       -h, --help
273           Show help.
274
275       Privileges:
276
277       The privileges are expected to be in the form of a list separated by a
278       colon:
279
280               $ sudo usbguard add-user joe --devices=listen,modify
281
282       Consult the usbguard-daemon.conf(5) man-page for a detailed list of
283       available privileges in each section. You can also use ALL instead of
284       privileges to automatically assign all relevant privileges to a given
285       section.
286
287   remove-user name [OPTIONS]
288       Remove an IPC access control file associated with the user/group
289       identified by name. The change takes effect only after restarting the
290       usbguard-daemon(8) instance.
291
292       Available options:
293
294       -u, --user
295           The specified name represents a username or UID (default).
296
297       -g, --group
298           The specified name represents a groupname or GID.
299
300       -h, --help
301           Show help.
302

EXAMPLES

304       Generating an initial policy:
305
306       Allow device(s):
307

SEE ALSO

309       usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)
310
311
312
313                                  07/23/2022                       USBGUARD(1)
Impressum