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 -h, --help
79 Show help.
80 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 Available options:
90 -p, --permanent
92 Make the decision permanent. A device specific allow rule will be
93 appended to the current policy.
94 -h, --help
96 Show help.
97 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 Available options:
106 -p, --permanent
108 Make the decision permanent. A device specific block rule will be
109 appended to the current policy.
110 -h, --help
112 Show help.
113 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 Available options:
122 -p, --permanent
124 Make the decision permanent. A device specific reject rule will be
125 appended to the current policy.
126 -h, --help
128 Show help.
129 list-rules [OPTIONS]
131 List the rule set (policy) used by the USBGuard daemon.
132 Available options:
134 -d, --show-devices
136 Show all devices which are affected by the specific rule.
137 -l, --label label
139 Only show rules having a specific label.
140 -h, --help
142 Show help.
143 append-rule [OPTIONS] rule
145 Append the rule to the current rule set.
146 Available options:
148 -a, --after id
150 Append the new rule after a rule with the specified rule id.
151 -t, --temporary
153 Make the decision temporary. The rule policy file will not be
154 updated.
155 -h, --help
157 Show help.
158 remove-rule [OPTIONS] id
160 Remove a rule identified by the rule id from the rule set.
161 Available options:
163 -h, --help
165 Show help.
166 generate-policy [OPTIONS]
168 Generate a rule set (policy) which authorizes the currently connected
169 USB devices.
170 Available options:
172 -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 -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 -d, --devpath devpath
188 Only generate a rule for the device at the specified sub path of
189 /sys.
190 -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 -X, --no-hashes
196 Don’t generate a hash attribute for each device.
197 -H, --hash-only
199 Generate a hash-only policy.
200 -L, --ldif
202 Generate a ldif policy for LDAP.
203 -b, --usbguardbase base
205 Generate a ldif policy for LDAP with this base. This option is
206 required when --ldif was specified.
207 -o, --objectclass objectclass
209 Generate a ldif policy for LDAP with this objectClass.
210 -n, --name-prefix prefix
212 Generate a ldif policy for LDAP with this name prefix.
213 -h, --help
215 Show help.
216 watch [OPTIONS]
218 Watch the IPC interface events and print them to stdout.
219 Available options:
221 -w, --wait
223 Wait for IPC connection to become available.
224 -o, --once
226 Wait only when starting, if needed. Exit when the connection is
227 lost.
228 -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 -h, --help
234 Show help.
235 read-descriptor [OPTIONS] file
237 Read a USB descriptor from a file and print it in human-readable form.
238 Available options:
240 -h, --help
242 Show help.
243 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 Available options:
250 -u, --user
252 The specified name represents a username or UID (default).
253 -g, --group
255 The specified name represents a groupname or GID.
256 -p, --policy privileges
258 Policy related privileges.
259 -d, --devices privileges
261 Device related privileges.
262 -e, --exceptions privileges
264 Exceptions related privileges.
265 -P, --parameters privileges
267 Run-time parameter related privileges.
268 -h, --help
270 Show help.
271 Privileges:
273 The privileges are expected to be in the form of a list separated by a
275 colon:
276 $ sudo usbguard add-user joe --devices=listen,modify
278 Consult the usbguard-daemon.conf(5) man-page for a detailed list of
280 available privileges in each section.
281 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 Available options:
288 -u, --user
290 The specified name represents a username or UID (default).
291 -g, --group
293 The specified name represents a groupname or GID.
294 -h, --help
296 Show help.
297
299 Generating an initial policy:
300 Allow device(s):
302
304 usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)
305 07/23/2021 USBGUARD(1)