Remove all mentions of wpa_supplicant file #3166

nathan-contino · 2023-10-12T13:49:06Z

aallan · 2023-10-12T13:51:57Z

Works for me!

lurch · 2023-10-12T14:19:20Z

documentation/asciidoc/computers/configuration/headless.adoc

@@ -12,54 +12,11 @@ IMPORTANT: If you are installing Raspberry Pi OS, and intend to run it headless,

 === Configuring Networking

-You will need to define a `wpa_supplicant.conf` file for your particular wireless network. Put this file onto the boot folder of the SD card. When the Raspberry Pi boots for the first time, it will copy that file into the correct location in the Linux root file system and use those settings to start up wireless networking.
+To configure network access at first boot in a headless Raspberry Pi, use the advanced settings menu in the Imager application. Enter a the SSID and password for your preferred wireless network. Your Raspberry Pi will use these credentials to connect to the network on first boot. Some wireless adapters and some Raspberry Pi boards do not support 5Ghz networks; check the documentation for your wireless module to ensure compatibility with your preferred network.


'Imager' -> 'Raspberry Pi Imager' ?

"Enter a the SSID" doesn't sound quite right 😉

lurch · 2023-10-12T14:20:35Z

documentation/asciidoc/computers/configuration/headless.adoc


-The Raspberry Pi's IP address will not be visible immediately after power on, so this step is crucial to connect to it headlessly. Depending on the OS and editor you are creating this on, the file could have incorrect newlines or the wrong file extension so make sure you use an editor that accounts for this. Linux expects the line feed (LF) newline character. 
+With no keyboard or monitor, you need some way of xref:remote-access.adoc[remotely accessing] your headless Raspberry Pi. To enable SSH, place a file named `ssh` (no file extension) into the boot folder (`/boot/firmware/`) of the SD Card. For more information, see xref:remote-access.adoc#ssh[set up an SSH server].


If the user is already using RPi Imager to configure networking, they might as well use that to enable SSH too? 🙂

...or at least recommend using RPi Imager first, and then give the manual instructions afterwards?
The same thing should probably apply to the "Configuring a User" section too? (i.e. recommend RPi Imager, before giving the manual instructions)

lurch · 2023-10-12T14:35:28Z

documentation/asciidoc/computers/configuration/headless.adoc

@@ -8,58 +8,20 @@ If you already have an image on the micro SD card, you can access the xref:confi

 If you plan on using VNC to access the desktop environment of your headless Raspberry Pi, use the `raspi-config` tool to set a xref:configuration.adoc#resolution[default display resolution].

-IMPORTANT: If you are installing Raspberry Pi OS, and intend to run it headless, you will need to create a new user account. Since you will not be able to create the user account xref:getting-started.adoc#configuration-on-first-boot[using the first-boot wizard] as it requires both a monitor and a keyboard, you *MUST* add a `userconf.txt` file to the boot folder to create a user on first boot or configure the OS with a user account using the xref:getting-started.adoc#advanced-options[Advanced Menu] in the Raspberry Pi Imager.
+IMPORTANT: If you are installing Raspberry Pi OS, and intend to run it headless, you will need to create a new user account. Since you will not be able to create the user account xref:getting-started.adoc#configuration-on-first-boot[using the first-boot wizard] as it requires both a monitor and a keyboard, you *MUST* add a `userconf.txt` file to the boot folder to create a user on first boot or configure the OS with a user account using the xref:getting-started.adoc#advanced-options[Advanced Menu] in Raspberry Pi Imager.


Along the lines of my other comment, I think we should mention RPi Imager more prominently (as the recommeded approach), rather than only mentioning it at the end.

OK! I just made a minor wording tweak here, but I can update that logic in this section as well.

The reason this documentation is written the way it is, is that when this feature was first added, RPi Imager initially didn't have the option for configuring the username - that only came later.

lurch · 2023-10-12T15:17:27Z

documentation/asciidoc/computers/configuration/headless.adoc


-You will need to add a `userconf.txt` in the boot partition of the SD card; this is the part of the SD card which can be seen when it is mounted in a Windows or MacOS computer.
+In the boot partition of your SD card (`/boot/firmware`), create a file named `userconf.txt`.


In contrast to other places where the boot partition is mentioned, I think you shouldn't mention /boot/firmware here; because that's only the path that the boot partition appears at once you're actually booted into Raspberry Pi OS, but these instructions are about editing files (from another computer) before you boot Raspberry Pi OS for the first time.

Aha, excellent point. I now see why the original sentence included the confusing bit about the "part which is seen when it is mounted in a [separate] computer". Fixing now.

lurch · 2023-10-12T15:52:49Z

documentation/asciidoc/computers/configuration/headless.adoc


-In the boot partition of your SD card (`/boot/firmware`), create a file named `userconf.txt`.
+Using another computer, at the root (`/`) of your SD card, create a file named `userconf.txt`.


Sorry to nitpick, but I think even the

(`/`)

here is inappropriate and potentially confusing. Especially for Windows users!

lurch · 2023-10-12T15:54:26Z

documentation/asciidoc/computers/configuration/headless.adoc

-* place a file named `ssh` (no file extension) into the boot folder (`/boot/firmware/`) of the SD Card, then configure a user with `userconf.txt`
-
-IMPORTANT: To use SSH on a fresh Raspberry Pi OS installation, you must create a user account in the xref:getting-started.adoc#advanced-options[Advanced Menu] of Raspberry Pi Imager.
+* place a file named `ssh` into the root (`/`) of the SD card, then configure a user manually with `userconf.txt` following the instructions below


If there's only two options, does it really need a bulleted list? 🤔 🤷

Nah, in hindsight ignore this :)

lurch · 2023-10-12T16:01:57Z

documentation/asciidoc/computers/configuration/headless.adoc


 [[configuring-a-user]]
-=== Configuring a User
+=== Configure a user manually


Is it worth simply folding this entire section into the second bullet-point in the "Remote access" section, rather than making this a whole separate section in its own right?

hot take: yes! It's too much scope creep for the above section, let alone a bullet point. Breaks up the flow of the above section too much.

I would be willing to add an extra = to drop it one header level and nest it within that other section, though. But I don't think it's necessary since it is technically a discrete task.

Should the configuring a user thing go at the top of the whole thing because if you don't configure a user your headless installation is useless.

So "Setting up a headless Raspberry Pi"

First you should configure your user account...

So just between the lede, and the SSH section. You can't SSH without a user, so the user stuff should go before the SSH stuff?

I was trying to suggest that we make the userconf.txt instructions less prominent, since most people will just be doing this via Raspberry Pi Imager.

User setup in general? Yes. Manual user setup with userconf? Especially with the latest Bookworm changes for wireless network setup on initial boot, decreasingly important and worthy of pushing down the page.

Yes, that's true if we have to point users at Imager to configure the wifi anyway, they should also configure the user there at the same time (and SSH!). Then we can demphasis both the userconf.txt and ssh files.

lurch

Marvellous. Great work @nathan-contino !

nathan-contino · 2023-10-12T16:41:10Z

@aallan I think this might be ready to merge. Let me know if you have any more suggestions!

nathan-contino · 2023-10-12T16:45:37Z

🥳

Remove all mentions of wpa_supplicant file

606d6c7

aallan approved these changes Oct 12, 2023

View reviewed changes

aallan added bug fix bookworm 🐛 Issue with Bookworm labels Oct 12, 2023

lurch reviewed Oct 12, 2023

View reviewed changes

nathan-contino added 2 commits October 12, 2023 10:29

Implement fixes recommended by lurch

524daee

Fix broken xref

81467f5

lurch reviewed Oct 12, 2023

View reviewed changes

nathan-contino added 3 commits October 12, 2023 11:07

Implemented more fixes as per lurch comments

5ed744b

Fixed titlecase

0380d22

explicitly set anchor point for headless section

829813a

lurch reviewed Oct 12, 2023

View reviewed changes

Refine boot partition instructions

0d5540b

lurch reviewed Oct 12, 2023

View reviewed changes

Remove potentially-confusing slash

cd0e625

lurch reviewed Oct 12, 2023

View reviewed changes

Add new wired section and slightly tweak layout

b7251ee

lurch approved these changes Oct 12, 2023

View reviewed changes

aallan approved these changes Oct 12, 2023

View reviewed changes

aallan merged commit f11b539 into develop Oct 12, 2023

aallan deleted the remove_wpa_supplicant branch October 12, 2023 16:45

lurch mentioned this pull request Oct 12, 2023

De-emphasise userconf.txt #3128

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove all mentions of wpa_supplicant file #3166

Remove all mentions of wpa_supplicant file #3166

nathan-contino commented Oct 12, 2023

aallan commented Oct 12, 2023

lurch Oct 12, 2023

lurch Oct 12, 2023

lurch Oct 12, 2023

lurch Oct 12, 2023

nathan-contino Oct 12, 2023

lurch Oct 12, 2023 •

edited

Loading

lurch Oct 12, 2023

nathan-contino Oct 12, 2023

lurch Oct 12, 2023

lurch Oct 12, 2023

lurch Oct 12, 2023

lurch Oct 12, 2023

nathan-contino Oct 12, 2023

aallan Oct 12, 2023

aallan Oct 12, 2023

lurch Oct 12, 2023

nathan-contino Oct 12, 2023

aallan Oct 12, 2023

lurch left a comment

nathan-contino commented Oct 12, 2023

nathan-contino commented Oct 12, 2023


		The Raspberry Pi's IP address will not be visible immediately after power on, so this step is crucial to connect to it headlessly. Depending on the OS and editor you are creating this on, the file could have incorrect newlines or the wrong file extension so make sure you use an editor that accounts for this. Linux expects the line feed (LF) newline character.
		With no keyboard or monitor, you need some way of xref:remote-access.adoc[remotely accessing] your headless Raspberry Pi. To enable SSH, place a file named `ssh` (no file extension) into the boot folder (`/boot/firmware/`) of the SD Card. For more information, see xref:remote-access.adoc#ssh[set up an SSH server].


		You will need to add a `userconf.txt` in the boot partition of the SD card; this is the part of the SD card which can be seen when it is mounted in a Windows or MacOS computer.
		In the boot partition of your SD card (`/boot/firmware`), create a file named `userconf.txt`.


		In the boot partition of your SD card (`/boot/firmware`), create a file named `userconf.txt`.
		Using another computer, at the root (`/`) of your SD card, create a file named `userconf.txt`.

Remove all mentions of wpa_supplicant file #3166

Remove all mentions of wpa_supplicant file #3166

Conversation

nathan-contino commented Oct 12, 2023

aallan commented Oct 12, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lurch Oct 12, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lurch left a comment

Choose a reason for hiding this comment

nathan-contino commented Oct 12, 2023

nathan-contino commented Oct 12, 2023

lurch Oct 12, 2023 •

edited

Loading