diff --git a/documentation/asciidoc/computers/configuration/headless.adoc b/documentation/asciidoc/computers/configuration/headless.adoc index e62c2eef0..32c56b80c 100644 --- a/documentation/asciidoc/computers/configuration/headless.adoc +++ b/documentation/asciidoc/computers/configuration/headless.adoc @@ -17,7 +17,7 @@ To connect to a wired network at first boot, plug your headless Raspberry Pi in === Connect to a wireless network -To configure wireless network access at first boot in a headless Raspberry Pi, use the advanced settings menu in Raspberry Pi Imager. Enter the SSID and password of 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. +To configure wireless network access at first boot for a headless Raspberry Pi, enter the network information in the **Customisation > Wi-Fi** tab in Raspberry Pi Imager. Enter the SSID and password of your preferred wireless network. Your Raspberry Pi uses these credentials to connect to the network on first boot. Some wireless adapters and some Raspberry Pi boards don't support 5 GHz networks; check the documentation for your wireless module to ensure compatibility with your preferred network. NOTE: Previous versions of Raspberry Pi OS made use of a `wpa_supplicant.conf` file which could be placed into the boot folder to configure wireless network settings. This functionality is not available from Raspberry Pi OS Bookworm onwards. @@ -25,8 +25,8 @@ NOTE: Previous versions of Raspberry Pi OS made use of a `wpa_supplicant.conf` f With no keyboard or monitor, you need a way to xref:remote-access.adoc[remotely control] your headless Raspberry Pi. On first boot, the only option is SSH. To enable SSH on a fresh installation of Raspberry Pi OS, choose one of the following methods: -* enable SSH in the OS customisation menu in Raspberry Pi Imager, then enter a username and password -* create a file named `ssh` at the root of the first partition of the SD card (labeled `bootfs`), then configure a user manually with `userconf.txt` following the instructions in the section below +* Enable SSH in the **Customisation > Remote Access** tab in Raspberry Pi Imager, choose the authentication mechanism, and provide a username and password or public key. +* Create a file named `ssh` at the root of the first partition of the SD card (labelled `bootfs`), then configure a user manually with `userconf.txt` using the instructions in the following section. For more information, see xref:remote-access.adoc#ssh[set up an SSH server]. Once you've connected over SSH, you can use `raspi-config` to xref:remote-access.adoc#vnc[enable VNC] if you'd prefer a graphical desktop environment. @@ -37,7 +37,7 @@ At the root of the first partition of your SD card (the filesystem labeled `boot This file should contain a single line of text, consisting of `:`: your desired username, followed immediately by a colon, followed immediately by an *encrypted* representation of the password you want to use. -NOTE: `` must only contain lower-case letters, digits and hyphens, and must start with a letter. It may not be longer than 31 characters. +NOTE: `` must only contain lowercase letters, digits, and hyphens, and must start with a letter. It may not be longer than 31 characters. To generate the encrypted password, use https://www.openssl.org[OpenSSL] on another computer. Open a terminal and enter the following: diff --git a/documentation/asciidoc/computers/getting-started/configuring.adoc b/documentation/asciidoc/computers/getting-started/configuring.adoc index 49d7f7d0e..be72ea1d1 100644 --- a/documentation/asciidoc/computers/getting-started/configuring.adoc +++ b/documentation/asciidoc/computers/getting-started/configuring.adoc @@ -16,7 +16,7 @@ Finally, connect the power supply to your Raspberry Pi. You should see the statu == Configuration on first boot -If you used OS customisation in Imager to preconfigure your Raspberry Pi, **congratulations!** Your device is ready to use. Proceed to xref:getting-started.adoc#next-steps[next steps] to learn how you can put your Raspberry Pi to good use. +If you customised your Raspberry Pi's operating system as part of the installation process in Imager, congratulations, your device is ready to use. Proceed to xref:getting-started.adoc#next-steps[next steps] to learn how you can put your Raspberry Pi to good use. If your Raspberry Pi does not boot within 5 minutes, check the status LED. If it's flashing, see the xref:configuration.adoc#led-warning-flash-codes[LED warning flash codes for more information]. If your Pi refuses to boot, try the following mitigation steps: @@ -24,7 +24,7 @@ If your Raspberry Pi does not boot within 5 minutes, check the status LED. If it * xref:getting-started.adoc#installing-the-operating-system[re-image your SD card]; be sure to complete the entire verify step in Imager * xref:raspberry-pi.adoc#bootloader_update_stable[update the bootloader] on your Raspberry Pi, then xref:getting-started.adoc#installing-the-operating-system[re-image your SD card] -If you chose to skip OS customisation in Imager, your Raspberry Pi will run a configuration wizard on first boot. You need a monitor and keyboard to navigate through the wizard; a mouse is optional. +If you chose to skip the customisation options in Imager, your Raspberry Pi runs a configuration wizard on first boot. You need a monitor and keyboard to navigate through the wizard; a mouse is optional. image::images/initial-setup/start.png[alt="Click Next to get started with configuration.",width="80%"] diff --git a/documentation/asciidoc/computers/getting-started/images/imager/app-options.png b/documentation/asciidoc/computers/getting-started/images/imager/app-options.png new file mode 100644 index 000000000..713ef93ac Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/app-options.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/are-you-sure.png b/documentation/asciidoc/computers/getting-started/images/imager/are-you-sure.png index 73c1f6c84..3e632a8f4 100644 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/are-you-sure.png and b/documentation/asciidoc/computers/getting-started/images/imager/are-you-sure.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/choose-device.png b/documentation/asciidoc/computers/getting-started/images/imager/choose-device.png new file mode 100644 index 000000000..8e2cb92e4 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/choose-device.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/choose-os.png b/documentation/asciidoc/computers/getting-started/images/imager/choose-os.png index c6fd9a25d..5381de755 100644 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/choose-os.png and b/documentation/asciidoc/computers/getting-started/images/imager/choose-os.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/choose-storage.png b/documentation/asciidoc/computers/getting-started/images/imager/choose-storage.png index 274b52b81..e6bab09d8 100644 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/choose-storage.png and b/documentation/asciidoc/computers/getting-started/images/imager/choose-storage.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/connect-auth-key.png b/documentation/asciidoc/computers/getting-started/images/imager/connect-auth-key.png new file mode 100644 index 000000000..fe750f3a9 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/connect-auth-key.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/finished.png b/documentation/asciidoc/computers/getting-started/images/imager/finished.png index bd8df650f..35db8feef 100644 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/finished.png and b/documentation/asciidoc/computers/getting-started/images/imager/finished.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-connect-token.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-connect-token.png new file mode 100644 index 000000000..e8725027f Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-connect-token.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-connect.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-connect.png new file mode 100644 index 000000000..33053135f Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-connect.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-hostname.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-hostname.png new file mode 100644 index 000000000..e54bb316e Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-hostname.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-interfaces.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-interfaces.png new file mode 100644 index 000000000..91e3a0bf3 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-interfaces.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-locale.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-locale.png new file mode 100644 index 000000000..1ecce5a11 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-locale.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-options.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-options.png deleted file mode 100644 index 971108d39..000000000 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-options.png and /dev/null differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-prompt.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-prompt.png deleted file mode 100644 index 9998c82b0..000000000 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-prompt.png and /dev/null differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-site.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-site.png new file mode 100644 index 000000000..f30363332 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-site.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-ssh.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-ssh.png new file mode 100644 index 000000000..19eff230a Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-ssh.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-user.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-user.png new file mode 100644 index 000000000..7e55a2b7c Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-user.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-wifi-open.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-wifi-open.png new file mode 100644 index 000000000..c213cf872 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-wifi-open.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-wifi-secure.png b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-wifi-secure.png new file mode 100644 index 000000000..cb34d8490 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/os-customisation-wifi-secure.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/summary.png b/documentation/asciidoc/computers/getting-started/images/imager/summary.png new file mode 100644 index 000000000..0fb9d7f71 Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/summary.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/verify.png b/documentation/asciidoc/computers/getting-started/images/imager/verify.png new file mode 100644 index 000000000..9b0f7cd5e Binary files /dev/null and b/documentation/asciidoc/computers/getting-started/images/imager/verify.png differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/welcome.png b/documentation/asciidoc/computers/getting-started/images/imager/welcome.png deleted file mode 100644 index 13fc67987..000000000 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/welcome.png and /dev/null differ diff --git a/documentation/asciidoc/computers/getting-started/images/imager/writing.png b/documentation/asciidoc/computers/getting-started/images/imager/writing.png index a21845b2d..39c1232d9 100644 Binary files a/documentation/asciidoc/computers/getting-started/images/imager/writing.png and b/documentation/asciidoc/computers/getting-started/images/imager/writing.png differ diff --git a/documentation/asciidoc/computers/getting-started/install.adoc b/documentation/asciidoc/computers/getting-started/install.adoc index 534417311..1b2e82fb9 100644 --- a/documentation/asciidoc/computers/getting-started/install.adoc +++ b/documentation/asciidoc/computers/getting-started/install.adoc @@ -1,124 +1,210 @@ [[installing-the-operating-system]] == Install an operating system -To use your Raspberry Pi, you'll need an operating system. By default, Raspberry Pis check for an operating system on any SD card inserted in the SD card slot. +To use your Raspberry Pi, you'll need an operating system. By default, Raspberry Pi devices check for an operating system on any SD card inserted in the SD card slot. -Depending on your Raspberry Pi model, you can also boot an operating system from other storage devices, including USB drives, storage connected via a HAT, and network storage. +Depending on your Raspberry Pi model, you can also boot an operating system from other storage devices, including USB drives, storage connected through a HAT, and network storage. To install an operating system on a storage device for your Raspberry Pi, you'll need: -* a computer you can use to image the storage device into a boot device -* a way to plug your storage device into that computer +* A computer you can use to image the storage device into a boot device +* A way to plug your storage device into that computer Most Raspberry Pi users choose microSD cards as their boot device. We recommend installing an operating system using xref:getting-started.adoc#raspberry-pi-imager[Raspberry Pi Imager]. -Raspberry Pi Imager is a tool that helps you download and write images on macOS, Windows, and Linux. Imager includes many popular operating system images for Raspberry Pi. Imager also supports loading images downloaded directly from https://www.raspberrypi.com/software/operating-systems/[Raspberry Pi] or third-party vendors such as https://ubuntu.com/download/raspberry-pi[Ubuntu]. You can use Imager to preconfigure credentials and remote access settings for your Raspberry Pi. - -Imager supports images packaged in the `.img` format as well as container formats like `.zip`. - If you have no other computer to write an image to a boot device, you may be able to install an operating system xref:getting-started.adoc#install-over-the-network[directly on your Raspberry Pi from the internet]. [[raspberry-pi-imager]] === Install using Imager +Raspberry Pi Imager is a tool, available on macOS, Windows, and Linux, that helps you download images and write them to a storage device. Imager includes many popular operating system images for Raspberry Pi. Imager also supports loading images downloaded directly from https://www.raspberrypi.com/software/operating-systems/[Raspberry Pi] or third-party vendors such as https://ubuntu.com/download/raspberry-pi[Ubuntu]. You can use Imager to preconfigure credentials and remote access settings for your Raspberry Pi. + +Imager supports images packaged in the `.img` format as well as container formats like `.zip` or `.xz`. + //// TODO: Update this video for the new Imager look & flow (video::ntaXWS8Lk34[youtube,width=80%,height=400px]) //// -You can install Imager in the following ways: +==== Step 1. Install and launch Imager -* Download the latest version from https://www.raspberrypi.com/software/[raspberrypi.com/software] and run the installer. -* Install it from a terminal using your package manager, e.g. `sudo apt install rpi-imager`. +Download Raspberry Pi Imager to your computer (Windows, Mac, or Linux): -Once you've installed Imager, launch the application by clicking the Raspberry Pi Imager icon or running `rpi-imager`. +. Install Imager in one of the following ways: +* On Windows and Mac, download the latest version from https://www.raspberrypi.com/software/[the Raspberry Pi website]. Run the installer. +* On Raspberry Pi OS, run `sudo apt install rpi-imager`. +* On other Linux OSes, download the latest version as an AppImage from https://www.raspberrypi.com/software/[the Raspberry Pi website]. Make the AppImage executable. -image::images/imager/welcome.png[alt="Raspberry Pi Imager main window.",width="80%"] +. Launch the Raspberry Pi Imager application in one of the following ways: +* Find it in your application menu. +* Select the Raspberry Pi Imager icon on your desktop. +* Run the AppImage file as root. For example, with the command: `sudo ./Raspberry_Pi_Imager-2.0.0-desktop-x86_64.AppImage` -Click **Choose device** and select your Raspberry Pi model from the list. +==== Step 2. Configure the fundamentals -image::images/imager/choose-model.png[alt="Raspberry Pi model selections in Imager.",width="80%"] +Tell Raspberry Pi Imager what combination of hardware and operating system you want to use: -Next, click **Choose OS** and select an operating system to install. Imager always shows the recommended version of Raspberry Pi OS for your model at the top of the list. +. In the *Device* tab, select your Raspberry Pi model from the list. Select *Next*. ++ +image::images/imager/choose-device.png[alt="Raspberry Pi Imager Device tab.",width="80%"] +. In the *OS* tab, choose from the available operating systems. Select *Next*. ++ +Imager shows the recommended version of Raspberry Pi OS for your device at the top of the list. +To install an operating system from an image on your computer, select the *Use Custom* option. ++ image::images/imager/choose-os.png[alt="Operating system selections in Imager.",width="80%"] -Connect your preferred storage device to your computer. For example, plug a microSD card in using an external or built-in SD card reader. Then, click **Choose storage** and select your storage device. - -WARNING: If you have more than one storage device connected to your computer, _be sure to choose the correct device!_ You can often identify storage devices by size. If you're unsure, disconnect other devices until you've identified the device you want to image. +. Connect your preferred storage device to your computer. For example, plug a microSD card in using an external or built-in SD card reader. +. In the *Storage* tab, select the storage device to write the image to. Select *Next*. ++ image::images/imager/choose-storage.png[alt="Storage selection options in Imager.",width="80%"] - -Next, click **Next**. - -image::images/imager/os-customisation-prompt.png[alt="Imager prompt to open OS customisation menu.",width="80%"] - -In a popup, Imager will ask you to apply OS customisation. We strongly recommend configuring your Raspberry Pi via the OS customisation settings. Click the **Edit Settings** button to open xref:getting-started.adoc#advanced-options[OS customisation]. - -If you don't configure your Raspberry Pi via OS customisation settings, Raspberry Pi OS will ask you for the same information at first boot during the xref:getting-started.adoc#configuration-on-first-boot[configuration wizard]. You can click the **No** button to skip OS customisation. ++ +WARNING: If you have more than one storage device connected to your computer, _be sure to choose the correct device!_ You can often identify storage devices by size. If you're unsure, disconnect other devices until you've identified the device you want to image. Imager warns you if you attempt to overwrite a system drive on your computer. [[advanced-options]] -==== OS customisation - -The OS customisation menu lets you set up your Raspberry Pi before first boot. You can preconfigure: - -* a username and password -* Wi-Fi credentials -* the device hostname -* the time zone -* your keyboard layout -* remote connectivity - -When you first open the OS customisation menu, you might see a prompt asking for permission to load Wi-Fi credentials from your host computer. If you respond "yes", Imager will prefill Wi-Fi credentials from the network you're currently connected to. If you respond "no", you can enter Wi-Fi credentials manually. - -The **hostname** option defines the hostname your Raspberry Pi broadcasts to the network using https://en.wikipedia.org/wiki/Multicast_DNS[mDNS]. When you connect your Raspberry Pi to your network, other devices on the network can communicate with your computer using `.local` or `.lan`. +==== Step 3. Customise your operating system -The **username and password** option defines the username and password of the admin user account on your Raspberry Pi. +Raspberry Pi OS and some third-party operating systems support customisation. If you're installing one of these operating systems, you can use the next set of steps in Imager to customise it. These steps are optional and can be skipped by choosing *Skip customisation*. However, we strongly recommend that you set up your Raspberry Pi before first boot by using the customisation settings in Imager. -The **wireless LAN** option allows you to enter an SSID (name) and password for your wireless network. If your network does not broadcast an SSID publicly, you should enable the "Hidden SSID" setting. By default, Imager uses the country you're currently in as the "Wireless LAN country". This setting controls the Wi-Fi broadcast frequencies used by your Raspberry Pi. Enter credentials for the wireless LAN option if you plan to run a headless Raspberry Pi. +You can preconfigure: -The **locale settings** option allows you to define the time zone and default keyboard layout for your Pi. - -image::images/imager/os-customisation-general.png[alt="General settings in the OS customisation menu.",width="80%"] - -The **Services** tab includes settings to help you connect to your Raspberry Pi remotely. +* The device hostname +* The time zone +* Your keyboard layout +* A username and password +* Wi-Fi credentials +* Remote connectivity +* Raspberry Pi Connect +* Hardware interfaces for peripherals +* Raspberry Pi USB Gadget mode + +If you've already completed the customisation steps previously with Imager, the values you chose are pre-filled in the following steps. + +If you don't configure your Raspberry Pi with these OS customisation settings, your operating system asks you for the same information after first boot. For Raspberry Pi OS, this first-boot configuration happens in the xref:getting-started.adoc#configuration-on-first-boot[configuration wizard]. + +. In the *Customisation > Hostname* tab, enter a host name for your Raspberry Pi that includes only letters, numbers, and hyphens. Select *Next*. ++ +Your Raspberry Pi broadcasts this host name to the network using https://en.wikipedia.org/wiki/Multicast_DNS[mDNS]. When you connect your Raspberry Pi to your network, other devices on the network can communicate with your computer using `.local` or `.lan`. ++ +image::images/imager/os-customisation-hostname.png[alt="Imager OS Customisation Hostname tab.",width="80%"] + +. In the *Customisation > Localisation* tab, choose your capital city. Imager autocompletes the time zone and keyboard layout for that city; you can change these settings. Select *Next*. ++ +image::images/imager/os-customisation-locale.png[alt="Imager OS Customisation Localisation tab.",width="80%"] + +. In the *Customisation > User* tab, enter a username and password for the admin user of your Raspberry Pi. Select *Next*. ++ +image::images/imager/os-customisation-user.png[alt="Imager OS Customisation User tab.",width="80%"] + +. In the *Customisation > Wi-Fi* tab, on first use, Imager pre-fills the SSID (name) and password of the Wi-Fi network you're currently connected to. ++ +.. Select whether to connect to a *Secure network* or an *Open network*. +.. If there's no pre-filled information or if you want to change it, enter the SSID (name) of your wireless network. For secure networks, enter and confirm the password for the network. +.. If your network doesn't broadcast an SSID publicly, enable the *Hidden SSID* setting. +.. Select *Next*. ++ +[.clearfix] +-- +[.left] +image::images/imager/os-customisation-wifi-secure.png[alt="Imager OS Customisation Wi-Fi tab, secure network.",width="100%"] +[.left] +image::images/imager/os-customisation-wifi-open.png[alt="Imager OS Customisation Wi-Fi tab, open network.",width="100%"] +-- + +. In the *Customisation > Remote Access* tab, configure your SSH settings. +.. To use your Raspberry Pi remotely over your network, toggle the *Enable SSH* switch to the active position. ++ +If you plan to run a headless Raspberry Pi, either enable this option or configure Raspberry Pi Connect for your device. +.. If you enable SSH, choose the authentication method to use: +* Choose *Use password authentication* to SSH into your Raspberry Pi over the network using the username and password you provided in the *Customisation > User* tab. +* Choose *Use public key authentication* to configure your Raspberry Pi to use SSH key-based authentication. Imager shows a field to provide a public key. +If you already have a public RSA key in your SSH configuration, Imager uses that public key. If you don't, you can copy a public key in to Imager or browse to locate a public key file on your computer. ++ +image::images/imager/os-customisation-ssh.png[alt="Imager OS Customisation Remote Access tab.",width="80%"] + +. Some operating systems now show the *Customisation > Raspberry Pi Connect* tab. To link your device to your xref:../services/connect.adoc[Raspberry Pi Connect account], complete the following steps: +.. Toggle the *Enable Raspberry Pi Connect* switch to the active position. ++ +image::images/imager/os-customisation-connect.png[alt="Imager OS Customisation Raspberry Pi Connect tab.",width="60%"] +.. Select *Open Raspberry Pi Connect*. The Raspberry Pi Connect website opens in your default browser. ++ +image::images/imager/os-customisation-site.png[alt="Raspberry Pi Connect page.",width="60%"] +.. Sign in to your Raspberry Pi ID account or, if you don't yet have an account, sign up. ++ +image::images/imager/connect-auth-key.png[alt="Raspberry Pi Connect new auth key page.",width="60%"] +.. On the *New auth key* page, create your auth key. ++ +The auth key is a single-use, temporary token. The Raspberry Pi Connect website displays how long after its creation the token expires. To use the token, ensure that you boot your Raspberry Pi and connect it to the internet before the expiry time. ++ +*** If your Raspberry Pi ID account isn't a member of any organisations, select *Create auth key and launch Raspberry Pi Imager*. +*** If you are a member of one or more organisations, select the organisation or account to associate the key with. Then select *Create auth key and launch Raspberry Pi Imager*. +.. Your browser might ask you whether you want to allow the site to open Raspberry Pi Imager. Confirm that you want to open Raspberry Pi Imager. ++ +Raspberry Pi Imager opens at the *Raspberry Pi Connect* tab. This tab shows a message to confirm that Imager received the authentication token from the browser and a field containing the token. ++ +If the token isn't copied across, you can copy it into Imager manually. Open the *Having trouble?* section of the Raspberry Pi Connect web page, copy the token, and paste it into the token field in Imager. ++ +image::images/imager/os-customisation-connect-token.png[alt="Raspberry Pi Connect token received message.",width="60%"] +.. Select *Next*. -If you plan to use your Raspberry Pi remotely over your network, check the box next to **Enable SSH**. You should enable this option if you plan to run a headless Raspberry Pi. +//// +. Some device and operating system combinations now show the *Customisation > Interfaces & Features* tab. On this tab, you can enable the following features: +* Hardware interfaces needed to use your Raspberry Pi with certain peripherals, such as sensors, displays, network controllers, or embedded systems. +* USB Gadget Mode feature. For more information, see https://github.com/raspberrypi/rpi-usb-gadget?tab=readme-ov-file[Raspberry Pi USB Gadget]. ++ +image::images/imager/os-customisation-interfaces.png[alt="Imager OS Customisation Interfaces & Features tab.",width="80%"] ++ +After choosing your options, select *Next*. +//// -* Choose the **password authentication** option to SSH into your Raspberry Pi over the network using the username and password you provided in the general tab of OS customisation. +==== Step 4. Set the Imager options -* Choose **Allow public-key authentication only** to preconfigure your Raspberry Pi for passwordless public-key SSH authentication using a private key from the computer you're currently using. If already have an RSA key in your SSH configuration, Imager uses that public key. If you don't, you can click **Run SSH-keygen** to generate a public/private key pair. Imager will use the newly-generated public key. +You can choose to configure the behaviour of Imager during a write. Do this at any point before you write the image by selecting *App Options*. -image::images/imager/os-customisation-services.png[alt="Services settings in the OS customisation menu.",width="80%"] +In the *App Options* dialog box you can configure the following options: -OS customisation also includes an **Options** menu that allows you to configure the behaviour of Imager during a write. These options allow you to play a noise when Imager finishes verifying an image, to automatically unmount storage media after verification, and to disable telemetry. +* Whether Imager plays an alert sound when the write finishes. +* Whether Imager ejects the storage media when the write finishes. +* Whether Imager sends anonymous telemetry to us about your device and operating system. For more information, see https://github.com/raspberrypi/rpi-imager?tab=readme-ov-file#anonymous-metrics-telemetry[Anonymous metrics (telemetry)]. +* Whether Imager shows warnings during the write process. -image::images/imager/os-customisation-options.png[alt="Options in the OS customisation menu.",width="80%"] +(Advanced users) The *App Options* dialog box also lets you set a custom repository to retrieve the operating system and devices list from. For more information, see xref:../computers/raspberry-pi.adoc#IMAGER_REPO_URL[Imager repo URL]. -==== Write +image::images/imager/app-options.png[alt="App Options dialog.",width="80%"] -When you've finished entering OS customisation settings, click **Save** to save your customisation. +==== Step 5. Write the image to the storage device -Then, click **Yes** to apply OS customisation settings when you write the image to the storage device. +After you've gone through the tabs in Imager, it shows a summary page where you can review your choices. -Finally, respond **Yes** to the "Are you sure you want to continue?" popup to begin writing data to the storage device. +. If you're happy with your choices and want to proceed, select *Write*. ++ +image::images/imager/summary.png[alt="Reviewing your choices in Imager before writing.",width="80%"] +. Imager shows a prompt warning you that you're about to overwrite all data on your storage media. To continue, select *I understand, erase and write*. ++ +If you see an admin prompt asking for permissions to read and write to your storage medium, grant Imager the permissions to proceed. ++ image::images/imager/are-you-sure.png[alt="Confirming a reimage of a storage device in Imager.",width="80%"] -If you see an admin prompt asking for permissions to read and write to your storage medium, grant Imager the permissions to proceed. +Imager begins writing your image to the storage media. This can take a few minutes; grab a cup of coffee while you wait. -.Grab a cup of coffee or go for a walk. This could take a few minutes. +.Imager writes to the storage device. image::images/imager/writing.png[alt="Writing an image to a device in Imager.",width="80%"] -.If you want to live especially dangerously, you can click **cancel verify** to skip the verification process. -image::images/imager/stop-ask-verify.png[alt="Verifying an image on a device in Imager.",width="80%"] +After writing the image, Imager verifies that the image is correctly written. We recommend that you complete the verification step. However, if you want to cancel verification, select *Skip verification*. + +.After writing the image, Imager verifies it. +image::images/imager/verify.png[alt="Verifying an image on a device in Imager.",width="80%"] -When you see the "Write Successful" popup, your image has been completely written and verified. You're now ready to boot a Raspberry Pi from the storage device! +After the image is written and verified, Imager shows the *Done* tab. Select *Finish* to exit Imager. +.The imaging process is complete. image::images/imager/finished.png[alt="The screen Imager shows when it finishes writing an image to a storage device.",width="80%"] -Next, proceed to the xref:getting-started.adoc#configuration-on-first-boot[first boot configuration instructions] to get your Raspberry Pi up and running. +Next, proceed to the xref:getting-started.adoc#set-up-your-raspberry-pi[Set up your Raspberry Pi] section to get your Raspberry Pi up and running. === Install over the network @@ -137,7 +223,7 @@ Network Install requires the following: * a keyboard * a wired internet connection -To launch Network Install, power on your Raspberry Pi _while pressing and holding the **SHIFT** key_ in the following configuration: +To launch Network Install, power on your Raspberry Pi _while pressing and holding the *SHIFT* key_ in the following configuration: * no bootable storage device * attached keyboard diff --git a/documentation/asciidoc/computers/raspberry-pi/boot-eeprom.adoc b/documentation/asciidoc/computers/raspberry-pi/boot-eeprom.adoc index 0e27031dc..0b92e16c1 100644 --- a/documentation/asciidoc/computers/raspberry-pi/boot-eeprom.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/boot-eeprom.adoc @@ -30,24 +30,28 @@ NOTE: Compute Module 4 and Compute Module 4S do not support automatic bootloader Raspberry Pi Imager provides a GUI for updating the bootloader and selecting the boot mode. -. Download https://www.raspberrypi.com/software/[Raspberry Pi Imager] -. Select a spare SD card (bootloader images overwrite the entire card) -. Launch Raspberry Pi Imager -. Select `Choose OS` -. Select `Misc utility images` -+ +. Download https://www.raspberrypi.com/software/[Raspberry Pi Imager]. +. Select an unused SD card. All data on this SD card is overwritten by Imager. +. Connect the SD card to the computer where Imager runs. +. Launch Raspberry Pi Imager. +. In the **Device** tab, select your Raspberry Pi model from the list. Select **Next**. +. In the **OS** tab, choose **Misc utility images** ++ image::images/misc-utility-images.png[alt="Select Misc utility images",width="60%"] -. Select `Bootloader` for your version of Raspberry Pi (Pi 400 is part of the 4 family) -+ +. Select **Bootloader** for your version of Raspberry Pi. ++ image::images/bootloader-family-select.png[alt="Choose a family for your bootloader",width="60%"] -. Select a boot mode: `SD` (recommended), `USB` or `Network` -+ +. Select a boot mode. We recommend **SD Card Boot**. Select **Next**. ++ image::images/bootloader-storage-select.png[alt="Choose the storage from which you'd like to boot",width="60%"] -. Select `SD card` and then `Write` -. Click `Yes` to continue -. Boot the Raspberry Pi with the new image and wait for at least ten seconds -. When the green activity LED blinks with a steady pattern and the HDMI display shows a green screen, you have successfully written the bootloader -. Power off the Raspberry Pi and remove the SD card +. In the **Storage** tab, select your SD card. Select **Next**.` +. In the **Writing** tab, review your choices and select **Write** to proceed. +. You're prompted to confirm overwriting the data on the SD card. To continue, select **I understand, erase and write**. +. Wait until Imager has finished writing and verifying the SD card +. Connect the SD card to the Raspberry Pi device where you want to update the bootloader. +. Boot the Raspberry Pi with the new image and wait for at least ten seconds. +. When the green activity LED blinks with a steady pattern and the HDMI display shows a green screen, you've successfully written the bootloader. +. Power off the Raspberry Pi and remove the SD card. [[raspi-config]] ==== Use `raspi-config` to update the bootloader diff --git a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc index 5ad20922a..4a650b803 100644 --- a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc @@ -446,12 +446,18 @@ Default: `net_install` [[IMAGER_REPO_URL]] ==== `IMAGER_REPO_URL` -The embedded Raspberry Pi Imager application is configured with a JSON file downloaded at startup. +The Raspberry Pi Imager application is configured with a JSON file downloaded at startup. By default, Raspberry Pi Imager uses the JSON at https://downloads.raspberrypi.com/os_list_imagingutility_v4.json. -You can change the URL of the JSON file used by the embedded Raspberry Pi Imager application to get it to offer your own images. -You can test this with the standard https://www.raspberrypi.com/software/[Raspberry Pi Imager] application by passing the URL via the `--repo` argument. -Default: `\http://downloads.raspberrypi.org/os_list_imagingutility_v3.json` +You can change the URL of the JSON file used by the Raspberry Pi Imager application to get it to offer your own images by one of the following methods: + +* Pass the `--repo` argument when starting Imager, for example: `rpi-imager --repo https://downloads.raspberrypi.com/os_list_imagingutility_v4.json` +* In the Raspberry Pi Imager UI. +.. Go to the **App Options** dialog box. +.. For **Content Repository**, select **Edit**. +** To use a JSON file on your computer, choose **Use custom file** and browse to the file location. +** To use a JSON file hosted at a URL, choose **Use custom URL** and enter the URL. +.. Click **Apply & Restart**. Imager resets your device and OS selections, and returns to the **Device** tab. [[NET_INSTALL_ENABLED]] ==== `NET_INSTALL_ENABLED` diff --git a/documentation/asciidoc/computers/raspberry-pi/images/bootloader-family-select.png b/documentation/asciidoc/computers/raspberry-pi/images/bootloader-family-select.png index 67811b1c6..aaa5d11bb 100644 Binary files a/documentation/asciidoc/computers/raspberry-pi/images/bootloader-family-select.png and b/documentation/asciidoc/computers/raspberry-pi/images/bootloader-family-select.png differ diff --git a/documentation/asciidoc/computers/raspberry-pi/images/bootloader-storage-select.png b/documentation/asciidoc/computers/raspberry-pi/images/bootloader-storage-select.png index 91f00cbfe..9c38977a3 100644 Binary files a/documentation/asciidoc/computers/raspberry-pi/images/bootloader-storage-select.png and b/documentation/asciidoc/computers/raspberry-pi/images/bootloader-storage-select.png differ diff --git a/documentation/asciidoc/computers/raspberry-pi/images/misc-utility-images.png b/documentation/asciidoc/computers/raspberry-pi/images/misc-utility-images.png index 016ed706d..91c8c1fc9 100644 Binary files a/documentation/asciidoc/computers/raspberry-pi/images/misc-utility-images.png and b/documentation/asciidoc/computers/raspberry-pi/images/misc-utility-images.png differ diff --git a/documentation/asciidoc/computers/remote-access/ssh.adoc b/documentation/asciidoc/computers/remote-access/ssh.adoc index c6861b784..b891b764b 100644 --- a/documentation/asciidoc/computers/remote-access/ssh.adoc +++ b/documentation/asciidoc/computers/remote-access/ssh.adoc @@ -21,9 +21,8 @@ While flashing a fresh OS image:: To configure SSH on a completely new installation of Raspberry Pi OS: + . Follow the instructions in the xref:../computers/getting-started.adoc#raspberry-pi-imager[Install with Imager] guide. -. During the **OS Customisation** step, navigate to the **Services** tab. -. Tick the checkbox to **Enable SSH**. -. Select **password authentication** to log in using the same username and password you use while physically using your Raspberry Pi. Select **Allow public-key authentication only** to xref:remote-access.adoc#configure-ssh-without-a-password[configure an SSH key] for passwordless login. +. In the **Customisation > Remote Access** tab, toggle the **Enable SSH** switch to the active position. +. Select **Use password authentication** to log in using the same username and password you use while physically using your Raspberry Pi. Select **Use public key authentication** to xref:remote-access.adoc#configure-ssh-without-a-password[configure an SSH key] for login with SSH key-based authentication. From the terminal:: + @@ -100,11 +99,14 @@ To remotely access your Raspberry Pi without providing a password each time you ==== Preconfigure an OS image with Raspberry Pi Imager -When configuring a boot image with Raspberry Pi Imager, you can preconfigure SSH keys. You can generate a new SSH keypair or an existing SSH key. +When configuring a boot image with Raspberry Pi Imager, you can preconfigure SSH keys to use an existing key on the computer where you run Imager. . Follow the xref:getting-started.adoc#raspberry-pi-imager[install using Imager] guide to configure your boot image. -. During the *OS Customisation* step, navigate to the *Services* tab and tick the *Enable SSH* checkbox. -. Select the *Allow public-key authentication only* radio button. If you already have an SSH public key stored in `~/.ssh/id_rsa.pub`, Imager automatically uses that public key to prefill the text box. If Imager doesn't find an SSH public key, you can click the *RUN SSH-KEYGEN* button to generate a new keypair. +. On the **Remote Access** tab, toggle the *Enable SSH* switch to the active position. +. Select *Use public key authentication*. +* If you already have an SSH public key stored in `~/.ssh/id_rsa.pub`, Imager automatically uses that public key to prefill the text box. +* Otherwise, browse to the location of your public key. +. Select **Next** to proceed with the imaging process. ==== Manually configure an SSH key diff --git a/documentation/asciidoc/services/connect/use.adoc b/documentation/asciidoc/services/connect/use.adoc index 2388242c4..7490227e3 100644 --- a/documentation/asciidoc/services/connect/use.adoc +++ b/documentation/asciidoc/services/connect/use.adoc @@ -3,6 +3,8 @@ Now that you've installed and started Connect on your Raspberry Pi device, you must associate your device with your Connect account. +NOTE: If you used Raspberry Pi Imager to install Raspberry Pi OS on your device, you might have already linked your device with your Connect account. For more information, see xref:../computers/getting-started.adoc#raspberry-pi-imager[Install using Imager]. + [tabs] ====== Desktop::