OPTIONS¶
RuleFile=path
The USBGuard daemon will use this file to load the policy
rule set from it and to write new rules received via the IPC interface.
Default: %sysconfdir%/usbguard/rules.conf
RuleFolder=path
The USBGuard daemon will use this folder to load the
policy rule set from it and to write new rules received via the IPC interface.
Usually, we set the option to /etc/usbguard/rules.d/. The USBGuard daemon is
supposed to behave like any other standard Linux daemon therefore it loads
rule files in alpha-numeric order. File names inside RuleFolder directory
should start with a two-digit number prefix indicating the position, in which
the rules are scanned by the daemon.
ImplicitPolicyTarget=target
How to treat USB devices that don’t match any rule
in the policy. Target should be one of allow, block or reject (logically
remove the device node from the system). Default: block
PresentDevicePolicy=policy
How to treat USB devices that are already connected when
the daemon starts. Policy should be one of allow, block, reject, keep (keep
whatever state the device is currently in) or apply-policy (evaluate the rule
set for every present device). Default: apply-policy
PresentControllerPolicy=policy
How to treat USB controller devices that are
already connected when the daemon starts. One of allow, block, reject, keep or
apply-policy. Default: keep
InsertedDevicePolicy=policy
How to treat USB devices that are already connected
after the daemon starts. One of block, reject, apply-policy. Default:
apply-policy
AuthorizedDefault=authorizedDefault
The USBGuard daemon modifies some of the default
authorization state attributes of controller devices. This setting, enables
you to define what value the default authorization is set to. Authorized
default should be one of keep (do not change authorization state), none (every
new device starts out deauthorized), all (every new device starts out
authorized) or internal (internal devices start out authorized, external do
not). Default: none
RestoreControllerDeviceState=boolean
The USBGuard daemon modifies some attributes of
controller devices like the default authorization state of new child device
instances. Using this setting, you can control whether the daemon will try to
restore the attribute values to the state before modification on shutdown.
Default: false
DeviceManagerBackend=backend
Which device manager backend implementation to use.
Backend should be one of uevent (default) or umockdev (useful for testing).
UEvent backend is a netlink based implementation which uses sysfs to scan for
present devices and an uevent socket for receiving USB device related events.
UMockDev based device manager is capable of simulating devices based on
umockdev-record files. Default: uevent
IPCAllowedUsers=username [username ...]
A space delimited list of usernames that the daemon will
accept IPC connections from. Default: root
IPCAllowedGroups=groupname [groupname ...]
A space delimited list of groupnames that the daemon will
accept IPC connections from.
IPCAccessControlFiles=path
The files at this location will be interpreted by the
daemon as IPC access control definition files. See the IPC ACCESS CONTROL
section for more details.
DeviceRulesWithPort=boolean
Generate device specific rules including the
"via-port" attribute. Default: false
AuditBackend=backend
USBGuard audit events log backend. The backend
value should be one of FileAudit or LinuxAudit. Default: FileAudit
AuditFilePath=filepath
USBGuard audit events log file path. Required if
AuditBackend is set to FileAudit. Default:
%localstatedir%/log/usbguard/usbguard-audit.log
HidePII=boolean
Hides personally identifiable information such as device
serial numbers and hashes of descriptors (which include the serial number)
from audit entries. Default: false
IPC ACCESS CONTROL¶
Access to the USBGuard IPC interface can be limited per user or
group. Furthermore, by using the IPC Access Control files, it is possible to
limit the access down to the level of Sections and Privileges as explained
below.
Recommended: IPCAccessControlFiles¶
When you set IPCAccessControlFiles option, the daemon will
look for IPC access control files in the directory specified by the set
value. Each file in the directory is processed as follows:
1.The basename of the file is interpreted as a username,
UID, groupname or GID. If the name starts with : (colon), it is assumed that
the rest of the name represents a group identifier (groupname or GID in case
of a numeric-only string). Otherwise, it is interpreted as a user identifier
(username or UID in case of numeric-only string).
2.The contents of the file are parsed as
Section=[privilege1][,privilege2] ... formatted lines which specify the
section privileges. If a section is omitted, it is assumed that no privileges
are given for that section.
Available sections and privileges:
•
Devices
•modify: Change authorization state of devices
including permanent changes (i.e. modification of device specific rules in the
policy).
•list: Ability to get a list of recognized devices
and their attributes.
•listen: Listen to device presence and device
policy changes.
•
Policy
•modify: Append rules to or remove any rules from
the policy.
•list: Ability to view the currently enforced
policy.
•
Exceptions
•listen: Receive exception messages.
•
Parameters
•modify: Set values of run-time parameters.
•list: Get values of run-time parameters.
The following is a generally usable and reasonably safe example of
an access control file. It allows one to modify USB device authorization
state (Devices=modify), list USB devices (Devices=list), listen to USB
device related events (Devices=listen), list USB authorization policy rules
(Policy=list) and listen to exception events (Exceptions=listen):
Devices=modify,list,listen
Policy=list
Exceptions=listen
You can create or remove the IPC access control files using
usbguard add-user and usbguard remove-user CLI commands. See usbguard(1) for
more details. If you want to create the IPC access control files manually,
you need to set the files permissions to 0600.
Legacy: IPCAllowedUsers and IPCAllowedGroups¶
Example configuration allowing full IPC access to users
root, joe and members of the group wheel:
IPCAllowedUsers=root joe
IPCAllowedGroups=wheel
