fapolicyd-cli - Man Page

fapolicyd-cli [options]

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.

The CLI checks command privilege requirements before accessing protected files or contacting the daemon. The following commands require root because they modify administrator-owned trust files or use daemon controls restricted to a privileged signal sender: --file, --check-status, --check-metrics, --reset-metrics, --timing-start, and --timing-stop.

Commands that read the installed configuration, rules, or trust database, and commands that use the daemon update FIFO, accept either root or a caller in the group that owns /etc/fapolicyd. These include --check-config, --check-path, --check-trustdb, --check-watch_fs, --check-ignore_mounts, --list, --dump-db, --delete-db, --update, --reload-rules, --compact-trustdb, and --test-filter. Checking the active rules with --check-rules has the same requirement. An unprivileged caller may still check an explicitly named readable rules file, classify a readable file with --ftype, or display help.

-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 , Config generation , Ruleset generation , Trust database generation , and LMDB environment generation headers so the counter window, active decision configuration generation, active policy generation, trust content generation, and physical LMDB storage 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.

--compact-trustdb

Request 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 on failure. 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.

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

--check-rules [path]

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

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

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.

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

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

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.

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.

-T, --ftype-ext /path/to/file

Writes two NUL-terminated fields to standard output: the supplied path followed by the fapolicyd MIME type. Each invocation writes one path/MIME pair. This binary output is intended for scripts; use --ftype for interactive, MIME-only output.

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

A pathname component may contain every byte except NUL and slash, including spaces, tabs, newlines, quotes, backslashes, glob characters, leading hyphens, colons, and terminal control sequences. NUL field framing prevents those bytes from creating additional output records, but does not make them safe for shell evaluation or terminal display. 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 discovering paths. The Bash %q conversion in the example renders values safely for a terminal.

-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 or directory that matched a risk category, the category names, and the detected MIME type when available.

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.

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

Zoltan Fridrich

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