The default value of a string property (almost?) always should be
%NULL, which means the value is absent and not specified.
That is necessary because adding new properties must be backward
compatible. That means, after upgrade those properties will have their
value unset. In these cases, %NULL really translates to some property
dependant behavior (like not using the value, or using a special default
value).
For example leaving "ethernet.cloned-mac-address" unset really means
"preserve", with the twist that %NULL can be overridden by a global
connection default.
For most string properties, a value can only be unset (%NULL) or set to
a non-empty string. nm_connection_verify() enforces that.
However, for some properties, it makes sense to allow both unset and the
empty word "" as value. This is the case if a property can have it's
value overridden by a global connection default, or if we need the
differentiation between having a value unset and having it set to the empty
word.
We would usually avoid allowing the empty word beside %NULL, because
that makes it hard to express the difference on the command line of
nmcli or in a UI text entry field. In the "ethernet.cloned-mac-address"
example, "" is not necessary nor sensible.
However, for some properties really all string values may be possible (including
"") and also unset/%NULL. Then, we need some form of escaping/mangling,
to allow to express all possible values. The chosen style here is that
on nmcli input field "" means %NULL, while a word with all white space
stands for the word with one less white space characters.
This is still unused, but I think it makes sense for some properties.
I initially added this for "connection.mud-url", but a valid MUD-URL
always must start with "https://", so not all strings are possible
to begin with. So to explicitly express that no MUD-URL should be set,
we will instead introduce a special word "none", and not use the empty
word, due to the oddities discussed here. However, I think this may
well make sense for some properties where all strings are valid.
The enum values are unique throughout the source code so they
can easier be searched (e.g. with grep), compared to '\0'. It
is often interesting where a certain modifier is used, so searching
the source code is important to give relevant results.
Also, the modifier is really an enum and we shouldn't misuse char type.
If that would be a good idea in general, we wouldn't need any enums
at all. But we use them for good reasons.
"ipv4.dns-options" and "ipv6.dns-options" are special, in that they can
be either unset/default or an empty list of options. That means, nmcli
must treat these two options differently.
For the (terse) getter, it returns "" for default and " " for empty.
The setter must likewise support and distingish between these two cases.
Cleanup the handling of such options. This only applies to properties of
type "multilist". Hence, add multilist.clear_emptyunset_fcn() handler
that indicates that the property is of that kind.
Try:
nmcli connection modify "$PROFILE" ipv4.dns-options ''
nmcli connection modify "$PROFILE" ipv4.dns-options ' '
and compare the output:
nmcli connection show "$PROFILE" | sed -n '/ipv4.dns-options/ s/.*/<\0>/p'
nmcli -t connection show "$PROFILE" | sed -n '/ipv4.dns-options/ s/.*/<\0>/p'
nmcli -o connection show "$PROFILE" | sed -n '/ipv4.dns-options/ s/.*/<\0>/p'
"libnm-core" implements common functionality for "NetworkManager" and
"libnm".
Note that clients like "nmcli" cannot access the internal API provided
by "libnm-core". So, if nmcli wants to do something that is also done by
"libnm-core", , "libnm", or "NetworkManager", the code would have to be
duplicated.
Instead, such code can be in "libnm-libnm-core-{intern|aux}.la".
Note that:
0) "libnm-libnm-core-intern.la" is used by libnm-core itsself.
On the other hand, "libnm-libnm-core-aux.la" is not used by
libnm-core, but provides utilities on top of it.
1) they both extend "libnm-core" with utlities that are not public
API of libnm itself. Maybe part of the code should one day become
public API of libnm. On the other hand, this is code for which
we may not want to commit to a stable interface or which we
don't want to provide as part of the API.
2) "libnm-libnm-core-intern.la" is statically linked by "libnm-core"
and thus directly available to "libnm" and "NetworkManager".
On the other hand, "libnm-libnm-core-aux.la" may be used by "libnm"
and "NetworkManager".
Both libraries may be statically linked by libnm clients (like
nmcli).
3) it must only use glib, libnm-glib-aux.la, and the public API
of libnm-core.
This is important: it must not use "libnm-core/nm-core-internal.h"
nor "libnm-core/nm-utils-private.h" so the static library is usable
by nmcli which couldn't access these.
Note that "shared/nm-meta-setting.c" is an entirely different case,
because it behaves differently depending on whether linking against
"libnm-core" or the client programs. As such, this file must be compiled
twice.
(cherry picked from commit af07ed01c0)
From the files under "shared/nm-utils" we build an internal library
that provides glib-based helper utilities.
Move the files of that basic library to a new subdirectory
"shared/nm-glib-aux" and rename the helper library "libnm-core-base.la"
to "libnm-glib-aux.la".
Reasons:
- the name "utils" is overused in our code-base. Everything's an
"utils". Give this thing a more distinct name.
- there were additional files under "shared/nm-utils", which are not
part of this internal library "libnm-utils-base.la". All the files
that are part of this library should be together in the same
directory, but files that are not, should not be there.
- the new name should better convey what this library is and what is isn't:
it's a set of utilities and helper functions that extend glib with
funcitonality that we commonly need.
There are still some files left under "shared/nm-utils". They have less
a unifying propose to be in their own directory, so I leave them there
for now. But at least they are separate from "shared/nm-glib-aux",
which has a very clear purpose.
(cherry picked from commit 80db06f768)
We had %VALUE_STRSPLIT_MODE_MULTILIST_WITH_ESCAPE, which was used
by "match.interface-names". This uses nm_utils_strsplit_set_full()
with %NM_UTILS_STRSPLIT_SET_FLAGS_ALLOW_ESCAPING and
_nm_utils_unescape_plain().
We want eventually to use nm_utils_escaped_tokens_split() everywhere.
We already have %VALUE_STRSPLIT_MODE_ESCAPED_TOKENS, which splits the
list at ',' (and strips whitespaces at the around the delimiter). That
differs from what %VALUE_STRSPLIT_MODE_MULTILIST_WITH_ESCAPE did, which
also considered whitespace a delimiter.
So, we need a new mode %VALUE_STRSPLIT_MODE_ESCAPED_TOKENS_WITH_SPACES
which replaces the previous mode.
Note that the previous implementation did almost the same thing. In
fact, I cannot imagine examples where they behaved differently, but
my feeling is that there might be some edge cases where this changes
behavior.
(cherry picked from commit 6093f49304)
When splitting (and concatenating) list-typed properties,
we really should use nm_utils_escaped_tokens_split()
and nm_utils_escaped_tokens_escape*().
Make that the default, and mark all properties to opt-in to the
legacy behavior.
(cherry picked from commit 5a71592087)
nmcli supports list options (optlist and multilist properties).
These commonly are individual items, concatenated by a delimiter.
It should be generally possibly to express every value. That means, we
need some for of escaping mechanism for delimiters.
Currently this is all inconsistent or no escaping is supported. I intend
to fix that (which will be a change in behavior).
For now, just add yet another style of tokenzing/concatenating list
items in nmcli. This is the style to replace all other styles.
(cherry picked from commit ba956bd499)
There is no reason to validate only in certain cases. Either we
validate, or we don't (always the same).
This is a change in behavior, but the cases should be sensible.
set_fcn() and remove_fcn() are strongly related. They should accept
arguments in the same format, hence the parsing of the arguments should
be done at one place.
In fact, previously the parsing was separate, leading to ugly
inconsistencies:
$ nmcli connection modify "$PROFILE" +vpn.data x=y
$ nmcli connection modify "$PROFILE" -vpn.data x=y
Error: failed to remove a value from vpn.data: invalid option 'x=y'.
or
$ nmcli connection modify "$PROFILE" +ipv4.addresses 192.168.1.5/24,192.168.2.5/24
$ nmcli connection modify "$PROFILE" -ipv4.addresses 192.168.1.5/24,192.168.2.5/24
Error: failed to remove a value from ipv4.addresses: invalid prefix '24,192.168.2.5/24'; <1-32> allowed.
Let set_fcn() handle set-default, set-all, add, and subtract.
Previously, set_fcn() could only append values. Now, pass on the modifier
so that it may append, set all, or reset the default.
These operations are strongly related and should be handled by the same
set_fcn() function.
A property-info can only have one property-typ-data. That means,
all functions (get_fcn(), set_fcn()) need to either take not
property-typ-data, or they must all accept the same.
That made it hard to mix _get_fcn_nmc_with_default() with setters
that do require a certain property-typ-data. Instead, move the
is_default_func() to the general portion, and let _get_fcn_gobject()
handle it.
Instead of using a macro to define the individual set/remove functions,
add a new property type _pt_multilist.
This way, we have more the concept of a property having a type, instead
of a property having a set of handlers how to implement something.
Also, this is only the first step. There are several similar properties
that also can be implemented as the same type.
Not all implementations support having the value being an index.
For example, the implementations that are done via DEFINE_REMOVER_OPTION() macro.
The meaning of the "value" string must not be determined by
nmc_setting_remove_property_option(). It's up to the implementation
to decide whether to allow an index and how to interpret it.
Rework the explicit implementation of NM_SETTING_802_1X_PASSWORD_RAW
handling to generically handle GBytes properties.
Note that the NM_SETTING_802_1X_PASSWORD_RAW setter accepts a legacy
format where hex-words are separated by space. I don't think we want
to support this format for new options.
So, there are two possibilities:
1) either leave _set_fcn_802_1x_password_raw() as-is, with the special
handling.
2) interpret a property-data gobject_bytes.legacy_format.
1) seems to make more sense, because there is only one such property,
and we won't use this for new properties. However let's do 2), because
it shows nicely the two styles side-by-side. In other words, let's
password-raw also be a _pt_gobject_bytes typed property, with some
special legacy handling. Instead, of having it an entirely separate
property type (with a different setter implementation). I think it's
better to have the parts where they differ pushed down (the "stack") as
much as possible.
libnm currently has only one GObject property of type uint64:
"serial.send-delay". However, it's broken because uint64 handling
is not implemented.
$ nmcli connection add type gsm autoconnect no con-name t ifname '*' apn 'xyz' serial.baud 5
Connection 't' (4c929f17-9fda-41d6-8f90-897f6d46b078) successfully added.
$ nmcli connection show t
...
ipv6.dhcp-duid: --
ipv6.dhcp-send-hostname: yes
ipv6.dhcp-hostname: --
ipv6.token: --
(process:14016): libnmc-CRITICAL **: 14:08:32.591: file clients/common/nm-meta-setting-desc.c: line 811 (_get_fcn_gobject_int): should not be reached
serial.baud: 5
serial.bits: 8
serial.parity: none
serial.stopbits: 1
serial.send-delay: --
gsm.number: *99#
...
$ nmcli connection add type gsm autoconnect no con-name t ifname '*' apn 'xyz' serial.baud 5 serial.send-delay 100
(process:14852): libnmc-CRITICAL **: 14:12:24.259: file clients/common/nm-meta-setting-desc.c: line 1131 (_set_fcn_gobject_int): should not be reached
Segmentation fault (core dumped)
Fixes: b6d9bdcee8
Historically, nmcli printed all fields during operations like
`nmcli connection show "$PROFILE"`. As we supported more and
more options, this resulted in a verbose output, of most properties
just being the default values.
To counter that, we added the '-overview' option. When given,
it would hide options that are set at their default. This option
was not the default, to preserve established behavior.
However, for new options, we can afford to hide them. Add a mechanism,
that property getters can mark their value to be hidden. At the moment,
there is no way to show these properties. However, we could add a
'-verbose' option, with the opposite meaning of '-overview'. Anyway,
that does not seem necessary at the moment.
Hiding properties from output is only acceptable for new properties
(otherwise we badly change behavior), and if the properties are set
at their default values (otherwise, we hide important information).
Note that in NetworkManager API (D-Bus, libnm, and nmcli),
the features are called "feature-xyz". The "feature-" prefix
is used, because NMSettingEthtool possibly will gain support
for options that are not only -K|--offload|--features, for
example -C|--coalesce.
The "xzy" suffix is either how ethtool utility calls the feature
("tso", "rx"). Or, if ethtool utility specifies no alias for that
feature, it's the name from kernel's ETH_SS_FEATURES ("tx-tcp6-segmentation").
If possible, we prefer ethtool utility's naming.
Also note, how the features "feature-sg", "feature-tso", and
"feature-tx" actually refer to multiple underlying kernel features
at once. This too follows what ethtool utility does.
The functionality is not yet implemented server-side.
The function nmc_print() receives a list of "targets". These are essentially
the rows that should be printed (while the "fields" list represents the columns).
When filling the cells with values, it calles repeatedly get_fcn() on the
column descriptors (fields), by passing each row (target).
The caller must be well aware that the fields and targets are
compatible. For example, in some cases the targets are NMDevice
instances and the target type must correspond to what get_fcn()
expects.
Add another user-data pointer that is passed on along with the
targets. That is useful, if we have a list of targets/rows, but
pass in additional data that applies to all rows alike.
It is still unused.
