Walkthrough installation of OPNSense on PCEngines APU2 single board
Install OPNSense on APU2
How to install OPNSense on a APU2 board?
Introduction
In my previous article — Plan my Home Lab, we discussed the importance of having a kind of plan or vision of your lab. It allows you to make progress towards your goals.
In this article, we start some implementation of my Home Lab. We will install and configure my new home router. It will be the base of the next steps. On this router, I will need to configure DNS and DHCP at least. I will also segment my network into two parts with my leisure appliances like TV, gaming consoles, and so on. In the other segment, I will have my lab.
Before we start
What is OPNSense?
OPNsense is an open source, easy-to-use and easy-to-build HardenedBSD based firewall and routing platform. OPNsense includes most of the features available in expensive commercial firewalls, and more in many cases. It brings the rich feature set of commercial offerings with the benefits of open and verifiable sources. — OPNSense website
It is a great open-source software to install on such a device. It can replace your internet provider modem-router.
What is the APU2 single board?
PC Engines offers small, low power servers for your network security, wireless networking, or embedded applications. — PCEngines website
The explanation on the PCEngines website is self-contained and clear enough 😄. It is a great fit to be the hardware piece that can be like your internet provider modem-router.
APU2 board assembly
Before we start the installation itself, we need first to get all the material. We have to assemble the router hardware. You can buy a device already built, but it is less fun.
First, here are all the parts to assemble:
- APU2 — apu4d4 (I went for four eth ports)
- Enclosure 4 LAN USB black (red and blue are two other options)
- AC adapter with euro plug (other variant also exists on PCEngines)
- 120GB mSATA SSD module (for sure, it is overkill)
- heat spreader placement fixture (optional accessory to place the thermal plate)
Also, I need to connect my Mac Book Pro with the APU2. My laptop has only USB-C ports. The APU2 offers a DB9 port. PCEngines sells USB-A to DB9 cable. So, I need an adapter for USB-C to USB-A.
With all the parts, I have to follow the documentation to assemble them up. As I have an APU2 board, I only have one thermal strip to paste on the CPU. The second link completes the instructions with a focus on the aluminum plate placement.
In summary, here are the operations I did:
- Remove the DB9 hex nuts
- Paste one thermal strip on the CPU.
- Use the heat spreader placement guide to paste the aluminum plate on the casing
- Place the APU2 board in the case with the CPU thermal strip. The strip will be in contact with the aluminum plate.
- Place the mSATA SSD module on the left of the board. Take note of the remarks in the documentation and do not forget to screw in your mSATA SSD module.
- Finally, close and screw in the casing top.
The physical assembly is over. It is time to boot for the first time and try to do something with this board.
Preparation
The installation requires some preparation. We need to download and install some tools.
Etcher will allow us to flash a USB stick with the OPNSense installer. We will later boot from the USB stick for the installation.
To install Etcher, run the following command. It assumes that you are running under Mac OS X, and you are already using homebrew.
❯ brew cask install balenaetcherI am not someone who often verifies what I download. I assume the risk when downloading corrupted/comprised files. Here, I wanted to follow the best practices. The OPNSense install documentation explains how to check the downloads.
Download and verify OPNSense
Download the OPNSense for Serial installer. I picked a swiss mirror for my download.
I retrieved the public key (you have various sources to find the public key). Avoid downloading the public key from the mirror. The documentation mention this point. All files on a mirror can be compromised.
I also got the signature and the checksum (again, it depends on the mirror you pick). Then, I ran the following command to process the signature:
❯ openssl base64 -d -i <signature_file>.sig -out /tmp/image.sigAnd to verify the image, I ran this command:
❯ openssl dgst -sha256 -verify <key>.pub \
-signature /tmp/image.sig <image>.img.bz2Here is the real example of what you can expect:
❯ openssl base64 -d \
-in OPNsense-20.7-OpenSSL-serial-amd64.img.bz2.sig \
-out /tmp/image.sig
❯ openssl dgst -sha256 -verify opnsense.pub -signature \
/tmp/image.sig OPNsense-20.7-OpenSSL-serial-amd64.img.bz2
Verified OKPrepare USB boot image
For the installation, we need to prepare a USB drive with the OPNSense image. We need a drive with at least 2Gb. All the data on the drive will be lost during the operation. Use a recent USB stick for this operation. I encountered several issues during the installation process of OPNSense. The age of my USB Stick did not help.
We need to unzip the image file. Use the following command to do it.
❯ bzip2 -d OPNsense-20.7-OpenSSL-serial-amd64.img.bz2Here is what you do to flash your USB drive. Connect it, and open the Etcher application. Click on the “Flash from file” button. Pick the image file you unzipped.
Then, you can select the USB drive you want to use to be your boot drive with OPNSense. Finally, click on the “Flash” button.
Wait until the completion of the flashing process.
Your USB boot drive is ready. You can disconnect it and go to the next steps.
Installing OPNSense
For the first boot, prepare the physical connection to the board. Connect the USB-C to USB-A adapter to the USB-A to DB9 cable and adapter. Then connect the USB-C to your computer, and (obviously) your board. You can now boot the board by plugging the power connector.
Open a terminal window to find which devices you can connect to. For this, run the following command:
❯ ls -laht /dev/*usbserial*
crw-rw-rw- ... /dev/cu.usbserial-01E7357C
crw-rw-rw- ... /dev/tty.usbserial-01E7357CIf you find nothing, you may need to install the serial console chip driver. You can find the driver for the CP2104 chipset on Silicon Labs website. Some complementary info on the Teklager website. The installation of the driver is straightforward.
Once you have found the device, you can execute the following command to connect to the APU2:
❯ screen /dev/cu.usbserial-01E7357C 115200,8n1The result would be something like this:
Press F10 to boot from the USB stick.
The first time I tried to boot from my USB stick, I encountered an issue. It was like my USB stick was unreadable. The APU2 board could not read it. See the errors in the next two screenshots.
Here, it means your USB stick is not supported by the APU2. For me, it may have been because my USB stick is old. Thus, you have two solutions:
- Use a recent USB stick
- Retry to boot as often as necessary. It took me 2–3 times before booting correctly. I will go for option one as soon as possible but meanwhile, the second option is ok 😝.
For the second option, you can type reboot when you have the prompt available.
Once you finalize the OPNSense boot from the USB stick, you will be able to install it. During the boot process, I left all the options with defaults. You can observe the full boot sequence in this cast:
Then I used the user installer with password opnsense. The credentials are present in the OPNSense documentation.
After this, start the install by pressing enter on the text < Ok, let’s go >.
You can configure the keymap and video settings. I kept the defaults. I pressed on enter on < Accept these Settings >.
Afterward, I answered different options on how to install OPNSense. I pressed enter on < Guided installation >.
Serious things are starting. Choose the destination of the install. I pressed enter on < ada0: 114473MB (234441648 512 byte sectors) >, which is my SSD storage.
Then, you will have choices for the installation mode. I pressed the enter key on < GPT/UEFI mode > which is the default mode.
Finally the installation starts. Define the swap size. I left the default configuration by pressing enter on < yes >.
After that, it copies the files. It will take several minutes to install. Then, you will have a prompt to set the root password. Fill the password fields and press enter. Press enter on < Accept and Set Password >.
Finally, after all these steps, reboot or choose another task. I went for the reboot by pressing enter on < Reboot >.
During the reboot process, you get info on how to connect to the device.
If you want to view the entire installation, you can go to the screen recording (5 minutes recording). All the screenshots shown above come from this screen recording.
My APU2 board is now installed with OPNSense. To be honest, it was not so trivial. The serial console connected via screen was a first for me. The first time I tried to install OPNSense on the device via the serial connection. I allow you to laugh at me for this one. I realized my error that transferring 2Gb at a rate of 115200 bit/s will take time. 2Gb is 2e+9 bits. At this speed, it will take 17361 seconds → approx. 4 hours 😅.
The documentation of OPNSense installation was not clear for me. I did not understand I had to prepare a USB Stick with OPNSense image. It is the first time I installed this kind of software. In the documentation, they have some dd commands. It is the command-line approach to preparing the USB stick. I preferred to use Etcher instead.
Conclusion
Starting an installation from scratch is always easier than a migration. I had no previous OPNSense installation. So, I do not have an older configuration file to use. It is always easier to start from scratch compared to starting from existing setups.
Now that I have installed it, I need to configure my router with the different services (DNS, DHCP,…). I will cover all that stuff in a future article. But before starting the configuration, I would like to update the firmware. It will be more challenging compared to this installation.
References
I used asciinema to record my terminal session. It can capture what I am doing and take screenshots later. It is a convenient way to work in a deferred way.
Unfortunately, there is no embed.ly available for asciinema on Medium. So, the simplest solution I found is to convert some of my screen recordings into GIFs. For this, I used the tool asciicast2gif. It is supported by asciinema.
I also use a command-line tool to edit my screen recordings. For example, I can reduce the delays between two outputs, I can cut parts of the recording. My OPNSense installation recording had a duration of about 25 minutes. I compressed it to 5 minutes.
This Medium article helped me to embed terminal sessions in my articles.
Homebrew is the most used package manager on Mac OS X. In the past, I used Mac Ports. Now, I only use Homebrew as it comes also with the ability to install rich applications.
Another tool I used to annotate my screenshots is Skitch from Evernote. It is free and easy to use. It does the job I need without too many options. Drag and drop from the app to the folder in the finder is enough to generate a PNG file from a screenshot.
To flash my USB sticks, I used Etcher from Balena. It is an easy tool to use. It can flash many sticks at once.
The TekLager commercial website is dedicated to APU/ALIX boards or similar. It offers a great knowledge base. I found an article for the serial console as an example. It also contains articles on PFSense and OPNSense.
And finally, the official websites of OPNSense and PCEngines.
