From 9d7644af5f084f8fe0fd60cc6c8520c9f7eaec8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8D=C3=B1igo=20Huguet?= Date: Tue, 29 Aug 2023 15:42:22 +0200 Subject: [PATCH 1/2] man: keyfile: improve explanation of the format Separate the explanation of the format in various paragraphs so it is better structured and easier to follow and understand. Add a note about the properties that, instead of using a semicolon separated list, use individual key-value pairs per list element (addresses, routes and routing-rules), since this is also a relevant difference from the standard key file format and from the settings specification format. --- man/nm-settings-keyfile.xsl | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/man/nm-settings-keyfile.xsl b/man/nm-settings-keyfile.xsl index 894aad3e88..450cc6fdee 100644 --- a/man/nm-settings-keyfile.xsl +++ b/man/nm-settings-keyfile.xsl @@ -54,22 +54,31 @@ File Format The keyfile config format is a simple .ini-style - format. It consists of sections (groups) of key-value pairs. Each section - corresponds to a setting name as described in the settings specification - (nm-settings-nmcli - 5). Each configuration key/value - pair in the section is one of the properties listed in the settings - specification. The majority of properties of the specification is written - in the same format into the keyfile too. However - some values are inconvenient for people to use. These are stored in the - files in more readable ways. These properties are described below. - An example could be IP addresses that are not written as integer arrays, - but more reasonably as "1.2.3.4/12 1.2.3.254". + format. It consists of sections (groups) of key-value pairs. More information of the generic key file format can be found at GLib key file format (Lines beginning with a '#' are comments, lists are separated by character ; etc.). + + Each section corresponds to a setting name as described in the settings + specification (nm-settings-nmcli + 5). Each key/value pair in a + section is one of the properties from the specification. + + + The majority of properties are written in the same format as the + specification into the keyfile. However, some + values are inconvenient for people to use so they are stored in the + keyfile in more readable ways. These properties + that differ from the specification are described below. + An example could be IP addresses that are not written as integer arrays, + but more reasonably as "1.2.3.4/12 1.2.3.254". + Also, some lists of complex values (addresses, routes, routing-rules), + instead of using a semicolon separated list, use one key-value pair + per list element, with the key being the singular of the property name + followed by the numeric index (i.e address1, address2, ...). + Users can create or modify the keyfile connection files manually, even if that is not the recommended way of managing the profiles. From 03db294c5ce5a852f885792f1149aa7a8798678c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8D=C3=B1igo=20Huguet?= Date: Tue, 29 Aug 2023 15:47:10 +0200 Subject: [PATCH 2/2] man: keyfile: complete the explanation of routes properties Complete the explanations of routes properties, adding explanations for routesN_option and routing-rules. --- src/libnm-core-impl/nm-setting-ip4-config.c | 19 +++++++++++++++++++ src/libnm-core-impl/nm-setting-ip6-config.c | 19 +++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/src/libnm-core-impl/nm-setting-ip4-config.c b/src/libnm-core-impl/nm-setting-ip4-config.c index 9ed3950724..4e8606feea 100644 --- a/src/libnm-core-impl/nm-setting-ip4-config.c +++ b/src/libnm-core-impl/nm-setting-ip4-config.c @@ -703,6 +703,15 @@ nm_setting_ip4_config_class_init(NMSettingIP4ConfigClass *klass) * route2=7.7.0.0/16 * ---end--- */ + /* ---keyfile--- + * property: routes (attributes) + * variable: route1_options, route2_options, ... + * format: key=val[,key=val...] + * description: Attributes defined for the routes, if any. The supported + * attributes are explained in ipv4.routes entry in `man nm-settings-nmcli`. + * example: route1_options=mtu=1000,onlink=true + * ---end--- + */ /* ---ifcfg-rh--- * property: routes * variable: ADDRESS1, NETMASK1, GATEWAY1, METRIC1, OPTIONS1, ... @@ -711,6 +720,16 @@ nm_setting_ip4_config_class_init(NMSettingIP4ConfigClass *klass) * ---end--- */ + /* ---keyfile--- + * property: routing-rules + * variable: routing-rule1, routing-rule2, ... + * format: routing rule string + * description: Routing rules as defined with `ip rule add`, but with mandatory + * fixed priority. + * example: routing-rule1=priority 5 from 192.167.4.0/24 table 45 + * ---end--- + */ + /* ---ifcfg-rh--- * property: ignore-auto-routes * variable: PEERROUTES(+) diff --git a/src/libnm-core-impl/nm-setting-ip6-config.c b/src/libnm-core-impl/nm-setting-ip6-config.c index 661a451e42..9e93336539 100644 --- a/src/libnm-core-impl/nm-setting-ip6-config.c +++ b/src/libnm-core-impl/nm-setting-ip6-config.c @@ -714,6 +714,15 @@ nm_setting_ip6_config_class_init(NMSettingIP6ConfigClass *klass) * example: route1=2001:4860:4860::/64,2620:52:0:2219:222:68ff:fe11:5403 * ---end--- */ + /* ---keyfile--- + * property: routes (attributes) + * variable: route1_options, route2_options, ... + * format: key=val[,key=val...] + * description: Attributes defined for the routes, if any. The supported + * attributes are explained in ipv6.routes entry in `man nm-settings-nmcli`. + * example: route1_options=mtu=1000,onlink=true + * ---end--- + */ /* ---ifcfg-rh--- * property: routes * variable: (none) @@ -722,6 +731,16 @@ nm_setting_ip6_config_class_init(NMSettingIP6ConfigClass *klass) * ---end--- */ + /* ---keyfile--- + * property: routing-rules + * variable: routing-rule1, routing-rule2, ... + * format: routing rule string + * description: Routing rules as defined with `ip rule add`, but with mandatory + * fixed priority. + * example: routing-rule1=priority 5 from 2001:4860:4860::/64 table 45 + * ---end--- + */ + /* ---ifcfg-rh--- * property: ignore-auto-routes * variable: IPV6_PEERROUTES(+)