Update headless.adoc: Add details about allowed symbols for the username

[leinher]

As the NAME_REGEX differs on different distributions I had to connect a screen to my 'headless' setup to find the following error message:

/boot/firmware/failed_userconf.txt detected:
Entered username is invalid:
Must only contrain lower-case letters, digits and hyphens, and must start with a letter.

The provided error message is clear and helps to fix this.
As finding the error message on a real headless setup is not that strait forward I hope this helps to avoid troubleshooting in the future.

[tdewey-rpi]

If we're including guidance on the username restrictions, we should also include guidance on length: https://systemd.io/USER_NAMES/#:~:text=%24%20%2C%20i.e.%20a%20size%20limit%20of,may%20be%20a%20dollar%20character.

[leinher]

If we're including guidance on the username restrictions, we should also include guidance on length: https://systemd.io/USER_NAMES/#:~:text=%24%20%2C%20i.e.%20a%20size%20limit%20of,may%20be%20a%20dollar%20character.

I had a look at this guideline, too. But it mentions that Debian based systems have no limit for the user name length and I wanted to only add documentation only about the current restrictions on the Raspberry Pi OS. (As asked in CONTRIBUTING.md.)

I'm happy to add one documentation that provides a recommendation for username length and points to systemd.io as resource for further reading.

[tdewey-rpi]

That's a fair point - however the rationale provided by the systemd.io page is pretty solid:

rationale: names longer than this cannot correctly appear in utmp/wtmp and create ambiguity with login accounting

Given that, I could see scope for a security issue - if a user is using the users command to identify active sessions, there is the possibility of a name clash across the first 31 characters (with a longer username remaining unique due to subsequent characters).

It's an interesting problem - and one I'm going to set a limit on in Raspberry Pi Imager for in order to mitigate.

[leinher]

OK, then I will add a note for the length, too.

Now this discussion starts to drift away from the pull request regarding the update of the documentation.

But I think it's still important do have it.

Restricting the username length in the rpi-imager is a good idea. BUT: Implementing restrictions in different tools that create users leads to inconsistency as the underling problem is not solved.
Even with the restrictions in the rpi-imager the headless setup mode (and probably the interactive setup on the Raspberry Pi OS Wizard) will still allow longer usernames.

In my opinion the maximum username length should be restricted for every of these setup methods.
If all of the setup tools use the adduser command the length restriction could by changing /etc/adduser.conf in the OS image.

What do you think?

[lurch]

Pulling in @spl237 for the discussion about the first-boot wizard.

[tdewey-rpi]

In my opinion the maximum username length should be restricted for every of these setup methods. If all of the setup tools use the adduser command the length restriction could by changing /etc/adduser.conf in the OS image.

What do you think?

I think this is a pretty nuanced area - guidance vs enforcement. I'm generally not keen on outright prohibiting something that could, in the marginal case, be acceptable - see my previous comments on Raspberry Pi Imager regarding the username 'root'. However, in this case I have to balance the enforcement cost vs the potential harm, and I conclude that the enforcement cost is fairly minimal (leaving at least 36^31 combinations, from 255^31 combinations), but the potential harm (not noticing an errant user, incorrect reporting) to be very high.

I defer to @spl237 for the wizard, but I judge the cost/harm in favour of introducing the restriction.

[spl237]

Just to make sure I understand - the suggestion is to add a restriction in the first-boot wizard to disallow usernames longer than 31 characters?

I've got no problem with doing that - it's a trivial change and as Tom says, it really isn't all that restrictive...

[leinher]

OK, so we agree on restricting the username to max 30 characters.

My previous question is still open:
a) Do we change rpi-imager, first-boot wizard and the headless documentation?
or
b) Do we configure the raspberry OS to not allow any tools to create users with long usernames?

In case a) it is still possible to create users with long names ether with the userconf.txt or using adduser later on a running system. It also mean that someone needs to keep track of the different setup methods and make sure none of these setup tools allow long usernames.
In case b) it would not be possible for any setup method to add a long username. In my opinion this is the better option as we enforce the max length in one place only. I can not tell the costs of a change like this in the OS image itself.

[spl237]

My previous question is still open: a) Do we change rpi-imager, first-boot wizard and the headless documentation? or b) Do we configure the raspberry OS to not allow any tools to create users with long usernames?

Given the tools (imager and wizard) will need to tell the user why their username was rejected, I think it is better to apply the restriction in the tools themselves.

[tdewey-rpi]

Agreed, this has to happen in the tooling where we can better present a help message.

[leinher]

I created two PRs for the headless setup and the wizard and leave the rpi-image to you.

[spl237]

Is there any reason for making this 30 characters rather than the 32 characters which has been the restriction in the wizard for several years now, and which was based on useradd's own restriction. It is also the same limit which is applied in Lite.

Where has this (arbitrary) 30 character figure come from? Every spec I can find which specifies a limit specifies 32 characters, not 30.

[leinher]

If we're including guidance on the username restrictions, we should also include guidance on length: https://systemd.io/USER_NAMES/#:~:text=%24%20%2C%20i.e.%20a%20size%20limit%20of,may%20be%20a%20dollar%20character.

The PR was mainly about adding the documentation about the allowed symbols. The discussion then drifted towards the allowed length. So probably we should keep length restriction untouched and focus on only update the documentation to save users time on a headless setup.

[lurch]

Is there any reason for making this 30 characters rather than the 32 characters which has been the restriction in the wizard for several years now

@spl237 In #3368 it was pointed out that Raspberry Pi Imager limits the length to 31 characters.