1USBGUARD(1) USBGUARD(1)
2
6 usbguard - USBGuard command-line interface
7
9 usbguard OPTIONS command [COMMAND-OPTIONS] ...
10 usbguard list-devices
12 usbguard allow-device id
14 usbguard block-device id
16 usbguard reject-device id
18 usbguard list-rules
20 usbguard append-rule rule
22 usbguard remove-rule id
24 usbguard generate-policy
26 usbguard watch
28 usbguard read-descriptor file
30 usbguard add-user name
32 usbguard remove-user name
34
36 The usbguard command provides a command-line interface (CLI) to a
37 running usbguard-daemon(8) instance. It also provides a tool for
38 generating initial USBGuard policies based on USB devices connected to
39 the system.
40
42 list-devices
43 List all USB devices recognized by the USBGuard daemon.
44 Available options:
46 -a, --allowed
48 List allowed devices.
49 -b, --blocked
51 List blocked devices.
52 -h, --help
54 Show help.
55 allow-device [OPTIONS] id
57 Authorize a device identified by the device id to interact with the
58 system.
59 Available options:
61 -p, --permanent
63 Make the decision permanent. A device specific allow rule will be
64 appended to the current policy.
65 -h, --help
67 Show help.
68 block-device [OPTIONS] id
70 Deauthorize a device identified by the device id.
71 Available options:
73 -p, --permanent
75 Make the decision permanent. A device specific block rule will be
76 appended to the current policy.
77 -h, --help
79 Show help.
80 reject-device [OPTIONS] id
82 Deauthorize and remove a device identified by the device id.
83 Available options:
85 -p, --permanent
87 Make the decision permanent. A device specific reject rule will be
88 appended to the current policy.
89 -h, --help
91 Show help.
92 list-rules [OPTIONS]
94 List the rule set (policy) used by the USBGuard daemon.
95 Available options:
97 -d, --show-devices
99 Show all devices which are affected by the specific rule.
100 -h, --help
102 Show help.
103 append-rule [OPTIONS] rule
105 Append the rule to the current rule set.
106 Available options:
108 -a, --after id
110 Append the new rule after a rule with the specified rule id.
111 -h, --help
113 Show help.
114 remove-rule [OPTIONS] id
116 Remove a rule identified by the rule id from the rule set.
117 Available options:
119 -h, --help
121 Show help.
122 generate-policy [OPTIONS]
124 Generate a rule set (policy) which authorizes the currently connected
125 USB devices.
126 Available options:
128 -p, --with-ports
130 Generate port specific rules for all devices. By default, port
131 specific rules are generated only for devices which do not export
132 an iSerial value.
133 -P, --no-ports-sn
135 Don’t generate port specific rules for devices without an iSerial
136 value. Without this option, the tool will add a via-port attribute
137 to any device that doesn’t provide a serial number. This is a
138 security measure to limit devices that cannot be uniquely
139 identified to connect only via a specific port. This makes it
140 harder to bypass the policy since the real device will occupy the
141 allowed USB port most of the time.
142 -t, --target target
144 Generate an explicit "catch all" rule with the specified target.
145 The target can be one of the following values: allow, block, reject
146 -X, --no-hashes
148 Don’t generate a hash attribute for each device.
149 -H, --hash-only
151 Generate a hash-only policy.
152 -h, --help
154 Show help.
155 watch [OPTIONS]
157 Watch the IPC interface events and print them to stdout.
158 Available options:
160 -w, --wait
162 Wait for IPC connection to become available.
163 -o, --once
165 Wait only when starting, if needed. Exit when the connection is
166 lost.
167 -e, --exec path
169 Run an executable file located at path for every event. Pass event
170 data to the process via environment variables.
171 -h, --help
173 Show help.
174 read-descriptor [OPTIONS] file
176 Read a USB descriptor from a file and print it in human-readable form.
177 Available options:
179 -h, --help
181 Show help.
182 add-user name [OPTIONS]
184 Create an IPC access control file allowing the user/group identified by
185 name to use the USBGuard IPC bus. The change takes effect only after
186 restarting the usbguard-daemon(8) instance.
187 Available options:
189 -u, --user
191 The specified name represents a username or UID (default).
192 -g, --group
194 The specified name represents a groupname or GID.
195 -p, --policy privileges
197 Policy related privileges.
198 -d, --devices privileges
200 Device related privileges.
201 -e, --exceptions privileges
203 Exceptions related privileges.
204 -P, --parameters privileges
206 Run-time parameter related privileges.
207 -h, --help
209 Show help.
210 Privileges:
212 The privileges are expected to be in the form of a list separated by a
214 colon:
215 $ sudo usbguard add-user joe --devices=listen,modify
217 Consult the usbguard-daemon.conf(5) man-page for a detailed list of
219 available privileges in each section.
220 remove-user name [OPTIONS]
222 Remove an IPC access control file associated with the user/group
223 identified by name. The change takes effect only after restarting the
224 usbguard-daemon(8) instance.
225 Available options:
227 -u, --user
229 The specified name represents a username or UID (default).
230 -g, --group
232 The specified name represents a groupname or GID.
233 -h, --help
235 Show help.
236
238 Generating an initial policy:
239 $ sudo usbguard generate-policy > rules.conf
241 $ vi rules.conf
242 (review/modify the rule set)
243 $ sudo install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
244 $ sudo systemctl restart usbguard
245
247 usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)
248 Unresolved directive in usbguard.1.adoc - include::footer.adoc[]
250 2019-07-27 USBGUARD(1)