We want to guard against concurrent modifications of profiles. We cannot
lock profiles, so what we instead do is expose (and bump) a version ID.
The user can check the version ID, plan ahead what to do, and tell
NetworkManager to only make the modification if no concurrent
modification was done. The conflict can be detected via the version ID.
The Update2() D-Bus call gets a parameter to only allow the request if
the version ID still matches.
nmcli should use this, but it is quite some effort to retry upon
concurrent modification. This is still to do.
Note that the user might make a decision that is based on multiple
profiles. As the new version-id is only per-profile, we cannot guard
against such inter-profile modifications. What would be needed, is a
UpdateMany() call, where we could modify multiple profiles at once, and
the action only takes effect if all version IDs show no concurrent
modification. That's not done yet, and maybe never will be.
This will allow migrating a connection. If specified, the connection will
be confined to a particular settings plugin when written back. If the
plugin differs from the existing one, it will be removed from the old one.
There has been a lot wrong with this one. Aside from the messy
capitalization, it broke the argument documentation into multiple lines,
baffling gdbus-codegen, which, in turn, generated garbage documentation.
Overhaul it.
D-Bus 1.3.1 (2010) introduced the standard "PropertiesChanged" signal
on "org.freedesktop.DBus.Properties". NetworkManager is old, and predates
this API. From that time, it still had it's own PropertiesChanged signal
that are emitted together with the standard ones. NetworkManager
supports the standard PropertiesChanged signal since it switched to
gdbus library in version 1.2.0 (2016).
These own signals are deprecated for a long time already ([1], 2016), and
are hopefully not used by anybody anymore. libnm-glib was using them and
relied on them, but that library is gone. libnm does not use them and neither
does plasma-nm.
Hopefully no users are left that are affected by this API break.
[1] 6fb917178a
This allows implementing some convenience features in nmcli -- listing
the backing store for the connection in "nmcli c show", and using the
filename for specifying connection in "nmcli c up/down".
Eventually, paired with ReloadConnections(), this could be used to
implement something similar to what "systemctl edit" does for units
(though we'd need to pick another command name as we aready use
"nmcli c edit" for something different).
The D-Bus interface already has a boolean property "Unsaved".
While that is nicer too look at (in the API), adding a new flag
is very cumbersome, and also has more overhead. For example,
it requires extending the D-Bus API, all the way down to libnm.
Add a flags argument, that will allow to add future boolean
flags easier.
Extend the Update2 flags to allow marking a connection as volatile.
Making a connection as volatile means that the connection stays alive
as long as an active connection references it.
It is correct that Update2() returns before the connection is actually
deleted. It might take an arbitrary long time until the volatile
mechanism cleans up the connection.
Also add two more IN_MEMORY flags: "detached" and "only".
The existing NM_SETTINGS_UPDATE2_FLAG_IN_MEMORY would not detach nor
delete the possible file on disk. That is, the mode only changes what NM
thinks is the current content of the connection profile. It would not delete
the file on disk nor would it detach the profile in-memory from the file.
As such, later persisting the connection again to disk would overwrite
the file, and deleting the profile, would delete the file.
Now add two new IN_MEMORY modes.
NM_SETTINGS_UPDATE2_FLAG_IN_MEMORY_DETACH is like making the connection
in-memory only, but forgetting that there might be any profile on disk.
That means, a later Delete() would not delete the file. Similarly, a
later Update2() that persists the connection again, would not overwrite
the existing file on disk, instead it would choose a new file name.
On the other hand, NM_SETTINGS_UPDATE2_FLAG_IN_MEMORY_ONLY would delete
a potential file from disk right away.
It's clear that "volatile" only makes sense with either "in-memory-detached"
or "in-memory-only". That is, the file on disk should be deleted right away
(before the in-memory part is garbage collected) or the file on disk should
be forgotten.
We already have Update(), UpdateUnsaved() and Save(), which serve
similar purposes. We will need a form of update with another argument.
Most notably, to block autoconnect while doing the update.
Other use cases could be to prevent reapplying connection.zone and
connection.metered, to to reapply all changes.
Instead of adding a specific update function that only serves that
new use-case, add a extensible Update2() function. It can be extended
to cope with future variants of update.
This makes it easier to install the files with proper names.
Also, it makes the makefile rules slightly simpler.
Lastly, the documentation is now generated into docs/api, which makes it
possible to get rid of the awkward relative file names in docbook.
