summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas Haller <thaller@redhat.com>2022-03-02 16:09:30 +0100
committerThomas Haller <thaller@redhat.com>2022-03-02 16:09:30 +0100
commit988ca74b4a87573aa47601ae2148a1525854a71c (patch)
treeefe2d6417ffa00f256319c0f5aa79d654658e23e
parent237c028e536c4dc282e8bc87211f0ddfdc046a36 (diff)
parentdf94cb2116234786d00a5d7149d796ed8a502cc2 (diff)
downloadNetworkManager-988ca74b4a87573aa47601ae2148a1525854a71c.tar.gz
man: merge branch 'th/man-nm-wait-online'
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1130
-rw-r--r--Makefile.am5
-rw-r--r--configure.ac3
-rw-r--r--contrib/fedora/rpm/NetworkManager.spec1
-rw-r--r--docs/api/Makefile.am1
-rw-r--r--docs/api/network-manager-docs.xml1
-rw-r--r--man/NetworkManager-wait-online.service.xml169
-rw-r--r--man/NetworkManager.xml1
-rw-r--r--man/meson.build1
-rw-r--r--man/nm-online.xml28
-rw-r--r--src/core/nm-manager.c3
10 files changed, 189 insertions, 24 deletions
diff --git a/Makefile.am b/Makefile.am
index af6743ec82..1c85805c96 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -5434,11 +5434,12 @@ CLEANFILES += $(man_nm_settings_xml)
endif
man_pages += \
- man/NetworkManager.8 \
man/NetworkManager-dispatcher.8 \
+ man/NetworkManager-wait-online.service.8 \
+ man/NetworkManager.8 \
man/NetworkManager.conf.5 \
- man/nm-online.1 \
man/nm-initrd-generator.8 \
+ man/nm-online.1 \
man/nmcli-examples.7 \
man/nmcli.1 \
man/nmtui.1 \
diff --git a/configure.ac b/configure.ac
index ad1a5b3957..6f3e312365 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1325,8 +1325,9 @@ AM_CONDITIONAL(WITH_PYTHON_BLACK, test "${BLACK}" != "")
# check for pregenerated manpages and documentation to be installed
use_pregen_docs=no
if test "$build_docs" != "yes" -a \
- -f "$srcdir"/man/NetworkManager.8 -a \
-f "$srcdir"/man/NetworkManager-dispatcher.8 -a \
+ -f "$srcdir"/man/NetworkManager-wait-online.service.8 -a \
+ -f "$srcdir"/man/NetworkManager.8 -a \
-f "$srcdir"/man/NetworkManager.conf.5 -a \
-f "$srcdir"/man/nm-online.1 -a \
-f "$srcdir"/man/nmcli-examples.7 -a \
diff --git a/contrib/fedora/rpm/NetworkManager.spec b/contrib/fedora/rpm/NetworkManager.spec
index 83bfaa93ae..a36968d7e9 100644
--- a/contrib/fedora/rpm/NetworkManager.spec
+++ b/contrib/fedora/rpm/NetworkManager.spec
@@ -1039,6 +1039,7 @@ fi
%{_mandir}/man8/nm-initrd-generator.8.gz
%{_mandir}/man8/NetworkManager.8.gz
%{_mandir}/man8/NetworkManager-dispatcher.8.gz
+%{_mandir}/man8/NetworkManager-wait-online.service.8.gz
%dir %{_localstatedir}/lib/NetworkManager
%dir %{_sysconfdir}/sysconfig/network-scripts
%{_datadir}/dbus-1/system-services/org.freedesktop.nm_dispatcher.service
diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am
index fd98aa2415..c89dbc4494 100644
--- a/docs/api/Makefile.am
+++ b/docs/api/Makefile.am
@@ -88,6 +88,7 @@ content_files = \
$(top_builddir)/man/NetworkManager.xml \
$(top_builddir)/man/NetworkManager-dispatcher.xml \
$(top_builddir)/man/NetworkManager.conf.xml \
+ $(top_builddir)/man/NetworkManager-wait-online.service.xml \
$(top_builddir)/man/nmcli-examples.xml \
$(top_builddir)/man/nm-settings-dbus.xml \
$(top_builddir)/man/nm-settings-keyfile.xml \
diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml
index 77b7e0177c..442b05aa7d 100644
--- a/docs/api/network-manager-docs.xml
+++ b/docs/api/network-manager-docs.xml
@@ -71,6 +71,7 @@
<xi:include href="../../man/NetworkManager.xml"/>
<xi:include href="../../man/NetworkManager.conf.xml"/>
<xi:include href="../../man/NetworkManager-dispatcher.xml"/>
+ <xi:include href="../../man/NetworkManager-wait-online.service.xml"/>
<xi:include href="../../man/nmcli.xml"/>
<xi:include href="../../man/nmcli-examples.xml"/>
<xi:include href="../../man/nmtui.xml"/>
diff --git a/man/NetworkManager-wait-online.service.xml b/man/NetworkManager-wait-online.service.xml
new file mode 100644
index 0000000000..d061643c3c
--- /dev/null
+++ b/man/NetworkManager-wait-online.service.xml
@@ -0,0 +1,169 @@
+<?xml version='1.0'?>
+<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "common.ent" >
+%entities;
+]>
+
+<!--
+ NetworkManager-wait-online.service(8) manual page
+
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. You may obtain a copy of the GNU Free Documentation License
+ from the Free Software Foundation by visiting their Web site or by
+ writing to:
+
+ Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+-->
+
+<refentry id="NetworkManager-wait-online.service">
+ <refentryinfo>
+ <title>NetworkManager-wait-online.service</title>
+ <author>NetworkManager developers</author>
+ </refentryinfo>
+ <refmeta>
+ <refentrytitle>NetworkManager-wait-online.service</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="source">NetworkManager-wait-online.service</refmiscinfo>
+ <refmiscinfo class="manual">Network management daemons</refmiscinfo>
+ <refmiscinfo class="version">&NM_VERSION;</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>NetworkManager-wait-online.service</refname>
+ <refpurpose>Wait for network to come online</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ NetworkManager-wait-online.service delays network-online.target until network
+ is ready.
+ </para>
+ <para>
+ The systemd target <literal>network-online.target</literal> acts as a synchronization point
+ for services to start after network is configured. Such services should
+ order themselves <literal>After=network-online.target</literal>
+ (and never <literal>After=NetworkManager-wait-online.service</literal>).
+ <literal>NetworkManager-wait-online.service</literal> is a one-shot service
+ that itself is ordered <literal>Before=network-online.target</literal>
+ and this way delays the target until the network is configured.
+ </para>
+ <para>
+ <literal>NetworkManager-wait-online.service</literal> itself is almost not configurable
+ itself. Instead the connection profiles and configuration in NetworkManager affects
+ the behavior.
+ </para>
+ <para>
+ In the best case, all services on the system can react to networking changes dynamically and
+ no service orders itself after <literal>network-online.target</literal>. That way,
+ <literal>NetworkManager-wait-online.service</literal> has no effect and, for example,
+ does not delay the boot. That means, if the problem is a long boot time related to
+ <literal>NetworkManager-wait-online.service</literal>, a possible solution is to
+ investigate the services that claim to require network and fix those.
+ </para>
+ <para>
+ For services that require network configured,
+ <literal>NetworkManager-wait-online.service</literal> is the default implementation
+ provided by NetworkManager to delay the target. But it does nothing magical. With
+ special requirements, it may be sensible to disable <literal>NetworkManager-wait-online.service</literal>
+ and replace it with a similar service that better implements the requirement.
+ </para>
+ <para>
+ <literal>NetworkManager-wait-online.service</literal> blocks until
+ NetworkManager logs "startup complete" and announces startup complete
+ on D-Bus. How long that takes depends on the network
+ and the NetworkManager configuration. If it takes longer than expected, then
+ the reasons need to be investigated in NetworkManager.
+ </para>
+ <para>
+ There are various reasons what affects NetworkManager reaching "startup complete"
+ and how long <literal>NetworkManager-wait-online.service</literal> blocks.
+ <itemizedlist>
+ <listitem>
+ <para>
+ In general, startup complete is not reached as long as NetworkManager is busy
+ activating a device and as long as there are profiles in activating state.
+ During boot, NetworkManager starts autoactivating
+ suitable profiles that are configured to autoconnect. If activation fails,
+ NetworkManager might retry right away (depending on <literal>connection.autoconnect-retries</literal>
+ setting). While trying and retrying, NetworkManager is busy until all
+ profiles and devices either reached an activated or disconnected state
+ and no further events are expected.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When a device reaches activated state, depends on its configuration.
+ For example, with a profile with both IPv4 and IPv6 addressing
+ enabled, the device is possibly considered fully activated when
+ either of the address families is ready. This can be controlled with the
+ <literal>ipv4.may-fail</literal> and <literal>ipv6.may-fail</literal>
+ settings, to indicate that the address family is required.
+ There are also <literal>ipv4.required-timeout</literal> and <literal>ipv6.required-timeout</literal>
+ settings which affect how long to wait for an address family.
+ Likewise, properties like <literal>ipv4.dhcp-timeout</literal> and
+ <literal>ipv6.ra-timeout</literal> affect how long NetworkManager
+ will try the IP configuration before giving up.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For example, a bridge or bond profile cannot do IP configuration
+ without ports. When booting with such profiles that autoactivate
+ without ports, <literal>NetworkManager-wait-online.service</literal> blocks until timeout.
+ This is a configuration error.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The property <literal>connection.wait-device-timeout</literal> of the connection
+ profiles waits until the waited devices appear. This is useful if the driver
+ takes a longer time to detect the networking interfaces.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ With Wi-Fi devices, NetworkManager needs to wait for the first scan
+ result to know which networks might be available. That always adds a delay.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ With ethernet devices, NetworkManager waits for carrier until the
+ configurable <literal>[device*].carrier-timeout</literal> is reached.
+ This is because some devices take a long time to detect carrier
+ and it means to boot with cable unplugged, will unnecessarily delay
+ <literal>NetworkManager-wait-online.service</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <literal>NetworkManager-wait-online.service</literal> internally uses
+ <literal>nm-online</literal>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Bugs</title>
+ <para>
+ Please report any bugs in NetworkManager at the
+ <ulink url="https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues">NetworkManager issue tracker</ulink>.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <ulink url="https://networkmanager.dev">NetworkManager home page</ulink>,
+ <link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
+ <link linkend='nm-online'><citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
+ </para>
+ </refsect1>
+</refentry>
diff --git a/man/NetworkManager.xml b/man/NetworkManager.xml
index ca3cd29da8..8f8788856d 100644
--- a/man/NetworkManager.xml
+++ b/man/NetworkManager.xml
@@ -340,6 +340,7 @@
<ulink url="https://networkmanager.dev">NetworkManager home page</ulink>,
<link linkend='NetworkManager.conf'><citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></link>,
<link linkend='NetworkManager-dispatcher'><citerefentry><refentrytitle>NetworkManager-dispatcher</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
+ <link linkend='NetworkManager-wait-online.service'><citerefentry><refentrytitle>NetworkManager-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
<link linkend='nmcli'><citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
<link linkend='nmcli-examples'><citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>7</manvolnum></citerefentry></link>,
<link linkend='nm-online'><citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
diff --git a/man/meson.build b/man/meson.build
index fea0b9dbdc..c814604402 100644
--- a/man/meson.build
+++ b/man/meson.build
@@ -27,6 +27,7 @@ mans_xmls = []
mans = [
['NetworkManager', '8'],
['NetworkManager-dispatcher', '8'],
+ ['NetworkManager-wait-online.service', '8'],
['NetworkManager.conf', '5'],
['nm-online', '1'],
['nmcli-examples', '7'],
diff --git a/man/nm-online.xml b/man/nm-online.xml
index a0db6b3d88..87672f749b 100644
--- a/man/nm-online.xml
+++ b/man/nm-online.xml
@@ -59,14 +59,8 @@
<para>This tool is not very useful to call directly. It is however used by
<literal>NetworkManager-wait-online.service</literal> with
- <literal>--wait-for-startup</literal> argument. This is used to delay
- the service and indirectly <literal>network-online.target</literal>,
- until networking is up. Don't order your own systemd services after
- <literal>NetworkManager-wait-online.service</literal> directly. Instead
- if necessary, order your services after <literal>network-online.target</literal>.
- Even better is to have your services react to network changes dynamically
- and don't order them with respect to <literal>network-online.target</literal>
- at all.
+ <literal>--wait-for-startup</literal> argument
+ (see <link linkend='NetworkManager-wait-online.service'><citerefentry><refentrytitle>NetworkManager-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>).
</para>
<para>By default, connections have the <literal>ipv4.may-fail</literal> and
@@ -118,18 +112,8 @@
<command>nm-online -s</command> will just return immediately, regardless of the
current network state.</para>
<para>There are various ways to affect when startup complete is reached.
- For example, by setting a connection profile to autoconnect, such a profile
- possibly will activate during startup and thus delay startup complete being reached.
- Also, a profile is considered ready when it fully reached the logical <literal>connected</literal>
- state in NetworkManager. That means, properties like <literal>ipv4.may-fail</literal> and <literal>ipv6.may-fail</literal>
- affect whether a certain address family is required. Also, the connection property
- <literal>connection.wait-device-timeout</literal> affects whether to wait for
- the driver to detect a certain device. Generally, a failure of <literal>NetworkManager-wait-online.service</literal>
- indicates a configuration error, where NetworkManager won't be able to reach the
- desired connectivity state during startup. An example for that are bridge or bond master
- profiles, that get autoconnected but without activating any slaves. Such master devices
- hang in activating state indefinitely, and cause <literal>NetworkManager-wait-online.service</literal>
- to fail.
+ For details see
+ <link linkend='NetworkManager-wait-online.service'><citerefentry><refentrytitle>NetworkManager-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>.
</para>
</listitem>
</varlistentry>
@@ -197,7 +181,9 @@
<refsect1 id='see_also'><title>See Also</title>
<para><link linkend='nmcli'><citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
- <link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>.</para>
+ <link linkend='NetworkManager'><citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
+ <link linkend='NetworkManager-wait-online.service'><citerefentry><refentrytitle>NetworkManager-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>.
+ </para>
</refsect1>
</refentry>
diff --git a/src/core/nm-manager.c b/src/core/nm-manager.c
index b459e74e8d..a249797384 100644
--- a/src/core/nm-manager.c
+++ b/src/core/nm-manager.c
@@ -1640,6 +1640,9 @@ check_if_startup_complete(NMManager *self)
return;
}
+ /* Most of our logging is not API/stable, but this line is kinda important and
+ * what people will look for when debugging NetworkManager-wait-online.service.
+ * Take care before rewording this message. */
_LOGI(LOGD_CORE, "startup complete");
priv->startup = FALSE;