Bring Up an MBIM Modem with mbim-network

Getting a USB modem online without a full network daemon is exactly what mbim-network is for, and it takes only a handful of steps. You will configure an MBIM modem, start its mobile-data session, get an address on the WWAN interface and stop the session cleanly. Allow 10 to 20 minutes if the modem is already detected and you know the carrier APN. The examples use /dev/cdc-wdm0; swap in the device exposed by your own system.

This guide covers the installed mbim-network from libmbim-utils 1.31.2. It is a small wrapper around mbimcli, not a full network configuration daemon. You need an MBIM-capable modem, a loaded driver, a readable cdc-wdm device, the carrier APN and a DHCP client. Starting and stopping a modem session normally needs elevated privileges.

1. Confirm the utility and modem device

Check the version before trusting output from another machine or an older guide:

$ mbim-network --version
mbim-network 1.31.2
$ ls -l /dev/cdc-wdm0
crw-rw---- 1 root plugdev ... /dev/cdc-wdm0

The permission line is host-specific. If the device does not exist, stop here and investigate the modem, USB connection and kernel driver rather than substituting a guessed path. The command expects the full path to a cdc-wdm character device.

Checkpoint: you have the exact device path and the command reports the version you expect.

2. Create a private connection profile

The default profile is /etc/mbim-network.conf. To avoid touching a shared system file while testing, create a profile in a location readable only by root:

$ sudo install -m 600 /dev/null /etc/mbim-network-phone.conf
$ sudo sh -c 'cat > /etc/mbim-network-phone.conf' <<'EOF'
APN=internet
EOF

Replace internet with the APN your carrier gave you. The profile is sourced as a shell file by the installed script, so keep it to the documented assignment lines and never paste untrusted text into it. If the carrier requires credentials, add all three related settings:

APN=internet
APN_USER=YOUR_APN_USERNAME
APN_PASS=YOUR_APN_PASSWORD
APN_AUTH=PAP

Warning: treat the profile as a secret, since it can hold the APN password.

Checkpoint: inspect the file without exposing it in a shared terminal or transcript:

$ sudo sh -c 'test -s /etc/mbim-network-phone.conf && echo profile-ready'
profile-ready

3. Start the MBIM session

Pass options before the device and command. Use the explicit profile path so this test cannot silently pick a different configuration:

$ sudo mbim-network --profile=/etc/mbim-network-phone.conf /dev/cdc-wdm0 start
Loading profile at /etc/mbim-network-phone.conf...
    APN: internet
    APN auth protocol: unset
    APN user: unset
    APN password: unset
    mbim-proxy: no
...
Network started successfully

The middle lines depend on the modem and registration state. A successful start only means the MBIM connection session was established; it does not assign an IP address to the network interface. If the modem is not registered, the APN is wrong or the device is busy, the underlying mbimcli diagnostics will show which stage failed.

With PROXY=yes in the profile, the script asks mbimcli to use mbim-proxy. That mode skips saving the usual transaction state file, so add it only when your deployment already provides and expects the proxy.

4. Obtain an address with DHCP

Find the WWAN network interface created for the modem, then run the DHCP client used by your distribution. The interface name is not fixed by mbim-network:

$ ip -brief link
lo               UNKNOWN        127.0.0.1/8 ::1/128
wwan0            UP
$ sudo dhclient wwan0
$ ip -brief address show dev wwan0
wwan0            UP             198.51.100.24/32

Your DHCP command, interface name and address will all differ. Use the network manager or DHCP client your system already relies on for that interface; do not run two competing clients. The address above is an example shape, not a value to copy.

Checkpoint: the modem reports a started session and the associated interface has an address. Test reachability with your normal network checks before touching routing or DNS.

5. Check status without changing the connection

The status command queries the modem and prints a short result:

$ sudo mbim-network --profile=/etc/mbim-network-phone.conf /dev/cdc-wdm0 status
Loading profile at /etc/mbim-network-phone.conf...
...
Status: connected

The installed script exits successfully only when the activation state is connected. Anything else produces error: couldn't get connection status or a non-zero result. Status does not renew DHCP, repair routing or check internet access; those stay separate checks.

6. Stop the session and undo the test

Warning: stopping is service-disrupting, since it drops the modem data session. Release the address first, using the DHCP client or network manager that acquired it, then stop the MBIM session:

$ sudo dhclient -r wwan0
$ sudo mbim-network --profile=/etc/mbim-network-phone.conf /dev/cdc-wdm0 stop
Loading profile at /etc/mbim-network-phone.conf...
...
Network stopped successfully

If you used a different DHCP tool, use its release or disconnect operation instead. The script clears its temporary state in /tmp/mbim-network-state-cdc-wdm0 when it stops. Do not delete that file while a session is active; the next command may need its transaction identifier.

To remove the test configuration once you are sure it is no longer needed, delete only the exact file you created:

$ sudo rm -- /etc/mbim-network-phone.conf

Destructive action: this deletion is irreversible and removes stored credentials. Keep the file if you plan to reconnect, or recreate it from a protected backup. Removing the profile does not itself disconnect an already active modem session, so stop the session first.

Common failure points

Done means