USBGUARD(1)

💖 usbguard(1) — the USBGuard command-line interface, bestie edition 💖

okay so. welcome to usbguard(1), the manual page for the USBGuard CLI. yes it's a section 1 page, yes it's iconic, yes we're going to get through it together. grab a snack. 🍓

---

✨ NAME ✨

usbguard — USBGuard command-line interface. that's it. that's the name. she's simple, she's powerful, she's the moment. 💅

---

🌸 SYNOPSIS 🌸

usbguard [OPTIONS] <subcommand> [SUBCOMMAND-OPTIONS] ...

usbguard get-parameter name

usbguard set-parameter name value

usbguard list-devices

usbguard allow-device id | rule | partial-rule

usbguard block-device id | rule | partial-rule

usbguard reject-device id | rule | partial-rule

usbguard list-rules

usbguard append-rule rule

usbguard remove-rule id

usbguard generate-policy

usbguard watch

usbguard read-descriptor file

usbguard add-user name

usbguard remove-user name

---

🦋 DESCRIPTION 🦋

the usbguard command gives you a command-line interface (CLI) to a running usbguard-daemon(8) instance. slay. 💖

she also comes with a bonus tool: generating your very first USBGuard policies based on the USB devices that are actually plugged into the system right now. so like, she's a communicator and a matchmaker. versatility, honestly. 👑

---

🎀 SUBCOMMANDS 🎀

---

💜 get-parameter [OPTIONS] name

get the value of a runtime parameter. name has to be one of InsertedDevicePolicy and ImplicitPolicyTarget. no vibes-based parameter names, sorry bestie, it's a closed set.

available options:

• -h, --help — show help. 🫶

---

💜 set-parameter [OPTIONS] name value

set the value of a runtime parameter. again, name is one of InsertedDevicePolicy and ImplicitPolicyTarget. changing things. powerful. 💅

available options:

• -v, --verbose — print the previous and the new attribute value. receipts, basically. 🧾
• -h, --help — show help. 🫶

---

💜 list-devices [OPTIONS]

list all the USB devices the USBGuard daemon recognizes. the whole roster. ✨

available options:

• -a, --allowed — list allowed devices. the good ones. 💚
• -b, --blocked — list blocked devices. 🚫
• -t, --tree — list devices in a tree format. 🌳 aesthetics.
• -h, --help — show help. 🫶

---

💜 allow-device [OPTIONS] < id | rule | partial-rule >

authorize a device to interact with the system. 🫶 the device can be identified by a device id, a rule, or a partial-rule (which is a rule without a target). both rule and partial-rule can be used to allow multiple devices at once — bulk slay.

important bestie, do not skip this: id refers to the internal device-rule ID (the very first number in the list-devices command output), not the device's ID attribute. the way these two are different things trips people up constantly. 😭

available options:

• -p, --permanent — make the decision permanent. a device-specific allow rule gets appended to the current policy. 📌
• -h, --help — show help. 🫶

---

💜 block-device [OPTIONS] < id | rule | partial-rule >

deauthorize a device. ✋ the device can be identified by a device id, a rule, or a partial-rule (rule without target). both rule and partial-rule can block multiple devices at once. and yes, same warning as above: id is the internal device-rule ID (very first number in the list-devices output), not the device's ID attribute. 🫠

available options:

• -p, --permanent — make the decision permanent. a device-specific block rule gets appended to the current policy. 📌
• -h, --help — show help. 🫶

---

💜 reject-device [OPTIONS] < id | rule | partial-rule >

deauthorize and remove a device. she's not just blocked, she's evicted. 💀 same deal: identified by device id, rule, or partial-rule (rule without target), and both rule and partial-rule can reject multiple devices at once. and once more for the people in the back: id = internal device-rule ID (the very first number of the list-devices output), not the device's ID attribute. 👑

available options:

• -p, --permanent — make the decision permanent. a device-specific reject rule gets appended to the current policy. 📌
• -h, --help — show help. 🫶

---

💜 list-rules [OPTIONS]

list the rule set (policy) that the USBGuard daemon is using. the whole lore document. 📜

available options:

• -d, --show-devices — show all devices affected by the specific rule. 👀
• -l, --label label — only show rules having a specific label. 🏷️
• -h, --help — show help. 🫶

---

💜 append-rule [OPTIONS] rule

append the rule to the current rule set. adding to the collection, no cap. ➕

available options:

• -a, --after id — append the new rule after a rule with the specified rule id. line-skipping, respectfully. 🧚
• -t, --temporary — make the decision temporary. the rule policy file will not be updated. 🫥
• -h, --help — show help. 🫶

---

💜 remove-rule [OPTIONS] id

remove a rule identified by the rule id from the rule set. bye bestie. 👋

available options:

• -h, --help — show help. 🫶

---

💜 generate-policy [OPTIONS]

generate a rule set (policy) which authorizes the currently connected USB devices. basically: trust the devices that are here right now, put it in writing. ✍️

available options:

• -p, --with-ports — generate port-specific rules for all devices. by default, port-specific rules are only generated for devices which do not export an iSerial value. 🔌
• -P, --no-ports-sn — don't generate port-specific rules for devices without an iSerial value. without this option, the tool will add a via-port attribute to any device that doesn't provide a serial number. this is a security measure to limit devices that cannot be uniquely identified to connecting only via a specific port. this makes it harder to bypass the policy, since the real device will occupy the allowed USB port most of the time. 🛡️
• -d, --devpath devpath — only generate a rule for the device at the specified sub path of /sys. 📂
• -t, --target target — generate an explicit "catch all" rule with the specified target. the target can be one of the following values: allow, block, reject. 🎯
• -X, --no-hashes — don't generate a hash attribute for each device. 🚫
• -H, --hash-only — generate a hash-only policy. #️⃣
• -L, --ldif — generate a ldif policy for LDAP. 🗂️
• -b, --usbguardbase base — generate a ldif policy for LDAP with this base. this option is required when --ldif was specified. ⚠️
• -o, --objectclass objectclass — generate a ldif policy for LDAP with this objectClass. 🗂️
• -n, --name-prefix prefix — generate a ldif policy for LDAP with this name prefix. 🗂️
• -h, --help — show help. 🫶

---

💜 watch [OPTIONS]

watch the IPC interface events and print them to stdout. it's giving live commentary. 📺✨

available options:

• -w, --wait — wait for the IPC connection to become available. ⏳
• -o, --once — wait only when starting, if needed. exit when the connection is lost. 🚪
• -e, --exec path — run an executable file located at path for every event. pass event data to the process via environment variables. 🏃
• -h, --help — show help. 🫶

---

💜 read-descriptor [OPTIONS] file

read a USB descriptor from a file and print it in human-readable form. translating device-speak into something we can actually read. 🔍

available options:

• -h, --help — show help. 🫶

---

💜 add-user name [OPTIONS]

create an IPC access control file allowing the user/group identified by name to use the USBGuard IPC bus. the change takes effect only after restarting the usbguard-daemon(8) instance. so like, don't panic when nothing happens immediately. 🔄

available options:

• -u, --user — the specified name represents a username or UID (default). 👤
• -g, --group — the specified name represents a groupname or GID. 👥
• -p, --policy privileges — policy-related privileges. 📋
• -d, --devices privileges — device-related privileges. 🔌
• -e, --exceptions privileges — exceptions-related privileges. ⚠️
• -P, --parameters privileges — run-time parameter-related privileges. 🎛️
• -h, --help — show help. 🫶

🍓 Privileges

the privileges are expected to be in the form of a list separated by a colon:

$ sudo usbguard add-user joe --devices=listen,modify

consult the usbguard-daemon.conf(5) man-page for a detailed list of available privileges in each section. you can also use ALL instead of privileges to automatically assign all relevant privileges to a given section. yes, ALL is the "just give me everything" button. iconic. 👑

---

💜 remove-user name [OPTIONS]

remove an IPC access control file associated with the user/group identified by name. and again: the change takes effect only after restarting the usbguard-daemon(8) instance. 🔄

available options:

• -u, --user — the specified name represents a username or UID (default). 👤
• -g, --group — the specified name represents a groupname or GID. 👥
• -h, --help — show help. 🫶

---

🌈 EXAMPLES 🌈

generating an initial policy:

$ sudo usbguard generate-policy > rules.conf
$ vi rules.conf
(review/modify the rule set)
$ sudo install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
$ sudo systemctl restart usbguard

allow device(s):

# Allow a device by ID(it is the very first number from the list-devices command output)
$ sudo usbguard allow-device 10
# Allow all devices named "Dell Wired Multimedia Keyboard"
$ sudo usbguard allow-device name \"Dell Wired Multimedia Keyboard\"

---

⭐ SEE ALSO ⭐

usbguard-daemon(8), usbguard-daemon.conf(5), usbguard-rules.conf(5)

---

💀 BUGS 💀

if you find a bug in this software, or if you'd like to request a feature to be implemented, please file a ticket at https://github.com/USBGuard/usbguard/issues/new. they want to hear from you, fr fr. 🫶

---

👑 AUTHOR 👑

USBGuard was originally written by Daniel Kopeček. many people have contributed to it. it takes a village, and this village ate. 💅

---

🧚 RESOURCES 🧚

main web site: https://usbguard.github.io/

---

📜 COPYING 📜

license GPLv2+: GNU GPL version 2 or later http://gnu.org/licenses/gpl.html. this is free software: you are free to change and redistribute it. there is NO WARRANTY, to the extent permitted by law.

---

and that's the whole page, bestie!! 🌸 you read a manual page voluntarily, main character energy honestly. 🦋

this was USBGuard — the USBGUARD(1) manual, dated 04/15/2026. go forth and manage your USB devices responsibly. periodt. 💖✨🎀