0xC45

Digital Audio Synthesizer in Rust

2022-01-09T00:00:00+00:00

Overview</h2>
Over the past couple weekends, I built a digital audio synthesizer in rust. It is controlled via the keyboard, with the bottom two rows emulating piano keys. Since there are fewer keyboard buttons than piano keys, you can specify which octave to play via a command line argument. For some extra fun, you can also specify which waveform to synthesize (sine, square, triangle, or sawtooth). Lastly, it is polyphonic, meaning it supports playing multiple notes at the same time (keyboard hardware / firmware permitting). Here</a> is a link to the code.</p>

In theory, digital audio synthesis is fairly straightforward. To create sound, send a series of digital values to the sound card that represent the relative position of the speaker cone at each instant in time. These digital values are converted to analog electric signals by the sound card, which get transformed into sounds via the motion of the speaker cone.</p>

</p>

This simple synthesizer is able to generate 4 distinct types of sounds (waveforms) by oscillating the speaker(s) in different ways. It receives button press events from the keyboard, determines what frequency (or "note") that key represents, then computes a waveform that oscillates at the desired frequency.</p>

On startup, the program launches two threads: graphics and audio.</p>

Graphics</h3>
Currently, the only job of the graphics thread is to create a window for the program, receive keyboard events, translate keyboard events to "midi" note on / off events, and send the midi events to the audio thread. It does not yet display a useful GUI for the synthesizer.</p>
</p>
To draw the window and collect keyboard events, I decided to use the piston</a> game engine library. This is a popular library that abstracts a bunch of the platform-specific details away. It should be easy to use this library to eventually make a useful UI.</p>
To send note on / off events to the audio thread, I employed the crossbeam</a> library's bounded channel. This is far from an optimal solution. Production quality audio engines utilize lock-free data structures (such as lock-free circular queues), self-managed heaps, and atomic data access. See this video</a> for a good overview of these concepts. Real-time guarantees would be a good area of future exploration to improve this synthesizer and my general rust language knowledge.</p>

Audio</h3>

The majority of the work for this program is done in the audio thread. To generate sound, I use CPAL</a>, a cross-platform audio library for Rust. The API this library provides was a bit bizarre to me at first. However, after doing some more research about audio programming, it seems to be the standard way of interacting with sound cards.</p>

As a user of CPAL, you provide a callback function (closure, actually). On regular intervals, the audio callback function is run, which must fill in the next chunk of digital audio values. For each note that is currently being played, the synthesizer generates values that correspond to a waveform. For example, here is a plot of a simple sine wave that was generated by this synth (plotted with gnu octave):</p>

</p>

To play this sound, the audio loop computes all of the "y" values for this waveform and dumps them into the audio buffer. To support polyphony (playing multiple notes at once), all of the values for each of the notes are added together. The resulting waveform may be quite complex. For example, here is the waveform of a simple 3-note chord (triad).</p>

</p>

Here is the core loop that computes and generates the various waveforms:</p>

let mut</span> value = </span>0_</span>f32</span>;
</span>
</span>for </span>(_, </span>mut</span> note) in active_notes {
</span>    </span>// increment the note clock
</span>    note.envelope.clock = note.envelope.clock + </span>1_</span>f32</span>;
</span>
</span>    </span>// compute common values
</span>    </span>use </span>std::f32::consts::</span>PI</span>;
</span>    </span>const </span>TAU</span>: </span>f32 </span>= </span>2_</span>f32 </span>* </span>PI</span>;
</span>    </span>const </span>AMPLITUDE_MODIFIER</span>: </span>f32 </span>= </span>0.2</span>;
</span>    </span>let</span> period = note.envelope.clock / audio_ctx.sample_rate;
</span>
</span>    </span>// determine next sample value
</span>    </span>let</span> sample = </span>match</span> note.waveform {
</span>        Waveform::</span>SINE </span>=> (note.frequency * </span>TAU </span>* period).</span>sin</span>(),
</span>        Waveform::</span>SQUARE </span>=> </span>match </span>(note.frequency * </span>TAU </span>* period).</span>sin</span>() {
</span>            i </span>if</span> i > </span>0_</span>f32 </span>=> </span>1_</span>f32</span>,
</span>            _ => -</span>1_</span>f32</span>,
</span>        },
</span>        Waveform::</span>TRIANGLE </span>=> (note.frequency * </span>TAU </span>* period).</span>sin</span>().</span>asin</span>() * (</span>2_</span>f32 </span>/ </span>PI</span>),
</span>        Waveform::</span>SAWTOOTH </span>=> (((note.frequency * period) % </span>1_</span>f32</span>) - </span>0.5</span>) * </span>2_</span>f32</span>,
</span>    };
</span>
</span>    </span>// add sample to final value
</span>    value += sample * </span>AMPLITUDE_MODIFIER</span>;
</span>}
</span>
</span>value
</span></code></pre>
For each note, the internal "clock" is incremented. This is the x axis for the graphs above. Then, based on the required waveform, the next y value is computed. All of the values are scaled based on some modifier (to reduce volume and allow multiple notes to be played at once). Each note's value is added to produce the final value for the instant.</p>
Based on a typical sample rate of 44.1 kHz, this loop must run 44,100 times a second. Therefore, it's essential to ensure that the audio callback function is highly efficient and maintains predictable runtimes. Otherwise, the audio stream will drop and there will be noticable clicks / pops in the sound.</p>
Next Steps</h2>
There are many ways that I plan to improve this synthesizer:</p>


Improve latency</p>
Currently, there is a slightly noticable latency between when you press a key on the keyboard and when the sound starts. This can be improved by optimizing the audio callback function and reducing the audio buffer size (so there is less latency). It may be necessary to employ a lock-free data structure to handle communication between the graphics and audio threads. In general, the audio callback function needs to be optimized for speed and to ensure a predictable runtime.</p>
</li>

Add GUI elements</p>
There is a GUI window, but it currently does not display anything. To improve user experience, the key presses should have some visual feedback. Also, it would be nice to be able to configure the waveform, envelope, etc. via some UI elements.</p>
</li>

Add configurable envelope</p>
To make more interesting sounds, I want to add configurable "envelopes" for the notes. The envelope is the relative amplitude (or volume) of the waveform over time. For example, a piano key is loud initially, then fades slowly.</p>
</li>

Ecosystem integration</p>
By turning this program into an actual MIDI receiver, it will be possible to send MIDI events that trigger sounds from outside sources, such as a physical piano keyboard or fun programs like Orca</a>.</p>
</li>

Embedded (?)</p>
It would be cool to run this code on some embedded system and create a standalone digital audio synthesizer.</p>
</li>
</ol>
Conclusion</h2>
This has been an interesting project. Before, I had extremely fuzzy / incomplete digital audio knowledge. What is a sound wave? How do speakers work? Now, I know enough to make simple noises and tones. Looking at youtube videos of electronic music production, modular synthesizers, and DIY analog synths, I am astounded at the complexity of sounds that people can produce by combining these basic elements. There is a lot more to explore in this space.</p>
Links</h2>

Code for this project on Github: https://github.com/0xC45/simple-synth</a></li>
CPAL - Rust cross-platform audio crate: https://github.com/RustAudio/cpal</a></li>
Piston - Rust game engine crate: https://crates.io/crates/piston</a></li>
Crossbeam - Rust concurrent programming crate: https://crates.io/crates/crossbeam</a></li>
CppCon 2015: Timur Doumler “C++ in the Audio Industry”: https://www.youtube.com/watch?v=boPEO2auJj4</a></li>
Orca - esoteric procedural sequencer livecoding environment: https://github.com/hundredrabbits/Orca</a></li>
Making sounds using SDL and visualizing them on a simulated oscilloscope: http://nicktasios.nl/posts/making-sounds-using-sdl-and-visualizing-them-on-a-simulated-oscilloscope.html</a></li>
Code-It-Yourself! Sound Synthesizer #1 - Basic Noises: https://www.youtube.com/watch?v=tgamhuQnOkM</a></li>
</ul>

4x4 Macro Pad

2020-10-06T00:00:00+00:00

Overview</h2>
Last weekend, I built a 4x4 keyboard kit. By this point, many people are familiar with the growing (and outspoken) mechanical keyboard hobbyist community. However, this kit is a bit unique. It's not a full keyboard. Instead, it's a 4x4 "macro pad" intended for sending keyboard shortcut sequences such as muting my microphone, muting my audio, volume up, volume down, etc. Additionally, with some extra software such as AutoHotKey, vastly complex programs could be triggered with the press of a button.</p>

Build Process</h2>
Overall, building the macro pad was a simple and straightforward process. The kit's build guide</a> provides a nice set of instructions with pictures to explain things. However, unlike many (some?) keyboard kits, the Sweet 16 kit requires soldering a few smaller components, such as the diodes and microcontroller headers. Additionally, the kit requires soldering one "surface-mount" component, the reset switch.</p>
The parts: </p>
Completed build: </p>

Flash Firmware</h2>

To program my custom keymap (including multiple keypress macros), I used QMK firmware</a>, the most popular keyboard firmware project.</p>

Using QMK, it's possible to create custom keycodes that, when pressed, trigger a sequence of inputs. So, by pressing one button on the macro pad (or keyboard), the firmware will submit an entire sequence of keycode presses.</p>

To do this, I defined my custom keycodes in an enum:</p>

enum </span>macro_keycodes {
</span>  MICMUTE = SAFE_RANGE,
</span>  MACRO1,
</span>  MACRO2,
</span>  MACRO3,
</span>  MACRO4,
</span>  MACRO5,
</span>  MACRO6,
</span>  MACRO7,
</span>  MACRO8
</span>};
</span></code></pre>
Next, I defined a "keymap" array. Each position in the array corresponds to a single button on the 4x4 macro pad:</p>
const </span>uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
</span>  [</span>0</span>] = </span>LAYOUT_ortho_4x4</span>( </span>/* Base */
</span>    MICMUTE, KC_MUTE, KC_VOLD, KC_VOLU,
</span>    XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,
</span>    MACRO1,  MACRO2,  MACRO3,  MACRO4,
</span>    MACRO5,  MACRO6,  MACRO7,  MACRO8
</span>  ),
</span>};
</span></code></pre>
Lastly, I implemented the process_record_user</code> function to define what should happen when each custom keycode is pressed:</p>
bool </span>process_record_user</span>(uint16_t </span>keycode</span>, keyrecord_t *</span>record</span>) {
</span>  </span>switch </span>(keycode) {
</span>  </span>case</span> MICMUTE:
</span>    </span>if </span>(record->event.</span>pressed</span>) {
</span>      </span>SEND_STRING</span>(</span>SS_LCTL</span>(</span>SS_LALT</span>(</span>SS_LSFT</span>(</span>SS_TAP</span>(X_F10)))));
</span>    }
</span>    </span>break</span>;
</span>  </span>case</span> MACRO1:
</span>    </span>if </span>(record->event.</span>pressed</span>) {
</span>      </span>SEND_STRING</span>(</span>SS_LCTL</span>(</span>SS_LALT</span>(</span>SS_LSFT</span>(</span>SS_TAP</span>(X_F1)))));
</span>    }
</span>    </span>break</span>;
</span>  </span>/*
</span>   * ... etc
</span>   */
</span>  }
</span>  </span>return </span>true</span>;
</span>}
</span></code></pre>
As you can see, I have configured the MICMUTE</code> button to send the entire sequence CTRL+ALT+SHIFT+F10</code>. However, in practice, any arbitrary sequence could be sent for any button. And, that's only beginning to scratch the surface of the capabilities of the QMK firmware.</p>
Design Keycaps</h2>
For this "DIY" kit, it felt important to design my own icons. I'm no graphic designer, but it was kinda fun. To do this, I used "re-legendable" keycaps that snap together with a clear top. Then, I printed the icons on plain white paper, cut them out, and sandwiched each icon in the keycaps. Here's a photo of my efforts:</p>
</p>
Conclusion</h2>
This was a pretty quick project, but I felt like it deserved a writeup nevertheless. As a relative beginner at soldering, this kit was a fantastic way to increase my skills and ability beyond the "absolute beginner" level required for most keyboard kits. Furthermore, the final product is quite useful and extensible. Beyond the specific purpose as a simple macro pad keyboard, this hardware is essentially a microcontroller connected to a set of buttons. There are numerous possible applications. It's ripe for hacking. This device could become a MIDI controller, home automation remote, or anything else my imagination might dream up. Until next time.</p>
Links</h2>

Sweeet 16 Macro Pad Kit: https://www.1upkeyboards.com/shop/keyboard-kits/macro-pads/sweet-16-macro-pad-black/</a></li>
QMK Firmware: https://qmk.fm/</a></li>
My Sweet 16 Keymap: https://github.com/0xC45/qmk-firmware/blob/master/keyboards/1upkeyboards/sweet16/keymaps/0xC45/keymap.c</a></li>
</ol>



Ansible-defined Homelab
2020-07-25T00:00:00+00:00
Overview</h2>
Around November of last year, I started a project to wrangle my digital life. Tired of haphazardly increasing my subjectivity by trusting "free" websites to provide various services, I wanted to wrest some control over my internet existence. I made a plan to self-host several "critical" services on my home network and maintain them personally. In short, I made a homelab.</p>
To be frank, the professional websites that I was previously dependent upon are undoubtedly more reliable than my cobbled-together hobby project of a homelab. However, on general principle (and because it seemed like a fun way to learn some sysadmin / devops skills), I made this setup:</p>
</p>
As you can see, I have deployed a couple of general-purpose compute platforms: 4 ESXi hypervisors, and a Kubernetes cluster. Additionally, there are several VM-based services: Nextcloud, Gitea, and Harbor. For data storage and backup, I use a Synology NAS. Finally, a custom OpenBSD-based router provides internet connectivity to everything. In order to reduce operational overhead, I crafted a set of Ansible scripts</a> that deploy and configure all of these components.</p>
Overall, making this setup has been quite a journey. In this blog post, I will describe my uses for each of these services, share my thoughts and experiences so far, and attempt to articulate my future improvement plans.</p>
Motivation</h2>
Of course, everything you see above already exists as a service on the internet. If my goal were solely the end feature set, it would have been much simpler to pay for each service. In most cases, there are even "free" versions available. For example, if I only cared about having access to a web-based git repository UI, I could have signed up for a Github or Gitlab account rather than bother setting up a Gitea VM on my home network.</p>
However, like most of my hobby projects, this endeavor was more about the journey than the destination. By setting up these services on my home network, I learned a bunch of useful devops and sysadmin skills. Additionally, by running my own services, I have achieved the philosophical goal of reducing my reliance on 3rd party services. Now, if any of the services that I rely upon break, I am empowered to fix them.</p>
Components</h2>
So, without further ado, let's dive into each of the components that make up my homelab. For each component, I will describe the main utility it provides me, why I chose it, and any additional commentary that may be helpful.</p>
Router</h3>
The first component of my homelab is a custom OpenBSD-based router. It provides internet connectivity and DHCP to everything on my home network. Additionally, the device serves as a caching DNS server and firewall. I could write an entire blog post describing this router in excruciating detail. In fact, I already have</a>.</p>
ESXi Hosts</h3>
In total, I maintain four physical ESXi</a> hosts to form a platform for running virtual machines on my network.</p>
Three of the ESXi hosts are Intel NUCs (System76 Meerkats). These smaller machines run the VMs that form my Kubernetes cluster.</p>
The other ESXi host is a custom machine built from spare parts. It currently runs three VM-based HTTPS services: Nextcloud, Gitea, and Harbor. Because it only runs three (relatively small) VMs, it has quite a bit of spare compute power leftover for future additions and/or temporary experiments.</p>
I chose ESXi to run my virtual machines because it's enterprise quality and free. There are many hypervisors out there. For my current use case, ESXi is perfect. Also, in the future, I may consider expanding my use of VMware products by running vCenter to programmatically manage virtual machines, setting-up vSAN for shared storage, and potentially installing NSX if my networking requirements become more complicated. So, there is room to grow.</p>
Kubernetes Cluster</h3>
In addition to the VM-based compute platform provided by ESXi, I run Kubernetes to provide a container-based compute platform. Though I do not currently use my Kubernetes cluster for anything, I have plans to setup Argo CI/CD</a>, experiment with kNative</a>, develop some operators, and maybe run a factorio game server</a>.</p>
The Kubernetes cluster consists of 6 VMs running across 3 Intel NUCs. I chose to install Kubernetes on VMs with the ESXi hypervisor layer for ease of management. At some point, I'm sure to break things, want to reconfigure, etc. With the hypervisor, it's easier to perform these type of adjustments. Furthermore, at some point in the future, I may switch to TKG</a>, a vSphere-integrated distribution of Kubernetes.</p>
Synology NAS</h3>
For backups and storing important data, I use a Synology NAS</a>. Though I didn't really shop around and compare NAS products / vendors, I am happy with the Synology so far. That being said, I would like to create my own NAS from scratch at some point in the future. However, the Synology product includes several features "out-of-the-box" that would be potentially difficult to replicate.</p>
First, it has an easy-to-use application called "Active Backup for Business"</a> that can automatically take backups of ESXi virtual machines following configurable schedules and retention policies.</p>
The VM backup application pairs nicely with the automatic cloud backup application, "Glacier Backup"</a>. Every night, after the VMs are backed-up to the NAS, I replicate the backups to Amazon S3 Glacier. Hopefully, this way I won't ever lose data.</p>
Finally, the Synology has built-in UPS integration. If my UPS</a> loses power for more than one minute, the NAS will cleanly shutdown, preventing any data corruption that could be caused by an unexpected power loss.</p>
Nextcloud VM</h3>
I use Nextcloud</a> as my "personal cloud". I use it to store my important files and photos. The desktop / mobile application synchronizes the files across all of my devices, allowing me to edit and view my files from anywhere.</p>
Nextcloud also has the capability to install "apps" that provide additional functionality. Currently, I have only installed one app, "Deck"</a>. Deck is a Kanban-style project management and organization tool. I use Deck to plan, organize, and record progress on my hobby projects.</p>
Because it gives me the capability to install (and potentially create) apps, Nextcloud is an extensible platform. It's open source and under active development. Though the recent major version upgrade was a bit rocky (for me, at least), I'm happy with Nextcloud and plan to stick with it.</p>
Gitea VM</h3>
Of course, I need a place to store my code. For that purpose, I use Gitea</a>. I prefer Gitea to Gitlab because it's lighter-weight. Unlike Gitlab, there aren't a million additional features bundled-in that add bloat (in my opinion). Also, I slightly prefer the Gitea UI over the Gitlab UI.</p>
There's really not much else to say about Gitea. It works great for my purposes. I push all of my code to the Gitea VM running on my home network. Whenever I want to "publish" a project or share it with the world, I push my code to a public Github repo.</p>
Harbor VM</h3>
To make container images available for running on my Kubernetes cluster, I need a container registry. For this purpose, I use Harbor</a>, an open source solution that seems to be the current most popular self-hosted container registry. In addition to providing a standard API for pushing/pulling container images, Harbor has the useful capability to scan container images for known vulnerabilities.</p>
Harbor has worked well for me so far, but I haven't really placed it under a serious workload. Soon, I will start using my Kubernetes cluster for various projects, which will require pushing / pulling images from Harbor on a regular basis. Perhaps, at some point in the future, I will have a more nuanced opinion of Harbor.</p>
Future Improvements</h2>
Though I am happy with the current setup, I continually find myself coming up with ideas for potential improvements and additions to the homelab. Here are a couple of the more well-defined ideas.</p>
First, I want to install Argo</a> on the Kubernetes cluster to run pipeline-based workflows. For example, it could be useful to automatically run tests for every commit that gets pushed to my repositories on Gitea. More generally, I could configure Argo to trigger a job for any arbitrary external event. It could be used to create a notification service. Or, it could be used to manage heavy workloads. There are endless potential uses for a pipeline-based workflow engine such as Argo.</p>
Second, I want to create a dashboard that provides a graphical representation of the status of each of my homelab components using Grafana</a>. Using various open-source tools, I could collect metrics and aggregate them. Then, using Grafana, I could visualize the data. It would be useful to be able to quickly ascertain the state of my home network services in order to understand workloads, diagnose issues, etc.</p>
Conclusion</h2>
With the work spanning several months, creating my homelab has been quite a journey. Along the way, I started to grow weary, concerned that I had signed myself up for the all-consuming task of operating my homelab. With the overhead required to maintain all the various components, how could I ever have time for anything else? However, I'm happy to report that the Ansible script automation has proved worthwhile. Now, upgrades, configuration changes, and various "day 2" operations are quick and simple. At this point, I'm looking forward to shifting gears and working on something else for a while, using my homelab services as helpful tools along the way.</p>
Links</h2>

Homelab Ansible scripts: https://github.com/0xC45/homelab-setup</a></li>
"OpenBSD Home Router" blog post: https://0xc45.com/blog/openbsd-home-router/</a></li>
</ol>


My Zola Workflow
2020-07-05T00:00:00+00:00
Overview</h2>
To build this website, I use the Zola static site engine</a>. So far, it has worked great. In this blog post, I will discuss my workflow improvements for using Zola, developing my blog posts, and publishing this website. As a quick intro, however, I will give a brief summary of the main features of Zola and why I chose to use it.</p>
What is Zola?</h3>
Zola advertises itself as a static site engine. It "compiles" Markdown content files, HTML templates (based on the Tera template engine</a>), and Sass</a> styling into static HTML and CSS pages. This way, a Zola website does not require any server-side code to "render" the website pages.</p>
In addition, Zola has several convenience features that one would want for a blog or website, such as built-in syntax highlighting</a>, simplified pagination</a>, and auto-generation of atom/rss feeds</a>.</p>
So, Zola is an all-in-one tool for generating static websites. As a blog author, I can mainly focus on writing my blog post content (in Markdown). I don't have to worry too much about HTML syntax, CSS styling, linking, pagination, or my Atom feed (after the initial setup and creation of my site theme). When I'm done writing a blog post, I "generate" the static site with Zola. All of the repetitive and error-prone work is handled for me and the actual static website pages are produced.</p>
Why use Zola?</h3>
There are many competing static site generators out there. Zola is but one of many. Currently, Hugo and Jekyll are probably the two most popular static site generators. However, for this website, I chose to use Zola for a few reasons:</p>

It's simple. It doesn't have a ridiculous number of features that will confuse me and distract me from actually writing blog posts.</li>
It's capable. It has all the feature that I need.</li>
It's a relatively new project. Why not give it a try?</li>
</ul>
My Zola Workflow</h2>
Rather than repeat stuff you can find in the Zola documentation, in this blog post I will cover three of my personal "workflow hacks" for working with Zola. Hopefully at least a couple of these patterns are useful to you.</p>
Git pre-push Hook</h3>
Because this blog is hosted on Github pages, git push</code> is equivalent to publishing the site. Early on, I made the mistake of writing an entire blog post, but forgetting to "generate" the static site. So, I made a commit, pushed, and nothing happened.</p>
To prevent myself from making this mistake again, I added a "pre-push" hook to my git repo. Now, git will refuse to push if the generated static site is out of date.</p>
Here is my simple "pre-push" git hook:</p>
#!/usr/bin/env bash
</span>
</span>project_root</span>="$</span>( </span>git</span> rev-parse</span> --show-toplevel </span>)</span>"
</span>pushd </span>"$</span>{</span>project_root</span>}</span>" &> /dev/null || </span>exit</span> 1
</span>make </span>&> /dev/null
</span>num_diff_files</span>="$</span>( </span>git</span> diff</span> --name-only </span>| </span>wc -l </span>)</span>"
</span>num_untracked_files</span>="$</span>( </span>git</span> ls-files</span> --others --exclude-standard </span>| </span>wc -l </span>)</span>"
</span>if </span>[ </span>"$</span>{</span>num_diff_files</span>}</span>" != "</span>0</span>" </span>] </span>|| </span>[ </span>"$</span>{</span>num_untracked_files</span>}</span>" != "</span>0</span>" </span>] </span>; </span>then
</span>  </span>echo </span>"</span>diff detected after running </span>\`</span>make</span>\`</span>, not pushing</span>"
</span>  </span>exit</span> 1
</span>fi
</span>popd </span>&> /dev/null || </span>exit</span> 1
</span></code></pre>
In summary, this git hook builds the site (with Zola) and then checks if any git diff is detected. If there is a git diff (or new, un-tracked file), the hook will prevent the git push</code> from running.</p>
As you might notice, this script depends on make</code>. To build the website, I have a Makefile target (which will be discussed soon).</p>
Docker Image</h3>
Next, rather than install the zola</code> binary on my base system, I decided to create a docker image that contains Zola. So, I now have a portable means to generate the site. In the future, I could potentially add some sort of continuous deployment automation to regenerate the site on every git push using this docker image. Additionally, the docker image locks Zola at a specific version (which I can be conscientious about upgrading).</p>
Here is my Zola docker image: https://github.com/0xC45/zola-docker</a>.</p>
Makefile</h3>
Lastly, I use a Makefile to build the site. Because I use a docker image to run Zola, some of the commands are quite complicated. Particularly, it was somewhat difficult to set up UID/GID mapping and port binding. Using a Makefile documents the commands in code and saves me from having to remember them. Here is my Makefile:</p>
.PHONY</span>: </span>all
</span>all</span>:
</span>	</span>PROJECT_ROOT</span>="</span>$$(</span>git rev-parse --show-toplevel</span>)</span>" && \
</span>	</span>docker</span> run \
</span>	  --rm </span>\
</span>	  -it </span>\
</span>	  -u </span>$$(</span>id -u </span>$${</span>USER</span>})</span>:</span>$$(</span>id -g </span>$${</span>USER</span>}) </span>\
</span>	  -v </span>"</span>$${</span>PROJECT_ROOT</span>}</span>:/site</span>" \
</span>	  zola:v0.11.0 \
</span>	  bash</span> -c </span>'</span>cd /site && zola build -o docs</span>'
</span>
</span>.PHONY</span>: </span>serve
</span>serve</span>:
</span>	</span>PROJECT_ROOT</span>="</span>$$(</span>git rev-parse --show-toplevel</span>)</span>" && \
</span>	</span>docker</span> run \
</span>	  --rm </span>\
</span>	  -it </span>\
</span>	  -u </span>$$(</span>id -u </span>$${</span>USER</span>})</span>:</span>$$(</span>id -g </span>$${</span>USER</span>}) </span>\
</span>	  -v </span>"</span>$${</span>PROJECT_ROOT</span>}</span>:/site</span>" \
</span>	  -p</span> 127.0.0.1:1111:1111 \
</span>	  zola:v0.11.0 \
</span>	  bash</span> -c </span>'</span>cd /site && zola serve -i 0.0.0.0</span>'
</span>
</span>.PHONY</span>: </span>clean
</span>clean</span>:
</span>	</span>rm -rf</span> docs/
</span></code></pre>
There are three main targets: all</code>, serve</code>, and clean</code>.</p>

all</code>: This target generates the static site.</li>
serve</code>: This target runs a "development" server on my local machine, allowing me to preview changes.</li>
clean</code>: This target deletes the directory containing the generated static site.</li>
</ul>
Conclusion</h2>
So, there you have it. These are my custom workflow improvements for using the Zola static site engine. So far, Zola has been a fantastic utility for generating my blog site. Of course, it does not have all the features of other popular static site generators, but it's perfect for my use case. It's simple, easy to use, fast, and capable. I definitely recommend checking it out.</p>


OpenSSL Certificate Authority
2020-05-24T00:00:00+00:00
Overview</h2>
At this point, HTTPS (HTTP encrypted with SSL/TLS) is nearly ubiquitous across the internet. You could say that any website that doesn't use HTTPS is behind the times. However, encrypting internet communications only achieves privacy from snooping third parties. In order to prevent "man in the middle" attacks, where an imposter pretends to represent the website you're trying to visit (and tricks you into giving them your passwords, secret data, etc.), it's also necessary to ensure that you're actually communicating with the website that you think you're communicating with. In other words, there needs to be a system in place that enables you to verify the identity of every website that you visit. The current system used on the internet involves certificates (objects that "prove" the identity of a website) and certificate authorities (entities that you trust).</p>
Motivation</h3>
On my home network, I run a few HTTPS services for miscellaneous things. In the past, I have generated a one-off, "self-signed" certificate for each of these services and clicked through the browser warning about the untrusted, self-signed certificate that every service presented.</p>
However, the browser warning should not be taken lightly. If, every time, I blindly click through the warning about the self-signed certificate (without actually checking that the certificate matches what I would expect), then I am vulnerable to a man in the middle attack. If I blindly trust every certificate, there is no difference between a valid and an invalid certificate.</p>
In order to solve this problem, I created a certificate authority for my internal home network HTTPS services. By configuring my browser to trust my certificate authority, the warnings disappear (as long as the certificates presented are actually valid). Now, any browser warning is an actual cause for concern (as it should be).</p>
Originally, I considered taking this project on for security reasons, but quite honestly, the threat model that accounts for the presence of an actual man in the middle attack within my internal home network is quite dubious. More realistically, I learned a lot with this project and (here's the real benefit) now I no longer need to click through annoying browser warnings whenever I visit the HTTPS services on my home network. Additionally, if I ever expose any of my services on the public internet, I could continue to use my personal certificate authority to enable HTTPS.</p>
How Does it Work?</h3>
When I browse to a website, how does my browser know that I am actually communicating with that website (and not someone else pretending to be that website)? The answer lies in the root certificates that are trusted by my browser.</p>
By default, most browsers trust a number of root certificates. These root certificates are owned and managed by organizations who serve as "certificate authorities". Certificate authorities approve and revoke certificates. Supposedly, certificate authorities perform their due diligence to ensure that they only approve and sign certificates when the entity requesting the certificate is the actual owner of the website.</p>
It is (theoretically and/or practically) impossible for someone to forge a signed certificate without a copy of the certificate authority private key. So, when my browser verifies a website's certificate, it checks that the certificate presented by the website is "signed" by a root certificate that the browser trusts. As long as a trusted root certificate authority approved and signed the website's certificate, then my browser trusts the website. Now, the browser warnings about my one-off, self-signed certificates make sense. The browser warns whenever it encounters a certificate that was not signed by a trusted root certificate.</p>
</p>
However, in reality, it's slightly more complicated than the picture above. In most cases, there are probably multiple certificates that form a chain back to the root certificate. For example, the certificate from the website would be signed by an "intermediate" certificate authority, which is then signed by a root certificate authority. As long as the chain of signed certificates ends in a root certificate that my browser trusts, the website is trusted.</p>
</p>
So, with that background information, I can describe this project in a little more detail. Using the OpenSSL free cryptography software, I created my own root certificate and used that root certificate to sign a number of leaf certificates for the various services running on my internal home network. Therefore, I am now acting as my own certificate authority. Next, I configured my browser to "trust" my personal root certificate. Now, whenever I browse to any of my internal HTTPS services, my browser no longer warns about the certificate because I have made it become trusted by my browser.</p>
</p>
Process</h2>
Standing up a personal certificate authority does not require a ton of work per se. It requires running only a handful of different commands. Every step can be performed with the openssl command line utility. However, openssl is a complicated program with a steep learning curve. In addition to the dozens of sub-commands and command line flags, the program reads a rather large configuration file for instructions that affect its behavior.</p>
After quite a bit of experimentation and documentation reading, I created a (hopefully) suitable configuration file for the purposes of my personal CA. First, I will explain my configuration file. Then, I will demonstrate the few commands needed to generate a root certificate and sign a leaf certificate.</p>
1. Setup Config File</h3>
By reading the default openssl config file (located at /etc/ssl/openssl.cnf</code> on my system) and the openssl manual pages related to certificate requests and authorities (req</a>, ca</a>, and x509v3_config</a>), I learned about the configuration options and their meanings. Then, through some experimentation (trial and error), I made a basic openssl config file.</p>
Request Configuration</h4>
[ req ]
</span>string_mask = utf8only
</span>prompt = no
</span>distinguished_name = req_distinguished_name
</span></code></pre>
The "req" section configures the behavior of the req sub-command and therefore affects how openssl generates certificate requests (both CA certificate requests and leaf certificate requests).</p>

string_mask = utf8only</code> masks the request to produce only utf8 characters. This is the recommended setting (according to the openssl docs, "this is the PKIX recommendation in RFC2459 after 2003").</li>
prompt = no</code> disables "interactive mode". The utility will not prompt for the DN (distinguished name) values on the command line interactively. Instead, the "distinguished_name" config option specifies a config section that contains the DN values to include in the request.</li>
distinguished_name = req_distinguished_name</code> specifies the section containing the DN values. So, let's take a look at the "req_distinguished_name" section next.</li>
</ul>
[ req_distinguished_name ]
</span>C = US
</span>ST = Colorado
</span>L = Denver
</span>O = 0xC45
</span>CN = Jason Vigil
</span>emailAddress = jason@0xc45.com
</span></code></pre>
The "req_distinguished_name" section specifies the DN (distinguished name) values for my certificate requests. Here, I give some information about where I am located (my country, state, and locale), my "organization name", my common name, and my email. The CA copies this information from certificate requests to signed certificates. Then, anyone can inspect a certificate and identify who it belongs to. Although, for a personal certificate authority, these values may not matter all that much.</p>
CA Configuration</h4>
[ ca ]
</span>default_ca = ca_default
</span></code></pre>
The "ca" section configures the openssl "ca" sub-command. This section affects how the certificate authority behaves when signing certificate requests. It contains only one config value. The default_ca</code> option sets the default section to use for the CA configuration. This value may be overridden on the command line, causing openssl to utilize a different section for configuration. However, for my purposes, I only need one type of CA configuration. So, the ca_default</code> section contains most of the configuration for my CA.</p>
[ ca_default ]
</span>dir = ./ca
</span>certificate = $dir/ca.cert.pem
</span>private_key = $dir/private/key.pem
</span>new_certs_dir = $dir/certs
</span>database = $dir/index.txt
</span>serial = $dir/serial
</span>
</span>name_opt = ca_default
</span>cert_opt = ca_default
</span>
</span>default_days = 30
</span>default_md = sha256
</span>copy_extensions = copy
</span>unique_subject = no
</span>preserve = no
</span>policy = policy_match
</span></code></pre>
This is the largest section in my config file (and, this is a super simple CA configuration). With additional features (OCSP, certificate revoke capabilities, etc), it could be much more complicated.</p>


The first group of configuration options refer to the CA directory structure. They specify the locations of important files, like the CA cert, private key, etc. These settings must match the directory structure on disk where the utility runs.</p>
</li>

The next two options (name_opt</code> and cert_opt</code>) configure how certificates are displayed by the openssl command line utility. The ca_default setting directs the openssl command line utility to print in the default format whenever instructed to output certificate information. I don't have any reason to change this default behavior.</p>
</li>
</ul>
The following options affect the behavior of the CA when signing certificate requests.</p>


default_days = 30</code> gives new certificates a lifespan of 30 days (by default). After 30 days from the time of signing, a certificate becomes invalid. It is possible to override this value on the command line with the "-days" flag.</p>
</li>

default_md = sha256</code> sets the default message digest for signing the certificate requests to sha256. Rather than use the default value (which leaves it up to the implementation), I decided to manually set the value to sha256. On one of my machines, I noticed the implementation used sha1 as the default. I opted to override the default in order to standardize and ensure the use of the newer sha256 algorithm.</p>
</li>

copy_extensions = copy</code> copies extensions from the certificate request (that aren't already present) to the signed certificate. This setting allows the certificate requester to specify the extensions they want applied to the signed certificate. Later on, you will see that I take advantage of this setting for every leaf certificate request to specify an extension containing a "subjectAltName" value. The CA copies the extension to the signed certificate because of this configuration setting.</p>
</li>

unique_subject = no</code> allows multiple signed certificates to have the same subject. The documentation recommends this setting in order to make CA certificate roll-over easier. I'm not sure that it will ever matter for my purposes, but I couldn't see the harm in allowing multiple certificates with the same subject, so I went with the recommended value.</p>
</li>

preserve = no</code> is a fairly confusing option. I think that it was originally intended to ensure that the ordering of the fields in the DN section remains consistent for all signed certificates. However, confusingly, it also means that any fields present in the certificate request DN that are not present in the CA policy (which we'll discuss next) are silently omitted in the signed certificate.</p>
</li>

policy = policy_match</code> refers to yet another section in the configuration file that sets some basic validation policies for certificate requests. So, let's look at that section now.</p>
</li>
</ul>
[ policy_match ]
</span>countryName = match
</span>stateOrProvinceName = match
</span>organizationName = match
</span>commonName = match
</span>emailAddress = match
</span></code></pre>
When the CA uses this policy, it enforces a highly restrictive set of rules for the DN values of certificate requests: all certificate requests must contain the exact same DN values as the CA certificate. Otherwise, the CA will refuse to sign the request. This is fine for my purposes because I am the only user of my CA. Every certificate request that I want to sign will have a matching DN section anyway.</p>
There are several values allowed for the fields in this section. Rather than match</code>, one could enforce that a certain value is supplied</code>. Or, it could be set to optional</code>. Also, remember, with the preserve = no</code> setting in the CA configuration section, any field not specified in the policy section is silently omitted in the signed certificate.</p>
CA Certificate Configuration</h4>
[ ca_extensions ]
</span>basicConstraints = critical,CA:true,pathlen:0
</span>subjectKeyIdentifier = hash
</span>authorityKeyIdentifier = keyid:always
</span>keyUsage = keyCertSign
</span></code></pre>
This section specifies additional configuration (beyond the "ca_default" section) for producing a CA certificate. When creating a CA certificate with the "openssl ca" command, I manually include this section with the "-extensions" flag.</p>


basicConstraints = critical,CA:true,pathlen:0</code> sets the configuration for the multi-valued "basicConstraints" extension using "short form" syntax.</p>

critical</code> makes "basicConstraints" a critical extension because it affects important behavior. Therefore, a certificate using system that does not recognize the "basicConstraints" extension must reject the certificate rater than potentially use it incorrectly.</li>
CA:true</code> configures the "ca" utility to sign requests and produce CA certificates. Certificates that are signed with this setting enabled may be used to sign requests to produce new certificates.</li>
pathlen:0</code> limits the capabilities of certificates that are signed with this setting enabled. Certificates that are signed with this setting enabled can only sign and produce "leaf" certificates. They cannot sign and produce additional CA certificates.</li>
</ul>
</li>

subjectKeyIdentifier = hash</code> instructs the utility to hash the CA's public key to produce the subject key identifier. All signed certificates refer to this hashed value in their authority key identifier section. This allows an application to determine the certificate authority certificate that signed a particular leaf certificate.</p>
</li>

authorityKeyIdentifier = keyid:always</code> configures the authority key identifier to equal the subject key identifier of the parent certificate. For the self-signed CA certificate (where there is no parent certificate), this value equals the subject key identifier.</p>
</li>

keyUsage = keyCertSign</code> defines how the signed CA certificate will be used. In my case, I plan to use the CA certificate only for signing other certificates.</p>
</li>
</ul>
Leaf Certificate Configuration</h4>
[ leaf_extensions ]
</span>basicConstraints = CA:false
</span>subjectKeyIdentifier = hash
</span>authorityKeyIdentifier = keyid:always
</span>keyUsage = nonRepudiation,digitalSignature,keyEncipherment
</span></code></pre>
This section specifies additional configuration (beyond the "ca_default" section) for producing a leaf certificate. When creating a leaf certificate with the "openssl ca" command, I manually include this section with the "-extensions" flag.</p>


basicConstraints = CA:false</code> means the leaf certificate cannot be used to sign other certificates.</p>
</li>

subjectKeyIdentifier = hash</code> instructs the utility to hash the request public key to produce the subject key identifier. This allows an application to verify the public key associated with a particular leaf certificate.</p>
</li>

authorityKeyIdentifier = keyid:always</code> configures the authority key identifier to equal the subject key identifier of the parent certificate. The authority key identifier extension is crucial to verify chains of certificates. Every leaf certificate needs an authority key identifier extension to identify the certificate authority that signed the leaf certificate.</p>
</li>

keyUsage = digitalSignature,nonRepudiation,keyEncipherment</code> specifies the valid uses for the leaf certificate. I use my leaf certificates to enable HTTPS services on my network.</p>
</li>
</ul>
2. Generate Root Certificate</h3>
So, after creating the openssl config file, let's use it to make a self-signed certificate authority certificate. In order to create a self-signed root certificate, we first need to generate a private key. Then, we use the key to create a certificate request. Lastly, we self-sign the certificate request to produce a root certificate. With openssl, it's possible to perform all three of these steps with one command, but I decided to break it apart in order to focus on the individual steps.</p>


Setup initial directory structure:</p>
mkdir -p</span> ca/certs ca/private ca/reqs
</span>touch</span> ca/index.txt
</span>echo </span>"</span>1000</span>" > ca/serial
</span></code></pre>
My openssl config file configures the utility to expect a particular directory structure. It is based on the directory structure used by the example openssl CA.pl</a> script. There are three directories:</p>

ca/certs</code>: for signed certificates</li>
ca/private</code>: for the CA private key</li>
ca/reqs</code>: for leaf certificate private keys and requests</li>
</ul>
In addition, two initial files are created:</p>

ca/index.txt</code>: to be used as a text database of all signed certificates</li>
ca/serial</code>: contains the next serial number to use when signing a certificate</li>
</ul>
</li>

Generate private key:</p>
openssl</span> genrsa</span> -out</span> ca/private/key.pem 8192
</span></code></pre>
This will generate an RSA key that is 8192 bits long.</p>
</li>

Create certificate request:</p>
openssl</span> req \
</span>    -new </span>\
</span>    -config</span> openssl.cnf \
</span>    -key</span> ca/private/key.pem \
</span>    -out</span> ca/ca.req.pem
</span></code></pre>
This creates a new certificate request using the config file "openssl.cnf" (created before) and the CA private key from the previous step. The resulting certificate request is written to "ca/ca.req.pem".</p>
</li>

Self-sign certificate request:</p>
openssl</span> ca \
</span>    -selfsign </span>\
</span>    -config</span> openssl.cnf \
</span>    -extensions</span> ca_extensions \
</span>    -days</span> 365 \
</span>    -keyfile</span> ca/private/key.pem \
</span>    -in</span> ca/ca.req.pem \
</span>    -out</span> ca/ca.cert.pem
</span></code></pre>
This command "self-signs" the certificate request. It adds the extensions in the "ca_extensions" section of the config file to the certificate. It overrides the config value "default_days" and makes the certificate valid for 365 days. The certificate is signed with the CA's own private key. This is why it's called a "self-signed" certificate. The resulting root certificate is written to "ca/ca.cert.pem".</p>
</li>
</ol>
3. Generate Leaf Certificates</h3>
After generating a root certificate, we can use it to sign leaf certificates. This process closely resembles the steps required to produce a self-signed root certificate. First, we need to generate a private key. Then, we use the key to create a certificate request. Then, we sign the certificate request with the certificate authority private key to produce a leaf certificate. Lastly, we combine the root certificate and the leaf certificate into a single file to "chain" them together.</p>


Generate private key:</p>
openssl</span> genrsa</span> -out</span> ca/reqs/test.key.pem 8192
</span></code></pre>
This will generate an RSA key that is 8192 bits long.</p>
</li>

Create certificate request:</p>
openssl</span> req \
</span>    -new </span>\
</span>    -config</span> openssl.cnf \
</span>    -addext </span>"</span>subjectAltName=DNS:test.mydomain.com</span>" \
</span>    -key</span> ca/reqs/test.key.pem \
</span>    -out</span> ca/reqs/test.req.pem
</span></code></pre>
This creates a new certificate request using the config file "openssl.cnf" (created before) and the private key from the previous step. It adds the "subjectAltName" extension to specify the DNS name for the service that will use the leaf certificate. The resulting certificate request is written to "ca/reqs/test.req.pem".</p>
</li>

Sign certificate request:</p>
openssl</span> ca \
</span>    -config</span> openssl.cnf \
</span>    -extensions</span> leaf_extensions \
</span>    -keyfile</span> ca/private/key.pem \
</span>    -in</span> ca/reqs/test.req.pem \
</span>    -out</span> ca/reqs/test.cert.pem
</span></code></pre>
This command signs the certificate request. It adds the extensions in the "leaf_extensions" section of the config file to the certificate. The certificate is signed with the CA private key. The resulting root certificate is written to "ca/reqs/test.cert.pem".</p>
</li>

Combine root and leaf certificates:</p>
cat</span> ca/reqs/test.cert.pem ca/ca.cert.pem > test.cert.pem
</span></code></pre>
Here, we combine the leaf certificate and the root certificate to produce a certificate "chain" (of length two). Any application that receives this chain can verify that the leaf certificate was signed by the private key associated with the root certificate.</p>
</li>
</ol>
Disclaimer and Best Practices</h2>
Of course, the certificate authority described in this blog post should not be used for production in corporate networks or anywhere where stuff actually matters. My personal certificate authority omits a couple of features considered to be best practices. Here are a couple features that real-world CAs have and my reasoning for not including them:</p>


Best practices advise utilizing "intermediate" CA certificates to form a certificate chain of length 3 (at minimum). The root certificate private key should be kept highly protected. Therefore, the root certificate private key should be rarely used only when it's necessary to sign additional intermediate CA certificates or to revoke compromised intermediate CA certificates. The intermediate CAs can be treated as slightly more disposable and their private keys will sign all leaf certificates.</p>
This pattern is considered a best practice because it's a big deal if a root certificate private key is compromised. Every browser that previously trusted the root certificate would need to be updated. It's embarrassing for the certificate authority and will cause people to question their overall security.</p>
</li>

Real certificate authorities have the ability to revoke certificates that they previously signed. In the real world, should a certificate private key become compromised, it would be necessary to revoke the certificate and provide a means for users to check the list of revoked certificates.</p>
</li>
</ul>
After considering my use case, I decided that I don't need these features. It's unlikely that any of my certificate private keys will ever become compromised because none of the services using them are accessible over the public internet. Additionally, should I ever want to roll my certificates, it wouldn't be a huge burden to recreate all of my certificates (including the root certificate) and update the root certificate in my browser. I am only one person. On a large corporate network, this would be onerous.</p>
Conclusion</h2>
This project has been quite a journey. Before beginning, I had a fuzzy idea of how certificates worked. Now, I understand in much greater detail how the certificate "chain of trust" works and how browsers are able to verify the identity of websites. Also, I am more capable of using the openssl utilities. I have learned a lot.</p>
However, on some level, I feel like I have only started to scratch the surface. The openssl req/ca utilities have a lot of complexity that enables many use cases beyond my simple example. It surprised me that certificates can actually contain a seemingly arbitrary number of (potentially custom) extensions. There are certainly numerous uses for certificates and various extensions that I still don't know about.</p>
Regardless, my home network now benefits from creating this simple CA. By now, I am somewhat tired of reading through the openssl manual pages and the X.509 certificate RFC. Fortunately, this is a good stopping point. There are no more browser warnings. I have improved my home network security. Time to close the books on this one... for now.</p>
Resources</h2>

https://www.ietf.org/rfc/rfc3280.txt</a></li>
https://www.openssl.org/docs/man1.1.1/man1/req.html</a></li>
https://www.openssl.org/docs/man1.1.1/man1/ca.html</a></li>
https://www.openssl.org/docs/man1.1.1/man5/x509v3_config.html</a></li>
https://www.openssl.org/docs/man1.1.1/man1/CA.pl.html</a></li>
</ul>


OpenBSD Home Router
2020-04-25T00:00:00+00:00
Overview</h2>
Recently, I made a home router from scratch using OpenBSD 6.6</a>, without installing any additional packages, using only what comes with the basic OS installation. Originally, before deciding to "do it from scratch", I had a goal to make a router using open source software in order to improve my network security. After looking at some popular open source firewall and routing projects (mainly pfSense</a> and OPNSense</a>), I finally decided to build my own. pfSense and OPNSense both seem like decent software (and I have successfully used both in the past), but this time, I wanted to "do it the hard way" and learn about the services that make up a typical router. Here are some of the cool features that my custom device currently has:</p>

It's almost fully open source, down to the BIOS and firmware. Unfortunately, the hardware isn't open source.</li>
It ensures that every DNS request leaving my network is encrypted.</li>
It caches DNS lookups for every device on my network, improving request speeds.</li>
It supports custom local network DNS entries, allowing me to refer to the various services on my network using memorable names, rather than IP addresses.</li>
</ol>
Of course, because this device is configured and built from scratch, the sky is the limit in terms of potential features and improvements. In the future, I may add improvements such as a VPN server or metrics reporting / analytics.</p>
Before we begin, because I can't really claim to know what I'm doing (I'm not a networking / firewall expert), I must make a disclaimer. This is a toy project. You probably shouldn't use this in production. However, having said that, I have been using this setup (in "production") for several months now and it has been stable. I haven't noticed any internet issues caused by this appliance. In addition, it seems quite secure. OpenBSD has a reputation for being a secure OS and I made every effort to configure the various services correctly. If you notice any mistakes with this configuration (or potential improvements to make), please let me know! Anyway, let's dive into the details.</p>
Hardware (apu2)</h2>
First, I needed an actual machine for my home network appliance. After considering the various options (purchase a device, build something myself, use a virtual machine, etc.) I decided to use an apu2</a>. It is a low-power, relatively inexpensive yet performant solution, which makes it ideal for this kind of application. In addition, it uses an open source BIOS (SeaBIOS</a>) and firmware (coreboot</a>). I went with a model that has a quad-core processor, 4GB memory, and 3 separate gigabit NICs. In addition, I purchased a 16GB M-SATA SSD (for the main OS installation), a 4GB SD (for a utility OS installation), a case, and a serial cable (the apu2 does not have a port for graphics output). The total cost was roughly $160.</p>
After the device arrived, the first challenge was connecting to it. Ok, it wasn't actually that challenging. I connected to the apu2 with my OpenBSD netbook and the serial cable:</p>
cu -l /dev/cuaU0 -s 115200
</span></code></pre>
No matter which software you use to connect to the apu2 over serial, the important setting is the default baud rate, 115200.</p>
Firmware (coreboot)</h2>
After booting up the apu2, I noticed that the BIOS was a bit out of date. It was probably flashed with the current BIOS version at the time of manufacturing, which was likely a while before it ended up in my hands. So, I needed to upgrade the BIOS. The official instructions</a> describe a method to update the BIOS using a PC Engines custom TinyCore Linux distribution. However, since I was already planning to make two different boot disks, one for the router OS and one for a "utility" OS, I decided to setup the utility OS and make it capable of flashing the BIOS.</p>
Utility OS (Debian)</h3>
Given that my apu2 device has two disks, it made sense to create a separate OS installation on the second disk. In addition to being capable of flashing the BIOS, I envision the second "utility" OS as a backup plan, in case I ever misconfigure the main router OS and want to attempt to debug network issues in a fresh environment. I would only boot into the utility OS for special situations. Generally, the device will always be running the main router OS.</p>
For the "utility" OS, I decided to use Debian Linux, because I like Debian. So, I made a Debian USB installer and booted the apu2 from it. There are a few important steps to follow in order to boot the Debian installer into a serial tty (thanks to TekLager</a> for the post on how to boot Debian on an apu2).</p>

Highlight the "Install" boot option (not "Graphical Install")</li>
Press <tab></code> to edit the boot entry</li>
Remove vga=xxx</code> to disable graphical output</li>
Add console=ttyS0,115200n8</code> to enable the serial tty</li>
Press <enter></code> to boot</li>
</ol>
Then, I walked through the regular Debian installation. However, because the install target disk is pretty small (4GB), the installer couldn't auto-partition the disk. So, it was necessary to manually setup disk partitions. Here are the settings that I used:</p>

200 MB primary ext4 partition (bootable, relatime flag set, mount point: /boot)</li>
3.8 GB primary crypto partition</li>
Then, after setting up the crypto partition (erase disk, set password)

3.8 GB primary ext4 partition (mount point: /)</li>
</ul>
</li>
</ul>
In order to boot the new Debian installation for the first time, I had to manually edit the boot entry. Like before, add console=ttyS0,115200n8</code> to boot into a serial tty. Then, after booting and logging in as root, I configured grub so that it would no longer be necessary to manually edit the boot entry. To do that, edit /etc/default/grub and change the following settings:</p>
GRUB_CMDLINE_LINUX='console=ttyS0,19200n8'
</span>GRUB_TERMINAL=serial
</span></code></pre>
Finally, run update-grub</code> to regenerate the grub boot menu. At this point, the Debian "utility" OS install is complete and it is time to update the BIOS.</p>
Firmware Update</h3>
Updating the BIOS is fairly simple. First, install the flashrom utility. It's available in the Debian package repositories.</p>
apt install flashrom
</span></code></pre>
Then, download the latest mainline version of the firmware from https://pcengines.github.io/</a>, write the file to a USB, and mount the USB on the apu2. To flash the firmware (assuming the file is named coreboot.rom), run:</p>
flashrom -w coreboot.rom -p internal
</span></code></pre>
Then, reboot. For more information on flashing the apu2 firmware, check out the docs</a>.</p>
OS (OpenBSD)</h2>
Ok, now it is time to start talking about the actual router OS. For this, I chose OpenBSD. OpenBSD is a popular flavor of BSD that's known for security. Given BSD's general reputation as a networking appliance operating system, OpenBSD seemed like a good fit for the job.</p>
Below (in exhaustive detail) are my installation instructions for OpenBSD 6.6. I decided to make an encrypted disk (why not?) and a custom partitioning strategy. Refer to the OpenBSD docs for additional information.</p>


Create an OpenBSD 6.6 installer USB drive.</p>
</li>

Boot the apu2 from the OpenBSD installer USB drive.</p>
At the boot></code> prompt, configure and enable a serial tty by entering the following commands.</p>
stty com0 115200
</span>set tty com0
</span></code></pre>
Now, press enter at the boot></code> prompt to boot the installer.</p>
</li>

After the installer boots up, type s</code> to run a shell.</p>
</li>

Erase the target installation disk.</p>
To determine the identifier for the target installation disk, check dmesg</code> (In was sd0 in my case).</p>
cd /dev && sh MAKEDEV sd0
</span>dd if=/dev/urandom of=/dev/rsd0c bs=1m
</span></code></pre>
</li>

Setup the disk MBR.</p>
fdisk -iy sd0
</span></code></pre>
</li>

Create a RAID partition to use as an encrypted pseudo-device.</p>
Run the disk label editor.</p>
disklabel -E sd0
</span></code></pre>
In the disk label editor, enter the following commands to create a RAID partition over the entire disk.</p>
a a
</span><enter>
</span><enter>
</span>RAID
</span>p
</span>w
</span>q
</span></code></pre>
</li>

Create the encrypted pseudo-device and set the encryption password.</p>
bioctl -c C -l sd0a softraid0
</span># use the device identifier created in the previous command (sd3 for me)
</span>cd /dev && sh MAKEDEV sd3
</span></code></pre>
</li>

Clear the first megabyte of the new pseudo-device.</p>
If you're unlucky, the random data written to the device may look like a real disk header. Clearing out the first megabyte fixes this potential issue.</p>
dd if=/dev/zero of=/dev/rsd3c bs=1m count=1
</span></code></pre>
</li>

Return to the main installer menu.</p>
exit
</span></code></pre>
</li>

Type i</code> to run the installer.</p>
Terminal type? <enter> (the default seemed to work fine for me)
</span></code></pre>
Next, set the system hostname and configure the network interfaces.</p>
System hostname? firewall (in my case)
</span>Which nic to configure? em0 (this will be the WAN interface)
</span>IPv4 address? 192.168.0.2 (in my case)
</span>Netmask? 255.255.255.0 (in my case)
</span>IPv6 address? none (in my case)
</span>Which nic to configure? em1 (this will be the "prod" network interface)
</span>Symbolic hostname? <enter> (same as system hostname)
</span>IPv4 address? 192.168.1.1 (in my case)
</span>Netmask? 255.255.255.0 (in my case)
</span>IPv6 address? none (in my case)
</span>Which nic to configure? em2 (this will be the "dev" network interface")
</span>Symbolic hostname? <enter> (same as system hostname)
</span>IPv4 address? 192.168.2.1 (in my case)
</span>Netmask? 255.255.255.0 (in my case)
</span>IPv6 address? none (in my case)
</span>Which nic to configure? done
</span></code></pre>
Next, set the default route and configure DNS.</p>
Default route? 192.168.0.1 (in my case)
</span>DNS domain name? localdomain (in my case)
</span>DNS nameservers? 8.8.8.8 8.8.4.4 (for now)
</span></code></pre>
Next, there are some miscellaneous tasks: set the root password, enable ssh, setup serial console, create a user, and set your timezone.</p>
Password for root account? (something secure)
</span>Start sshd by default? yes (not necessary, but useful)
</span>Change default console to com0? yes
</span>Which speed should com0 use? 115200
</span>Setup a user? (choose a username)
</span>Full name? <enter>
</span>Password? (something secure)
</span>Allow root ssh login? no
</span>What timezone? (set your timezone)
</span></code></pre>
Next, partition your target installation disk (the encrypted pseudo-device).</p>
Which disk is the root disk? sd3 (pseudo-device from previous steps)
</span>Whole disk MBR? whole
</span>Disk partitioning? c (setup custom layout)
</span></code></pre>
Here are the commands I used to partition my disk.</p>
a a
</span><enter>
</span>6G
</span><enter>
</span>/
</span>a b
</span><enter>
</span>4G
</span><enter>
</span>a d
</span><enter>
</span>0.1G
</span><enter>
</span>/usr/local
</span>a e
</span><enter>
</span>4G
</span><enter>
</span>/var
</span>a f
</span><enter>
</span><enter>
</span><enter>
</span>/tmp
</span>p
</span>w
</span>q
</span></code></pre>
My disk ended up being partitioned as follows:</p>
#   size       offset     fstype   [fsize   bsize   cpg]
</span>a:  12594880   64         4.2BSD    2048    16384   1      # /
</span>b:  8402011    12594944   swap
</span>c:  31261898   0          unused
</span>d:  224896     20996960   4.2BSD    2048    16384   1      # /usr/local
</span>e:  8401984    21221856   4.2BSD    2048    16384   1      # /var
</span>f:  1622560    29623840   4.2BSD    2048    16384   1      # /tmp
</span></code></pre>
Finish partitioning disks.</p>
Which disk to initialize? done
</span></code></pre>
Before installing the sets, type !</code> to exit to a shell and determine the device identifier of the OpenBSD 6.6 installer USB drive. Then, return to the installer.</p>
!
</span>dmesg  # for me, the device identifier ended up being sd2
</span>exit
</span></code></pre>
Next, mount the OpenBSD 6.6 installer USB drive and load the sets.</p>
Location of sets? disk
</span>Already mounted? no
</span>Which disk contains the install media? sd2 (as just determined)
</span>Which partition has the install sets? <enter>
</span>Pathname to the sets? <enter>
</span></code></pre>
Next, select which sets to install and install them.</p>
Set name(s)? -game* -x* (no need for games or a gui)
</span>Set name(s)? done
</span>Continue without verification? yes
</span>Location of sets? done
</span></code></pre>
</li>
</ol>
Success! Reboot the device. Don't forget to run syspatch</code> after rebooting in order to apply the latest patches.</p>
Firewall (pf)</h2>
Now that we have an apu2 running the latest firmware and OpenBSD, it's time to turn this thing into a router. With OpenBSD, you don't even have to install anything extra in order to make this happen. Everything you need already comes with the basic OS installation.</p>
For my home network, I want two subnets, which I refer to as dev and prod. The dev subnet is an experimental and development zone where I can break things. The prod subnet contains the devices I use on a day-to-day basis. I want both the dev and prod subnets to be able to access the external internet, but I want to block communication between the two subnets. Devices in the dev subnet should not be able to communicate with devices in the prod subnet (and vice versa). Fortunately, the apu2 has three physical NICs. So, one NIC could be used for the WAN network, one NIC could be used for the dev network, and one NIC could be used for the prod network.</p>
To learn how to configure the pf firewall and make this setup a reality, I read the pf.conf man page</a> and the router tutorial</a>. There are three main differences between my configuration and the one described in the tutorial.</p>

My configuration has two subnets that are not allowed to talk to each other.</li>
My configuration prevents outgoing unencrypted DNS traffic.</li>
My router exists on a local network (behind my ISP-supplied modem/router) so I had to allow traffic destined to the gateway at 192.168.0.1.</li>
</ol>
Here is my /etc/pf.conf that achieves this desired configuration.</p>
# interfaces
</span>lo_if = "lo0"
</span>wan_if = "em0"
</span>prod_if = "em1"
</span>dev_if = "em2"
</span>
</span># cidr ranges
</span>prod_range = "192.168.1.0/24"
</span>dev_range = "192.168.2.0/24"
</span>
</span># setup non-routable address list
</span># note: since this firewall is behind a local network,
</span>#       do not include the default gateway in the table
</span>table <martians> { 0.0.0.0/8 10.0.0.0/8 127.0.0.0/8 169.254.0.0/16     \
</span>                   172.16.0.0/12 192.0.0.0/24 192.0.2.0/24 224.0.0.0/3 \
</span>                   192.168.0.0/16 198.18.0.0/15 198.51.100.0/24        \
</span>                   203.0.113.0/24 !192.168.0.1 }
</span>
</span># drop blocked traffic
</span>set block-policy drop
</span># set interface for logging
</span>set loginterface $wan_if
</span># ignore loopback traffic
</span>set skip on $lo_if
</span>
</span># normalize incoming packets
</span>match in all scrub (no-df random-id max-mss 1460)
</span># perform NAT
</span>match out on $wan_if inet from !($wan_if:network) to any nat-to ($wan_if:0)
</span>
</span># prevent spoofed traffic
</span>antispoof quick for { $wan_if $prod_if $dev_if }
</span>
</span># block non-routable traffic
</span>block in quick on $wan_if from <martians> to any
</span>block return out quick on $wan_if from any to <martians>
</span>
</span># block all traffic
</span>block all
</span># allow outgoing traffic
</span>pass out inet
</span># allow traffic from internal networks
</span>pass in on { $prod_if $dev_if } inet
</span># block traffic from prod <--> dev
</span>block in on $prod_if from $prod_range to $dev_range
</span>block in on $dev_if from $dev_range to $prod_range
</span># block outgoing unencrypted dns requests
</span>block proto { TCP UDP } from { $prod_range $dev_range } to any port 53
</span>pass proto { TCP UDP } from { $prod_range $dev_range} to self port 53
</span></code></pre>
Next, in order to perform NAT (to make this device an actual router), run the following:</p>
echo 'net.inet.ip.forwarding=1' >> /etc/sysctl.conf
</span></code></pre>
Finally, reboot with reboot -p</code>. Now, the router is functional and secured with the pf firewall. At this point, it will work as a minimum viable product. However, every device on the network will need to manually configure its own static IP address, subnet mask, gateway, and DNS server (because there is no DHCP service running to supply these configuration details).</p>
DHCP (dhcpd)</h2>
DHCP is a service that (among other things) gives IP addresses to the devices on your network. So when a device joins the network, it will be given an IP address by the DHCP server running on the router. The DHCP server bundled with OpenBSD 6.6 is dhcpd.</p>
Most devices, upon joining the network, will be given an IP address from within a specified IP range. They could potentially receive any IP address in this range. However, I wanted some devices to be treated specially and always be given the same IP addresses by dhcpd. That way, I can rely on those devices to have predictable IP addresses. It is simpler and easier to define "static" IP addresses all in one place (on the router) rather than configure static IP addresses on each individual device. This way, every IP on my network is defined in one place, on the router. It will be obvious if two devices are configured to have the same static IP (a classic mistake).</p>
In addition to defining the IP address allocations in my network, I configured dhcpd to inform devices on my network of the preferred DNS server for the network, the router itself. We haven't set this up yet, but the router will also function as a caching DNS server.</p>
Here is an example /etc/dhcpd.conf file:</p>
# prod network
</span>subnet 192.168.1.0 netmask 255.255.255.0 {
</span>        option routers 192.168.1.1;
</span>        option domain-name-servers 192.168.1.1;
</span>        range 192.168.1.100 192.168.1.149;
</span>        host special-device-1 {
</span>                fixed-address 192.168.1.2;
</span>                hardware ethernet 00:00:00:00:00:00;
</span>        }
</span>}
</span># dev network
</span>subnet 192.168.2.0 netmask 255.255.255.0 {
</span>        option routers 192.168.2.1;
</span>        option domain-name-servers 192.168.2.1;
</span>        range 192.168.2.100 192.168.2.199;
</span>        host special-device-2 {
</span>                fixed-address 192.168.2.2;
</span>                hardware ethernet 11:11:11:11:11:11;
</span>        }
</span>}
</span></code></pre>
This /etc/dhcpd.conf file configures the dhcpd server to hand out IP addresses for the dev and prod networks from within the specified ranges. In addition, it informs devices of the local DNS server (not yet configured). It also configures two "special devices" that will always be given the same IP addresses. dhcpd identifies these two devices by their MAC addresses. For more information check out the dhcpd.conf man page</a>.</p>
To enable dhcpd on the em1 and em2 interfaces, run:</p>
rcctl enable dhcpd
</span>rcctl set dhcpd flags em1 em2
</span></code></pre>
Now, the DHCP server is running, automatically handing out IP addresses and network configuration details to new devices that join the network.</p>
DNS (unbound)</h2>
The last piece (for now) of this home router is DNS. Setting up a caching DNS server on the home router offers several benefits.</p>

DNS lookups, if they are already cached, will be quicker. The router will immediately reply with the answer. There will be no need to make a request to some external DNS server on the internet.</li>
By ensuring all outgoing DNS lookups are performed by the router, it is easy to enforce a standard of security / privacy. I have configured the DNS caching server running on the router to always encrypt outgoing DNS requests. Of course, any device on the network is free to use other DNS servers besides the router. However, the pf firewall configuration blocks outgoing requests on port 53, the port commonly used for unencrypted DNS.</li>
It is possible to configure custom DNS entries for the local network. The "special devices" configured in the DHCP server to always have the same IP addresses can be given DNS entries on the local network. For example, if I have a server running on my home network, I can give it a memorable DNS entry that will always resolve to its "static" IP address defined in the DHCP configuration.</li>
</ol>
Here is an example unbound config file (located at /var/unbound/etc/unbound.conf):</p>
server:
</span>        interface: 127.0.0.1
</span>        interface: 192.168.1.1
</span>        interface: 192.168.2.1
</span>        access-control: 127.0.0.0/8 allow
</span>        access-control: 192.168.1.0/24 allow
</span>        access-control: 192.168.2.0/24 allow
</span>        hide-identity: yes
</span>        hide-version: yes
</span>        do-not-query-localhost: no
</span>        tls-cert-bundle: "/etc/ssl/cert.pem"
</span>        local-data: "special-device-1.localdomain A 192.168.1.2"
</span>        local-data: "special-device-2.localdomain A 192.168.2.2"
</span>
</span>forward-zone:
</span>        name: "."
</span>        forward-tls-upstream: yes
</span>        forward-addr: 8.8.8.8@853
</span>        forward-addr: 8.8.4.4@853
</span></code></pre>
To enable the unbound DNS caching server, run:</p>
rcctl enable unbound
</span></code></pre>
Now, the DNS caching server is running. Devices that join the network will automatically use this DNS server (unless otherwise configured) because the DHCP server will inform new devices that this is the preferred DNS server for the network. Also, by using this DNS server, the custom local DNS entries will resolve properly. For example, when any device on the local network makes a DNS lookup for special-device-1.localdoman</code>, it resolves to 192.168.1.2. Lastly, all DNS lookups are cached by the unbound service. This will improve the latency of repeat DNS lookups.</p>
Conclusion</h2>
So, that's pretty much it. At this point, the device functions as a router, firewall, DHCP server, and caching DNS server. The software it runs is entirely open source. It maintains several custom DNS entries for services running on my local network. Every outgoing DNS request is guaranteed to be encrypted. For the past few months, I have used this device in my home network and it has been working great. It is secure, performant, minimal, and easy to maintain (only three config files).</p>
In the future, I will likely add more features to this device. It might be useful to add a VPN service in order to allow me to access my home network from anywhere on the internet. Also, it would be neat to setup some logging / metrics collection to analyze network traffic. However, at this point, all of the original project goals have been met. There are probably many easier ways to build a home router, but I learned a lot doing it this way. For now, I am quite happy with this device.</p>

0xC45

Digital Audio Synthesizer in Rust

Graphics</h3> Currently, the only job of the graphics thread is to create a window for the program, receive keyboard events, translate keyboard events to "midi" note on / off events, and send the midi events to the audio thread. It does not yet display a useful GUI for the synthesizer.</p> </p>

Next Steps</h2> There are many ways that I plan to improve this synthesizer:</p>

4x4 Macro Pad

Ansible-defined Homelab

Components</h2> So, without further ado, let's dive into each of the components that make up my homelab. For each component, I will describe the main utility it provides me, why I chose it, and any additional commentary that may be helpful.</p>

My Zola Workflow

My Zola Workflow</h2> Rather than repeat stuff you can find in the Zola documentation, in this blog post I will cover three of my personal "workflow hacks" for working with Zola. Hopefully at least a couple of these patterns are useful to you.</p>

OpenSSL Certificate Authority

OpenBSD Home Router

Components</h2>
So, without further ado, let's dive into each of the components that make up my homelab. For each component, I will describe the main utility it provides me, why I chose it, and any additional commentary that may be helpful.</p>

My Zola Workflow</h2>
Rather than repeat stuff you can find in the Zola documentation, in this blog post I will cover three of my personal "workflow hacks" for working with Zola. Hopefully at least a couple of these patterns are useful to you.</p>