Netplan tutorial

Use this tutorial to learn about basic use of the Netplan utility: how to set up an environment to try it, run it for the first time, check its configuration, and modify its settings.

Trying Netplan in a virtual machine

To try Netplan, you can use a virtual environment, preferably running Ubuntu. This tutorial uses LXD to create virtual networks and launch virtual machines. You can also use a cloud instance or a different hypervisor.

Warning

When using your own system without virtualisation, some of the exercises might interrupt your network connectivity.

Setting up the virtual environment

Follow the steps below to install and create a basic LXD configuration to launch virtual machines (VM). For more information about LXD, visit documentation.ubuntu.com/lxd.

  1. Install LXD: LXD | How to install LXD.

    On Ubuntu, use snap to install LXD:

    snap install lxd

  2. Initialise LXD configuration:

    lxd init --minimal

  3. Create a new network in LXD (some of the exercises require a second network interface in the virtual machine):

    lxc network create netplanbr0 --type=bridge

    The following output confirms the successful creation of the bridge network:

    Network netplanbr0 created

    Now you have a usable LXD installation with a working network bridge.

  4. Create a virtual machine called netplan-lab0:

    lxc init --vm ubuntu:23.10 netplan-lab0

    You should see the output below:

    Creating netplan-lab0

    The new VM has one network interface attached to the default LXD bridge.

  5. Attach the network you created (netplanbr0) to the VM (netplan-lab0) as the eth1 interface:

    lxc network attach netplanbr0 netplan-lab0 eth1

    Tip

    For more on LXD networking, visit LXD | Attach a network to an instance.

  6. Start the new VM:

    lxc start netplan-lab0

  7. Access the new VM using lxc shell:

    lxc shell netplan-lab0

    In case of problems, try running lxc exec netplan-lab0 bash or lxc console netplan-lab0.

    You should now have a root shell inside the VM:

    root@netplan-lab0:~#

  8. Run the ip link command to show the network interfaces:

    ip link

    You should see an output similar to the below:

    1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp5s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
    link/ether 00:16:3e:13:ae:10 brd ff:ff:ff:ff:ff:ff
3: enp6s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff

    In this case:

    • enp5s0 is the primary interface connected to the default LXD network.

    • enp6s0 is the second interface you added connected to your custom network.

You’re ready to start the first exercise.

Running Netplan for the first time

Start by typing the command netplan in your shell:

netplan

You should see the following output:

You need to specify a command
usage: /usr/sbin/netplan  [-h] [--debug]  ...

Network configuration in YAML

options:
  -h, --help  show this help message and exit
  --debug     Enable debug messages

Available commands:

    help      Show this help message
    apply     Apply current Netplan config to running system
    generate  Generate back end specific configuration files from /etc/netplan/*.yaml
    get       Get a setting by specifying a nested key like "ethernets.eth0.addresses", or "all"
    info      Show available features
    ip        Retrieve IP information from the system
    set       Add new setting by specifying a dotted key=value pair like ethernets.eth0.dhcp4=true
    rebind    Rebind SR-IOV virtual functions of given physical functions to their driver
    status    Query networking state of the running system
    try       Try to apply a new Netplan config to running system, with automatic rollback

As you can see, Netplan has a number of sub-commands. Let’s explore some of them.

Showing current Netplan configuration

To show the current configuration, run the netplan get command:

netplan get

You should see an output similar to the one below:

network:
  version: 2
  ethernets:
    enp5s0:
      dhcp4: true

This means:

  • There’s an Ethernet interface called enp5s0.

  • DHCP is enabled for the IPv4 protocol on enp5s0.

Showing current network configuration

Netplan 0.106 introduced the netplan status command. The command displays the current network configuration of the system. Try it by running:

netplan status --all

You should see an output similar to the one below:

     Online state: online
    DNS Addresses: 127.0.0.53 (stub)
       DNS Search: lxd

●  1: lo ethernet UNKNOWN/UP (unmanaged)
      MAC Address: 00:00:00:00:00:00
        Addresses: 127.0.0.1/8
                   ::1/128
           Routes: ::1 metric 256

●  2: enp5s0 ethernet UP (networkd: enp5s0)
      MAC Address: 00:16:3e:13:ae:10 (Red Hat, Inc.)
        Addresses: 10.86.126.221/24 (dhcp)
                   fd42:bc43:e20e:8cf7:216:3eff:fe13:ae10/64
                   fe80::216:3eff:fe13:ae10/64 (link)
    DNS Addresses: 10.86.126.1
                   fe80::216:3eff:feab:beb9
       DNS Search: lxd
           Routes: default via 10.86.126.1 from 10.86.126.221 metric 100 (dhcp)
                   10.86.126.0/24 from 10.86.126.221 metric 100 (link)
                   10.86.126.1 from 10.86.126.221 metric 100 (dhcp, link)
                   fd42:bc43:e20e:8cf7::/64 metric 100 (ra)
                   fe80::/64 metric 256
                   default via fe80::216:3eff:feab:beb9 metric 100 (ra)

●  3: enp6s0 ethernet DOWN (unmanaged)
      MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.)

Checking Netplan configuration files

Netplan configuration is stored in YAML-formatted files in the /etc/netplan directory. To display the contents of the directory, run:

ls -1 /etc/netplan/

Provided your system was initialised using cloud-init, such as the Ubuntu virtual machine recommended for testing Netplan in Trying Netplan in a virtual machine, you can find the initial Netplan configuration in the 50-cloud-init.yaml file:

cat /etc/netplan/50-cloud-init.yaml

You should see an output similar to this:

# This file is generated from information provided by the datasource.  Changes
# to it will not persist across an instance reboot.  To disable cloud-init's
# network configuration capabilities, write a file
# /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg with the following:
# network: {config: disabled}
network:
    version: 2
    ethernets:
        enp5s0:
            dhcp4: true

This configuration file is automatically generated by the cloud-init tool when the system is initialised. As noted in the file comments, direct changes to this file do not persist.

Creating and modifying Netplan configuration

There are two methods to create or modify Netplan configuration:

Using the netplan set command

Example: Using netplan set to enable a network interface with DHCP

Editing the YAML configuration files manually

Example: Editing Netplan YAML files to disable IPv6

Using netplan set to enable a network interface with DHCP

For simple configuration changes, use the netplan set command. In the example below, you are going to create a new YAML file called second-interface.yaml containing only the configuration needed to enable the second network interface.

  1. To create a second network interface called enp6s0, run:

    netplan set --origin-hint second-interface ethernets.enp6s0.dhcp4=true

    The --origin-hint command-line parameter sets the name of the file in which the configuration is stored.

  2. List the files in the directory /etc/netplan:

    ls -1 /etc/netplan

    You should see the auto-generated cloud-init file and a new file called second-interface.yaml:

    50-cloud-init.yaml
second-interface.yaml

  3. Use the command cat to see the file content:

    cat /etc/netplan/second-interface.yaml

    network:
  version: 2
  ethernets:
    enp6s0:
      dhcp4: true

    Notice it is similar to the configuration file generated by cloud-init (Checking Netplan configuration files).

  4. Check the full configuration using netplan get:

    netplan get

    You should see an output similar to the one below with both Ethernet interfaces:

    network:
  version: 2
  ethernets:
    enp5s0:
      dhcp4: true
    enp6s0:
      dhcp4: true

The interface configuration has been created. To apply the changes to the system, follow the instructions in Applying new Netplan configuration.

Editing Netplan YAML files to disable IPv6

For more complex settings, you can edit existing or create new configuration files manually.

For example, to disable automatic IPv6 configuration on the second network interface created in Using netplan set to enable a network interface with DHCP, edit the /etc/netplan/second-interface.yaml file:

  1. Add the following lines to the configuration section of the interface:

    accept-ra: false
link-local: []

    When you finish, the whole configuration in second-interface.yaml should look like this:

    network:
  version: 2
  ethernets:
    enp6s0:
      dhcp4: true
      accept-ra: false
      link-local: []

    With this new configuration, the network configuration back end (systemd-networkd in this case) does not accept Route Advertisements and does not add the link-local address to the interface.

  2. Check the new configuration using the netplan get command:

    netplan get

    You should see something similar to this:

    network:
  version: 2
  ethernets:
    enp5s0:
      dhcp4: true
    enp6s0:
      dhcp4: true
      accept-ra: false
      link-local: []

IPv6 has been disabled for the interface in the configuration. To apply the changes to the system, follow the instructions in Applying new Netplan configuration.

Applying new Netplan configuration

New or modified Netplan settings need to be applied before they take effect on a running system.

Note

Using the netplan set command to modify configuration or editing (creating) the Netplan YAML configuration files directly does not automatically apply the new settings to the running system.

After creating a new configuration as described in Using netplan set to enable a network interface with DHCP, follow these steps to apply the settings and confirm they have taken effect.

  1. Display the current state of the network interface:

    ip address show enp6s0

    Where enp6s0 is the interface you wish to display status for. You should see an output similar to the one below:

    3: enp6s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff

    This interface has no IP address and its state is DOWN.

  2. Apply the new Netplan configuration:

    netplan apply

  3. Check the state of the enp6s0 interface again using one of the following two methods:

    • Using the ip tool:

      ip address show enp6s0

      You should see an output similar to this:

      3: enp6s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
    link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
    inet 10.33.59.157/24 metric 100 brd 10.33.59.255 scope global dynamic enp6s0
       valid_lft 3589sec preferred_lft 3589sec

    • Using the netplan status command:

      netplan status enp6s0

      You should see an output similar to this:

           Online state: online
    DNS Addresses: 127.0.0.53 (stub)
       DNS Search: lxd

●  3: enp6s0 ethernet UP (networkd: enp6s0)
      MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.)
        Addresses: 10.33.59.157/24 (dhcp)
    DNS Addresses: 10.33.59.1
       DNS Search: lxd
           Routes: default via 10.33.59.1 from 10.33.59.157 metric 100 (dhcp)
                   10.33.59.0/24 from 10.33.59.157 metric 100 (link)
                   10.33.59.1 from 10.33.59.157 metric 100 (dhcp, link)

2 inactive interfaces hidden. Use "--all" to show all.

In this tutorial you learned how to set up a learning environment for Netplan using LXD virtual machines, explored Netplan configuration, including its underlying configuration files, and tried the netplan set, netplan get, netplan apply, and netplan status commands. You also used some of the Ethernet configuration options to enable a network interface with DHCP.