mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager
synced 2024-10-15 04:24:32 +00:00
man: add NetworkManager-wait-online.service.8 manual
NetworkManager-wait-online is a constant source of confusion, as it seems to delay the boot (when it's often just the messenger or either a network problem, a NetworkManager misconfiguration or a misconfiguration of other systemd services). Try to clear that up with a manual page. https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1130
This commit is contained in:
parent
9e422f01de
commit
df94cb2116
|
@ -5434,11 +5434,12 @@ CLEANFILES += $(man_nm_settings_xml)
|
||||||
endif
|
endif
|
||||||
|
|
||||||
man_pages += \
|
man_pages += \
|
||||||
man/NetworkManager.8 \
|
|
||||||
man/NetworkManager-dispatcher.8 \
|
man/NetworkManager-dispatcher.8 \
|
||||||
|
man/NetworkManager-wait-online.service.8 \
|
||||||
|
man/NetworkManager.8 \
|
||||||
man/NetworkManager.conf.5 \
|
man/NetworkManager.conf.5 \
|
||||||
man/nm-online.1 \
|
|
||||||
man/nm-initrd-generator.8 \
|
man/nm-initrd-generator.8 \
|
||||||
|
man/nm-online.1 \
|
||||||
man/nmcli-examples.7 \
|
man/nmcli-examples.7 \
|
||||||
man/nmcli.1 \
|
man/nmcli.1 \
|
||||||
man/nmtui.1 \
|
man/nmtui.1 \
|
||||||
|
|
|
@ -1325,8 +1325,9 @@ AM_CONDITIONAL(WITH_PYTHON_BLACK, test "${BLACK}" != "")
|
||||||
# check for pregenerated manpages and documentation to be installed
|
# check for pregenerated manpages and documentation to be installed
|
||||||
use_pregen_docs=no
|
use_pregen_docs=no
|
||||||
if test "$build_docs" != "yes" -a \
|
if test "$build_docs" != "yes" -a \
|
||||||
-f "$srcdir"/man/NetworkManager.8 -a \
|
|
||||||
-f "$srcdir"/man/NetworkManager-dispatcher.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/NetworkManager.conf.5 -a \
|
||||||
-f "$srcdir"/man/nm-online.1 -a \
|
-f "$srcdir"/man/nm-online.1 -a \
|
||||||
-f "$srcdir"/man/nmcli-examples.7 -a \
|
-f "$srcdir"/man/nmcli-examples.7 -a \
|
||||||
|
|
|
@ -1039,6 +1039,7 @@ fi
|
||||||
%{_mandir}/man8/nm-initrd-generator.8.gz
|
%{_mandir}/man8/nm-initrd-generator.8.gz
|
||||||
%{_mandir}/man8/NetworkManager.8.gz
|
%{_mandir}/man8/NetworkManager.8.gz
|
||||||
%{_mandir}/man8/NetworkManager-dispatcher.8.gz
|
%{_mandir}/man8/NetworkManager-dispatcher.8.gz
|
||||||
|
%{_mandir}/man8/NetworkManager-wait-online.service.8.gz
|
||||||
%dir %{_localstatedir}/lib/NetworkManager
|
%dir %{_localstatedir}/lib/NetworkManager
|
||||||
%dir %{_sysconfdir}/sysconfig/network-scripts
|
%dir %{_sysconfdir}/sysconfig/network-scripts
|
||||||
%{_datadir}/dbus-1/system-services/org.freedesktop.nm_dispatcher.service
|
%{_datadir}/dbus-1/system-services/org.freedesktop.nm_dispatcher.service
|
||||||
|
|
|
@ -88,6 +88,7 @@ content_files = \
|
||||||
$(top_builddir)/man/NetworkManager.xml \
|
$(top_builddir)/man/NetworkManager.xml \
|
||||||
$(top_builddir)/man/NetworkManager-dispatcher.xml \
|
$(top_builddir)/man/NetworkManager-dispatcher.xml \
|
||||||
$(top_builddir)/man/NetworkManager.conf.xml \
|
$(top_builddir)/man/NetworkManager.conf.xml \
|
||||||
|
$(top_builddir)/man/NetworkManager-wait-online.service.xml \
|
||||||
$(top_builddir)/man/nmcli-examples.xml \
|
$(top_builddir)/man/nmcli-examples.xml \
|
||||||
$(top_builddir)/man/nm-settings-dbus.xml \
|
$(top_builddir)/man/nm-settings-dbus.xml \
|
||||||
$(top_builddir)/man/nm-settings-keyfile.xml \
|
$(top_builddir)/man/nm-settings-keyfile.xml \
|
||||||
|
|
|
@ -71,6 +71,7 @@
|
||||||
<xi:include href="../../man/NetworkManager.xml"/>
|
<xi:include href="../../man/NetworkManager.xml"/>
|
||||||
<xi:include href="../../man/NetworkManager.conf.xml"/>
|
<xi:include href="../../man/NetworkManager.conf.xml"/>
|
||||||
<xi:include href="../../man/NetworkManager-dispatcher.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.xml"/>
|
||||||
<xi:include href="../../man/nmcli-examples.xml"/>
|
<xi:include href="../../man/nmcli-examples.xml"/>
|
||||||
<xi:include href="../../man/nmtui.xml"/>
|
<xi:include href="../../man/nmtui.xml"/>
|
||||||
|
|
169
man/NetworkManager-wait-online.service.xml
Normal file
169
man/NetworkManager-wait-online.service.xml
Normal file
|
@ -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>
|
|
@ -340,6 +340,7 @@
|
||||||
<ulink url="https://networkmanager.dev">NetworkManager home page</ulink>,
|
<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.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-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'><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='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>,
|
<link linkend='nm-online'><citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
|
||||||
|
|
|
@ -27,6 +27,7 @@ mans_xmls = []
|
||||||
mans = [
|
mans = [
|
||||||
['NetworkManager', '8'],
|
['NetworkManager', '8'],
|
||||||
['NetworkManager-dispatcher', '8'],
|
['NetworkManager-dispatcher', '8'],
|
||||||
|
['NetworkManager-wait-online.service', '8'],
|
||||||
['NetworkManager.conf', '5'],
|
['NetworkManager.conf', '5'],
|
||||||
['nm-online', '1'],
|
['nm-online', '1'],
|
||||||
['nmcli-examples', '7'],
|
['nmcli-examples', '7'],
|
||||||
|
|
|
@ -59,14 +59,8 @@
|
||||||
|
|
||||||
<para>This tool is not very useful to call directly. It is however used by
|
<para>This tool is not very useful to call directly. It is however used by
|
||||||
<literal>NetworkManager-wait-online.service</literal> with
|
<literal>NetworkManager-wait-online.service</literal> with
|
||||||
<literal>--wait-for-startup</literal> argument. This is used to delay
|
<literal>--wait-for-startup</literal> argument
|
||||||
the service and indirectly <literal>network-online.target</literal>,
|
(see <link linkend='NetworkManager-wait-online.service'><citerefentry><refentrytitle>NetworkManager-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>).
|
||||||
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.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>By default, connections have the <literal>ipv4.may-fail</literal> and
|
<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
|
<command>nm-online -s</command> will just return immediately, regardless of the
|
||||||
current network state.</para>
|
current network state.</para>
|
||||||
<para>There are various ways to affect when startup complete is reached.
|
<para>There are various ways to affect when startup complete is reached.
|
||||||
For example, by setting a connection profile to autoconnect, such a profile
|
For details see
|
||||||
possibly will activate during startup and thus delay startup complete being reached.
|
<link linkend='NetworkManager-wait-online.service'><citerefentry><refentrytitle>NetworkManager-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>.
|
||||||
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.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -197,7 +181,9 @@
|
||||||
|
|
||||||
<refsect1 id='see_also'><title>See Also</title>
|
<refsect1 id='see_also'><title>See Also</title>
|
||||||
<para><link linkend='nmcli'><citerefentry><refentrytitle>nmcli</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
|
<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>
|
</refsect1>
|
||||||
|
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
Loading…
Reference in a new issue