FAPOLICYD-CLI(8)

💖 NAME 💖

fapolicyd-cli — the Fapolicyd CLI Tool, bestie. Your little remote control for the big scary daemon. 🎀

---

✨ SYNOPSIS ✨

fapolicyd-cli [options]

---

🌸 DESCRIPTION 🌸

Okay so fapolicyd has a command line utility and it is genuinely your bestie for maintenance and troubleshooting. It does the whole vibe check: it can ask the daemon to reload state, go peek inside the trust database, validate your configuration, test filter decisions, and manage the trust entries that admins define themselves. 👑

Normally the daemon finds out about package changes on its own through integration, like the dnf plugin — she's got connections, she hears things. 💅 But if you install packages manually, or you go editing the trust files with your own two hands? Yeah, then an administrator has to take explicit action. No autopilot for that one, fr fr.

---

🔐 PRIVILEGES 🔐

The CLI does a vibe check on privilege requirements before it touches any protected files or goes knocking on the daemon's door. Respect the boundaries, bestie. 🫶

So listen — these commands need root, periodt, because they either modify administrator-owned trust files or use daemon controls that are locked to a privileged signal sender:

• --file
• --check-status
• --check-metrics
• --reset-metrics
• --timing-start
• --timing-stop

Then there's the second group, the ✨chill✨ ones — commands that read the installed configuration, rules, or trust database, and commands that use the daemon update FIFO. Those accept root or a caller in the group that owns /etc/fapolicyd:

• --check-config
• --check-path
• --check-trustdb
• --check-watch_fs
• --check-ignore_mounts
• --list
• --dump-db
• --delete-db
• --update
• --reload-rules
• --compact-trustdb
• --test-filter

Checking the active rules with --check-rules has that exact same requirement, okay? Same energy.

And for the unprivileged girlies — you're still not locked out entirely! 💖 An unprivileged caller can still check an explicitly named readable rules file, classify a readable file with --ftype, or just display help. We love accessible help text in this house. 🌈

---

💅 OPTIONS 💅

• -h, --help — prints a list of the command line options. That's it, that's the whole job, and honestly? Iconic.
• --check-config — opens fapolicyd.conf and parses it to see if there are any syntax errors lurking in the file. Typos hate to see her coming. 🔍
• --check-path — checks the PATH environmental variable against the trustdb, hunting for files that are not in the trustdb and could cause problems at run time. She's just being proactive, bestie. 💅
• --check-status — dumps the daemon's health and configuration state. This report is for checking whether the daemon is healthy and configured the way you expected — like a full checkup but make it terminal. 🩺 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 instead. See fapolicyd.state(5) for the state report fields. And heads up: this command requests a plain state report — it does not ask the daemon to reset runtime metric counters. No sneaky resets here. 🙈
• --check-metrics — dumps the daemon's runtime metrics report from /run/fapolicyd/fapolicyd.metrics. The report starts with the headers Last metrics reset , Config generation , Ruleset generation , Trust database generation , and LMDB environment generation so that the counter window, active decision configuration generation, active policy generation, trust content generation, and physical LMDB storage generation are all explicit. Then it 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. Numbers girlies rise. 📊
• --check-trustdb — checks the trustdb against the files actually on disk, looking for mismatches that will cause problems at run time. It's giving detective energy. 🔎
• --compact-trustdb — requests controlled trust database LMDB compaction. The daemon refreshes backend snapshots, builds a replacement LMDB environment in a temporary directory, validates it, then briefly blocks new trust database readers, closes the live environment, and swaps in the replacement. The previous environment is kept, or restored if something fails. This command is intended for administrator maintenance when fapolicyd-cli --check-status reports that trust database compaction is recommended. Ordinary trust database updates should use --update. Glow-up for your database, no cap. ✨
• --check-watch_fs — checks the mounted file systems against the watch_fs daemon config entry to figure out if any file systems need to be added to the configuration.
• --check-ignore_mounts[=mount-point] — inspects the ignore_mounts list, or the mount point you hand her, 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 risk categories that fapolicyd cannot see on an ignored mount. The summary reports counts for executable regular files, ELF/shared objects, archives/JARs/ZIPs, bytecode caches, plugin/runtime directories, and files matching the %languages macro. A non-zero status is returned when risky entries are found, so automated workflows can gate changes. She's thorough and I respect it. 💅
• --check-rules [path] — parses the rules file with the daemon policy parser 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. If both installed rules files exist, the command reports a path configuration error — unless --lint is also used. A zero exit status means the file is valid. 🎉 Values with the explicit glob: prefix are accepted only for exe and path, and the pattern after the prefix must be an absolute path. This command reports violations of those requirements, including patterns supplied through named sets. It does not expand valid patterns or simulate which concrete paths they match. Read carefully, bestie, she's not doing that for you.
• --lint — when used with --check-rules, also emits 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. ⚠️

Examples:

fapolicyd-cli --check-rules --lint
fapolicyd-cli --check-rules /tmp/proposed.rules --lint

Warnings include rule numbers and file-line locations where a specific rule is involved. For example:

Policy lint warning: executable events can fall through; no terminal broad execute deny found after rule 12 at /etc/fapolicyd/compiled.rules:13
Policy lint hint: add a final "deny_audit perm=execute all : all" rule
Policy lint warning: broad open allow rule 17 at /etc/fapolicyd/compiled.rules:18 appears before programmatic-content deny rule 18 at /etc/fapolicyd/compiled.rules:19

When both /etc/fapolicyd/fapolicyd.rules and /etc/fapolicyd/compiled.rules exist, linting warns that the old rules file shadows compiled.rules and recommends removing or migrating the old file. Old file said "I'm the main character" and she is not. 😭

• --reset-metrics — requests 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. Consent first, always. 🫶

• --timing-start, --timer-start — requests 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. Let's get those receipts. ⏱️
• --timing-stop, --timer-stop — stops a manual decision timing run and asks the daemon to write /run/fapolicyd/fapolicyd.timing. The command waits for that report and writes it to stdout. If a timing report already exists, the command asks before replacing it. 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.
• -y, --yes — do not prompt before --reset-metrics sends a reset request. Auto-yes, no small talk. 💅
• -d, --delete-db — 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. Last-resort queen. 💀
• -D, --dump-db — 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.
• -f, --file add|delete|update [path] — manage the file trust database. 🗂️

The path is a command-line argument, not a rule-file value. Use the shell's quoting to pass a path containing a space, for example:

fapolicyd-cli --file add /tmp/first last/
fapolicyd-cli --file delete /tmp/first last/

The CLI receives the unquoted path. A literal %20 in a command-line path is not decoded to a space. Do not try it, she will not fall for it. 😭

• add — 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.

• delete — ok so this one 💅 yeets every entry that matches straight out of the trust database. It's smart about it too — it'll try to match multiple entries at once, so you can nuke whole directories in a single command, no cap. And here's the tea bestie: if you wanna make sure you're matching a directory and not just some random partial name that happens to start the same way, end your path with /. Trust. 🙏
• update — refreshes the size and hash of any matching paths in the file trust database. No path given? Then literally everything gets updated, periodt. Pass an argument and only the matching paths get touched. And same rule as above, queen: if you're tryna match against a directory, make sure it ends with /. ✨
• --filter — when you use this with add or update, it runs the selected files and directories through the filter configuration (fapolicyd-filter.conf). Anything the filter excludes just gets skipped, so only the allowed entries get added or refreshed. It's giving "vibe check before you come in" 🚪✨

---

• --trust-file trust-file-name — use this after the file option, bestie. It makes every command of the file option operate on one single trust file named trust-file-name that lives inside the trust.d directory. If a trust file with that name doesn't exist in trust.d yet, don't worry — it gets created. Manifesting your own file 🎀
• --test-filter /path/to/file — evaluates the filter configuration against the path you give it and spits out a rule-by-rule trace, ending with either "decision include" or "decision exclude". Use this when you need to confirm whether a file would even be eligible for inclusion in the trust database. It's the "am I on the list??" check 🔍💖
• -t, --ftype /path/to/file — prints the mime type of the file you hand it. You must give a full path, no shortcuts. This command exists to help you get the ftype parameter of your rules correct by seeing how fapolicyd will actually classify that file. Heads up though: fapolicyd may differ from the file command. They don't always agree, iykyk 😭
• -T, --ftype-ext /path/to/file — writes two NUL-terminated fields to standard output: the supplied path, followed by the fapolicyd MIME type. Every invocation writes exactly one path/MIME pair. This binary output is made for scripts — if you want interactive, MIME-only output, use --ftype instead. 🫶

The following Bash example reads one or more path/MIME pairs safely:

for file in "$@"; do
        fapolicyd-cli --ftype-ext="$file"
done |
while IFS= read -r -d '' path &&
      IFS= read -r -d '' mime
do
        printf 'path=%q mime=%q\n' "$path" "$mime"
done

⚠️ okay so this next part is the important part, bestie, do not skip it. A pathname component may contain every byte except NUL and slash — and that includes spaces, tabs, newlines, quotes, backslashes, glob characters, leading hyphens, colons, and terminal control sequences. 😳 The NUL field framing stops those bytes from creating extra output records, but it does not make them safe for shell evaluation or terminal display. So: do not use command substitution, unquoted expansions, eval, or newline-delimited file lists for these values. Use quoted variables when passing paths to commands, and use find -print0 with the same NUL-aware read pattern when you're discovering paths. The Bash %q conversion in the example renders values safely for a terminal. Stay safe out here 🫶💅

• -l, --list — prints a listing of the fapolicyd rules file with a rule number attached, so you can actually make sense of troubleshooting and those debug messages. Numbered receipts, iconic 👑
• -u, --update — notifies fapolicyd to perform an update of the trust database. Sliding into its DMs to say "refresh pls" 📬
• -r, --reload-rules — notifies fapolicyd to perform a reload of the rules. Same energy, different chore. 🔄
• --verbose — enables additional output for the commands that support it. At present this affects --check-ignore_mounts, printing each file or directory that matched a risk category, the category names, and the detected MIME type when it's available. More tea, more detail 🍵✨

---

🌈 RETURN CODES 🌈

These exit status values are what get used for error reporting and scripting. Learn them, love them, they're your friends fr fr 💖

• 0 Success — normal completion. The good ending. ✨
• 1 Generic/unspecified failure — the fallback for errors that don't map to a more specific category. It's giving "idk man" 😭
• 2 CLI/usage error — incorrect options or argument counts. Bestie, check your flags 💀
• 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). The database said no 🚫
• 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). Nobody picked up the phone 📞😭
• 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. We ran out of room, queen 💀
• 9 No-op/Not-found/Nothing to do — operations that completed without making changes, like trying to update, delete, or add entries that weren't even there. Respectfully, there was nothing to do 🙈

---

🌸 SEE ALSO 🌸

Go read your sisters, bestie, they're all slaying:

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

---

👑 AUTHOR 👑

Zoltan Fridrich — the icon, the legend, the moment. 🫶

---

And that's the whole page, bestie!! This one came from Red Hat, it's the March 2026 edition, and the manual itself is FAPOLICYD-CLI(8) — go forth and trust-database responsibly, mwah 💅✨🎀🦋