Run ModemManager Safely and Capture Useful Diagnostics

You will check the installed ModemManager daemon, understand which options are safe to use during diagnosis, and capture logs without accidentally launching a second system service. Allow about 15 minutes for a basic check, or longer if you need to reproduce a modem-probing problem.

This guide uses the installed ModemManager(8) manual and binary. The machine used for these examples has ModemManager 1.23.4, packaged as 1.23.4-0ubuntu2. Options and diagnostic output can differ on another release, so check the local manual before copying an option into a service unit.

1. Confirm the binary and version

Start with read-only checks. ModemManager is a D-Bus system daemon, not an interactive modem client. The normal way to inspect or control modems is a client such as mmcli; launching the daemon directly is mainly useful for controlled diagnostics.

$ command -v ModemManager
/usr/sbin/ModemManager
$ ModemManager --version
ModemManager 1.23.4
Copyright (C) 2008-2023 The ModemManager authors
License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl-2.0.html>
$ man ModemManager

The copyright and licence lines are normal version output. The useful checkpoint is the version number. If command -v finds nothing, stop here and repair the package installation rather than guessing a path.

2. Read the options your installation actually exposes

The manual page is the primary reference for this guide. Check the executable's help as well, because a package can update the binary and manual page at different times.

$ ModemManager --help
Usage:
  ModemManager [OPTION?]

DBus system service to control mobile broadband modems.

Logging options:
  --log-level=[LEVEL]                  Log level: one of ERR, WARN, MSG, INFO, DEBUG
  --log-file=[PATH]                    Path to log file
  --log-journal                        Log to systemd journal
  --log-timestamps                     Show timestamps
  --log-relative-timestamps            Use relative timestamps (from MM start)

Application Options:
  --filter-policy=[POLICY]             Filter policy: one of ALLOWLIST-ONLY, STRICT
  --no-auto-scan                       Don't auto-scan looking for devices
  --initial-kernel-events=[PATH]       Path to initial kernel events file
  --debug                              Run with extended debugging capabilities

Your output may contain additional options. That is a version-specific detail, not a reason to mix options from a newer manual into an older deployment. For this guide, use only options confirmed by both your installed help and the local manual.

3. Choose a diagnostic output destination

The default logging level is informational, warning and error messages. The manual names four accepted levels: ERR, WARN, INFO and DEBUG. Use the least noisy level that can answer the question you have.

For a temporary foreground investigation, --debug runs without daemonising and sends log output to the controlling terminal as well as syslog. This is a service-level operation. Do not run it while the packaged system service is already active, because two daemons can compete for the same D-Bus name and modem ports.

A typical diagnostic invocation is:

$ sudo ModemManager --debug --log-level=DEBUG --log-timestamps

Use elevated privileges only when your installation requires them. The command remains in the foreground until you stop it with Ctrl-C. Stop it before restarting the normal service. The command changes no persistent configuration, but it can disrupt modem access while it is running.

If terminal output is too easy to lose, direct logs to a file instead:

$ sudo ModemManager --debug --log-level=DEBUG --log-file=/tmp/modemmanager-debug.log --log-timestamps
$ sudo tail -f /tmp/modemmanager-debug.log

Do not put a modem user's credentials, SIM PIN or other personal data into a log path that is broadly readable. Keep a temporary log private and remove it after collecting the needed evidence:

$ sudo chmod 600 /tmp/modemmanager-debug.log
$ sudo rm -- /tmp/modemmanager-debug.log

The final command is irreversible. Only remove the file after you have checked that it is no longer needed.

4. Narrow probing only when you know why

ModemManager normally uses udev-based auto-scanning to find devices. --no-auto-scan fully disables that scan. It is useful when testing startup behaviour or isolating a device-event problem, but it also means that a modem may not appear simply because the daemon has been told not to look for it.

--filter-policy=STRICT limits probing to TTY ports that heuristics consider very likely to be modem ports. The manual warns that this may ignore some devices. --filter-policy=ALLOWLIST-ONLY is stricter: only devices or ports explicitly allowlisted with the ID_MM_DEVICE_PROCESS udev tag are probed.

These are diagnostic boundaries, not general performance switches. Record the original invocation before adding one. If a modem disappears after a test, remove the filter option and --no-auto-scan, stop the foreground process, and return to the normal system service. Do not edit udev rules as a first response.

5. Use initial events and test options carefully

--initial-kernel-events=PATH tells the daemon to process a file containing the initial kernel-event list at startup. Use it only when you already have a file produced by the diagnostic workflow that requires it. Do not invent the file format or point this option at an arbitrary log.

The manual also lists --test-session, --test-enable and --test-plugin-dir=PATH. These change the D-Bus bus, expose a test interface, or select an alternate vendor-plugin directory. They are for an isolated test setup, not for repairing a production service. A session-bus test can appear to work while ordinary system clients still cannot see the daemon.

For a suspected plugin problem, first capture the version, exact command line, selected log level, and the relevant log lines. Change one test setting at a time. That makes it possible to undo the experiment and identify which setting affected probing.

6. Check the result without guessing from silence

A clean process exit is not proof that a modem was found, and a quiet log is not proof that the daemon is healthy. Check the daemon through the normal client path after returning to the system service. The installed manual points to mmcli(1) for that purpose:

$ man mmcli
$ mmcli --help

If the client cannot connect, record the exact error and check that only the intended system service is running. Do not start another copy with more flags until you have established whether the existing daemon owns the D-Bus name. When a foreground diagnostic is no longer needed, press Ctrl-C, then use your distribution's normal service-management procedure to restore the packaged daemon. The service manager and unit name are outside this man page, so verify them locally rather than copying a command from another distribution.