The complete idiot's guide to OpenBSD on the Pinebook Pro
Today I will show you how I installed the latest snapshot of OpenBSD on my Pinebook Pro with plenty of detail so that you can do it, too. I will include instructions for setting up full disk encryption, and conclude with a summary of my experience running OpenBSD on this device.
Why would you want to do such a thing? Because you can.1 That said, there are a couple CAVEATs around this exercise. I will try my best to convey the pitfalls and shortcomings of the state of the art—so you can decide whether this is something for you or not.
The most important CAVEAT is, to quote OpenBSD’s INSTALL.arm64:
Please be aware that OpenBSD support for this platform is far from complete.
Also worth stating that we are on moving ground: by the time you read this, things might have changed (hopefully for the better), so be mindful when following the steps and do not hesitate to deviate based on your circumstances. Exercise common sense and good judgment, and strive to get an understanding of what you do before doing it.
You should read and understand this article in its entirety before you even think of touching your Pinebook Pro. You might also want to go through earlier reports of OpenBSD on the PBP, with snapshots of 6.7 here and 7.0 here.
DISCLAIMER: all responsibility from tinkering with your laptop is yours alone. This write-up is purely for entertainment purposes. Please leave me alone if you managed to fry, smoke, brick, break, or otherwise hurt your device. Ditto if you lost precious data, sleep, or hair. Any consequences of your decision to keep reading and proceed with the below article are entirely yours to live with.
Still with me? You like to live dangerously? Okay, let’s get going.
Overview
We are going to install the latest OpenBSD snapshot on a Pinebook Pro (PBP) made in April, 2021. That manufacturing batch was a fairly large one at Pine64, and I speculate the majority of PBPs in existence is not significantly older than mine. Your hardware should therefore be more or less the same (with the exception of the earliest batches, where various issues were found and since have been ironed out). Still, if there seem to be mysterious mismatches between what I describe and what you see, your PBP might be different than mine.
We will install OpenBSD by writing the miniroot image directly to the eMMC, and patching it with the bootloaders so the machine will boot from the eMMC. To do this, you will need to unscrew the PBP’s bottom plate and unplug the eMMC, attach it to another computer via a USB-eMMC adapter, write (or “flash” or “burn” or “etch”) the data, then stick the eMMC back into the PBP and boot the OpenBSD installer from there. The installer will load from eMMC into memory and run from a so-called ramdisk, allowing us to install the system directly on the same eMMC. We will use the PBP’s serial console, so you will need a serial cable plugged into the headphone jack, with the other end connected to a second computer where you interact with the serial terminal.
In addition to the eMMC, we will also prepare a USB memory stick to carry the archives of the OpenBSD distribution set, as well as the firmware binaries relevant to the PBP. This way, we will have access to everything required to do the install all the way to a graphical desktop and a working wireless network interface. Without the USB stick, we would need a temporary wired connection to download the sets as well as the extra firmware to get the wifi working. Given that the PBP does not have a wired Ethernet interface, that would cost us a USB-Ethernet dongle.
Note that we do not use an SD card (we won’t need the PBP’s SD card slot at all). SD cards are trickier than they seem.2 On the other hand, a good old USB stick is easy to find and generally pretty reliable, usable without issues even across operating systems.
Removing the eMMC from the laptop might seem like an unnecessary hassle. We could, at least in theory, boot the installer from an SD card, sidestepping the need for a USB-eMMC adapter and messing with the PBP’s delicate eMMC. But this would not be without complications. First, as mentioned above, SD cards present a host of potential issues. Second, correctly landing the bootloader on the eMMC, while certainly possible, is non-trivial (given that we could only patch it on the SD card, but not the eMMC), adding complexity and making the process even more error-prone. Finally, we would need to open the PBP anyway, to toggle the internal switch to send the serial console on the headphone jack. Because OpenBSD does not (yet) support the PBP’s “real” console, this is the only way to interact with the installer.
Therefore, I feel that at the time of writing, the method presented below is probably the easiest way to reliably land OpenBSD on the PBP. Further, it does not depend on the a priori state of the PBP at all: no matter how hard you messed it up,3 this way you can always do a clean reinstall.
Preparations
Gather the tools
Apart from the Pinebook Pro itself, you will need the following tools:
- USB-eMMC adapter
- USB-to-serial cable with headphone jack connector
- USB memory stick
- Phillips screwdriver of a fairly small size (for the PBP’s delicate bottom screws)
The necessary tools (click to enlarge)
I got my USB-eMMC dongle from a local SBC shop here in Sweden; it is made by Hardkernel and does not look exactly like the one sold on the Pine64 store. You can probably do the same and grab one from your nearest supplier.
I grabbed the first old, spare 8GB USB3.0 memory stick I had lying around in my drawer. Its age in years is probably more than its capacity in gigabytes, and by now it has spent most of its lifespan hidden away as a spare. We will need less than a CD’s worth of free capacity (around 500 MB); no need to reformat as long as it has a commonly understood filesystem and enough free space.
I did not have the ready-made serial console cable offered by the Pine64 store, but as an electronics nut, I did have the obligatory FTDI USB-serial module floating around my desk. I found an audio cable with 3.5” jack plugs on both ends. With some wires tightly twisted around the plug on one end, a breadboard and duct tape, I created my own console cable (close-up images here and here). I’m not too proud of it, but it works.4 If you also roll your own, the wiring of the UART connection goes like this:
- tip: RX, connect to FTDI’s TX
- ring: TX, connect to FTDI’s RX
- sleeve: GND, connect to FTDI’s GND
The three-way connector does not leave any lines for hardware flow control (RTS/CTS). Disable hardware flow control in your serial terminal, or it might refuse to send keyboard input on the wire. Terminal programs have various options and defaults around this; please check the relevant manuals. By the way, the correct line speed to communicate with the PBP console is 115200 baud.
Please ensure that you use a USB-serial converter with 3.3V pins, or else you might fry (at least some pins of) the PBP SoC! If in doubt, plug it into a USB port and measure the DC voltage level of the idle RX and TX lines with a digital instrument.
Lastly, you will need access to a second computer to prepare the eMMC and the USB stick, and to access the serial console. This computer can be any regular Linux or BSD machine; it does not matter much as long as it can access the Internet and has a functioning USB port.5
Download the install material
First, familiarize yourself with the official OpenBSD installation instructions for the ARM64 architecture. The file INSTALL.arm64 is for the snapshot version we will use. Read it now. In general, you are advised to follow the links throughout this article and study the relevant materials to gain a fuller picture.
Let’s download everything needed to complete the installation. For
this, create a scratch folder on your second computer; I used
~/openbsd70
but you can put the files wherever you like. You will
need less than a gigabyte of free space on the filesystem.
Snapshot archives
First, download the latest OpenBSD snapshot archives under your
scratch folder. The below commands should be shell-agnostic enough to
work on OpenBSD (ksh) and Linux (bash) alike, but on Linux, you will
want to use wget
or curl
instead of ftp
. For example, write
curl $BASE/$f -o $f
instead of ftp $BASE/$f
.
mkdir ~/openbsd70 && cd ~/openbsd70
mkdir snapshot && cd snapshot
BASE="https://cdn.openbsd.org/pub/OpenBSD/snapshots/arm64"
FILES="SHA256 SHA256.sig base70.tgz bsd bsd.mp bsd.rd \
comp70.tgz game70.tgz man70.tgz miniroot70.img \
xbase70.tgz xfont70.tgz xserv70.tgz xshare70.tgz"
for f in $FILES ; do ftp $BASE/$f ; done
Note that we did not download the largest image called install70.img
,
because we won’t need it. On OpenBSD, use signify
to verify the
integrity of the downloads:
signify -C -p /etc/signify/openbsd-70-base.pub -x SHA256.sig
This should print an OK next to all the downloaded files. It will
print FAIL for all other files (listed in SHA256.sig
but not
downloaded); that is fine. On Linux, use sha256sum
to verify the
file hashes:
sha256sum -c SHA256
This is slightly less secure (it does not prove that the files were published by OpenBSD) but still protects against corrupted downloads.
Firmware archives
Next, download the latest OpenBSD firmware archives in a similar manner. Do not blindly copy-paste the below snippet, because the version numbers embedded into the filenames are bound to change! Visit the previous link to see the actual list of files and adjust accordingly.
mkdir ~/openbsd70/firmware && cd ~/openbsd70/firmware
BASE="http://firmware.openbsd.org/firmware/7.0"
FILES="SHA256 SHA256.sig bwfm-firmware-20200316.1.2p2.tgz \
uvideo-firmware-1.2p3.tgz"
for f in $FILES ; do ftp $BASE/$f ; done
Given the PBP hardware, the two firmware archives (for bwfm
and
uvideo
) are all you need. But feel free to download all the firmware
if that makes you comfortable. Again, do not forget to verify the
integrity of your downloads. On OpenBSD:
signify -C -p /etc/signify/openbsd-70-fw.pub -x SHA256.sig
On Linux, verification of the sha256 hashes is complicated by the fact
that OpenBSD started to use the base64 encoded binary hash values in
some of its SHA256
files. This is not yet supported by sha256sum
,
but here is a workaround using openssl
:
openssl sha256 -binary bwfm-firmware-20200316.1.2p2.tgz | openssl base64
Compare the output of the above command with the hash stored in SHA256
:
grep bwfm SHA256
Now you should be able to check that the two hashes are one and the same.
Bootloader packages
Finally, we need the contents of two OpenBSD packages to set up the
bootloader: dtb
and u-boot-aarch64
. We will download the packages
manually.6 To do so, navigate to the snapshot
packages with your browser and locate the files for dtb
and
u-boot-aarch64
. At the time of writing, these are dtb-5.14p1.tgz
and u-boot-aarch64-2021.10p3.tgz
. Again, adapt the filenames:
mkdir ~/openbsd70/packages && cd ~/openbsd70/packages
BASE="https://ftp.openbsd.org/pub/OpenBSD/snapshots/packages/aarch64"
FILES="SHA256 SHA256.sig dtb-5.14p1.tgz u-boot-aarch64-2021.10p3.tgz"
for f in $FILES ; do ftp $BASE/$f ; done
After verification, untar them:
tar xzf dtb-5.14p1.tgz
tar xzf u-boot-aarch64-2021.10p3.tgz
Now you have a share/
directory beside the archives. We will use
some of the files from there when preparing the eMMC. But first, let’s
deal with the USB stick.
Prepare the USB memory stick
With all install material conveniently at hand, it’s time to prepare
the USB stick. Verify that there is enough free space on it. We will
set it up with the OpenBSD archive structure. Assuming it is mounted
under /mnt
, these are the commands you could use (should work on
both OpenBSD and Linux):
# cd /mnt
# mkdir -p 7.0/arm64
# cp ~/openbsd70/snapshot/* 7.0/arm64/
# cp -r ~/openbsd70/firmware .
Depending on how you mounted the USB stick, you might need elevated
rights to be able to write to it. In that case, do what you need to do
(i.e., precede the commands with sudo
).
The directory structure on your USB stick should now look like this:
# ls -R /mnt
/mnt:
7.0 firmware
/mnt/7.0:
arm64
/mnt/7.0/arm64:
SHA256 bsd.mp man70.tgz xserv70.tgz
SHA256.sig bsd.rd miniroot70.img xshare70.tgz
base70.tgz comp70.tgz xbase70.tgz
bsd game70.tgz xfont70.tgz
/mnt/firmware:
SHA256
SHA256.sig
bwfm-firmware-20200316.1.2p2.tgz
uvideo-firmware-1.2p3.tgz
We do not actually need the miniroot70.img
on the USB stick, but it
was simpler to just copy everything. You can delete it if you wish.
Unmount and remove the USB stick; we will put it into the PBP before powering it on to boot the installer. But that is for later. The next logical step is to prepare the eMMC. But before we touch the PBP, let’s make sure we really have everything in order.
Test your serial cable
Test your serial cable and get acquainted with the serial terminal program you will use. Take the audio jack that you will plug into the headphone socket of your PBP. By shorting the tip and ring (RX and TX) together with a piece of bare wire (or a metal clamp, or a piece of tinfoil…), you get an echo loop that prints everything you type. If you remove the short, your typing should no longer echo (proving that your typing really went through the cable).
On Linux, I like to use minicom
, a very user-friendly menu-driven
terminal program. There is also picocom
, screen
, etc. On OpenBSD,
there is cu
.
To discover the device node after plugging the serial cable in, check
the dmesg
output. It is usually ttyUSB0
on Linux and ttyU0
on
OpenBSD. One of these commands should get you started:
minicom -D /dev/ttyUSB0 -b 115200
picocom -b 115200 /dev/ttyUSB0
screen /dev/ttyUSB0 115200
cu -d -s 115200 -l ttyU0
You might need elevated privileges unless your user is set up with permission to access the serial device. Do not proceed until you can echo characters through your cable!
The point of no return
Your second computer is fired up with the USB of the USB-serial cable plugged into it, the serial terminal program of your choice up and running and connected to it, and your cable verified to work. All install media is downloaded, verified, and the parts that belong to the USB stick have been copied there. Great progress! There is nothing else we can do without touching the Pinebook Pro. This is your last chance to close this page and walk away whistling, hands firmly planted in your pockets.
« twiddling thumbs for a minute »
Still here? Alright, then you have some more studying to do: if you haven’t already, thoroughly read through the PBP wiki page on disassembling the laptop. On top of being careful enough not to break anything, not lose any small parts (shiny metal screws and hinge screw stand-offs made of black plastic) and not cut your fingers, you will need to locate the eMMC and two switches after removing the bottom cover plate of the laptop. Here is a close-up of my PBP, showing exactly what you need to look for:
Pinebook Pro internals (click to enlarge)
The way I like to open my PBP is this. First, I fully open the lid, then put the laptop with keyboard facing down, resting on the table surface, with the display pointing downwards into my lap. I remove the screws (into a small box) and carefully take the bottom cover off. Then, holding the laptop at its sides, I lift it up and place it on the table, resting on its side edge with the display pointing away from me. This allows me to inspect and manipulate the inside with no risk of stressing the hinges. When it is time to power on, I put the bottom plate in place, but do not fasten it with screws. I just hold everything together and turn the thing around, with bottom to the table, just like a normal laptop so I can turn it on, look at the screen and type as usual. The bottom cover should be in place because it acts as the SoC heatsink. I believe the above is OK (at least my PBP did not break yet). What you should never do is exercise (open/close) the display lid with the bottom unscrewed, because the unfastened hinges lack structural strength and will break.
After taking off the bottom of your PBP, set both switches (marked with red circles above) as pictured, with their levers towards the display hinge and away from the touchpad. They are number 9 and 24 on the PBP parts diagram; these settings enable the eMMC and send the serial console to the headphone jack. In your PBP, the eMMC will most likely already be enabled, but you will have to toggle switch 9 for the UART.
Remove the eMMC
Now we need to remove the eMMC, the fairly small rectangular board only slightly larger than the black memory chip itself. As you can see in the photo above, mine is 64GB in size. On the underside of the eMMC board, the socket is alongside the edge closest to the switch (24). In my PBP, the eMMC was stuck to the mainboard with some two-sided sticker tape holding it in place. Thus, removing it was a bit harder than anticipated. It is probably safest to use a piece of hard plastic with an edge, such as a guitar pick, to pry the eMMC off of the mainboard and separate it from the sticky tape. Do not use a sharp piece of metal (such as a knife or screwdriver), or you might hurt one of the boards.
Once you have the eMMC between your fingers, immediately snap it on to the socket of the USB-eMMC adapter. This reduces the chances of dropping it, losing it, or smudging the electrical contacts with sweaty fingers. Be careful to correctly position it over the adapter’s socket, then connect with a gente but firm push. You should be able to feel that it is now sitting in place.
Backup eMMC data
Plug the USB-eMMC adapter into your second machine and check out the
storage device. This is what I saw in the dmesg
log on Linux:
usb 4-2: new SuperSpeed Gen 1 USB device number 3 using xhci_hcd
usb 4-2: New USB device found, idVendor=05e3, idProduct=0749, bcdDevice=15.32
usb 4-2: New USB device strings: Mfr=3, Product=4, SerialNumber=2
usb 4-2: Product: USB3.0 Flash Disk
usb 4-2: Manufacturer: Generic
usb 4-2: SerialNumber: 000000001532
usb-storage 4-2:1.0: USB Mass Storage device detected
scsi host2: usb-storage 4-2:1.0
scsi 2:0:0:0: Direct-Access Generic USB Flash Disk 1532 PQ: 0 ANSI: 6
sd 2:0:0:0: Attached scsi generic sg0 type 0
sd 2:0:0:0: [sda] 122142720 512-byte logical blocks: (62.5 GB/58.2 GiB)
sd 2:0:0:0: [sda] Write Protect is off
sd 2:0:0:0: [sda] Mode Sense: 21 00 00 00
sd 2:0:0:0: [sda] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA
sd 2:0:0:0: [sda] Attached SCSI removable disk
As you can see, my eMMC showed up as sda
through the adapter. Yours
might be different. Note the correct device and use it in all
subsequent commands! We want to use the device for the complete raw
storage, as opposed to the partitions (if any). On OpenBSD, you will
want to use something like rsd0c
.
If you have an existing system on the PBP that is at all valuable, start by saving the full content of the eMMC. This will allow you to restore it later and get your old PBP back, should you get stuck or tired of this adventure. You could also buy a second eMMC to install OpenBSD on, allowing you to keep the original intact so you can swap back and forth between different systems. I would actually advise you to do that instead of destroying a working system if you routinely relied on your PBP for… well, anything.
On Linux, the following command will write an image of the eMMC
content to emmc_orig.img
. Remember, substitute your correct
device in place of sda
. On OpenBSD, the command is identical
(modulo input device), except that you should use bs=1m
instead of
bs=1M
.
dd if=/dev/sda of=emmc_orig.img bs=1M
This should take a couple minutes and you should see the light flashing on the USB-eMMC adapter throughout, serving as proof that you are using the correct device. At the end, you will get a nice summary of the bulk read performance of your eMMC. This is what I saw:
# dd if=/dev/sda of=emmc_orig.img bs=1M
59640+0 records in
59640+0 records out
62537072640 bytes (63 GB, 58 GiB) copied, 390.282 s, 160 MB/s
Bulk write performance is significantly lower at around 60 MB/s, according to my measurements.
Prepare the eMMC
Time to equip the eMMC with the bootable installer image!
This is the very last moment you can put everything back together and pretend that nothing happened.
This SBC bootcamp by Exotic Silicon is an interesting read if you want some more background on booting ARM64 SBCs.
First, we will write the downloaded miniroot70.img
to the eMMC. On
Linux:
cd ~/openbsd70/snapshot
dd if=miniroot70.img of=/dev/sdX bs=1M
I hope you did not forget to use the correct device this time
either.7 Again, on OpenBSD you will want to use
something like /dev/rsd0c
and bs=1m
.
This should not take more than a second or two, as the miniroot image is only 43 megabytes.
Now we will copy the Pinebook Pro-specific DTB (device tree blob) on
to the msdos-type boot partition containing u-boot data. The correct
partition to mount will be sda1
or similar on Linux; on OpenBSD, it
will be something like sd0i
.
cd ~/openbsd70/packages
mount /dev/sdX1 /mnt
mkdir /mnt/rockchip
cp share/dtb/arm64/rockchip/rk3399-pinebook-pro.dtb /mnt/rockchip/
umount /mnt
Next, patch the U-Boot bootloader code into the eMMC image. On Linux:
dd if=share/u-boot/pinebook-pro-rk3399/idbloader.img of=/dev/sdX seek=64
dd if=share/u-boot/pinebook-pro-rk3399/u-boot.itb of=/dev/sdX seek=16384
On OpenBSD, use something like sd0c
(ending in c
to operate on the
complete disk, but without r
to use the block device as opposed to
the raw device).
Installing OpenBSD
With the eMMC prepared, we are finally ready to actually install OpenBSD. Carefully put the eMMC back into the laptop. If you followed what I did and opened the lid before unscrewing the bottom, you can just put the bottom cover in its place, and turn the laptop into the normal position while holding it tight. If you were working the PBP in the more traditional way (with lid closed), you must screw on the bottom cover before you can open the display hinges.
With the PBP now in working position, lid open, and bottom plate (SoC heatsink) in place, plug the serial console into the headphone jack. Plug in the USB stick as well. Make sure there is no SD card accidentally left in the slot. Take a deep breath and hold the power button for about a second. If everything went well, you should see something like this on the serial terminal (full console log):
U-Boot TPL 2021.10 (Jan 25 2022 - 00:18:46)
Channel 0: LPDDR4, 50MHz
BW=32 Col=10 Bk=8 CS0 Row=15 CS1 Row=15 CS=2 Die BW=16 Size=2048MB
Channel 1: LPDDR4, 50MHz
BW=32 Col=10 Bk=8 CS0 Row=15 CS1 Row=15 CS=2 Die BW=16 Size=2048MB
...
Found EFI removable media binary efi/boot/bootaa64.efi
178519 bytes read in 36 ms (4.7 MiB/s)
Booting /efi\boot\bootaa64.efi
disks: sd0*
>> OpenBSD/arm64 BOOTAA64 1.7
boot>
...
Welcome to the OpenBSD/arm64 7.0 installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell?
Congratulations, you are staring in the face of the OpenBSD installer. From here it should be smooth sailing. If you get stuck, refer to my full console log to see what I did exactly.
Base system install
At startup, we have no way to configure the network, because we do not (yet) have the necessary firmware:
Available network interfaces are: bwfm0 vlan0.
Which network interface do you wish to configure? (or 'done') [bwfm0] done
DNS domain name? (e.g. 'example.com') [my.domain] lan
DNS nameservers? (IP address list or 'none') [none]
When it comes to available disks, use ‘?’ to get a list of storage
devices if you are not sure. But sd0
should be the eMMC and sd1
should be the USB stick. For partitioning, use the whole disk; the
installer is smart enough to realize that the small msdos-type boot
partition containing u-boot must be left intact. Since this is a demo
install, I accepted the auto-allocated layout. You are of course free
(and encouraged) to adjust it however you see fit.
Next, when it comes to installing the sets, we direct the installer to
the USB stick recognised as sd1
:
Let's install the sets!
Location of sets? (disk http nfs or 'done') [http] disk
Is the disk partition already mounted? [yes] no
Available disks are: sd0 sd1.
Which disk contains the install media? (or 'done') [sd1]
a: 1358848 1024 4.2BSD 2048 16384 16142
i: 960 64 MSDOS
Available sd1 partitions are: a i.
Which sd1 partition has the install sets? (or 'done') [a]
Pathname to the sets? (or 'done') [7.0/arm64]
INSTALL.arm64 not found. Use sets found here anyway? [no] yes
You will get a warning about INSTALL.arm64
missing from the archive;
just confirm that you want to continue. After selecting the sets, you
will also be warned about a missing SHA256.sig
(which I do not fully
comprehend, given that we put that file in place). Again, confirm that
you want to continue:
Select sets by entering a set name, a file name pattern or 'all'. De-select
sets by prepending a '-', e.g.: '-game*'. Selected sets are labelled '[X]'.
[X] bsd [X] base70.tgz [X] game70.tgz [X] xfont70.tgz
[X] bsd.mp [X] comp70.tgz [X] xbase70.tgz [X] xserv70.tgz
[X] bsd.rd [X] man70.tgz [X] xshare70.tgz
Set name(s)? (or 'abort' or 'done') [done] done
Directory does not contain SHA256.sig. Continue without verification? [no] yes
And that is all there is to it. Relinking the unique kernel takes a bit of time, and I sure hope you have the heatsink in place over the SoC. When the installer is done, reboot. Rebooting actually worked for me, which came as a pleasant surprise (based on earlier reports, I expected having to hold the power button).
CONGRATULATIONS! Your OpenBSD install has been successfully completed!
When you login to your new system the first time, please read your mail
using the 'mail' command.
Exit to (S)hell, (H)alt or (R)eboot? [reboot]
syncing disks... done
rebooting...
U-Boot TPL 2021.10 (Jan 25 2022 - 00:18:46)
Channel 0: LPDDR4, 50MHz
...
At the end of the first reboot, login to the brand new OpenBSD system as root:
...
OpenBSD/arm64 (aurora.lan) (console)
login: root
Password:
OpenBSD 7.0-current (GENERIC.MP) #1516: Mon Jan 31 00:30:28 MST 2022
Welcome to OpenBSD: The proactively secure Unix-like operating system.
Now mount the USB stick (still plugged in, right?); look above for a
hint to the correct device (printed by the installer).8
Run fw_update
to install necessary firmware:
aurora# mount /dev/sd1a /mnt
aurora# fw_update -p /mnt/firmware
fw_update: added bwfm,uvideo; updated none; kept none
To connect to the network, create the file /etc/hostname.bwfm0
with
the network SSID and the WPA key (substitute SSID
and WPAKEY
with
your actual wireless credentials). We also enable xenodm
, the X
display manager service to get X started on boot. Then reboot:
aurora# echo "join SSID wpakey WPAKEY" > /etc/hostname.bwfm0
aurora# echo "inet autoconf" >> /etc/hostname.bwfm0
aurora# rcctl enable xenodm
aurora# reboot
When you see the message syncing disks... done
, remove the USB stick.
On the first bootup with X enabled, you will get a garbled screen (I got a bunch of vertical lines against a grey backdrop). Unfortunately, the serial console will be dead as well, so just hold the power button until the laptop goes dark, and then wait a couple minutes. On the next boot, you will get some unfriendly messages about filesystems that were not cleanly unmounted, but OpenBSD should come up alright (including the graphics).9
Et voilà:
The end result (click to enlarge)
At this point, we can login via X as well as SSH over the network.
As you can probably tell from the ugly white stickers (actually,
patches of duct tape) on the keyboard: I use the Dvorak layout. At an
earlier time, while still running Linux, I updated the keyboard
firmware and as part of the process, converted the layout to Dvorak.
Since the mapping is handled by the keyboard controller, it is
transparent to OpenBSD which is set to the default us
keyboard
layout. I find this to be very convenient, messing around with
different operating systems, bootloaders et al.
Even if you do not want to change the layout, it is advised to upgrade the firmware, as it fixes some issues (I remember Alt + arrow keys did not work).10 Something you might want to look into while you still have Linux up and running (as that is what you need to run the firmware updater). But you can also boot from an SD card prepared with Linux to do this later. Check the Pine64 forums for details.
If you reached this point, congratulations! Now you can login with the
regular user you created, start an xterm
and compare your dmesg
to
mine. What a grand luxury!
Full disk encryption
Nowadays it is de rigueur to set up mobile computers with full disk encryption, and OpenBSD provides a convenient way to do so via its softraid subsystem. The thought of using this might well be tempting—after all, if you want an OpenBSD laptop, you probably want a secure laptop. While it is technically possible to install OpenBSD on the PBP with this today, I would recommend against doing so for reasons that will become clear in a moment.
That said, I did test the complete install with FDE to verify that it is indeed possible to make it work, and here I give you all the instructions you might need. I assume you have studied and understood the OpenBSD documentation on softraid FDE; if not, please follow the previous link before you read on. We will mostly rely on the steps outlined there, but we need to deviate a little.
First, it is customary to overwrite the whole device with random data at the start of an FDE install. If you want to do that, take it as the first step of preparing the eMMC (while attached to the secondary, presumably more powerful computer). Then, continue to prepare it as described above by writing the miniroot image to it, followed by copying the DTB and finally patching in the bootloaders.
When you boot up the PBP with the installer, you will need to drop into the live shell environment and prepare a softraid device on top of which the operating system will be installed. We cannot directly execute the commands as spelled out in the OpenBSD FAQ, because that assumes a “normal” architecture without the complications of ARM and the U-Boot bootloader. In other words, we cannot yank the existing disk content and reinitialize the partition table—instead, we need to preserve the msdos-type boot partition at the beginning of the disk.
What we will do is use disklabel(8) to extend the partition table to the entire size of the disk, and substitute the OpenBSD partition with a RAID-type area that takes up the whole extent. The offsets reflect the fact that I am doing this on a brand new 128GB eMMC:
Welcome to the OpenBSD/arm64 7.0 installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? s
# cd /dev && sh MAKEDEV sd0
# disklabel -E sd0
Label editor (enter '?' for help at any prompt)
sd0> p
OpenBSD area: 49152-88064; size: 38912; free: 0
# size offset fstype [fsize bsize cpg]
a: 38912 49152 4.2BSD 2048 16384 1216
c: 244285440 0 unused
i: 16384 32768 MSDOS
sd0> b
Starting sector: [49152]
Size ('*' for entire disk): [38912] *
sd0*> d a
sd0*> a a
offset: [49152]
size: [244236288]
FS type: [4.2BSD] RAID
sd0*> w
sd0> q
No label changes.
We set up the softraid device (it becomes sd2
, since sd1
is taken
by our USB stick), supplying the encryption password. Then, we wipe
the first 1MB of the crypto device as recommended.
# bioctl -c C -l sd0a softraid0
New passphrase:
Re-type passphrase:
sd2 at scsibus2 targ 1 lun 0: <OPENBSD, SR CRYPTO, 006>
sd2: 119255MB, 512 bytes/sector, 244235760 sectors
softraid0: CRYPTO volume attached as sd2
# cd /dev && sh MAKEDEV sd2
# dd if=/dev/zero of=/dev/rsd2c bs=1m count=1
1+0 records in
1+0 records out
1048576 bytes transferred in 0.183 secs (5710289 bytes/sec)
Finally, we exit from the shell and proceed to install OpenBSD as usual:
# exit
erase ^?, werase ^W, kill ^U, intr ^C, status ^T
Welcome to the OpenBSD/arm64 7.0 installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? i
Just be mindful to use the correct device; sd2
is our encrypted
volume:
Available disks are: sd0 sd1 sd2.
Which disk is the root disk? ('?' for details) [sd0] sd2
There is literally no further change required from our previous
actions. Once we remove the USB stick, the encrypted volume will
auto-migrate to sd1
on the next boot.
CAVEATs with FDE
So what’s not to like about encrypting the PBP?
When you turn on your laptop, you will see this on the screen:
disks: sd0* sr0
>> OpenBSD/arm64 BOOTAA64 1.7
Passphrase:
Even though the password prompt will appear on the screen, you will not be able to type your password. It only works through the serial console. For me, this is a showstopper. This means you will not be able to revert the headphone jack to its primary function, and you will always need to have a second computer and serial adapter at hand, just to turn on your laptop.
There is a second downside related to performance. Because of the
PBP’s limited compute power, disk operations will cause a noticeable
CPU load. This is especially apparent on bootup (before apmd gets to
fix the CPU frequencies); at least subjectively, finding the boot
blocks seems to take a great deal longer. But even after the system is
up and running, disk operations will tax the processor. While writing
1GB of zeroes to a file with dd
, the process spent significant time
blocked in bqwait
and biowait
, with CPU usage around 20-30%. For
reference, on the same task but without FDE, CPUs were mostly idle.
For the above reasons, even though full disk encryption technically works (clearly, you can enter the password via the serial console and boot up your laptop), I decided against using it. I reinstalled the base system without FDE on the 128GB eMMC, keeping my 64GB module as a backup, and for possible future experiments.
Minimal tuning and survival tips
There are many great resources on how to set up OpenBSD in general and for desktop use in particular. Here I will only link to this guide which I personally found quite useful. Below are some essentials that are PBP-specific or especially important from our perspective.
Enable apmd
This is important for getting reasonable CPU clock speeds across all the cores. Without this, the ARM cores will be stuck at 600 MHz or so.
The -A
flag enables performance auto-adjustment mode, which is what
you want on a laptop.
rcctl enable apmd
rcctl set apmd flags -A
rcctl start apmd
Adjust display brightness
The hotkeys do not work out of the box, but it is possible to query
and set the display brightness with wsconsctl
:
# wsconsctl display.brightness
display.brightness=100.00%
# wsconsctl display.brightness=70
display.brightness -> 69.41%
To set a permanent default brightness, put the command in
/etc/wsconsctl.conf
, for example:
echo "display.brightness=70" >> /etc/wsconsctl.conf
Fix the Delete key
Pressing Delete
(that is, Fn
+ Backspace
) in xterm
does not
work out of the box the way most people would expect. This is not
strictly specific to the PBP, but something most users new to the
OpenBSD desktop will run into. To fix it, add the following entry to
~/.Xresources
(creating it if it does not yet exist):
XTerm*deleteIsDEL: false
and then either issue xrdb -merge ~/.Xresources
or restart
(logout/login) your X session. For background, see
xterm(1).
First impressions
So now we have OpenBSD on the Pinebook Pro. But to what extent does it actually work?
Things that work
-
The graphical desktop, keyboard and touchpad all seem to work fine.
-
Battery charge indicator seems fine (
i3status
suggests around 7 hours remaining near full charge while idling on 50% display brightness, matching my expectations). -
Wireless network adapter seems to work. But do not expect great performance: I measured roughly 40-50 Mbits/sec of throughput on the 5GHz band, and around 20 Mbits/sec on the 2.4GHz band. For comparison, the same Pinebook Pro with Manjaro ARM 21.12 (temporarily booted from an SD card) managed around 85 Mbits/sec on 5GHz and around the same 20 Mbits/sec on 2.4GHz. OpenBSD’s
bwfm
driver seems to deliver inferior performance on 5GHz compared to what an up-to-date Linux kernel offers; the performance on 2.4GHz seems to be on par. For reference, a contemporary AMD Ryzen 5 laptop with Debian scored around 300-400 Mbits/sec on 5GHz and 50-60 Mbits/sec on 2.4GHz in the same physical locations, on the same home network. For more details, take a look at the measurement logs. -
Audio plays through the speakers (my headphone jack is still on serial, did not yet switch back in anticipation of more tinkering). As expected, the sound level is quite low (even with
sndioctl output.level=1
).Update: I failed to notice this at first, but the keyboard shortcuts for Mute (
Fn+F4
), Volume Down (Fn+F5
) and Volume Up (Fn+F6
) work out of the box! -
The webcam seems to work: following the steps in the Webcam section of the Multimedia FAQ, I was able to bring up a live view of the webcam using this command:
ffplay -f v4l2 -input_format yuyv422 -video_size 1280x720 -i /dev/video0
-
My usual
i3
setup that I have been using for the last decade or so worked almost completely out of the box, so I felt right at home. In fact, I only recall adjusting the device names in thei3status
config for network and free disk space indicators. -
I was able to
pkg_add firefox-esr
, and set it up with my preferred (minimal) set of extensions such as Privacy Badger, adblocker, etc. The browsing experience is a bit sluggish, but OK. -
After a couple days, I successfully bumped my OpenBSD snapshot by running
sysupgrade -s
. While rebooting (both times), I force-powered off the PBP and left it for about 5 minutes without the charger plugged in to make sure it won’t hang on the wifi driver (see below).
Things that do not (fully) work
Wifi driver hangs on boot (with workaround)
As also reported on a previous
account, sometimes the PBP will
freeze during boot. It seems to get stuck in the bwfm
driver. Once
stuck, immediate restarts will also likely run into this issue, so it
feels like you are trapped in an endless crash-restart-crash loop.
These are the relevant (and last) lines printed on the console:
bwfm_sdio_buf_write: error 60
bwfm0: timeout on core reset
However, I found that the problem only happens on warm reboots and/or reboots done shortly after the previous power-off, and with the charger plugged in. I suspect some hardware state might not be correctly reset or (re)initialized on reboot, so it only works if the whole machine started up cold. If this happens to you, try to give the circuits some extra downtime so they can fully discharge and “forget” everything. Disconnect the charger as well for the wait, and boot before possibly plugging it in again. With this treatment, so far I could almost always bring up OpenBSD on the first try.
“Real” console
As you’ve already seen, after U-Boot hands off execution to the kernel, there is only a flicker on the LCD where console output should be. Eventually, X will appear and things will look normal. When the system is up and running, I can even switch pseudo-terminals (with Control-Alt-Fn where n > 1), and they seem to work fine.
Still, the lack of console support is a real impediment to a more streamlined installation procedure and taking advantage of OpenBSD’s otherwise excellent support for full disk encryption.
Update: see my follow-up post for some half-baked patches to tackle this issue.
Poweroff
After shutdown -h -p now
, OpenBSD is not able to power down the
laptop. After the below message appears, I have to keep the power
button depressed for several seconds to power off the hardware.
*** FINAL System shutdown message from root@aurora.lan ***
System going down IMMEDIATELY
System shutdown time has arrived
syncing disks... done
Attempting to power down...
At least for me, this is not a big deal. If you don’t have the serial terminal attached, count to ten after issuing the shutdown command and before depressing the power button, and you should be fine.
Update: see my follow-up post for a patch to work around this issue.
Microphone input
I was not successful in trying to record (or otherwise detect the
presence of) audio input from the PBP’s microphones. Trying to debug
the issue, I found
that while recording with aucat -o rec.wav
, the output of audioctl
showed lines record.bytes=0
and record.errors=0
(i.e., stuck at
zero) while play.bytes
kept happily increasing. Neither decreasing
the sample rate from 48000 to 44100 to 32000, nor switching
record.channels
from 2 to 1 changed the outcome. I took this as a
sign of missing driver support and gave up.
AC adapter state
While the battery capacity readout seems accurate, apm
reports the
AC adapter state as “unknown”, so OpenBSD is seemingly unaware of
whether the PBP is on charger or running on battery. The battery does
get charged if AC is connected (I guess that works on the hardware
level), and the capacity seems to be accurate (increasing while being
charged), so no big deal.
Update: I was advised that hw.sensors
contains an entry for this:
sysctl hw.sensors.gpiocharger0.indicator0
hw.sensors.gpiocharger0.indicator0=On (mains power supply)
SD card slot
I plugged in a known-good SD card, but nothing even appeared in
dmesg
, so I assume this is a case of missing platform support. My
USB-connected SD card reader seems to work though, so this is not a
real issue for me. And I can still use the SD slot to boot a different
operating system on a temporary basis.
Suspend and resume
This is something that clearly does not work; even the display screen stays bright after I close the lid. Another clear case of missing platform support.
Conclusion
Given the target audience of the Pinebook Pro is hardware tinkerers and Linux/BSD enthusiasts: in case you are into OpenBSD, I feel this is a workable state of affairs. Hardware support is a bit incomplete here and there (but we knew that from the start). We still get a very reasonable set of capabilities and the performance is roughly on par with Linux (minus GPU acceleration of the desktop and diminished 5GHz wireless throughput). Of course, this won’t cut it for those demanding a “production quality” or “professional” laptop experience, but for us tinkerers, I feel it’s a pretty comfortable place to be. Considering that things are bound to improve even further, OpenBSD has earned its stay on my Pinebook Pro.
1 Okay, okay. Because it’s a great way to learn more about OpenBSD, and the Pinebook Pro, and the nascent ARM64 architecture. Because it’s the best excuse to tinker with hardware and generally to appease your inner geek, and possibly to build the ultimate geeky laptop for yourself.
2 Just look at all the SBC forums full of people complaining about various install errors that turn out to be caused by faulty or badly written SD cards.
3 With the obvious exceptions of breaking the hardware or bricking the embedded controllers, such as that of the keyboard. Then you will be in the market for a brand new PBP or two.
4 If you are also into the DIY route, try to scavenge an audio plug on a cable that you can cut off, like an old pair of headphones. Then you can blank and solder the wires from the cable to a standard FTDI header (2.54mm pins). That is what I will do to build my real serial console adapter as soon as I find a suitable “donor”.
5 You could probably use a computer with a different operating system as long as you are able to perform the tasks with it, but in that case you will have to come up with the equivalent programs to use and commands to run.
6 If the machine we used for this preparation was
another OpenBSD running the same snapshot, we could just install these
via pkg_add
. In general (and especially if you use Linux) that is
not feasible.
7 I changed it to sdX
to protect those guilty of
mindless copy-pasting.
8 If it’s not sd1a
, it is probably going to be
sd1i
, which is how a single FAT32 partition looks to OpenBSD.
9 I have no idea why this happens, but I suspect the graphics, since after a hard poweroff due to a wifi boot hang, the filesystem will be clean thereafter.
10 This might not apply to you if your PBP is recent enough. Please check the Pine64 forums.