| 1 |
.TH "AUPLUGIN" "3" "June 2025" "Red Hat" "Linux Audit API" |
| 2 |
.SH NAME |
| 3 |
auplugin_init, auplugin_stop, auplugin_event_loop, auplugin_event_feed \- plugin event processing helpers |
| 4 |
.SH SYNOPSIS |
| 5 |
.B #include <auplugin.h> |
| 6 |
.sp |
| 7 |
.BI "int auplugin_init(int " inbound_fd ", unsigned " queue_size ", int " q_flags ", const char *" path ");" |
| 8 |
.br |
| 9 |
.B void auplugin_stop(void); |
| 10 |
.br |
| 11 |
.BI "void auplugin_event_loop(auplugin_callback_ptr " callback ");" |
| 12 |
.br |
| 13 |
.BI "int auplugin_event_feed(auparse_callback_ptr " callback ", unsigned " timer_interval ", auplugin_timer_callback_ptr " timer_cb ");" |
| 14 |
.SH DESCRIPTION |
| 15 |
.B auplugin_init |
| 16 |
initializes the plugin framework. The |
| 17 |
.I inbound_fd |
| 18 |
parameter specifies the file descriptor that will provide audit |
| 19 |
messages, typically standard input. The |
| 20 |
.I queue_size |
| 21 |
argument controls the maximum number of events that may be queued for |
| 22 |
processing. The |
| 23 |
.I q_flags |
| 24 |
parameter selects in-memory or file-backed storage using the |
| 25 |
.B AUPLUGIN_Q_* |
| 26 |
constants defined in |
| 27 |
.BR auplugin.h . |
| 28 |
If |
| 29 |
.I q_flags |
| 30 |
includes |
| 31 |
.B AUPLUGIN_Q_IN_FILE, |
| 32 |
.I path |
| 33 |
specifies the backing file. Any events already present in the file are queued |
| 34 |
on startup so plugins resume processing previously unhandled records. |
| 35 |
The library maintains global state for its queue and worker threads. Only one plugin instance is supported, so callers must not invoke auplugin_init() concurrently from multiple threads. The function returns 0 on success or \-1 if initialization fails. |
| 36 |
.PP |
| 37 |
.B auplugin_stop |
| 38 |
signals the framework to terminate. It is normally called from a |
| 39 |
SIGTERM handler or other shutdown logic. |
| 40 |
.PP |
| 41 |
.B auplugin_event_loop |
| 42 |
starts a worker thread to deliver queued events to the supplied |
| 43 |
.I callback |
| 44 |
function one record at a time. The function blocks in the caller until |
| 45 |
.B auplugin_stop |
| 46 |
is invoked. |
| 47 |
.PP |
| 48 |
.B auplugin_event_feed |
| 49 |
behaves like |
| 50 |
.BR auplugin_event_loop , |
| 51 |
except that queued events are fed to libauparse. The provided |
| 52 |
.I callback |
| 53 |
must match the |
| 54 |
.B auparse_callback_ptr |
| 55 |
type. The |
| 56 |
.I timer_interval |
| 57 |
argument specifies how many seconds the worker thread will wait for new |
| 58 |
records. A value of 0 disables the timer logic. When the interval elapses, |
| 59 |
.B auparse_feed_age_events |
| 60 |
is called to flush aged events. If |
| 61 |
.I timer_cb |
| 62 |
is not |
| 63 |
.B NULL, |
| 64 |
it is invoked with the interval before the flush. Passing a |
| 65 |
.I timer_cb |
| 66 |
of |
| 67 |
.B NULL |
| 68 |
keeps the default behaviour of calling |
| 69 |
.B auparse_feed_age_events |
| 70 |
only. The function returns 0 on success or \-1 if |
| 71 |
libauparse could not be initialized. |
| 72 |
.PP |
| 73 |
Plugins can query queue statistics with |
| 74 |
.BR auplugin_queue_depth , |
| 75 |
.BR auplugin_queue_max_depth , |
| 76 |
and |
| 77 |
.BR auplugin_queue_overflow . |
| 78 |
Register a callback with |
| 79 |
.BR auplugin_register_stats_callback , |
| 80 |
and invoke it using |
| 81 |
.BR auplugin_report_stats . |
| 82 |
.SH SIGNAL HANDLING |
| 83 |
Plugins should establish signal handlers with sigaction(2) before entering the event loop. The SIGTERM handler should call auplugin_stop() to shut down the worker thread. Handlers for other signals, such as SIGHUP or SIGUSR1, should set global flags that are processed in the event or timer callbacks. |
| 84 |
.PP |
| 85 |
Example: |
| 86 |
.nf |
| 87 |
static volatile sig_atomic_t reload; |
| 88 |
static void handler(int sig) |
| 89 |
{ |
| 90 |
if (sig == SIGTERM) |
| 91 |
auplugin_stop(); |
| 92 |
else if (sig == SIGHUP) |
| 93 |
reload = 1; |
| 94 |
} |
| 95 |
.fi |
| 96 |
.PP |
| 97 |
.SH SEE ALSO |
| 98 |
.BR auplugin_fgets (3), |
| 99 |
.BR auparse_feed (3) |
| 100 |
.SH AUTHOR |
| 101 |
Steve Grubb |