Documentation improvement: clarify exit status bitmask behavior #230

Problem

The current documentation in aide.1 for exit status codes from aide --check mentions that codes 1, 2, and 4 can be combined, but doesn't explicitly state that these are bitmask values or provide examples of all possible combinations.

Many engineers run AIDE via systemd (using aide-check.service and aide-check.timer), and they see exit status codes in systemctl status aide-check.service. When they see exit codes like 3, 5, 6, or 7, they often get concerned because the man page only shows an example for exit code 3.

Example scenario:
$ systemctl status aide-check.service
● aide-check.service - AIDE Integrity Check
Active: failed (Result: exit-code)
Process: 1234 ExitCode=5/n/a

Users see exit code 5 but the man page only mentions codes 1, 2, 4, and gives one example (3). This creates confusion about whether something unexpected happened.

Proposed Solution

I have prepared a patch that improves the exit status documentation by:

1. Explicitly stating that exit codes 1, 2, and 4 are bitmask values
2. Adding examples of all possible combinations:
   • 3 = 1 + 2 (new + removed files)
   • 5 = 1 + 4 (new + changed files)
   • 6 = 2 + 4 (removed + changed files)
   • 7 = 1 + 2 + 4 (new + removed + changed files)
3. Clarifying that exit status 0 means no differences were detected

Current Documentation (lines 119-126)

.IP "1 * (new files reported?) +"
.IP "2 * (removed files reported?) +"
.IP "4 * (changed files reported?)"
.PP
Since those three cases can occur together, the respective error codes
are added. For example, if there are new files and removed files reported,
the exit status will be 1 + 2 = 3.

Proposed Documentation

.IP "1 * (new files reported?) +"
.IP "2 * (removed files reported?) +"
.IP "4 * (changed files reported?) "
.PP
The exit codes 1, 2, and 4 are bitmask values that can be combined.
Since those three cases can occur together, the exit status is the
sum of the applicable values:
.IP "3 = 1 + 2 (new files and removed files reported)"
.IP "5 = 1 + 4 (new files and changed files reported)"
.IP "6 = 2 + 4 (removed files and changed files reported)"
.IP "7 = 1 + 2 + 4 (new, removed, and changed files reported)"
.PP
An exit status of 0 in these modes indicates that no differences were
detected between the file system and the database.

Status

I have the patch ready (also updates ChangeLog) and have pushed it to a branch in my fork:

• Branch: https://github.com/abetkike/aide/tree/doc-exit-status-bitmask
• Commit: abetkike@8d66f46

However, I noticed that pull request creation is restricted to collaborators. What is the preferred method for contributing this patch?

1. Should I send it to the AIDE mailing list ([email protected])?
2. Can I attach the patch file to this issue?
3. Is there another preferred contribution workflow?

This change was identified while working on RHEL packaging, where users frequently encounter these exit codes in systemd service status outputs.

Benefits

• Reduces confusion for users monitoring AIDE via systemd
• Complete reference of all possible exit codes in one place
• Better troubleshooting - users can quickly understand what triggered the exit code
• No functional changes - documentation only