examples/lib/live: a lib example for live capture

Simple libpcap example for live capture. Allows listening on multiple
interfaces.

Author: jasonish

Makefile.am

@@ -14,7 +14,10 @@ EXTRA_DIST = ChangeLog COPYING LICENSE suricata.yaml.in \
 	     examples/plugins
 SUBDIRS = rust src plugins qa rules doc etc python ebpf \
           $(SURICATA_UPDATE_DIR)
-DIST_SUBDIRS = $(SUBDIRS) examples/lib/simple examples/lib/custom
+DIST_SUBDIRS = $(SUBDIRS) \
+		examples/lib/simple \
+		examples/lib/custom \
+		examples/lib/live
 
 CLEANFILES = stamp-h[0-9]*
 

configure.ac

@@ -2574,6 +2574,7 @@ AC_CONFIG_FILES(examples/plugins/c-custom-loggers/Makefile)
 AC_CONFIG_FILES(examples/plugins/ci-capture/Makefile)
 AC_CONFIG_FILES(examples/lib/simple/Makefile examples/lib/simple/Makefile.example)
 AC_CONFIG_FILES(examples/lib/custom/Makefile examples/lib/custom/Makefile.example)
+AC_CONFIG_FILES(examples/lib/live/Makefile examples/lib/live/Makefile.example)
 AC_CONFIG_FILES(examples/lib/cplusplus/Makefile.example)
 AC_CONFIG_FILES(plugins/Makefile)
 AC_CONFIG_FILES(plugins/pfring/Makefile)

examples/lib/live/.gitignore

@@ -0,0 +1,3 @@
+!/Makefile.example.in
+Makefile.example
+/custom

examples/lib/live/Makefile.am

@@ -0,0 +1,9 @@
+bin_PROGRAMS = live
+
+live_SOURCES = main.c
+
+AM_CPPFLAGS = -I$(top_srcdir)/src
+
+live_LDFLAGS = $(all_libraries) $(SECLDFLAGS)
+live_LDADD = "-Wl,--start-group,$(top_builddir)/src/libsuricata_c.a,../../$(RUST_SURICATA_LIB),--end-group" $(RUST_LDADD)
+live_DEPENDENCIES = $(top_builddir)/src/libsuricata_c.a ../../$(RUST_SURICATA_LIB)

examples/lib/live/Makefile.example.in

@@ -0,0 +1,16 @@
+LIBSURICATA_CONFIG ?=	@CONFIGURE_PREFIX@/bin/libsuricata-config
+
+SURICATA_LIBS =		`$(LIBSURICATA_CONFIG) --libs --static`
+SURICATA_CFLAGS :=	`$(LIBSURICATA_CONFIG) --cflags`
+
+# Currently the Suricata logging system requires this to be even for
+# plugins.
+CPPFLAGS +=    "-D__SCFILENAME__=\"$(*F)\""
+
+all: live
+
+live: main.c
+	$(CC) -o $@ $^ $(CPPFLAGS) $(CFLAGS) $(SURICATA_CFLAGS) $(SURICATA_LIBS)
+
+clean:
+	rm -f live

examples/lib/live/README.md

@@ -0,0 +1,73 @@
+# Live Capture Library Example
+
+This is an example of using the Suricata library to capture live
+traffic from a network interface with custom packet handling and
+threading.
+
+## Building In Tree
+
+The Suricata build system has created a Makefile that should allow you
+to build this application in-tree on most supported platforms. To
+build simply run:
+
+```
+make
+```
+
+## Running
+
+```
+./live -i eth0 -l .
+```
+
+This example requires at least one `-i` option to specify the network
+interface to capture from. You can specify multiple interfaces to
+capture from multiple sources simultaneously - a separate worker thread
+will be created for each interface:
+
+```
+./live -i eth0 -i eth1 -l .
+```
+
+Any additional arguments are passed directly to Suricata as command
+line arguments.
+
+**Note:** Live packet capture typically requires root privileges or
+appropriate capabilities (e.g., CAP_NET_RAW on Linux).
+
+Example with common options:
+```
+sudo ./live -i eth0 -- -l . -S rules.rules
+```
+
+Example capturing from multiple interfaces:
+```
+sudo ./live -i eth0 -i wlan0 -- -i eth1 -l . -S rules.rules
+```
+
+The example supports up to 16 interfaces simultaneously.
+
+## Building Out of Tree
+
+A Makefile.example has also been generated to use as an example on how
+to build against the library in a standalone application.
+
+First build and install the Suricata library including:
+
+```
+make install-library
+make install-headers
+```
+
+Then run:
+
+```
+make -f Makefile.example
+```
+
+If you installed to a non-standard location, you need to ensure that
+`libsuricata-config` is in your path, for example:
+
+```
+PATH=/opt/suricata/bin:$PATH make -f Makefile.example
+```