Skip to the content.

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:

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):

  1. Detects your distribution and installs the default-profile build set (compiler, make, git) plus libpcap for the example programs1 — not libxml2, which only ENABLESEC=1 needs.
  2. Clones the pinned release tag into a temporary directory and verifies it (commit pin, plus the tag signature when present).2
  3. Runs make ARCH=linux MMT_BASE=/opt/mmt -jN.
  4. Installs to /opt/mmt/dpi/ (override with MMT_BASE=/custom/path or --prefix /custom/path), elevating with sudo only when the prefix is not writable by the current user.3
  5. 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 no LD_LIBRARY_PATH advice; a user-local prefix skips it. LDCONF=0 opts out. Its --uninstall option removes the install (add --prefix for 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:

  1. Initialise the global state once with init_extraction(), before any handler exists, and check its return value — it returns false on 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, including close_extraction().
  2. Create a handler with mmt_init_handler() and check it for NULL — on failure it fills the errbuf you pass in (at least MMT_ERRBUF_SIZE bytes).7 Each new handler is recorded in the global handler map.8
  3. Register the attributes you care about with register_extraction_attribute() (by protocol id and attribute id) or register_extraction_attribute_by_name(), and optionally packet-, attribute- or session-level callbacks. Each returns false on failure.
  4. Feed packets in with packet_process();9 it returns false when a packet could not be processed, and later packets can still be fed.
  5. 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
  6. 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 call mmt_close_handler() or packet_process() on it once close_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

If you hit something this guide doesn’t answer, open an issue using the bug report template or start a discussion on the repo.

  1. The package sets per distribution: install.sh:356-423; what each list must hold is recorded in tools/ci/build-deps.txt. ↩

  2. Release-tag verification: issue #197. ↩

  3. Privilege elevation only for an unwritable prefix: issue #211. ↩

  4. The prefix and its directories: rules/common.mk:3-8; make install copies the example sources at sdk/Makefile:110-113. ↩

  5. src/mmt_core/src/packet_registry.c:626. ↩

  6. src/mmt_core/src/packet_registry.c:668-669, src/mmt_core/src/packet_registry_handler.c:414. ↩

  7. src/mmt_core/src/packet_registry_handler.c:116. ↩

  8. src/mmt_core/src/packet_registry_handler.c:269. ↩

  9. src/mmt_core/src/packet_pipeline.c:1592. ↩

  10. src/mmt_core/src/packet_registry_handler.c:302, src/mmt_core/src/packet_registry_handler.c:352. ↩

  11. src/mmt_core/src/packet_registry.c:677. ↩

  12. src/mmt_core/src/packet_registry.c:680, src/mmt_core/src/packet_registry_handler.c:420. ↩

  13. src/mmt_core/src/packet_registry.c:688. ↩

  14. init_extraction() at src/examples/packet_handler.c:63, the handler at src/examples/packet_handler.c:69, the pcap loop at src/examples/packet_handler.c:100, mmt_close_handler() at src/examples/packet_handler.c:108 and close_extraction() at src/examples/packet_handler.c:111. The docs_lifecycle test suite compiles and runs this example against a throwaway install. ↩

  15. src/mmt_core/src/plugins_engine.c:50-53. ↩

  16. src/mmt_core/src/plugins_engine.c:94-96. ↩