diff --git a/doc/netplan-everywhere.md b/doc/netplan-everywhere.md index 1ae30cacf..81ef6e247 100644 --- a/doc/netplan-everywhere.md +++ b/doc/netplan-everywhere.md @@ -1,6 +1,6 @@ # Desktop integration -## NetworkManager YAML settings backend (Netplan everywhere) +## NetworkManager YAML settings backend NetworkManager is the tool used by Ubuntu Desktop systems to manage network devices such as Ethernet and Wifi adapters. While it is a great @@ -8,23 +8,22 @@ tool for the job and users can directly use it through the command line and the graphical interfaces to configure their devices, Ubuntu has its own way of describing and storing network configuration via Netplan. -On Ubuntu, NetworkManager uses (or will use, depending on when you are -reading this) Netplan's APIs to save the configuration created by the -user using any of its interfaces. Our goal is to have a centralized place -to store network configuration. In the Desktop it's convenient to use -graphical tools for configuration when they are available, so nothing will -change from the user perspective, only the way the configuration is -handled under the hood. +On Ubuntu 23.10 "Mantic Minotaur" and later, NetworkManager uses Netplan's APIs +to save the configuration created through any of its graphical or programmatic +interfaces. This leads to having a centralized location to store network +configuration. In the Desktop it's convenient to use graphical tools for +configuration when they are available, so nothing will change from the user +perspective, only the way the configuration is handled under the hood. -For more information on Netplan, check https://netplan.io/ +For more information on Netplan, check [https://netplan.io](https://netplan.io) -For more information on NetworkManager, check https://networkmanager.dev/ +For more information on NetworkManager, check [https://networkmanager.dev](https://networkmanager.dev) ## How it works Every time a non-temporary connection is created in NetworkManager, instead -of persisting the original .nmconnection file, it will create a Netplan YAML -at `/etc/netplan` called `90-NM-.yaml`. After creating the +of persisting the original `.nmconnection` file, it will create a Netplan YAML +in `/etc/netplan/` called `90-NM-.yaml`. After creating the file, NetworkManager will call the Netplan generator to emit the configuration for that connection. Connections that are temporary, like the ones created for virtual network interfaces when you connect to a VPN for example, are not @@ -34,59 +33,36 @@ change that would affect them. ## How to install it -### Creating a backup of your current configuration - -The new NetworkManager will remove connection profiles that you eventually -modify from `/etc/NetworkManager`. So you might want to create a copy of all -your connection profiles before installing the new network-manager package: - -``` -$ mkdir ~/NetworkManager.bak && cd ~/NetworkManager.bak/ -$ sudo cp -r /etc/NetworkManager/system-connections . -``` - -In any case, a backup will be created automatically for you at -`/root/NetworkManager.bak` during package installation. - -And also keep a copy of all the original network-manager related packages in -case you want to revert to the previous installation: - -``` -$ apt download gir1.2-nm-1.0 libnm0 network-manager network-manager-config-connectivity-ubuntu -``` - ### Installing NetworkManager -The NetworkManager 1.42.0 package containing the Netplan integration patch -is currently available as a PPA. In order to install it, you will need to -have `netplan.io >= 0.106` installed in your system (it is available in Lunar). - +The NetworkManager 1.44.2 package containing the Netplan integration patch +is available by default in Ubuntu 23.10 "Mantic Minotaur" and later as part of +the official Ubuntu archive. ``` -$ sudo add-apt-repository ppa:canonical-foundations/networkmanager-netplan $ sudo apt update $ sudo apt install network-manager ``` ## How connections are managed from now on -After installing the new NetworkManager, your existing connection profiles -will not be imported to Netplan YAML files, only new connections and the -existing ones you eventually modify. +The NetworkManager-Netplan integration will import connection profiles from +`/etc/NetworkManager/system-connections/` to Netplan during the installation +process. It automatically creates a copy of all your connection profiles during +package installation of the new network-manager package in +`/root/NetworkManager.bak/system-connections/`. -For example, if you have a Wifi connection, you will find the connection -profile file at `/etc/NetworkManager/system-connections`. If you modify it -using one of the NetworkManager's interfaces (or delete and create a new one), -the respective file will be removed from `/etc/NetworkManager/system-connections`, -a Netplan YAML called `90-NM-.yaml` will be created at -`/etc/netplan` and a new profile will be generated and stored at -`/run/NetworkManager/system-connections`. +For example, if you have a Wifi connection, you will not find the connection +profile file at `/etc/NetworkManager/system-connections/` anymore. Instead, +that file will be removed and a Netplan YAML called `90-NM-.yaml` +will be created in `/etc/netplan/` and a new ephemeral profile will be generated +and stored in `/run/NetworkManager/system-connections/`. ## Limitation -Netplan doesn't yet support all the configuration available in +Netplan doesn't yet support all the configuration options available in NetworkManager (or doesn't know how to interpret some of the keywords found in the keyfile). After creating a new connection you might find -a section called "passthrough" in your YAML file, like in the example below: +a section called `passthrough` in your YAML file, like in the example below: ```yaml network: @@ -113,7 +89,7 @@ network: proxy._: "" ``` -All the configuration under the "passthrough" mapping will be added to +All the configuration under the `passthrough` mapping will be added to the `.nmconnection` file as they are. In cases where the connection type is not supported by Netplan the