Ubuntu Network Configuration Guide: Netplan, Static IP, and DNS

A Netplan file can be valid YAML, apply without an error, and still leave the machine unreachable. The generator reports only what it can parse, so a wrong interface name, a missing default route, or a resolver that never lands surfaces once the network is gone.

I checked the generator against a config that still carried the old gateway key, and it warned instead of stopping, which is how a clean render keeps no route at all.

How Ubuntu decides which network settings to use

Netplan reads every YAML file in /etc/netplan, generates backend configuration under /run, and hands the devices to a renderer. Server images use systemd-networkd, desktop images use NetworkManager, and that one choice decides where a change has to be made.

The YAML you edit is a request rather than the live state. What the kernel and the resolver hold afterwards is the thing worth checking, which means a file can be perfect while the interface is not.

Each layer keeps a copy of part of the configuration, so the value you want is always read from the layer that owns it.

On a desktop image the installer writes a Netplan file that hands every device to NetworkManager, and the Settings panel then edits NetworkManager connections rather than the YAML. That is why a desktop change made through the GUI and a server change made in a file can both be correct and still disagree about the same machine.

What you need before you change anything

A Netplan change needs root, because the files under /etc/netplan are readable only by their owner. It also needs a way back into the machine that does not depend on the network you are about to alter.

On a remote machine that second requirement means a console session from the provider, since it is the only entry point that survives a wrong address or a lost default route.

• Root or sudo on the machine.
• The interface name, from the command in the next section.
• The address, prefix length, gateway and resolvers, from your router or network administrator.
• A console session when the machine is remote.

The generator is strict about file modes and expects 600 on every file it reads. I set that mode on the config before generating, and the permissions warning was gone on the next run.

ls -l /etc/netplan/
sudo chmod 600 /etc/netplan/90-static.yaml

Ubuntu’s server documentation warns against setting DHCP on an interface that another file, such as the one cloud-init writes, already configures. Deciding which file owns the device before you add keys to it saves a merge you cannot predict.

I opened the Netplan file a cloud image writes for itself, and it matches the hardware address and renames the device, which is the shape to copy when a config has to stay attached to one port.

The desktop path through Settings

On a desktop image the Settings panel writes through NetworkManager. The IPv4 tab of a connection carries the same decisions as the YAML: an automatic or manual method, resolvers, and routes.

Choose Wi-Fi or Network for the device type, then open the gear icon beside the connection you want to change.

A Wi-Fi device configured from the terminal is a separate task, covered in the guide on connecting to Wi-Fi from the command line. What follows applies to Ethernet devices and to virtual interfaces, which is where Netplan edits usually land.

Find the interface Ubuntu is using

Interface names come from the firmware and the bus the device sits on, so a PCI Ethernet card comes up as something like enp0s6 and a Wi-Fi card as something like wlp4s0. The leading letters carry the type, with en for Ethernet, wl for Wi-Fi, and lo for the loopback device that never leaves the machine.

ip -brief address

A container host shows more than that. I ran ip -brief address on a machine with containers running and the physical device turned out to be one line in a list dominated by container bridges, so the leading type letters are what you scan for.

The address side of that list is covered in more detail in the guide on finding your IP address in Linux. The name is what the YAML needs, and the name is the first column here.

Write the Netplan YAML for DHCP or a fixed address

An interface takes its address from a lease or from a block you type yourself. The keys differ by which one you want, and both cases open with the same block header, which names the format version, the renderer, and the device.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s6:
      dhcp4: true

A lease is the setting to keep on any machine whose address you do not care about, because the DHCP server also delivers the route and the resolvers. If you need that server to exist in the first place, the walkthrough on setting up a DHCP server on Ubuntu covers it.

Set a fixed address with a default route

A fixed address needs the address with its prefix, a default route, and resolvers, all inside the same interface block.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s6:
      dhcp4: false
      addresses:
        - 192.168.1.50/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [1.1.1.1, 9.9.9.9]

The route entry replaces the gateway4 key, which still renders but earns a warning. I generated that block in a throwaway tree and it printed “gateway4 has been deprecated, use default routes instead” while the exit status stayed 0, so a deprecated key can survive repeated applies unnoticed until the day it stops being accepted.

A wrong prefix length hides in this block, because the machine keeps answering on the subnet it believes it is on. The full walkthrough for a fixed address, including the values a home router expects, is in the guide on setting up a static IP on Ubuntu.

Set DNS resolvers on the interface

Resolvers belong in the same interface block, because /etc/resolv.conf points into systemd-resolved on a current Ubuntu and is rewritten on the next boot. Anything typed into that file is a temporary edit, and the resolvers that survive a reboot belong to the interface.

      nameservers:
        addresses: [1.1.1.1, 9.9.9.9]
        search: [example.lan]

For a single value, netplan set writes the key back to the YAML without an editor. I set a resolver list that way and the new address was appended to the list already in the file, so read the result before applying it.

sudo netplan get ethernets.enp0s6
sudo netplan set ethernets.enp0s6.nameservers.addresses=[8.8.8.8]

Resolver changes take effect for new lookups only, and cached answers live in systemd-resolved rather than in the browser. The guides on changing DNS on Linux and clearing the DNS cache on Ubuntu cover those two cases.

An address on an interface comes from DHCP or from the file, never from both, and a temporary address added by hand is gone at the next reboot. That difference is spelled out in the guide on setting a temporary IP address in Linux.

Apply the change without cutting the connection

Applying a Netplan file happens in two places, and the first one is safe. The generator renders the YAML into backend configuration without touching the running state, so it can run at any point, and the command that changes a live machine comes second.

sudo netplan generate

File modes are the warning people meet first, and the exact text asks for permission mode 600 on every file it reads. The generator writes its own configuration under /run, so a clean run leaves no other trace and a broken file stops there.

The apply command comes in two versions, and the choice between them is about what a failed apply costs.

netplan try applies the file, starts a timer, and reverts on its own unless the change is accepted inside the window. That timer is what makes it the right command over SSH, because a wrong address ends the session before anything can be confirmed.

netplan apply writes the configuration and keeps it, with no timer and no automatic revert.

sudo netplan try
sudo netplan apply

When the running state has to be reset rather than reconfigured, the guide on restarting networking on Ubuntu covers the service commands involved.

Verify the address, the route and DNS

Correct YAML proves nothing about the running state. netplan status prints the address, the route and the resolver for each interface, and when I ran it on a machine whose route came from DHCP it reported the physical device in full and marked every container bridge as unmanaged.

netplan status
netplan status --diff

A default route that never landed is the failure that looks healthy from the machine itself, because the interface still answers on its local subnet while every off-network request fails.

ip route show default

Name resolution runs through the systemd-resolved stub on 127.0.0.53, and resolvectl query reports the address it returned and the interface that answered. An answer arriving through an interface you did not configure points at a second Netplan file still holding that device.

resolvectl query example.com

Reachability with the resolver out of the picture is the last check, and it separates a name resolution problem from a routing problem.

ping -c 3 1.1.1.1

When the configuration fails

Each failure below leaves a machine that looks healthy from its own shell. Each one has a command that identifies it before anything is changed.

Recovery from a machine that has already lost its network has one order of operations, and the provider console is the only entry point once the address is wrong.

1. Open the provider console and log in on the local terminal.
2. Compare the device name in the file with the output of ip -brief link.
3. Put back the block that worked, or correct the name, the address and the route.
4. Run netplan try and confirm the settings before the timer runs out.

Keeping a copy of the file that worked takes a second and removes the guesswork from that sequence. That copy ends an outage without diagnosis, which no step above can do.

Pin the interface by MAC so the name stops moving

Names come from the order the firmware enumerates the bus, so a machine that gains a card, moves to a dock, or boots with a different virtual adapter can return with a name that matches nothing in the YAML. Matching the hardware address and setting the name yourself keeps a block attached to the port instead of to the name.

    enp0s6:
      match:
        macaddress: "02:00:17:01:18:67"
      set-name: enp0s6
      dhcp4: true

The hardware address for that block comes from the device itself. The ip -brief link command prints it next to the interface name.

ip -brief link

A config that follows the hardware address follows the port through every rename, which is the one part of the machine that stays put when the kernel renumbers its devices.

Frequently asked questions

The questions below come up often in support threads, with the short answer for each.

The key-by-key reference is the Netplan YAML documentation. The DHCP and static examples come from the Ubuntu Server networking pages.