Safely test and apply a Netplan network change

You will inspect the active Netplan view, make a small YAML change, generate backend configuration, and apply it with a rollback path. This guide uses Netplan 1.1.2 on a system with the netplan.io and netplan-generator packages installed. Allow 15 to 20 minutes, plus time to arrange console access if the machine is remote.

1. Confirm the installed command and current state

Start without changing anything. The CLI has separate commands for reading configuration, generating backend files, applying configuration, and testing a change with an automatic rollback.

$ netplan --version
netplan-generator 1.1.2-8ubuntu1~24.04.3
netplan.io 1.1.2-8ubuntu1~24.04.3
$ netplan status
     Online state: online
    DNS Addresses: 127.0.0.53 (stub)
...

Your status output will describe different interfaces, addresses and routes. Use netplan status INTERFACE for one interface, or netplan status --format json when a script needs machine-readable output. These queries do not alter the running network.

2. Understand which YAML Netplan reads

Netplan reads *.yaml files from /lib/netplan, /etc/netplan and /run/netplan. Files are merged in lexicographic order. A later key overrides an earlier key, and a file in /run/netplan shadows a same-named file in /etc/netplan. This is a common distraction: editing a file that is shadowed, or adding a filename that sorts earlier than an existing override, can appear to do nothing.

The top-level structure is a network mapping. Configuration format version 2 is the supported value. The default renderer is networkd; set renderer: NetworkManager when that is the intended backend. A device definition brings that device under Netplan's control, so omitting an interface is different from defining it with an empty mapping.

3. Read the merged configuration

Run the read-only query as root when the YAML files are not readable by your account. The all key returns the merged view; a dotted key narrows the result.

$ sudo netplan get all
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true
$ sudo netplan get network.ethernets.eth0
network:
  ethernets:
    eth0:
      dhcp4: true

Do not assume that dhcp4: true is present just because the interface has an address. An address may have come from another file, a static configuration, or a different manager. Check the merged YAML and netplan status together.

4. Make a change in a controlled file

For a normal host, netplan set writes a validated YAML override in /etc/netplan. It accepts a dotted key and a value. The following enables IPv4 DHCP on the placeholder interface:

$ sudo netplan set --origin-hint local network.ethernets.eth0.dhcp4=true
$ sudo netplan get network.ethernets.eth0.dhcp4
true

The command may create /etc/netplan/local.yaml; inspect the actual file before applying it. If eth0 is not the intended device, stop and correct the key. To undo this particular file before applying, remove the new override after reviewing its path, or set the key to null to delete that key from the generated override:

$ sudo netplan set --origin-hint local network.ethernets.eth0.dhcp4=null
$ sudo netplan get network.ethernets.eth0

For an unprivileged rehearsal, use a temporary root with its own etc/netplan directory. This verifies the syntax and merge behaviour without touching the host:

$ test_root=$(mktemp -d /tmp/netplan-test.XXXXXX)
$ mkdir -p "$test_root/etc/netplan"
$ netplan set --root-dir "$test_root" --origin-hint example network.ethernets.eth0.dhcp4=true
$ netplan get --root-dir "$test_root" all
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true

5. Generate backend configuration before touching the network

netplan generate converts the merged YAML into configuration for systemd-networkd or NetworkManager. It does not apply that configuration. Run it with elevated privileges on the real host, then inspect the command's exit status and debug output if it fails.

$ sudo netplan --debug generate
$ printf 'generate exit status: %s\n' "$?"
generate exit status: 0

A zero status means generation completed; it does not prove that the interface has the desired address or route. If generation reports an unknown key, a malformed address, or an unavailable renderer, fix the YAML and repeat this step. Do not proceed with apply while the generated configuration is unresolved.

6. Apply with a rollback window

netplan try applies a configuration and rolls it back if you do not confirm it before its timeout. The default timeout is 120 seconds. Use it for changes that might affect your connection, and confirm only after checking the new state from the same or a second session.

$ sudo netplan try --timeout 120
Do you want to keep these settings?
Press ENTER before the timeout to accept the changes
Changes will revert automatically if not confirmed.

The exact prompt depends on the installed release. Test the connection, name resolution and required routes before pressing Enter. If the session dies or you cannot confirm, leave the prompt alone and let the rollback happen. If you have already confirmed a bad change, restore the previous YAML and run sudo netplan generate followed by sudo netplan apply from console access.

netplan apply applies the current configuration immediately and has no equivalent confirmation window. Use it only after generation and, for a remote system, after a tested recovery plan:

$ sudo netplan apply
$ netplan status eth0

7. Diagnose a result that does not match the YAML

First compare the merged configuration with the running state:

$ sudo netplan get all
$ netplan status --verbose
$ netplan status --diff

If the merged view is wrong, check filename ordering and shadowing under the three Netplan directories. If the merged view is right but the running state is wrong, check which renderer owns the interface and inspect that renderer's service logs using the system's normal systemd tools. A configured device is brought up by its applicable renderer; an interface that is entirely omitted is not touched by Netplan.

Do not solve a permissions error by making Netplan YAML world-readable. Configuration can contain Wi-Fi credentials and other sensitive values. Use root for protected reads and preserve the existing file ownership and permissions.