That's all. Bye now.

For those who stuck around:

Custom Static Site Generator Part II

As explained in this post, this site is powered by my custom hacky SSG. So I had to do some more scripting to implement this new RSS feed generator. It's really simple as expected (and as the name implies), I just had to adjust some of my original code so that it could be reused, and fill in some XML templates:

cat <<-EOF
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
	<channel>
		<title>~jlucas/</title>
		<link>${url}/</link>
		<description>Posts by jlucas</description>
		<language>en-us</language>
		<lastBuildDate>$(date -Rd "${posts%%-*}")</lastBuildDate>
		<atom:link href="${url}/index.xml" rel="self" type="application/rss+xml" />
		$(items)
	</channel>
</rss>
EOF

This is the outer template. Mostly all constants except for the lastBuildDate tag, which I am formatting based on the date prefix of the latest post, which happens to be the first entry in the space separated $posts variable.

The template for the actual posts is expanded from the items function, which simply fills in another template in a loop:

for fname in $posts; do
	cat <<-EOF
	<item>
		<title>$(gettitle "${srcdir}/posts/${fname}")</title>
		<link>${url}/posts/${fname%md}html</link>
		<pubDate>$(date -Rd "${fname%%-*}")</pubDate>
		<guid>${url}/posts/${fname%md}html</guid>
		<description><![CDATA[
			$(tail +3 "${srcdir}/posts/${fname}" | render)
		]]></description>
	</item>
	EOF
done

The gettitle function was explained in part 1, and the render function simply wraps the code to preprocess and convert the markdown content to HTML.

Then just add it to the Makefile and it's done:

index.xml: $(POSTS) $(SCRIPTS)
	src/ssg/genrss.sh > $@

You can check out the full code here.

Expect a Part III whenever I manage to integrate some nice (static, server side) syntax highlighting to fix those ugly code blocks.

• I wrote the pacc password manager, inspired by pass.
• Unlike pass, pacc does not use public-key cryptography, which makes no sense to use when encrypting to yourself.
• Unlike pass, pacc uses an encrypted vault file which does not expose entry names in plain text.

Introduction

I had been using the pass password manager (aka password-store) for a few years, and it was great in terms of user experience. However it has some design flaws that impact security, which should be a primary focus when we're talking about a password manager. So I wrote pacc, which aims to keep the familiar user experience of pass, but not at the cost of security.

pacc is neither a fork nor a rewrite. While the CLI is inspired by pass, it was built from scratch, and functions entirely differently under the hood.

The Problem

While pass claims to be simple (which it is from the user's perspective), it is a shell script that relies on the old complex GPG. Even disregarding any flaws in GPG itself, it is just not the right tool for the job, because it uses public-key cryptography, which makes no sense in a password manager. Now let me give you a little cryptography crash course to show you why:

Cryptography 101

Let's say Alice wants to send Bob an encrypted message.

Using symmetric-key cryptography, Alice and Bob share a secret key, which is used for both encrypting and decrypting the messages. It is impossible for anyone to decrypt their messages without the key. But how do they establish a secret key? That's where public-key cryptography comes in.

With public-key cryptography, Alice and Bob have a public and a private key each. They can share their public keys over an insecure channel, and through some mathematical witchcraft, securely exchange a symmetric key for their chat session.

Public-key cryptography isn't stronger than symmetric-key cryptography. Quite the opposite, actually. In this case it is only used to solve the key exchange problem, after which a symmetric-key algorithm is used.

Getting back to pass

Do you see the problem here? A password manager is used to encrypt your passwords, so that they can only be decrypted by you. There are no other parties involved, meaning you are both Alice and Bob. With pass, you are using public-key cryptography to exchange a key with yourself! A chain is no stronger than its weakest link, and pass adds a weaker link for no good reason.

Encryption Coverage

Another problem is that pass stores each entry in a file, using the (unencrypted) file path as the entry name. There is no strict rule for how you should name your entries, but the recommended way is to use "the title of the website or resource that requires the password". You might also want to throw the username in there, or some other useful information. All of this is left exposed in plaintext in your file system, as well as other metadata such as timestamps.

The Solution

And so I wrote pacc, which solves the previously mentioned problems, has a similar CLI (including (pseudo-)directory operations), and is also faster and uses less disk space. How?

• Encryption/decryption is done using a symmetric key, derived from a passphrase. Key files are also supported. No silly key exchange involved.
• It stores all password entries (including names) in a single encrypted file (vault).
• It's written in C, uses OpenSSL for cryptography, and a simple custom vault format.

Why the name?

Because time spent naming it is time not spent developing it. Also because pass... but in C... whatever, let's go with pacc.

What will I miss from pass?

While some features might be added in the future, others are out of scope, due to unjustified complexity or reliance on pass's design flaws. Here are some examples:

• Anything that requires bypassing the pass script and accessing the files in ~/.password-store directly: Though that is convenient, it is based on the flaw of having plaintext entry names, and so pacc doesn't support it.
• Git integration: While you can version-control your vault, it isn't built into pacc, and it isn't possible to see which entries have changed (because they are all contained in one encrypted binary vault).
• Extensions: There is currently no extension support, though I plan on implementing some features from pass extensions, such as OTP support, either as built-ins, or compile-time options, or maybe suckless style patches. Suggestions and contributions are welcome.

Additionally, some features such as pass's QR code options weren't added since they can be easily achieved by piping the output of pacc to another program.

How to migrate?

To switch from pass to pacc, initialize a new vault using pacc init -i (omit -i for default parameters), then simply run the included pass2pacc script to import all your password-store entries.

How to use?

For most operations, if you've been using pass, you'll feel right at home. The biggest differences are in the init command, for obvious reasons. Run pacc help and pacc help SUBCOMMAND do learn more. Also there are bash and zsh completions.

Conclusion

pass is cool and all, but it puts UNIX philosophy above security. pacc aims to be as close to pass as possible without compromising security, though it ended up with many fundamental differences under the hood due to the fact that many advantages of pass depend on its design flaws.

Also, public-key cryptography is great when we need it. Not for storing passwords.

And it should go without saying but I mean no disrespect to the pass project and its contributors and users. Your threat model, your choice.

TL;DR: Your master key should be airgapped. All your keys should expire. You should have revocation certificates in case you lose your master key. You should back it up safely so you don't lose it.

This post assumes you know what PGP is and have a rough understanding of how public key cryptography works. Also it is based on this tutorial which you should read for more details.

Quick PGP Refresher

To understand what we'll be working with, here are the core concepts that you should understand:

• Master key: the key that you use to sign subkeys and identities;
• Subkeys: the keys that you use to encrypt/decrypt and sign/verify arbitrary data;
• Identities: names and email addresses associated with the master key.

Airgapped Master Key

Most of the actions that you do with PGP only require subkeys. You only really need your master key when you want to add new subkeys or identities, or change something about the existing ones.

That means you can (and should) keep only your subkeys on your day-to-day devices, and access the master key only on a secure isolated offline device. Once you are done with your master key stuff, you just export everything except the master key itself to a removable storage device and import it on your other devices. That way, if one of your devices gets compromised you can just revoke the affected subkeys, while the master key remains secure.

If you haven't done this with your current key, you might want to consider retiring it and starting fresh, generating a new key from the airgapped system.

Example Setup

Use an old SBC or laptop that you have lying around, that will never be connected to a network ever again. Run a live OS on it. You will need a persistent partition for storing the private master key, which could be on a USB stick or on the device itself, as long as it stays offline. Export the subkeys to a different USB stick. You should make backups of the master key, but be sure to only access them from the airgapped system.

In Practice

Alright, that sounds fun, but how do you do it? I'm assuming you know how to create a PGP key, so go ahead and do that on your airgapped system. After that, you'll want to export only the subkeys, which can be done with the command:

gpg --export-secret-subkeys -o secret-subkeys.gpg

Then you move secret-subkeys.gpg to your USB stick and import it normally on your other devices. Also you should export the public keys whenever you change identities or expiration dates or whatever.

Revocation Certificates

You should keep a few of these around in case you lose your master key. To generate them, run the following command from your airgapped system (replace $KEY with your actual key ID):

gpg --gen-revoke $KEY

In order to actually revoke the key, import the resulting certificate so that it is merged with your key. Then you need to publish it to a keyserver or share it in some other way so that people know it is revoked. Keep this certificate somewhere safe. Anyone with access to it can revoke your master key.

Rotating Keys

Don't hold on to your subkeys for eternity. It is good practice to rotate them every once in a while. For that, set them to expire, and generate new ones to replace them once they're approaching EOL. The lifetime of your keys will depend on your threat model. Rotating them more frequently is better for security, but it is very inconvenient.

As for the master key, things get a bit more complicated. Rotating a master key would mean revoking it and starting the whole process from scratch, having to send it to everyone and rebuild trust each time. So if you are confident that your airgapped system is truly airgapped, and that the key is too strong to have been cracked since it was created, then it might be best to keep it around. Either way, you should also set an expiry date on it, and extend it when needed instead of rotating. This will ensure the key eventually expires if you lose it or die or something.

Conclusion

Airgapping your master key greatly increases security, at the cost of having to boot into the airgapped system every now and then to edit and export stuff. I hope this made you rethink your PGP OPSEC. Read the linked tutorial if you want an actual step-by-step guide.

This is Part 2 of my previous article about why phones suck, and I encourage you to read Part 1 before taking any of this as advice, since this is not quite the PinePhone review you are looking for. A lot of what I say here about the PinePhone applies to any phone running any of the Linux distros you would typically run on a PinePhone.

Introduction

The TL;DR for Part 1 is that it's bad that society expects you to carry a phone all the time and install a bunch of proprietary apps for things that shouldn't even require electricity. Therefore the answer for the title is: no, the PinePhone won't magically solve all of society's problems, but it can be quite an upgrade in terms of freedom and privacy if you are not expecting to have full spyware compatibility.

Some Positive Notes

I got carried away and ended up making this too much of a Part 2 on hating phones instead of focusing on the PinePhone, so let's insert some nice things here before it all gets ugly.

Linux phones get it right when it comes to making mobile-friendly interfaces: They run full desktop Linux systems, with a friendly mobile interface on top (optional). You still have access to all the desktop stuff you could possibly need, including root access, terminal access (including Linux virtual terminals), any desktop app that is totally not meant for a phone, SSH daemon, partitioning and mounting internal/removable storage, literally everything. Most of the "mobile apps" shipped with these distros are just desktop apps that adapt to small screens. This shows that it is possible to have a functioning mobile device without all the dumb Android limitations. Phones are computers.

Another great thing is that the PinePhone can boot from a microSD card out of the box. That means you can easily switch the operating system without having to sacrifice your child into a volcano and do the bootloader unlock dance.

My Setup

To give you an idea of the freedom you get, here is how I have my PinePhone set up:

• OS: Arch Linux ARM. There is a community maintaining a mobile friendly version that just works, but I installed it the Arch way instead;
• Window Manager: dwm. Yep, the suckless one. On a phone. To be honest I didn't think it would be usable at first, but a project called sxmo went and did it before me, and I took some inspiration and made my own build;
• Phone stuff: for calls and SMS, I wrote my own scripts that interface with ModemManager.

That's basically it, I use it as if it were a desktop and it works. Of course it is very limited by the form factor, but it's the path I took. I just do most stuff on the terminal and launch graphical programs with dmenu. To make it suck a little less, I make use of many single-letter aliases and scripts.

The point here is, although I wouldn't really recommend it, you are free to do crazy stuff like this.

Signal

There is a lot I dislike about the Signal messenger, but that's not for this post.

There are several ways to use Signal on a Linux phone. There are third party clients such as Axolotl, which support registering a new account, but using a phone as the master device is dumb (I still hate phones, remember?). I use signal-cli on the desktop for that, and on the PinePhone I just link the desktop app to it. Once again, yep, the Signal-Desktop app, on a phone. It's... usable.

Unfortunately there is no official Linux ARM support from Signal, so I use this unofficial build instead. Use it at your own risk.

Waydroid

It is possible to run Android apps on the PinePhone through Waydroid. But should you? I think that defeats the purpose of using a Linux phone. If you are going to run Android on top of it, you might as well run it natively without the extra complexity and overhead. Also the main use case for it would be supporting proprietary spyware that you shouldn't be running anyway.

Once again, this is not a review. I personally don't use Waydroid. Some people say it works great. Good for them. That's not the point.

The Paradox

This is basically how being a phone-hating-FOSS-enthusiast-PinePhone-owner feels:

• I want to build stuff from scratch and be in control of my device;
• If you've been paying attention, you know I don't particularly like phones;
• Therefore I don't feel like wasting time improving my phone;
• I end up with a worse experience than I would have if I put a little more effort into it;
• Even considering switching to a "just works" distro is too much of a chore since I really don't care enough, and also because this list wraps around.

And Now Some Negative Notes

Before that let me emphasize that some of the bad stuff here might be specific to my setup, and not to the PinePhone in general. Also I can't comment on other Linux phones.

• The camera sucks: I haven't been keeping up with the latest development, but last I checked there was only one specific app that knows how to access it. It is not usable in web browsers for example. The supported camera app always crashes for me when I try to take a picture. I think it only crashes on X11 (biggest mobile-friendly UIs use Wayland). Also the image quality isn't great;
• The modem can be unstable sometimes: The thing that makes the PinePhone a phone is not very reliable. There have been improvements but I'm still not confident in its ability to do a bunch of tasks without a reboot;
• Call audio sucks: It's too quiet on my end, and sounds like shit on the other end;
• Battery life isn't great. That's not much of a problem for me because I keep it powered off all the time.

That being said, I do appreciate all the work that volunteers are doing to improve things.

And now back to why all phones will always suck.

Crippled Pocket Computers

Let me elaborate on this quote from Part 1:

phones will always be crippled pocket computers, either because there is too much abstraction in order to fit the form factor, or because there isn't.

You can absolutely do computer stuff on the PinePhone (or other Linux phones, or even Android to some extent), but computer stuff usually requires a larger screen and a keyboard. So if you treat a phone like a computer, it's powerful but hard to use, and if you abstract away all the mobile-unfriendliness, you end up with a frustratingly limited toy with a cute shiny UI.

Virtual Keyboards

They always suck:

• They cover a significant portion of the screen, giving you even less space to work with;
• You can't feel the tiny keys on your fingertips going down and up as you press them. The best you'll get is an artificial vibration;
• Typing should be done with 10 fingers, not just 2 thumbs;
• Layouts suck, either because they only show a small subset of the keys on the main layer or because they show too many and it gets all cluttered.

Keyboard-driven workflows are just superior on the desktop, but painful on mobile. So you can either get used to it or give in to the high level toy interfaces.

Conclusion

I still hate phones. Linux phones are great for what they are, but they are still phones. You get a whole lot more freedom from them compared to Android and iOS phones, but freedom always comes at the cost of not being spoon-fed stuff that just works for the average blue pill junky, and instead having to make choices and set things up yourself.

If you are a FOSS enjoyer, and you think my opinions on phones are too extreme, then by all means give Linux phones a try. If instead you totally agree, then take a step further and go phoneless.

Now I can hopefully quit yapping about hating stuff and write about some more joyful subjects. Hopefully.

In this post I'll be bitching some more about why phones generally suck and you shouldn't use one most of the times, so keep on reading if that's something that interests you.

Note: this is mostly aimed towards smartphones, but many things also apply to the dumb ones.

UPDATE 2025-07-13: Just came across this video by Luke Smith on the same subject. Totally agree. Go watch it.

Surveillance Gold Mine

Most phones ship spyware out of the box. And most users go out of their way to install some more spyware on top. Phones are just the perfect surveillance gold mine: with all the cameras and microphones and sensors and the fact that most people voluntarily carry them around everywhere, always powered on and connected to the internet, their potential for data collection is far beyond what you would get from your traditional desktop spyware.

Even if you are smart enough not to install random spyware into your phone, it's likely that everyone around you is not, and is unknowingly snitching on you with their pocket surveillance devices.

Also if your device gets pwned through some zero-day exploit, despite your best efforts to keep it secured, the cyber bad guys who don't wear suits will also get to enjoy all the juicy data your phone can provide.

Too Much Abstraction

That thing in your pocket is actually a computer. But likely has an OS that tries to pretend otherwise, by abstracting away a bunch of stuff. Pictures? Oh yeah, those are stored in the gallery app. Absolute paths? File systems? You're talking nonsense, hackerman! This is a phone!

There might be valid reasons for this to some extent: You don't usually have a keyboard hooked up to a phone, just like you don't usually have a touchscreen on your desktop computer. It has to take some shortcuts to be convenient to use. However it ends up getting in the way of advanced users. The concept of "program" is abstracted away by these "mobile apps", with mandatory complexity to look and behave consistently. It's nice to have a consistent user experience, but if the best tool for the job looks ugly and out of place, then so be it.

Not only is this annoying for people who want to do computer stuff, it also gives a false sense of security. After all, what harm could this random app that I don't really need possibly do? Look how cute its shiny little icon looks sitting on my home screen. Most people are to some degree aware of the dangers of installing random software on computers, but phones? The trusted ad app store says all the cool kids are using this app, so I must have it.

This makes people more willing to install random apps on a phone than they would be on a desktop computer. And don't get me started on the dumb low effort mobile games whose sole purpose is rewarding you with fake points for microtransactions or voluntarily watching ads, aside from the ones they were gonna shove down your throat anyway.

To summarize, the main point here is that mobile apps are viewed as something entirely different from desktop computer programs for artificial reasons, resulting in harm to the freedom of users and developers.

Fake Restrictions

Certain platforms restrict functionalities for made up reasons. Wanna play music from YouTube in the background (don't do that, own your audio files)? That'll be $13.99/month, fuck you. Wanna view certain message formats on Instagram? Sorry buddy, the web version won't do, you'll need the app for that!

Then there are all those mobile apps that serve as the only authorized way to access some online service. Most of the times that is either stupid or evil. Your dumb mobile app could very well be a web app. But you just can't fit enough spyware in a web app, can you? If you are going to milk your users for data, might as well force them into more spyware-friendly platforms.

Take WhatsApp for example. It has valid reasons to require a native app, such as the alleged end-to-end encryption. But the only way to use it is to have that one spyware app running on your spyware device. Signal is far from perfect, but at least there are non-official ways to use it without ever installing the mobile app, such as signal-cli. And that's the beauty of FOSS.

Not Much Choice

So far a lot of what I said was about shitty software running on phones, and not about phones themselves being shitty. So you could just use non-shitty software, right? If we're talking about the operating system, sure, as long as you are able to replace it without bricking the phone. But of course the better alternatives won't magically support the shitty mobile apps you might need, because the term "mobile app" usually just means "Android/iOS app", and has nothing to do with the hardware it runs on. Compatibility layers and emulation defeat the purpose and are overly complex solutions for a fabricated problem.

That being said, let's take a look at the 2 only options that non-hackers use. I'll leave real mobile Linux for the upcoming PinePhone article. UPDATE 2025-03-29: Here it is.

iOS

This heading is only here for completeness. Nothing to say here other than just don't use Apple's proprietary trash.

Android

A lot of what I said so far was with Android in mind, so I won't be repeating it. Here are some other things that piss me off about this compromised OS:

No Root Access

You should avoid running things as root for security reasons. That was never a phone specific concept, and should not have had the phone specific solution of taking away the ability to do so. You need root access if you want to own your device. If you think it's okay to take freedom away from users for their own safety, you might as well put on a straitjacket and go live in a padded cell to protect yourself from the dangers of paper cuts and shark attacks.

Can't Remove Stock Spyware

The vast majority of Android phones you can buy ship with a lot of proprietary spyware sprinkled on top, that cannot be uninstalled by regular users. Some of the built in spyware trash only provides the option to uninstall updates, i.e. downgrade the spyware. Some can also be "disabled", which is like uninstalling it except it's still there. I can't think of any good (as opposed to evil) reason for this, considering that uninstalling these apps would not break the system in any way if you weren't using them. But you could just use the open-source part of Android without all the shit smeared on top, right?

Kinda Open-Source-ish But Not Really

Most people just use stock spyware. Maybe you can get some freedom with Android if you jump through enough hoops. But let me tell you the story of when I tried building a simple "hello world" app for Android using FOSS only. Spoiler: I gave up.

I was trying to install the Android SDK, which is supposedly open-source, when I was asked to accept a EULA. Something was very clearly wrong. So apparently the official binary distribution is nonfree. Very well, let's build it from source. After all I'm a Gentoo user, that's what I do. The problem is there don't seem to be any good instructions on how to do so: you either run a script that ends up pulling the proprietary binary sources from somewhere else, or you use Google's git-based repo management thingy that pulls from a bunch of repos and then you supposedly get to build the thing. Well that sounds sketchy as hell! It's almost like they don't want you using the free version (who would've guessed?). Screw this, I'm outta here!

After writing the previous paragraph I went and gave it another shot to make sure I wasn't being unfair. So I installed the git wrapper thingy and tried to clone the sources as instructed here. Result: after 20 minutes and 7% progress, it had fetched 17 GB. Also it logged a bunch of errors to the console about not being able to fetch some repos. I remind you I only wanted to build a "hello world". For reference, the LibreWolf browser's unpacked sources take up 4.4 GB and my kernel directory (including compiled objects) takes up only 2.5 GB. It turns out it was fetching the whole Android sources, not just the SDK, but I couldn't find any docs on how to fetch only the SDK components (assuming it doesn't actually require the whole thing), and if the instructions are not in the file called "howto_build_SDK.txt", then I don't know where else they would be.

I'd love to be proven wrong on this one, so if you know of an officially documented way to get a free SDK that doesn't try to roofie you into using the nonfree release every step of the way, and can be built/installed completely offline after getting the sources, then please let me know.

You Don't Own Your Phone Number

This starts the "phones themselves being shitty" section.

It is ridiculous that so many services use phone numbers for verifications and SMS-based 2FA. Securing your number from SIM-swapping attacks is outside of your control. All you can do is hope your carrier does not fuck it up.

Pinging Cell Towers

Your phone does this all the time regardless of how "smart" it is marketed as. Whoever controls the towers can track your location.

Conclusion

I've been writing this post for over 3 weeks now, let's wrap it up, we've all got better stuff to do.

Phones are everywhere and society expects you to carry one. That's harmful for freedom and privacy, since it's impossible to have a phone that does not milk you for your data and at the same time meets society's expectations of being able to run all the fancy exclusive "mobile apps" made for Android/iOS. So the main problem is this proprietary "mobile app" trend.

It's nice that there are projects aiming to bring user freedom to mobile platforms, and I don't see much of a problem with using them responsibly, but phones will always be crippled pocket computers, either because there is too much abstraction in order to fit the form factor, or because there isn't. And like with desktop computers, there is a time to use them, and there is a time to touch grass. So get off that damn phone!

TL;DR

• Move non-critical services to a separate custom runlevel;
• Write a boot script that switches to that runlevel in the background, allowing you to log in while some services finish starting up;
• Set rc_parallel to "YES" in /etc/rc.conf.

The Problem

By default OpenRC will start all services in the runlevel before it presents you a login prompt (specifically referring to the getty, I don't use a display manager so I cannot comment on those). This takes up a lot of boot time for no good reason. Do you really need your network related services to be running before you log into your desktop? Couldn't they just start in the background, and be done by the time your bloated web browser finally opens?

I couldn't find any properly documented solution for this problem, so I had to come up with a little hack. The best I could find was this Reddit thread, which describes the exact problem but does not provide a direct solution. It does however mention the use of custom runlevels, which I did end up using.

The Solution

Here's an overview of the hacky solution I came up with:

• First of all, we create a custom runlevel;
• Secondly, we move all services from the default runlevel that we wish to start in the background into it;
• Then we stack the default runlevel onto it;
• Finally we write a little boot script that switches to our custom runlevel asynchronously, starting all required services in the background.

Let's break it down.

Creating a Custom Runlevel

I called mine async. Name it whatever you want. Run the following as root:

mkdir /etc/runlevels/async

As easy as that.

Moving Stuff Over

Now we will move most of the services from the default runlevel into async. In my case it was safe to move all except for the gettys and local (you may not have gettys there if booting with sysvinit). The easiest approach here is probably to directly move the symlinks from /etc/runlevels/default/ into /etc/runlevels/async/, although you can also use utilities such as rc-update as you normally would. Here's an example (run as root, add or remove services as needed):

cd /etc/runlevels/default
mv net.* sshd chronyd distccd tor libvirtd ../async

Stacking Runlevels

Runlevel stacking is what they call adding a runlevel to another runlevel, i.e. inheriting services from another runlevel. We need this because otherwise the services from the default runlevel would be stopped upon switching to the async runlevel (unless they were also added to it). Run the following as root:

rc-update add -s default async

Starting It Asynchronously on Boot

Note: If you use OpenRC to start the gettys, e.g. you use openrc-init, then it would suffice to boot into the async runlevel by appending softlevel=async to the kernel cmdline. But the getty will get buried by the console logs of the services in async, so you might prefer these next methods that also don't involve messing with the kernel parameters.

I find that the simplest way to achieve this is through a custom script in /etc/local.d/, but for some more complex setups it might be better to write an init script instead (i.e. in /etc/init.d/) and add it to the default runlevel. The local.d approach will work as long as you have the local service enabled in the default runlevel, which at least in Gentoo should be there if you haven't removed it.

Simply create the file /etc/local.d/async.start (or anything in that directory ending in .start) with the following contents:

#!/bin/sh
/sbin/openrc async &

And make it executable: (as root)

chmod +x /etc/local.d/async.start

And you're all set! All the script is doing is switching to the async runlevel, using the '&' character to background the process.

Bonus: Parallel Service Startup

You might already know this, but here is a general tip for faster OpenRC boots: Enable parallel service startup by editing /etc/rc.conf and ensuring that you have an uncommented line with rc_parallel="YES". This will considerably speed up the boot process but won't fix the main issue I've described. However it is safe to use together with the solution that I've demonstrated here.

Conclusion

And just as I was about to post this, I checked again for existing solutions, and guess what I found: NEARLY THE EXACT SAME THING POSTED BY SOMEONE ELSE 3 YEARS AGO! With the same runlevel name and all. I swear on my life it's the first time I'm looking at it.

Seriously though, go check it out if you're using sysvinit, it seems cleaner than my approach. It will not work for openrc-init however, which means my article is still kinda relevant and I'm slightly less mad.

TL;DR

I show you how I build this site using a script called from a Makefile, that converts markdown files to HTML with some additional processing.

Converting Markdown to HTML

If you're feeling adventurous, implement it from scratch. That's not what I did here, I felt this was a wheel not worth reinventing. There are several tools you can use for this. I chose cmark-gfm (GitHub's fork of cmark).

The syntax is as simple as:

cmark-gfm file.md > file.html

It can also read from stdin in case you need to do some preprocessing:

my-preprocessing-function | cmark-gfm > file.html

Putting it in a Makefile

Makefiles are great since they only rebuild files if their source was updated. Check out the great tutorial in the references¹ to learn more. Let's start putting one together with what we've learned so far. What we want is to take all the markdown files in the current directory and convert them to HTML files with the same name and different extension. We start by listing the files that we will be working with:

MD   := $(wildcard *.md)
HTML := $(MD:%.md=%.html)

Here we're first using a wildcard to match all .md files in the current directory and put them in the $(MD) variable. Then we use a Substitution Reference² to replace all the .md extensions in $(MD) with .html, and save it in the $(HTML) variable, which now contains all our targets.

Now we need a rule to build our targets:

all: $(HTML)

%.html: %.md
	cmark-gfm $< > $@

Here we're saying that the .html files should be built from the corresponding .md files using cmark-gfm. The special variables $< and $@ mean the name of the first prerequisite (.md file) and the name of the target (.html file), respectively. ³

The "all" target (or whatever you decide to name it) must be specified and depend on the files in the $(HTML) variable.

Preprocessing

That's cool and all, but our HTML files are still lacking some important stuff, like hmm... I don't know, a <html> tag maybe? I suppose you could do something as ugly as echoing/cating some template HTML to prepend/append to the generated one, with all your headers and stuff, but let's do something slightly less ugly. Oh wait, never mind, that's almost exactly what I did. Let's put it in a shell script, we'll get back to the Makefile soon. Here is the main thing (we'll get to the functions later):

cat <<-EOF
<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<link rel="stylesheet" type="text/css" href="/css/style.css"/>
	<title>~jlucas/$(gettitle "$input")</title>
</head>
<body>
	<header>
		$(cat "${srcdir}/templates/header.html")
	</header>
<main>
	$(preprocess "$input" | cmark-gfm --unsafe -e strikethrough -e table -e footnotes)
</main>
<footer>
	$(cat "${srcdir}/templates/footer.html")
</footer>
</body>
EOF

Yes, a lot of it is hardcoded. Yes, I could've used a real template engine. But this is specific for this site and I don't plan on changing this structure for specific files, so who cares?

With that out of the way, let's break it down. In the middle of this hardcoded mess, you can find some $(shell substitutions). They are used to insert the page title in the <head>, the navigation bar in the <header>, the converted HTML in <main> and the footer in the <footer>.

The header and footer are pretty simple. I just do a little catception to include them from static manually written files.

As for the title, I'm taking it from the heading on the first line of the markdown file. Here's the function:

gettitle() {
  sed -n '1s/^#* *//p' "$1"
}

The regex is just removing any '#' symbols that might be prepended.

The final piece we're missing here is the preprocess function. This will depend on the use case and might not always be needed. All I use it for at the time of writing is to auto generate a list with all posts. For that I make it search each line of the input file for the expression "@POSTS@" and replace it with the actual list. Here it is:

preprocess() {
  while IFS= read -r line; do
    case "$line" in
      '@POSTS@') listposts ;;
              *) printf '%s\n' "$line" ;;
    esac
  done < "$1"
}

Basically it reads each line of the markdown file, and either prints it as is or lists the posts. The "IFS=" is needed to prevent it from removing leading whitespace. And what's that listposts thing? Oh, right, it's yet another function. I promise it's the last one. Here it is:

listposts() {
  find "${srcdir}/posts" -type f -regextype posix-extended \
                         -regex '.*/[0-9]{8}-.*\.md' -printf '%f\n' |
  sort -r |
  while read -r file; do
    filedate="$(date -d "${file%%-*}" +%F)"
    printf '+ [%s] [%s](%s)\n' \
      "$filedate" \
      "$(gettitle "${srcdir}/posts/${file}")" \
      "/posts/${file%md}html"
  done
}

I decided to name my posts with a prepended date, in the format YYYYMMDD-title-goes-here.md. That way I avoid having to store some metadata elsewhere. Then I just list all the files in the posts dir, sort them as latest first, and write the date, title and link in a markdown list.

Then this preprocessed markdown gets fed to cmark-gfm with some additional options to enable some nice extensions and allow raw HTML.

Putting it all together

So far we have an outdated Makefile and a shell script that takes a markdown file, does some preprocessing to it and spits out the resulting HTML to stdout. We'll name the shell script src/generate.sh. Let's update that Makefile.

Previously we were calling cmark-gfm directly in the Makefile. That's now handled by the script, so just replace cmark-gfm with src/generate.sh. And that's all there is to it, unless of course you want to go a little bit further with organizing the directory structure. You do? Cool, let's do that.

Since I wanted to have the HTML and markdown in separate directories while mirroring the directory structure, I had to make some changes to the way I get the list of targets, as well as the rule to build them. Instead of a wildcard like we had before, we can invoke a shell with the find command to list markdown files recursively. Also I keep the markdown files in the src directory, so that also needs to be handled when we do the substitution for the HTML targets:

MD   := $(shell find src -type f -name '*.md')
HTML := $(MD:src/%.md=%.html)

And finally the rule to build our HTML should look like this:

$(HTML): %.html: src/%.md
	@mkdir -p $(@D)
	src/generate.sh $< > $@

Notice I added a mkdir command to create directories if needed. The $(@D) variable evaluates to the directory containing $@. Also I had to use Static Pattern Rules⁴ to allow the pattern matching to work properly with subdirectories.

Now add some more dependencies to have certain files rebuild when scripts or templates change, and we're all set (check out the complete Makefile below).

Wrapping up

Wow, that came out a bit longer than I was expecting. Still, the point is that if you don't need all the complexity of modern SSGs, you might be better off making your own thing. All we did here convert markdown to HTML with a little {pre,post}processing and the help of a Makefile. Oh, and you might want to sprinkle some nice CSS on top. But not JS. Don't do that. That's bad, mkay?

I'm leaving the complete Makefile and script here for convenience, though you can also view the source on Codeberg (or even here and here since I don't keep the source in a separate repo).

MD        := $(shell find src -type f -name '*.md')
HTML      := $(MD:src/%.md=%.html)
TEMPLATES := $(wildcard src/templates/*.html)
SCRIPTS   := $(wildcard src/*.sh)

.PHONY: all clean

all: $(HTML)

# Rebuild post lists when posts are updated
index.html posts/index.html: $(wildcard src/posts/*.md)

$(HTML): %.html: src/%.md $(TEMPLATES) $(SCRIPTS)
	@mkdir -p $(@D)
	src/generate.sh $< > $@

clean:
	rm -f $(HTML)

#!/bin/sh
srcdir="$(dirname $0)"

die() {
  printf '%s\n' "$1" >&2
  exit "${2:-1}"
}

gettitle() {
  sed -n '1s/^#* *//p' "$1"
}

listposts() {
  find "${srcdir}/posts" -type f -regextype posix-extended \
                         -regex '.*/[0-9]{8}-.*\.md' -printf '%f\n' |
  sort -r |
  while read -r file; do
    filedate="$(date -d "${file%%-*}" +%F)"
    printf '+ [%s] [%s](%s)\n' \
      "$filedate" \
      "$(gettitle "${srcdir}/posts/${file}")" \
      "/posts/${file%md}html"
  done
}

preprocess() {
  while IFS= read -r line; do
    case "$line" in
      '@POSTS@') listposts ;;
              *) printf '%s\n' "$line" ;;
    esac
  done < "$1"
}

input="$1"
echo "$input" | grep -sq '\.md$' || die "Usage: $0 INPUT_FILE.md"

cat <<-EOF
<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<link rel="stylesheet" type="text/css" href="/css/style.css"/>
	<title>~jlucas/$(gettitle "$input")</title>
</head>
<body>
	<header>
		$(cat "${srcdir}/templates/header.html")
	</header>
<main>
	$(preprocess "$input" | cmark-gfm --unsafe -e strikethrough -e table -e footnotes)
</main>
<footer>
	$(cat "${srcdir}/templates/footer.html")
</footer>
</body>
EOF

References

Who?

Check out the about page.

Why?

Because I wanted to write stuff as an exercise and for future reference, and social media is dumb. Also I was playing around with Codeberg Pages and building my own simple static site generator, and decided I might as well keep it.