From 2b7f22447a2e820e11c8cc0c5baf2802d67cc712 Mon Sep 17 00:00:00 2001 From: Atanas Dinov Date: Tue, 21 May 2024 11:49:16 +0300 Subject: [PATCH] Update README Signed-off-by: Atanas Dinov --- README.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e1481de..72ec6a8 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # nm-configurator -nm-configurator (or NMC) is a CLI tool which makes it easy to generate and apply NetworkManager configurations. +nm-configurator (or nmc) is a CLI tool which makes it easy to generate and apply NetworkManager configurations. ## How to install it? ### Download from release -Each release is published with NMC already built for `amd64` and `arm64` Linux systems: +Each release is published with nmc already built for `amd64` and `arm64` Linux systems: ```shell $ curl -o nmc -L https://github.com/suse-edge/nm-configurator/releases/latest/download/nmc-linux-$(uname -m) @@ -25,13 +25,21 @@ $ cargo build --release # only supports Linux based systems ### Generate config -NMC depends on having the desired network state for all known nodes beforehand. +nmc depends on having the desired network state for all known nodes beforehand. [NetworkManager](https://documentation.suse.com/sle-micro/5.5/html/SLE-Micro-all/cha-nm-configuration.html) is using connection profiles defined as files stored under `/etc/NetworkManager/system-connections`. -In order to generate these config (*.nmconnection) files, NMC uses the + +In order to generate these config (*.nmconnection) files, nmc uses the [nmstate](https://github.com/nmstate/nmstate) library and requires a configuration directory as an input. -This directory must contain the desired network state for all hosts in a hostname.yaml file format. +This directory must contain the desired network state in one of the following file formats: + +1. A single or multiple `.yaml` files containing the different configurations per host. +This method requires specifying the MAC addresses of all Ethernet interfaces for each host +in order to properly identify the relevant configurations when applying those. + +2. A single `_all.yaml` file containing the configurations to be applied to all hosts. +This method does not depend on MAC address matching. #### Prepare desired states @@ -89,7 +97,7 @@ EOF Please refer to the official nmstate docs for more extensive [examples](https://nmstate.io/examples.html). -#### Run NMC +#### Run nmc ```shell $ ./nmc generate --config-dir desired-states --output-dir network-config @@ -119,7 +127,7 @@ There are separate directories for each host (identified by their input hostn Each of these contains the configuration files for the desired network interfaces (e.g. `eth0`). The `host_config.yaml` file on the root level maps the hosts to all of their preconfigured interfaces. -This is necessary in order for NMC to identify which host it is running on when applying the network configurations later. +This is necessary in order for nmc to identify which host it is running on when applying the network configurations later. ```yaml - hostname: node1 @@ -139,9 +147,11 @@ This is necessary in order for NMC to identify which host it is running on when interface_type: ethernet ``` +**NOTE:** The `host_config.yaml` file will not be present if the input configurations are the same for all provisioned hosts (specified in `_all.yaml`). + ### Apply config -NMC will use the previously generated configurations to identify and store the relevant NetworkManager settings for a given host. +nmc will use the previously generated configurations to identify and store the relevant NetworkManager settings for a given host. Typically used with [Combustion](https://documentation.suse.com/sle-micro/5.5/single-html/SLE-Micro-deployment/#cha-images-combustion) in order to bootstrap multiple nodes using the same provisioning artefact instead of depending on different custom images per machine. @@ -160,6 +170,6 @@ $ ./nmc apply --config-dir network-config/ ``` **NOTE:** Interface names during the installation of nodes might differ from the preconfigured logical ones. -This is expected and NMC will rely on the MAC addresses and use the actual names for the NetworkManager +This is expected and nmc will rely on the MAC addresses and use the actual names for the NetworkManager configurations instead e.g. settings for interface with a predefined logical name `eth0` but actually named `eth2` will automatically be adjusted and stored to `/etc/NetworkManager/eth2.nmconnection`.