Netplan is a network configuration utility used by Ubuntu and other Linux distributions. It uses YAML files to define network interfaces, IP addresses, gateways, DNS servers, and routing rules.

Starting with newer Netplan releases, the gateway4 and gateway6 configuration properties have been deprecated in favor of default routes. These properties may still work, but using the routes configuration is the recommended approach.

This guide explains how to update your Netplan configuration, resolve deprecation warnings, and safely apply the changes.

1. Understanding the Warning

When running netplan generate or netplan apply, you may encounter warnings similar to these:

WARNING: `gateway4` has been deprecated, use default routes instead.
WARNING: `gateway6` has been deprecated, use default routes instead.

These warnings indicate that your configuration uses the deprecated gateway4 or gateway6 properties.

For example, an older configuration might look like this:

Old configuration

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
      dhcp6: false
      addresses:
        - 192.168.1.137/24
      gateway4: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8

The configuration defines a static IPv4 address, a default gateway, and a DNS resolver.

To eliminate the deprecation warning, replace gateway4 with a default route.

2. Replace gateway4 with a Default Route

Netplan uses the routes property to define routing rules. A default route directs traffic to destinations for which no more specific route exists.

Updated configuration

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
      dhcp6: false
      addresses:
        - 192.168.1.137/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8

What changed?

The deprecated directive:

gateway4: 192.168.1.1

has been replaced with:

routes:
  - to: default
    via: 192.168.1.1

Here:

• to: default defines the default route.
• via: 192.168.1.1 specifies the gateway used to reach destinations outside directly connected networks.

This configuration preserves the original static IPv4 setup while using the modern Netplan routing syntax.

3. Configure an IPv6 Default Route

The same routing mechanism supports IPv6.

For example, to define an IPv6 default route through a link-local gateway:

routes:
  - to: default
    via: "fe80::1"

However, IPv6 link-local addresses require the appropriate network interface scope. Depending on your environment and Netplan version, you may need to specify the interface explicitly:

routes:
  - to: default
    via: "fe80::1"
    on-link: true

Important: Do not assume that fe80::1 is your actual IPv6 gateway. Verify the gateway address and your network's IPv6 configuration before applying changes.

Also, on-link: true should only be used when the routing configuration requires it; it is not a universal requirement for link-local gateways.

For a dual-stack configuration, IPv4 and IPv6 default routes can be defined together under the same routes section, provided they are valid for the network.

4. Validate and Apply Your Configuration

Before changing network settings on a remote server, make a backup of the existing configuration.

For example:

$ sudo cp -a /etc/netplan /etc/netplan.backup

After editing the appropriate YAML file, generate the configuration to check for errors:

$ sudo netplan generate

If no errors are reported, test the configuration:

$ sudo netplan try

netplan try attempts to apply the configuration and allows you to confirm it. If you do not confirm within the timeout, Netplan attempts to restore the previous configuration.

Once the configuration is verified, apply it:

$ sudo netplan apply

For additional diagnostic output, use:

$ sudo netplan --debug apply

Remote server warning: Network changes can disconnect your SSH session. Keep console access available when possible, and use netplan try before committing potentially disruptive changes.

5. Troubleshooting

If the warnings persist or the network fails to come up, inspect your configuration files:

$ ls -l /etc/netplan/

Search for deprecated gateway directives:

$ grep -R -nE 'gateway4|gateway6' /etc/netplan/

Check the generated network configuration:

$ sudo netplan generate

Inspect the routing table:

$ ip route
$ ip -6 route

Check the status of the network service:

$ systemctl status systemd-networkd

Note that this last command applies when your Netplan configuration uses systemd-networkd as its renderer. Systems using NetworkManager should be diagnosed accordingly.

The gateway4 and gateway6 properties have been deprecated in Netplan in favor of explicit routing configuration.

Replacing them with routes removes the deprecated syntax and makes default routing rules explicit. Before applying changes, validate your YAML, verify your gateway addresses, and take precautions to avoid losing network connectivity.

Best practice: Use the routes configuration for new Netplan setups, and test network changes carefully—especially on remote Linux servers.

We hope this was helpful!