Read Network State and Safely Apply networkd Changes with networkctl

In about 10 minutes, you can use networkctl to identify an interface, tell the difference between carrier and a usable route, inspect the configuration that systemd-networkd selected, and apply a changed .network file with a controlled reload and reconfigure.

Before you start

This guide assumes a system using systemd-networkd. You need the networkctl command from systemd 219 or newer. The examples were checked with systemd 255.4 on the local machine. Reading status normally needs no elevated privilege. Changing link state or reloading network configuration normally needs root, so use sudo where shown.

Have the real interface name ready, such as enp0s31f6. Do not copy that name blindly: predictable interface names differ between machines. Find yours first.

1. Find the interface and its high-level state

Start with a complete link list:

networkctl --no-pager list

The useful columns are the link index and name, then OPERATIONAL and SETUP. A line such as this is healthy for a managed Ethernet link:

2 enp0s31f6  ether  routable  configured

routable means the link has carrier and a routable address. carrier only means that a physical or virtual link is present. no-carrier means the device is powered but has no carrier yet. The setup column is separate: configured means networkd configured the link, while unmanaged means it is not handling it. A Docker bridge can therefore be routable and unmanaged without indicating that networkd is broken.

Use a name or index to narrow the output:

networkctl --no-pager list enp0s31f6

2. Inspect one link and the overall network

Ask for details about the selected interface:

networkctl --no-pager status enp0s31f6

The report can include the selected link and network files, driver, hardware address, MTU, operational state, addresses, gateway, DNS servers, and recent networkd log lines. With no link argument, status reports the combined network state instead:

networkctl --no-pager status

The overall report has a State and an Online state. Online status is based on links that networkd considers required. partial does not mean every interface is unusable: it means some required links are online and some are not. If status is long, --lines=20 shows the 20 most recent journal lines. --full prevents long values from being shortened.

networkctl --no-pager --full --lines=20 status enp0s31f6

When diagnosing a service outage, compare the address and gateway here with the route and resolver evidence from the application host. An interface being routable does not prove that a particular remote service, route policy, or DNS name works.

3. Use JSON when a script needs stable fields

Human-readable output is useful at a terminal but awkward to parse. Request compact JSON for a script or a quick inspection:

networkctl --no-pager --json=short status enp0s31f6

For review, use the indented form:

networkctl --no-pager --json=pretty status enp0s31f6

Do not assume a missing field is an error. For example, the local loopback interface reports no associated network file, and some online-state fields are not meaningful for every interface. Check the command exit status as well as the data:

if networkctl --no-pager --json=short status enp0s31f6 >/tmp/networkctl.json; then
    printf '%s\n' 'networkctl completed successfully'
else
    printf '%s\n' 'networkctl could not inspect the interface' >&2
    exit 1
fi

4. Check the configuration selected for a device

cat displays network configuration files known to networkd. For a specific interface, use the @ form:

networkctl --no-pager cat @enp0s31f6

If no file is associated, networkctl says so. That is different from a syntax error. A file can exist in /etc/systemd/network/ but fail to match the interface, or a link can be intentionally unmanaged.

You can also display a named file, if you know it:

networkctl --no-pager cat 10-wan.network

Use this step before editing anything. It helps prevent the common mistake of changing a file that looks plausible but is not the file networkd selected.

5. Apply a changed networkd configuration

Editing a .network file and asking only for a reconfigure is a common trap. In systemd 255, reconfigure does not reload changed .network or .netdev files first. The safe sequence is:

sudo networkctl reload
sudo networkctl reconfigure enp0s31f6
networkctl --no-pager status enp0s31f6

reload makes networkd reread .network and .netdev files. New matching network files can reconfigure their interfaces. A new .netdev can create its virtual device, but editing or removing an existing .netdev does not automatically update or remove that device. Treat those changes as a separate operational task.

Reloading or reconfiguring a live management interface can interrupt SSH, DHCP, routes, or addresses. Keep an existing session open, arrange console access, and make one change at a time. If the result is wrong, restore the previous file and repeat the same reload and reconfigure sequence. If the configuration change is only temporary, reverting the file is the undo operation; networkctl does not keep a rollback copy for you.

networkctl --no-pager --lines=30 status enp0s31f6

Commands that can disrupt or delete links

The commands below change live state and are not needed for ordinary diagnosis:

• sudo networkctl down DEVICE brings a device down and can cut the current connection.
• sudo networkctl up DEVICE brings a device up, but does not by itself guarantee that addressing or routing is correct.
• sudo networkctl renew DEVICE renews dynamic configuration, such as a DHCP lease.
• sudo networkctl delete DEVICE deletes a virtual netdev. Never use it on a production bridge or virtual device until you have checked which workloads depend on it.

Use an interface name rather than an uncertain numeric index, and verify the target with networkctl list immediately before a state-changing command. Network topology can change while you are working, so an old index is not a safe identity.