oam/knowledge base/raspberry pi os.md

Raspberry Pi OS

Table of contents

1. First boot
2. Repositories
3. Privilege escalation
4. Disable WiFi and Bluetooth
   1. Through boot configuration
   2. Through rfkill
   3. Disable the related services
   4. Disable the stacks completely uninstalling the packages
5. Disable swap
6. Disable automatic upgrades
7. Overlay filesystem mode
   1. Store files on the SD when the overlay file system is active
8. Checks
   1. Frequencies
   2. CPU throttling
   3. Board temperature
9. Apply CPU governors
10. Tuning
11. Headless boot
    1. The wpa_supplicant file
       1. Compute the password's hash
12. Run containers
    1. Kernel containerization features
    2. Firewall settings
13. Troubleshooting
    1. LED warning flash codes
    2. Issues connecting to WiFi network using roaming features or WPA3
14. Further readings
15. Sources

First boot

Unless manually set from the Imager, on first boot the system will ask to create a new initial user.

Repositories

Repositories, Mirrors.

curl -fsSL https://raspbian.mirror.garr.it/mirrors/raspbian/raspbian.public.key | sudo gpg --dearmor -o /etc/apt/keyrings/raspbian.mirror.garr.it
curl -fsSL https://mirror.nl.leaseweb.net/raspbian/raspbian.public.key | sudo gpg --dearmor -o /etc/apt/keyrings/mirror.nl.leaseweb.net.gpg
cat <<EOF | sudo tee /etc/apt/sources.list.d/mirrors.list > /dev/null
deb [arch=armhf signed-by=/etc/apt/keyrings/raspbian.mirror.garr.it] https://raspbian.mirror.garr.it/mirrors/raspbian/raspbian/ bullseye main contrib non-free rpi firmware
deb [arch=armhf signed-by=/etc/apt/keyrings/mirror.nl.leaseweb.net.gpg] http://mirror.nl.leaseweb.net/raspbian/raspbian bullseye main contrib non-free rpi firmware
deb [arch=armhf signed-by=/etc/apt/keyrings/mirror.nl.leaseweb.net.gpg] https://raspbian.mirror.liteserver.nl/ bullseye main contrib non-free rpi firmware
EOF
sudo apt update

Privilege escalation

• Users in the sudo group can sudo.
• The initial user can sudo without being asked for a password by default.

Disable WiFi and Bluetooth

Through boot configuration

Disable one or both in the all section of /boot/config.txt:

[all]
dtoverlay=disable-wifi
dtoverlay=disable-bt

Through rfkill

1. block one or both:

   rfkill block 'wifi'
   rfkill block 'bluetooth'
   

2. check they are correctly soft-blocked:

   rfkill list
   

Disable the related services

• hciuart.service and bluetooth.service for Bluetooth
• wpa_supplicant.service for WiFi

Disable the stacks completely uninstalling the packages

sudo apt --assume-yes purge 'bluez'
sudo apt --assume-yes autoremove --purge

Disable swap

Disable the swap file:

sudo systemctl disable --now 'dphys-swapfile'

Disable automatic upgrades

Raspberry Pi OS has daily upgrades enabled by default. Check the second line of this command's output:

systemctl status 'apt-daily-upgrade.timer'

Check the time it was last run with the following:

stat -c '%z' '/var/lib/apt/daily-lock'

If the service is enabled, there should be a record of that in /var/log/dpkg.log.

To disable this, execute the following:

sudo systemctl mask 'apt-daily-upgrade'
sudo systemctl mask 'apt-daily'
sudo systemctl disable 'apt-daily-upgrade.timer'
sudo systemctl disable 'apt-daily.timer'

Using mask to prevent the above services from being re-enabled by some dependency.

Notice those are two separate services; they both run /usr/lib/apt/apt.systemd.daily, a shell script, with parameters install and update.

Overlay filesystem mode

This enhances the performances, but all changes will be kept in RAM and lost after a reboot unless it is saved elsewhere.

Enable it using raspi-config. While enabled, /root is in RO and no data will be written to the card.

Store files on the SD when the overlay file system is active

The files just need to be stored on a different file system from /. You can partition the SD and use that, or create a file and mount it as a virtual file system:

truncate -s '6G' 'file'
mkfs.ext4 'file'
mkdir 'mount/point'
sudo mount -t 'ext4' -o 'loop' 'file' 'mount/point'
sudo chown 'user':'group' 'mount/point'
touch 'mount/point/new-file'

Checks

See vcgencmd for more information.

Frequencies

# Current CPU frequency.
vcgencmd measure_clock arm

# Current GPU frequency.
vcgencmd measure_clock core

# Min set frequency per CPU core.
cat '/sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_min_freq'
cat /sys/devices/system/cpu/cpu*/cpufreq/cpuinfo_min_freq

# Max set frequency per CPU core.
cat '/sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_max_freq'
cat /sys/devices/system/cpu/cpu*/cpufreq/cpuinfo_max_freq

# Current set frequency per CPU core.
cat '/sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_cur_freq'
cat /sys/devices/system/cpu/cpu*/cpufreq/cpuinfo_cur_freq

CPU throttling

See also Re: How to make sure the rpi cpu is not throttled down?.

$ vcgencmd get_throttled
throttled=0x0

The bits in this number represent the following:

Bit	Hex value	Meaning
0	0x1	Under-voltage detected; occurs when voltage drops below 4.63V; the Pi is throttled
1	0x2	Arm frequency capped; occurs with temp > 80˚C
2	0x4	Currently throttled
3	0x8	Soft temperature limit active
16	0x10000	Under-voltage has occurred
17	0x20000	Arm frequency capping has occurred
18	0x40000	Throttling has occurred
19	0x80000	Soft temperature limit has occurred

over-temperature occurs with temp > 85˚C. The Pi is throttled.

Throttling removes turbo mode, which reduces core voltage and sets arm and gpu frequencies to a non-turbo value.

Capping just limits the CPU frequency (somewhere between 600MHz and 1200MHz) to try to avoid throttling.

If the board throttled but is not under-voltage, you can assume over-temperature; confirm this with vcgencmd measure_temp.

Sums of error codes mean multiple events occurred.
E.g., 0x50005 means you are currently under-voltage and throttled. If you want to be able to support this use case without throttling you will need a better power supply.

If you never see a non-zero get_throttled value in normal usage, then you may not need to do anything.

Board temperature

$ vcgencmd measure_temp
temp=73.1'C

Apply CPU governors

Until next boot:

echo 'ondemand' | sudo tee '/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor'
echo 'performance' | sudo tee '/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor'
echo 'powersave' | sudo tee '/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor'

Permanently:

sudo nano '/etc/init.d/raspi-config'

Tuning

See Timely tips for speeding up your Raspberry Pi.

Headless boot

Manual procedure:

1. Image the SD card

   sudo dd bs='4M' if='/tmp/2019-09-26-raspbian-buster-lite.img' of='/dev/mmcblk0' status='progress' oflag='sync'
   

2. Mount the boot partition.

3. Create an empty ssh file in that partition.
   This will enable the ssh service at boot.

4. Create the wpa_supplicant.conf file in the same partition.
   This will be used to overwrite the same file in /etc on the OS.

   1. Follow the template below.
   2. [Optionally] fill the template with the password's hash for improved security

The wpa_supplicant file

wpa_supplicant.conf template:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=«your_ISO-3166-1_two-letter_country_code»

network={
    ssid="«your_SSID»"
    psk="«your_PSK»"
    key_mgmt=WPA-PSK
}

Replace «your_ISO-3166-1_two-letter_country_code» with your ISO Country Code (such as CA for Canada), «your_SSID» with your wireless access point name and «your_PSK» with your wifi password.

Note that the country, ctrl_interface and update_config lines are required in file as created in /boot: if they are missing the system will not connect to the network. The above process can be repeated to correct the omissions.

wpa_supplicant.conf example:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=IE

network={
    ssid="VM6371722"
    psk=77475166938e2ddc18bcde2a59d4b63810c0a05ddf9b931e4b0223b74e94e389  # psk="qqqqqqqqq"
    key_mgmt=WPA-PSK
}

Compute the password's hash

Use wpa_passphrase:

usage: wpa_passphrase <ssid> [passphrase]
If passphrase is left out, it will be read from stdin

The utility will prompt for the password, and will return the hexadecimal hash value. This hashed password is to be stored without quotes in the /boot/wpa_supplicant.conf file.

$ wpa_passphrase "ssid"
# reading passphrase from stdin
password
network={
    ssid="ssid"
    #psk="password"
    psk=77475166938e2ddc18bcde2a59d4b63810c0a05ddf9b931e4b0223b74e94e389
}

Run containers

1. enable the kernel's containerization feature
2. disable swap
3. if kubernetes is involved, set up the firewall to use the legacy configuration

Kernel containerization features

Enable containerization features in the kernel to be able to run containers as intended.

Add the following properties at the end of the line in /boot/cmdline.txt:

cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1

sed -i '/cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1/!s/\s*$/ cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1&/' /boot/cmdline.txt

Firewall settings

Switch Debian firewall to use the legacy configuration:

update-alternatives --set 'iptables'  '/usr/sbin/iptables-legacy'
update-alternatives --set 'ip6tables' '/usr/sbin/ip6tables-legacy'

Troubleshooting

LED warning flash codes

If a Raspberry Pi fails to boot or has to shut down for some reason, in most cases it will flash a LED a specific number of times to indicate what happened.
The LED will blink for a number of long flashes (0 or more), then short flashes, to indicate the exact status. In most cases, the pattern will repeat after a 2 second gap.

See the configuration page for updated information.

Long flashes	Short flashes	Status	Notes
0	3	Generic failure on boot
0	4	start*.elf not found
0	7	Kernel image not found
0	8	SDRAM failure
0	9	Insufficient SDRAM
0	10	In HALT state
2	1	Partition not FAT
2	2	Failed to read from partition
2	3	Extended partition not FAT
2	4	File signature/hash mismatch	Pi 4 only
3	1	SPI EEPROM error	Pi 4 only
3	2	SPI EEPROM is write protected	Pi 4 only
3	3	I2C error	Pi 4 only
3	4	Secure-boot configuration is not valid
4	4	Unsupported board type
4	5	Fatal firmware error
4	6	Power failure type A
4	7	Power failure type B

Issues connecting to WiFi network using roaming features or WPA3

Check raspbian's bug 1929746 for more information.

Quick solutions:

• (quick 'n' dirty) disable roaming options and WPA3 in your router;

• (preferable) disable SAE (WPA3) and SWSUP (offload authentication to the firmware), and fast roaming:

  rmmod 'brcmfmac'
  modprobe 'brcmfmac' roamoff=1 feature_disable=0x82000
  

  Make it permanent in a .conf file in /etc/modprobe.d/:

  # /etc/modprobe.d/wifi_workaround.conf
  options brcmfmac roamoff=1 feature_disable=0x82000
  

Long term solution: none currently known.

Further readings

• /boot/config.txt
• Overclocking
• rfkill
• Country code search
• k3s
• Configuration

Sources

All the references in the further readings section, plus the following:

• Prepare SD card for WiFi on headless Pi
• Run Kubernetes on a Raspberry Pi with k3s
• Project's issue 2067
• Re: How to make sure the rpi CPU is not throttled down?
• Timely tips for speeding up your Raspberry Pi
• Repositories
• Mirrors