'\" t

.\"     Title: nm-cloud-setup

.\"    Author: 

.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>

.\"      Date: 12/23/2020

.\"    Manual: Automatic Network Configuration in Cloud with NetworkManager

.\"    Source: NetworkManager 1.29.7

.\"  Language: English

.\"

.TH "NM\-CLOUD\-SETUP" "8" "" "NetworkManager 1\&.29\&.7" "Automatic Network Configuratio"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "NAME"

nm-cloud-setup \- Overview of Automatic Network Configuration in Cloud

.SH "OVERVIEW"

.PP

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 cloud supports automatic configuration via DHCP, DHCP6 or IPv6 autoconf\&. However, on 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\*(Aqs nm\-cloud\-setup is a tool that automatically picks up such configuration and updates the network configuration of the host\&.

.PP

Multiple cloud providers are supported\&. See

the section called \(lqSUPPORTED CLOUD PROVIDERS\(rq\&.

.SH "USE"

.PP

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

the section called \(lqENVIRONMENT VARIABLES\(rq) and run

\fB/usr/libexec/nm\-cloud\-setup\fR\&.

.PP

Usually this is done by enabling the nm\-cloud\-setup\&.service systemd service and let it run periodically\&. For that there is both a nm\-cloud\-setup\&.timer systemd timer and a NetworkManager dispatcher script\&.

.SH "DETAILS"

.PP

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 needs the network configured to the point where it can reach the meta data server\&. Commonly that means, that a simple connection profile is activated that possibly uses DHCP to get the primary IP address\&. NetworkManager will create such a profile for ethernet devices automatically if it is not configured otherwise via

"no\-auto\-default"

setting in NetworkManager\&.conf\&. One possible alternative may be to create such an initial profile with

\fBnmcli device connect "$DEVICE"\fR

or

\fBnmcli connection add type ethernet \&.\&.\&.\fR\&.

.PP

nm\-cloud\-setup modifies the run time configuration akin to

\fBnmcli device modify\fR\&. With this approach, the configuration is not persisted and only preserved until the device disconnects\&.

.SS "/usr/libexec/nm\-cloud\-setup"

.PP

The binary

\fB/usr/libexec/nm\-cloud\-setup\fR

does most of the work\&. It supports no command line arguments but can be configured via environment variables\&. See

the section called \(lqENVIRONMENT VARIABLES\(rq

for the supported environment variables\&.

.PP

By default, all cloud providers are disabled unless you opt\-in by enabling one or several providers\&. If cloud providers are enabled, the program tries to fetch the host\*(Aqs configuration from a meta data server of the cloud via HTTP\&. If configuration could be not fetched, no cloud provider are detected and the program quits\&. If host configuration is obtained, the corresponding cloud provider is successfully detected\&. Then the network of the host will be configured\&.

.PP

It is intended to re\-run nm\-cloud\-setup every time when the configuration (maybe) changes\&. The tool is idempotent, so it should be OK to also run it more often than necessary\&. You could run

\fB/usr/libexec/nm\-cloud\-setup\fR

directly\&. However it may be preferable to restart the nm\-cloud\-setup systemd service instead or use the timer or dispatcher script to run it periodically (see below)\&.

.SS "nm\-cloud\-setup\&.service systemd unit"

.PP

Usually

\fB/usr/libexec/nm\-cloud\-setup\fR

is not run directly, but only by

\fBsystemctl restart nm\-cloud\-setup\&.service\fR\&. This ensures that the tool only runs once at any time\&. It also allows to integrate use the nm\-cloud\-setup systemd timer, and to enable/disable the service via systemd\&.

.PP

As you need to set environment variable to configure nm\-cloud\-setup binary, you can do so via systemd override files\&. Try

\fBsystemctl edit nm\-cloud\-setup\&.service\fR\&.

.SS "nm\-cloud\-setup\&.timer systemd timer"

.PP

\fB/usr/libexec/nm\-cloud\-setup\fR

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 provider\&.

.PP

One way to do this, is by enabling the nm\-cloud\-setup\&.timer systemd timer with

\fBsystemctl enable \-\-now nm\-cloud\-setup\&.timer\fR\&.

.SS "/usr/lib/NetworkManager/dispatcher\&.d/90\-nm\-cloud\-setup\&.sh"

.PP

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 script is to automatically pick up changes to the network\&.

.PP

The dispatcher script will do nothing, unless the systemd service is enabled\&. To use the dispatcher script you should therefor run

\fBsystemctl enable nm\-cloud\-setup\&.service\fR

once\&.

.SH "ENVIRONMENT VARIABLES"

.PP

The environment variables are used to configure

\fB/usr/libexec/nm\-cloud\-setup\fR\&. You may want to configure them in the systemd service with

\fBsystemctl edit nm\-cloud\-setup\&.service\fR\&.

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

NM_CLOUD_SETUP_LOG: control the logging verbosity\&. Set it one of

TRACE,

DEBUG,

INFO,

WARN,

ERR

or

OFF\&. The program will print message on stdout and the default level is

WARN\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

NM_CLOUD_SETUP_AZURE: boolean, whether Microsoft Azure 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_EC2: boolean, whether Amazon EC2 (AWS) 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_GCP: boolean, whether Google GCP support is enabled\&. Defaults to

no\&.

.RE

.SH "SUPPORTED CLOUD PROVIDERS"

.SS "Amazon EC2 (AWS)"

.PP

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\&.

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

First fetch

http://169\&.254\&.169\&.254/latest/meta\-data/

to determine whether the expected API is present\&. This determines whether EC2 environment is detected and whether to proceed to configure the host using EC2 meta data\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Fetch

http://169\&.254\&.169\&.254/2018\-09\-24/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://169\&.254\&.169\&.254/2018\-09\-24/meta\-data/network/interfaces/macs/$MAC/subnet\-ipv4\-cidr\-block

and

http://169\&.254\&.169\&.254/2018\-09\-24/meta\-data/network/interfaces/macs/$MAC/local\-ipv4s\&. Thereby we get a list of local IPv4 addresses and one CIDR subnet block\&.

.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\&.

.sp

Then, the tool will change the runtime configuration of the device\&.

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Add static IPv4 addresses for all the configured addresses from

local\-ipv4s

with prefix length according to

subnet\-ipv4\-cidr\-block\&. For example, we might have here 2 IP addresses like

"172\&.16\&.5\&.3/24,172\&.16\&.5\&.4/24"\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

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"\&.

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.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"\&.

.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 is not affected by that\&.

.RE

.SS "Google Cloud Platform (GCP)"

.PP

The tools tries to fetch configuration from

http://metadata\&.google\&.internal/\&.

.SS "Microsoft Azure"

.PP

The tools tries to fetch configuration from

http://169\&.254\&.169\&.254/\&.

.SH "SEE ALSO"

.PP

\fBNetworkManager\fR(8)

\fBnmcli\fR(1)