From f0c4b3b287ff08af4aa0a34cee2735836d6bdd70 Mon Sep 17 00:00:00 2001 From: Thomas Haller Date: Tue, 5 Jan 2021 14:21:05 +0100 Subject: [PATCH] man: improve "nm-cloud-setup" manual page It's questionable whether the manual page should explain exactly what it does. However, it's a good exercise writing this up (to review what happens). Also, a manual page that simply says "it configures the network automatically" without going into how exactly, is not very useful either. --- man/nm-cloud-setup.xml | 100 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 90 insertions(+), 10 deletions(-) diff --git a/man/nm-cloud-setup.xml b/man/nm-cloud-setup.xml index 16c695a97f..2ffee5b055 100644 --- a/man/nm-cloud-setup.xml +++ b/man/nm-cloud-setup.xml @@ -49,11 +49,12 @@ desirable to automatically configure the network of that VM. In simple setups, the VM only has one network interface and the public cloud supports automatic configuration via DHCP, DHCP6 or IPv6 autoconf. - However, on the virtual machine might have multiple network + However, the virtual machine might have multiple network interfaces, or multiple IP addresses and IP subnets - on one interface. Also, the administrator can reconfigure those settings - while the machine is running. NetworkManager's nm-cloud-setup is a tool - that automatically picks up such configuration and updates the network + on one interface which cannot be configured via DHCP. Also, the administrator + may reconfigure the network while the machine is running. NetworkManager's + nm-cloud-setup is a tool + that automatically picks up such configuration in cloud environments and updates the network configuration of the host. Multiple cloud providers are supported. See . @@ -87,6 +88,11 @@ nmcli connection add type ethernet .... + + By setting the user-data org.freedesktop.nm-cloud-setup.skip=yes + on the profile, nm-cloud-setup will skip the device. + + nm-cloud-setup modifies the run time configuration akin to nmcli device modify. With this approach, the configuration is not persisted and only preserved until the device disconnects. @@ -119,7 +125,7 @@ Usually /usr/libexec/nm-cloud-setup is not run directly, but only by systemctl restart nm-cloud-setup.service. This ensures that the tool only runs once at any time. It also allows to integrate - use the nm-cloud-setup systemd timer, + with the nm-cloud-setup systemd timer, and to enable/disable the service via systemd. As you need to set environment variable to configure nm-cloud-setup binary, @@ -161,7 +167,7 @@ NM_CLOUD_SETUP_LOG: control the logging verbosity. Set it - one of TRACE, DEBUG, INFO, + to one of TRACE, DEBUG, INFO, WARN, ERR or OFF. The program will print message on stdout and the default level is WARN. @@ -187,7 +193,7 @@ Amazon EC2 (AWS) - The tools tries to fetch configuration from http://169.254.169.254/. Currently, it only + For AWS, the tools tries to fetch configuration from http://169.254.169.254/. Currently, it only configures IPv4 and does nothing about IPv6. It will do the following. @@ -233,7 +239,7 @@ nmcli device modify "eth0" ipv4.addresses "172.16.5.3/24,172.16.5.4/24" ipv4.routes "0.0.0.0/0 172.16.5.1 10 table=30401" ipv4.routing-rules "priority 30401 from 172.16.5.3/32 table 30401, priority 30401 from 172.16.5.4/32 table 30401". Note that this replaces the previous addresses, routes and rules with the new information. But also note that this only changes the run time configuration of the device. The - connection profile is not affected by that. + connection profile on disk is not affected. @@ -242,13 +248,87 @@ Google Cloud Platform (GCP) - The tools tries to fetch configuration from http://metadata.google.internal/. + + For GCP, the meta data is fetched from URIs starting with http://metadata.google.internal/computeMetadata/v1/ with a + HTTP header "Metadata-Flavor: Google". + Currently, the tool only configures IPv4 and does nothing about IPv6. It will do the following. + + + + + First fetch http://metadata.google.internal/computeMetadata/v1/instance/id to detect whether the tool + runs on Google Cloud Platform. Only if the platform is detected, it will continue fetching the configuration. + + + Fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/ to get the list + of available interface indexes. These indexes can be used for further lookups. + + + Then, for each interface fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/mac to get + the corresponding MAC address of the found interfaces. The MAC address is used to identify the device later on. + + + Then, for each interface with a MAC address fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/forwarded-ips/ + and then all the found IP addresses at http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/forwarded-ips/$FIPS_INDEX. + + + + At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses. + For each device, we lookup the currently applied connection in NetworkManager. That implies, that the device is currently activated + in NetworkManager. If no such device was in NetworkManager, or if the profile has user-data org.freedesktop.nm-cloud-setup.skip=yes, + we skip the device. Now for each found IP address we add a static route "$FIPS_ADDR/32 0.0.0.0 100 type=local" and reapply the change. + The effect is not unlike calling nmcli device modify "$DEVICE" ipv4.routes "$FIPS_ADDR/32 0.0.0.0 100 type=local [,...]" for all relevant + devices and all found addresses. + + Microsoft Azure - The tools tries to fetch configuration from http://169.254.169.254/. + + For Azure, the meta data is fetched from URIs starting with http://169.254.169.254/metadata/instance with a + URL parameter "?format=text&api-version=2017-04-02" and a HTTP header "Metadata:true". + Currently, the tool only configures IPv4 and does nothing about IPv6. It will do the following. + + + + + First fetch http://169.254.169.254/metadata/instance?format=text&api-version=2017-04-02 to detect whether the tool + runs on Azure Cloud. Only if the platform is detected, it will continue fetching the configuration. + + + Fetch http://169.254.169.254/metadata/instance/network/interface/?format=text&api-version=2017-04-02 to get the list + of available interface indexes. These indexes can be used for further lookups. + + + Then, for each interface fetch http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/macAddress?format=text&api-version=2017-04-02 + to get the corresponding MAC address of the found interfaces. The MAC address is used to identify the device later on. + + + Then, for each interface with a MAC address fetch http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/ipAddress/?format=text&api-version=2017-04-02 + to get the list of (indexes of) IP addresses on that interface. + + + + Then, for each IP address index fetch the address at + http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/ipAddress/$ADDR_INDEX/privateIpAddress?format=text&api-version=2017-04-02. + Also fetch the size of the subnet (the netmask) for the interface from + http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/prefix/?format=text&api-version=2017-04-02. + + + + At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses. + For each device, we lookup the currently applied connection in NetworkManager. That implies, that the device is currently activated + in NetworkManager. If no such device was in NetworkManager, or if the profile has user-data org.freedesktop.nm-cloud-setup.skip=yes, + we skip the device. Now for each found IP address we add a static address "$ADDR/$SUBNET_PREFIX". Also we configure policy routing + by adding a static route "$ADDR/$SUBNET_PREFIX $GATEWAY 10, table=$TABLE" where $GATEWAY is the first IP address in the subnet and table + is 30400 plus the interface index. Also we add a policy routing rule "priority $TABLE from $ADDR/32 table $TABLE". + The effect is not unlike calling + nmcli device modify "$DEVICE" ipv4.addresses "$ADDR/$SUBNET [,...]" ipv4.routes "$ADDR/32 $GATEWAY 10 table=$TABLE" ipv4.routing-rules "priority $TABLE from $ADDR/32 table $TABLE" + for all relevant devices and all found addresses. + +