Scroll to navigation

FAPOLICYD-CLI(8) System Administration Utilities FAPOLICYD-CLI(8)

NAME

fapolicyd-cli - Fapolicyd CLI Tool

SYNOPSIS

fapolicyd-cli [options]

DESCRIPTION

The fapolicyd command line utility performs maintenance and troubleshooting tasks for fapolicyd. It can ask the daemon to reload state, inspect the trust database, validate configuration, test filter decisions, and manage administrator-defined trust entries. Normally the daemon learns about package changes through integration such as the dnf plugin, but manual package installation or direct edits to trust files still require explicit administrator action.

OPTIONS

Prints a list of command line options.
Opens fapolicyd.conf and parses it to see if there are any syntax errors in the file.
Check the PATH environmental variable against the trustdb to look for file not in the trustdb which could cause problems at run time.
Dump the daemon's health and configuration state. This report is for checking whether the daemon is healthy and configured as expected. It includes operating mode, startup-sized resources, current resource utilization, headline allow and deny activity, health indicators, and watched mounts. Runtime counters, attribute lookup tables, cache effectiveness metrics, and rule hit counts are reported by --check-metrics. See fapolicyd.state(5) for the state report fields. This command requests a plain state report and does not ask the daemon to reset runtime metric counters.
Dump the daemon's runtime metrics report from /run/fapolicyd/fapolicyd.metrics. The report starts with Last metrics reset and Ruleset generation headers so the counter window and active policy generation are explicit. It then prints decision outcome counters, subject and object cache effectiveness, rule hit counts, subject and object attribute lookup tables, and queue and defer activity. See fapolicyd.metrics(5) for the metrics report fields.
Check the trustdb against the files on disk to look for mismatches that will cause problems at run time.
Check the mounted file systems against the watch_fs daemon config entry to determine if any file systems need to be added to the configuration.
Inspect the ignore_mounts list or the provided mount point for potentially executable content. The command verifies that each mount exists, confirms the presence of the noexec option, and scans the directory tree for files matching the %languages macro. Any matches are reported and a summary per mount is displayed. A non-zero status is returned when suspicious files are found so automated workflows can gate changes.
Parse the rules file and validate its syntax without loading it into the daemon. If path is omitted, the command checks the active rules file, using /etc/fapolicyd/fapolicyd.rules when present and /etc/fapolicyd/compiled.rules otherwise. A zero exit status means the file is valid.
When used with --check-rules, also emit policy-shape warnings for executable or programmatic content that can reach the default-allow path. The option may be placed before or after --check-rules. A warning causes a non-zero exit status.
Request the metrics to be reset. Runtime metric counters reset after a metrics report is written when the daemon is configured with reset_strategy=manual. Rule hit counters normally reset when a new ruleset generation is loaded, but this command also clears them after reporting so the current rules can be tested from a fresh counter window. The report contains the counter values being reset. A successful reset also updates the Last metrics reset timestamp shown by later metrics reports. If metrics have never been reset since daemon start, the header says never. The CLI checks the on-disk fapolicyd.conf before requesting the metrics to be reset. If the on-disk reset_strategy is not manual, or the setting cannot be verified, the command tells the user and sends a plain --check-metrics request instead. The daemon's active in-memory setting may differ from the file until configuration is reloaded. The command asks for confirmation before sending the reset request unless -y or --yes is used.
Request a manual decision timing run. The daemon honors the request only when the active configuration has timing_collection=manual and the signal sender is privileged. Starting resets the fixed per-worker timing aggregates and starts collecting timing for subsequent fanotify decisions.
Stop a manual decision timing run and ask the daemon to write /run/fapolicyd/fapolicyd.timing. The command waits for that report and writes it to stdout. If timing is not armed, the report says so instead of printing timing data. See fapolicyd.timing(5) for the report fields, including the TL;DR summary printed before the detailed latency sections. The daemon honors the request only when the active configuration has timing_collection=manual and the signal sender is privileged.
Do not prompt before --reset-metrics sends a reset request.
Deletes the trust database. Normally this never needs to be done. But if for some reason the trust database becomes corrupted, then the only method of recovery is to run this command.
Dumps the trust db contents for inspection. This will print the original trust source, path, file size, and recorded hash of the file as known by the trust source the entry came from. The rpm backend may provide SHA256 or SHA512 digests depending on how the package was built.
Manage the file trust database.
This command adds the file given by path to the trust database. It gets the size and calculates the required hash (SHA256 by default). If the path is a directory, it will walk the directory tree to the bottom and add every regular file that it finds. By default, the path is appended to the end of the fapolicyd.trust file.
This command deletes all entries that match from the trust database. It will try to match multiple entries so that entire directories can be deleted in one command. To ensure that you only match a directory and not a partial name, be sure to end with '/'.
This command updates the size and hash of any matching paths in the file trust database. If no path is given, then all files are updated. If an argument is passed, then only matching paths get updated. If the intent is to match against a directory, ensure that it ends with '/'.
When used with add or update, evaluate the selected files and directories through the filter configuration (fapolicyd-filter.conf). Paths excluded by the filter are skipped so only allowed entries are added or refreshed.
Use after file option. Makes every command of file option operate on a single trust file named trust-file-name that is located inside trust.d directory. If a trust file with such a name does not exist inside trust.d directory, it is created.
Evaluate the filter configuration against the given path and emit a rule-by-rule trace ending with "decision include" or "decision exclude". Use this to confirm whether a file would be eligible for inclusion in the trust database.
Prints the mime type of the file given. A full path must be specified. This command is intended to help get the ftype parameter of rules correct by seeing how fapolicyd will classify it. Fapolicyd may differ from the file command.
Prints a listing of the fapolicyd rules file with a rule number to aid in troubleshooting or understanding of the debug messages.
Notifies fapolicyd to perform an update of the trust database.
Notifies fapolicyd to perform a reload of the rules.
Enable additional output for commands that support it. At present this affects --check-ignore_mounts by printing each file that does not pass inspection.

RETURN CODES

The following exit status values are used for error reporting and scripting:

0 Success
Normal completion.
1 Generic/unspecified failure
Fallback for errors that do not map to a more specific category.
2 CLI/usage error
Incorrect options or argument counts.
3 Path/configuration error
Failed realpath lookups, malformed configuration, or invalid mount overrides.
4 Database/LMDB error
Trust database operations failed (creation, open, cursor traversal, or deletion).
5 Rule/filter error
Filter initialization or parsing problems, including %languages handling.
6 Daemon/IPC error
Communication with the daemon failed (FIFO permissions/shape issues, missing PID, or status report timeouts).
7 Filesystem/I-O/permission error
Problems opening, stat'ing, or writing files (including rule files or the trust database on disk).
8 Internal software/OOM
Allocation failures or other unexpected internal errors.
9 No-op/Not-found/Nothing to do
Operations that completed without making changes, such as attempting to update, delete, or add entries that were not present.

SEE ALSO

fapolicyd(8), fapolicyd.rules(5), fapolicyd.state(5), fapolicyd.metrics(5), fapolicyd.timing(5), fapolicyd.trust(5), and fapolicyd.conf(5)

AUTHOR

Zoltan Fridrich

March 2026 Red Hat