User Guide
This guide walks through installing MMT-DPI, running the included example binaries against a packet capture, and writing a small program that uses the library to extract attributes from live or recorded traffic.
For deeper dives into specific subsystems, see:
- ARCHITECTURE.md — layered overview of the code base.
- DEVELOPMENT.md — building from source, debug builds, static analysis, adding new protocols.
- DEPLOYMENT.md — install paths, packaging, runtime configuration.
1. Install
Take the install command for your platform from the Quick Start — on the
landing page, or in the
root README
on GitHub. Both show the one shared block, docs/_includes/quick-start.md
(Linux only): the verified package bootstrap for the Debian, Ubuntu and
Enterprise Linux releases it covers, then the source installer for every
supported Linux.
The source installer (install.sh):
- Detects your distribution and installs the default-profile build set
(compiler,
make,git) plus libpcap for the example programs1 — not libxml2, which onlyENABLESEC=1needs. - Clones the pinned release tag into a temporary directory and verifies it (commit pin, plus the tag signature when present).2
- Runs
make ARCH=linux MMT_BASE=/opt/mmt -jN. - Installs to
/opt/mmt/dpi/(override withMMT_BASE=/custom/pathor--prefix /custom/path), elevating withsudoonly when the prefix is not writable by the current user.3 - Registers the libraries with the dynamic loader
(
/etc/ld.so.conf.d/mmt-dpi.conf+ldconfig) whenever the install ran as root — elevated or invoked by root — whatever the prefix, and then prints noLD_LIBRARY_PATHadvice; a user-local prefix skips it.LDCONF=0opts out. Its--uninstalloption removes the install (add--prefixfor a custom prefix): the Quick Start’s uninstall line.
Manual build, from any directory (the block clones into ./mmt-dpi and
stays at the root of that checkout), once the packages of the
prerequisites
are installed:
git clone https://github.com/Montimage/mmt-dpi.git
cd mmt-dpi
make -C sdk -j$(nproc)
sudo make -C sdk install
After installation (default MMT_BASE=/opt/mmt), the layout is:4
/opt/mmt/
├── dpi/
│ ├── include/ # Public C headers (mmt_core.h, ...)
│ └── lib/ # Shared libraries (libmmt_core.so, libmmt_tcpip.so, ...)
├── plugins/ # Protocol plugin .so files loaded at runtime
└── examples/ # Example sources (copied by make install)
If a build, install, compile or run step fails, the Troubleshooting page lists each first-run error with its fix.
2. First run: extract attributes from a pcap
The extract_all example iterates over a pcap and prints every attribute
the configured protocol stack can extract. From the root of a checkout (the
manual build above leaves you there):
cd src/examples
gcc -o extract_all extract_all.c \
-I /opt/mmt/dpi/include \
-L /opt/mmt/dpi/lib \
-lmmt_core -ldl -lpcap
./extract_all -t google-fr.pcap
A sample pcap (google-fr.pcap) is shipped under src/examples/ for
quick smoke testing.
No checkout at hand? A complete first program,
hello_packet.c, and the synthetic,
redistributable capture it runs on, traffic.pcap,
are published with the documentation site; the README’s Basic Packet
Processing section and the site’s landing page give the exact steps to
fetch, compile and run them from an empty directory, and the output to
expect.
Other ready-to-build examples in the same directory:
| File | Purpose |
|---|---|
extract_all.c |
Dump every extractable attribute per packet. |
packet_handler.c |
Register a per-packet callback. |
attribute_handler_session_counter.c |
Per-attribute callback that counts sessions. |
proto_attributes_iterator.c |
Walk the registered protocol/attribute tree. |
simple_traffic_reporting.c |
Lightweight traffic statistics. |
MAC_extraction.c |
Pull link-layer addresses. |
mmt_export_info.c |
Dump exported protocol/attribute metadata. |
3. Minimum embedding pattern
The library has two levels of state, and the lifecycle follows them:
global state (the protocol registry and the loaded plugins), created once
per process, and per-handler state (sessions, registered attributes and
callbacks, statistics), one mmt_handler_t per packet stream. The order is:
- Initialise the global state once with
init_extraction(), before any handler exists, and check its return value — it returnsfalseon failure.5 It builds the protocol registry, loads the plugins and creates the map that tracks live handlers;6 nothing else in the API works before it. If it fails, do not call anything else, includingclose_extraction(). - Create a handler with
mmt_init_handler()and check it forNULL— on failure it fills theerrbufyou pass in (at leastMMT_ERRBUF_SIZEbytes).7 Each new handler is recorded in the global handler map.8 - Register the attributes you care about with
register_extraction_attribute()(by protocol id and attribute id) orregister_extraction_attribute_by_name(), and optionally packet-, attribute- or session-level callbacks. Each returnsfalseon failure. - Feed packets in with
packet_process();9 it returnsfalsewhen a packet could not be processed, and later packets can still be fed. - Release every handler with
mmt_close_handler(): it expires the handler’s sessions, frees everything the handler owns and removes it from the global handler map.10 - Tear down the global state last, once, with
close_extraction().11 It force-closes any handler still registered12 and then unloads the plugins,13 so a handler pointer is dangling afterwards: never callmmt_close_handler()orpacket_process()on it onceclose_extraction()has run.
On an error part-way through, release only what was acquired, in reverse
order: a failed mmt_init_handler() is followed by close_extraction()
alone; a failure after the handler exists closes the handler and then the
global state.
Worker ownership. Handlers are not shared: each worker thread owns its
own mmt_handler_t and feeds packets only to it. init_extraction() and
all protocol/plugin registration run on one thread before any worker starts;
handlers may then be created on the main thread or inside the workers.
Shutdown stops every worker first, closes each worker’s handler with
mmt_close_handler(), then calls close_extraction() once on a single
thread. The full contract, the locks behind it and the ThreadSanitizer
harness that checks it are in THREADING.md.
src/examples/packet_handler.c is the runnable reference for this order:
it checks init_extraction() before creating its handler, unwinds each
failure path, processes a pcap and closes the handler before the global
state.14 Against an install prefix (/opt/mmt or your MMT_BASE,
the same for the build and the install — see the
Deployment Guide):
gcc -o packet_handler "$MMT_BASE/examples/packet_handler.c" \
-I "$MMT_BASE/dpi/include" -L "$MMT_BASE/dpi/lib" -lmmt_core -ldl -lpcap
curl -fsSL -O https://montimage.github.io/mmt-dpi/first-run/traffic.pcap
LD_LIBRARY_PATH="$MMT_BASE/dpi/lib" ./packet_handler traffic.pcap
Any Ethernet pcap works; the curl line fetches the published
traffic.pcap into the current directory, so the
commands run from any directory — a checkout’s src/examples/google-fr.pcap
works too when passed by its full path.
init_extraction() loads the protocol plugins only from
$MMT_BASE/plugins, the directory compiled into the SDK, or from the
absolute directory named by the MMT_DPI_PLUGINS_DIR environment
variable;15 the working directory is never scanned. A plugin
that fails to load or initialise makes init_extraction() return
false,16 and so does a relative or unreadable
MMT_DPI_PLUGINS_DIR.
src/examples/extract_all.c is the most complete attribute-extraction
reference.
4. Where to look next
- Conceptual reference for the public API:
docs/MMT-Handler.md,docs/MMT-Packet.md,docs/MMT-Session.md,docs/MMT-Attributes.md. - Adding a new protocol parser:
docs/Add-New-Protocol.md. - Per-protocol design notes:
docs/HTTP-protocol.md,docs/DNS-protocol.md,docs/FTP-Protocol.md,docs/TCP-protocol.md, etc. - Auto-extracted public symbol list:
docs/Exported-Symbols.md. - Performance / runtime tuning:
docs/Deployment-Consideration.md.
If you hit something this guide doesn’t answer, open an issue using the bug report template or start a discussion on the repo.
-
The package sets per distribution:
install.sh:356-423; what each list must hold is recorded intools/ci/build-deps.txt. ↩ -
Release-tag verification: issue #197. ↩
-
Privilege elevation only for an unwritable prefix: issue #211. ↩
-
The prefix and its directories:
rules/common.mk:3-8;make installcopies the example sources atsdk/Makefile:110-113. ↩ -
src/mmt_core/src/packet_registry.c:626. ↩ -
src/mmt_core/src/packet_registry.c:668-669,src/mmt_core/src/packet_registry_handler.c:414. ↩ -
src/mmt_core/src/packet_registry_handler.c:116. ↩ -
src/mmt_core/src/packet_registry_handler.c:269. ↩ -
src/mmt_core/src/packet_pipeline.c:1592. ↩ -
src/mmt_core/src/packet_registry_handler.c:302,src/mmt_core/src/packet_registry_handler.c:352. ↩ -
src/mmt_core/src/packet_registry.c:677. ↩ -
src/mmt_core/src/packet_registry.c:680,src/mmt_core/src/packet_registry_handler.c:420. ↩ -
src/mmt_core/src/packet_registry.c:688. ↩ -
init_extraction()atsrc/examples/packet_handler.c:63, the handler atsrc/examples/packet_handler.c:69, the pcap loop atsrc/examples/packet_handler.c:100,mmt_close_handler()atsrc/examples/packet_handler.c:108andclose_extraction()atsrc/examples/packet_handler.c:111. Thedocs_lifecycletest suite compiles and runs this example against a throwaway install. ↩ -
src/mmt_core/src/plugins_engine.c:50-53. ↩ -
src/mmt_core/src/plugins_engine.c:94-96. ↩