mirror of
https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git
synced 2026-04-30 23:48:05 +02:00
read-only mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager
e90684a169
Note that D-Bus is fundamentally asynchronous. Doing blocking calls
on top of D-Bus is odd, especially for libnm's NMClient. That is because
NMClient essentially is a client-side cache of the objects from the D-Bus
interface. This cache should be filled exclusively by (asynchronous) D-Bus
events (PropertiesChanged). So, making a blocking D-Bus call means to wait
for a response and return it, while queuing all messages that are received
in the meantime.
Basically there are three ways how a synchronous API on NMClient could behave:
1) the call just calls g_dbus_connection_call_sync(). This means
that libnm sends a D-Bus request via GDBusConnection, and blockingly
waits for the response. All D-Bus messages that get received in the
meantime are queued in the GMainContext that belongs to NMClient.
That means, none of these D-Bus events are processed until we
iterate the GMainContext after the call returns. The effect is,
that NMClient (and all cached objects in there) are unaffected by
the D-Bus request.
Most of the synchronous API calls in libnm are of this kind.
The problem is that the strict ordering of D-Bus events gets
violated.
For some API this is not an immediate problem. Take for example
nm_device_wifi_request_scan(). The call merely blockingly tells
NetworkManager to start scanning, but since NetworkManager's D-Bus
API does not directly expose any state that tells whether we are
currently scanning, this out of order processing of the D-Bus
request is a small issue.
The problem is more obvious for nm_client_networking_set_enabled().
After calling it, NM_CLIENT_NETWORKING_ENABLED is still unaffected
and unchanged, because the PropertiesChanged signal from D-Bus
is not yet processed.
This means, while you make such a blocking call, NMClient's state
does not change. But usually you perform the synchronous call
to change some state. In this form, the blocking call is not useful,
because NMClient only changes the state after iterating the GMainContext,
and not after the blocking call returns.
2) like 1), but after making the blocking g_dbus_connection_call_sync(),
update the NMClient cache artificially. This is what
nm_manager_check_connectivity() does, to "fix" bgo#784629.
This also has the problem of out-of-order events, but it kinda
solves the problem of not changing the state during the blocking
call. But it does so by hacking the state of the cache. I think
this is really wrong because the state should only be updated from
the ordered stream of D-Bus messages (PropertiesChanged signal and
similar). When libnm decides to modify the state, there may be already
D-Bus messages queued that affect this very state.
3) instead of calling g_dbus_connection_call_sync(), use the
asynchronous g_dbus_connection_call(). If we would use a sepaate
GMainContext for all D-Bus related calls, we could ensure that
while we block for the response, we iterate that internal main context.
This might be nice, because all events are processed in order and
after the blocking call returns, the NMClient state is up to date.
The are problems however: current blocking API does not do this,
so it's a significant change in behavior. Also, it might be
unexpected to the user that during the blocking call the entire
content of NMClient's cache might change and all pointers to the
cache might be invalidated. Also, of course NMClient would invoke
signals for all the changes that happen.
Another problem is that this would be more effort to implement
and it involves a small performance overhead for all D-Bus related
calls (because we have to serialize all events in an internal
GMainContext first and then invoke them on the caller's context).
Also, if the users wants this behavior, they could implement it themself
by running libnm in their own GMainContext. Note that libnm might
have bugs to make that really working, but that should be fixed
instead of adding such synchrnous API behavior.
Read also [1], for why blocking calls are wrong.
[1] https://smcv.pseudorandom.co.uk/2008/11/nonblocking/
So, all possible behaviors for synchronous API have severe behavioural
issues. Mark all this API as deprecated. Also, this serves the purpose of
identifying blocking D-Bus calls in libnm.
Note that "deprecated" here does not really mean that the API is going
to be removed. We don't break API. The user may:
- continue to use this API. It's deprecated, awkward and discouraged,
but if it works, by all means use it.
- use asynchronous API. That's the only sensible way to use D-Bus.
If libnm lacks a certain asynchronous counterpart, it should be
added.
- use GDBusConnection directly. There really isn't anything wrong
with D-Bus or GDBusConnection. This deprecated API is just a wrapper
around g_dbus_connection_call_sync(). You may call it directly
without feeling dirty.
---
The only other remainging API is the synchronous GInitable call for
NMClient. That is an entirely separate beast and not particularly
wrong (from an API point of view).
Note that synchronous API in NMSecretAgentOld, NMVpnPluginOld and
NMVpnServicePlugin as not deprecated here. These types are not part
of the D-Bus cache and while they have similar issues, it's less severe
because they have less state.
|
||
|---|---|---|
| clients | ||
| contrib | ||
| data | ||
| dispatcher | ||
| docs | ||
| examples | ||
| introspection | ||
| libnm | ||
| libnm-core | ||
| m4 | ||
| man | ||
| po | ||
| shared | ||
| src | ||
| tools | ||
| vapi | ||
| .dir-locals.el | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| .mailmap | ||
| .travis.yml | ||
| AUTHORS | ||
| autogen.sh | ||
| ChangeLog | ||
| config-extra.h.meson | ||
| config-extra.h.mk | ||
| config.h.meson | ||
| configure.ac | ||
| CONTRIBUTING | ||
| COPYING | ||
| COPYING.GFDL | ||
| COPYING.LGPL | ||
| linker-script-binary.ver | ||
| linker-script-devices.ver | ||
| linker-script-settings.ver | ||
| MAINTAINERS | ||
| Makefile.am | ||
| Makefile.examples | ||
| Makefile.glib | ||
| Makefile.vapigen | ||
| meson.build | ||
| meson_options.txt | ||
| NetworkManager.pc.in | ||
| NEWS | ||
| README | ||
| TODO | ||
| valgrind.suppressions | ||
****************** NetworkManager core daemon has moved to gitlab.freedesktop.org! git clone https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git ****************** Networking that Just Works -------------------------- NetworkManager attempts to keep an active network connection available at all times. The point of NetworkManager is to make networking configuration and setup as painless and automatic as possible. NetworkManager is intended to replace default route, replace other routes, set IP addresses, and in general configure networking as NM sees fit (with the possibility of manual override as necessary). In effect, the goal of NetworkManager is to make networking Just Work with a minimum of user hassle, but still allow customization and a high level of manual network control. If you have special needs, we'd like to hear about them, but understand that NetworkManager is not intended for every use-case. NetworkManager will attempt to keep every network device in the system up and active, as long as the device is available for use (has a cable plugged in, the killswitch isn't turned on, etc). Network connections can be set to 'autoconnect', meaning that NetworkManager will make that connection active whenever it and the hardware is available. "Settings services" store lists of user- or administrator-defined "connections", which contain all the settings and parameters required to connect to a specific network. NetworkManager will _never_ activate a connection that is not in this list, or that the user has not directed NetworkManager to connect to. How it works: The NetworkManager daemon runs as a privileged service (since it must access and control hardware), but provides a D-Bus interface on the system bus to allow for fine-grained control of networking. NetworkManager does not store connections or settings, it is only the mechanism by which those connections are selected and activated. To store pre-defined network connections, two separate services, the "system settings service" and the "user settings service" store connection information and provide these to NetworkManager, also via D-Bus. Each settings service can determine how and where it persistently stores the connection information; for example, the GNOME applet stores its configuration in GConf, and the system settings service stores its config in distro-specific formats, or in a distro- agnostic format, depending on user/administrator preference. A variety of other system services are used by NetworkManager to provide network functionality: wpa_supplicant for wireless connections and 802.1x wired connections, pppd for PPP and mobile broadband connections, DHCP clients for dynamic IP addressing, dnsmasq for proxy nameserver and DHCP server functionality for internet connection sharing, and avahi-autoipd for IPv4 link-local addresses. Most communication with these daemons occurs, again, via D-Bus. Why doesn't my network Just Work? Driver problems are the #1 cause of why NetworkManager sometimes fails to connect to wireless networks. Often, the driver simply doesn't behave in a consistent manner, or is just plain buggy. NetworkManager supports _only_ those drivers that are shipped with the upstream Linux kernel, because only those drivers can be easily fixed and debugged. ndiswrapper, vendor binary drivers, or other out-of-tree drivers may or may not work well with NetworkManager, precisely because they have not been vetted and improved by the open-source community, and because problems in these drivers usually cannot be fixed. Sometimes, command-line tools like 'iwconfig' will work, but NetworkManager will fail. This is again often due to buggy drivers, because these drivers simply aren't expecting the dynamic requests that NetworkManager and wpa_supplicant make. Driver bugs should be filed in the bug tracker of the distribution being run, since often distributions customize their kernel and drivers. Sometimes, it really is NetworkManager's fault. If you think that's the case, please file a bug at: https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues Attaching NetworkManager debug logs from the journal (or wherever your distribution directs syslog's 'daemon' facility output, as /var/log/messages or /var/log/daemon.log) is often very helpful, and (if you can get) a working wpa_supplicant config file helps enormously. See the logging section of file contrib/fedora/rpm/NetworkManager.conf for how to enable debug logging in NetworkManager.