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

-h, --help
    Prints a list of command line options.

--check-config
    Opens fapolicyd.conf and parses it to see if there are any syntax errors in the file.

--check-path
    Check the PATH environmental variable against the trustdb to look for file not in the trustdb which could cause problems at run time.

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

--check-metrics
    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-trustdb
    Check the trustdb against the files on disk to look for mismatches that will cause problems at run time.

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

--check-ignore_mounts[=mount-point]
    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.

--check-rules [path]
    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.

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

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

--timing-start, --timer-start
    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.

--timing-stop, --timer-stop
    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.

-y, --yes
    Do not prompt before --reset-metrics sends a reset request.

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

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

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

    update
        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 '/'.

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

--trust-file trust-file-name
    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.

--test-filter /path/to/file
    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.

-t, --ftype /path/to/file
    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.

-l, --list
    Prints a listing of the fapolicyd rules file with a rule number to aid in troubleshooting or understanding of the debug messages.

-u, --update
    Notifies fapolicyd to perform an update of the trust database.

-r, --reload-rules
    Notifies fapolicyd to perform a reload of the rules.

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