NetworkManager, networkd, and address configuration

Before you start#

Review network namespaces, routing and netlink, service jobs, and authorization boundaries. The source examples use NetworkManager 1.48.10 commit b14ad1b692ee2dc0116998e193bbc891a35f6ff2 and systemd v256 commit 5c79cdec10a547a866764a66e1e14898112a00cd. They are independently pinned historical snapshots, not a tested combination or a recommendation to change the host.

Learning goals#

Distinguish a saved profile, a device and an active connection; follow a conditional DHCPv4 lease and cleanup path; and compare networkd's configuration objects without assuming two managers should simultaneously control an interface. Model renewal failure without sending packets or reading host network configuration.

Source walkthrough#

NetworkManager is a userspace network configuration service. A connection profile stores desired settings and identity; a device represents an interface or other supported network object; an active connection represents a particular activation and its state. A profile can exist without an active device, and a device can exist without a successfully activated profile. An activation can require credentials or secrets from an authorized agent. The service, agent and kernel have separate state and failure paths; a configured profile is not proof of connectivity.

The following exact excerpt is from NetworkManager 1.48.10 src/core/devices/nm-device.c, _dev_ipdhcpx_cleanup; its file is GPL-2.0-or-later. Declarations and later cleanup are omitted:

    _dev_ipdhcpx_set_state(self, addr_family, NM_DEVICE_IP_STATE_NONE);

self is the NetworkManager device object and addr_family selects the relevant IP family. This call resets the DHCP-specific IP state to none as part of cleanup. The surrounding code obtains the applicable IP settings and decides whether to send a DHCP release based on configuration and cleanup flags; it does not prove that every deactivation sends a release or that every address disappears immediately. Callbacks, lease data and device references must be detached or released according to the rest of the implementation. A late callback after deactivation is a race the implementation must handle using its own state and lifetime rules.

The next exact excerpt comes from systemd v256 src/network/networkd-dhcp4.c, dhcp4_handler; the file is LGPL-2.1-or-later. Surrounding event conditions and the following branch are omitted:

                                r = dhcp4_lease_lost(link);
                                if (r < 0) {
                                        link_enter_failed(link);
                                        return r;
                                }

On this conditional handler path, networkd asks its Link to process a lost lease. A negative result moves the link to a failed state and propagates the error. The surrounding code includes configuration-dependent branches that can retain configuration instead. The Link object and lease are userspace state; a kernel address or route is a separate object updated through networking interfaces. This source does not establish that NetworkManager uses networkd's handler or that the exact branch ran on a host.

Profiles, links and managers#

A NetworkManager profile can describe addressing, routes, DNS, device matching and other settings. An active connection ties an activation attempt to devices and runtime configuration. A device can change state while a request is pending: it can disappear, lose carrier or be deactivated. A secret agent can provide sensitive credentials through an authorized interaction, and secrets may be stored or requested according to policy. This chapter never reads such credentials or invokes an agent. An IP configuration object is derived state; it is not the same object as the profile from which an activation began.

NetworkManager can use different DHCP client implementations or backends depending on its version, build and configuration. Its src/core/dhcp/nm-dhcp-client.c and nm-dhcp-manager.c are source entry points for this pinned release. A particular installation may use a different backend or configuration, so a single remembered DHCP call chain is not a universal trace.

systemd-networkd has its own configuration and runtime objects. .link files influence matching and link properties in their documented stage; .netdev describes supported virtual network devices; .network matches links and configures network behavior. The precise match, precedence and feature support depend on the version and environment. NetworkManager and networkd are distinct managers and should not be assumed to manage the same interface concurrently. Running two controllers against the same link can cause conflicting desired state or repeated reconfiguration; a specific distribution's delegation and ownership policy must be inspected before drawing conclusions.

A manager uses netlink and other kernel interfaces to learn about links and request address or route changes. The kernel can reject a request due to permissions, invalid attributes, resource limits or races with interface removal. A successful D-Bus response or profile selection does not by itself establish that all requested netlink operations succeeded. The manager's event loop receives asynchronous link and address notifications; it must reconcile its desired state with actual kernel state. An interface index can be reused after a link disappears, so a stale index without lifecycle context is not a permanent device identity.

DHCPv4 state and a worked lease#

DHCPv4 lets a client obtain configuration from a server under the protocol's rules. A simplified initial exchange is DISCOVER, OFFER, REQUEST and ACK. The client sends a discovery, considers an offer, requests a selected configuration and receives an acknowledgment. Real exchanges include retransmission, validation, server identifiers, options, conflicts and implementation-specific choices; a packet sequence in a textbook is not evidence that a host used a particular server.

Use this synthetic lease: address 192.0.2.10/24, router 192.0.2.1, DNS server 192.0.2.53, lease lifetime 3600 seconds, T1 1800 seconds and T2 3150 seconds. At T0 the ACK is accepted under our assumptions. At T1 the client enters RENEWING and attempts to contact the server that originally supplied the address. If no DHCPACK arrives before T2, RFC 2131 specifies transition to REBINDING and a broadcast DHCPREQUEST to any server; T1/T2 may be supplied by the server, with defaults of 0.5 and 0.875 of lease duration. Clients retransmit while the lease remains valid. At expiry without an ACK, the client must stop using the address and return to INIT (RFC 2131 §§4.4.5–4.4.6). A graceful DHCPRELEASE is optional for correct protocol operation. If the lease expires at T0+3600 with no successful extension, the client and manager must handle loss of the lease according to their configured policy. The documentation addresses and values are synthetic; no packet was sent and no route was installed for this example.

A valid lease supplies candidate network configuration, not an end-to-end guarantee. The manager may request an address and route through netlink and hand DNS information to a resolver integration. A kernel rejection, address conflict, missing route, firewall policy, broken gateway, DNS failure or unreachable remote service can still prevent an application from working. A successful address assignment does not prove that a remote host is reachable. DNS handoff is also configuration-specific: not every system uses systemd-resolved or writes the same resolver file.

In the pinned networkd handler, a lost-lease event can invoke dhcp4_lease_lost and put the link into failure if the cleanup operation returns a negative error. The surrounding source has KeepConfiguration-related conditional behavior; do not promise that every configured address is always removed in every failure. The source's lease object, link object, address objects and asynchronous callbacks have distinct lifetimes. A lease becoming invalid while an address update is pending must be handled according to the implementation's state machine, not by a stale callback blindly restoring old configuration.

DHCPv6 and IPv6 router advertisements are related but distinct mechanisms. Router advertisements can supply prefix and router information and influence address configuration; DHCPv6 can supply other configuration according to its protocol and deployment. Neither should be reduced to the DHCPv4 four-message diagram. Link-local addresses, duplicate-address detection, route lifetimes and DNS information have their own conditions. A system can have an IPv6 address but lack a usable default route, just as an IPv4 address alone does not establish application reachability.

Renewal, failure and ownership#

At T1 in the synthetic lease, no renewal response is received. The client retains and uses its existing lease only while the protocol and implementation consider it valid. At T2 it can try the rebinding path, still subject to the expiry deadline. At T0+3600, assume no valid extension arrived and the configured policy does not keep stale configuration. The manager processes lease loss, requests removal or replacement of applicable state, updates dependent objects and reports the resulting status. If a kernel update fails, the manager's error and actual kernel state must be examined separately. This is a source-grounded model, not a prediction that every networkd or NetworkManager deployment takes the same cleanup branch.

The inspected v256 dhcp4_lease_lost clears the link's configured flag, gathers the results of address-and-route removal and other cleanup, unreferences link->dhcp_lease, marks the link dirty and stops before requesting static nexthops if a gathered cleanup error is negative. It then requests static nexthops and routes on the nonerror path. This is a more specific statement than “delete everything”: individual operations can fail, KeepConfiguration can alter the handler path, and other address sources can still exist. It also illustrates why an error result must not be treated as an atomic rollback of all previous network changes.

In src/network/networkd-dhcp4.c, systemd v256, dhcp4_lease_lost, LGPL-2.1-or-later (SPDX; the function's first lines and the 6rd branch are omitted, marked with /* ... */):

        link->dhcp4_configured = false;
        /* ... */
        RET_GATHER(r, dhcp4_remove_address_and_routes(link, /* only_marked = */ false));
        RET_GATHER(r, dhcp_reset_mtu(link));
        RET_GATHER(r, dhcp_reset_hostname(link));

        link->dhcp_lease = sd_dhcp_lease_unref(link->dhcp_lease);
        link_dirty(link);

        /* If one of the above failed. Do not request nexthops and routes. */
        if (r < 0)
                return r;

The gathered errors decide whether the static nexthop and route requests run after the cleanup. The excerpt does not show whether each removal succeeded or whether another address source survives the call, and it does not establish that NetworkManager runs this code.

An old lease callback can arrive near a new activation or device removal. The relevant client, lease and link references must remain alive until callbacks and event sources are detached, while a state or generation check prevents an old result from being applied to a newer activation. The exact references, cancellation APIs and state checks differ between the two projects. A service restart can invalidate a D-Bus proxy or active-connection path even though a profile file remains. A consumer must handle disappearance, errors and renewed state rather than treating an object path as an eternal network identity.

Configuration may have multiple sources: a static profile, DHCP options, router advertisements, VPN-specific routes and administrator policy. A manager combines or prioritizes them under its own rules. A default route and per-link DNS configuration can change independently. If a DNS server is installed but the route to it is absent, queries can fail; if a route exists but the service is unreachable, the same symptom can have another cause. Record the exact profile, device, lease and route state only in an authorized environment, with secrets and private addresses omitted from shared evidence.

A lease is not a single object#

A DHCP client can own an event source, socket or backend process while the network manager owns a device object and a particular activation request. The lease data received from the client can be converted into address, route and DNS configuration with lifetimes independent of the original packet buffer. A component that keeps only a pointer into a freed reply buffer has a memory-lifetime error; a component that holds a valid lease object after its expiry has a state-validity error. Those problems require different fixes. This model does not assert that both managers use the same internal representation.

In src/core/devices/nm-device.c, NetworkManager 1.48.10, _dev_ipdhcpx_cleanup, GPL-2.0-or-later (SPDX; the branches between the two parts are omitted, marked with /* ... */):

        release = force_release || (release && full_cleanup);
    /* ... */
    if (priv->ipdhcp_data_x[IS_IPv4].client) {
        nm_clear_g_signal_handler(priv->ipdhcp_data_x[IS_IPv4].client,
                                  &priv->ipdhcp_data_x[IS_IPv4].notify_sigid);
        nm_dhcp_client_stop(priv->ipdhcp_data_x[IS_IPv4].client, release);
        g_clear_object(&priv->ipdhcp_data_x[IS_IPv4].client);
    }

The flag is computed from the applied dhcp-send-release setting and the cleanup flags, then passed to nm_dhcp_client_stop before the client object is cleared. The excerpt does not show whether a release packet is actually sent, because the DHCP client decides that.

When an interface disappears during activation, a pending address-install acknowledgment can arrive after the manager has moved on. A robust investigation asks which activation and link the callback belongs to, whether a reference still exists, whether a stop or reconfiguration was requested and which kernel operation actually succeeded. An interface name can be reused after hotplug, so matching only a displayed name is weaker evidence than tracking the appropriate lifecycle and identifiers. The selected source shows concrete state and error branches, but it does not independently prove that every late callback is impossible.

Consider two additional failure outcomes for the synthetic lease. If the server returns no usable renewal but the old lease is still valid, the current address may remain usable until expiry under the stated client policy. If the manager receives a negative result while removing expired state, its recorded link failure does not by itself reveal which kernel address or route was successfully removed before the error. A follow-up needs the individual operation results and current state in a controlled environment. Similarly, DNS options handed to another component can outlive a particular event only under that component's own configuration and cleanup rules. Neither a profile nor a DHCP ACK alone proves that the resolver consumed the options.

A comparison between managers should start from an ownership decision: which service is responsible for the link, who supplies the profile, which DHCP backend is selected, and which component receives DNS information. If two independent managers both try to enforce configuration, one can remove or replace what the other just installed. A rapid sequence of netlink notifications is evidence of events to investigate, not proof of a particular manager conflict. The safe exercise below models none of these host operations; it only checks arithmetic over declared lease thresholds.

Practice#

The following pure state model calculates the stated lease stages. It sends no packets, opens no network sockets, reads no host interfaces or configuration, and invokes neither NetworkManager nor networkd:

python3 - <<'PY'
def stage(seconds):
    if seconds < 1800: return 'bound'
    if seconds < 3150: return 'renewing'
    if seconds < 3600: return 'rebinding'
    return 'expired'
for t in (0, 1800, 3150, 3600):
    print('synthetic', t, stage(t))
PY

Expected output is bound, renewing, rebinding and expired for the listed synthetic times. This does not implement DHCP packet validation, a real timer, retransmission or either manager's policy. If Python is unavailable, evaluate the same four thresholds by hand. A failed renewal is represented by the absence of a successful extension in the model; it is not a captured network failure.

For a source-only alternative, draw the profile, device, active connection, DHCP client and kernel address as distinct objects. Use the four-message and T0/T1/T2 timeline above, mark the two source excerpts' cleanup and error branches, and explain why an address does not prove DNS or remote application connectivity. Deliver the timeline and ownership table with all addresses labeled synthetic.

Knowledge check#

1. How does a saved profile differ from an active connection and a device?
2. What does the NetworkManager cleanup excerpt reset, and why does it not prove a release packet was sent?
3. What happens in the quoted networkd branch when lease-loss handling fails?
4. What are the synthetic T1, T2 and expiry values, and why are they not measurements?
5. Why can a configured address coexist with failed application connectivity?

Answers#

1. A profile records desired configuration, a device represents a managed network object, and an active connection represents a particular runtime activation. Their lifetimes and failure states differ.
2. It resets the DHCP IP state for the selected device and address family. Release behavior is decided by surrounding configuration and flags, so the one call does not establish a packet was sent.
3. The handler marks the link failed and returns the negative result. Other configuration-dependent branches can retain or handle state differently.
4. They are 1800, 3150 and 3600 seconds in the explicitly invented example. No DHCP server, packet or real clock produced them.
5. Routes, gateway, DNS, policy, remote service and kernel installation can fail independently of address assignment. Each boundary needs its own evidence.

Checkpoint#

Submit the lease state table, object ownership diagram and either the private model output or source-only calculation. Ready means explaining renewal versus expiry, both source cleanup branches and at least two reasons an address is not end-to-end connectivity. Retry with the one synthetic lease before adding IPv6 and VPN configuration.

Sources#

• NetworkManager 1.48.10 device source
• NetworkManager 1.48.10 DHCP client
• NetworkManager 1.48.10 DHCP manager
• systemd v256 networkd DHCPv4
• systemd v256 networkd address handling