How to Change Ubuntu Server Main IP Using Netplan (Static IP Assignment)

I. Strategic Overview of Netplan in Modern Ubuntu Server Environments

Modern Ubuntu Server distributions (18.04 LTS and subsequent versions) utilize Netplan as the high-level standard for network configuration, shifting away from legacy methods like ifupdown.¹ Netplan’s primary function is to provide a comprehensive, distribution-agnostic mechanism for defining the desired network state through structured YAML files. This system simplifies network management by acting as an abstraction layer between the administrator and the low-level configuration mechanisms.²

A. Netplan as a Configuration Abstraction Layer

Netplan itself does not directly manage network traffic or interfaces; rather, it functions as a generator that translates the declarative YAML configuration into the native configuration files required by a specific backend utility, known as the renderer.¹ For standard Ubuntu Server environments, the default and typically preferred renderer is systemd-networkd (identified simply as networkd), which manages the network links, addresses, and routing tables.²

This reliance on a renderer mechanism carries significant implications for system maintenance and troubleshooting. While Netplan simplifies the initial setup, administrators must understand this abstraction/backend interplay. If the YAML configuration is syntactically correct but the system fails to establish network connectivity, the troubleshooting focus shifts from Netplan’s configuration parsing to the operational backend. The generated configurations, which can be inspected under /run/netplan/ for the chosen backend, must be analyzed alongside system logs to diagnose deep failures.³ Properly configured files residing in the standard location of /etc/netplan/ are designed to persist across system reboots, ensuring that the defined network state is consistently reapplied upon startup.⁴

Effective network management necessitates careful conflict avoidance. Netplan’s design requires the administrator to specify which renderer is in use. While it is theoretically possible to run multiple network managers, configuring Netplan ensures that the chosen backend (e.g., networkd) takes authoritative control of the specified interfaces. This prevents conflicts, such as those that arise when both NetworkManager and systemd-networkd simultaneously attempt to manage the same device, which can lead to unpredictable behavior and connectivity loss.⁵

B. Network Interface Identification Standards

Before any configuration change can be implemented, the logical name of the target network interface must be accurately determined. Modern Ubuntu systems utilize predictable network interface names, moving beyond the historical, non-persistent eth# convention. These names are often descriptive of the device’s hardware location or bus topology (e.g., eno1, enp0s25, or ens3).²

The foundational tool for identifying interfaces is the ip command. Executing ip a displays a list of all available network interfaces, their link status (UP or DOWN), and any currently assigned IP addresses, including the loopback interface (lo).² Accurate identification is a prerequisite for generating a functional Netplan YAML file. If the network link is found to be administratively down (state OFF or similar indication), the command ip link set <interface> up can be used manually to enable the device link layer, although persistent enablement should be managed through Netplan.⁶

II. Establishing the Foundation: Identifying and Preparing Configuration Files

The integrity and location of the Netplan configuration files are paramount to a successful IP change. Failures often stem from mislocated files or fundamental syntax errors.

A. Configuration File Location and Hierarchy

Netplan configuration files must be stored within the /etc/netplan/ directory and possess the .yaml file extension (e.g., /etc/netplan/config.yaml).¹ Netplan processes these files in alpha-numeric order, dictated by a two-digit priority prefix ranging from 01 through 99.¹

For server administration, especially when modifying network settings, it is best practice to create a new, high-priority configuration file, such as /etc/netplan/99-static-config.yaml.² This approach is favored because it ensures that the customized static settings override any configuration provided by lower-priority files, such as those generated automatically by cloud environments (e.g., 50-cloud-init.yaml). Direct modification of a cloud-generated configuration file is risky, as subsequent actions by the cloud-init utility may overwrite or revert local changes, leading to unexpected network behavior or failure.⁷

B. YAML Syntax and Formatting Strictures

YAML (YAML Ain’t Markup Language) is a human-readable data serialization standard that places stringent requirements on structure and formatting. Network administrators must strictly adhere to these rules, as incorrect formatting is the most frequent cause of Netplan application failure.⁸

The most critical requirement is indentation: YAML relies exclusively on spaces for hierarchy, and the use of tab characters is strictly prohibited.⁸ A seemingly minor syntax error, such as a single misplaced space or a missing colon, will prevent the entire configuration file from being parsed by the Netplan generator, resulting in the failure to apply any network settings and a potential loss of connectivity. This elevated risk demands robust pre-validation and the mandatory use of safety protocols (see Section IV). To aid in preparation, administrators are strongly advised to use dedicated tools such as yamllint before application. The command sudo apt install yamllint can install this tool, which provides line numbers for syntax errors, simplifying the debugging process prior to deployment.¹⁰

III. Definitive Guide to Static IP Configuration using Netplan YAML

The process of configuring a static IP address requires defining the interface, disabling dynamic assignment, specifying the IPv4 address, and establishing routing and name resolution parameters using precise YAML syntax.

A. Static Address and Interface Definition

The configuration file must begin with the header defining the network version and the chosen backend renderer. Version 2 is the currently supported format.¹ While NetworkManager is an option, networkd is the standard and recommended renderer for minimal Ubuntu Server installations.²

network:
  version: 2
  renderer: networkd
  ethernets:
    enp3s0: # Replace enp3s0 with the actual interface name
      dhcp4: false
      addresses:
        - 192.168.1.10/24

The configuration is structured under the ethernets key, followed by the logical name of the interface (e.g., enp3s0). Within the interface block, dhcp4: false must be explicitly set to ensure the interface does not attempt to obtain an address dynamically, thereby committing to the static configuration.⁷ The IP address is assigned using the addresses key, which takes a list of addresses expressed in CIDR notation (e.g., 192.168.1.10/24).⁴ Using a list for the addresses key allows for streamlined binding of multiple secondary or non-primary IP addresses to a single network interface, which is particularly useful for virtual hosting setups.¹³

B. Default Gateway and Routing Management

In Netplan, defining the default gateway is managed via the routes array. It is critical to note that the older, simpler gateway4 key has been deprecated.¹⁰ The modern structure requires defining a route to the destination default (equivalent to 0.0.0.0/0) via the IP address of the gateway.⁴

      routes:
        - to: default
          via: 192.168.1.1

This deliberate shift to the routes array, replacing the deprecated gateway4 syntax, provides greater routing flexibility. This unified structure ensures that administrators can define both simple default routes and complex, multi-path routing configurations (including metric management) through the same interface, preparing the server for advanced networking requirements such as redundant paths or complex traffic engineering.¹⁴

C. Name Resolution Configuration (DNS)

To ensure the server can resolve domain names, the nameservers and any necessary search domains must be statically configured. This is done under the nameservers key.

      nameservers:
        search:
          - "mycompany.local"
        addresses:
          - 192.168.1.2
          - 8.8.8.8

The addresses list defines the IP addresses of the primary and secondary DNS resolvers, while the search list defines the domain suffixes the system should use for unqualified hostname lookups.¹¹

The following table summarizes the essential elements of a static IPv4 configuration:

Table 1: Netplan YAML Template for Static IPv4 Configuration

IV. Ensuring Operational Safety: The Netplan Application Workflow

Changing the IP configuration, especially on a remote server, carries a high risk of permanent lockout if an error is introduced. Netplan provides a critical safety mechanism, netplan try, designed specifically to mitigate this administrative risk.

A. The Safety Protocol: Leveraging netplan try

The netplan try command applies the new configuration temporarily and initiates an interactive session with a default timeout of 120 seconds.¹¹ The purpose of this command is to allow the administrator to confirm that the network changes have not compromised connectivity. If the connection remains stable, the administrator presses ENTER to confirm the configuration, making it permanent. If the connection fails, or if the administrator fails to confirm the change within the specified timeout, the command automatically reverts the network state to the previously working configuration.¹¹

To execute the safety protocol, the administrator runs:

sudo netplan try

A custom timeout period can be specified if needed, particularly for configurations involving protocols like Spanning Tree Protocol (STP) that require longer convergence times: sudo netplan try --timeout 300 (for 5 minutes).¹¹

While the automatic rollback is robust, documentation cautions that administrators must actively verify the reversion after a timeout or cancellation, as known bugs in interaction with certain backends (like NetworkManager) can occasionally interfere with a clean rollback.¹¹ This necessitates a prompt check using ip a following an unconfirmed netplan try. Furthermore, the netplan try command creates a status file (/run/netplan/netplan-try.ready) to manage its state. If the command is abruptly terminated (e.g., due to a hard process kill), this file might persist, leading to subsequent netplan apply attempts failing. In such an event, manual intervention to remove the blocking file may be required to clear the system state.¹⁶

B. Finalizing the Change: netplan apply

Once the configuration has been validated successfully through netplan try, or if the administrator is working via a secure console that is impervious to network failure, the changes are committed permanently using the netplan apply command.⁴

sudo netplan apply

If the application fails or produces unexpected results, a more verbose diagnostic output can be generated using the debug flag: sudo netplan --debug apply. This provides extensive detail regarding how Netplan parses the YAML and interacts with the underlying renderer, which is invaluable for isolating configuration faults.⁹

V. Post-Configuration Verification and Validation

Verification is a multi-layered process, ensuring that the YAML intention has been correctly translated by Netplan, implemented by the backend, and reflected accurately in the kernel’s operational state.

A. Inspecting Kernel State (Low-Level Verification)

The immediate post-application check involves verifying that the kernel has registered the new settings using the iproute2 utility commands.

1. IP Address Confirmation: Use ip a show dev <interface> to confirm that the static IPv4 address and its subnet mask have been bound to the interface and that the link state is UP.²

2. Route Verification: Use ip route show to confirm the successful injection of the default gateway. The output should clearly show an entry similar to default via <gateway IP> dev <interface>, indicating the correct routing table entry.²

B. Confirming Netplan Configuration Integrity

Netplan provides dedicated tools to verify its internal interpretation and the status reported by the backend.

1. Parsed Configuration View: The netplan get command should be used to visualize the complete configuration that Netplan loaded and parsed from the YAML files, including any defaults that were automatically derived or applied. This helps verify that the YAML structure was interpreted as intended, even if the output order or presentation differs slightly from the source file.¹¹

2. Backend Status Summary: The netplan status <interface> command provides a centralized summary of the operational status as reported by the backend renderer. This is a critical verification step, as it consolidates information on the interface’s online state, assigned IP address, active routes, and, crucially, the DNS resolver addresses currently in use by the system.¹¹ This command’s value lies in providing a single source of truth for the entire operational network stack configuration, including name resolution settings that might otherwise require inspecting system-managed files.

C. Testing External Connectivity

The final stage of verification is functional testing. The administrator should confirm reachability to both local and external network resources. A successful ping test to the configured default gateway confirms local segment connectivity. Subsequently, pinging an external IP address (e.g., a known public DNS server) confirms routing functionality. Name resolution must then be validated using tools such as dig or nslookup to ensure the static DNS servers are reachable and correctly resolving external domain names. If the IP address is correctly configured and routes are established but connectivity is still limited, administrators must expand diagnostics to check for external network issues, such as an IP address conflict with another device on the network—a potential failure mode unique to static configurations.⁸

Table 2: Netplan Configuration Application and Verification Commands

VI. Advanced Configuration Scenarios

Netplan is capable of handling complex networking requirements beyond simple static IP assignment, including managing redundant paths and overriding DHCP-provided information.

A. Static DNS Overrides on DHCP-managed Interfaces

In certain scenarios, a server may require its IP address to be dynamically assigned via DHCP, but its DNS resolution must point to specific, static nameservers (e.g., internal directory services). Netplan accommodates this by using the dhcp4-overrides key to explicitly instruct the system to ignore DNS information provided by the DHCP server.

The configuration below ensures the interface eth0 obtains its IP address dynamically, but the locally defined DNS addresses are used for name resolution ¹:

ethernets:
  eth0:
    dhcp4: yes
    dhcp4-overrides:
      use-dns: no
    nameservers:
      addresses: [203.0.113.1, 203.0.113.2]

B. Multi-Homing and Redundant Gateway Configuration

For high availability or complex traffic engineering, systems may require multiple interfaces or multiple default paths. Netplan utilizes route metrics to define the preference for traffic destined for the default gateway. A lower metric value indicates a preferred path.¹⁴

In a scenario involving redundant default routes, the routes array is used to specify multiple default gateways, each associated with a different metric:

ethernets:
  enp5s0:
    dhcp4: yes
    dhcp4-overrides:
      route-metric: 100
  enp6s0:
    dhcp4: yes
    dhcp4-overrides:
      route-metric: 200

In this example, traffic prefers the routes acquired via enp5s0 because it has a lower route metric (100) compared to enp6s0 (200).⁴

Additionally, Netplan supports “on-link” routes, allowing a route to be established via a gateway IP that is directly connected, even if that gateway IP does not reside within the subnet explicitly configured on the interface.¹⁴

  routes:
    - to: default
      via: 9.9.9.9
      on-link: true

VII. Troubleshooting and Failure Remediation

Despite careful preparation, network configuration failures can occur. Effective troubleshooting requires moving systematically through the layers of the network stack, from the configuration abstraction down to the kernel implementation.

A. Diagnosing and Correcting Backend Failures

The first diagnostic step is to differentiate between a YAML parsing error and a backend implementation failure.

If netplan try or netplan apply reports syntax errors, the failure is localized to the Netplan abstraction layer. Administrators must immediately check for incorrect indentation (using tabs instead of spaces), missing colons, or improper data types.⁸ Using yamllint or running netplan --debug apply provides the line number of the error, accelerating correction.¹⁰

If the YAML is syntactically correct but the system fails to connect or apply the configuration successfully, the issue resides with the renderer (e.g., networkd). The administrator must review system logs using the command:

journalctl -xe | grep netplan

This log query filters output for Netplan-related events, revealing messages indicating if the backend failed to implement the generated configuration files (which reside in /run/netplan/).³ A backend failure suggests either an inherent bug in Netplan’s generation logic or an incompatibility between the configuration and the chosen backend.³

B. Restoring Connectivity Post-Failure (Manual Recovery)

In the event of a catastrophic configuration error that leads to the loss of remote connectivity, manual intervention via a console or KVM session is required to restore network access temporarily. This process utilizes the low-level iproute2 utilities, which directly manipulate the kernel’s runtime network state.

The temporary recovery process involves three steps ⁶:

1. Bring the interface link up:sudo ip link set <interface> up
2. Assign the IP address and subnet mask:sudo ip address add <ip address>/24 dev <interface>
3. Set the default route:sudo ip route add default via <gateway> dev <interface>

It is critical to understand the distinction between temporary runtime fixes and persistent configuration. Manual commands executed using ip address add only configure the kernel’s live state and will be lost immediately upon reboot.⁵ Netplan remains the sole source for persistent network configuration. Therefore, after temporary connectivity is restored, the immediate priority must be to correct the flawed YAML file in /etc/netplan/ and successfully run sudo netplan apply.

While rebooting can sometimes clear transient system state issues, a reboot should never be attempted until the administrator has absolutely verified that the corrected YAML configuration on disk is sound and reflects the desired network state. Rebooting with a persistent, flawed configuration will simply guarantee the recurrence of the network failure.¹¹

VIII. Conclusions and Recommendations

The transition of an Ubuntu server to a static IP configuration using Netplan is a standardized, declarative process that requires precision in YAML syntax and strict adherence to safety protocols. Netplan acts as a crucial abstraction layer, simplifying configuration while maintaining compatibility with powerful backends like systemd-networkd.

The most significant administrative recommendation is the mandatory use of sudo netplan try for any configuration change on a remote system. This process, coupled with the administrator’s vigilance in verifying rollback completion, serves as the primary line of defense against network lockout. The deprecation of the gateway4 key reinforces Netplan’s commitment to modern, flexible routing management through the routes array.

Effective management of Netplan requires a diagnostic methodology that moves sequentially through the configuration hierarchy: from syntax validation (yamllint), through high-level state verification (netplan status), and finally, to low-level kernel confirmation (ip a, ip route show). Understanding that the system’s persistent network configuration is solely derived from the YAML files in /etc/netplan/ is paramount, especially when performing manual, non-persistent recovery using iproute2 commands. By following these established procedures, administrators can reliably and safely manage static IP transitions across modern Ubuntu Server deployments.