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

EXAMPLES

299       Generating an initial policy:
300
301       Allow device(s):
302

SEE ALSO

304       usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)
305
306
307
308                                  01/14/2021                       USBGUARD(1)
Impressum