usbguard in Debian
==================

1. Policy generation
--------------------

On first installation (or if /etc/usbguard/rules.conf has been deleted),
usbguard will ask to run:

  # usbguard generate-policy

to generate a rule set (policy) in /etc/usbguard/rules.conf which authorizes the
currently connected USB devices.


2. Disaster recovery / unbricking
---------------------------------

In extremely rare cases, generating the policy doesn't detect required input
devices such as keyboards, which will disable them until stopping usbguard.

In cases where no input is possible anymore, the system can be powered off
and any one of the following boot parameters can be used to make usbguard not be
started:

  > usbguard=0
  > usbguard=false


3. Factory reset
----------------

If you want to completely remove all allow/block listed usb devices and start
with a fresh, empty config, the following steps need to be done:

  1) Remove manually added rules, if any
     # rm -f /etc/usbguard/IPCAccessControl.d/*
     # rm -f /etc/usbguard/rules.d/*

  2) Remove generated and permanent rules, if any
     # rm -f /etc/usbguard/rules.conf

  3) Rerun maintainer scripts
     # dpkg-reconfigure -plow usbguard


4. GNOME integration
--------------------

GNOME can make use of usbguard when being enable with:

  # gsettings set org.gnome.desktop.privacy usb-protection true

There are two protection levels available, 'lockscreen' (blocks new USB devices
in lockscreen only) and 'always' (always blocks new USB devices):

  # gsettings set org.gnome.desktop.privacy usb-protection-level lockscreen

  # gsettings set org.gnome.desktop.privacy usb-protection-level always


5. Managing devices
-------------------

All devices with the current active rules can be listed with:

  # usbguard list-devices

Devices can be unblocked with:

  # usbguard allow-device ${id}

where '${id}' is the id listed at the beginning of the line of the
'list-devices' command output.

Devices can be blocked with:

  # usbguard block-device ${id}

Devices can be permanently by allowed or blocked (i.e. written to rules.conf
and thus allowed/blocked at the start of the system) with the '-p' option
to the 'block-device' or 'allow-device' command.

Permanet rules can be listed with:

  # usbguard list-rules


6. IPC interface
----------------

usbguard provides a public IPC interface.

By default, /etc/usbguard/usbguard-daemon.conf allow the 'plugdev' group access
to the IPC interface.

 -- Daniel Baumann <daniel@debian.org>  Sun, 27 Sep 2026 02:13:31 +0200