diff options
Diffstat (limited to 'docs/api/html/nm-cloud-setup.html')
| -rw-r--r-- | docs/api/html/nm-cloud-setup.html | 121 |
1 files changed, 96 insertions, 25 deletions
diff --git a/docs/api/html/nm-cloud-setup.html b/docs/api/html/nm-cloud-setup.html index fdf78578..b5d6c808 100644 --- a/docs/api/html/nm-cloud-setup.html +++ b/docs/api/html/nm-cloud-setup.html @@ -29,7 +29,7 @@ <td class="gallery_image" valign="top" align="right"></td> </tr></table></div> <div class="refsect1"> -<a name="id-1.2.13.4"></a><h2>Overview</h2> +<a name="id-1.2.14.4"></a><h2>Overview</h2> <p>When running a virtual machine in a public cloud environment, it is desirable to automatically configure the network of that VM. In simple setups, the VM only has one network interface and the public @@ -44,7 +44,7 @@ <p>Multiple cloud providers are supported. See <a class="xref" href="nm-cloud-setup.html#providers" title="Supported Cloud Providers">the section called “Supported Cloud Providers”</a>.</p> </div> <div class="refsect1"> -<a name="id-1.2.13.5"></a><h2>Use</h2> +<a name="id-1.2.14.5"></a><h2>Use</h2> <p>The goal of nm-cloud-setup is to be configuration-less and work automatically. All you need is to opt-in to the desired cloud providers (see <a class="xref" href="nm-cloud-setup.html#env" title="Environment Variables">the section called “Environment Variables”</a>) and run <span class="command"><strong>/usr/libexec/nm-cloud-setup</strong></span>.</p> @@ -53,7 +53,7 @@ and a NetworkManager dispatcher script.</p> </div> <div class="refsect1"> -<a name="id-1.2.13.6"></a><h2>Details</h2> +<a name="id-1.2.14.6"></a><h2>Details</h2> <p> nm-cloud-setup configures the network by fetching the configuration from the well-known meta data server of the cloud provider. That means, it already @@ -74,7 +74,7 @@ With this approach, the configuration is not persisted and only preserved until the device disconnects.</p> <div class="refsect2"> -<a name="id-1.2.13.6.5"></a><h3>/usr/libexec/nm-cloud-setup</h3> +<a name="id-1.2.14.6.5"></a><h3>/usr/libexec/nm-cloud-setup</h3> <p>The binary <span class="command"><strong>/usr/libexec/nm-cloud-setup</strong></span> does most of the work. It supports no command line arguments but can be configured via environment variables. @@ -94,7 +94,7 @@ </div> <hr> <div class="refsect2"> -<a name="id-1.2.13.6.6"></a><h3>nm-cloud-setup.service systemd unit</h3> +<a name="id-1.2.14.6.6"></a><h3>nm-cloud-setup.service systemd unit</h3> <p>Usually <span class="command"><strong>/usr/libexec/nm-cloud-setup</strong></span> is not run directly, but only by <span class="command"><strong>systemctl restart nm-cloud-setup.service</strong></span>. This ensures that the tool only runs once at any time. It also allows to integrate @@ -105,7 +105,7 @@ </div> <hr> <div class="refsect2"> -<a name="id-1.2.13.6.7"></a><h3>nm-cloud-setup.timer systemd timer</h3> +<a name="id-1.2.14.6.7"></a><h3>nm-cloud-setup.timer systemd timer</h3> <p><span class="command"><strong>/usr/libexec/nm-cloud-setup</strong></span> is intended to run whenever an update is necessary. For example, during boot when when changing the network configuration of the virtual machine via the cloud @@ -115,7 +115,7 @@ </div> <hr> <div class="refsect2"> -<a name="id-1.2.13.6.8"></a><h3>/usr/lib/NetworkManager/dispatcher.d/90-nm-cloud-setup.sh</h3> +<a name="id-1.2.14.6.8"></a><h3>/usr/lib/NetworkManager/dispatcher.d/90-nm-cloud-setup.sh</h3> <p>There is also a NetworkManager dispatcher script that will run for example when an interface is activated by NetworkManager. Together with the nm-cloud-setup.timer systemd timer this @@ -144,12 +144,45 @@ to <code class="literal">no</code>.</p></li> <li class="listitem"><p><code class="literal">NM_CLOUD_SETUP_GCP</code>: boolean, whether Google GCP support is enabled. Defaults to <code class="literal">no</code>.</p></li> +<li class="listitem"><p><code class="literal">NM_CLOUD_SETUP_ALIYUN</code>: boolean, whether Alibaba Cloud (Aliyun) support is enabled. Defaults + to <code class="literal">no</code>.</p></li> </ul></div> </div> <div class="refsect1"> +<a name="deploy"></a><h2>Example Setup for Configuring and Predeploying nm-cloud-setup</h2> +<p>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. + </p> +<p> + The following example enables nm-cloud-setup for Amazon EC2 cloud: + </p> +<pre class="programlisting"> +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 + </pre> +<p> + </p> +</div> +<div class="refsect1"> <a name="providers"></a><h2>Supported Cloud Providers</h2> <div class="refsect2"> -<a name="id-1.2.13.8.2"></a><h3>Amazon EC2 (AWS)</h3> +<a name="id-1.2.14.9.2"></a><h3>Amazon EC2 (AWS)</h3> <p>For AWS, the tools tries to fetch configuration from <code class="literal">http://169.254.169.254/</code>. Currently, it only configures IPv4 and does nothing about IPv6. It will do the following.</p> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> @@ -167,22 +200,36 @@ Also, if the device is currently not activated in NetworkManager or if the currently activated profile has a user-data <code class="literal">org.freedesktop.nm-cloud-setup.skip=yes</code>, it is skipped.</p> -<p>Then, the tool will change the runtime configuration of the device. +<p>If only one interface and one address is configured, then the tool does nothing + and leaves the automatic configuration that was obtained via DHCP.</p> +<p>Otherwise, the tool will change the runtime configuration of the device. </p> <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> <li class="listitem"><p>Add static IPv4 addresses for all the configured addresses from <code class="literal">local-ipv4s</code> with prefix length according to <code class="literal">subnet-ipv4-cidr-block</code>. For example, we might have here 2 IP addresses like <code class="literal">"172.16.5.3/24,172.16.5.4/24"</code>.</p></li> -<li class="listitem"><p>Choose a route table 30400 + the index of the interface and +<li class="listitem"> +<p>Choose a route table 30400 + the index of the interface and add a default route <code class="literal">0.0.0.0/0</code>. The gateway is the first IP address in the CIDR subnet block. For - example, we might get a route <code class="literal">"0.0.0.0/0 172.16.5.1 10 table=30401"</code>.</p></li> + example, we might get a route <code class="literal">"0.0.0.0/0 172.16.5.1 10 table=30400"</code>.</p> +<p>Also choose a route table 30200 + the interface index. This + contains a direct routes to the subnets of this interface.</p> +</li> <li class="listitem"><p>Finally, add a policy routing rule for each address. For example - <code class="literal">"priority 30401 from 172.16.5.3/32 table 30401, priority 30401 from 172.16.5.4/32 table 30401"</code>.</p></li> + <code class="literal">"priority 30200 from 172.16.5.3/32 table 30200, priority 30200 from 172.16.5.4/32 table 30200"</code>. + and + <code class="literal">"priority 30400 from 172.16.5.3/32 table 30400, priority 30400 from 172.16.5.4/32 table 30400"</code> + The 30200+ rules select the table to reach the subnet directly, while the 30400+ rules use the + default route. Also add a rule + <code class="literal">"priority 30350 table main suppress_prefixlength 0"</code>. 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+.</p></li> </ul></div> <p> With above example, this roughly corresponds for interface <code class="literal">eth0</code> to - <span class="command"><strong>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"</strong></span>. + <span class="command"><strong>nmcli 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"</strong></span>. 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. @@ -192,7 +239,7 @@ </div> <hr> <div class="refsect2"> -<a name="id-1.2.13.8.3"></a><h3>Google Cloud Platform (GCP)</h3> +<a name="id-1.2.14.9.3"></a><h3>Google Cloud Platform (GCP)</h3> <p> For GCP, the meta data is fetched from URIs starting with <code class="literal">http://metadata.google.internal/computeMetadata/v1/</code> with a HTTP header <code class="literal">"Metadata-Flavor: Google"</code>. @@ -220,7 +267,7 @@ </div> <hr> <div class="refsect2"> -<a name="id-1.2.13.8.4"></a><h3>Microsoft Azure</h3> +<a name="id-1.2.14.9.4"></a><h3>Microsoft Azure</h3> <p> For Azure, the meta data is fetched from URIs starting with <code class="literal">http://169.254.169.254/metadata/instance</code> with a URL parameter <code class="literal">"?format=text&api-version=2017-04-02"</code> and a HTTP header <code class="literal">"Metadata:true"</code>. @@ -238,25 +285,49 @@ </p></li> <li class="listitem"><p>Then, for each IP address index fetch the address at <code class="literal">http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/ipAddress/$ADDR_INDEX/privateIpAddress?format=text&api-version=2017-04-02</code>. - Also fetch the size of the subnet (the netmask) for the interface from + Also fetch the size of the subnet and prefix for the interface from + <code class="literal">http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/address/?format=text&api-version=2017-04-02</code>. + and <code class="literal">http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/prefix/?format=text&api-version=2017-04-02</code>. </p></li> <li class="listitem"> <p>At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses.</p> -<p>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 <code class="literal">org.freedesktop.nm-cloud-setup.skip=yes</code>, - 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".</p> -<p>The effect is not unlike calling - <span class="command"><strong>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"</strong></span> - for all relevant devices and all found addresses.</p> +<p>Then the tool configures the system like doing for AWS environment. That is, using source based policy routing + with the tables/rules 30200/30400.</p> +</li> +</ul></div> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.14.9.5"></a><h3>Alibaba Cloud (Aliyun)</h3> +<p>For Aliyun, the tools tries to fetch configuration from <code class="literal">http://100.100.100.200/</code>. Currently, it only + configures IPv4 and does nothing about IPv6. It will do the following.</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"><p>First fetch <code class="literal">http://100.100.100.200/2016-01-01/meta-data/</code> 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.</p></li> +<li class="listitem"><p>Fetch <code class="literal">http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/</code> to get the list + of available interface. Interfaces are identified by their MAC address.</p></li> +<li class="listitem"><p>Then for each interface fetch <code class="literal">http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/vpc-cidr-block</code>, + <code class="literal">http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/private-ipv4s</code>, + <code class="literal">http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/netmask</code> and + <code class="literal">http://100.100.100.200/2016-01-01/meta-data/network/interfaces/macs/$MAC/gateway</code>. + Thereby we get a list of private IPv4 addresses, one CIDR subnet block and private IPv4 addresses prefix.</p></li> +<li class="listitem"> +<p>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 <code class="literal">org.freedesktop.nm-cloud-setup.skip=yes</code>, + it is skipped. Also, there is only one interface and one IP address, the tool does nothing.</p> +<p>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.</p> </li> </ul></div> </div> </div> <div class="refsect1"> -<a name="id-1.2.13.9"></a><h2>See Also</h2> +<a name="id-1.2.14.10"></a><h2>See Also</h2> <p> <a class="link" href="NetworkManager.html" title="NetworkManager"><span class="citerefentry"><span class="refentrytitle">NetworkManager</span>(8)</span></a> <a class="link" href="nmcli.html" title="nmcli"><span class="citerefentry"><span class="refentrytitle">nmcli</span>(1)</span></a> |