summaryrefslogtreecommitdiff
path: root/docs
Commit message (Collapse)AuthorAgeFilesLines
* all: add "link" settingBeniamino Galvani2023-03-021-0/+1
| | | | | Introduce a new "link" setting that holds properties that are related to the kernel link.
* libnm/docs: fix gtk-doc generation for settingsThomas Haller2023-02-102-4/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Marking "nm-core-types.h" as to be ignored by gtk-doc, causes many files to have the wrong names: /docs/libnm/html/{NMConnection.html => libnm-NMConnection.html} /docs/libnm/html/{NMSetting.html => libnm-NMSetting.html} /docs/libnm/html/{NMSetting6Lowpan.html => libnm-NMSetting6Lowpan.html} /docs/libnm/html/{NMSetting8021x.html => libnm-NMSetting8021x.html} /docs/libnm/html/{NMSettingAdsl.html => libnm-NMSettingAdsl.html} /docs/libnm/html/{NMSettingBluetooth.html => libnm-NMSettingBluetooth.html} /docs/libnm/html/{NMSettingBond.html => libnm-NMSettingBond.html} /docs/libnm/html/{NMSettingBondPort.html => libnm-NMSettingBondPort.html} /docs/libnm/html/{NMSettingBridge.html => libnm-NMSettingBridge.html} /docs/libnm/html/{NMSettingBridgePort.html => libnm-NMSettingBridgePort.html} /docs/libnm/html/{NMSettingCdma.html => libnm-NMSettingCdma.html} /docs/libnm/html/{NMSettingConnection.html => libnm-NMSettingConnection.html} /docs/libnm/html/{NMSettingDcb.html => libnm-NMSettingDcb.html} /docs/libnm/html/{NMSettingDummy.html => libnm-NMSettingDummy.html} /docs/libnm/html/{NMSettingEthtool.html => libnm-NMSettingEthtool.html} /docs/libnm/html/{NMSettingGeneric.html => libnm-NMSettingGeneric.html} /docs/libnm/html/{NMSettingGsm.html => libnm-NMSettingGsm.html} /docs/libnm/html/{NMSettingHostname.html => libnm-NMSettingHostname.html} /docs/libnm/html/{NMSettingIP4Config.html => libnm-NMSettingIP4Config.html} /docs/libnm/html/{NMSettingIP6Config.html => libnm-NMSettingIP6Config.html} /docs/libnm/html/{NMSettingIPConfig.html => libnm-NMSettingIPConfig.html} /docs/libnm/html/{NMSettingIPTunnel.html => libnm-NMSettingIPTunnel.html} /docs/libnm/html/{NMSettingInfiniband.html => libnm-NMSettingInfiniband.html} /docs/libnm/html/{NMSettingMacsec.html => libnm-NMSettingMacsec.html} /docs/libnm/html/{NMSettingMacvlan.html => libnm-NMSettingMacvlan.html} /docs/libnm/html/{NMSettingMatch.html => libnm-NMSettingMatch.html} /docs/libnm/html/{NMSettingOlpcMesh.html => libnm-NMSettingOlpcMesh.html} /docs/libnm/html/{NMSettingOvsBridge.html => libnm-NMSettingOvsBridge.html} /docs/libnm/html/{NMSettingOvsDpdk.html => libnm-NMSettingOvsDpdk.html} /docs/libnm/html/{NMSettingOvsExternalIDs.html => libnm-NMSettingOvsExternalIDs.html} /docs/libnm/html/{NMSettingOvsInterface.html => libnm-NMSettingOvsInterface.html} /docs/libnm/html/{NMSettingOvsPatch.html => libnm-NMSettingOvsPatch.html} /docs/libnm/html/{NMSettingOvsPort.html => libnm-NMSettingOvsPort.html} /docs/libnm/html/{NMSettingPpp.html => libnm-NMSettingPpp.html} /docs/libnm/html/{NMSettingPppoe.html => libnm-NMSettingPppoe.html} /docs/libnm/html/{NMSettingProxy.html => libnm-NMSettingProxy.html} /docs/libnm/html/{NMSettingSerial.html => libnm-NMSettingSerial.html} /docs/libnm/html/{NMSettingSriov.html => libnm-NMSettingSriov.html} /docs/libnm/html/{NMSettingTCConfig.html => libnm-NMSettingTCConfig.html} /docs/libnm/html/{NMSettingTeam.html => libnm-NMSettingTeam.html} /docs/libnm/html/{NMSettingTeamPort.html => libnm-NMSettingTeamPort.html} /docs/libnm/html/{NMSettingTun.html => libnm-NMSettingTun.html} /docs/libnm/html/{NMSettingUser.html => libnm-NMSettingUser.html} /docs/libnm/html/{NMSettingVeth.html => libnm-NMSettingVeth.html} /docs/libnm/html/{NMSettingVlan.html => libnm-NMSettingVlan.html} /docs/libnm/html/{NMSettingVpn.html => libnm-NMSettingVpn.html} /docs/libnm/html/{NMSettingVrf.html => libnm-NMSettingVrf.html} /docs/libnm/html/{NMSettingVxlan.html => libnm-NMSettingVxlan.html} /docs/libnm/html/{NMSettingWifiP2P.html => libnm-NMSettingWifiP2P.html} /docs/libnm/html/{NMSettingWimax.html => libnm-NMSettingWimax.html} /docs/libnm/html/{NMSettingWireGuard.html => libnm-NMSettingWireGuard.html} /docs/libnm/html/{NMSettingWired.html => libnm-NMSettingWired.html} /docs/libnm/html/{NMSettingWireless.html => libnm-NMSettingWireless.html} /docs/libnm/html/{NMSettingWirelessSecurity.html => libnm-NMSettingWirelessSecurity.html} /docs/libnm/html/{NMSettingWpan.html => libnm-NMSettingWpan.html} /docs/libnm/html/{NMSimpleConnection.html => libnm-NMSimpleConnection.html} Revert that part of the change. Even if this regresses other problems. Fixes: 1330292d057c ('docs/libnm: fix gtkdoc-scan ignore lists')
* ovs: add support for "other_config" settingsThomas Haller2023-01-111-0/+1
| | | | | | See `man ovs-vswitchd.conf.db` for documentation of "other_config" keys. https://bugzilla.redhat.com/show_bug.cgi?id=2151455
* support loopback interfaceWen Liang2022-11-233-0/+4
| | | | | | | | | Support managing the loopback interface through NM as the users want to set the proper mtu for loopback interface when forwarding the packets. Additionally, the IP addresses, DNS, route and routing rules are also allowed to configure for the loopback connection profiles. https://bugzilla.redhat.com/show_bug.cgi?id=2060905
* docs/libnm: include a couple more files generated from headersLubomir Rintel2022-11-131-0/+4
| | | | | These are part of the public API. Not including them makes links from API index dead (and sad).
* libnm,docs: ignore NM_DEPRECATED_IN_..._GUARDSLubomir Rintel2022-11-132-2/+2
| | | | | | | | | | | | | | gtk-doc gets confused by these, ignore them: common.py:ParseFunctionDeclaration:541:WARNING:Cannot parse args for function in "nm_device_get_hw_address) const char *nm_device_dummy_get_hw_address(NMDeviceDummy *device common.py:ParseFunctionDeclaration:541:WARNING:Cannot parse args for function in "nm_device_get_ports) const GPtrArray *nm_device_ovs_port_get_slaves(NMDeviceOvsPort *device For some reason it's still confused if NM_AVAILABLE_* comes first. I refuse to look into that, just reorder them.
* docs/libnm: fix gtkdoc-scan ignore listsLubomir Rintel2022-11-132-40/+20
| | | | | | | | | These went out of date and now all sorts of useless junk is included in the libnm documentation They contain everything outside *-public/ (perhaps they could be generated, but I'm not doing that) and nm-core-types.h (because that one confuses gtk-doc in an outrageous manner).
* docs/api: fix ugly things in MakefileLubomir Rintel2022-11-081-14/+2
| | | | | | | | | | | | | | | | | | | | Turns out automake doesn't like either that we add dependencies to a target conditionally. Not sure why, but it's a tasteless thing to do nevertheless: gtk-doc.make:174: warning: $(DOC_MAIN_SGML_FILE) was already defined in condition BUILD_DOCS, which is included in condition TRUE ... docs/api/Makefile.am:112: 'gtk-doc.make' included from here docs/api/Makefile.am:14: ... '$(DOC_MAIN_SGML_FILE)' previously defined here In any case, the dependency is wrong in the first place -- the source document doesn't depend on other source. The target (which is a stamp file, since the xslt processor produces multiple files) does! Moreover, there's a dependency of the stamp file on $(content_files) already, so including GENERATED_FILES (like we already do) in content_files should be sufficient. While at that, deal with other not-so-nice things; don't extend "all" target needlessly and don't define a target conditionally.
* docs: add "sandboxing.md"Thomas Haller2022-03-281-0/+109
|
* man: add NetworkManager-wait-online.service.8 manualThomas Haller2022-03-022-0/+2
| | | | | | | | | | | 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
* docs: update URL for latest online documentationThomas Haller2021-09-242-4/+4
|
* build: sort filename alphabetically in Makefile.am and similarThomas Haller2021-08-261-4/+4
| | | | | The question is what "alphabetically" means (as it depends on collation). To me, it means ":sort" in `LANG=en_US.UTF-8 vim`.
* bond: add support of queue_id of bond portGris Ge2021-08-261-0/+1
| | | | | | | | | | | | | | | | Introduced `NMSettingBondPort` to hold the new setting class with single property `NM_SETTING_BOND_PORT_QUEUE_ID`. For dbus interface, please use `bond-port` as setting name and `queue-id` as property name. Unit test cases for ifcfg reader and writer included. Signed-off-by: Gris Ge <fge@redhat.com> https://bugzilla.redhat.com/show_bug.cgi?id=1949127 https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/952
* docs: fix reference to "main" branch in docsThomas Haller2021-04-011-1/+1
|
* man: split NetworkManager-dispatcher(8) manual page out of NetworkManager(8)Thomas Haller2021-03-162-0/+2
| | | | https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/784
* base: move "libnm-core-intern/nm-core-types-internal.h" to libnm-baseThomas Haller2021-03-052-2/+0
| | | | | "libnm-platform" has no dependency on libnm-core. To have the symbols accessible, move them to libnm-base.
* build: move "libnm/" to "src/" and split itThomas Haller2021-02-242-8/+11
| | | | | | Like with "libnm-core/", split "libnm/" into different directories for the public headers, for the implementation and for the helper "aux" library.
* build: move "libnm-core/" to "src/" and split itThomas Haller2021-02-184-17/+17
| | | | | | | | | | | | | | | | | | | | "libnm-core/" is rather complicated. It provides a static library that is linked into libnm.so and NetworkManager. It also contains public headers (like "nm-setting.h") which are part of public libnm API. Then we have helper libraries ("libnm-core/nm-libnm-core-*/") which only rely on public API of libnm-core, but are themself static libraries that can be used by anybody who uses libnm-core. And "libnm-core/nm-libnm-core-intern" is used by libnm-core itself. Move "libnm-core/" to "src/". But also split it in different directories so that they have a clearer purpose. The goal is to have a flat directory hierarchy. The "src/libnm-core*/" directories correspond to the different modules (static libraries and set of headers that we have). We have different kinds of such modules because of how we combine various code together. The directory layout now reflects this.
* all: add "libnm-core/nm-default-libnm-core.h" as replacement for "nm-default.h"Thomas Haller2021-02-092-0/+2
|
* libnm/docs: hook up new nm-keyfile API in libnm documentationThomas Haller2021-02-021-0/+1
|
* libnm: split ethtool option names to a new header ↵Thomas Haller2021-01-152-2/+2
| | | | | | | | | | | | | | | "libnm-core/nm-ethtool-utils.h" We want to use these defines for option names also in "shared/nm-base" (and in turn in "shared/nm-platform), which cannot include "libnm-core". However, they are also public API of libnm. To get this done, in a first step, move these defines to a new header "libnm-core/nm-ethtool-utils.h". Since now the name "nm-ethtool-utils.h" is taken, also rename nm-libnm-core-intern files.
* all: update deprecated SPDX license identifiersThomas Haller2021-01-053-3/+3
| | | | | | | | | | | | | | | | These SPDX license identifiers are deprecated ([1]). Update them. [1] https://spdx.org/licenses/ sed \ -e '1 s%^/\* SPDX-License-Identifier: \(GPL-2.0\|LGPL-2.1\)+ \*/$%/* SPDX-License-Identifier: \1-or-later */%' \ -e '1,2 s%^\(--\|#\|//\) SPDX-License-Identifier: \(GPL-2.0\|LGPL-2.1\)+$%\1 SPDX-License-Identifier: \2-or-later%' \ -i \ $(git grep -l SPDX-License-Identifier -- \ ':(exclude)shared/c-*/' \ ':(exclude)shared/n-*/' \ ':(exclude)shared/systemd/src' \ ':(exclude)src/systemd/src')
* man: add `man 8 nm-cloud-setup`Thomas Haller2020-12-112-0/+5
| | | | | https://bugzilla.redhat.com/show_bug.cgi?id=1867997 https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/ ## 600
* build: ignore "docs/api/NetworkManager.actions" build artifactThomas Haller2020-12-032-11/+24
| | | | | | I still don't understand why we get now these ".actions" build artifacts. Anyway, I don't think we need to care. Just ignore it.
* veth: add support to configure veth interfacesFernando Fernandez Mancera2020-11-271-0/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | NetworkManager is now able to configure veth interfaces throught the NMSettingVeth. Veth interfaces only have "peer" property. In order to support Veth interfaces in NetworkManager the design need to pass the following requirements: * Veth setting only has "peer" attribute. * Ethernet profiles must be applicable to Veth interfaces. * When creating a veth interface, the peer will be managed by NetworkManager but will not have a profile. * Veth connection can reapply only if the peer has not been modified. * In order to modify the veth peer, NetworkManager must deactivate the connection and create a new one with peer modified. In general, it should support the basis of veth interfaces but without breaking any existing feature or use case. The users that are using veth interfaces as ethernet should not notice anything changed unless they specified the veth peer setting. Creating a Veth interface in NetworkManager is useful even without the support for namespaces for some use cases, e.g "connecting one side of the veth to an OVS bridge and the other side to a Linux bridge" this is done when using OVN kubernetes [1][2]. In addition, it would provide persistent configuration and rollback support for Veth interfaces. [1] https://bugzilla.redhat.com/show_bug.cgi?id=1885605 [2] https://bugzilla.redhat.com/show_bug.cgi?id=1894139 Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net>
* all: add hostname settingBeniamino Galvani2020-11-161-0/+1
| | | | | Add a new setting that contains properties related to how NM should get the hostname from the connection.
* libnm: add NMSettingOvsExternalIDsThomas Haller2020-11-091-0/+1
|
* Makefile: remove "libnm.actions" explicitly when uninstallingFernando Fernandez Mancera2020-10-261-0/+2
| | | | | | | | | | | | | | | | | | | | | On Fedora 33 when compiling NetworkManager it is failing with the following error: ``` ERROR: files left in build directory after distclean: ./docs/libnm/libnm.actions make[1]: *** [Makefile:18427: distcleancheck] Error 1 make[1]: Leaving directory '/builddir/nm-build/NetworkManager/NetworkManager-1.27.90/_build/sub' make: *** [Makefile:18356: distcheck] Error 1 Error make distcheck ``` Adding the file to the DISTCLEANFILES will enforce the removal of this file. Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net> https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/659
* all: fix minor typosYuri Chornoivan2020-07-071-1/+1
| | | | https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/565
* docs: move "nm-settings-docs-{dbus,nmcli}.xml" from "libnm/" to "man/"Thomas Haller2020-06-111-1/+1
| | | | | | | | | | | | "nm-settings-docs-nmcli.xml" will be generated by a tool that depends on "clients/common/". The file should thus not be in libnm directory, otherwise there is a circular dependency. Move the file to "man/" directory. For consistency, also move "nm-settings-docs-dbus.xml". Note that we cannot move "nm-settings-docs-gir.xml" to "man/", because that one is needed for building clients.
* all: move "shared/nm-libnm-aux" to "libnm/nm-libnm-aux"Thomas Haller2020-06-111-0/+2
| | | | | | | | Like the previous commit. Move code that depends on libnm out of shared to avoid circular dependency. Also add a readme file explaining the reason for existence of the helper library.
* all: move "shared/nm-libnm-core-aux" to "libnm-core/nm-libnm-core-aux"Thomas Haller2020-06-112-0/+6
| | | | | | | | Like the previous commit. Move code that depends on libnm-core out of shared to avoid circular dependency. Also add a readme file explaining the reason for existence of the helper libraries nm-libnm-core-intern and nm-libnm-core-aux.
* all: move "shared/nm-libnm-core-intern" to "libnm-core/nm-libnm-core-intern"Thomas Haller2020-06-112-0/+10
| | | | | | | | | | | | | | | | The "shared" directory is used by libnm-core, it should thus only depend on code that is in the "shared" directory. Otherwise there is a circular dependency, and meson's subdir() does not work nicely. Also, libnm-core is really part of (and also an extension of) libnm-core, so it belongs there. I guess, the original idea was that this is also an extension for libnm, so another project could take these utility functions (by copying them into their source tree) and use them. That is still possible, it's just that the sources are no longer under the shared directory. Also add a readme to explain the non-obvious meaning of these files.
* all: move "shared/nm-keyfile" to "libnm-core/nm-keyfile"Thomas Haller2020-06-112-10/+16
| | | | | | | | | | | | | | | | | | | | Originally, these files were part of libnm-core and linked together. However, that is a licensing violation, because the code is GPL-2.0+ licensed, while libnm-core also gets linked with libnm (it must thus be LGPL-2.1+). The original intent behind moving the code to "shared/" was to avoid the licensing issue, but also to prepare when we would add a separate, GPL licensed libnm-keyfile. However, currently we hope to be able to relicense the code, so that it actually could be exposed as part of libnm. This is work in progress at ([1]). [1] https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/ ## 517 Anyway, the current directory layout is problematic. libnm-keyfile depends on libnm-core, while libnm-core depends on code under shared. That means, there is a circular dependency and meson's subdir() does not work well. Move the code.
* docs: add more nm-settings manpages (dbus,nmcli,keyfile,ifcfg-rh)Thomas Haller2020-06-112-2/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | A significant part of NetworkManager's API are the connection profiles, documented in `man nm-settings*`. But there are different aspects about profiles, depending on what you are interested. There is the D-Bus API, nmcli options, keyfile format, and ifcfg-rh format. Additionally, there is also libnm API. Add distinct manual pages for the four aspects. Currently the two new manual pages "nm-settings-dbus" and "nm-settings-nmcli" are still identical to the former "nm-settings.5" manual. In the future, they will diverge to account for the differences. There are the following aspects: - "dbus" - "keyfile" - "ifcfg-rh" - "nmcli" For "libnm" we don't generate a separate "nm-settings-libnm" manual page. That is instead documented via gtk-doc. Currently the keyfile and ifcfg-rh manual pages only detail settings which differ. But later I think also these manual pages should contain all settings that apply.
* docs: rename "nm-settings-docs.xml" to "nm-settings-docs-dbus.xml"Thomas Haller2020-06-112-2/+2
| | | | | | "nm-settings-docs-dbus.xml" is "nm-settings-docs-gir.xml" merged with "nm-property-infos-dbus.xml". The name should reflect that, also because we will get more files with this naming scheme.
* docs: fix dependency of "nm-settings*xml" to "common.ent"Thomas Haller2020-06-111-1/+20
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | "man/nm-settings%.xml" really should depend on "common.ent". The reason is that XSL files like "man/nm-settings.xsl" include "common.ent". The previous code already tried to express that, but for some reasons this dependency was not honored. Fix that. However, that uncovers another problem with gtk-doc.make. If we do that without the workaround for "docs/api/Makefile.am", then $ ./autogen.sh && make V=1 SHELL='sh -x' distcheck breaks. The reason is not clear to me. The new dependency leads to rebuild "man/nm-settings-keyfile.xml". But that is worse, somehow the file "$(top_srcdir)/man/nm-settings-keyfile.xml" ends up being read-only. Afterwards, gtk-doc.make does setup-build.stamp: -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ if test "x$$files" != "x" ; then \ for file in $$files ; do \ destdir=`dirname $(abs_builddir)/$$file`; \ test -d "$$destdir" || mkdir -p "$$destdir"; \ test -f $(abs_srcdir)/$$file && \ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ done; \ fi; \ fi $(AM_V_at)touch setup-build.stamp so that the files in build dir are also read-only. Then, make distcheck goes ahead and builds the files once again, which fails. You are welcome to understand why this workaround is necessary. Please then create a better fix.
* license: Add license using SPDX identifiers to meson build filesIñigo Martínez2020-02-173-0/+6
| | | | | License is missing in meson build files. This has been added using SPDX identifiers and licensed under LGPL-2.1+.
* core,libnm: add VRF supportBeniamino Galvani2020-01-142-0/+2
| | | | | | | | Add VRF support to the daemon. When the device we are activating is a VRF or a VRF's slave, put routes in the table specified by the VRF connection. Also, introduce a VRF device type in libnm.
* libnm-core,cli: add VRF settingBeniamino Galvani2020-01-141-0/+1
| | | | | Add new VRF setting and connection types to libnm-core and support them in nmcli.
* libnm: refactor caching of D-Bus objects in NMClientThomas Haller2019-11-252-2/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | No longer use GDBusObjectMangaerClient and gdbus-codegen generated classes for the NMClient cache. Instead, use GDBusConnection directly and a custom implementation (NMLDBusObject) for caching D-Bus' ObjectManager data. CHANGES ------- - This is a complete rework. I think the previous implementation was difficult to understand. There were unfixed bugs and nobody understood the code well enough to fix them. Maybe somebody out there understood the code, but I certainly did not. At least nobody provided patches to fix those issues. I do believe that this implementation is more straightforward and easier to understand. It removes a lot of layers of code. Whether this claim of simplicity is true, each reader must decide for himself/herself. Note that it is still fairly complex. - There was a lingering performance issue with large number of D-Bus objects. The patch tries hard that the implementation scales well. Of course, when we cache N objects that have N-to-M references to other, we still are fundamentally O(N*M) for runtime and memory consumption (with M being the number of references between objects). But each part should behave efficiently and well. - Play well with GMainContext. libnm code (NMClient) is generally not thread safe. However, it should work to use multiple instances in parallel, as long as each access to a NMClient is through the caller's GMainContext. This follows glib's style and effectively allows to use NMClient in a multi threaded scenario. This implies to stick to a main context upon construction and ensure that callbacks are only invoked when iterating that context. Also, NMClient itself shall never iterate the caller's context. This also means, libnm must never use g_idle_add() or g_timeout_add(), as those enqueue sources in the g_main_context_default() context. - Get ordering of messages right. All events are consistently enqueued in a GMainContext and processed strictly in order. For example, previously "nm-object.c" tried to combine signals and emit them on an idle handler. That is wrong, signals must be emitted in the right order and when they happen. Note that when using GInitable's synchronous initialization to initialize the NMClient instance, NMClient internally still operates fully asynchronously. In that case NMClient has an internal main context. - NMClient takes over most of the functionality. When using D-Bus' ObjectManager interface, one needs to handle basically the entire state of the D-Bus interface. That cannot be separated well into distinct parts, and even if you try, you just end up having closely related code in different source files. Spreading related code does not make it easier to understand, on the contrary. That means, NMClient is inherently complex as it contains most of the logic. I think that is not avoidable, but it's not as bad as it sounds. - NMClient processes D-Bus messages and state changes in separate steps. First NMClient unpacks the message (e.g. _dbus_handle_properties_changed()) and keeps track of the changed data. Then we update the GObject instances (_dbus_handle_obj_changed_dbus()) without emitting any signals yet. Finally, we emit all signals and notifications that were collected (_dbus_handle_changes_commit()). Note that for example during the initial GetManagedObjects() reply, NMClient receive a large amount of state at once. But we first apply all the changes to our GObject instances before emitting any signals. The result is that signals are always emitted in a moment when the cache is consistent. The unavoidable downside is that when you receive a property changed signal, possibly many other properties changed already and more signals are about to be emitted. - NMDeviceWifi no longer modifies the content of the cache from client side during poke_wireless_devices_with_rf_status(). The content of the cache should be determined by D-Bus alone and follow what NetworkManager service exposes. Local modifications should be avoided. - This aims to bring no API/ABI change, though it does of course bring various subtle changes in behavior. Those should be all for the better, but the goal is not to break any existing clients. This does change internal (albeit externally visible) API, like dropping NM_OBJECT_DBUS_OBJECT_MANAGER property and NMObject no longer implementing GInitableIface and GAsyncInitableIface. - Some uses of gdbus-codegen classes remain in NMVpnPluginOld, NMVpnServicePlugin and NMSecretAgentOld. These are independent of NMClient/NMObject and should be reworked separately. - While we no longer use generated classes from gdbus-codegen, we don't need more glue code than before. Also before we constructed NMPropertiesInfo and a had large amount of code to propagate properties from NMDBus* to NMObject. That got completely reworked, but did not fundamentally change. You still need about the same effort to create the NMLDBusMetaIface. Not using generated bindings did not make anything worse (which tells about the usefulness of generated code, at least in the way it was used). - NMLDBusMetaIface and other meta data is static and immutable. This avoids copying them around. Also, macros like NML_DBUS_META_PROPERTY_INIT_U() have compile time checks to ensure the property types matches. It's pretty hard to misuse them because it won't compile. - The meta data now explicitly encodes the expected D-Bus types and makes sure never to accept wrong data. That would only matter when the server (accidentally or intentionally) exposes unexpected types on D-Bus. I don't think that was previously ensured in all cases. For example, demarshal_generic() only cared about the GObject property type, it didn't know the expected D-Bus type. - Previously GDBusObjectManager would sometimes emit warnings (g_log()). Those probably indicated real bugs. In any case, it prevented us from running CI with G_DEBUG=fatal-warnings, because there would be just too many unrelated crashes. Now we log debug messages that can be enabled with "LIBNM_CLIENT_DEBUG=trace". Some of these messages can also be turned into g_warning()/g_critical() by setting LIBNM_CLIENT_DEBUG=warning,error. Together with G_DEBUG=fatal-warnings, this turns them into assertions. Note that such "assertion failures" might also happen because of a server bug (or change). Thus these are not common assertions that indicate a bug in libnm and are thus not armed unless explicitly requested. In our CI we should now always run with LIBNM_CLIENT_DEBUG=warning,error and G_DEBUG=fatal-warnings and to catch bugs. Note that currently NetworkManager has bugs in this regard, so enabling this will result in assertion failures. That should be fixed first. - Note that this changes the order in which we emit "notify:devices" and "device-added" signals. I think it makes the most sense to emit first "device-removed", then "notify:devices", and finally "device-added" signals. This changes behavior for commit 52ae28f6e5bf ('libnm: queue added/removed signals and suppress uninitialized notifications'), but I don't think that users should actually rely on the order. Still, the new order makes the most sense to me. - In NetworkManager, profiles can be invisible to the user by setting "connection.permissions". Such profiles would be hidden by NMClient's nm_client_get_connections() and their "connection-added"/"connection-removed" signals. Note that NMActiveConnection's nm_active_connection_get_connection() and NMDevice's nm_device_get_available_connections() still exposes such hidden NMRemoteConnection instances. This behavior was preserved. NUMBERS ------- I compared 3 versions of libnm. [1] 962297f9085d, current tip of nm-1-20 branch [2] 4fad8c7c642e, current master, immediate parent of this patch [3] this patch All tests were done on Fedora 31, x86_64, gcc 9.2.1-1.fc31. The libraries were build with $ ./contrib/fedora/rpm/build_clean.sh -g -w test -W debug Note that RPM build already stripped the library. --- N1) File size of libnm.so.0.1.0 in bytes. There currently seems to be a issue on Fedora 31 generating wrong ELF notes. Usually, libnm is smaller but in these tests it had large (and bogus) ELF notes. Anyway, the point is to show the relative sizes, so it doesn't matter). [1] 4075552 (102.7%) [2] 3969624 (100.0%) [3] 3705208 ( 93.3%) --- N2) `size /usr/lib64/libnm.so.0.1.0`: text data bss dec hex filename [1] 1314569 (102.0%) 69980 ( 94.8%) 10632 ( 80.4%) 1395181 (101.4%) 1549ed /usr/lib64/libnm.so.0.1.0 [2] 1288410 (100.0%) 73796 (100.0%) 13224 (100.0%) 1375430 (100.0%) 14fcc6 /usr/lib64/libnm.so.0.1.0 [3] 1229066 ( 95.4%) 65248 ( 88.4%) 13400 (101.3%) 1307714 ( 95.1%) 13f442 /usr/lib64/libnm.so.0.1.0 --- N3) Performance test with test-client.py. With checkout of [2], run ``` prepare_checkout() { rm -rf /tmp/nm-test && \ git checkout -B test 4fad8c7c642e && \ git clean -fdx && \ ./autogen.sh --prefix=/tmp/nm-test && \ make -j 5 install && \ make -j 5 check-local-clients-tests-test-client } prepare_test() { NM_TEST_REGENERATE=1 NM_TEST_CLIENT_BUILDDIR="/data/src/NetworkManager" NM_TEST_CLIENT_NMCLI_PATH=/usr/bin/nmcli python3 ./clients/tests/test-client.py -v } do_test() { for i in {1..10}; do NM_TEST_CLIENT_BUILDDIR="/data/src/NetworkManager" NM_TEST_CLIENT_NMCLI_PATH=/usr/bin/nmcli python3 ./clients/tests/test-client.py -v || return -1 done echo "done!" } prepare_checkout prepare_test time do_test ``` [1] real 2m14.497s (101.3%) user 5m26.651s (100.3%) sys 1m40.453s (101.4%) [2] real 2m12.800s (100.0%) user 5m25.619s (100.0%) sys 1m39.065s (100.0%) [3] real 1m54.915s ( 86.5%) user 4m18.585s ( 79.4%) sys 1m32.066s ( 92.9%) --- N4) Performance. Run NetworkManager from build [2] and setup a large number of profiles (551 profiles and 515 devices, mostly unrealized). This setup is already at the edge of what NetworkManager currently can handle. Of course, that is a different issue. Here we just check how long plain `nmcli` takes on the system. ``` do_cleanup() { for UUID in $(nmcli -g NAME,UUID connection show | sed -n 's/^xx-c-.*:\([^:]\+\)$/\1/p'); do nmcli connection delete uuid "$UUID" done for DEVICE in $(nmcli -g DEVICE device status | grep '^xx-i-'); do nmcli device delete "$DEVICE" done } do_setup() { do_cleanup for i in {1..30}; do nmcli connection add type bond autoconnect no con-name xx-c-bond-$i ifname xx-i-bond-$i ipv4.method disabled ipv6.method ignore for j in $(seq $i 30); do nmcli connection add type vlan autoconnect no con-name xx-c-vlan-$i-$j vlan.id $j ifname xx-i-vlan-$i-$j vlan.parent xx-i-bond-$i ipv4.method disabled ipv6.method ignore done done systemctl restart NetworkManager.service sleep 5 } do_test() { perf stat -r 50 -B nmcli 1>/dev/null } do_test ``` [1] Performance counter stats for 'nmcli' (50 runs): 456.33 msec task-clock:u # 1.093 CPUs utilized ( +- 0.44% ) 0 context-switches:u # 0.000 K/sec 0 cpu-migrations:u # 0.000 K/sec 5,900 page-faults:u # 0.013 M/sec ( +- 0.02% ) 1,408,675,453 cycles:u # 3.087 GHz ( +- 0.48% ) 1,594,741,060 instructions:u # 1.13 insn per cycle ( +- 0.02% ) 368,744,018 branches:u # 808.061 M/sec ( +- 0.02% ) 4,566,058 branch-misses:u # 1.24% of all branches ( +- 0.76% ) 0.41761 +- 0.00282 seconds time elapsed ( +- 0.68% ) [2] Performance counter stats for 'nmcli' (50 runs): 477.99 msec task-clock:u # 1.088 CPUs utilized ( +- 0.36% ) 0 context-switches:u # 0.000 K/sec 0 cpu-migrations:u # 0.000 K/sec 5,948 page-faults:u # 0.012 M/sec ( +- 0.03% ) 1,471,133,482 cycles:u # 3.078 GHz ( +- 0.36% ) 1,655,275,369 instructions:u # 1.13 insn per cycle ( +- 0.02% ) 382,595,152 branches:u # 800.433 M/sec ( +- 0.02% ) 4,746,070 branch-misses:u # 1.24% of all branches ( +- 0.49% ) 0.43923 +- 0.00242 seconds time elapsed ( +- 0.55% ) [3] Performance counter stats for 'nmcli' (50 runs): 352.36 msec task-clock:u # 1.027 CPUs utilized ( +- 0.32% ) 0 context-switches:u # 0.000 K/sec 0 cpu-migrations:u # 0.000 K/sec 4,790 page-faults:u # 0.014 M/sec ( +- 0.26% ) 1,092,341,186 cycles:u # 3.100 GHz ( +- 0.26% ) 1,209,045,283 instructions:u # 1.11 insn per cycle ( +- 0.02% ) 281,708,462 branches:u # 799.499 M/sec ( +- 0.01% ) 3,101,031 branch-misses:u # 1.10% of all branches ( +- 0.61% ) 0.34296 +- 0.00120 seconds time elapsed ( +- 0.35% ) --- N5) same setup as N4), but run `PAGER= /bin/time -v nmcli`: [1] Command being timed: "nmcli" User time (seconds): 0.42 System time (seconds): 0.04 Percent of CPU this job got: 107% Elapsed (wall clock) time (h:mm:ss or m:ss): 0:00.43 Average shared text size (kbytes): 0 Average unshared data size (kbytes): 0 Average stack size (kbytes): 0 Average total size (kbytes): 0 Maximum resident set size (kbytes): 34456 Average resident set size (kbytes): 0 Major (requiring I/O) page faults: 0 Minor (reclaiming a frame) page faults: 6128 Voluntary context switches: 1298 Involuntary context switches: 1106 Swaps: 0 File system inputs: 0 File system outputs: 0 Socket messages sent: 0 Socket messages received: 0 Signals delivered: 0 Page size (bytes): 4096 Exit status: 0 [2] Command being timed: "nmcli" User time (seconds): 0.44 System time (seconds): 0.04 Percent of CPU this job got: 108% Elapsed (wall clock) time (h:mm:ss or m:ss): 0:00.44 Average shared text size (kbytes): 0 Average unshared data size (kbytes): 0 Average stack size (kbytes): 0 Average total size (kbytes): 0 Maximum resident set size (kbytes): 34452 Average resident set size (kbytes): 0 Major (requiring I/O) page faults: 0 Minor (reclaiming a frame) page faults: 6169 Voluntary context switches: 1849 Involuntary context switches: 142 Swaps: 0 File system inputs: 0 File system outputs: 0 Socket messages sent: 0 Socket messages received: 0 Signals delivered: 0 Page size (bytes): 4096 Exit status: 0 [3] Command being timed: "nmcli" User time (seconds): 0.32 System time (seconds): 0.02 Percent of CPU this job got: 102% Elapsed (wall clock) time (h:mm:ss or m:ss): 0:00.34 Average shared text size (kbytes): 0 Average unshared data size (kbytes): 0 Average stack size (kbytes): 0 Average total size (kbytes): 0 Maximum resident set size (kbytes): 29196 Average resident set size (kbytes): 0 Major (requiring I/O) page faults: 0 Minor (reclaiming a frame) page faults: 5059 Voluntary context switches: 919 Involuntary context switches: 685 Swaps: 0 File system inputs: 0 File system outputs: 0 Socket messages sent: 0 Socket messages received: 0 Signals delivered: 0 Page size (bytes): 4096 Exit status: 0 --- N6) same setup as N4), but run `nmcli monitor` and look at `ps aux` for the RSS size. USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND [1] me 1492900 21.0 0.2 461348 33248 pts/10 Sl+ 15:02 0:00 nmcli monitor [2] me 1490721 5.0 0.2 461496 33548 pts/10 Sl+ 15:00 0:00 nmcli monitor [3] me 1495801 16.5 0.1 459476 28692 pts/10 Sl+ 15:04 0:00 nmcli monitor
* build/meson: cleanup configuration_data() for pathsThomas Haller2019-11-223-5/+2
| | | | | | | | | | | We don't need such data duplicated. The build setup should have only one configuration_data() for patching such values. Now we only have one global, immutable data_conf dictionary with configuration values. Note that none of the users of data_conf uses all entries, but as the entries are basically only dependent on the meson/configure option and valid for the entire project, this simplifies to handling.
* libnm: deprecate synchronous/blocking API in libnmThomas Haller2019-10-031-0/+119
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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.
* meson: Improve api documentation build fileIñigo Martínez2019-10-011-22/+29
| | | | | | | | | | | | the `doc_module` variable has been removed. It was created because its used in the autotools build file but actually `nm_name` variable can be used easily. Different objects used in the documentation target have been grouped together. The content file `version.xml`, and different build files are now added properly.
* meson: Improve libnm documentation build fileIñigo Martínez2019-10-011-17/+20
| | | | | | | | | | | the `doc_module` variable has been removed. It was created because its used in the autotools build file but actually `libnm_name` variable can be used easily. Different objects used in the documentation target have been grouped together. The content file `version.xml` is now added properly.
* meson: Avoid the use of source_root and build_root methodsIñigo Martínez2019-10-011-2/+2
| | | | | | | | The way some directory paths are defined has also been changed to avoid the use of the `source_root` and `build_root` functions because they are discouraged[0] [0] https://wiki.gnome.org/Initiatives/GnomeGoals/MesonPorting
* meson: Use generators placeholdersIñigo Martínez2019-10-013-6/+4
| | | | | | | | | | Functions derived from generators as `configure_file`, `custom_target` and `i18n.merge_file` can use placeholders like `@BASENAME@` that removes the extension from the input filename string. The output string has been replaced by this placeholder that allows in some cases the use of less variables.
* docs: include the license boilerplate instead of full GPL textLubomir Rintel2019-09-104-5/+71
| | | | | | | | What's actually needed here is an explaination of how the license applies along with the explanation where to find the full text. Also, the libnm documentation was lacking the licensing information altogether. Fix fixes it too.
* build: use regexp in gtkdoc --ignore-decorators optionBeniamino Galvani2019-09-062-7/+2
| | | | | | | gtkdoc-scan supports regular expressions in the --ignore-decorators command-line option. Since it is easier to use a regexp than grepping macros from a source file, revert the ugly solution from commit 2d941dc95a1d ('build: fix errors when building with gtk-doc 1.32').
* build: fix errors when building with gtk-doc 1.32Beniamino Galvani2019-09-052-1/+7
| | | | | | | | | | | | | | | | | | gtkdoc-scan 1.32 performs stricter checks on structures definitions and so it complains on: /build/networkmanager/src/NetworkManager/libnm/./nm-vpn-plugin-old.h:0: warning: partial declaration (struct) : typedef struct { NM_DEPRECATED_IN_1_2 GObject parent; } NMVpnPluginOld NM_DEPRECATED_IN_1_2; because of the unrecognized token 'NM_DEPRECATED_IN_1_2'. Pass all allowed macros to gtkdoc-scan through the --ignore-decorators argument. https://gitlab.gnome.org/GNOME/gtk-doc/issues/98 https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/238
View Lorry Controller Status