1USBGUARD(1) USBGUARD(1)
2
6 usbguard - USBGuard command-line interface
7
9 usbguard [OPTIONS] <subcommand> [SUBCOMMAND-OPTIONS] ...
10 usbguard get-parameter name
12 usbguard set-parameter name value
14 usbguard list-devices
16 usbguard allow-device id | rule | partial-rule
18 usbguard block-device id | rule | partial-rule
20 usbguard reject-device id | rule | partial-rule
22 usbguard list-rules
24 usbguard append-rule rule
26 usbguard remove-rule id
28 usbguard generate-policy
30 usbguard watch
32 usbguard read-descriptor file
34 usbguard add-user name
36 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 Available options:
51 -h, --help
53 Show help.
54 set-parameter [OPTIONS] name value
56 Set the value of a runtime parameter. Parameter name is one of
57 InsertedDevicePolicy and ImplicitPolicyTarget.
58 Available options:
60 -v, --verbose
62 Print the previous and new attribute value.
63 -h, --help
65 Show help.
66 list-devices [OPTIONS]
68 List all USB devices recognized by the USBGuard daemon.
69 Available options:
71 -a, --allowed
73 List allowed devices.
74 -b, --blocked
76 List blocked devices.
77 -t, --tree
79 List devices in a tree format.
80 -h, --help
82 Show help.
83 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 Available options:
93 -p, --permanent
95 Make the decision permanent. A device specific allow rule will be
96 appended to the current policy.
97 -h, --help
99 Show help.
100 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 Available options:
109 -p, --permanent
111 Make the decision permanent. A device specific block rule will be
112 appended to the current policy.
113 -h, --help
115 Show help.
116 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 Available options:
125 -p, --permanent
127 Make the decision permanent. A device specific reject rule will be
128 appended to the current policy.
129 -h, --help
131 Show help.
132 list-rules [OPTIONS]
134 List the rule set (policy) used by the USBGuard daemon.
135 Available options:
137 -d, --show-devices
139 Show all devices which are affected by the specific rule.
140 -l, --label label
142 Only show rules having a specific label.
143 -h, --help
145 Show help.
146 append-rule [OPTIONS] rule
148 Append the rule to the current rule set.
149 Available options:
151 -a, --after id
153 Append the new rule after a rule with the specified rule id.
154 -t, --temporary
156 Make the decision temporary. The rule policy file will not be
157 updated.
158 -h, --help
160 Show help.
161 remove-rule [OPTIONS] id
163 Remove a rule identified by the rule id from the rule set.
164 Available options:
166 -h, --help
168 Show help.
169 generate-policy [OPTIONS]
171 Generate a rule set (policy) which authorizes the currently connected
172 USB devices.
173 Available options:
175 -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 -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 -d, --devpath devpath
191 Only generate a rule for the device at the specified sub path of
192 /sys.
193 -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 -X, --no-hashes
199 Don’t generate a hash attribute for each device.
200 -H, --hash-only
202 Generate a hash-only policy.
203 -L, --ldif
205 Generate a ldif policy for LDAP.
206 -b, --usbguardbase base
208 Generate a ldif policy for LDAP with this base. This option is
209 required when --ldif was specified.
210 -o, --objectclass objectclass
212 Generate a ldif policy for LDAP with this objectClass.
213 -n, --name-prefix prefix
215 Generate a ldif policy for LDAP with this name prefix.
216 -h, --help
218 Show help.
219 watch [OPTIONS]
221 Watch the IPC interface events and print them to stdout.
222 Available options:
224 -w, --wait
226 Wait for IPC connection to become available.
227 -o, --once
229 Wait only when starting, if needed. Exit when the connection is
230 lost.
231 -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 -h, --help
237 Show help.
238 read-descriptor [OPTIONS] file
240 Read a USB descriptor from a file and print it in human-readable form.
241 Available options:
243 -h, --help
245 Show help.
246 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 Available options:
253 -u, --user
255 The specified name represents a username or UID (default).
256 -g, --group
258 The specified name represents a groupname or GID.
259 -p, --policy privileges
261 Policy related privileges.
262 -d, --devices privileges
264 Device related privileges.
265 -e, --exceptions privileges
267 Exceptions related privileges.
268 -P, --parameters privileges
270 Run-time parameter related privileges.
271 -h, --help
273 Show help.
274 Privileges:
276 The privileges are expected to be in the form of a list separated by a
278 colon:
279 $ sudo usbguard add-user joe --devices=listen,modify
281 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 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 Available options:
293 -u, --user
295 The specified name represents a username or UID (default).
296 -g, --group
298 The specified name represents a groupname or GID.
299 -h, --help
301 Show help.
302
304 Generating an initial policy:
305 Allow device(s):
307
309 usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)
310 07/27/2023 USBGUARD(1)