Tutorial reorg & lang. + formatting improvements.

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.
+```

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
 ```

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: <BROADCAST,MULTICAST,UP,LOWER_UP> 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: <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: netplan-isp: <BROADCAST,MULTICAST,UP,LOWER_UP> 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
+```