Write and Verify Netplan YAML with netplan set

You will use netplan set to write a small, validated YAML change, inspect the file it created, and decide when it is safe to apply that change to a running machine. The installed package here is netplan.io 1.1.2-8ubuntu1~24.04.3. Allow about fifteen minutes for a simple DHCP setting, longer if you need to identify the correct interface.

You need a shell, Netplan installed, and a configuration key that matches your machine. Writing to the real configuration normally requires sudo. The examples use documentation addresses and an interface name that you must replace. Netplan accepts the setting and validates the YAML, but netplan set does not apply networking by itself.

1. Check the installed command

Start with a read-only check. This does not require elevated privileges and confirms the syntax available on this installation:

$ netplan set --help
usage: /usr/sbin/netplan set [-h] [--debug] [--origin-hint ORIGIN_HINT]
                             [--root-dir ROOT_DIR]
                             key_value

The positional argument is one dotted key and value, such as ethernets.enp1s0.dhcp4=true. The installed help also documents null as a value for deleting a key. The manpage describes either a single value or a complete YAML subtree; both forms are written into Netplan's configuration hierarchy.

$ ip link
1: lo: <LOOPBACK,UP,LOWER_UP> ...
2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> ...

2. Write a DHCP setting to a named file

Use --origin-hint to choose a recognisable output file. The hint is turned into a YAML filename under /etc/netplan; it is not a network interface or a profile to apply:

$ sudo netplan set --origin-hint lab-dhcp \
    ethernets.enp1s0.dhcp4=true

On the installed version this creates or updates /etc/netplan/lab-dhcp.yaml. Netplan may also add the top-level network: mapping and version: 2 when it writes the snippet. Inspect the result as root because Netplan configuration files are normally private to root:

$ sudo sed -n '1,80p' /etc/netplan/lab-dhcp.yaml
network:
  version: 2
  ethernets:
    enp1s0:
      dhcp4: true

Do not use a file name already owned by cloud-init or another provisioning system unless you have deliberately chosen that ownership. A separate hint makes the change easier to review and remove. Configuration files are merged according to Netplan's file ordering, so a later file can amend or override an earlier one.

3. Add a list or a subtree

Values can be YAML collections. Quote the whole shell argument so brackets, commas and braces reach Netplan as one value. This example adds addresses to the same interface:

$ sudo netplan set --origin-hint lab-dhcp \
    'ethernets.enp1s0.addresses=[192.0.2.10/24, 2001:db8::10/64]'

A complete subtree is useful when several related keys should be written together. For example, this describes a second interface using DHCP:

$ sudo netplan set --origin-hint second-interface \
    'ethernets.enp2s0={dhcp4: true, dhcp6: true}'

These are configuration changes, not resize or conversion operations. If the value contains shell metacharacters or whitespace, keep the single quotes. Review the generated YAML after each meaningful change rather than building a long command that is hard to audit.

4. Verify the merged configuration before applying it

Read the effective configuration with netplan get:

$ sudo netplan get
network:
  version: 2
  ethernets:
    enp1s0:
      addresses:
      - 192.0.2.10/24
      - 2001:db8::10/64
      dhcp4: true

Your output will include the other files on the machine, and the order may differ. The useful check is that the intended interface and keys appear in the merged view. If Netplan reports an undefined interface, duplicate or conflicting setting, or invalid value, stop there and correct the YAML. Do not apply a configuration that you have not understood.

Safe test option: use an isolated root while experimenting. This writes under a temporary directory rather than the host's /etc/netplan:

$ test_root=$(mktemp -d)
$ mkdir -p "$test_root/etc/netplan"
$ netplan set --root-dir "$test_root" --origin-hint demo \
    ethernets.eth0.dhcp4=true
$ find "$test_root/etc/netplan" -maxdepth 1 -type f -print
/tmp/tmp.XXXXXX/etc/netplan/demo.yaml

--root-dir changes where Netplan reads and writes the configuration root. It is useful for tests and image-building workflows. It does not make a real host configuration active, and it does not bypass validation.

5. Apply only after a network safety check

Writing a file does not change the running network. Applying it can interrupt SSH, change routes, or remove an address, so schedule a maintenance window and keep console access when the change could affect your connection.

For a remotely administered machine, prefer Netplan's temporary test workflow where it is available, and confirm the result before making it permanent:

$ sudo netplan try

If the test is suitable and you confirm it, or if you have an approved change window, apply the stored configuration explicitly:

$ sudo netplan apply
$ ip address show enp1s0
$ netplan status enp1s0

These commands are separate from netplan set. A successful write only proves that Netplan accepted the setting and produced configuration. It does not prove that the renderer brought the interface up or that the route and addresses are correct.

6. Remove a setting or recover a bad file

Before changing an existing snippet, make a root-owned backup if it contains settings you may need. This is an explicit destructive boundary: never remove a file just because its name looks temporary.

$ sudo cp --preserve=all /etc/netplan/lab-dhcp.yaml \
    /etc/netplan/lab-dhcp.yaml.before-change

To remove the DHCP key written above, pass null with the same key and file hint:

$ sudo netplan set --origin-hint lab-dhcp \
    ethernets.enp1s0.dhcp4=null
$ sudo sed -n '1,80p' /etc/netplan/lab-dhcp.yaml

If that snippet contained no other settings, the installed command removes the now-empty generated file. If the change has already been applied, removing the key does not undo the running network until you run sudo netplan try or sudo netplan apply with a valid replacement configuration. If a test fails, restore the backup, run sudo netplan get, and only then consider applying the restored state.

An invalid value should fail without being treated as a successful network change:

$ netplan set --root-dir "$test_root" \
    ethernets.eth0.dhcp4=not-a-bool
Command failed: Error in network definition: invalid boolean value 'not-a-bool'

Use a fresh temporary root for failure tests. Existing invalid files can cause a later command to fail before it reaches the new argument, which can distract from the real error.