docs/auplugin.3 - master - githubmirror/audit-userspace

docs/auplugin.3
101 строка3 KB
Steve Grubb
Document how to use signals in conjunction with auplugin
29 июн 2025, 02:00
29 июн 2025, 02:00a37f69c
.TH "AUPLUGIN" "3" "June 2025" "Red Hat" "Linux Audit API"
.SH NAME
auplugin_init, auplugin_stop, auplugin_event_loop, auplugin_event_feed \- plugin event processing helpers
.SH SYNOPSIS
.B #include <auplugin.h>
.sp
.BI "int auplugin_init(int " inbound_fd ", unsigned " queue_size ", int " q_flags ", const char *" path ");"
.br
.B void auplugin_stop(void);
.br
.BI "void auplugin_event_loop(auplugin_callback_ptr " callback ");"
.br
.BI "int auplugin_event_feed(auparse_callback_ptr " callback ", unsigned " timer_interval ", auplugin_timer_callback_ptr " timer_cb ");"
.SH DESCRIPTION
.B auplugin_init
initializes the plugin framework. The
.I inbound_fd
parameter specifies the file descriptor that will provide audit
messages, typically standard input. The
.I queue_size
argument controls the maximum number of events that may be queued for
processing. The
.I q_flags
parameter selects in-memory or file-backed storage using the
.B AUPLUGIN_Q_*
constants defined in
.BR auplugin.h .
If
.I q_flags
includes
.B AUPLUGIN_Q_IN_FILE,
.I path
specifies the backing file. Any events already present in the file are queued
on startup so plugins resume processing previously unhandled records.
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.
.PP
.B auplugin_stop
signals the framework to terminate. It is normally called from a
SIGTERM handler or other shutdown logic.
.PP
.B auplugin_event_loop
starts a worker thread to deliver queued events to the supplied
.I callback
function one record at a time. The function blocks in the caller until
.B auplugin_stop
is invoked.
.PP
.B auplugin_event_feed
behaves like
.BR auplugin_event_loop ,
except that queued events are fed to libauparse. The provided
.I callback
must match the
.B auparse_callback_ptr
type. The
.I timer_interval
argument specifies how many seconds the worker thread will wait for new
records. A value of 0 disables the timer logic. When the interval elapses,
.B auparse_feed_age_events
is called to flush aged events. If
.I timer_cb
is not
.B NULL,
it is invoked with the interval before the flush. Passing a
.I timer_cb
of
.B NULL
keeps the default behaviour of calling
.B auparse_feed_age_events
only. The function returns 0 on success or \-1 if
libauparse could not be initialized.
.PP
Plugins can query queue statistics with
.BR auplugin_queue_depth ,
.BR auplugin_queue_max_depth ,
and
.BR auplugin_queue_overflow .
Register a callback with
.BR auplugin_register_stats_callback ,
and invoke it using
.BR auplugin_report_stats .
.SH SIGNAL HANDLING
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.
.PP
Example:
.nf
static volatile sig_atomic_t reload;
static void handler(int sig)
{
    if (sig == SIGTERM)
        auplugin_stop();
    else if (sig == SIGHUP)
        reload = 1;
}
.fi
.PP
.SH SEE ALSO
.BR auplugin_fgets (3),
.BR auparse_feed (3)
.SH AUTHOR
Steve Grubb