FAPOLICYD.STATE(5)

NAME
fapolicyd.state - fapolicyd runtime state report file

DESCRIPTION
The /run/fapolicyd/fapolicyd.state file contains the most recent daemon state report requested through fapolicyd-cli --check-status or periodic interval reporting.

The state report answers whether the daemon is healthy and configured as expected. Runtime counters, rule hit counts, cache effectiveness metrics, attribute lookup tables, and queue/defer activity are reported in /run/fapolicyd/fapolicyd.metrics. Each field is printed as a name: value line. Section headers end in a colon. Worker-specific health and queue drill-down fields are indented by two spaces under the related section.

STATE REPORT

  Operating mode

Permissive
    Whether the daemon is running in permissive mode. In permissive mode, policy denials are reported as denied decisions, but the response sent to the kernel allows access.

Integrity
    The configured file integrity mode used for trust checks.

reset_strategy
    The active metrics reset strategy: never keeps metrics growing for the daemon lifetime, auto resets timer-generated metrics reports, and manual allows privileged signal-generated reset requests such as fapolicyd-cli --reset-metrics.

Config generation
    The immutable decision configuration generation currently published by the daemon. Each successful reload publishes a new generation for decision-used fields such as permissive mode and integrity mode, so one decision does not mix values from different reloads.

Ruleset generation
    The current in-memory ruleset generation. This value increments each time a fully validated ruleset is published by the daemon.

Trust database generation
    The currently published trust database generation used by new decision reads. This is a daemon-runtime generation that starts at 1 during startup. The effective-since timestamp is the time the generation was published.

LMDB environment generation
    The physical LMDB environment generation currently opened by the daemon. This starts at 1 during startup and increments when fapolicyd publishes a rebuilt LMDB environment during controlled compaction. A trust database generation is a logical content epoch inside an environment; an LMDB environment generation is the storage epoch containing the LMDB page map, free list, and high-water state.

Trust database entries
    The number of records in the currently published trust database generation.

Timing collection mode
    The configured timing collection control mode.

Timing collection armed
    Whether a manual timing run is currently active.

Timing collection last start time
    The wall-clock time of the last successful timing start request, or never when timing has not been started.

Timing collection last stop time
    The wall-clock time of the last successful timing stop request, or never when timing has not been stopped.

  Headline activity

Allowed accesses
    The number of policy decisions that allowed access.

Denied accesses
    The number of policy decisions that denied access. In permissive mode these decisions are still counted as denials even though the daemon permits kernel access.

  Resource configuration

Daemon PID
    The process ID of the daemon process that wrote the report.

CPU cores
    The number of online processor cores reported by the system.

decision_threads
    The configured decision worker count from fapolicyd.conf.

Per worker q_size
    The configured size of each decision worker's internal event queue.

Per worker Subject defer array size
    The number of preallocated entries available in each decision worker's subject-slot defer array.

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 currently opened by the daemon, including any automatic resize applied for reload headroom.

Trust database max readers
    The configured LMDB reader-slot limit. This is sized for decision_threads plus maintenance readers.

  Resource utilization

Trust database pages in use
    The number and percentage of LMDB pages currently used by the active trust database contents. 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 can be higher than the active trust database footprint after drop/rebuild reloads, because LMDB cannot reuse pages until transactions and freelist metadata allow it. 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
    The number of old trust generations waiting for readers to drain before their named databases can be reclaimed.

Oldest retired trust database generation age
    The age in seconds of the oldest retired trust generation still waiting for safe reclamation.

Max trust database generation reclaim delay
    The longest observed delay in seconds between retiring an old trust generation and reclaiming its named database.

Trust database resize recommended
    Whether the current LMDB sizing state suggests increasing a manually configured db_max_size . This field is printed only when db_max_size is a numeric value. It is omitted when db_max_size is set to auto because auto mode grows the map itself before rebuilds.

Trust database resize reason
    Short explanation for the manual resize recommendation.

Trust database resize target
    The recommended minimum db_max_size in MiB. This field is printed only when manual resize is recommended.

Trust database compaction recommended
    Whether the current LMDB sizing state suggests running controlled trust database compaction. Compaction is 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. If retired generations are pinned, the recommendation is no because readers must drain before the environment can be safely replaced.

Trust database compaction target
    The current map-size target in MiB for a compact rebuilt environment. This field is 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. This field is printed only 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. This field is printed only 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. This field is printed only when mallinfo2(3) support is available.

  Health indicators
Any non-zero counter in this section warrants investigation.

Kernel queue overflow
    The number of FAN_Q_OVERFLOW events reported by the kernel. A non-zero value means kernel fanotify events were lost before the daemon could process them.

Filesystem errors
    The number of FAN_FS_ERROR events reported by the kernel. These are filesystem health events, not policy decisions.

Filesystem error last status
    Parser status for the most recent FAN_FS_ERROR event: 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.

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 suppressed behind the most recent error notification.

Reply errors
    The number of failed or short writes when sending fanotify permission responses back to the kernel.

Decision worker N health
    Compact health line for one decision worker. It includes a derived state, heartbeat age, and current event age. The state is idle, busy, or stalled. An idle worker reports current_event=idle. Queue depth and oldest queued event age are reported by the per-worker queue entries that follow.

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 observed for that worker since the last metrics reset.

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. The value is formatted with a human-readable unit such as ms or s.

Subject defer fallbacks
    The number of times the defer array was full and fapolicyd fell back to the historical subject cache eviction behavior.

Early subject cache evictions
    The number of subject cache entries evicted before process startup state was complete.

Subject BUILDING tracer evictions
    The number of BUILDING subject cache entries evicted because the owning process was traced and could hold the slot indefinitely.

Subject BUILDING stale evictions
    The number of BUILDING subject cache entries evicted because their startup state stayed incomplete past the bounded stale window.

Subject defer oldest age
    The age of the oldest currently deferred subject event, formatted with a human-readable unit such as ms or s.

Failure action queue_full (observe)
    Number of times the internal userspace event queue was full.

Failure action kernel_queue_overflow (observe)
    Number of kernel fanotify queue overflow events.

Failure action worker_stall (terminate)
    Number of decision worker stall detections.

Failure action rule_reload_failure (observe)
    Number of rule reload failures. A failed transactional reload preserves the previous published policy when one exists.

Failure action trust_reload_failure (observe)
    Number of trust database reload failures.

Failure action response_write_failure (observe)
    Number of failed or incomplete fanotify response writes to the kernel.

Failure action fanotify_filesystem_error (observe)
    Number of FAN_FS_ERROR filesystem health events reported by the kernel.

  Watched mounts

watching mount
    One line is printed for each mount point currently marked for fanotify monitoring.

NOTES
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 intentionally appear in both state and metrics reports. In the state report they provide health and activity context; in the metrics report they describe the current report context and counter window.

Metrics resets affect counters in the metrics report. Static configuration, current utilization snapshots, watched mounts, and health indicators are not reset by fapolicyd-cli --reset-metrics.

FILES

/run/fapolicyd/fapolicyd.state
    Runtime state report file.

/run/fapolicyd/fapolicyd.metrics
    Runtime metrics report file.

/run/fapolicyd/fapolicyd.timing
    Manual decision timing report 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.

SEE ALSO
fapolicyd(8), fapolicyd-cli(8), fapolicyd.conf(5), fapolicyd.metrics(5), fapolicyd.rules(5), fapolicyd.timing(5), and fapolicyd.trust(5).