Push to production

documentation/asciidoc/computers/configuration/configuring-networking.adoc

@@ -169,17 +169,15 @@ By default, Raspberry Pi OS attempts to automatically configure all network inte
 
 === Static IP Addresses
 
-If you wish to disable automatic configuration for an interface and instead configure it statically, add the details to `/etc/dhcpcd.conf`. For example:
+WARNING: If allocation of IP addresses is normally handled by a DHCP server on your network, allocating your Raspberry Pi a static IP address may cause an address conflict which may lead to networking problems.
+
+If you want to allocate a static IP address to your Raspberry Pi, the best way to do so is to reserve an address for it on your router. That way your Raspberry Pi will continue to have its address allocated via DHCP but will receive the same address each time. A "fixed" address can be allocated by your DHCP server associating it with the MAC address of your Raspberry Pi. Management of IP addresses will remain with the DHCP server and this will avoid address conflicts and potential network problems.
+
+However, if you wish to disable automatic configuration for an interface, and instead configure it statically, you can do so in `/etc/dhcpcd.conf`. For example:
 
 ----
 interface eth0
 static ip_address=192.168.0.4/24	
 static routers=192.168.0.254
 static domain_name_servers=192.168.0.254 8.8.8.8
 ----
-
-You can find the names of the interfaces present on your system using the `ip link` command.
-
-Note that if you have several Raspberry Pis connected to the same network, you may find it easier instead to set address reservations on your DHCP server. In this way, each Raspberry Pi will keep the same IP address, but they will all be managed in one place, making reconfiguring your network in the future more straightforward.
-
-On Raspberry Pi systems where the graphical desktop is installed, a GUI tool called `lxplug-network` is used to allow the user to make changes to the configuration of `dhcpcd`, including setting static IP addresses. The `lxplug-network` tool is based on `dhcpcd-ui`, which was also developed by Roy Marples.

documentation/asciidoc/computers/configuration/headless.adoc

@@ -4,6 +4,8 @@ If you do not use a monitor or keyboard to run your Raspberry Pi (known as headl
 
 Once an image is created on an SD card, by inserting it into a card reader on a Linux or Windows machines the xref:configuration.adoc#the-boot-folder[boot folder] can be accessed. Adding certain files to this folder will activate certain setup features on the first boot of the Raspberry Pi.
 
+IMPORTANT: If you are installing Raspberry Pi OS Lite 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 on first boot, you *MUST* add a `userconf.txt` file to the boot folder to create a user on first boot.
+
 === 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.
@@ -54,3 +56,18 @@ network={
 NOTE: Some older Raspberry Pi boards and some USB wireless dongles do not support 5GHz networks.
 
 NOTE: With no keyboard or monitor, you will need some way of xref:remote-access.adoc[remotely accessing] your headless Raspberry Pi. For headless setup, SSH can be enabled by placing a file named `ssh`, without any extension, onto the boot folder of the SD Card. For more information see the section on xref:remote-access.adoc#ssh[setting up an SSH server].
+
+=== Configuring a User
+
+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.
+
+This file should contain a single line of text, consisting of `username:password` – so your desired username, followed immediately by a colon, followed immediately by an *encrypted* representation of the password you want to use.
+
+To generate the encrypted password, the easiest way is to use OpenSSL on a Raspberry Pi that is already running – open a terminal window and enter:
+
+----
+echo 'mypassword' | openssl passwd -6 -stdin
+----
+
+This will produce what looks like a string of random characters, which is actually an encrypted version of the supplied password.
+

documentation/asciidoc/computers/getting-started.adoc

@@ -12,6 +12,4 @@ include::getting-started/installing-from-mac.adoc[]
 
 include::getting-started/installing-from-windows.adoc[]
 
-include::getting-started/sd-cards.adoc[]
-
-include::getting-started/connecting-a-monitor.adoc[]
+include::getting-started/configuring.adoc[]

documentation/asciidoc/computers/getting-started/configuring.adoc

@@ -0,0 +1,43 @@
+== Configuration on First Boot
+
+If you have not already configured your operating system using the xref:getting-started.adoc#advanced-options[Advanced Menu] of Raspberry Pi Imager when Raspberry Pi OS starts up for the first time you will be guided through initial setip.
+
+image::images/initial-setup/1.png[width="80%"]
+
+The Raspberry Pi OS configuration wizard will run on the first boot. The wizard starts off by allowing you to configure international settings and your timezone information.
+
+NOTE: If you are using a Bluetooth keyboard and mouse the first page will prompt you to put any Bluetooth keyboard or mouse you wish to use into pairing mode, and then to wait. As long as you are on the first page of the wizard, the Raspberry Pi will now scan for pairable Bluetooth mice and keyboards, and will automatically pair the first of each which it finds. You will see messages pop up to indicate that a Bluetooth device has been found and is being paired – you may need to wait a few seconds after the final “connected” dialog appears for the newly-connected device to wake up and start being used by the system. This works both with the built-in Bluetooth adapter on Raspberry Pi 3 and 4, and also with USB Bluetooth adapters on earlier models of Raspberry Pi – just make sure the USB adapter is inserted before the Raspberry Pi is booted.
+
+image::images/initial-setup/2.png[width="80%"]
+
+After hitting "Next" you'll be prompted to create a user account. Here you can choose your username, and a password.
+
+image::images/initial-setup/3.png[width="80%"]
+
+If you want to you can set your user name to the old default username of `pi`, which was used on older versions of Raspberry Pi OS. 
+
+NOTE: Some older software may require the presence of the `pi` user. 
+
+image::images/initial-setup/3.png[width="80%"]
+
+However, if you do choose to create this account you will trigger a warning message, and we'd advise you to avoid the old default password of `raspberry`.
+
+image::images/initial-setup/4.png[width="80%"]
+
+After creating an user account you can configure your screen,
+
+image::images/initial-setup/5.png[width="80%"]
+
+and your wireless network.
+
+image::images/initial-setup/6.png[width="80%"]
+
+Once your wireless network is configured and your Raspberry Pi has access to the Internet you will be prompted to update the operating system to the latest version. This will automatically download any patches and updates needed to bring your new operating system right up to date.
+
+image::images/initial-setup/8.png[width="80%"]
+
+Once the operating system is updated you will be prompted to reboot your Raspberry Pi.
+
+image::images/initial-setup/10.png[width="80%"]
+
+NOTE: If you are installing Raspberry Pi OS Lite you will still need to create a new user account. You will therefore be prompted to create an account by text prompts at the command line when you first boot a Lite image. If you are booting Raspberry Pi OS xref:configuration.adoc#setting-up-a-headless-raspberry-pi[headless] you *MUST* configure the operating system using Raspberry Pi Imager using the xref:getting-started.adoc#advanced-options[Advanced Menu].

documentation/asciidoc/computers/getting-started/installing-from-an-image.adoc

@@ -23,13 +23,15 @@ NOTE: If using Raspberry Pi Imager on Windows 10 with controlled folder access e
 
 NOTE: You can see which operating systems are most often downloaded, on our https://rpi-imager-stats.raspberrypi.com/[statistics page].
 
-You can now insert the SD card into the Raspberry Pi and power it up. For Raspberry Pi OS, if you need to manually log in, the default user name is `pi`, with password `raspberry`, and the default keyboard layout is set to https://datasheets.raspberrypi.com/keyboard-mouse/UK-layout.png[United Kingdom (UK)].
+You can now insert the SD card into the Raspberry Pi and power it up. When your Raspberry Pi boots for the first time a xref:getting-started.adoc#configuration-on-first-boot[configuration wizard] will run that allows you to set up your Raspberry Pi.
 
-You should change the default password straight away to ensure your Raspberry Pi is xref:configuration.adoc#securing-your-raspberry-pi[secure].
+NOTE: In the past Raspberry Pi OS had a default user name and password; user name `pi`, with password `raspberry`. This is no longer the case. However if you are using an older version of the operating system, or you are working with an existing installation, this default user may be present. If you have not already done so, you should change the default password straight away to ensure your Raspberry Pi is xref:configuration.adoc#securing-your-raspberry-pi[secure].
 
 ==== Advanced Options
 
-When you have the Raspberry Pi Imager open, and after you have selected the operating system to install, a cog wheel will appear allowing you to open an "Advanced Options" menu if it is supported by the operating system. This menu lets you carry out tasks like enabling SSH, or setting your Raspberry Pi's hostname, before first boot.
+When you have the Raspberry Pi Imager open, and after you have selected the operating system to install, a cog wheel will appear allowing you to open an "Advanced Options" menu if it is supported by the operating system. This menu lets you carry out tasks like enabling SSH, or setting your Raspberry Pi's hostname, and configuring the default user before first boot.
+
+NOTE: If you use the Advanced Options menu in Imager to configure your Raspberry Pi OS installation then the xref:getting-started.adoc#configuration-on-first-boot[configuration wizard] that normally runs on first boot will be skipped.
 
 image::images/rpi_imager.png[width="80%"]
 
@@ -39,6 +41,8 @@ image::images/rpi_imager_2.png[width="80%"]
 
 NOTE: In older versions of Imager you should push `Ctrl-Shift-X` to open the "Advanced" menu.
 
+If you are installing Raspberry Pi OS Lite and intend to run it xref:configuration.adoc#setting-up-a-headless-raspberry-pi[headless], you will still need to create a new user account. Since you will not be able to create the user account on first boot, you *MUST* configure the operating system using the Advanced Menu.
+
 === Downloading an Image
 
 If you are using a different tool than Raspberry Pi Imager to write to your SD Card, most require you to download the image first, then use the tool to write it to the card. Official images for recommended operating systems are available to download from the Raspberry Pi website https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit[downloads page]. Alternative operating systems for Raspberry Pi computers are https://www.raspberrypi.com/software/operating-systems/#third-party-software[also available] from some third-party vendors.

documentation/asciidoc/computers/getting-started/setting-up.adoc

@@ -4,8 +4,6 @@ To get started with your Raspberry Pi computer you'll need the following accesso
 
 A computer monitor, or television. Most should work as a display for the Raspberry Pi, but for best results, you should use a display with HDMI input. You'll also need an appropriate xref:getting-started.adoc#connecting-a-display[display] cable, to connect your monitor to your Raspberry Pi.
 
-NOTE: If your display uses an HDMI connection and has built-in speakers, you can use it to output sound.
-
 A computer keyboard and mouse
 
  * Any standard USB keyboard and mouse will work with your Raspberry Pi.
@@ -20,6 +18,34 @@ For the Raspberry Pi 4 Model B and Raspberry Pi 400 you should use the https://w
 
 Finally you'll need an xref:getting-started.adoc#sd-cards[SD card]; we recommend a minimum of 8GB micro SD card, and to use the https://www.raspberrypi.com/software/[Raspberry Pi Imager] to install an operating system onto it.
 
+=== Connecting a Display
+
+Unless you're setting up your Raspberry Pi to operate xref:configuration.adoc#setting-up-a-headless-raspberry-pi[headless], for regular use you'll want to plug the Raspberry Pi in to a display: either a computer monitor, or a television.
+
+Your Raspberry Pi has an HDMI port which you can connect directly to a monitor or TV with an HDMI cable. This is the easiest solution; some modern monitors and TVs have HDMI ports, some do not, but there are other options.
+
+NOTE: The Raspberry Pi 4 has two micro HDMI connectors, which require a good-quality micro HDMI cable, especially when using 4K monitors or television. Raspberry Pi sells a https://www.raspberrypi.com/products/micro-hdmi-to-standard-hdmi-a-cable/[suitable cable].
+
+If you're using your Raspberry Pi with a monitor with built-in speakers and are connecting to it using an HDMI cable you can also use it to output sound. For monitors with a DVI port, you can use an HDMI-to-DVI cable, or an HDMI cable with a DVI adapter. For older monitors that only support VGA, you can use an HDMI-to-VGA adapter. 
+
+
+NOTE: Unlike HDMI the DVI and VGA standards do not support audio.
+
+Finally, some models of Raspberry Pi have a composite out port for connecting to analog devices, but the type of connector varies depending on the model. The original Raspberry Pi used an RCA connector, and a standard RCA composite video lead will work. Others models (Raspberry Pi B+ and later) combine the audio out and composite out on to the same 3.5mm jack. This requires a particular type of lead, with audio left on the tip, audio right on ring 1, ground on ring 2, and video on the sleeve. This is the same as leads used on the Zune, and on Apple devices.
+
+More information on connecting to a monitor can be found in as part of the Raspberry Pi Foundation's https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up[Learning Resources].
+
+[[sd-cards]]
+=== SD Cards for Raspberry Pi
+
+Raspberry Pi computers use a micro SD card, except for very early models which use a full-sized SD card.
+
+WARNING: Because of a hardware limitation in the Raspberry Pi Zero, 1 and 2, the boot partition on the SD card must be 256GB or less otherwise the device will not boot up. Later models of Raspberry Pi 2 — with a BCM2837 SoC — along with the Raspberry Pi 3, 4, Zero 2 W, and the Raspberry Pi 400 do not have this limitation. This does not affect Raspberry Pi OS, which always uses a small boot partition.
+
+==== Recommended Capacity
+
+We recommend using an SD card of 8GB or greater capacity with Raspberry Pi OS. If you are using the lite version of Raspberry Pi OS, you can use a 4GB card. Other operating systems have different requirements: for example, LibreELEC can run from a smaller card. Please check with the supplier of the operating system to find out what capacity of card they recommend.
+
 === Optional items
 
 A network (Ethernet) cable to connect your Raspberry Pi to your local network and the Internet.
@@ -28,4 +54,11 @@ If you aren't using an HDMI monitor with speakers you might also need some form
 
 === Troubleshooting
 
-You can get help with setting up your Raspberry Pi on our https://forums.raspberrypi.com/[forums].
+If you are having problems with your SD card:
+
+* Make sure you are using a genuine SD card. The best way to avoid fake SD cards is to always buy from a reputable supplier.
+* Make sure you are using a good quality power supply: we recommend using an official Raspberry Pi power supply.
+* The cable from the power supply unit to the Raspberry Pi can also cause problems. This is usually due to the resistance of the wires in the USB power cable; to save money, USB cables have as little copper in them as possible, which causes a voltage drop across the cable.
+* Make sure you shut down the operating system correctly before you power down the Raspberry Pi.
+
+You can get help with setting up your Raspberry Pi on our https://forums.raspberrypi.com/[forums].