[PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[Antonin Godard]

Add a migration note on the pni-names default policy change after commit
<> in OE-Core.

Cc: Koen Kooi <koen.kooi@oss.qualcomm.com>
Cc: Ross Burton <Ross.Burton@arm.com>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/migration-guides/migration-5.3.rst | 25 ++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
index 2d2f8d91a..8aa7b537f 100644
--- a/documentation/migration-guides/migration-5.3.rst
+++ b/documentation/migration-guides/migration-5.3.rst
@@ -118,6 +118,31 @@ class. Instead, one should create a new recipe to build this FIT image, as
 described in the :ref:`Removed Classes <migration-guides/migration-5.3:Removed
 Classes>` section of the Migration notes for |yocto-ver| (|yocto-codename|).
 
+systemd Predictable Interface Names no longer MAC policy by default
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :oe_git:`systemd recipe </openembedded-core/tree/meta/recipes-core/systemd>`
+used to forcibly set the MAC policy by default when the ``pni-names``
+:term:`distro feature <DISTRO_FEATURES>` was enabled. See
+https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html#AlternativeNamesPolicy=.
+
+This is no longer the case. Instead, when the ``pni-names`` :term:`distro
+feature <DISTRO_FEATURES>` is enabled, the default policy from systemd is
+selected (from https://github.com/systemd/systemd/blob/main/network/99-default.link).
+
+To set the MAC policy to systemd, add the following to a systemd ``.bbappend``
+file in your custom layer::
+
+   do_install:append() {
+          if ${@bb.utils.contains('PACKAGECONFIG', 'pni-names', 'true', 'false', d)}; then
+                  if ! grep -q '^NamePolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
+                          sed -i '/^NamePolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
+                  fi
+                  if ! grep -q 'AlternativeNamesPolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
+                          sed -i '/AlternativeNamesPolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
+                  fi
+   }
+
 Supported kernel versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

---
base-commit: ee0b46bd074dd34c3d6b401e65d2c519c2c3d47b
change-id: 20250904-systemd-pni-names-a9e6c45602c9

Best regards,
--  
Antonin Godard <antonin.godard@bootlin.com>

Re: [docs] [PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[Quentin Schulz]

Hi Antonin,

On 9/9/25 3:29 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Add a migration note on the pni-names default policy change after commit
> <> in OE-Core.
> 

General question, the systemd manpage specifies the policy as mac and 
not MAC, should we follow that as well?

> Cc: Koen Kooi <koen.kooi@oss.qualcomm.com>
> Cc: Ross Burton <Ross.Burton@arm.com>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/migration-guides/migration-5.3.rst | 25 ++++++++++++++++++++++++
>   1 file changed, 25 insertions(+)
> 
> diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
> index 2d2f8d91a..8aa7b537f 100644
> --- a/documentation/migration-guides/migration-5.3.rst
> +++ b/documentation/migration-guides/migration-5.3.rst
> @@ -118,6 +118,31 @@ class. Instead, one should create a new recipe to build this FIT image, as
>   described in the :ref:`Removed Classes <migration-guides/migration-5.3:Removed
>   Classes>` section of the Migration notes for |yocto-ver| (|yocto-codename|).
>   
> +systemd Predictable Interface Names no longer MAC policy by default
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The :oe_git:`systemd recipe </openembedded-core/tree/meta/recipes-core/systemd>`
> +used to forcibly set the MAC policy by default when the ``pni-names``
> +:term:`distro feature <DISTRO_FEATURES>` was enabled. See

s/was/is/ ?

> +https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html#AlternativeNamesPolicy=.
> +
> +This is no longer the case. Instead, when the ``pni-names`` :term:`distro

SHould we justify here why it is no longer the case?

> +feature <DISTRO_FEATURES>` is enabled, the default policy from systemd is
> +selected (from https://github.com/systemd/systemd/blob/main/network/99-default.link).
> +
> +To set the MAC policy to systemd, add the following to a systemd ``.bbappend``

s/to systemd/in systemd/ ?

> +file in your custom layer::
> +
> +   do_install:append() {
> +          if ${@bb.utils.contains('PACKAGECONFIG', 'pni-names', 'true', 'false', d)}; then
> +                  if ! grep -q '^NamePolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
> +                          sed -i '/^NamePolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
> +                  fi
> +                  if ! grep -q 'AlternativeNamesPolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
> +                          sed -i '/AlternativeNamesPolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
> +                  fi

My brain's sh parser says this is invalid because we're missing a 
closing fi for the outermost if block.

I'm also a bit worried about this code snippet as it'll just not be 
tested or maintained once this gets merged.

Cheers,
Quentin

Re: [docs] [PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[Antonin Godard]

On Tue Sep 9, 2025 at 3:59 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
> On 9/9/25 3:29 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> Add a migration note on the pni-names default policy change after commit
>> <> in OE-Core.
>> 
>
> General question, the systemd manpage specifies the policy as mac and 
> not MAC, should we follow that as well?
>
>> Cc: Koen Kooi <koen.kooi@oss.qualcomm.com>
>> Cc: Ross Burton <Ross.Burton@arm.com>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/migration-guides/migration-5.3.rst | 25 ++++++++++++++++++++++++
>>   1 file changed, 25 insertions(+)
>> 
>> diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
>> index 2d2f8d91a..8aa7b537f 100644
>> --- a/documentation/migration-guides/migration-5.3.rst
>> +++ b/documentation/migration-guides/migration-5.3.rst
>> @@ -118,6 +118,31 @@ class. Instead, one should create a new recipe to build this FIT image, as
>>   described in the :ref:`Removed Classes <migration-guides/migration-5.3:Removed
>>   Classes>` section of the Migration notes for |yocto-ver| (|yocto-codename|).
>>   
>> +systemd Predictable Interface Names no longer MAC policy by default
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +The :oe_git:`systemd recipe </openembedded-core/tree/meta/recipes-core/systemd>`
>> +used to forcibly set the MAC policy by default when the ``pni-names``
>> +:term:`distro feature <DISTRO_FEATURES>` was enabled. See
>
> s/was/is/ ?
>
>> +https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html#AlternativeNamesPolicy=.
>> +
>> +This is no longer the case. Instead, when the ``pni-names`` :term:`distro
>
> SHould we justify here why it is no longer the case?
>
>> +feature <DISTRO_FEATURES>` is enabled, the default policy from systemd is
>> +selected (from https://github.com/systemd/systemd/blob/main/network/99-default.link).
>> +
>> +To set the MAC policy to systemd, add the following to a systemd ``.bbappend``
>
> s/to systemd/in systemd/ ?
>
>> +file in your custom layer::
>> +
>> +   do_install:append() {
>> +          if ${@bb.utils.contains('PACKAGECONFIG', 'pni-names', 'true', 'false', d)}; then
>> +                  if ! grep -q '^NamePolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>> +                          sed -i '/^NamePolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>> +                  fi
>> +                  if ! grep -q 'AlternativeNamesPolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>> +                          sed -i '/AlternativeNamesPolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>> +                  fi
>
> My brain's sh parser says this is invalid because we're missing a 
> closing fi for the outermost if block.

Yes, my bad I must have removed it by mistake

> I'm also a bit worried about this code snippet as it'll just not be 
> tested or maintained once this gets merged.

This snippet belongs to a release note for 5.3 so it already matches the Yocto
version? I will include the version of systemd version here at the time of
writing to give some more context.


Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[Quentin Schulz]

Hi Antonin,

On 9/10/25 3:08 PM, Antonin Godard wrote:
> On Tue Sep 9, 2025 at 3:59 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>> Hi Antonin,
>>
>> On 9/9/25 3:29 PM, Antonin Godard via lists.yoctoproject.org wrote:
>>> Add a migration note on the pni-names default policy change after commit
>>> <> in OE-Core.
>>>
>>
>> General question, the systemd manpage specifies the policy as mac and
>> not MAC, should we follow that as well?
>>
>>> Cc: Koen Kooi <koen.kooi@oss.qualcomm.com>
>>> Cc: Ross Burton <Ross.Burton@arm.com>
>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>> ---
>>>    documentation/migration-guides/migration-5.3.rst | 25 ++++++++++++++++++++++++
>>>    1 file changed, 25 insertions(+)
>>>
>>> diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
>>> index 2d2f8d91a..8aa7b537f 100644
>>> --- a/documentation/migration-guides/migration-5.3.rst
>>> +++ b/documentation/migration-guides/migration-5.3.rst
>>> @@ -118,6 +118,31 @@ class. Instead, one should create a new recipe to build this FIT image, as
>>>    described in the :ref:`Removed Classes <migration-guides/migration-5.3:Removed
>>>    Classes>` section of the Migration notes for |yocto-ver| (|yocto-codename|).
>>>    
>>> +systemd Predictable Interface Names no longer MAC policy by default
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>> +
>>> +The :oe_git:`systemd recipe </openembedded-core/tree/meta/recipes-core/systemd>`
>>> +used to forcibly set the MAC policy by default when the ``pni-names``
>>> +:term:`distro feature <DISTRO_FEATURES>` was enabled. See
>>
>> s/was/is/ ?
>>
>>> +https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html#AlternativeNamesPolicy=.
>>> +
>>> +This is no longer the case. Instead, when the ``pni-names`` :term:`distro
>>
>> SHould we justify here why it is no longer the case?
>>
>>> +feature <DISTRO_FEATURES>` is enabled, the default policy from systemd is
>>> +selected (from https://github.com/systemd/systemd/blob/main/network/99-default.link).
>>> +
>>> +To set the MAC policy to systemd, add the following to a systemd ``.bbappend``
>>
>> s/to systemd/in systemd/ ?
>>
>>> +file in your custom layer::
>>> +
>>> +   do_install:append() {
>>> +          if ${@bb.utils.contains('PACKAGECONFIG', 'pni-names', 'true', 'false', d)}; then
>>> +                  if ! grep -q '^NamePolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>> +                          sed -i '/^NamePolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>> +                  fi
>>> +                  if ! grep -q 'AlternativeNamesPolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>> +                          sed -i '/AlternativeNamesPolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>> +                  fi
>>
>> My brain's sh parser says this is invalid because we're missing a
>> closing fi for the outermost if block.
> 
> Yes, my bad I must have removed it by mistake
> 
>> I'm also a bit worried about this code snippet as it'll just not be
>> tested or maintained once this gets merged.
> 
> This snippet belongs to a release note for 5.3 so it already matches the Yocto
> version? I will include the version of systemd version here at the time of
> writing to give some more context.
> 

Does this mean that we already know it's not going to be compatible with 
Wrynose?

People are told to follow each migration manual between their current 
and target Yocto releases, so this will essentially be understood as 
"apply for any release starting from 5.3".

We already saw how well maintained old example recipes were since we 
don't test them, I'm not sure it makes sense to have code snippets we'll 
likely never test as well?

Cheers,
Quentin

Re: [docs] [PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[Antonin Godard]

On Wed Sep 10, 2025 at 3:16 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
> On 9/10/25 3:08 PM, Antonin Godard wrote:
>> On Tue Sep 9, 2025 at 3:59 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>> Hi Antonin,
>>>
>>> On 9/9/25 3:29 PM, Antonin Godard via lists.yoctoproject.org wrote:
>>>> Add a migration note on the pni-names default policy change after commit
>>>> <> in OE-Core.
>>>>
>>>
>>> General question, the systemd manpage specifies the policy as mac and
>>> not MAC, should we follow that as well?
>>>
>>>> Cc: Koen Kooi <koen.kooi@oss.qualcomm.com>
>>>> Cc: Ross Burton <Ross.Burton@arm.com>
>>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>>> ---
>>>>    documentation/migration-guides/migration-5.3.rst | 25 ++++++++++++++++++++++++
>>>>    1 file changed, 25 insertions(+)
>>>>
>>>> diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
>>>> index 2d2f8d91a..8aa7b537f 100644
>>>> --- a/documentation/migration-guides/migration-5.3.rst
>>>> +++ b/documentation/migration-guides/migration-5.3.rst
>>>> @@ -118,6 +118,31 @@ class. Instead, one should create a new recipe to build this FIT image, as
>>>>    described in the :ref:`Removed Classes <migration-guides/migration-5.3:Removed
>>>>    Classes>` section of the Migration notes for |yocto-ver| (|yocto-codename|).
>>>>    
>>>> +systemd Predictable Interface Names no longer MAC policy by default
>>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>> +
>>>> +The :oe_git:`systemd recipe </openembedded-core/tree/meta/recipes-core/systemd>`
>>>> +used to forcibly set the MAC policy by default when the ``pni-names``
>>>> +:term:`distro feature <DISTRO_FEATURES>` was enabled. See
>>>
>>> s/was/is/ ?
>>>
>>>> +https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html#AlternativeNamesPolicy=.
>>>> +
>>>> +This is no longer the case. Instead, when the ``pni-names`` :term:`distro
>>>
>>> SHould we justify here why it is no longer the case?
>>>
>>>> +feature <DISTRO_FEATURES>` is enabled, the default policy from systemd is
>>>> +selected (from https://github.com/systemd/systemd/blob/main/network/99-default.link).
>>>> +
>>>> +To set the MAC policy to systemd, add the following to a systemd ``.bbappend``
>>>
>>> s/to systemd/in systemd/ ?
>>>
>>>> +file in your custom layer::
>>>> +
>>>> +   do_install:append() {
>>>> +          if ${@bb.utils.contains('PACKAGECONFIG', 'pni-names', 'true', 'false', d)}; then
>>>> +                  if ! grep -q '^NamePolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>>> +                          sed -i '/^NamePolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>>> +                  fi
>>>> +                  if ! grep -q 'AlternativeNamesPolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>>> +                          sed -i '/AlternativeNamesPolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>>> +                  fi
>>>
>>> My brain's sh parser says this is invalid because we're missing a
>>> closing fi for the outermost if block.
>> 
>> Yes, my bad I must have removed it by mistake
>> 
>>> I'm also a bit worried about this code snippet as it'll just not be
>>> tested or maintained once this gets merged.
>> 
>> This snippet belongs to a release note for 5.3 so it already matches the Yocto
>> version? I will include the version of systemd version here at the time of
>> writing to give some more context.
>> 
>
> Does this mean that we already know it's not going to be compatible with 
> Wrynose?
>
> People are told to follow each migration manual between their current 
> and target Yocto releases, so this will essentially be understood as 
> "apply for any release starting from 5.3".
>
> We already saw how well maintained old example recipes were since we 
> don't test them, I'm not sure it makes sense to have code snippets we'll 
> likely never test as well?

A simpler approach could be to say:

"""
To set the mac policy to systemd, modify the ``99-default-link.link`` file
provided by systemd in a ``.bbappend`` file to set the ``NamePolicy=`` and
``AlternativeNamesPolicy=`` settings to "mac".
"""

This should not require maintenance. Do you agree?

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[Quentin Schulz]

Hi Antonin,

On 9/10/25 3:32 PM, Antonin Godard via lists.yoctoproject.org wrote:
> On Wed Sep 10, 2025 at 3:16 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>> Hi Antonin,
>>
>> On 9/10/25 3:08 PM, Antonin Godard wrote:
>>> On Tue Sep 9, 2025 at 3:59 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>>> Hi Antonin,
>>>>
>>>> On 9/9/25 3:29 PM, Antonin Godard via lists.yoctoproject.org wrote:
>>>>> Add a migration note on the pni-names default policy change after commit
>>>>> <> in OE-Core.
>>>>>
>>>>
>>>> General question, the systemd manpage specifies the policy as mac and
>>>> not MAC, should we follow that as well?
>>>>
>>>>> Cc: Koen Kooi <koen.kooi@oss.qualcomm.com>
>>>>> Cc: Ross Burton <Ross.Burton@arm.com>
>>>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>>>> ---
>>>>>     documentation/migration-guides/migration-5.3.rst | 25 ++++++++++++++++++++++++
>>>>>     1 file changed, 25 insertions(+)
>>>>>
>>>>> diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
>>>>> index 2d2f8d91a..8aa7b537f 100644
>>>>> --- a/documentation/migration-guides/migration-5.3.rst
>>>>> +++ b/documentation/migration-guides/migration-5.3.rst
>>>>> @@ -118,6 +118,31 @@ class. Instead, one should create a new recipe to build this FIT image, as
>>>>>     described in the :ref:`Removed Classes <migration-guides/migration-5.3:Removed
>>>>>     Classes>` section of the Migration notes for |yocto-ver| (|yocto-codename|).
>>>>>     
>>>>> +systemd Predictable Interface Names no longer MAC policy by default
>>>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>>> +
>>>>> +The :oe_git:`systemd recipe </openembedded-core/tree/meta/recipes-core/systemd>`
>>>>> +used to forcibly set the MAC policy by default when the ``pni-names``
>>>>> +:term:`distro feature <DISTRO_FEATURES>` was enabled. See
>>>>
>>>> s/was/is/ ?
>>>>
>>>>> +https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html#AlternativeNamesPolicy=.
>>>>> +
>>>>> +This is no longer the case. Instead, when the ``pni-names`` :term:`distro
>>>>
>>>> SHould we justify here why it is no longer the case?
>>>>
>>>>> +feature <DISTRO_FEATURES>` is enabled, the default policy from systemd is
>>>>> +selected (from https://github.com/systemd/systemd/blob/main/network/99-default.link).
>>>>> +
>>>>> +To set the MAC policy to systemd, add the following to a systemd ``.bbappend``
>>>>
>>>> s/to systemd/in systemd/ ?
>>>>
>>>>> +file in your custom layer::
>>>>> +
>>>>> +   do_install:append() {
>>>>> +          if ${@bb.utils.contains('PACKAGECONFIG', 'pni-names', 'true', 'false', d)}; then
>>>>> +                  if ! grep -q '^NamePolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>>>> +                          sed -i '/^NamePolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>>>> +                  fi
>>>>> +                  if ! grep -q 'AlternativeNamesPolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>>>> +                          sed -i '/AlternativeNamesPolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>>>> +                  fi
>>>>
>>>> My brain's sh parser says this is invalid because we're missing a
>>>> closing fi for the outermost if block.
>>>
>>> Yes, my bad I must have removed it by mistake
>>>
>>>> I'm also a bit worried about this code snippet as it'll just not be
>>>> tested or maintained once this gets merged.
>>>
>>> This snippet belongs to a release note for 5.3 so it already matches the Yocto
>>> version? I will include the version of systemd version here at the time of
>>> writing to give some more context.
>>>
>>
>> Does this mean that we already know it's not going to be compatible with
>> Wrynose?
>>
>> People are told to follow each migration manual between their current
>> and target Yocto releases, so this will essentially be understood as
>> "apply for any release starting from 5.3".
>>
>> We already saw how well maintained old example recipes were since we
>> don't test them, I'm not sure it makes sense to have code snippets we'll
>> likely never test as well?
> 
> A simpler approach could be to say:
> 
> """
> To set the mac policy to systemd, modify the ``99-default-link.link`` file
> provided by systemd in a ``.bbappend`` file to set the ``NamePolicy=`` and
> ``AlternativeNamesPolicy=`` settings to "mac".
> """
> 
> This should not require maintenance. Do you agree?
> 

There are many ways to set the NamePolicy key for a net device in 
systemd, c.f. https://man.archlinux.org/man/systemd.link.5

One can override 99-default.link from /usr/lib with one from /etc or 
/run. One can add 98-whatever.link anywhere with a [Match] section that 
would match the device in question and 99-default.link wouldn't be used 
then. One could add a 99-default.link.d/mac-policy.conf file to set the 
properties differently. And probably other ways I missed from the 
documentation.

NOT modifying 99-default.link probably would be a good idea too, because 
then you don't need to recompile systemd just for changing the policy 
for a link and can do that from another recipe (possibly even an image 
recipe modifying the rootfs on the fly depending on a distro variable 
for example).

The link filename could change also, in which case those instructions 
will be outdated too without our knowledge, but that should be easier 
for the user to figure out.

We can also mention/link to the commit in which this changed because it 
provides the diff with the (back-then-)default that got replaced and 
information on how to do that from the commit log as well.

We could simply say that when pni-names is unset, NamePolicy and 
AlternativeNamesPolicy are unset. Otherwise, the systemd upstream 
default is used.

Maybe add a link to the manpage as well, via :manpage:`systemd.link(5)` 
(not tested)?

No better suggestion though :/

Cheers,
Quentin

Re: [docs] [PATCH] migration-guides/migration-5.3.rst: add note on systemd pni-names change

[Antonin Godard]

On Wed Sep 10, 2025 at 4:08 PM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 9/10/25 3:32 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> On Wed Sep 10, 2025 at 3:16 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>> Hi Antonin,
>>>
>>> On 9/10/25 3:08 PM, Antonin Godard wrote:
>>>> On Tue Sep 9, 2025 at 3:59 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>>>> Hi Antonin,
>>>>>
>>>>> On 9/9/25 3:29 PM, Antonin Godard via lists.yoctoproject.org wrote:
>>>>>> Add a migration note on the pni-names default policy change after commit
>>>>>> <> in OE-Core.
>>>>>>
>>>>>
>>>>> General question, the systemd manpage specifies the policy as mac and
>>>>> not MAC, should we follow that as well?
>>>>>
>>>>>> Cc: Koen Kooi <koen.kooi@oss.qualcomm.com>
>>>>>> Cc: Ross Burton <Ross.Burton@arm.com>
>>>>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>>>>> ---
>>>>>>     documentation/migration-guides/migration-5.3.rst | 25 ++++++++++++++++++++++++
>>>>>>     1 file changed, 25 insertions(+)
>>>>>>
>>>>>> diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
>>>>>> index 2d2f8d91a..8aa7b537f 100644
>>>>>> --- a/documentation/migration-guides/migration-5.3.rst
>>>>>> +++ b/documentation/migration-guides/migration-5.3.rst
>>>>>> @@ -118,6 +118,31 @@ class. Instead, one should create a new recipe to build this FIT image, as
>>>>>>     described in the :ref:`Removed Classes <migration-guides/migration-5.3:Removed
>>>>>>     Classes>` section of the Migration notes for |yocto-ver| (|yocto-codename|).
>>>>>>     
>>>>>> +systemd Predictable Interface Names no longer MAC policy by default
>>>>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>>>> +
>>>>>> +The :oe_git:`systemd recipe </openembedded-core/tree/meta/recipes-core/systemd>`
>>>>>> +used to forcibly set the MAC policy by default when the ``pni-names``
>>>>>> +:term:`distro feature <DISTRO_FEATURES>` was enabled. See
>>>>>
>>>>> s/was/is/ ?
>>>>>
>>>>>> +https://www.freedesktop.org/software/systemd/man/latest/systemd.link.html#AlternativeNamesPolicy=.
>>>>>> +
>>>>>> +This is no longer the case. Instead, when the ``pni-names`` :term:`distro
>>>>>
>>>>> SHould we justify here why it is no longer the case?
>>>>>
>>>>>> +feature <DISTRO_FEATURES>` is enabled, the default policy from systemd is
>>>>>> +selected (from https://github.com/systemd/systemd/blob/main/network/99-default.link).
>>>>>> +
>>>>>> +To set the MAC policy to systemd, add the following to a systemd ``.bbappend``
>>>>>
>>>>> s/to systemd/in systemd/ ?
>>>>>
>>>>>> +file in your custom layer::
>>>>>> +
>>>>>> +   do_install:append() {
>>>>>> +          if ${@bb.utils.contains('PACKAGECONFIG', 'pni-names', 'true', 'false', d)}; then
>>>>>> +                  if ! grep -q '^NamePolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>>>>> +                          sed -i '/^NamePolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>>>>> +                  fi
>>>>>> +                  if ! grep -q 'AlternativeNamesPolicy=.*mac' ${D}${nonarch_libdir}/systemd/network/99-default.link; then
>>>>>> +                          sed -i '/AlternativeNamesPolicy=/s/$/ mac/' ${D}${nonarch_libdir}/systemd/network/99-default.link
>>>>>> +                  fi
>>>>>
>>>>> My brain's sh parser says this is invalid because we're missing a
>>>>> closing fi for the outermost if block.
>>>>
>>>> Yes, my bad I must have removed it by mistake
>>>>
>>>>> I'm also a bit worried about this code snippet as it'll just not be
>>>>> tested or maintained once this gets merged.
>>>>
>>>> This snippet belongs to a release note for 5.3 so it already matches the Yocto
>>>> version? I will include the version of systemd version here at the time of
>>>> writing to give some more context.
>>>>
>>>
>>> Does this mean that we already know it's not going to be compatible with
>>> Wrynose?
>>>
>>> People are told to follow each migration manual between their current
>>> and target Yocto releases, so this will essentially be understood as
>>> "apply for any release starting from 5.3".
>>>
>>> We already saw how well maintained old example recipes were since we
>>> don't test them, I'm not sure it makes sense to have code snippets we'll
>>> likely never test as well?
>> 
>> A simpler approach could be to say:
>> 
>> """
>> To set the mac policy to systemd, modify the ``99-default-link.link`` file
>> provided by systemd in a ``.bbappend`` file to set the ``NamePolicy=`` and
>> ``AlternativeNamesPolicy=`` settings to "mac".
>> """
>> 
>> This should not require maintenance. Do you agree?
>> 
[...]
> We could simply say that when pni-names is unset, NamePolicy and 
> AlternativeNamesPolicy are unset. Otherwise, the systemd upstream 
> default is used.
>
> Maybe add a link to the manpage as well, via :manpage:`systemd.link(5)` 
> (not tested)?
>
> No better suggestion though :/

Yes, I think we both want to keep things simple. I'll send a v2 with a link to
the manpage and just mention the NamePolicy and AlternativeNamesPolicy options,
as you phrased it.

Thanks!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com