colin/NetworkManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ip-config: Fix the nmcli docs for the renamed dhcp-send-hostname

Browse Source 
In nmcli we have renamed dhcp-send-hostname and dhcp-send-hostname-v2 to
dhcp-send-hostname-deprecated and dhcp-send-hostname so users don't need
to worry about the details of the weird workarounds that we sometimes
need to do to expand and/or deprecate some properties.

However, the autogenerated documentation didn't include this names. Add
---nmcli--- specific documentation, adding a new property-infos field
called "rename" with the new name used in nmcli. This field can be used
for more properties if we use the same strategy in the future.
This commit is contained in:
Íñigo Huguet
2024-10-04 11:51:33 +02:00
committed by Wen Liang
parent add4dad505
commit 380458b0ee
8 changed files with 962 additions and 929 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
man/nm-settings-nmcli.xsl
View File

@@ -141,7 +141,14 @@
<term>
<option>
<xsl:attribute name="id">nm-settings-nmcli.property.<xsl:value-of select="$setting_name"/>.<xsl:value-of select="@name"/></xsl:attribute>
<xsl:value-of select="$setting_name"/>.<xsl:value-of select="@name"/>
<xsl:choose>
<xsl:when test="@rename">
<xsl:value-of select="$setting_name"/>.<xsl:value-of select="@rename"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$setting_name"/>.<xsl:value-of select="@name"/>
</xsl:otherwise>
</xsl:choose>
</option>
</term>
<listitem>

24
src/libnm-core-impl/nm-setting-ip-config.c
View File

@@ -6737,6 +6737,14 @@ nm_setting_ip_config_class_init(NMSettingIPConfigClass *klass)
*
* Deprecated: 1.52: use the new version of dhcp-send-hostname instead.
**/
/* ---nmcli---
* property: dhcp-send-hostname
* rename: dhcp-send-hostname-deprecated
* description: Since 1.52 this property is deprecated and is only used as fallback value
* for dhcp-send-hostname if it's set to 'default'. This is only done to avoid
* breaking existing configurations, the new property should be used from now on.
* ---end---
*/
obj_properties[PROP_DHCP_SEND_HOSTNAME] =
g_param_spec_boolean(NM_SETTING_IP_CONFIG_DHCP_SEND_HOSTNAME,
"",
@@ -7053,6 +7061,22 @@ nm_setting_ip_config_class_init(NMSettingIPConfigClass *klass)
*
* Since: 1.52
**/
/* ---nmcli---
* property: dhcp-send-hostname-v2
* rename: dhcp-send-hostname
* description: If %TRUE, a hostname is sent to the DHCP server when acquiring a lease.
* Some DHCP servers use this hostname to update DNS databases, essentially
* providing a static hostname for the computer. If the dhcp-hostname
* property is %NULL and this property is %TRUE, the current persistent
* hostname of the computer is sent.
*
* The default value is %NM_TERNARY_DEFAULT. In this case the global value
* from NetworkManager configuration is looked up. If it's not set, the value
* from dhcp-send-hostname-deprecated, which defaults to %TRUE, is
* used for backwards compatibility. In the future this will change and, in
* absence of a global default, it will always fallback to %TRUE.
* ---end---
*/
obj_properties[PROP_DHCP_SEND_HOSTNAME_V2] =
g_param_spec_int(NM_SETTING_IP_CONFIG_DHCP_SEND_HOSTNAME_V2,
"",

8
src/libnmc-setting/settings-docs.h.in
View File

@@ -188,8 +188,8 @@
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_IAID N_("A string containing the \"Identity Association Identifier\" (IAID) used by the DHCP client. The string can be a 32-bit number (either decimal, hexadecimal or as colon separated hexadecimal numbers). Alternatively it can be set to the special values \"mac\", \"perm-mac\", \"ifname\" or \"stable\". When set to \"mac\" (or \"perm-mac\"), the last 4 bytes of the current (or permanent) MAC address are used as IAID. When set to \"ifname\", the IAID is computed by hashing the interface name. The special value \"stable\" can be used to generate an IAID based on the stable-id (see connection.stable-id), a per-host key and the interface name. When the property is unset, the value from global configuration is used; if no global default is set then the IAID is assumed to be \"ifname\". For DHCPv4, the IAID is only used with \"ipv4.dhcp-client-id\" values \"duid\" and \"ipv6-duid\" to generate the client-id. For DHCPv6, note that at the moment this property is only supported by the \"internal\" DHCPv6 plugin. The \"dhclient\" DHCPv6 plugin always derives the IAID from the MAC address. The actually used DHCPv6 IAID for a currently activated interface is exposed in the lease information of the device.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_IPV6_ONLY_PREFERRED N_("Controls the \"IPv6-Only Preferred\" DHCPv4 option (RFC 8925). When set to \"yes\" (1), the host adds the option to the parameter request list; if the DHCP server sends the option back, the host stops the DHCP client for the time interval specified in the option. Enable this feature if the host supports an IPv6-only mode, i.e. either all applications are IPv6-only capable or there is a form of 464XLAT deployed. When set to \"default\" (-1), the actual value is looked up in the global configuration; if not specified, it defaults to \"no\" (0). If the connection has IPv6 method set to \"disabled\", this property does not have effect and the \"IPv6-Only Preferred\" option is always disabled.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_REJECT_SERVERS N_("Array of servers from which DHCP offers must be rejected. This property is useful to avoid getting a lease from misconfigured or rogue servers. For DHCPv4, each element must be an IPv4 address, optionally followed by a slash and a prefix length (e.g. \"192.168.122.0/24\"). This property is currently not implemented for DHCPv6.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_SEND_HOSTNAME N_("Since 1.52 this property is deprecated and is only used as fallback value for \"dhcp-send-hostname-v2\" if it's set to 'default'. This is only done to avoid breaking existing configurations, the new property should be used from now on.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_SEND_HOSTNAME_V2 N_("If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the \"dhcp-hostname\" property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is \"default\" (-1). In this case the global value from NetworkManager configuration is looked up. If it's not set, the value from \"dhcp-send-hostname\", which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_SEND_HOSTNAME N_("Since 1.52 this property is deprecated and is only used as fallback value for dhcp-send-hostname if it's set to 'default'. This is only done to avoid breaking existing configurations, the new property should be used from now on.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_SEND_HOSTNAME_V2 N_("If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the dhcp-hostname property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is default (-1). In this case the global value from NetworkManager configuration is looked up. If it's not set, the value from dhcp-send-hostname-deprecated, which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_SEND_RELEASE N_("Whether the DHCP client will send RELEASE message when bringing the connection down. The default value is \"default\" (-1). When the default value is specified, then the global value from NetworkManager configuration is looked up, if not set, it is considered as FALSE.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_TIMEOUT N_("A timeout for a DHCP transaction in seconds. If zero (the default), a globally configured default is used. If still unspecified, a device specific timeout is used (usually 45 seconds). Set to 2147483647 (MAXINT32) for infinity.")
#define DESCRIBE_DOC_NM_SETTING_IP4_CONFIG_DHCP_VENDOR_CLASS_IDENTIFIER N_("The Vendor Class Identifier DHCP option (60). Special characters in the data string may be escaped using C-style escapes, nevertheless this property cannot contain nul bytes. If the per-profile value is unspecified (the default), a global connection default gets consulted. If still unspecified, the DHCP option is not sent to the server.")
@@ -222,8 +222,8 @@
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_IAID N_("A string containing the \"Identity Association Identifier\" (IAID) used by the DHCP client. The string can be a 32-bit number (either decimal, hexadecimal or as colon separated hexadecimal numbers). Alternatively it can be set to the special values \"mac\", \"perm-mac\", \"ifname\" or \"stable\". When set to \"mac\" (or \"perm-mac\"), the last 4 bytes of the current (or permanent) MAC address are used as IAID. When set to \"ifname\", the IAID is computed by hashing the interface name. The special value \"stable\" can be used to generate an IAID based on the stable-id (see connection.stable-id), a per-host key and the interface name. When the property is unset, the value from global configuration is used; if no global default is set then the IAID is assumed to be \"ifname\". For DHCPv4, the IAID is only used with \"ipv4.dhcp-client-id\" values \"duid\" and \"ipv6-duid\" to generate the client-id. For DHCPv6, note that at the moment this property is only supported by the \"internal\" DHCPv6 plugin. The \"dhclient\" DHCPv6 plugin always derives the IAID from the MAC address. The actually used DHCPv6 IAID for a currently activated interface is exposed in the lease information of the device.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_PD_HINT N_("A IPv6 address followed by a slash and a prefix length. If set, the value is sent to the DHCPv6 server as hint indicating the prefix delegation (IA_PD) we want to receive. To only hint a prefix length without prefix, set the address part to the zero address (for example \"::/60\").")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_REJECT_SERVERS N_("Array of servers from which DHCP offers must be rejected. This property is useful to avoid getting a lease from misconfigured or rogue servers. For DHCPv4, each element must be an IPv4 address, optionally followed by a slash and a prefix length (e.g. \"192.168.122.0/24\"). This property is currently not implemented for DHCPv6.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_SEND_HOSTNAME N_("Since 1.52 this property is deprecated and is only used as fallback value for \"dhcp-send-hostname-v2\" if it's set to 'default'. This is only done to avoid breaking existing configurations, the new property should be used from now on.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_SEND_HOSTNAME_V2 N_("If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the \"dhcp-hostname\" property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is \"default\" (-1). In this case the global value from NetworkManager configuration is looked up. If it's not set, the value from \"dhcp-send-hostname\", which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_SEND_HOSTNAME N_("Since 1.52 this property is deprecated and is only used as fallback value for dhcp-send-hostname if it's set to 'default'. This is only done to avoid breaking existing configurations, the new property should be used from now on.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_SEND_HOSTNAME_V2 N_("If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the dhcp-hostname property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is default (-1). In this case the global value from NetworkManager configuration is looked up. If it's not set, the value from dhcp-send-hostname-deprecated, which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_SEND_RELEASE N_("Whether the DHCP client will send RELEASE message when bringing the connection down. The default value is \"default\" (-1). When the default value is specified, then the global value from NetworkManager configuration is looked up, if not set, it is considered as FALSE.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DHCP_TIMEOUT N_("A timeout for a DHCP transaction in seconds. If zero (the default), a globally configured default is used. If still unspecified, a device specific timeout is used (usually 45 seconds). Set to 2147483647 (MAXINT32) for infinity.")
#define DESCRIBE_DOC_NM_SETTING_IP6_CONFIG_DNS N_("Array of IP addresses of DNS servers. For DoT (DNS over TLS), the SNI server name can be specified by appending \"#example.com\" to the IP address of the DNS server. This currently only has effect when using systemd-resolved.")

8
src/nmcli/gen-metadata-nm-settings-nmcli.xml.in
View File

@@ -1380,11 +1380,11 @@
values="0 - 2147483647"
special-values="default (0), infinity (2147483647)" />
<property name="dhcp-send-hostname"
nmcli-description="Since 1.52 this property is deprecated and is only used as fallback value for &quot;dhcp-send-hostname-v2&quot; if it&apos;s set to &apos;default&apos;. This is only done to avoid breaking existing configurations, the new property should be used from now on."
nmcli-description="Since 1.52 this property is deprecated and is only used as fallback value for dhcp-send-hostname if it&apos;s set to &apos;default&apos;. This is only done to avoid breaking existing configurations, the new property should be used from now on."
format="boolean"
values="true/yes/on, false/no/off" />
<property name="dhcp-send-hostname-v2"
nmcli-description="If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the &quot;dhcp-hostname&quot; property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is &quot;default&quot; (-1). In this case the global value from NetworkManager configuration is looked up. If it&apos;s not set, the value from &quot;dhcp-send-hostname&quot;, which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE."
nmcli-description="If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the dhcp-hostname property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is default (-1). In this case the global value from NetworkManager configuration is looked up. If it&apos;s not set, the value from dhcp-send-hostname-deprecated, which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE."
format="choice (NMTernary)"
values="default (-1), false/no (0), true/yes (1)" />
<property name="dhcp-hostname"
@@ -1549,11 +1549,11 @@
values="0 - 2147483647"
special-values="default (0), infinity (2147483647)" />
<property name="dhcp-send-hostname"
nmcli-description="Since 1.52 this property is deprecated and is only used as fallback value for &quot;dhcp-send-hostname-v2&quot; if it&apos;s set to &apos;default&apos;. This is only done to avoid breaking existing configurations, the new property should be used from now on."
nmcli-description="Since 1.52 this property is deprecated and is only used as fallback value for dhcp-send-hostname if it&apos;s set to &apos;default&apos;. This is only done to avoid breaking existing configurations, the new property should be used from now on."
format="boolean"
values="true/yes/on, false/no/off" />
<property name="dhcp-send-hostname-v2"
nmcli-description="If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the &quot;dhcp-hostname&quot; property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is &quot;default&quot; (-1). In this case the global value from NetworkManager configuration is looked up. If it&apos;s not set, the value from &quot;dhcp-send-hostname&quot;, which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE."
nmcli-description="If TRUE, a hostname is sent to the DHCP server when acquiring a lease. Some DHCP servers use this hostname to update DNS databases, essentially providing a static hostname for the computer. If the dhcp-hostname property is NULL and this property is TRUE, the current persistent hostname of the computer is sent. The default value is default (-1). In this case the global value from NetworkManager configuration is looked up. If it&apos;s not set, the value from dhcp-send-hostname-deprecated, which defaults to TRUE, is used for backwards compatibility. In the future this will change and, in absence of a global default, it will always fallback to TRUE."
format="choice (NMTernary)"
values="default (-1), false/no (0), true/yes (1)" />
<property name="dhcp-hostname"

784
src/tests/client/test-client.check-on-disk/test_003.expected
View File

File diff suppressed because it is too large Load Diff

1056
src/tests/client/test-client.check-on-disk/test_004.expected
View File

File diff suppressed because it is too large Load Diff

1
tools/generate-docs-nm-property-infos.py
View File

@@ -164,6 +164,7 @@ KEYWORD_XML_TYPE_ATTR = "attr"
keywords = collections.OrderedDict(
[
("property", KEYWORD_XML_TYPE_ATTR),
("rename", KEYWORD_XML_TYPE_ATTR),
("variable", KEYWORD_XML_TYPE_ATTR),
("format", KEYWORD_XML_TYPE_ATTR),
("values", KEYWORD_XML_TYPE_ATTR),

1
tools/generate-docs-nm-settings-docs-merge.py
View File

@@ -300,6 +300,7 @@ for setting_name in iter_keys_of_dicts(settings_roots, key_fcn_setting_name):
node_set_attr(property_node, "special-values", properties_attrs)
node_set_attr(property_node, "default", properties_attrs)
node_set_attr(property_node, "alias", properties_attrs)
node_set_attr(property_node, "rename", properties_attrs)
if description_docbook is not None:
property_node.insert(0, description_docbook)