|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
<html>
|
|
Packit Service |
8f75d2 |
<head>
|
|
Packit Service |
8f75d2 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit Service |
8f75d2 |
<title>nm-cloud-setup: NetworkManager Reference Manual</title>
|
|
Packit Service |
8f75d2 |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit Service |
8f75d2 |
<link rel="home" href="index.html" title="NetworkManager Reference Manual">
|
|
Packit Service |
8f75d2 |
<link rel="up" href="manpages.html" title="Part I. Manual Pages">
|
|
Packit Service |
8f75d2 |
<link rel="prev" href="nm-initrd-generator.html" title="nm-initrd-generator">
|
|
Packit Service |
8f75d2 |
<link rel="next" href="nm-openvswitch.html" title="nm-openvswitch">
|
|
Packit Service |
018b0a |
<meta name="generator" content="GTK-Doc V1.33.0 (XML mode)">
|
|
Packit Service |
8f75d2 |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit Service |
8f75d2 |
</head>
|
|
Packit Service |
8f75d2 |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
nm-cloud-setup
|
|
Packit Service |
8f75d2 |
nm-cloud-setup — Overview of Automatic Network Configuration in Cloud
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Overview
|
|
Packit Service |
8f75d2 |
When running a virtual machine in a public cloud environment, it is
|
|
Packit Service |
8f75d2 |
desirable to automatically configure the network of that VM.
|
|
Packit Service |
8f75d2 |
In simple setups, the VM only has one network interface and the public
|
|
Packit Service |
8f75d2 |
cloud supports automatic configuration via DHCP, DHCP6 or IPv6 autoconf.
|
|
Packit Service |
87a54e |
However, the virtual machine might have multiple network
|
|
Packit Service |
8f75d2 |
interfaces, or multiple IP addresses and IP subnets
|
|
Packit Service |
87a54e |
on one interface which cannot be configured via DHCP. Also, the administrator
|
|
Packit Service |
87a54e |
may reconfigure the network while the machine is running. NetworkManager's
|
|
Packit Service |
87a54e |
nm-cloud-setup is a tool
|
|
Packit Service |
87a54e |
that automatically picks up such configuration in cloud environments and updates the network
|
|
Packit Service |
8f75d2 |
configuration of the host.
|
|
Packit Service |
8f75d2 |
Multiple cloud providers are supported. See the section called “Supported Cloud Providers”.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Use
|
|
Packit Service |
8f75d2 |
The goal of nm-cloud-setup is to be configuration-less and work automatically.
|
|
Packit Service |
8f75d2 |
All you need is to opt-in to the desired cloud providers (see the section called “Environment Variables”)
|
|
Packit Service |
8f75d2 |
and run /usr/libexec/nm-cloud-setup.
|
|
Packit Service |
8f75d2 |
Usually this is done by enabling the nm-cloud-setup.service systemd service
|
|
Packit Service |
8f75d2 |
and let it run periodically. For that there is both a nm-cloud-setup.timer systemd timer
|
|
Packit Service |
8f75d2 |
and a NetworkManager dispatcher script.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Details
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
nm-cloud-setup configures the network by fetching the configuration from
|
|
Packit Service |
8f75d2 |
the well-known meta data server of the cloud provider. That means, it already
|
|
Packit Service |
8f75d2 |
needs the network configured to the point where it can reach the meta data
|
|
Packit Service |
8f75d2 |
server. Commonly that means, that a simple connection profile is activated
|
|
Packit Service |
8f75d2 |
that possibly uses DHCP to get the primary IP address. NetworkManager will
|
|
Packit Service |
8f75d2 |
create such a profile for ethernet devices automatically if it is not configured
|
|
Packit Service |
8f75d2 |
otherwise via "no-auto-default" setting in NetworkManager.conf.
|
|
Packit Service |
8f75d2 |
One possible alternative may be to create such an initial profile with
|
|
Packit Service |
8f75d2 |
nmcli device connect "$DEVICE" or
|
|
Packit Service |
8f75d2 |
nmcli connection add type ethernet ....
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
By setting the user-data org.freedesktop.nm-cloud-setup.skip=yes
|
|
Packit Service |
87a54e |
on the profile, nm-cloud-setup will skip the device.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
8f75d2 |
nm-cloud-setup modifies the run time configuration akin to nmcli device modify.
|
|
Packit Service |
8f75d2 |
With this approach, the configuration is not persisted
|
|
Packit Service |
8f75d2 |
and only preserved until the device disconnects.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
87a54e |
/usr/libexec/nm-cloud-setup
|
|
Packit Service |
8f75d2 |
The binary /usr/libexec/nm-cloud-setup does most of the
|
|
Packit Service |
8f75d2 |
work. It supports no command line arguments but can be configured via environment
|
|
Packit Service |
8f75d2 |
variables.
|
|
Packit Service |
8f75d2 |
See the section called “Environment Variables” for the supported environment variables.
|
|
Packit Service |
8f75d2 |
By default, all cloud providers are disabled unless you opt-in by enabling one
|
|
Packit Service |
8f75d2 |
or several providers. If cloud providers are enabled, the program
|
|
Packit Service |
8f75d2 |
tries to fetch the host's configuration from a meta data server of the cloud via HTTP.
|
|
Packit Service |
8f75d2 |
If configuration could be not fetched, no cloud provider are detected and the
|
|
Packit Service |
8f75d2 |
program quits.
|
|
Packit Service |
8f75d2 |
If host configuration is obtained, the corresponding cloud provider is
|
|
Packit Service |
8f75d2 |
successfully detected. Then the network of the host will be configured.
|
|
Packit Service |
8f75d2 |
It is intended to re-run nm-cloud-setup every time when the configuration
|
|
Packit Service |
8f75d2 |
(maybe) changes. The tool is idempotent, so it should be OK to also run it
|
|
Packit Service |
8f75d2 |
more often than necessary. You could run /usr/libexec/nm-cloud-setup
|
|
Packit Service |
8f75d2 |
directly. However it may be preferable to restart the nm-cloud-setup systemd
|
|
Packit Service |
8f75d2 |
service instead or use the timer or dispatcher script to run it periodically (see below).
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
87a54e |
nm-cloud-setup.service systemd unit
|
|
Packit Service |
8f75d2 |
Usually /usr/libexec/nm-cloud-setup is not run directly,
|
|
Packit Service |
8f75d2 |
but only by systemctl restart nm-cloud-setup.service. This
|
|
Packit Service |
8f75d2 |
ensures that the tool only runs once at any time. It also allows to integrate
|
|
Packit Service |
87a54e |
with the nm-cloud-setup systemd timer,
|
|
Packit Service |
8f75d2 |
and to enable/disable the service via systemd.
|
|
Packit Service |
8f75d2 |
As you need to set environment variable to configure nm-cloud-setup binary,
|
|
Packit Service |
8f75d2 |
you can do so via systemd override files. Try systemctl edit nm-cloud-setup.service.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
87a54e |
nm-cloud-setup.timer systemd timer
|
|
Packit Service |
8f75d2 |
/usr/libexec/nm-cloud-setup is intended to run
|
|
Packit Service |
8f75d2 |
whenever an update is necessary. For example, during boot when when
|
|
Packit Service |
8f75d2 |
changing the network configuration of the virtual machine via the cloud
|
|
Packit Service |
8f75d2 |
provider.
|
|
Packit Service |
8f75d2 |
One way to do this, is by enabling the nm-cloud-setup.timer systemd timer
|
|
Packit Service |
8f75d2 |
with systemctl enable --now nm-cloud-setup.timer.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
87a54e |
/usr/lib/NetworkManager/dispatcher.d/90-nm-cloud-setup.sh
|
|
Packit Service |
8f75d2 |
There is also a NetworkManager dispatcher script that will
|
|
Packit Service |
8f75d2 |
run for example when an interface is activated by NetworkManager.
|
|
Packit Service |
8f75d2 |
Together with the nm-cloud-setup.timer systemd timer this
|
|
Packit Service |
8f75d2 |
script is to automatically pick up changes to the network.
|
|
Packit Service |
8f75d2 |
The dispatcher script will do nothing, unless the systemd service is
|
|
Packit Service |
8f75d2 |
enabled. To use the dispatcher script you should therefor run
|
|
Packit Service |
8f75d2 |
systemctl enable nm-cloud-setup.service once.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Environment Variables
|
|
Packit Service |
8f75d2 |
The environment variables are used to configure /usr/libexec/nm-cloud-setup.
|
|
Packit Service |
8f75d2 |
You may want to configure them in the systemd service with systemctl edit nm-cloud-setup.service.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
NM_CLOUD_SETUP_LOG: control the logging verbosity. Set it
|
|
Packit Service |
87a54e |
to one of TRACE, DEBUG, INFO,
|
|
Packit Service |
8f75d2 |
WARN, ERR or OFF. The program
|
|
Packit Service |
8f75d2 |
will print message on stdout and the default level is WARN.
|
|
Packit Service |
8f75d2 |
NM_CLOUD_SETUP_AZURE: boolean, whether Microsoft Azure support is enabled. Defaults
|
|
Packit Service |
8f75d2 |
to no.
|
|
Packit Service |
8f75d2 |
NM_CLOUD_SETUP_EC2: boolean, whether Amazon EC2 (AWS) support is enabled. Defaults
|
|
Packit Service |
8f75d2 |
to no.
|
|
Packit Service |
8f75d2 |
NM_CLOUD_SETUP_GCP: boolean, whether Google GCP support is enabled. Defaults
|
|
Packit Service |
8f75d2 |
to no.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Supported Cloud Providers
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Amazon EC2 (AWS)
|
|
Packit Service |
87a54e |
For AWS, the tools tries to fetch configuration from http://169.254.169.254/. Currently, it only
|
|
Packit Service |
8f75d2 |
configures IPv4 and does nothing about IPv6. It will do the following.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
First fetch http://169.254.169.254/latest/meta-data/ to determine whether the
|
|
Packit Service |
8f75d2 |
expected API is present. This determines whether EC2 environment is detected and whether to proceed
|
|
Packit Service |
8f75d2 |
to configure the host using EC2 meta data.
|
|
Packit Service |
8f75d2 |
Fetch http://169.254.169.254/2018-09-24/meta-data/network/interfaces/macs/ to get the list
|
|
Packit Service |
8f75d2 |
of available interface. Interfaces are identified by their MAC address.
|
|
Packit Service |
8f75d2 |
Then for each interface fetch http://169.254.169.254/2018-09-24/meta-data/network/interfaces/macs/$MAC/subnet-ipv4-cidr-block
|
|
Packit Service |
8f75d2 |
and http://169.254.169.254/2018-09-24/meta-data/network/interfaces/macs/$MAC/local-ipv4s.
|
|
Packit Service |
8f75d2 |
Thereby we get a list of local IPv4 addresses and one CIDR subnet block.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Then nm-cloud-setup iterates over all interfaces for which it could fetch IP configuration.
|
|
Packit Service |
8f75d2 |
If no ethernet device for the respective MAC address is found, it is skipped.
|
|
Packit Service |
8f75d2 |
Also, if the device is currently not activated in NetworkManager or if the currently
|
|
Packit Service |
8f75d2 |
activated profile has a user-data org.freedesktop.nm-cloud-setup.skip=yes,
|
|
Packit Service |
8f75d2 |
it is skipped.
|
|
Packit Service |
8f75d2 |
Then, the tool will change the runtime configuration of the device.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Add static IPv4 addresses for all the configured addresses from local-ipv4s with
|
|
Packit Service |
8f75d2 |
prefix length according to subnet-ipv4-cidr-block. For example,
|
|
Packit Service |
8f75d2 |
we might have here 2 IP addresses like "172.16.5.3/24,172.16.5.4/24".
|
|
Packit Service |
8f75d2 |
Choose a route table 30400 + the index of the interface and
|
|
Packit Service |
8f75d2 |
add a default route 0.0.0.0/0. The gateway
|
|
Packit Service |
8f75d2 |
is the first IP address in the CIDR subnet block. For
|
|
Packit Service |
8f75d2 |
example, we might get a route "0.0.0.0/0 172.16.5.1 10 table=30401".
|
|
Packit Service |
8f75d2 |
Finally, add a policy routing rule for each address. For example
|
|
Packit Service |
8f75d2 |
"priority 30401 from 172.16.5.3/32 table 30401, priority 30401 from 172.16.5.4/32 table 30401".
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
With above example, this roughly corresponds for interface eth0 to
|
|
Packit Service |
8f75d2 |
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".
|
|
Packit Service |
8f75d2 |
Note that this replaces the previous addresses, routes and rules with the new information.
|
|
Packit Service |
8f75d2 |
But also note that this only changes the run time configuration of the device. The
|
|
Packit Service |
87a54e |
connection profile on disk is not affected.
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Google Cloud Platform (GCP)
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
For GCP, the meta data is fetched from URIs starting with http://metadata.google.internal/computeMetadata/v1/ with a
|
|
Packit Service |
87a54e |
HTTP header "Metadata-Flavor: Google".
|
|
Packit Service |
87a54e |
Currently, the tool only configures IPv4 and does nothing about IPv6. It will do the following.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
First fetch http://metadata.google.internal/computeMetadata/v1/instance/id to detect whether the tool
|
|
Packit Service |
87a54e |
runs on Google Cloud Platform. Only if the platform is detected, it will continue fetching the configuration.
|
|
Packit Service |
87a54e |
Fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/ to get the list
|
|
Packit Service |
87a54e |
of available interface indexes. These indexes can be used for further lookups.
|
|
Packit Service |
87a54e |
Then, for each interface fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/mac to get
|
|
Packit Service |
87a54e |
the corresponding MAC address of the found interfaces. The MAC address is used to identify the device later on.
|
|
Packit Service |
87a54e |
Then, for each interface with a MAC address fetch http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/forwarded-ips/
|
|
Packit Service |
87a54e |
and then all the found IP addresses at http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/$IFACE_INDEX/forwarded-ips/$FIPS_INDEX.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses.
|
|
Packit Service |
87a54e |
For each device, we lookup the currently applied connection in NetworkManager. That implies, that the device is currently activated
|
|
Packit Service |
87a54e |
in NetworkManager. If no such device was in NetworkManager, or if the profile has user-data org.freedesktop.nm-cloud-setup.skip=yes,
|
|
Packit Service |
87a54e |
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.
|
|
Packit Service |
87a54e |
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
|
|
Packit Service |
87a54e |
devices and all found addresses.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
Microsoft Azure
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
For Azure, the meta data is fetched from URIs starting with http://169.254.169.254/metadata/instance with a
|
|
Packit Service |
87a54e |
URL parameter "?format=text&api-version=2017-04-02" and a HTTP header "Metadata:true".
|
|
Packit Service |
87a54e |
Currently, the tool only configures IPv4 and does nothing about IPv6. It will do the following.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
First fetch http://169.254.169.254/metadata/instance?format=text&api-version=2017-04-02 to detect whether the tool
|
|
Packit Service |
87a54e |
runs on Azure Cloud. Only if the platform is detected, it will continue fetching the configuration.
|
|
Packit Service |
87a54e |
Fetch http://169.254.169.254/metadata/instance/network/interface/?format=text&api-version=2017-04-02 to get the list
|
|
Packit Service |
87a54e |
of available interface indexes. These indexes can be used for further lookups.
|
|
Packit Service |
87a54e |
Then, for each interface fetch http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/macAddress?format=text&api-version=2017-04-02
|
|
Packit Service |
87a54e |
to get the corresponding MAC address of the found interfaces. The MAC address is used to identify the device later on.
|
|
Packit Service |
87a54e |
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
|
|
Packit Service |
87a54e |
to get the list of (indexes of) IP addresses on that interface.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
Then, for each IP address index fetch the address at
|
|
Packit Service |
87a54e |
http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/ipAddress/$ADDR_INDEX/privateIpAddress?format=text&api-version=2017-04-02.
|
|
Packit Service |
87a54e |
Also fetch the size of the subnet (the netmask) for the interface from
|
|
Packit Service |
87a54e |
http://169.254.169.254/metadata/instance/network/interface/$IFACE_INDEX/ipv4/subnet/0/prefix/?format=text&api-version=2017-04-02.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
At this point, we have a list of all interfaces (by MAC address) and their configured IPv4 addresses.
|
|
Packit Service |
87a54e |
For each device, we lookup the currently applied connection in NetworkManager. That implies, that the device is currently activated
|
|
Packit Service |
87a54e |
in NetworkManager. If no such device was in NetworkManager, or if the profile has user-data org.freedesktop.nm-cloud-setup.skip=yes,
|
|
Packit Service |
87a54e |
we skip the device. Now for each found IP address we add a static address "$ADDR/$SUBNET_PREFIX". Also we configure policy routing
|
|
Packit Service |
87a54e |
by adding a static route "$ADDR/$SUBNET_PREFIX $GATEWAY 10, table=$TABLE" where $GATEWAY is the first IP address in the subnet and table
|
|
Packit Service |
87a54e |
is 30400 plus the interface index. Also we add a policy routing rule "priority $TABLE from $ADDR/32 table $TABLE".
|
|
Packit Service |
87a54e |
The effect is not unlike calling
|
|
Packit Service |
87a54e |
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"
|
|
Packit Service |
87a54e |
for all relevant devices and all found addresses.
|
|
Packit Service |
87a54e |
|
|
Packit Service |
87a54e |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
See Also
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
NetworkManager(8)
|
|
Packit Service |
8f75d2 |
nmcli(1)
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
8f75d2 |
|
|
Packit Service |
018b0a |
Generated by GTK-Doc V1.33.0
|
|
Packit Service |
8f75d2 |
</body>
|
|
Packit Service |
8f75d2 |
</html>
|