FAPOLICYD.STATE(5)

💖 NAME 💖

fapolicyd.state — the fapolicyd runtime state report file. That's the whole concept, bestie. (You're reading FAPOLICYD.STATE(5), in case the terminal dropped you here and you forgot how you got in 💅)

---

🌸 DESCRIPTION 🌸

okay so, picture this: /run/fapolicyd/fapolicyd.state is the file that holds the most recent daemon state report. Where does it come from? Either you asked for it with fapolicyd-cli --check-status, or it just ✨appeared✨ because periodic interval reporting did its thing. Both count. 🫶

And what is a state report, you ask? It's the answer to the eternal question: is my daemon healthy and configured the way I expected? 🩺 If you want the numbers-numbers — runtime counters, rule hit counts, cache effectiveness metrics, attribute lookup tables, and queue/defer activity — those live in /run/fapolicyd/fapolicyd.metrics, not here. Different file, different vibe.

Formatting tea, real quick, because it matters when you're grepping:

• Every field is printed as a name: value line. Every single one.
• Section headers end in a colon. That's how you spot 'em.
• Worker-specific health and queue drill-down fields get indented by two spaces, tucked under the section they belong to. Cute little nesting situation. 🪆

---

📊 STATE REPORT 📊

🧭 Operating mode

• Permissive — is the daemon running in permissive mode or not? And here's the plot twist you need to know: in permissive mode, policy denials still get reported as denied decisions, but the response that actually goes back to the kernel allows access. Denial in the report, yes in real life. 😭
• Integrity — the configured file integrity mode used for trust checks. Whatever you set, it shows up here.
• reset_strategy — which metrics reset strategy is active. The options are: never, which just lets metrics grow for the daemon's whole lifetime (no thoughts, head empty, forever); auto, which resets timer-generated metrics reports; and manual, which allows privileged signal-generated reset requests like the one from fapolicyd-cli --reset-metrics. 👑
• Config generation — the immutable decision configuration generation the daemon has currently published. Every successful reload publishes a fresh generation for decision-used fields like permissive mode and integrity mode, so that one decision never mixes values from different reloads. Consistency queen. ✨
• Ruleset generation — the current in-memory ruleset generation. This number increments every time the daemon publishes a fully validated ruleset. Fully validated, no shortcuts.
• Trust database generation — the trust database generation currently published, and the one new decision reads use. Heads up: this is a daemon-runtime generation that starts at 1 during startup. The effective-since timestamp is the moment the generation got published. 🕐
• LMDB environment generation — the physical LMDB environment generation currently opened by the daemon. Starts at 1 during startup and increments when fapolicyd publishes a rebuilt LMDB environment during controlled compaction. And yes, these are two different things, don't confuse them: a trust database generation is a logical content epoch inside an environment, while an LMDB environment generation is the storage epoch holding the LMDB page map, free list, and high-water state. Two layers, both real. 🧚
• Trust database entries — how many records are in the currently published trust database generation. Count 'em.
• Timing collection mode — the configured timing collection control mode.
• Timing collection armed — is a manual timing run active right now, or nah?
• Timing collection last start time — the wall-clock time of the last successful timing start request, or never if timing has never been started.
• Timing collection last stop time — the wall-clock time of the last successful timing stop request, or never if timing has never been stopped. ⏱️

🔥 Headline activity

• Allowed accesses — the number of policy decisions that allowed access. Slay. 💚
• Denied accesses — the number of policy decisions that denied access. And here's the reminder: in permissive mode these decisions are still counted as denials, even though the daemon lets the kernel have access anyway. The counter does not care about your feelings. 💀

🛠️ Resource configuration

• Daemon PID — the process ID of the daemon process that wrote this very report. It's signing its work. 🖊️
• CPU cores — the number of online processor cores the system reported.
• decision_threads — the configured decision worker count, straight from fapolicyd.conf.
• Per worker q_size — the configured size of each decision worker's internal event queue.
• Per worker Subject defer array size — how many preallocated entries each decision worker's subject-slot defer array has to work with.
• Per worker Subject cache size — the configured number of entries in each decision worker's subject cache.
• Per worker Object cache size — the configured number of entries in each decision worker's object cache.
• Trust database max pages — the current maximum LMDB map page count for the trust database environment. This reflects the map size the daemon has currently opened, including any automatic resize it applied for reload headroom. 🔍
• Trust database max readers — the configured LMDB reader-slot limit. It's sized for decision_threads plus maintenance readers, so everybody gets a seat. 🪑

📈 Resource utilization

• Trust database pages in use — the number and percentage of LMDB pages currently used by the active trust database contents. Important distinction, bestie: this is the active named-database footprint, not the LMDB environment high-water mark. 🙅
• Trust database allocated high-water pages — the number and percentage of LMDB map pages that have been allocated in the environment. This follows LMDB's file high-water mark, and it can be higher than the active trust database footprint after drop/rebuild reloads — because LMDB can't reuse pages until transactions and freelist metadata allow it. It's not being wasteful on purpose, it's just LMDB rules. 🌀 And when db_max_size is set to auto, fapolicyd uses this value as reload-headroom pressure, while active pages show the steady-state trust database size.
• Retired trust database generations — how many old trust generations are sitting around waiting for readers to drain before their named databases can be reclaimed. They're in the waiting room. 🛋️
• Oldest retired trust database generation age — the age in seconds of the oldest retired trust generation still waiting for a safe reclamation.
• Max trust database generation reclaim delay — the longest delay in seconds anyone has ever observed between retiring an old trust generation and reclaiming its named database. Personal record. 🏆
• Trust database resize recommended — does the current LMDB sizing state suggest bumping up a manually configured db_max_size? Heads up on the print rules: this field only shows up when db_max_size is a numeric value. It gets omitted when db_max_size is auto, because auto mode grows the map itself before rebuilds. It's got it handled. 💅
• Trust database resize reason — the short explanation for that manual resize recommendation.
• Trust database resize target — the recommended minimum db_max_size in MiB. Printed only when manual resize is actually recommended.
• Trust database compaction recommended — does the current LMDB sizing state suggest running controlled trust database compaction? Compaction gets recommended when the allocated LMDB high-water mark is much larger than the active trust database footprint and no retired trust generations are pinned.
• Trust database compaction reason — short explanation for the recommendation. And if retired generations are pinned, the recommendation is no, because readers must drain before the environment can be safely replaced. Safety first, always. 🦺
• Trust database compaction target — the current map-size target in MiB for a compact rebuilt environment. Printed when compaction is recommended.
• Subject slots in use — the number and percentage of subject cache slots currently occupied.
• Object slots in use — the number and percentage of object cache slots currently occupied.
• glibc arena (total memory) is — the current total glibc heap arena size in KiB, followed by the value from the previous report. Only printed when the daemon is built with mallinfo2(3) support.
• glibc uordblks (in use memory) is — the current allocated heap memory in KiB, followed by the value from the previous report. Only printed when mallinfo2(3) support is available.
• glibc fordblks (total free space) is — the current free heap memory in KiB, followed by the value from the previous report. Only printed when mallinfo2(3) support is available.

🚨 Health indicators

Any non-zero counter in this section warrants investigation. Like, genuinely. Go look. 👀

• Kernel queue overflow — the number of FAN_Q_OVERFLOW events the kernel reported. A non-zero value means kernel fanotify events were lost before the daemon could even process them. That's data that just vanished. 😭
• Filesystem errors — the number of FAN_FS_ERROR events reported by the kernel. Note the category: these are filesystem health events, not policy decisions. Different thing entirely.
• Filesystem error last status — parser status for the most recent FAN_FS_ERROR event. One of: none, ok, missing_error_record, or malformed.
• Filesystem error last seen — the wall-clock time of the most recent FAN_FS_ERROR event, or never when no filesystem error has been reported. (Hope it says never 🫶)
• Filesystem error last errno — the errno-style error code from the most recent parseable filesystem error event.
• Filesystem error last suppressed count — the kernel-reported count of additional filesystem errors that got suppressed behind the most recent error notification. Yeah, there were more. 🙈
• Reply errors — the number of failed or short writes when sending fanotify permission responses back to the kernel. The reply didn't land. That's bad.
• Decision worker N health — a compact health line for one decision worker. It packs in a derived state, heartbeat age, and current event age. The state is idle, busy, or stalled. An idle worker reports current_event=idle. And queue depth plus oldest queued event age? Those come from the per-worker queue entries that follow, not from this line. ✨
• Decision worker N current queue depth — the number of fanotify permission events currently waiting in that worker's queue.
• Decision worker N max queue depth — the highest queue depth that worker has hit since the last metrics reset. Its personal best, unfortunately. 📉
• Decision worker N queue full count — the number of failed enqueue attempts for that worker since the last metrics reset.
• Decision worker N oldest queued age — the age of the oldest event currently waiting in that worker's queue. Formatted with a human-readable unit like ms or s, so you don't have to do math. 💅
• Subject defer fallbacks — the number of times the defer array was full and fapolicyd fell back to the historical subject cache eviction behavior. Plan B got used.
• Early subject cache evictions — the number of subject cache entries evicted before process startup state was complete. Rude, but it happens.
• Subject BUILDING tracer evictions — how many BUILDING subject cache entries got evicted because the process that owned the slot was being traced and could've just… sat there holding it forever 💀 not on our watch.
• Subject BUILDING stale evictions — how many BUILDING subject cache entries got evicted because their startup state never finished in time, past the bounded stale window. bestie took too long getting ready, we left without her 🫶
• Subject defer oldest age — the age of the oldest subject event that's currently deferred, formatted with a human-readable unit like ms or s.
• Failure action queue_full (observe) — how many times the internal userspace event queue was full.
• Failure action kernel_queue_overflow (observe) — how many kernel fanotify queue overflow events happened.
• Failure action worker_stall (terminate) — how many decision worker stall detections happened.
• Failure action rule_reload_failure (observe) — how many rule reload failures happened. Heads up: a failed transactional reload preserves the previous published policy when one exists, so it's not the end of the world 💅
• Failure action trust_reload_failure (observe) — how many trust database reload failures happened.
• Failure action response_write_failure (observe) — how many fanotify response writes back to the kernel failed or came out incomplete.
• Failure action fanotify_filesystem_error (observe) — how many FAN_FS_ERROR filesystem health events the kernel reported. the kernel is basically sending you a "we need to talk" text 😭

👀 Watched mounts 👀

• watching mount — one line gets printed for every mount point that's currently marked for fanotify monitoring. one line per mount, no skimping ✨

---

📝 NOTES 📝

Okay so this next bit is important, don't scroll past it bestie 🙈

These ones, and I mean all of these: Allowed accesses, Denied accesses, Config generation, Ruleset generation, Trust database generation, LMDB environment generation, Trust database entries, Decision worker N health, Decision worker N current queue depth, Decision worker N max queue depth, Decision worker N queue full count, Decision worker N oldest queued age, Subject defer fallbacks, Early subject cache evictions, Subject BUILDING tracer evictions, and Subject BUILDING stale evictions — they intentionally show up in both the state report and the metrics report. no, it's not a copy-paste accident, it's a design choice and it ate 🔥

Why though? In the state report they're giving you health and activity context. In the metrics report they're describing the current report context and the counter window. same names, different job, main character energy in both 💅

⚠️ And this part matters: metrics resets only affect the counters in the metrics report. Static configuration, current utilization snapshots, watched mounts, and health indicators are not reset by fapolicyd-cli --reset-metrics. so don't come for them, they're staying 🌸

---

📂 FILES 📂

• /run/fapolicyd/fapolicyd.state — the runtime state report file.
• /run/fapolicyd/fapolicyd.metrics — the runtime metrics report file.
• /run/fapolicyd/fapolicyd.timing — the manual decision timing report. it gets written when a privileged stop request ends an armed timing run, when a stop request finds timing unarmed, or when timing collection stops to avoid counter overflow. three very specific situations, and she shows up for all of them 🎀

---

🦋 SEE ALSO 🦋

fapolicyd(8), fapolicyd-cli(8), fapolicyd.conf(5), fapolicyd.metrics(5), fapolicyd.rules(5), fapolicyd.timing(5), and fapolicyd.trust(5). go read your sisters, they're all iconic 👑

---

and that's the whole page, bestie!! this one came from Red Hat, dated May 2026, and it lives at FAPOLICYD.STATE(5) — go forth and read your state report with confidence 💖✨