Inspect systemd-networkd Through Its D-Bus Interface

You will inspect the system bus interface exposed by systemd-networkd, find the D-Bus object for a named network link, and distinguish a network problem from a missing D-Bus service. The examples are read-only. Allow about fifteen minutes and have a shell on a host using systemd-networkd.

This guide matches the installed systemd 255 manpage on this machine. D-Bus interfaces are versioned, so a newer systemd may expose additional methods or properties. Check the installed interface before copying a command into automation.

1. Confirm that networkd is the service you are inspecting

Check the service state first. This command reads service state and normally needs no elevated privileges:

$ systemctl is-active systemd-networkd.service
active
$ systemctl is-enabled systemd-networkd.service
enabled

active is a useful checkpoint, but it does not prove that the D-Bus name is available or that every link is managed. A host can have network connectivity from another manager, and networkd can deliberately leave links unmanaged.

Next, compare the high-level view from networkctl:

$ networkctl list --no-pager
IDX LINK          TYPE     OPERATIONAL SETUP
  1 lo            loopback carrier     unmanaged
  2 enp0s31f6     ether    routable    configured
  4 docker0       bridge   routable    unmanaged

Your interface names and rows will differ. Record the exact name you want to investigate, such as enp0s31f6. Do not use a guessed name in the D-Bus path.

2. Introspect the manager object

The manager object is always addressed as /org/freedesktop/network1. Ask the system bus for its methods and properties:

$ gdbus introspect --system \
    --dest org.freedesktop.network1 \
    --object-path /org/freedesktop/network1

Look for the org.freedesktop.network1.Manager interface. On the installed version it includes read-oriented methods such as ListLinks, GetLinkByName, GetLinkByIndex, Describe and DescribeLink. It also lists methods that can alter live DNS, NTP, resolver domains or link state. Seeing a method in introspection is not a reason to call it.

Expected output is long and includes signatures similar to:

interface org.freedesktop.network1.Manager {
  ListLinks(out a(iso) links);
  GetLinkByName(in  s name, out i ifindex, out o path);
  Describe(out s json);
}

Checkpoint: if the command prints Error connecting, stop here. A running unit is not enough if the service is not reachable on the system bus. Check systemctl status systemd-networkd.service --no-pager, recent logs with journalctl -u systemd-networkd.service -b --no-pager, and whether the host is using a different network manager. Do not work around this by changing network configuration.

3. Map an interface name to its object path

Use the manager method instead of constructing a path from memory. Replace IFACE with the name from networkctl list:

$ IFACE='enp0s31f6'
$ gdbus call --system \
    --dest org.freedesktop.network1 \
    --object-path /org/freedesktop/network1 \
    --method org.freedesktop.network1.Manager.GetLinkByName \
    "$IFACE"
(2, objectpath '/org/freedesktop/network1/link/_2')

The first value is the kernel interface index. The second is the link object path. The suffix is based on that numeric index, not on the interface name, so it can change when a virtual device is recreated.

If the result says that the link cannot be found, verify spelling and confirm that networkd knows about the device. An interface can exist in the kernel while networkd has no corresponding managed link object. Check the service log before trying a runtime setter.

4. Read link status without changing it

Pass the returned object path to another introspection request:

$ gdbus introspect --system \
    --dest org.freedesktop.network1 \
    --object-path /org/freedesktop/network1/link/_2

The org.freedesktop.network1.Link interface exposes states including OperationalState, CarrierState, address states, OnlineState and AdministrativeState. Their values describe networkd's view at that moment. They are not a promise that an application can reach a particular remote service.

For a compact human-readable check, use the same link name with networkctl:

$ networkctl status "$IFACE" --no-pager
● 2: enp0s31f6
       Link File: /usr/lib/systemd/network/99-default.link
    Network File: /etc/systemd/network/20-wired.network
           State: routable (configured)
          Online state: online

Output varies with the host and networkctl version. The useful comparison is whether the link path, operational state and network file agree with what you expected.

5. Read the manager description when debugging configuration selection

The installed interface also provides a JSON description of the manager. Call it without arguments:

$ gdbus call --system \
    --dest org.freedesktop.network1 \
    --object-path /org/freedesktop/network1 \
    --method org.freedesktop.network1.Manager.Describe

The returned string is JSON and may be easier to save for comparison than a screen-wide introspection dump. To keep a diagnostic file in your current directory, use an explicit destination:

$ gdbus call --system \
    --dest org.freedesktop.network1 \
    --object-path /org/freedesktop/network1 \
    --method org.freedesktop.network1.Manager.Describe > networkd-manager.txt

This writes command output, including the D-Bus return wrapper, rather than a guaranteed standalone JSON document. Treat it as a diagnostic capture, not as a stable file format. Remove it after checking that it contains no environment-specific information you should not retain:

$ less networkd-manager.txt
$ rm -- networkd-manager.txt

The removal is optional and irreversible. If you need the record, move it to an approved diagnostic location instead.

6. Keep inspection separate from live changes

The manager and link interfaces include methods such as SetLinkDNS, SetLinkNTP, SetLinkDomains, ReconfigureLink and Reload. These are not harmless queries. They can change resolver behaviour, trigger DHCP activity or interrupt a link, and their authorisation depends on the host's D-Bus policy.

Do not test them on a remote production host just to discover their argument syntax. For persistent network configuration, edit the intended .network or .netdev file with a backup and a console or recovery path, then use the documented networkd reload workflow. For a runtime change made through a supported tool, record the previous state first. The interface offers RevertDNS and RevertNTP for their corresponding transient settings, but there is no single undo method for every possible change.

After any authorised change, verify both the affected link and the overall state:

$ networkctl status "$IFACE" --no-pager
$ networkctl status --no-pager

Use sudo only when your host requires it for the particular inspection or approved change. Read-only gdbus and networkctl checks normally work as an ordinary user.