New upstream version 1.32.12 upstream/1.32.12

1 files changed, 121 insertions, 13 deletions

diff --git a/man/nm-cloud-setup.8 b/man/nm-cloud-setup.8
index 0cc322d5..31f582df 100644
--- a/man/nm-cloud-setup.8
+++ b/man/nm-cloud-setup.8
@@ -2,12 +2,12 @@
 .\"     Title: nm-cloud-setup
 .\"    Author: 
 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.\"      Date: 07/16/2021
+.\"      Date: 09/22/2021
 .\"    Manual: Automatic Network Configuration in Cloud with NetworkManager
-.\"    Source: NetworkManager 1.30.6
+.\"    Source: NetworkManager 1.32.12
 .\"  Language: English
 .\"
-.TH "NM\-CLOUD\-SETUP" "8" "" "NetworkManager 1\&.30\&.6" "Automatic Network Configuratio"
+.TH "NM\-CLOUD\-SETUP" "8" "" "NetworkManager 1\&.32\&.12" "Automatic Network Configuratio"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -157,6 +157,51 @@ no\&.
 NM_CLOUD_SETUP_GCP: boolean, whether Google GCP support is enabled\&. Defaults to
 no\&.
 .RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+NM_CLOUD_SETUP_ALIYUN: boolean, whether Alibaba Cloud (Aliyun) support is enabled\&. Defaults to
+no\&.
+.RE
+.SH "EXAMPLE SETUP FOR CONFIGURING AND PREDEPLOYING NM\-CLOUD\-SETUP"
+.PP
+As detailed before, nm\-cloud\-setup needs to be explicitly enabled\&. As it runs as a systemd service and timer, that basically means to enable and configure those\&. This can be done by dropping the correct files and symlinks to disk\&.
+.PP
+The following example enables nm\-cloud\-setup for Amazon EC2 cloud:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+dnf install \-y NetworkManager\-cloud\-setup
+
+mkdir \-p /etc/systemd/system/nm\-cloud\-setup\&.service\&.d
+cat > /etc/systemd/system/nm\-cloud\-setup\&.service\&.d/10\-enable\-ec2\&.conf << EOF
+[Service]
+Environment=NM_CLOUD_SETUP_EC2=yes
+EOF
+
+# systemctl enable nm\-cloud\-setup\&.service
+mkdir \-p /etc/systemd/system/NetworkManager\&.service\&.wants/
+ln \-s /usr/lib/systemd/system/nm\-cloud\-setup\&.service /etc/systemd/system/NetworkManager\&.service\&.wants/nm\-cloud\-setup\&.service
+
+# systemctl enable nm\-cloud\-setup\&.timer
+mkdir \-p /etc/systemd/system/timers\&.target\&.wants/
+ln \-s /etc/systemd/system/timers\&.target\&.wants/nm\-cloud\-setup\&.timer /usr/lib/systemd/system/nm\-cloud\-setup\&.timer
+
+# systemctl daemon\-reload
+      
+.fi
+.if n \{\
+.RE
+.\}
+.sp
 .SH "SUPPORTED CLOUD PROVIDERS"
 .SS "Amazon EC2 (AWS)"
 .PP
@@ -214,7 +259,9 @@ http://169\&.254\&.169\&.254/2018\-09\-24/meta\-data/network/interfaces/macs/$MA
 Then nm\-cloud\-setup iterates over all interfaces for which it could fetch IP configuration\&. If no ethernet device for the respective MAC address is found, it is skipped\&. Also, if the device is currently not activated in NetworkManager or if the currently activated profile has a user\-data
 org\&.freedesktop\&.nm\-cloud\-setup\&.skip=yes, it is skipped\&.
 .sp
-Then, the tool will change the runtime configuration of the device\&.
+If only one interface and one address is configured, then the tool does nothing and leaves the automatic configuration that was obtained via DHCP\&.
+.sp
+Otherwise, the tool will change the runtime configuration of the device\&.
 .sp
 .RS 4
 .ie n \{\
@@ -241,7 +288,9 @@ subnet\-ipv4\-cidr\-block\&. For example, we might have here 2 IP addresses like
 .\}
 Choose a route table 30400 + the index of the interface and add a default route
 0\&.0\&.0\&.0/0\&. The gateway is the first IP address in the CIDR subnet block\&. For example, we might get a route
-"0\&.0\&.0\&.0/0 172\&.16\&.5\&.1 10 table=30401"\&.
+"0\&.0\&.0\&.0/0 172\&.16\&.5\&.1 10 table=30400"\&.
+.sp
+Also choose a route table 30200 + the interface index\&. This contains a direct routes to the subnets of this interface\&.
 .RE
 .sp
 .RS 4
@@ -253,13 +302,16 @@ Choose a route table 30400 + the index of the interface and add a default route
 .IP \(bu 2.3
 .\}
 Finally, add a policy routing rule for each address\&. For example
-"priority 30401 from 172\&.16\&.5\&.3/32 table 30401, priority 30401 from 172\&.16\&.5\&.4/32 table 30401"\&.
+"priority 30200 from 172\&.16\&.5\&.3/32 table 30200, priority 30200 from 172\&.16\&.5\&.4/32 table 30200"\&. and
+"priority 30400 from 172\&.16\&.5\&.3/32 table 30400, priority 30400 from 172\&.16\&.5\&.4/32 table 30400"
+The 30200+ rules select the table to reach the subnet directly, while the 30400+ rules use the default route\&. Also add a rule
+"priority 30350 table main suppress_prefixlength 0"\&. This has a priority between the two previous rules and causes a lookup of routes in the main table while ignoring the default route\&. The purpose of this is so that other specific routes in the main table are honored over the default route in table 30400+\&.
 .RE
 .sp
 With above example, this roughly corresponds for interface
 eth0
 to
-\fBnmcli 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"\fR\&. 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 on disk is not affected\&.
+\fBnmcli device modify "eth0" ipv4\&.addresses "172\&.16\&.5\&.3/24,172\&.16\&.5\&.4/24" ipv4\&.routes "172\&.16\&.5\&.0/24 0\&.0\&.0\&.0 10 table=30200, 0\&.0\&.0\&.0/0 172\&.16\&.5\&.1 10 table=30400" ipv4\&.routing\-rules "priority 30200 from 172\&.16\&.5\&.3/32 table 30200, priority 30200 from 172\&.16\&.5\&.4/32 table 30200, priority 20350 table main suppress_prefixlength 0, priority 30400 from 172\&.16\&.5\&.3/32 table 30400, priority 30400 from 172\&.16\&.5\&.4/32 table 30400"\fR\&. 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 on disk is not affected\&.
 .RE
 .SS "Google Cloud Platform (GCP)"
 .PP
@@ -408,7 +460,8 @@ to get the list of (indexes of) IP addresses on that interface\&.
 .IP \(bu 2.3
 .\}
 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/ipAddress/$ADDR_INDEX/privateIpAddress?format=text&api\-version=2017\-04\-02\&. Also fetch the size of the subnet and prefix for the interface from
+http://169\&.254\&.169\&.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/address/?format=text&api\-version=2017\-04\-02\&. and
 http://169\&.254\&.169\&.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/prefix/?format=text&api\-version=2017\-04\-02\&.
 .RE
 .sp
@@ -422,12 +475,67 @@ http://169\&.254\&.169\&.254/metadata/instance/network/interface/$IFACE_INDEX/ip
 .\}
 At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses\&.
 .sp
-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"\&.
+Then the tool configures the system like doing for AWS environment\&. That is, using source based policy routing with the tables/rules 30200/30400\&.
+.RE
+.SS "Alibaba Cloud (Aliyun)"
+.PP
+For Aliyun, the tools tries to fetch configuration from
+http://100\&.100\&.100\&.200/\&. Currently, it only configures IPv4 and does nothing about IPv6\&. It will do the following\&.
 .sp
-The effect is not unlike calling
-\fBnmcli 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"\fR
-for all relevant devices and all found addresses\&.
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+First fetch
+http://100\&.100\&.100\&.200/2016\-01\-01/meta\-data/
+to determine whether the expected API is present\&. This determines whether Aliyun environment is detected and whether to proceed to configure the host using Aliyun meta data\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Fetch
+http://100\&.100\&.100\&.200/2016\-01\-01/meta\-data/network/interfaces/macs/
+to get the list of available interface\&. Interfaces are identified by their MAC address\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Then for each interface fetch
+http://100\&.100\&.100\&.200/2016\-01\-01/meta\-data/network/interfaces/macs/$MAC/vpc\-cidr\-block,
+http://100\&.100\&.100\&.200/2016\-01\-01/meta\-data/network/interfaces/macs/$MAC/private\-ipv4s,
+http://100\&.100\&.100\&.200/2016\-01\-01/meta\-data/network/interfaces/macs/$MAC/netmask
+and
+http://100\&.100\&.100\&.200/2016\-01\-01/meta\-data/network/interfaces/macs/$MAC/gateway\&. Thereby we get a list of private IPv4 addresses, one CIDR subnet block and private IPv4 addresses prefix\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Then nm\-cloud\-setup iterates over all interfaces for which it could fetch IP configuration\&. If no ethernet device for the respective MAC address is found, it is skipped\&. Also, if the device is currently not activated in NetworkManager or if the currently activated profile has a user\-data
+org\&.freedesktop\&.nm\-cloud\-setup\&.skip=yes, it is skipped\&. Also, there is only one interface and one IP address, the tool does nothing\&.
+.sp
+Then the tool configures the system like doing for AWS environment\&. That is, using source based policy routing with the tables/rules 30200/30400\&. One difference to AWS is that the gateway is also fetched via metadata instead of using the first IP address in the subnet\&.
 .RE
 .SH "SEE ALSO"
 .PP