Configure a Static IP with Netplan

A comprehensive guide to configuring static IP addresses on Linux using Netplan, covering YAML syntax, common scenarios, DNS, gateways, and troubleshooting.

Netplan, introduced in Ubuntu 17.10, is a YAML-based network configuration abstraction tool designed to simplify network setup across different Linux distributions. It generates configuration files for various renderers like NetworkManager or systemd-networkd, providing a consistent interface for network management. This article details how to configure a static IPv4 address using Netplan, covering essential parameters such as IP addresses, subnet masks, default gateways, and DNS servers.

While Netplan is primarily associated with Ubuntu and its derivatives, its YAML-based approach offers a streamlined way to manage network settings that can be adapted for other systems utilizing compatible network renderers.

Understanding the Netplan Configuration File

Netplan configuration files are typically located in the /etc/netplan/ directory and usually have a .yaml or .yml extension. Multiple files can exist in this directory; Netplan processes them in lexicographical order. The most common filename is 01-netcfg.yaml or a similar numeric prefix to control processing order.

A basic Netplan configuration for a static IP address defines the network interface, its addressing scheme, gateway, and DNS servers. All parameters are case-sensitive and rely on correct indentation, using spaces (never tabs) for hierarchy.

Key YAML Structure Elements

  • network:: The top-level key for all network configurations.
  • version: 2: Specifies the Netplan configuration file format version. Version 2 is the current stable version.
  • renderer:: (Optional) Specifies which backend Netplan should use (e.g., networkd or NetworkManager). If omitted, Netplan often attempts to autodetect or uses networkd by default on server installations.
  • ethernets:: Defines configurations for Ethernet interfaces. Wi-Fi interfaces use wifis:.
  • [interface_name]:: The name of your network interface (e.g., ens33, eth0). You can find this using commands like ip a or ifconfig -a.
  • dhcp4: no: Explicitly disables IPv4 DHCP for this interface. For static IP, this must be no.
  • dhcp6: no: Explicitly disables IPv6 DHCP (optional, but good practice if not used).
  • addresses:: A list of IPv4 or IPv6 addresses with their subnet masks in CIDR notation (e.g., [192.168.1.50/24]). Multiple addresses can be specified.
  • routes:: (Optional) Used for defining static routes, including the default gateway.
  • gateway4:: (Deprecated in Netplan 0.106+, prefer routes:) The default IPv4 gateway address.
  • nameservers:: Configures DNS servers.
  • addresses: (under nameservers:): A list of DNS server IP addresses (e.g., [1.1.1.1, 8.8.8.8]).
  • search: (under nameservers:): A list of domain suffixes to search for hostnames (e.g., [example.com, mycompany.local]).

Example Configuration: Static IPv4

Let's configure a common scenario: assigning a static IPv4 address to an interface named ens33.

# /etc/netplan/01-netcfg.yaml
network:
  version: 2
  renderer: networkd # Explicitly specify systemd-networkd as the renderer
  ethernets:
    ens33:
      dhcp4: no
      dhcp6: no # Disable IPv6 DHCP as well if not using
      addresses: [192.168.1.50/24] # Static IP address with subnet mask (CIDR)
      routes:
        - to: default
          via: 192.168.1.1 # The default gateway
      nameservers:
        addresses: [1.1.1.1, 8.8.8.8, 208.67.222.222] # Primary, secondary, tertiary DNS servers
        search: [home.local, mycorp.com] # Optional: DNS search domains

In this example:

  • The interface ens33 will not obtain an IP address via DHCP.
  • It will be assigned 192.168.1.50 with a subnet mask of 255.255.255.0 (equivalent to /24).
  • The default gateway for outbound traffic will be 192.168.1.1. Note the use of routes: which is the preferred method for defining gateways in recent Netplan versions (0.106+). If you're on an older Netplan version, gateway4: 192.168.1.1 would be used directly under ens33:.
  • DNS queries will first go to Cloudflare (1.1.1.1), then Google (8.8.8.8), then OpenDNS (208.67.222.222).
  • When resolving hostnames like myhost, the system will first try myhost.home.local, then myhost.mycorp.com.

Applying the Configuration

After creating or modifying the Netplan YAML file, two commands are typically used:

  1. Test the configuration: 
    sudo netplan try

    This command attempts to apply the configuration and reverts to the previous working state if connectivity is lost or if there's a syntax error. It provides a 120-second window (default) for you to confirm the changes or for it to automatically roll back.

  2. Apply the configuration permanently: 
    sudo netplan apply

    This command applies the configuration directly. It's recommended to use netplan try first, especially for remote systems, to prevent losing connectivity due to misconfigurations.

You can also generate the backend configuration files without applying them using sudo netplan generate. This can be useful for debugging or inspection.

Verifying the Configuration

After applying the changes, verify that the IP address, gateway, and DNS settings are correctly configured:

  • Check IP address: 
    ip a show ens33

    Look for the inet address corresponding to your static IP.

  • Check default route: 
    ip r

    Verify that the default via entry points to your configured gateway.

  • Check DNS resolvers: 
    cat /run/systemd/resolve/resolv.conf

    On systems using systemd-resolved (common with renderer: networkd), this file contains the effective DNS servers. Alternatively, resolvectl status provides detailed DNS information.

    resolvectl status
  • Test connectivity: 
    ping -c 3 8.8.8.8 # Ping a public IP to test internet connectivity
ping -c 3 stackoverflow.com # Ping a hostname to test DNS resolution

Advanced Configuration Options (Briefly)

Netplan supports various other configurations, including:

  • IPv6 Static Configuration: Similar to IPv4, using addresses: [2001:db8::1/64] and routes: - to: default via: 2001:db8::fe.
  • Bonding (Link Aggregation): Grouping multiple network interfaces for redundancy or increased bandwidth.
  • Bridges: Creating software bridges for virtualization or other networking setups.
  • VLANs: Configuring Virtual Local Area Networks on top of physical interfaces.
  • MAC Address: You can explicitly set the MAC address for an interface using macaddress: 00:1a:2b:3c:4d:5e under the interface definition.

Common Pitfalls and Troubleshooting

  • YAML Syntax Errors: The most common issue. Ensure correct indentation (spaces, not tabs), proper colons, and valid key names. Netplan will usually output an error message indicating the line number if there's a syntax issue during netplan try or netplan apply.
  • Incorrect Interface Name: Double-check the interface name (e.g., ens33, eth0) using ip a. Typos will prevent the configuration from applying.
  • Conflicting Configurations: If you have multiple Netplan files, ensure they don't define the same interface with conflicting settings. The last processed file (lexicographically) typically wins for overlapping settings. Also, ensure no old /etc/network/interfaces configurations are active if you're transitioning.
  • gateway4 vs. routes: Be aware of the Netplan version. If you are on Netplan 0.106 or newer, use the routes: syntax for the default gateway. Older versions use gateway4: directly under the interface. Using the wrong one can lead to no default route.
  • DNS Not Working: Verify nameservers: addresses: are correct and reachable. Check /run/systemd/resolve/resolv.conf or resolvectl status for the actual resolvers being used. Firewalls might block DNS traffic (UDP port 53).
  • Permissions: Ensure the YAML file has appropriate permissions (e.g., -rw-r--r--, owned by root) to prevent accidental modification or security issues.
  • NetworkManager vs. systemd-networkd: If you're on a desktop system, renderer: NetworkManager might be more appropriate. For servers, renderer: networkd is standard. Using the wrong renderer can lead to unexpected behavior or configurations not being applied.

Back to the knowledge base · Ask the AI assistant