usbguard-daemon.conf(5)
=======================
:doctype: manpage


== NAME
usbguard-daemon.conf - USBGuard daemon configuration file


== DESCRIPTION
The *usbguard-daemon.conf* file is loaded by the USBGuard daemon after it parses its command-line options.
It is used to configure runtime parameters of the daemon.
The default search path is '/etc/usbguard/usbguard-daemon.conf'.
It may be overridden using the *-c* command-line option, see *usbguard-daemon*(8) for further details.


== 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. Using RuleFile and RuleFolder at the same time is
    permitted. However, modification of the permanent policy is not possible if
    one of the following conditions are met:
    ** Neither RuleFile nor RuleFolder are specified.
    ** RuleFile is not specified, RuleFolder is but it does not contain any files,
       where we could save permanent rules.

*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,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


== SECURITY CONSIDERATIONS

=== IPC
The daemon provides the USBGuard public IPC interface.
Depending on your distribution defaults, access to this interface is limited to a certain group or a specific user only.
Please set either the *IPCAllowedUsers*, *IPCAllowedGroups* or *IPCAccessControlFiles* options to limit access to the IPC interface.
*Do not leave the ACL unconfigured as that will expose the IPC interface to all local users and will allow them to manipulate the authorization state of USB devices and modify the USBGuard policy*.

=== RestoreControllerDeviceState configuration option
If set to true, the USB authorization policy could be bypassed by performing some sort of attack on the daemon (via a local exploit or via
a USB device) to make it shutdown and restore to the operating-system default state (known to be permissive).


[[ipc-access-control]]
== 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.

 ** listen: Listen to property parameter changes.

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
....


== SEE ALSO
link:usbguard-daemon.8.adoc#name[usbguard-daemon(8)],
link:usbguard-rules.conf.5.adoc#name[usbguard-rules.conf(5)]


include::footer.adoc[]
