diff --git a/Makefile.am b/Makefile.am index af6743ec827e6b49f2f7e08f19673414e2fe316d..1c85805c96b0ac7e73c927f1fd1c58f9e58dc7dd 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 ad1a5b3957f9935971897b32f3bba2d603a9ff39..6f3e312365eea502f4fc938866688231a1abb1a3 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 83bfaa93ae18841a2fb8b926c0ea0d80e464d9ca..a36968d7e98366913d4b67475d9dddf15ea596fa 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 fd98aa24153d01d9aa35693a2c4d68918d3700c4..c89dbc4494a604c401caa4d3dfa134e2eae46b85 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 77b7e0177ca81c06dcae4d624748ee2d28eb6831..442b05aa7deb619320f3f911ab9fff525a392fda 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -71,6 +71,7 @@ + diff --git a/man/NetworkManager-wait-online.service.xml b/man/NetworkManager-wait-online.service.xml new file mode 100644 index 0000000000000000000000000000000000000000..6e514208ee6a12983cc3ba7647804edafb8255b1 --- /dev/null +++ b/man/NetworkManager-wait-online.service.xml @@ -0,0 +1,169 @@ + + + +%entities; +]> + + + + + + NetworkManager-wait-online.service + NetworkManager developers + + + NetworkManager-wait-online.service + 8 + NetworkManager-wait-online.service + Network management daemons + &NM_VERSION; + + + + NetworkManager-wait-online.service + Wait for network to come online + + + + Description + + NetworkManager-wait-online.service delays network-online.target until network + is ready. + + + The systemd target network-online.target acts as a synchronization point + for services to start after network is configured. Such services should + order themselves After=network-online.target + (and never After=NetworkManager-wait-online.service). + NetworkManager-wait-online.service is a one-shot service + that itself is ordered Before=network-online.target + and this way delays the target until the network is configured. + + + NetworkManager-wait-online.service itself is almost not configurable + itself. Instead the connection profiles and configuration in NetworkManager affects + the behavior. + + + In the best case, all services on the system can react to networking changes dynamically and + no service orders itself after network-online.target. That way, + NetworkManager-wait-online.service has no effect and, for example, + does not delay the boot. That means, if the problem is a long boot time related to + NetworkManager-wait-online.service, a possible solution is to + investigate the services that claim to require network and fix those. + + + For services that require network configured, + NetworkManager-wait-online.service 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 NetworkManager-wait-online.service + and replace it with a similar service that better implements the requirement. + + + NetworkManager-wait-online.service blocks until + the 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. + + + There are various reasons what affects NetworkManager reaching "startup complete" + and how long NetworkManager-wait-online.service blocks. + + + + 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 connection.autoconnect-retries + 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. + + + + + When a device reaches activated state, depends on its configuration. + For example, with a profile with both IPv4 and IPv6 addressing + enabled, by device is possibly considered fully activated when + either of the address families is ready. This can be controlled with the + ipv4.may-fail and ipv6.may-fail + settings, to indicate that the address family is required. + There is also ipv4.required-timeout and ipv6.required-timeout + that affects how long for an address family is waited. + Likewise, properties like ipv4.dhcp-timeout and + ipv6.ra-timeout affect how long NetworkManager + will try the IP configuration before giving up. + + + + + For example, a bridge or bond profile cannot do IP configuration + without ports. When booting with such profiles that autoactivate + without ports, NetworkManager-wait-online.service blocks until timeout. + This is a configuration error. + + + + + The property connection.wait-device-timeout 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. + + + + + 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. + + + + + With ethernet devices, NetworkManager waits for carrier until the + configurable [device*].carrier-timeout 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 + NetworkManager-wait-online.service. + + + + + + NetworkManager-wait-online.service internally uses + nm-online. + + + + + Bugs + + Please report any bugs in NetworkManager at the + NetworkManager issue tracker. + + + + + See Also + + NetworkManager home page, + NetworkManager8, + nm-online1, + + + diff --git a/man/NetworkManager.xml b/man/NetworkManager.xml index ca3cd29da8ff3bfdf1cf629713d32f525ddc7ac5..8f8788856ddaa67fed0058ecaf91294fedf0fba7 100644 --- a/man/NetworkManager.xml +++ b/man/NetworkManager.xml @@ -340,6 +340,7 @@ NetworkManager home page, NetworkManager.conf5, NetworkManager-dispatcher8, + NetworkManager-wait-online.service8, nmcli1, nmcli-examples7, nm-online1, diff --git a/man/meson.build b/man/meson.build index fea0b9dbdc83bd7420f6b516b61fe98f9df2b4a9..c81460440280b1dbc8bc288603227aac8b4e4bff 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 a0db6b3d88bb86fd5f99da612727f8c104cb4c05..87672f749bfcd4c19fa31c4aa07d3cd25cfa2345 100644 --- a/man/nm-online.xml +++ b/man/nm-online.xml @@ -59,14 +59,8 @@ This tool is not very useful to call directly. It is however used by NetworkManager-wait-online.service with - --wait-for-startup argument. This is used to delay - the service and indirectly network-online.target, - until networking is up. Don't order your own systemd services after - NetworkManager-wait-online.service directly. Instead - if necessary, order your services after network-online.target. - Even better is to have your services react to network changes dynamically - and don't order them with respect to network-online.target - at all. + --wait-for-startup argument + (see NetworkManager-wait-online.service8). By default, connections have the ipv4.may-fail and @@ -118,18 +112,8 @@ nm-online -s will just return immediately, regardless of the current network state. 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 connected - state in NetworkManager. That means, properties like ipv4.may-fail and ipv6.may-fail - affect whether a certain address family is required. Also, the connection property - connection.wait-device-timeout affects whether to wait for - the driver to detect a certain device. Generally, a failure of NetworkManager-wait-online.service - 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 NetworkManager-wait-online.service - to fail. + For details see + NetworkManager-wait-online.service8. @@ -197,7 +181,9 @@ See Also nmcli1, - NetworkManager8. + NetworkManager8, + NetworkManager-wait-online.service8. +