From 3ee377f476d081f5928400262fb1544d89a87082 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Thu, 18 Apr 2024 18:25:36 +0200 Subject: [PATCH] Tutorial reorg & lang. + formatting improvements. --- doc/creating-link-aggregation.md | 86 +++ doc/howto.md | 40 +- doc/matching-interface-by-mac-address.md | 85 +++ doc/netplan-tutorial.md | 772 +++++++---------------- doc/netplan-yaml.md | 2 +- doc/tutorial.md | 2 + doc/using-static-ip-addresses.md | 128 ++++ 7 files changed, 567 insertions(+), 548 deletions(-) create mode 100644 doc/creating-link-aggregation.md create mode 100644 doc/matching-interface-by-mac-address.md create mode 100644 doc/using-static-ip-addresses.md diff --git a/doc/creating-link-aggregation.md b/doc/creating-link-aggregation.md new file mode 100644 index 000000000..2543d0052 --- /dev/null +++ b/doc/creating-link-aggregation.md @@ -0,0 +1,86 @@ +# How to create link aggregation + +:::{note} +These instructions assume a system setup based on the example configuration outlined in the [Netplan tutorial](/netplan-tutorial). +::: + +Let's suppose now that you need to configure your system to connect to your +ISP links via a link aggregation. On Linux you can do that with a `bond` +virtual interface. + +On Netplan, an interface of type `bond` can be created inside a `bonds` mapping. + +Now that the traffic will flow through the link aggregation, you will move +all the addressing configuration to the bond itself. + +You can define a list of interfaces that will be attached to the bond. In our +simple scenario, we have a single one. + +Edit the file `/etc/netplan/second-interface.yaml` and make the following changes: + +```yaml +network: + version: 2 + ethernets: + netplan-isp-interface: + dhcp4: false + dhcp6: false + match: + macaddress: 00:16:3e:0c:97:8a + set-name: netplan-isp + bonds: + isp-bond0: + interfaces: + - netplan-isp-interface + dhcp4: false + dhcp6: false + accept-ra: false + link-local: [] + addresses: + - 172.16.0.1/24 + routes: + - to: default + via: 172.16.0.254 + nameservers: + search: + - netplanlab.local + addresses: + - 172.16.0.254 + - 172.16.0.253 +``` + +Note that you can reference the interface used in the bond by the name you +defined for it in the `ethernets` section. + +Now use `netplan apply` to apply your changes + +``` +netplan apply +``` + +Now your system has a new interface called `isp-bond0`. Use the command +`ip address show isp-bond0` or `netplan status` to check its state: + +``` +netplan status isp-bond0 +``` + +You should see an output similar to the one below: + +``` + Online state: online + DNS Addresses: 127.0.0.53 (stub) + DNS Search: lxd + netplanlab.local + +● 4: isp-bond0 bond UP (networkd: isp-bond0) + MAC Address: b2:6b:19:b1:9a:86 + Addresses: 172.16.0.1/24 + DNS Addresses: 172.16.0.254 + 172.16.0.253 + DNS Search: netplanlab.local + Routes: default via 172.16.0.254 (static) + 172.16.0.0/24 from 172.16.0.1 (link) + +3 inactive interfaces hidden. Use "--all" to show all. +``` diff --git a/doc/howto.md b/doc/howto.md index 83850900b..326ec1153 100644 --- a/doc/howto.md +++ b/doc/howto.md @@ -1,28 +1,40 @@ # How-to guides -Below is a collection of how-to guides for common scenarios. -If you see a scenario missing or have one to contribute, please, -[file a bug](https://bugs.launchpad.net/netplan/+filebug) against this -documentation with the example. +This is a collection of how-to guides for common scenarios. If you see a scenario missing or have one to contribute, [file an issue](https://bugs.launchpad.net/netplan/+filebug) against this documentation with the example. -To configure Netplan, save configuration files in the `/etc/netplan/` directory -with a `.yaml` extension (e.g. `/etc/netplan/config.yaml`), then run -`sudo netplan apply`. This command parses and applies the configuration to the -system. Configuration written to disk under `/etc/netplan/` persists between -reboots. +To configure Netplan, save configuration files in the `/etc/netplan/` directory with a `.yaml` extension (e.g. `/etc/netplan/config.yaml`), then run `sudo netplan apply`. This command parses and applies the configuration to the system. Configuration written to disk under `/etc/netplan/` persists between reboots. Visit [Applying new Netplan configuration](/netplan-tutorial.md#applying-new-netplan-configuration) for detailed guidance. -For each of the example below, use the `renderer` that applies to your scenario. -For example, for Ubuntu Desktop the `renderer` is usually `NetworkManager`, -and `networkd` for Ubuntu Server. +For each of the examples below, use the `renderer` that applies to your scenario. For example, for Ubuntu Desktop, the `renderer` is usually `NetworkManager`. For Ubuntu Server, it is `networkd`. -Also, see [/examples](https://github.com/canonical/netplan/tree/main/examples) -on GitHub. + +## Quick configuration examples ```{toctree} :maxdepth: 1 examples +``` + +YAML configuration snippets for these examples, as well as additional examples, are available in the [examples](https://github.com/canonical/netplan/tree/main/examples) directory on GitHub. + + +## Complex how-to guides + +```{toctree} +:maxdepth: 1 + +using-static-ip-addresses +matching-interface-by-mac-address +creating-link-aggregation dbus-config netplan-everywhere +``` + + +## Documentation + +```{toctree} +:maxdepth: 1 + contribute-docs ``` diff --git a/doc/matching-interface-by-mac-address.md b/doc/matching-interface-by-mac-address.md new file mode 100644 index 000000000..916cef31b --- /dev/null +++ b/doc/matching-interface-by-mac-address.md @@ -0,0 +1,85 @@ +# How to match the interface by MAC address + +:::{note} +These instructions assume a system setup based on the example configuration outlined in the [Netplan tutorial](/netplan-tutorial). +::: + +Sometimes you can't rely on the interface names to apply configuration to them. Changes in the system might cause a change in their names, such as when you move an interface card from a PCI slot to another. + +In this exercise you will use the `match` keyword to locate the device based on its MAC address and also set a more meaningful name to the interface. + +Let's assume that your second interface is connected to the Netplan ISP internet provider company and you want to identify it as such. + +First identify its MAC address: + +``` +ip link show enp6s0 +``` + +In the output, the MAC address is the number in front of the `link/ether` property. +``` +3: enp6s0: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000 + link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff +``` + +Edit the file `/etc/netplan/second-interface.yaml` and make the following changes: + +```yaml +network: + version: 2 + ethernets: + netplan-isp-interface: + match: + macaddress: 00:16:3e:0c:97:8a + set-name: netplan-isp + dhcp4: false + dhcp6: false + accept-ra: false + link-local: [] + addresses: + - 172.16.0.1/24 + routes: + - to: default + via: 172.16.0.254 + nameservers: + search: + - netplanlab.local + addresses: + - 172.16.0.254 + - 172.16.0.253 +``` + +These are the important changes in this exercise: + +```yaml + ethernets: + netplan-isp-interface: + match: + macaddress: 00:16:3e:0c:97:8a + set-name: netplan-isp +``` + +Note that, as you are now matching the interface by its MAC address, you are free to identify it with a different name. It makes it easier to read and find information in the YAML file. + +After changing the file, apply your new configuration: + +``` +netplan apply +``` + +Now list your interfaces: + +``` +ip link show +``` + +As you can see, your interface is now called `netplan-isp`. + +``` +1: lo: 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: 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: netplan-isp: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000 + link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff +``` diff --git a/doc/netplan-tutorial.md b/doc/netplan-tutorial.md index ef4ebbcf9..9df480e75 100644 --- a/doc/netplan-tutorial.md +++ b/doc/netplan-tutorial.md @@ -1,108 +1,119 @@ -# Pre-requisites +# Netplan tutorial -In order to do the exercises yourself you will need a virtual machine, preferably running Ubuntu. In this tutorial, we will use LXD to create virtual networks and launch virtual machines. Feel free to use a cloud instance or a different hypervisor. As long as you can achieve the same results, you should be fine. If you're going to use your own desktop/laptop system, some of the exercises might interrupt your network connectivity. +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. -If you already have a setup where you can do the exercises you can just skip this section. -## Setting up the environment +# Trying Netplan in a virtual machine -You can follow the steps below to install and create a basic LXD configuration you can use to launch virtual machines. +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. -For more information about LXD, please visit [linuxcontainers.org](https://documentation.ubuntu.com/lxd/). +:::{warning} +When using your own system without virtualisation, some of the exercises might interrupt your network connectivity. +::: -First, install LXD: [LXD | How to install LXD](https://documentation.ubuntu.com/lxd/en/latest/installing/) -On Ubuntu, you can install it using `snap`: +## Setting up the virtual environment -``` -snap install lxd -``` +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](https://documentation.ubuntu.com/lxd/). -Now, initialise your LXD configuration: +1. Install LXD: [LXD | How to install LXD](https://documentation.ubuntu.com/lxd/en/latest/installing/). -``` -lxd init --minimal -``` + On Ubuntu, use `snap` to install LXD: -Run the command below to create a new network in LXD. For some of the exercises you will need a second network interface in your virtual machine. + ``` + snap install lxd + ``` -``` -lxc network create netplanbr0 --type=bridge -``` +2. Initialise LXD configuration: -You should see the output below: + ``` + lxd init --minimal + ``` -``` -Network netplanbr0 created -``` +3. Create a new network in LXD (some of the exercises require a second network interface in the virtual machine): -At this point you should have a usable LXD installation with a working network bridge. + ``` + lxc network create netplanbr0 --type=bridge + ``` -Now create a virtual machine called `netplan-lab0`: + The following output confirms the successful creation of the bridge network: -``` -lxc init --vm ubuntu:22.04 netplan-lab0 -``` + ``` + Network netplanbr0 created + ``` -You should see the output below: + Now you have a usable LXD installation with a working network bridge. -``` -Creating netplan-lab0 -``` +4. Create a virtual machine called `netplan-lab0`: -The new VM will have one network interface attached to the default LXD bridge. + ```none + lxc init --vm ubuntu:23.10 netplan-lab0 + ``` -Now attach the network you created just now, `netplanbr0`, to your VM, `netplan-lab0`, as interface `eth1`: + You should see the output below: -``` -lxc network attach netplanbr0 netplan-lab0 eth1 -``` + ``` + Creating netplan-lab0 + ``` -> See more: [LXD | Attach a network to an instance](https://documentation.ubuntu.com/lxd/en/latest/howto/network_create/#attach-a-network-to-an-instance) + The new VM has one network interface attached to the default LXD bridge. -And start your new VM: +5. Attach the network you created (`netplanbr0`) to the VM (`netplan-lab0`) as the `eth1` interface: -``` -lxc start netplan-lab0 -``` + ``` + lxc network attach netplanbr0 netplan-lab0 eth1 + ``` -Access your new VM using `lxc shell`: + :::{tip} + For more on LXD networking, visit [LXD | Attach a network to an instance](https://documentation.ubuntu.com/lxd/en/latest/howto/network_create/#attach-a-network-to-an-instance). + ::: -``` -lxc shell netplan-lab0 -``` +6. Start the new VM: -> **If this doesn't work for you**: Try instead `lxc exec netplan-lab0 bash` or `lxc console netplan-lab0`. + ``` + lxc start netplan-lab0 + ``` -You should now have a root shell inside your VM: +7. Access the new VM using `lxc shell`: -``` -root@netplan-lab0:~# -``` + ``` + lxc shell netplan-lab0 + ``` -Run the command `ip link` to show your network interfaces: + In case of problems, try running `lxc exec netplan-lab0 bash` or `lxc console netplan-lab0`. -``` -ip link -``` + You should now have a root shell inside the VM: -You should see an output similar to the below: + ```none + root@netplan-lab0:~# + ``` -``` -1: lo: 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: 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: 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 -``` +8. Run the `ip link` command to show the network interfaces: + + ``` + ip link + ``` + + You should see an output similar to the below: + + ```none + 1: lo: 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: 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: 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 and `enp6s0` is the second interface you added connected to your custom network. + 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. -Now, let's start with a simple exercise. +You're ready to start the first exercise. -# Running netplan for the first time + +# Running Netplan for the first time Start by typing the command `netplan` in your shell: @@ -110,9 +121,9 @@ Start by typing the command `netplan` in your shell: netplan ``` -You should see the output below +You should see the following output: -``` +```none You need to specify a command usage: /usr/sbin/netplan [-h] [--debug] ... @@ -136,11 +147,12 @@ Available commands: 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. +As you can see, Netplan has a number of sub-commands. Let's explore some of them. + -# Showing your current Netplan configuration +# Showing current Netplan configuration -To show your current configuration, run the command `netplan get`. +To show the current configuration, run the `netplan get` command: ``` netplan get @@ -148,7 +160,6 @@ netplan get You should see an output similar to the one below: - ```yaml network: version: 2 @@ -157,16 +168,17 @@ network: dhcp4: true ``` -It shows you have an Ethernet interface called `enp5s0` and it has DHCP enabled for IPv4. +This means: +* There's an Ethernet interface called `enp5s0`. +* DHCP is enabled for the IPv4 protocol on `enp5s0`. -# Showing your current network configuration -Netplan 0.106 introduced the `netplan status` command. You can use it to -show your system's current network configuration. Try that by typing -`netplan status --all` in your console: +# 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: + +```none netplan status --all ``` @@ -202,11 +214,18 @@ You should see an output similar to the one below: MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.) ``` -# Checking the file where your configuration is stored -The configuration you just listed is stored at `/etc/netplan`. You can see the contents of the file with the command below: +# 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: +```none +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](#trying-netplan-in-a-virtual-machine), you can find the initial Netplan configuration in the `50-cloud-init.yaml` file: + +```none cat /etc/netplan/50-cloud-init.yaml ``` @@ -225,518 +244,205 @@ network: dhcp4: true ``` -This file was automatically generated by `cloud-init` when the system was initialised. As noted in the comments, changes to this file will not persist. +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. -# Enabling your second network interface with DHCP -There are basically 2 ways to create or change Netplan configuration: +# Creating and modifying Netplan configuration -1) Using the `netplan set` command -2) Editing the YAML files manually +There are two methods to create or modify Netplan configuration: -Let's see how you can enable your second network interface using both ways. +Using the `netplan set` command +: Example: [Using netplan set to enable a network interface with DHCP](#using-netplan-set-to-enable-a-network-interface-with-dhcp) -## Using `netplan set` +Editing the YAML configuration files manually +: Example: [Editing Netplan YAML files to disable IPv6](#editing-netplan-yaml-files-to-disable-ipv6) -For simple tasks, you can use `netplan set` to change your configuration. -In the example below you are going to create a new YAML file called `second-interface.yaml` containing only the configuration needed to enable our second interfaces. +## Using `netplan set` to enable a network interface with DHCP -Considering your second network interface is `enp6s0`, run the command below: +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. -``` -netplan set --origin-hint second-interface ethernets.enp6s0.dhcp4=true -``` +1. To create a second network interface called `enp6s0`, run: -The command line parameter `--origin-hint` sets the name of the file where the configuration will be stored. + ``` + netplan set --origin-hint second-interface ethernets.enp6s0.dhcp4=true + ``` -Now list the files in the directory `/etc/netplan`: + The `--origin-hint` command-line parameter sets the name of the file in which the configuration is stored. -``` -ls /etc/netplan -``` +2. List the files in the directory `/etc/netplan`: -You should see the auto generated `cloud-init` file and a new file called `second-interface.yaml`: + ```none + ls -1 /etc/netplan + ``` -``` -root@netplan-lab0:~# ls /etc/netplan/ -50-cloud-init.yaml second-interface.yaml -``` - -Use the command `cat` to see its content: - -``` -cat /etc/netplan/second-interface.yaml -``` - -```yaml -network: - version: 2 - ethernets: - enp6s0: - dhcp4: true -``` - -You will notice it is very similar to the one generated by `cloud-init`. - -Now use `netplan get` to see your full configuration: - -``` -netplan get -``` + You should see the auto-generated `cloud-init` file and a new file called `second-interface.yaml`: -You should see an output similar to the one below with both Ethernet interfaces: + ```none + 50-cloud-init.yaml + second-interface.yaml + ``` -```yaml -network: - version: 2 - ethernets: - enp5s0: - dhcp4: true - enp6s0: - dhcp4: true -``` +3. Use the command `cat` to see the file content: -## Applying your new configuration + ``` + cat /etc/netplan/second-interface.yaml + ``` -The command `netplan set` created the configuration for your second network interface but it wasn't applied to the running system. + ```yaml + network: + version: 2 + ethernets: + enp6s0: + dhcp4: true + ``` -Run the command below to see the current state of your second network interface: + Notice it is similar to the configuration file generated by `cloud-init` ([Checking Netplan configuration files](#checking-netplan-configuration-files)). -``` -ip address show enp6s0 -``` +4. Check the full configuration using `netplan get`: -You should see an output similar to the one below: + ``` + netplan get + ``` -``` -3: enp6s0: 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 -``` + You should see an output similar to the one below with both Ethernet interfaces: -As you can see, this interface has no IP address and its state is DOWN. + ```yaml + network: + version: 2 + ethernets: + enp5s0: + dhcp4: true + enp6s0: + dhcp4: true + ``` -In order to apply the Netplan configuration, you can use the command `netplan apply`. +The interface configuration has been created. To apply the changes to the system, follow the instructions in [Applying new Netplan configuration](#applying-new-netplan-configuration). -Run the command below in your shell: -``` -netplan apply -``` +## Editing Netplan YAML files to disable IPv6 -Now check again the state of the interface `enp6s0`: +For more complex settings, you can edit existing or create new configuration files manually. -``` -ip address show enp6s0 -``` +For example, to disable automatic IPv6 configuration on the second network interface created in [Using netplan set to enable a network interface with DHCP](#using-netplan-set-to-enable-a-network-interface-with-dhcp), edit the `/etc/netplan/second-interface.yaml` file: -You should see an output similar to this: +1. Add the following lines to the configuration section of the interface: -``` -3: enp6s0: 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 - inet6 fd42:ee65:61d0:abcb:216:3eff:fe0c:978a/64 scope global dynamic mngtmpaddr noprefixroute - valid_lft 3599sec preferred_lft 3599sec - inet6 fe80::216:3eff:fe0c:978a/64 scope link - valid_lft forever preferred_lft forever -``` + ```yaml + accept-ra: false + link-local: [] + ``` -You can also use `netplan status` to check the interface: + When you finish, the whole configuration in `second-interface.yaml` should look like this: -``` -netplan status enp6s0 -``` + ```yaml + network: + version: 2 + ethernets: + enp6s0: + dhcp4: true + accept-ra: false + link-local: [] + ``` -You should see an output similar to this: + 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. -``` - Online state: online - DNS Addresses: 127.0.0.53 (stub) - DNS Search: lxd +2. Check the new configuration using the `netplan get` command: -● 3: enp6s0 ethernet UP (networkd: enp6s0) - MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.) - Addresses: 10.33.59.157/24 (dhcp) - fd42:ee65:61d0:abcb:216:3eff:fe0c:978a/64 - fe80::216:3eff:fe0c:978a/64 (link) - DNS Addresses: 10.33.59.1 - fe80::216:3eff:fea1:585b - 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) - fd42:ee65:61d0:abcb::/64 metric 100 (ra) - fe80::/64 metric 256 + ``` + netplan get + ``` -2 inactive interfaces hidden. Use "--all" to show all. -``` + You should see something similar to this: -As you can see, even though you haven't enabled DHCP for IPv6 on this interface, the network configuration back end (in this case systemd-networkd) enabled it anyway. But let's assume you want only IPv4. + ```yaml + network: + version: 2 + ethernets: + enp5s0: + dhcp4: true + enp6s0: + dhcp4: true + accept-ra: false + link-local: [] + ``` -Let's address this situation in the next exercise. +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). -## Editing YAML files -For more complex configuration, you can just create or edit a new file yourself using your favourite text editor. +# Applying new Netplan configuration -Continuing the exercise from the previous section, let's go ahead and disable automatic IPv6 configuration on your second interface. But this time let's do it by manually editing the YAML file. +New or modified Netplan settings need to be applied before they take effect on a running system. -Use your favourite text editor and open the file `/etc/netplan/second-interface.yaml`. +:::{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. +::: -Add the configuration below to the interface configuration section: +After creating a new configuration as described in [Using netplan set to enable a network interface with DHCP](#using-netplan-set-to-enable-a-network-interface-with-dhcp), follow these steps to apply the settings and confirm they have taken effect. -```yaml -accept-ra: false -link-local: [] -``` +1. Display the current state of the network interface: -When you finish, it should look like this: + ``` + ip address show enp6s0 + ``` -```yaml -network: - version: 2 - ethernets: - enp6s0: - dhcp4: true - accept-ra: false - link-local: [] -``` + Where `enp6s0` is the interface you wish to display status for. You should see an output similar to the one below: -With this new configuration, the network configuration back end (systemd-networkd in this case) will not accept Route Advertisements and will not add the link-local address to our interface. + ```none + 3: enp6s0: 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 + ``` -Now check your new configuration with the `netplan get` command: + This interface has no IP address and its state is `DOWN`. -``` -netplan get -``` +2. Apply the new Netplan configuration: -You should see something similar to this: + ``` + netplan apply + ``` -```yaml -network: - version: 2 - ethernets: - enp5s0: - dhcp4: true - enp6s0: - dhcp4: true - accept-ra: false - link-local: [] -``` +3. Check the state of the `enp6s0` interface again using one of the following two methods: -Now use `netplan apply` to apply your new configuration: + * Using the `ip` tool: -``` -netplan apply -``` + ``` + ip address show enp6s0 + ``` -And check your interface configuration: + You should see an output similar to this: -``` -ip address show enp6s0 -``` + ```none + 3: enp6s0: 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 + ``` -You should see an output similar to this: + * Using the `netplan status` command: -``` -3: enp6s0: 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 3585sec preferred_lft 3585sec -``` + ``` + netplan status enp6s0 + ``` -And as you can see, now it only has an IPv4 address. + You should see an output similar to this: -In this exercise you explored the `netplan set`, `netplan get`, `netplan apply` and `netplan status` commands. You also used some of the Ethernet configuration options to get a network interface up and running with DHCP. + ``` + Online state: online + DNS Addresses: 127.0.0.53 (stub) + DNS Search: lxd -# Using static IP addresses + ● 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) -In this exercise you're going to add an static IP address to the second interface with a default route and DNS configuration. + 2 inactive interfaces hidden. Use "--all" to show all. + ``` -Edit the file `/etc/netplan/second-interface.yaml` created previously. Change it so it will look like this: +--- -```yaml -network: - version: 2 - ethernets: - enp6s0: - dhcp4: false - dhcp6: false - accept-ra: false - link-local: [] - addresses: - - 172.16.0.1/24 - routes: - - to: default - via: 172.16.0.254 - nameservers: - search: - - netplanlab.local - addresses: - - 172.16.0.254 - - 172.16.0.253 -``` - -The configuration above is what you'd expect in a desktop system for example. It defines the interface's IP address statically as `172.16.0.1/24`, a default route via gateway `172.16.0.254` and the DNS search domain and name servers. - -Now use `netplan get` to visualise all your network configuration: - -``` -netplan get -``` - -You should see an output similar to this: - -```yaml -network: - version: 2 - ethernets: - enp5s0: - dhcp4: true - enp6s0: - addresses: - - "172.16.0.1/24" - nameservers: - addresses: - - 172.16.0.254 - - 172.16.0.253 - search: - - netplanlab.local - dhcp4: false - dhcp6: false - accept-ra: false - routes: - - to: "default" - via: "172.16.0.254" - link-local: [] -``` - -You will notice that it might be a little different than what you have defined in the YAML file. Some things might be in a different order for example. - -The reason for that is that `netplan get` loads and parses your configuration before outputting it, and the YAML parsing engine used by Netplan might shuffle things around. Although, what you see from `netplan get` is equivalent to what you have in the file. - -Now use `netplan apply` to apply the new configuration: - -``` -netplan apply -``` - -And check the interface's new state: - -``` -ip address show dev enp6s0 -``` - -You should see something similar to this: -``` -3: enp6s0: 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 172.16.0.1/24 brd 172.16.0.255 scope global enp6s0 - valid_lft forever preferred_lft forever -``` - -Check the routes associated to the interface: - -``` -ip route show dev enp6s0 -``` - -You should see something similar to this: - -``` -default via 172.16.0.254 proto static -172.16.0.0/24 proto kernel scope link src 172.16.0.1 -``` - -And check the DNS configuration: - -``` -netplan status enp6s0 -``` - -You should see something similar to this: - -``` - Online state: online - DNS Addresses: 127.0.0.53 (stub) - DNS Search: netplanlab.local - lxd - -● 3: enp6s0 ethernet UP (networkd: enp6s0) - MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.) - Addresses: 172.16.0.1/24 - DNS Addresses: 172.16.0.254 - 172.16.0.253 - DNS Search: netplanlab.local - Routes: default via 172.16.0.254 (static) - 172.16.0.0/24 from 172.16.0.1 (link) - -2 inactive interfaces hidden. Use "--all" to show all. -``` - -# Matching the interface by MAC address - -Sometimes you can't rely on the interface names to apply configuration to them. Changes in the system might cause a change in their names, such as when you move an interface card from a PCI slot to another. - -In this exercise you will use the `match` keyword to locate the device based on its MAC address and also set a more meaningful name to the interface. - -Let's assume that your second interface is connected to the Netplan ISP internet provider company and you want to identify it as such. - -First identify its MAC address: - -``` -ip link show enp6s0 -``` - -In the output, the MAC address is the number in front of the `link/ether` property. -``` -3: enp6s0: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000 - link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff -``` - -Edit the file `/etc/netplan/second-interface.yaml` and make the following changes: - -```yaml -network: - version: 2 - ethernets: - netplan-isp-interface: - match: - macaddress: 00:16:3e:0c:97:8a - set-name: netplan-isp - dhcp4: false - dhcp6: false - accept-ra: false - link-local: [] - addresses: - - 172.16.0.1/24 - routes: - - to: default - via: 172.16.0.254 - nameservers: - search: - - netplanlab.local - addresses: - - 172.16.0.254 - - 172.16.0.253 -``` - -These are the important changes in this exercise: - -```yaml - ethernets: - netplan-isp-interface: - match: - macaddress: 00:16:3e:0c:97:8a - set-name: netplan-isp -``` - -Note that, as you are now matching the interface by its MAC address, you are free to identify it with a different name. It makes it easier to read and find information in the YAML file. - -After changing the file, apply your new configuration: - -``` -netplan apply -``` - -Now list your interfaces: - -``` -ip link show -``` - -As you can see, your interface is now called `netplan-isp`. - -``` -1: lo: 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: 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: netplan-isp: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000 - link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff -``` - -# Creating a link aggregation - -Let's suppose now that you need to configure your system to connect to your -ISP links via a link aggregation. On Linux you can do that with a `bond` -virtual interface. - -On Netplan, an interface of type `bond` can be created inside a `bonds` mapping. - -Now that the traffic will flow through the link aggregation, you will move -all the addressing configuration to the bond itself. - -You can define a list of interfaces that will be attached to the bond. In our -simple scenario, we have a single one. - -Edit the file `/etc/netplan/second-interface.yaml` and make the following changes: - -```yaml -network: - version: 2 - ethernets: - netplan-isp-interface: - dhcp4: false - dhcp6: false - match: - macaddress: 00:16:3e:0c:97:8a - set-name: netplan-isp - bonds: - isp-bond0: - interfaces: - - netplan-isp-interface - dhcp4: false - dhcp6: false - accept-ra: false - link-local: [] - addresses: - - 172.16.0.1/24 - routes: - - to: default - via: 172.16.0.254 - nameservers: - search: - - netplanlab.local - addresses: - - 172.16.0.254 - - 172.16.0.253 -``` - -Note that you can reference the interface used in the bond by the name you -defined for it in the `ethernets` section. - -Now use `netplan apply` to apply your changes - -``` -netplan apply -``` - -Now your system has a new interface called `isp-bond0`. Use the command -`ip address show isp-bond0` or `netplan status` to check its state: - -``` -netplan status isp-bond0 -``` - -You should see an output similar to the one below: - -``` - Online state: online - DNS Addresses: 127.0.0.53 (stub) - DNS Search: lxd - netplanlab.local - -● 4: isp-bond0 bond UP (networkd: isp-bond0) - MAC Address: b2:6b:19:b1:9a:86 - Addresses: 172.16.0.1/24 - DNS Addresses: 172.16.0.254 - 172.16.0.253 - DNS Search: netplanlab.local - Routes: default via 172.16.0.254 (static) - 172.16.0.0/24 from 172.16.0.1 (link) - -3 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. diff --git a/doc/netplan-yaml.md b/doc/netplan-yaml.md index 0656bf3c9..c80900c83 100644 --- a/doc/netplan-yaml.md +++ b/doc/netplan-yaml.md @@ -599,7 +599,7 @@ Match devices by MAC when setting options like: `wakeonlan` or `*-offload`. > Takes a boolean. Configures whether traffic may be sent back out of the > bridge port on which it was received. When this flag is false, then the > bridge does not forward traffic back out of the receiving port. When - > unset, the back end `default` is be used. + > unset, the back end `default` is used. - **`port-mac-learning`** (scalar) – since **1.0** diff --git a/doc/tutorial.md b/doc/tutorial.md index af753140e..3e6fc64a3 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1,5 +1,7 @@ # Tutorial +The Netplan tutorial offers guidance for basic use of the utility. It starts with instructions on setting up an environment that allows users to experiment with Netplan and test its features, and continues with running the tool for the first time and checking its configuration. The tutorial also shows the ways available for modifying the configuration in order to enable the user to follow [how-to guides](/howto) that provide procedures for achieving specific goals with Netplan. + ```{toctree} netplan-tutorial ``` diff --git a/doc/using-static-ip-addresses.md b/doc/using-static-ip-addresses.md new file mode 100644 index 000000000..311860c9a --- /dev/null +++ b/doc/using-static-ip-addresses.md @@ -0,0 +1,128 @@ +# How to use static IP addresses + +:::{note} +These instructions assume a system setup based on the example configuration outlined in the [Netplan tutorial](/netplan-tutorial). +::: + +In this exercise you're going to add an static IP address to the second interface with a default route and DNS configuration. + +Edit the file `/etc/netplan/second-interface.yaml` created previously. Change it so it will look like this: + +```yaml +network: + version: 2 + ethernets: + enp6s0: + dhcp4: false + dhcp6: false + accept-ra: false + link-local: [] + addresses: + - 172.16.0.1/24 + routes: + - to: default + via: 172.16.0.254 + nameservers: + search: + - netplanlab.local + addresses: + - 172.16.0.254 + - 172.16.0.253 +``` + +The configuration above is what you'd expect in a desktop system for example. It defines the interface's IP address statically as `172.16.0.1/24`, a default route via gateway `172.16.0.254` and the DNS search domain and name servers. + +Now use `netplan get` to visualise all your network configuration: + +``` +netplan get +``` + +You should see an output similar to this: + +```yaml +network: + version: 2 + ethernets: + enp5s0: + dhcp4: true + enp6s0: + addresses: + - "172.16.0.1/24" + nameservers: + addresses: + - 172.16.0.254 + - 172.16.0.253 + search: + - netplanlab.local + dhcp4: false + dhcp6: false + accept-ra: false + routes: + - to: "default" + via: "172.16.0.254" + link-local: [] +``` + +You will notice that it might be a little different than what you have defined in the YAML file. Some things might be in a different order for example. + +The reason for that is that `netplan get` loads and parses your configuration before outputting it, and the YAML parsing engine used by Netplan might shuffle things around. Although, what you see from `netplan get` is equivalent to what you have in the file. + +Now use `netplan apply` to apply the new configuration: + +``` +netplan apply +``` + +And check the interface's new state: + +``` +ip address show dev enp6s0 +``` + +You should see something similar to this: +``` +3: enp6s0: 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 172.16.0.1/24 brd 172.16.0.255 scope global enp6s0 + valid_lft forever preferred_lft forever +``` + +Check the routes associated to the interface: + +``` +ip route show dev enp6s0 +``` + +You should see something similar to this: + +``` +default via 172.16.0.254 proto static +172.16.0.0/24 proto kernel scope link src 172.16.0.1 +``` + +And check the DNS configuration: + +``` +netplan status enp6s0 +``` + +You should see something similar to this: + +``` + Online state: online + DNS Addresses: 127.0.0.53 (stub) + DNS Search: netplanlab.local + lxd + +● 3: enp6s0 ethernet UP (networkd: enp6s0) + MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.) + Addresses: 172.16.0.1/24 + DNS Addresses: 172.16.0.254 + 172.16.0.253 + DNS Search: netplanlab.local + Routes: default via 172.16.0.254 (static) + 172.16.0.0/24 from 172.16.0.1 (link) + +2 inactive interfaces hidden. Use "--all" to show all. +```