1USBGUARD(1) USBGUARD(1)
2
3
4
6 usbguard - USBGuard command-line interface
7
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
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
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
299 Generating an initial policy:
300
301 Allow device(s):
302
304 usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)
305
306
307
308 01/14/2021 USBGUARD(1)