September 11, 2026
10 min read
By Kokil Thapa | Last reviewed: September 2026
Broken SSH after a network edit is one of the fastest ways to lock yourself out of a production VPS. This Ubuntu Netplan Tutorial walks you through Netplan—the default network configuration layer on modern Ubuntu—so you can set static IPs, DHCP, bonds, and bridges without guessing. If you run Ubuntu server setup for Laravel, WordPress, or API workloads, Netplan is the file you touch before Nginx, PHP-FPM, or MySQL ever see traffic. The examples below match what I use on Ubuntu 22.04 and 24.04 LTS servers in Nepal and abroad.
Quick answer: Ubuntu Netplan reads YAML files in
/etc/netplan/, generates backend configs for systemd-networkd or NetworkManager, and applies them with sudo netplan apply. Edit one file, validate syntax, test with netplan try, then apply.What Is Netplan and How Does It Work on Ubuntu?
Netplan is not a network daemon. It is a configuration abstraction that sits between you and the real backend. On Ubuntu Server, that backend is usually systemd-networkd. Desktop installs often use NetworkManager instead. You write human-readable YAML once. Netplan translates it into files the backend understands.
That separation matters in practice. Before Netplan, you edited /etc/network/interfaces on Debian-style systems or chased NetworkManager profiles on desktops. Ubuntu 18.04 and later standardised on Netplan for consistency across cloud images, bare metal, and VMs.
Where Netplan files live
Configuration files belong in /etc/netplan/. Typical names include 00-installer-config.yaml, 50-cloud-init.yaml, or 01-netcfg.yaml. Only .yaml extensions are read. Lexicographic order decides merge priority—later files override earlier ones for the same key.
Check your renderer before editing:
ls -la /etc/netplan/
networkctl status
systemctl is-active NetworkManagerCloud images from AWS, DigitalOcean, Hetzner, and local Nepali hosts often ship a cloud-init file. Read it before you overwrite addresses your provider expects. For broader context, see the Ubuntu network configuration guide.
How Do You Write a Basic Netplan YAML File?
Netplan YAML has three top-level keys you will use daily: network, version, and renderer. Indentation is two spaces. Tabs break parsing. Always back up before editing.
sudo cp /etc/netplan/00-installer-config.yaml /etc/netplan/00-installer-config.yaml.bakA minimal DHCP example for a single interface:
network:
version: 2
renderer: networkd
ethernets:
enp0s3:
dhcp4: true
dhcp6: falseReplace enp0s3 with your interface name from ip link. Names like ens3, eth0, and enp1s0 are common on VPS and bare-metal boxes I maintain for Linux system administration clients.
Validate before apply
Never run netplan apply on a remote server without a safety net. Use this sequence:
sudo netplan --debug generate— catches YAML syntax and schema errors.sudo netplan try— applies temporarily and waits 120 seconds for confirmation.- Press Enter to keep changes, or wait for automatic rollback.
sudo netplan apply— final apply once you are confident.
The official Netplan reference is published at netplan.io/reference. Ubuntu documents server networking at documentation.ubuntu.com/server.
How Do You Configure a Static IP Address with Netplan?
Static IPs are standard on production web servers. Database hosts, mail relays, and firewall rules all expect a fixed address. The pattern below works on a typical /24 LAN or VPS with a known gateway.
network:
version: 2
renderer: networkd
ethernets:
ens3:
dhcp4: false
addresses:
- 192.168.1.50/24
routes:
- to: default
via: 192.168.1.1
nameservers:
addresses:
- 1.1.1.1
- 8.8.8.8
search:
- lan.localUbuntu 22.04 and later prefer routes with to: default instead of the deprecated gateway4 key. Older snippets online still show gateway4. It may work but triggers warnings on current releases.
For a focused walkthrough, read configure a static IP on Ubuntu with Netplan. Pair DNS entries with the Ubuntu DNS configuration guide when debugging resolver issues.
Multiple addresses and secondary NICs
Add extra entries under addresses for secondary IPs. Define each physical NIC under ethernets with its own block. Bonding and VLANs use separate top-level keys covered below.
When Should You Use DHCP vs a Static IP in Netplan?
DHCP suits laptops, temporary staging VMs, and home lab machines. Static IPs suit production servers, database hosts, and anything referenced by firewall rules or A records. The wrong choice causes midnight pages.
| Scenario | Recommended mode | Why |
|---|---|---|
| Cloud VPS with provider firewall | Often DHCP or provider-assigned static via cloud-init | Provider metadata may overwrite manual edits on reboot |
| Self-managed dedicated server | Static IP in Netplan | Predictable SSH, mail, and monitoring targets |
| Local LAN dev box | DHCP with reservation on router | Less YAML churn; still predictable MAC binding |
| Docker or KVM host | Static on primary NIC; bridges for guests | Host must stay reachable while guests get own subnets |
| Legal-tech or eCommerce production | Static plus documented DNS | SSL, webhooks, and payment callbacks need stable endpoints |
On sister sites I deploy with Deployer 7—such as legal portals in the Notary Kathmandu portfolio entry—a bad Netplan edit during migration can cut CI/CD deploys instantly. Always schedule network changes outside peak hours for Nepal business traffic.
How Do You Set Up Bonds, Bridges, and VLANs in Netplan?
Advanced layouts appear on KVM hosts, Proxmox nodes, and servers running multiple containers. Bonds aggregate NICs for redundancy. Bridges connect VMs to the physical LAN. VLANs segment traffic without extra hardware.
Network bond example
network:
version: 2
renderer: networkd
ethernets:
enp2s0:
dhcp4: false
enp3s0:
dhcp4: false
bonds:
bond0:
interfaces: [enp2s0, enp3s0]
parameters:
mode: active-backup
primary: enp2s0
mii-monitor-interval: 100
addresses:
- 10.0.0.10/24
routes:
- to: default
via: 10.0.0.1
nameservers:
addresses: [1.1.1.1]Bridge for KVM or LXD
network:
version: 2
renderer: networkd
ethernets:
enp1s0:
dhcp4: false
bridges:
br0:
interfaces: [enp1s0]
dhcp4: false
addresses:
- 192.168.10.5/24
routes:
- to: default
via: 192.168.10.1
parameters:
stp: false
forward-delay: 0VLAN subinterface
network:
version: 2
renderer: networkd
ethernets:
enp1s0:
dhcp4: false
vlans:
enp1s0.100:
id: 100
link: enp1s0
addresses:
- 10.10.100.2/24Validate YAML structure with the JSON formatter tool only as a mental check—Netplan is YAML, not JSON—but the same indentation discipline applies. Complex hosts benefit from domain registration and hosting planning so IP, DNS, and SSL line up before go-live.
How Do You Troubleshoot Netplan When the Network Breaks?
I've locked myself out twice in fifteen years of server work. Both times involved a wrong gateway on a remote SSH session. Recovery always started at the provider console—not wishful thinking.
Common failure patterns and fixes:
- YAML indentation error —
netplan generateprints the line number. Fix spaces versus tabs. - Wrong interface name — Run
ip linkfrom console. Predictable names neednet.ifnames=0at boot for legacyeth0style. - Gateway on wrong subnet — Address and gateway must share a routable prefix.
- Cloud-init overwrite — Disable or edit
/etc/cloud/cloud.cfg.d/network snippets if changes vanish on reboot. - NetworkManager conflict — Do not mix manual
nmcliedits with Netplan on the same interface. - DNS works but HTTP fails — Check UFW firewall rules after the IP change.
Diagnostic commands
sudo netplan --debug apply
networkctl status ens3
journalctl -u systemd-networkd -b
resolvectl status
ip -br addr
ip route showAfter networking is stable, continue the stack build with Nginx on Ubuntu, PHP on Ubuntu, and MySQL on Ubuntu. For Laravel or Symfony deploys, see Symfony deployment on Ubuntu VPS and Docker on Ubuntu.
Cloud-init and persistent changes
On AWS, GCP, Azure, and many budget VPS panels, cloud-init regenerates Netplan at boot. To make manual static configs stick, either disable network management in cloud-init or edit the cloud-init template directly. The systemd-networkd docs at freedesktop.org systemd.network explain the generated file format if you need to debug at that layer.
What Netplan Mistakes Break Production Servers Most Often?
These errors recur across client servers I touch for support and maintenance:
- Applying on SSH without
netplan tryand no console access. - Using
gateway4on Ubuntu 24.04 instead of modernroutessyntax. - Setting
renderer: NetworkManagerwhile editing a server that actually runs networkd. - Forgetting to disable duplicate configs—two files defining the same interface fight at apply time.
- Changing IP without updating DNS A records, mail SPF paths, or payment webhook allowlists.
- Skipping firewall updates after a subnet move—see server hardening for Ubuntu web servers.
On booking platforms like Adventure Third Pole Trek, uptime during trekking season matters. Document every Netplan change in your runbook alongside Ubuntu server backup strategies.
File permissions matter too. Netplan files should be root-owned and not world-writable. Align with Ubuntu file permissions explained and broader Ubuntu security hardening practices.
Key Takeaways
- Netplan YAML lives in
/etc/netplan/; always back up before editing and confirm your renderer withnetworkctl status. - Use
netplan generate, thennetplan try, thennetplan apply—never apply blind over SSH without console access. - Prefer
routes: [{to: default, via: GATEWAY}]over deprecatedgateway4on Ubuntu 22.04 and 24.04. - Match mode to role: DHCP for transient hosts, static IPs for production web and database servers.
- On cloud VPS instances, check cloud-init so your Netplan changes survive reboot.
- After IP changes, update DNS, firewall rules, and monitoring before closing the maintenance window.
People Also Ask
Does Ubuntu Desktop use Netplan the same way as Ubuntu Server?
Both use Netplan, but desktops often set renderer: NetworkManager while servers default to systemd-networkd. GUI network settings may overwrite YAML on desktop installs. On servers, you typically manage everything through Netplan files and CLI tools.
Where does Netplan write its generated configuration?
For systemd-networkd, generated units appear under /run/systemd/network/ at runtime. NetworkManager gets keyfile snippets under /run/NetworkManager/. You rarely edit these directly—fix the YAML source and regenerate.
Can you use Netplan with Wi-Fi interfaces?
Yes. Define the wireless device under wifis: with access-point name and credentials. Server tutorials focus on Ethernet, but the same apply workflow applies. NetworkManager renderer is common for Wi-Fi on laptops.
What happens if two Netplan files conflict?
Files merge in lexicographic order. Later filenames override earlier keys for the same interface. Keep one authoritative file when possible, or prefix with 01-, 50-, 99- intentionally so priority is obvious.
Put Netplan to Work on Your Next Server
You now have a complete Ubuntu Netplan Tutorial path—from DHCP basics to bonds, bridges, VLANs, and recovery when something goes wrong. Netplan is boring infrastructure until it isn't; the five minutes you spend on netplan try can save hours at a provider console. If you want hands-on help wiring Ubuntu servers for Laravel, WordPress, or client portals, review available services or contact us for deployment support. For day-one server tasks after networking, start with essential Ubuntu terminal commands and the Ubuntu server monitoring guide.
Frequently Asked Questions
Netplan is not a network daemon. It is a YAML configuration layer that sits between you and the real backend—usually systemd-networkd on Ubuntu Server or NetworkManager on desktop installs. You write human-readable config once; Netplan translates it into files the backend understands.
All Netplan YAML lives in /etc/netplan/. Only .yaml extensions are read. Typical names include 00-installer-config.yaml, 50-cloud-init.yaml, and 01-netcfg.yaml. Files merge in lexicographic order, so later filenames override earlier ones for the same key.
netplan apply permanently applies your YAML with no automatic rollback—dangerous over SSH if the gateway or interface name is wrong. netplan try applies changes temporarily and waits 120 seconds for you to press Enter to keep them; otherwise it rolls back automatically. On remote servers I always run sudo netplan --debug generate first to catch syntax errors, then netplan try, and only netplan apply once connectivity is verified. Skipping try is how you end up at the provider console instead of your terminal.
Under ethernets, set dhcp4: false on your interface, add addresses with CIDR notation such as 192.168.1.50/24, define the default route with routes using to: default and via: pointing at your gateway, and list DNS servers under nameservers addresses. Replace the interface name with yours from ip link—ens3, enp0s3, and eth0 are all common on VPS hosts. Back up the file first with sudo cp, validate with netplan generate, test with netplan try, then apply. On Ubuntu 22.04 and 24.04 use routes syntax, not the deprecated gateway4 key.
Static IPs belong on production web servers, database hosts, and anything tied to firewall rules, DNS A records, SSL certificates, or payment webhooks. DHCP suits laptops, temporary staging VMs, and home lab machines where a router reservation gives predictability without YAML churn. Cloud VPS images are a special case: AWS, DigitalOcean, Hetzner, and many Nepali hosts ship cloud-init configs that may overwrite manual edits on reboot. Self-managed dedicated servers should use static Netplan configs. Schedule network changes outside peak hours and keep provider console access ready before you touch anything over SSH.
gateway4 was the old shorthand for a default IPv4 gateway, but Ubuntu 22.04 and later prefer an explicit routes block with to: default and via: set to your gateway IP. Older tutorials still show gateway4 and it may work, but current releases emit warnings and the modern syntax is clearer when you add multiple routes or secondary NICs. When migrating snippets from Debian-style configs or pre-2022 guides, rewrite gateway4 to routes before applying on a live server. Pair the change with netplan generate to confirm the schema accepts your file.
Cloud images from AWS, GCP, Azure, DigitalOcean, Hetzner, and local Nepali hosts often run cloud-init, which regenerates Netplan at boot from templates in /etc/cloud/cloud.cfg.d/. Your manual static IP may look fine until the next restart, then vanish. Read 50-cloud-init.yaml before overwriting addresses the provider expects. To make changes stick, either disable network management in cloud-init or edit the cloud-init network template directly rather than fighting it on every boot. This is one of the first things I check when a client says their static IP worked yesterday but not today.
Recovery starts at the provider console, not by hoping the session reconnects. From console, restore your backup YAML or fix the error—common causes are YAML indentation with tabs instead of spaces, a wrong interface name from ip link, a gateway on the wrong subnet, or cloud-init overwriting your file. Run sudo netplan --debug apply, networkctl status on the interface, journalctl -u systemd-networkd -b, resolvectl status, ip -br addr, and ip route show. If DNS resolves but HTTP fails, check UFW rules after the IP change. Never apply blind over SSH without netplan try and console fallback.
Applying over SSH without netplan try and no console access tops the list—I have locked myself out twice in fifteen years of server work, both times from a wrong gateway. Other repeats: using gateway4 on Ubuntu 24.04 instead of routes syntax, setting renderer: NetworkManager on a server that actually runs systemd-networkd, leaving two Netplan files defining the same interface, changing IP without updating DNS A records or webhook allowlists, and skipping firewall updates after a subnet move. Netplan files should also be root-owned and not world-writable. Document every change in your runbook alongside backup strategy.
Define each physical NIC under ethernets with dhcp4: false, then create a bonds section referencing those interfaces. A typical active-backup bond sets mode: active-backup, names a primary interface, and uses mii-monitor-interval: 100 for link monitoring. Assign addresses, routes, and nameservers on the bond interface itself—not on the member NICs. This pattern appears on KVM hosts, Proxmox nodes, and servers needing NIC redundancy. Validate structure with netplan generate, test with netplan try on console-accessible hardware, then apply. Bonding is advanced layout; get basic static IP networking solid first.
Set the physical NIC to dhcp4: false under ethernets, then define a bridges block with the NIC listed under interfaces. Assign the IP address, default route, and DNS to the bridge—not the raw Ethernet port. Useful parameters include stp: false and forward-delay: 0 for simple KVM or LXD setups where you want VMs on the same LAN as the host. The host must stay reachable on its bridge IP while guests get their own addresses or DHCP from upstream. Always confirm the renderer is networkd on servers, back up existing YAML, and use the standard generate, try, apply sequence.
Both use Netplan, but the defaults differ. Desktop installs often set renderer: NetworkManager and GUI network settings may overwrite YAML you edit by hand. Ubuntu Server typically uses systemd-networkd as the backend, and you manage everything through Netplan files and CLI tools like networkctl status. Before editing any machine, confirm the active renderer with systemctl is-active NetworkManager and networkctl status. Mixing manual nmcli edits with Netplan on the same interface causes conflicts. Server tutorials in this guide assume networkd; adjust your approach if NetworkManager is the active backend.
Netplan merges all .yaml files in /etc/netplan/ in lexicographic order. Later filenames override earlier keys for the same interface, which means 50-cloud-init.yaml can silently trump 00-installer-config.yaml. Duplicate definitions fighting at apply time produce unpredictable results. Keep one authoritative file when possible, or prefix files intentionally with 01-, 50-, and 99- so priority is obvious. Before major edits, run ls -la /etc/netplan/ and read every file—cloud-init snippets are easy to miss and are a common reason manual static IP changes seem to work until the next merge or reboot.
For systemd-networkd, generated units appear under /run/systemd/network/ at runtime. For NetworkManager, keyfile snippets land under /run/NetworkManager/. You rarely edit these directly—fix the source YAML in /etc/netplan/ and regenerate with netplan generate or netplan apply.
Yes. Define the wireless device under a wifis top-level key with the access-point name and credentials. Server-focused tutorials concentrate on Ethernet under ethernets, but the same validate-and-apply workflow applies: back up, run netplan generate, use netplan try on remote systems, then netplan apply. NetworkManager is the common renderer for Wi-Fi on laptops, while Ubuntu Server guides assume wired networkd backends. Check your renderer before editing, because Wi-Fi on desktop installs may also be managed partly through GUI settings that overwrite hand-edited YAML files.
0 Comments
Leave a comment
Your email is not published. Comments appear once they have been read. Sign in to have your details filled in.
