Bring Up a QMI Data Session with qmi-network

You will configure a QMI modem profile, start a data session on a cdc-wdm device, check its state, and stop it cleanly. The examples match qmi-network 1.35.2 from the Debian package libqmi-utils 1.35.2-0ubuntu2. Allow about fifteen minutes if the modem is already exposed as a /dev/cdc-wdmN device.

You need the libqmi-utils package, a QMI-capable modem, its cdc-wdm character device, the APN supplied by your network operator, and a DHCP client for the resulting WWAN interface. Starting and stopping a session changes modem state and may interrupt an existing connection. Confirm that you are working on the right device before running the state-changing commands.

1. Identify the command and modem device

First check the installed command and locate the device. These checks are ordinary commands and do not need elevated privileges:

$ qmi-network --version
qmi-network 1.35.2
$ ls -l /dev/cdc-wdm*
crw-rw---- 1 root dialout ... /dev/cdc-wdm0

The device path is an example. Use the path belonging to your modem, not whichever number happens to appear in documentation. If the glob matches nothing, stop here and investigate modem enumeration, drivers and permissions. Do not create a fake device node.

Checkpoint: set a shell variable to the path you verified. This does not change system state:

DEVICE=/dev/cdc-wdm0
test -c "$DEVICE" && printf 'Using %s\n' "$DEVICE"

2. Create a private profile

qmi-network requires a profile. Without --profile, it reads /etc/qmi-network.conf. Use a separate file while testing so an existing system-wide profile is not overwritten:

PROFILE=/tmp/qmi-network.conf
umask 077
cat > "$PROFILE" <<'EOF'
APN=YOUR_APN
# APN_USER=YOUR_USERNAME
# APN_PASS=YOUR_PASSWORD
# IP_TYPE=4
# PROXY=yes
# PROFILE=auto
EOF

Replace YOUR_APN with the real APN before continuing. The optional username and password are only needed when your operator requires them. IP_TYPE may be 4 or 6. PROXY=yes asks the script to use qmi-proxy, and PROFILE=auto creates a temporary modem profile for the session. An existing numeric profile ID can be used instead, for example PROFILE=3.

Security warning: the installed script reads the profile as shell syntax, and it can print the APN password while loading it. Keep the file trusted and private, avoid committing it, and do not paste credentials into support logs. When the test is over, remove this temporary profile only if it contains no information you need:

rm -f -- "$PROFILE"

That removal is irreversible. If you need to retain the settings, move the file to an access-controlled location instead and pass that path explicitly.

3. Start the network session

Starting the connection normally needs access to the modem device and may require elevated privileges on your host. Pass options before the device, then the device and the command:

$ sudo qmi-network --profile=/tmp/qmi-network.conf /dev/cdc-wdm0 start
Loading profile at /tmp/qmi-network.conf...
    APN: YOUR_APN
    APN user: unset
    APN password: unset
    qmi-proxy: no
    IP_TYPE: unset
    PROFILE: unset

The lines above are the profile summary printed by the installed script. Further modem diagnostics vary, and a real APN replaces YOUR_APN. Treat the command's exit status and the later status check as the verification, not a copied transcript.

The exact diagnostic lines depend on the modem and qmi-proxy configuration, so do not use a copied success message as proof. A successful qmi-network start is only the modem-side part of the job. The manpage explicitly requires a DHCP client on the associated WWAN interface before the host has usable IP configuration.

Checkpoint: if the command reports that the profile is missing, check the path and permissions. If it reports a modem or WDS error, keep the session stopped until you know whether a partial connection was created; do not repeatedly start it as a troubleshooting shortcut.

4. Query the session and run DHCP

Ask qmi-network for the modem-side status using the same device and profile:

$ sudo qmi-network --profile=/tmp/qmi-network.conf /dev/cdc-wdm0 status

Output is modem-specific. The useful result is the command's reported packet-service state, not a guessed interface name. Find the WWAN interface separately with ip link, then run the DHCP client your distribution uses. For example, only after you have identified the correct interface:

$ ip link
$ sudo dhclient WWAN_INTERFACE

Replace WWAN_INTERFACE with the real interface, such as a name shown by ip link. Do not run DHCP against WWAN_INTERFACE literally. Verify the result with ip address show dev WWAN_INTERFACE and a route check. A connected modem without a DHCP lease is not a completed host network setup.

5. Stop the session and recover

Stopping is also a service-disrupting action. Use it when you are ready to tear down the data session:

$ sudo qmi-network --profile=/tmp/qmi-network.conf /dev/cdc-wdm0 stop
... stop-network output ...

Afterwards, query status again. If you ran a separate DHCP client, release its lease using the client and options used by your distribution, then remove any temporary profile you no longer need. If stop fails, do not delete state blindly or keep issuing start; capture the diagnostic, confirm the device path, and check whether the modem is still reachable.

For a persistent setup, copy the reviewed settings into the intended system profile, protect its permissions, and use the same explicit device path. Do not put an APN password into a world-readable file. Test a persistent profile in a maintenance window because the first start can change the modem's data format or interrupt another user of the device.