Forem: Shaun

Setting up DSMR Meter Readings via a Raspberry Pi

Shaun — Thu, 23 May 2024 12:40:23 +0000

Originally published at https://badgerbadgerbadgerbadger.dev/posts/automation/2024-05-23-setting-up-dsmr-readings-via-raspberry-pi/

The internet is probably full of tutorials on how to do this right, but I had to struggle a bit to figure it out for myself. My Pi randomly crashed, the other day, and I'm having to do some of the setup again and having done this for the first time months ago (and having now mostly forgotten what I did), I decided I should blog about it as I retread my steps and recreate my setup.

Aside: The internet tells me that the C shell was the first to introduce the history command. It would not be hyperbolic to say that without history my task of recreating my setup would be significantly more difficult. I used it extensively to figure out what I ran when I needed to do this all those months ago. I should probably containerise or chefise or ansibilise or something.

I live in a country that uses DSMR meters and have one in my home. My girlfriend wanted a closer look at our electricity consumption, so I decided to hook up a raspberry Pi to the meter's P1 port and send those readings to my home lab server using the Pi as a relay.

I bought a RJ12 --> USB cable off of Amazon and tried to read from my Pi's USB port by using first cu and then pyserial (which is a much friendlier interface).

# Using cu
cu -l /dev/ttyUSB0 -s 115200 --parity=none

# Using pyserial
python3 -m serial.tools.miniterm /dev/ttyUSB0 115200 --xonxoff

Initially neither tool gave me any readings and I nearly tore my luscious hair out before finally realising that it was a bad cable I was using. I returned it and bought a more respectable cable from robbshop.nl.

And that gave me results!

I had a few different ways of turning the meter readings into useful insights:

Run HomeAssistant on my Pi with direct access to the port: Not an option since my HA instance was already running on my home lab server. The Pi was meant to be a relay only.
DSMR to MQTT: I could run something that would read the DSMR telegrams and send them to an MQTT broker to which I could subscribe my HA integration. Definitely an option.
Serial to Network Proxy: The option I ended up going with since it felt the simplest to me. I would run a program that would expose the DSMR telegrams over a TCP connection.

The program I landed on for doing this is ser2net With a little help from ChatGPT I figured out this ser2net config. Comments describe what the various fields do.

# defines an alias confver, I'm not entirely sure if this does anything
define: &confver 1.0

# begins a new connection definition and assigns it an alias `con00`.
connection: &con00
  # specifies how incoming network connections will be accepted, in this case the Telnet protocol with RFC 2217 support (I no clue what that means), and the connection will be over TCP and listen on port 2013c (this part I understand)
  accepter: telnet(rfc2217),tcp,2013
  # specifies how the serial device will be connected, includes path to the serial device file and port settings, and it is to be configured in local mode (not sure what local mode means)
  connector: serialdev,/dev/ttyUSB0,115200n81,local

I paired this with HA's DSMR Slimme Meter integration with it set to listen on the network, pointed at my Pi on port 2013.

And we have lift-off!

Note: Solar readings are coming in via a different integrations and configured together with the DSMR readings using HomeAssistant's Energy Dashboard.

Is it Dry Yet?

Shaun — Fri, 12 Apr 2024 08:17:30 +0000

Clarification: This is literally about my laundry. I am not being metaphorical. I am not talking about my feelings or my secrets. I am talking about my clothes.

Intro

Our washing machine is a Samsung something-something that sends me a notification on the SmartThings app when it completes a wash cycle. This is useful since we almost always need to follow up a washing cycle with a drying one and maybe even another load of laundry. The machine isn't a combined-washer-dryer so someone has to move the wet clothes from our smart washer to our dumb dryer.

The fact that our dryer is "dumb" is what led me to my automation journey. If it was Wifi-enabled and also sending out notifications as it completed a cycle, I wouldn't be writing this post.

Having been spoiled by knowing exactly when my washing has completed (so I know when to go move things to the dryer) I decided to do something similar for the dryer. This is especially useful, for example, when the clothes need an extra drying cycle or when there are more wet clothes that are waiting in the washer. In these times it is useful to know if the dryer has finished a cycle.

And since it is not a smart device, I have to add the brains, somehow.

Plan of Attack

This is how I decided to approach the problem:

I have a Shelly smart plug that I would put between Drew (the dryer is called Drew) and the wall.
The plug would transmit power readings to my Home Assistant setup.
I would do something to detect when the power reading goes down from some high number to some very low number (I'm assuming it never goes to 0 since the little LED panel needs power).
I will notify myself of this somehow.

It's the something and somehow parts I was unsure of. My Home Assistant setup is as basic as it gets. I only started my home automation journey a month or two ago and was unfamiliar with the possibilities. However, this felt like something that should be within the realm of HASS's capabilities.

Discovering Automations

The first thing I discovered as I dug further into Home Assistant was Automations. In Home Assistant you create automations via the Automations system. You can turn on a light when a motion sensor senses someone in the room; you can turn on the vent when humidity reaches a certain level; you can make all the lights turn pink and romantic music play over the speakers when it is February 14th and your beloved comes home from work. The possibilities are endless.

The Automation Setup

Figuring out the Automation setup I wanted was straightforward. There are 3 key components to the Home Assistant Automation system.

Triggers: The thing that kicks off an Automation. These can be of many types ranging from a number on a sensor changing, to an incoming MQTT payload.
Conditions: An optional extra check to ensure that when the Automation triggers everything is in the state you want it to be. You can check the value of sensors, check the on/off status of devices, or even check if the sun is up.
Actions: This where we do something in our Automation. This is where you will want to set up that electric rooster crowing when the sun comes up (if you want to build your own weird alarm clock for some reason), or send a message on a webhook when the kids are using too much electricity.

Thinking over my needs I decided on the following for my Trigger/Condition/Action setup:

Trigger: I want the Automation to start when Drew's power draw falls below 10 W (as reported by Sheila, the smart plug), and has remained under 10 W for more than 5 minutes.
Condition: I want to ensure this Automation only fires if we have consumed more than a 100 Watts of power sometime in the last 5 minutes.
Action: Inform me somehow that this has happened.

While the Trigger and Condition were straightforward, the Action was a bit more nebulous. At first, I wasn't entirely sure how to notify myself. I looked into Home Assistant's Restful Notifications but could not make it work for the life of me. Then I decided to check if I could send an email. I found Home Assistant's SMTP Notifications and decided to give it a go. Again, I could not make it work. It asked me to enter my Gmail password in the Home Assistant configuration file, but I was not comfortable doing that. I decided to look for another way.

I finally stumbled upon the Home Assistant iOS App which I installed on my phone and pointed to my Home Assistant server. This allowed me to send notifications to my phone (my phone became available as a target for notifications).

The full Automation setup looks like this:

alias: Is it dry yet?
description: Notifies when Drew (the dryer) has finished a drying cycle.
trigger:
  - id: Sheila Power Below 10 W
    platform: numeric_state
    entity_id:
      - sensor.sheila_power
    below: 10
    for:
      minutes: 5
condition:
  - condition: numeric_state
    entity_id: sensor.sheila_power_5_minutes_ago
    above: 100
action:
  - service: notify.mobile_app_sharpie
    data:
      message: Drew has finished a cycle. You should unload him.
      title: Dryer Cycle Finished
  - service: notify.mobile_app_buttercups_android
    data:
      message: Drew has finished a cycle. You should unload him.
      title: Dryer cycle finished.
  - service: media_player.play_media
    target:
      entity_id: media_player.thuis
    data:
      announce: true
      media_content_type: mp3
      media_content_id: https://<static-host>/drew-finished-drying.mp3
mode: single

notify.mobile_app_sharpie and notify.mobile_app_buttercups_android are the entities exposed by the Home Assistant iOS and Android apps on my phone and my girlfriend's phone respectively. media_player.thuis is the entity exposed by my Google Nest speaker group. Not being simply content to send a notification to my phone, I also wanted to play a sound on my Google Nest speaker group. The sound is a mp3 file that I host on a static host.

sensor.sheila_power is the sensor entity exposed by my smart plug and what lets me monitor the power draw of the dryer. sensor.sheila_power_5_minutes_ago is a sensor that I created using the SQL Integration. I created a custom sensor to get the power draw 5 minutes ago.

select *
from states
where metadata_id = (select states_meta.metadata_id
                     from states_meta
                     where states_meta.entity_id = 'sensor.sheila_power')
  and datetime(last_updated_ts, 'unixepoch') < datetime('now', '-5 minutes')
order by last_updated_ts desc
limit 1

In combination this ensures that this Automation only triggers when our power draw falls below 10 W for at least 5 minutes, and we have consumed more than 100 W of power just before. This gives me a good indication that the dryer has finished a cycle and I should go unload it.

Exposing to the World

I should mention that my Home Assistant server was not available to the internet at that point. All integrations were over local Wi-Fi with firewall rules to prevent any external access. I did not have to expose my Home Assistant server to the internet to get notifications on my phone since they are both part of a Tailnet. This meant that as long as I had the Tailscale App on my phone and Tailscale VPN enabled, I could access my Home Assistant server from anywhere in the world.

And this would have been good enough for me, but my girlfriend also needs notifications on her phone and asking her to install Tailscale and turn it on/off before she could access the notifications was a bit much.

So I decided to expose my Home Assistant server to the internet.

My first attempt was using Let's Encrypt and DuckDNS, following a guide (or three) similar to this. I won't go into all the details, but I will say that it was a pain. Ultimately, after struggling for several days, I gave up. I gave up and decided to go back to my girlfriend, head bowed, and give her the bad news.

But then I stumbled upon Tailscale Funnels. Since I was using Tailscale anyway, with a single additional invocation, I could have a secure, encrypted, tunnel to my Home Assistant server.

➜  ~ tailscale funnel --https=8443 --bg 8123

No extra DNS required since I can use my Tailnet's name and no extra certificates required since Tailscale handles all of that for me.

The only caveat to this approach is that Tailscale does not yet support domain name handling. So I can't assign a nice domain name to my Home Assistant server. Furthermore, I only have 3 ports available to me. This means that if I were to have other services on that machine that I want to expose to the world, I can at most have 2 more, and they will have to be referenced by their port numbers.

This is something I will have to come back to later, but for now both me and my girlfriend have access to our Home Assistant server from anywhere in the world and are happy ducks.

Of course, I limited her account to only have access to the notifications and some views. I don't want her messing with my automations and I don't want a third party poking around my smart home setup.

Dealing With Errors in Go Projects

Shaun — Thu, 22 Apr 2021 10:52:06 +0000

Originally published on https://badgerbadgerbadgerbadger.dev/dealing-with-errors-in-go-projects/

Dealing With Errors in Go Projects

Note: In this post I talk both about the purely technical reasons for doing certain things and some practices that have made debugging production systems easier for me. I'm still fairly new to Go and still learning so if you find any issues with my approach or have a better way to approach the problem, please leave a comment.

I come from a NodeJS background and my coding habits have been heavily influenced by the paradigms most used in Node. I started coding in Go quite recently and I immediately fell in love with the language. I love a lot of things about Go, but let's not get into that right now or we'll never get to the point.

Let's talk, instead, of what caused me a lot of headache and frustration: errors.

I didn't know what to do with the darned things. The idiomatic way in Go is to return errors as a second value and that's what pretty much all libraries do. There is a panic-recover mechanism but I've found it to be used to recover from things like illegal memory access or nil pointer dereference (these shouldn't happen if you code properly).

I was looking down the barrel of either handling and logging errors on the spot, or returning them up the chain of function calls. Neither sounded like a good idea. Why? Here's why:

If you handle errors on the spot and log them you lose context of the steps that led to this error. You can log variables local to the function where the error occured, but you have no idea what path your program took to finally call this function and face this error.

If you return errors up the chain and then handle them at the topmost level, you end up with almost the same thing. You have the error and you know which entry point of your function eventually led to that error, but now you've lost context of the function where the error originated.

Neither of them is a good idea, especially not at 4 in the morning when your boss calls you up to debug some obscure bug made more obscure by insufficient information. You need to know where the error originated, which entry point led to this and what path it followed. And of course, the details of the error itself.

To work around these issues, I had this idea of annotating the error message at each stage. So say I have the following extremely contrived code:

package contrived

import(
    "thirdparty/lib"
    "errors"
)

func HandleRequest(req Request, res Response) {
    result, err := ControllerCall(req.Id)
    if err != nil {
        log(err.Error())
        res.BadResponse("...")
        return
    }

    res.GoodResponse("...")
}

func ControllerCall(id string) (*string, error) {
    result, err := DbCall(id)
    if err != nil {
        return nil, errors.New("controller failed to blah blah blah "+err.Error())
    }

    return result, nil
}

func DbCall(id string) (*string, error) {
    result, err := lib.DoSomething(id)
    if err != nil {
        return nil, errors.New("db call failed for id: "+id+" "+err.Error())
    }

    return result, nil
}

By concatenating the errors at each step I retain context. At the top level, when I log, I can see the calls that led to the error. This is better than not having much context but is extremely tedious in practice.

Then I came across this excellent blog post by Dave Cheney. And once you've read through it (seriously, read through it before continuing), you'll see that he's implemented the same idea I had but done it a gazillion times better. So I started perusing more things he'd written. The presentation link includes most of the content of the preceding articles.

Constant Errors
Don’t just check errors, handle them gracefully
Inspecting Errors
pkg/errors
Dave Cheney's presentation on Error Handling youtube pdf

After reading through all that and tinkering around for a while, I came up with a set of sensible guidelines for handling errors. Some of them are taken directly from Dave Cheney's blog, some I added based on my own experiences.

Let's Begin

Always check for errors if the function returns one. I know that sounds obvious but you'd be surprised at how much code I've seen that doesn't do this.
Create custom error types for the errors you know you are gonna face (bad input, duplicate request, etc.). Return these, wrapped by the errors package, when you face them.
When dealing with errors returned from a library, wrap it with errors.Wrap or errors.Wrapf and return.
When dealing with errors returned from your own code, if:
- it requires no further context, just return it.
- if it requires some extra context (perhaps data points captured within that function), use Wrap or Wrapf.
Handle errors without further propagation at the entry point of your program (commands in a cli or handlers in a web server). Unwrap it with errors.Cause and test it:
- If it is of the custom type you have defined for your project, handle accordingly (you might wanna log these at level Error or Warning since these were expected). If it's an endpoint facing your users, you might wanna have a contract with the client on what codes to return and act accordingly (you might even end up returing a generic error message). If it is an internal endpoint (thinking microservices), you could return an appropriate status code and message while logging the same.
- If it is of an unknown type, you might wanna log a fatal. This is an error that should never have happened. After that it's up to you.

I use these guidelines to make sure I have enough information during debugging to figure what's going wrong. I still have to do error != nil everywhere but I think that's not as bad a thing as I first thought. Unlike exception propagation, this way of doing things makes me stop and think at each step if I wanna let the error propagate on its own or add more context.

Lastly

This approach works for me, for now. Is there a better way to do this? I don't know. There's still a lot for me to learn and I'm hoping that as I keep coding, I'll face enough new challenges to keep me reaching for better ways to code.

Bookmarklets Made My Life Easier

Shaun — Thu, 15 Apr 2021 09:48:40 +0000

Originally published on https://badgerbadgerbadgerbadger.dev/bookmarklets-made-my-life-easier/

Update

I've put the bookmarklets that I mostly frequently use in every day life on this repository.

Being a Developer is Fun

One of the advantages of browsing the web as a web-developer vs. as a layman is the fact that you get to do some pretty cool stuff to make your life easier.

For example, I remember once being on a website where a certain action kept failing with no visible errors. I’d click a button and nothing would happen. It was frustrating and a layman would have been forced to quit at that point or write in to the website’s maintainers.

And that's what I did too. I wrote in to the site's maintainers.

But before I did that I fired up the developer console on Chrome and started debugging the issue. It turned out to be an error in the script that was trying to handle the button's click event. The event registered to the handler had a typo in the name.

Since I could fix the code on the client, I did so and moved on with my life. I never returned to the site and the developers never wrote back. I hope they found the bug-report useful and it helped better their site.

Where do bookmarklets come in?

One of the things I take advantage of most are bookmarklets. These are tiny pieces of javascript code that run in the context of whatever page you’re on and have full access to the page’s DOM. They live in the form of a clickable bookmark on your toolbar and do their thing at the click of a mouse button. You can even configure them to ask for input before taking actions making them incredibly versatile.

So how have you taken advantage of bookmarklets?

Running Queries on Rockmongo.

Anyone who has used the tool Rockmongo knows how irritating it can be to click through multiple pages to get to a collection’s query interface and then run the query. But once I realized that this action could be represented as a query string, I quickly scripted a little querybuilder that would prompt me for an _id and would perform a lookup against the relevant collection. This improved my productivity a lot.

Show me what it looks like.

Here's the code for one of the Rockmongo query builders:

javascript:(function getDocumentById() {
    window.location.href = encodeURI("http://<host>/rockmongo/index.php?db=<db_name>&collection=<CollectionName>&action=collection.index&format=json&criteria=%7B%0D%0A%09_id%3A+ObjectId%28%27" +
    prompt() +
    "%27%29%0D%0A%7D&newobj=%7B%0D%0A%09%27%24set%27%3A+%7B%0D%0A%09%09%2F%2Fyour+attributes%0D%0A%09%7D%0D%0A%7D&field%5B%5D=_id&order%5B%5D=desc&field%5B%5D=&order%5B%5D=asc&field%5B%5D=&order%5B%5D=asc&field%5B%5D=&order%5B%5D=asc&limit=0&pagesize=10&command=findAll");
})();

It looks quite messy, unfortunately, but it gets the job done. Just replace the stuff in angle brackets with your own values and this should be up and running (if it isn't, let me know).

Getting Email Records on the Mandrill Dashboard

Another example would be of querying in Mandrill. If you've used Mailchimp's Mandrill service, you'll know just how frustrating it can be to log in to the Mandrill dashboard and query for certain tags on certain dates. The interface is clunky and slow and you get logged out often for no reason.

The only way I could maintain my sanity was to use a handy little bookmarklet to quickly run the queries that I most regularly accessed.

javascript:(function getTodaysTag() {
    function getToday() { 
      return formatDate(new Date());
    }

    function formatDate(date) {
      return (date.getMonth() + 1) + '/' + date.getDate() + '/' + date.getFullYear();  
    }

    window.location.href = 
        "https://mandrillapp.com/activity?date_format=mm%2Fdd%2Fyy&q=&date_range=custom&start_date=" + 
        encodeURIComponent(getToday()) + 
        "&stop_date=" + 
        encodeURIComponent(getToday()) + 
        "&tag=" +
        "<your-tag>" +
        "&sender=&search-select-q=&api_key=&__csrf_token=<your-token>";
})();

The above script builds a query string that would fetch for you all the emails tagged with a particular tag (which you can also accept dynamically by calling prompt()), that were sent on the current date. You don't have to click through multiple boxes, you just click on one little bookmarklet.

One caveat is that these two bookmarklets work by building querystrings which are then accessed like any normal page. This only works if you're already logged in to Rockmongo or Mandrill. If you're not, you'll be redirected to the login page, after which you'll come to the dashboard's standard homepage and will have to click on the bookmarklet again. Still better than the alternative.

That sounds pretty cool but what else can I do? I don't use Mandrill or Rockmongo.

These are just two examples of what you can do with bookmarklets and that's not the end of it. Tumblr's Post to Tumblr bookmarklet let's you quickly share the contents of any page to your tumblr blog.

Similarly many other services use bookmarklets to for sharing content or simply providing better readability. Hongkiat has this beautiful list of bookmarklets that you can copy to your bookmarks bar and start using immediately. And since they are just pieces of javascript code, you can customize them as much as you want and have your own version of the bookmarklet tailored to your needs.

So there you go, the power of bookmarklets. I hope this will help you become more productive in your everyday browsing or at least alleviate some of the pains. If you have any questions, send me an email or drop me a tweet.

Generating the Mandelbrot Set

Shaun — Tue, 30 Mar 2021 15:15:25 +0000

Originally published on https://badgerbadgerbadgerbadger.dev/generating-the-mandelbrot-set/

Update

The shared github repo for the end product of this post is in version 2 state. @lovasoa kindly contributed a pull request which massivley improved performance and allowed the rendering to happen at full screen with much better speed and taught me many things in the process. I've added these improvements as an updated section at the end of the post. Many thanks @lovasoa. The first version, on which most of this post is based is still available for perusal at https://github.com/ScionOfBytes/smooth-mandelbrot/tree/v1.0.

Intro

A few weeks ago, somewhere in late April, I became fascinated with the Mandelbrot Set. I came across an interesting video by Ben Sparks on Numberphile where he speaks of them. He starts off with the idea of stable iterations first, on a one-dimensional number line and then, on a two dimensional complex plane, demonstrating how-- on iterating on the square of a given number-- the result can either blow up and tend towards infinity or remain stable and tend towards 0. Or at least that's the idea I got. Someone more math-y correct me if I'm wrong.

The visualisations in the video were quite nicely done and I got an itch to try them myself. My best friend has been studying Daniel Shiffman's Code! Programming with p5.js for Beginners and that reminded me of my own early years in programming when I kept myself motivated by building trippy animations and other cool stuff you can do with a library like p5.js (though back then only Processing existed).

So I thought, why not try my hand at generating the Mandelbrot Set?

Complex Numbers

First, we need to talk about Complex Numbers. There are a ton of videos on YouTube about Complex Numbers. I won't go into the details of what they are exactly or why they exist. Let's just say that for our purposes we can think of complex numbers existing on a line perpindicular to our regular number line. If you take a piece of graph paper and mark a line from left to right, and then another line that crosses that line at 90 degrees, from top to bottom, you can imagine that the horizontal line represents the real number line, and the vertical line represents the complex number line. This gives us a Complex Plane to work with.

I highly suggest watching the videos I've linked to really grasp the ideas behind Complex Numbers and how they represent a plane, but for the purpose of this post, let's just say we have a grid and two numbers to work with, one number representing a horizontal position on the grid, and one representing a vertical. And these give us a point.

The Mandelbrot Set

The Mandelbrot set starts with the idea of iteration. Say you have a number z. This is a complex number of two parts, but for now let's imagine it's a simple number.

Let's square z giving us z². Let's take another number c and add it to our result to get z² + c. Let this be our new z.

We have the operation z' = z² + c

We can do this again but this time, instead of our original z we are using our new value z'. This way, we keep feeding the result of the previous operation into the next one. We keep iterating like this until we have a reason to stop. We can start with a value z = 0, but it's the c that's noteworthy here.

The Mandelbrot Set, as I understand it, is the set of all numbers in the Complex Plane that, when put under this iteration, does not blow up. The c in our equation is the number we're testing.

In this context, if, upon iteration the value of z becomes larger than 2 at any time, we consider it to have blown up. At this point we know that it will tend towards infinity.

So, when speaking of the Mandelbrot set what we do is, for each point in our grid, we test to see if, when put under iteration via the z' = z² + c operation, where c = the point, if the value blows up, then the point is not part of the Mandelbrot Set. And if it does not, then it is.

Honestly, this is all very math-y and I am going to stop with the Math now. I highly recommend you watch the above videos for a solid understanding of Complex Numbers and the Mandelbrot Set. From here on out, I will be talking mostly code.

Let's say we have a grid of pixels, and each pixel can be represented by x / y coordinates. Let's also say that we have a function (the programming kind, not the math kind) testMandelbrot which takes a coordinate c and tells us if c is in the Mandelbrot Set or not. That function and most of the math we need to perform is in this file. As you can see, it requires very little code.

For a proper understanding of why all this math is happening (and especially if my attempt to explain wasn't sufficient), have a look at these videos.

The Mandelbrot Set - Numberphile - More about the Mandelbrot Set.
Mandelbrot Set on Vsauce - A very entertaining and educational video by the beloved Michael Stevens.

And then read this excellent little page by Karl Sims-- Understanding Julia and Mandelbrot Sets by Karl Sims-- this one helped me a lot.

Early Attempts

My first attempt was semi-successful. I made many mistakes, wrote a lot of messy code, and managed to get something going that rendered very slowly even for a 450 x 200 resolution canvas. You can find it here. If you play around with the resolution, you will notice that upping it slightly to 600 x 350 will make it render significantly slower than the initial 400 x 200 setting. This is no surprise. It might only be an increase of 200 pixels horizontally and 150 pixels vertically, but overall, there are now 30K more pixels to scan than before.

I also have a version of this with cleaner code on https://openprocessing.org (this one), but I stressed it out too much in terms of resolution and openprocessing is taking too long to render it.

This is how it looks, by the way:

I decided it was running slow because it was in Javascript. I am ashamed to say that even after five years of working in the industry I still have such naive thoughts. The truth is my code was merely bad and lacking any sort of polish or optimisation.

So the next step of my plan was to try to do the same thing in Processing 3.

I started small:

And then went a tiny bit bigger.

These took way too long to generate, though, with the first one clocking in at 2251 ms and the second at 7869 ms.

I was still making mistakes here. I was using a full package to do the complex math and several other overly complicated things. There wasn't a noticeable performance gain over the JS code.

And then I decided to do something really stupid. I wanted to see a highly zoomed-in version of the Mandelbrot Set and admire the beautiful fractal patterns. So I thought, why not make a really large image and then zoom into that using a regular image viewer and admire the fractals that way?

So I tried to generate a 12000x10000 image. That's 120 million pixels. A 120 mega-pixel image. I tried to generate that on my laptop. And I made a royal mess of it, too. Not only did it take over an hour to do, I forgot to save it, so just to show you guys that image I'll have to let my laptop run hot for an hour, again, and it won't even be that great an image. You'll get to see it anyway.

But let's take a step back.

I didn't want to just make a 120 megapixel image. I wanted to make a 12 gigapixel one. But the moment I tried to allocate an array that large, JVM told me to stick my head where the sun don't shine. Okay, 12K x 10K it would be. I wanted this image to look extra special so I decided to make some smaller ones look really good as practice.

First a 1200 x 1000 that took 38,785ms:

This is pretty nice looking, actually, but let's see if we can do something prettier.

For each of the points not inside the Mandelbrot set, I'm taking the number of iterations it took before it blew up and mapping that from 0 - 200 (since 200 is the maximum number of iterations I'm checking) to 0 - 255 (8 bit greyscale color range).

Now we can not only see the scattered Mandelbrot islands, we can also see the connections between them. These connections are too thin to show up on such a low resolution image, but the surrounding shading gives them away.

Let's try something in another color.

For this I decided to color the inside of the Set fully black, and let the outside be mapped from 0 (full black) to #FF0000(full red), giving us a vivid red border.

Let's do something even more colorful.

This looks closer to what I see in most online visualisations. Here I'm using the same iterations-till-blowup value and then mapping that to a hue (think HSL).

Now I'll leave you with the 12K x 10K resolution version of this image. I won't render it on this page directly because that would tank its load time. You can click on this link to view it. If you compare it to the low res ones you should see a significantly greater amount of detail visible.

A More Sensible Approach

I wanted to see the tiniest details in the fractal pattern and I thought the way to go about doing that would be to create a very high resolution image. But there's only so much a tiny computer can do. And once you cross the screen resolutions currently available (4K is only 3840 x 2160, compared to the 12K x 10K image I generated which can never be fully represented on a 4K screen), you'll have to zoom in a lot to see details. There is a never a time when you can see the full fractal in absolute detail.

Then there's the matter of how long it takes to generate one of these. If you want to play around with iteration values or colors or any other paramter, you would have to generate the static image all over again. Not fun.

I decided to watch some more YouTube videos and figure out how to do this better. I turned to Daniel Shiffman, one of the best YouTube educators I know of in the programming space.

A new plan formed in my mind.

Zooming and Panning

I fired up the p5 editor again. Since I was planning to keep the resolution fairly small, I figured I could keep things in the browser. Or rather, because I wanted to keep it in the browser, I decided to go with the low, low resolution of 400 x 400.

I also made it so the image can be zoomed using + and - and panned using the arrow keys. It still happens really slowly, but at least it works.

Note: In case the embed is not working, go here.

I decided to get a little bit fancy and let the image appear iteration by iteration all the way up to 200. The iterations here are the maximum number of iterations at which we stop testing if the z value will grow beyond 2 (blow up). As you can see, the more iterations performed, the more detailed the picture. This effect is clearer when you are zoomed into one of the edges. You can see the details becoming finer.

Zooming and panning is the way to go forward. If you are to look at only a part of the image at a time, why bother rendering the rest? Graphics programmers have known this since ages beyond reckoning. It took me a failed attempt at generating a high res image at speed to think of doing the same thing (and ideas from Shiffman's video).

Making It Smoother

This rendering is still very clunky, and quite slow. Even at smaller iterations. I want at least 200 iterations to get good fractal detail which will make this run really slowly. But Javascript is single-threaded and there isn't any more I can squeeze out of it. Or can I?

Web Workers have been a thing for a while. OffScreen Canvases are somewhat newer (and not very well supported on non-Chrome browsers). The demo I present here might not work if you're not on the latest Chrome and I apologise for that. Making it work in other ways is possible but too tedious and not something I want to do.

I've since learned that a Uint8ClampedArray works much better than an OffScreenCanvas both in terms of performance and browser compatibility. It needs more code for computing array indices and colors but overall much better outcome. See the end of the post for details.

Play around with it. ~Click on any part of the image to center it~ Click and drag to pan and use alt/option + up arrow/down arrow or the scroll wheel/pad to zoom in and out. You can zoom in pretty deep before the fractal finally gives up; numbers on a computer only have so much precision.

The entire code for it (which is small), can be found here: https://github.com/BadgerBadgerBadgerBadger/smooth-mandelbrot

Let's talk about how it works and why it is so much smoother than the previous version (though not as smooth as I would ultimately like it to be).

Divide and Conquer

Web Workers allow us to run honest-to-goodness OS threads and offload tasks to them. My main goals for my worker threads were:

Free up the main thread for processing user input.
Break up the rendering task between multiple workers to speed it up.

We start with the sketch.js as our entry point.

We set up a canvas, attach a click and keyboard listener, and add it to our DOM. We also start the painter.js worker which, as the name suggests, will be doing all the work of painting our canvas. And then we send a setup command to the painter asking it to set everything up and do the first paint.

The interesting bits here are

const offScreen = canvas.transferControlToOffscreen()

and

const message = {
    message: 'setup',
    canvas: offScreen
}
const transfers = [offScreen]

First, we transfer control of our canvas to an offscreen version which we then send to our painter. We are detaching the painting part and the displaying part. Though the canvas is still part of our DOM and displayed as such, the painting is done by the painter in a different thread and the results show up automatically. Also note the function call we make to send the offscreen canvas to our painter worker. That second parameter is an array of Transferrable objects to send to the worker.

Transferrable objects, in short, are those that you can send to a Web Worker and it will be a true memory transfer. The sending thread loses reference to the transferrable (if I try to do anything with offScreen after this bit of code, I will get an error), and the receiving thread assumes full control.

Which is exactly what we want-- we let the painter do the job of painting so our main thread is free to interact with the user. It does so in two ways. A mouse click event and a key type event. I won't go into the code of those. They aren't very interesting or pertinent to this article. Let's just say, they work and they send a draw command to the painter with some parameters.

There is a lot going on here but we need not focus on all of it. Let's look at the interesting bits.

First, the setup. I'm assigning the canvas and its context, retrieved from the setup event sent by the main thread, to the global variables for the painter. Then I start divvying up the tasks. I decided, somewhat arbitrarily, that I want the task of painting to be broken up into 8 parts. I'm sure there is a way to figure out what the optimal number should be, but I just decided to go for 8. So I create 8 acolytes. These acolytes get only a portion of the canvas to work on. I'm slicing up the canvas into 8 vertical slices. We need to know the width of each segment: segmentLength = canvas.width / numOfAcolytes.

Note that I'm not actually slicing up the original canvas. Instead, I'm creating baby canvases, each given to one of the acolytes. Later, once the acolytes have drawn on one of these canvases, we will take the resulting image and paint it onto our main canvas. I hope this analogy of a master painter and their acolytes provides a good analogy for how this process works.

Something I should have talked about much earlier is that the Mandelbrot Set lives somewhere between -3 and 1 on the Complex Line and -2 and 2 on the Real Line. Since the canvas is hundreds of pixels wide and similarly high, we need to map these values from a large range into a smaller one. Which is easy enough to do with a simple map function.

But the acolytes, unless they know exactly by how much each of their canvases are offset from the main canvas, won’t do this computation correctly. Hence, we need to provide them with this info. They also need to know the dimensions of the original canvas so we send that in, too. Furthermore, they need to know what range they need to map their canvases to. So we also pass in the ranges for the x direction and for the y direction.

Most of this info is only sent during setup. We don't change the size of the original canvas or the number of acolytes (and thus the width of each acolyte's segment) during the lifetime of the app. Only the boundaries change when we pan or zoom and we send this information when we issue draw commands.

So let's talk about the draw command, our second case in the switch-case. When receiving a draw command, the painter could receive mouse or keyboard events from the main thread. We allow users to pan the canvas by clicking on a point in the image and we pan so that that point becomes the new center of the image. The if (mousePos.x !== undefined) { block of the if statement takes care of this. I won't explain the math here. Suffice it to say, that based on the position of the mouse click, we adjust the boundaries. Similarly, in the } else if (zoomBy) { block, we adjust the boundaries so we are zooming in/out of the image.

Either way, once the new boundaries are computed, the global xBounds and yBounds variables are updated and the draw function of the painter is called. This is a really simple function that sends the boundaries and number of iterations to the acolytes and asks them to paint their pieces of the canvas. The acolytes do that (we'll talk about that next), and send these images back which we capture in the onAcolyteMessage function. We know which acolyte sent the image, hence we know which piece of the canvas they were given and we paint the image onto the canvas at that place.

Note, I am not waiting to collect all the responses from each acolyte for each draw command before updating the canvas. That would probably lead to smoother looking updates. Right now, if you pan or zoom quickly you can see the update happening in bands as each acolyte draws their portion of the image.

The code for the acolytes is quite simple as well. In the setup command we capture the canvas and context for drawing and we capture the boundaries. And then it draws once. Further, when it receives more draw commands, it updates its knowledge of the boundaries and draws its part of the image again.

The draw function itself isn't very different from what I've done in previous versions of the generator. Iterate over the pixels, map it into the correct range, figure out if it is part of the set or not and color accordingly. It then gets a copy of the image from its canvas and sends that to the painter (again via Transferrable). It seems while a normal canvas can have its drawing part detached and in a different thread with updates to the drawing appearing on the canvas, the same is not true if you use an OffscreenCanvas instance. This is still an experimental API so it will be really interesting to see how it develops.

Note: You might have noticed that the acolytes are receiving maxIters as well. Currently they aren't doing anything interesting with this variable. I've set it to a fixed value and it stays there. I could potentially play with it but I don't want to.

And that's mostly it. I have a main thread which kicks everything off and then handles user input and sends to the painter. The painter decides the image boundaries based on user input (panning/zooming), and then offloads the drawing of sections of the canvas to the acolytes.

Hope you enjoyed the post. Feedback is appreciated.

Updates

@lovasoa was kind enough to contribute several optimisation updates that make smooth mandelbrot worth its name. These include but are not limited to:

Using Uint8ClampedArray in the Acolytes for setting color values and passing that back instead of the heavier Canvas objects. Additionally with the non-standard OffScreenCanvas not in use the demo actually works on more browsers.
Inlining a lot of the Complex math.
Introducing a mouse-based scroll.
Flooring numbers using a bitwise OR operator that looks like black magic.

I'd recommend taking a look at his PR to get a feel for the changes.

Yet Another mTLS Tutorial

Shaun — Fri, 12 Mar 2021 14:59:26 +0000

Originally published on https://badgerbadgerbadgerbadger.dev/yet-another-m-tls-tutorial/

I've come across many mTLS tutorials on the internet but none of them took me through the process, end-to-end, in a satisfying fashion. I hope to do in this tutorial is to start with the ideas of TLS and mTLS and conclude with an implementation you could reasonably productionize. Although we'll be using a Golang server as our backend and Traefik as our reverse proxy, these ideas translate to other technologies as well.

Let's Start with the Barebones

Serve Me!

In a traditional TLS setup, the kind you encounter every time you see that green padlock icon in your browser's address bar, it is the browser verifying the server's identity. When you go to a website you access it via an address such as badgerbadgerbadgerbadger.dev. If the website has TLS support (and if you encounter one in 2021 that does not have TLS support, seriously, don't use it), the browser will ask it to send over its server-side certificate in order to verify that the website is actually who it says it is. The website sends back such a certificate which has a CommonName (also known as a Fully Qualified Domain Name, or FQDN) field which should match the address you entered in the address bar. For https://badgerbadgerbadgerbadger.dev the returned certificate should have a CommonName of badgerbadgerbadgerbadger.dev. Your browser will see that the CommonName and the name in the address match and it will be satisfied that you are indeed visiting a website who is what it claims to be.

"But wait!" I hear you say, "Couldn't anyone send back a certificate with a CommonName field set to whatever?" Astute observation. Indeed, anyone can create a certificate, attach whatever CommonName they choose and send it back to your browser...

...except, they can't.

That's where Certificate Authorities (CAs) come in. These are organizations that have (allegedly) gone through rigorous audits and whose trustworthiness has been verified to an extent that if they say that a website is who it says it is, that's good enough for browsers to trust that website. And how does this process work, you say? We'll get to that when we get to the more hands-on section of this post.

Ti(m)e to Reciprocate

Alright, so web browsers know who the server is. The server can be trusted. But can the browser be trusted? Maybe, maybe not. But to make our use case more practical let's move away from the example of an end-user using a browser and move to two backend machines talking to each other. Let's imagine we have a traditional client-server architecture where Machine A needs to get data from Machine B at random intervals, and the way that Machine B has decided it wants Machine A to authenticate is Mutual TLS.

If you understood how a server identified itself to the client by using a certificate trusted by a third party, you're already most of the way to understanding mTLS: it's kind of in the name.

In mTLS (Mutual TLS) the server sends its certificate as usual, but the client has to send one too. Let's say Machine B (the server) identifies itself as machineb.com and has a certificate with a matching CommonName, that's one side of the equation. In order for the other side (Machine A, the client) to do its part, it also needs to obtain a certificate. This certificate doesn't have to have a specific CommonName. It doesn't have to be machinea.com. But if we're only using public CAs, the easiest thing for Machine A to do is to prove to a CA that they own machinea.com and then be issued a certificate for that CommonName. Machine B, on its end will know to expect requests from Machine A authenticated by a certificate that has the CommonName of machinea.com.

Are there other ways to do this? Sure. Machine B could host its own CA and issue a certificate to Machine A. That way Machine B knows exactly what to expect since it's the one that issued the certificate.

I'll end this section with a link to a really nice article that has some informative diagrams.

Let's Get Our Hands Dirty

It's time to get into some hands-on learning. Let's start with our backend.

Reflect Thine Headers

package main
import (
    "fmt"
    "net/http"
)
func main() {
    http.HandleFunc("/headers", headers)
    http.ListenAndServe(":6969", nil)
}
func headers(w http.ResponseWriter, req *http.Request) {
    for name, headers := range req.Header {
        for _, h := range headers {
            fmt.Fprintf(w, "%v: %v\n", name, h)
        }
    }
}

If you're unfamiliar with Golang here's what the above code does:

starts a http server on port 6969
responds with any headers sent to it

Feel free to implement this in your language of choice if you don't have the Golang toolchain set up. Once you have your backend running, let's move on to the frontend.

Curl It

❯ curl -H "heyo: mayo" http://localhost:6969/headers

What, did you think we were going to write some HTML and JS code? Do I look like I'm in a masochistic mood? Curl is good enough for our needs. If you don't have it installed, google (or your choice of search engine) is your friend.

If you managed to run that curl command and your backend has been running, you should get a response like this:

User-Agent: curl/7.64.1
Accept: */*
Heyo: mayo

As expected, we've had our headers reflected back to us. So far so good.

We could go ahead and implement mTLS right there in our backend Golang code but in a robust production system you want your concerns to be separated. Our backend shouldn't have to worry about TLS protocol stuff, so let's move all of that to our reverse proxy.

For our choice of reverse proxy there's always good old Nginx which has a straightforward way to configure mTLS. If you're feeling especially nostalgic you might even find yourself reaching for Apache where you can also configure mTLS.

But we're hip and cool (or at least we like to think so) so we're going to be using the (relatively) new kid on the block Traefik Proxy. I'm sure you can figure out how to install it, by yourself. Do that and come back once you've read up on Traefik's configuration management.

Traefiking

Back? Figured out how to load static and dynamic configuration in Traefik? Good, so here's what we'll be using.

Note: I'm using version 2.2.1, the latest (at the time of this writing) is 2.4.x, but I don't think there should be a big difference in our experiences using either one.

Static Config

## Static configuration
[log]
level = "DEBUG"

[api]
dashboard = true
debug = true
insecure = true

[entryPoints]
[entryPoints.web]
address = ":8089"

[entryPoints.websecure]
address = ":443"

[providers]
[providers.file]
directory = "path/to/dynamic-config/directory"

[accessLog]
[accessLog.fields]
defaultMode = "keep"

[accessLog.fields.names]
defaultMode = "keep"

[accessLog.fields.headers]
defaultMode = "keep"

Here's what's happening:

We're starting a dashboard where we can view our configurations
We're starting a web listener (regular http) at port 8089
We're starting a secure listener (https) at port 443
We're providing the directory where our dynamic config is stored (you can have a ton of dynamic config files and they all get merged into one big config)

Let's look at the dynamic config.

Dynamic Config

[http]

[http.routers]

[http.routers.traeifk-api]
rule = "Host(`traefik.local`)"
service = "api@internal"

[http.routers.mtls-tut]
rule = "Host(`server.mtls-tut.local`)"
service = "mtls-tut"

[http.services]
[http.services.mtls-tut.loadBalancer]
[[http.services.mtls-tut.loadBalancer.servers]]
url = "http://127.0.0.1:6969/"

Here's what's happening:

We're defining a router to route any requests that match the rule Host(server.mtls-tut.local). Any requests that arrive with the host value set to server.mtls-tut.local will get picked up by the router mtls-tut. The same is done for the traefik api (which is used by its dashboard).
We're defining a service called mtls-tut which load-balances to our backend server running at port 6969. In our router configuration we've defined this service as the one that should be serving all requests for server.mtls-tut.local

Now start Traefik however you prefer (docker, binary, whatever), make sure it can access both the static and dynamic files and you've pointed it to pick up the static config. If you did everything right Traefik will start up and print logs.

INFO[0000] Configuration loaded from file: /Users/shak/installs/traefik/traefik.toml
INFO[2023-02-04T10:01:47+01:00] Traefik version 2.2.1 built on 2020-04-29T18:09:41Z
DEBU[2023-02-04T10:01:47+01:00] Static configuration loaded {"global":{"checkNewVersion":true},"serversTransport":{"maxIdleConnsPerHost":200},"entryPoints":{"traefik":{"address":":8080","transport":{"lifeCycle":{"graceTimeOut":10000000000},"respondingTimeouts":{"idleTimeout":180000000000}},"forwardedHeaders":{},"http":{}},"web":{"address":":8089","transport":{"lifeCycle":{"graceTimeOut":10000000000},"respondingTimeouts":{"idleTimeout":180000000000}},"forwardedHeaders":{},"http":{}},"websecure":{"address":":443","transport":{"lifeCycle":{"graceTimeOut":10000000000},"respondingTimeouts":{"idleTimeout":180000000000}},"forwardedHeaders":{},"http":{}}},"providers":{"providersThrottleDuration":2000000000,"file":{"directory":"/Users/shak/projects/mtls-example/traeifk/dynamic","watch":true}},"api":{"insecure":true,"dashboard":true,"debug":true},"log":{"level":"DEBUG","format":"common"},"accessLog":{"format":"common","filters":{},"fields":{"defaultMode":"keep","names":{"defaultMode":"keep"},"headers":{"defaultMode":"keep"}}}}
...
...
INFO[2023-02-04T10:01:47+01:00] Starting provider *file.Provider {"directory":"/Users/shak/projects/mtls-example/traeifk/dynamic","watch":true}
INFO[2023-03-04T10:01:47+01:00] Starting provider *traefik.Provider {}
DEBU[2023-03-04T10:01:47+01:00] Configuration received from provider file: {"http":{"routers":{"mtls-tut":{"service":"mtls-tut","rule":"Host(`server.mtls-tut.local`)"},"traeifk-api":{"service":"api@internal","rule":"Host(`traefik.local`)"}},"services":{"mtls-tut":{"loadBalancer":{"servers":[{"url":"http://127.0.0.1:6969/"}],"passHostHeader":null}}}},"tcp":{},"udp":{},"tls":{}}  providerName=file

Traefik started with the static config we provided and then loaded the dynamic config. Let's make sure the dashboard is up. By default Traefik starts the dashboard on port 8080

If you see this page

Traefik is up and running. If we go to /dashboard/#/http/routers/mtls-tut@file

We can confirm that our desired configurations were picked up by Traefik. Note the empty TLS and Middlewares sections. We'll be filling those soon.

The final piece of this first part of the puzzle is modifying our /etc/hosts file and adding a new entry:

127.0.0.1 server.mtls-tut.local

Let's try curl again.

❯ curl -H "heyo: mayo" http://server.mtls-talk.local:8089/headers

Note that we are now accessing the http entrypoint of our reverse proxy and not our backend. Your response should look something like:

X-Real-Ip: 127.0.0.1
Accept-Encoding: gzip
Heyo: mayo
X-Forwarded-For: 127.0.0.1
X-Forwarded-Host: server.mtls-tut.local:8089
X-Forwarded-Port: 8089
X-Forwarded-Proto: http
User-Agent: curl/7.64.1
Accept: */*

All those extra headers are telling us that Traefik is successfully routing our request to our backend at port 6969.

Phew! All that work and we haven't even started on the TLS part of things.

TLS Time

First we're going to need a CA. You could go to the trouble of getting a certificate online. If you have two domain names you own, getting certificates from Let's Encrypt is an inexpensive solution. But for our tutorial we'll stick with our local resources. Let's make a CA!

Break Open that Bottle of openssl

Making your own CA is surprisingly simple (getting others to trust it is a different matter). You'll need openssl which should already be installed on your platform of choice but if it isn't, google is your friend, again.

Once you have it, it's time to make the most important decision so far: what are you going to call your CA? I'll keep things simple for myself and call mine mtls-tut.ca. Not very imaginative but it's been a long week.

The first thing we need to do now that we've decided a name is to create the Root Certificate. The Root Certificate is a Big Deal™. This is the certificate that will be acting as-- you guessed it-- the root of all certificates issued by our CA. Other certificates will draw their authority from this Root Certificate.

First, we need a private key.

❯ openssl genrsa \
    -out mtls-tut.ca.key 4096

The private key is basically a really big random number. We need to keep this number secret. Most CAs don't even keep these keys online. If it can't be accessed via a network it (probably) can't be hacked. CAs take the security of their private keys very seriously. In our case, we can choose to be somewhat lackadaisical about the security of our private key. I'm going to store it in a directory called mtls-tut and pretend it is guarded by digital pitbulls.

If you ran the above command you should see output like this:

Generating RSA private key, 4096 bit long modulus
..............................................................................................................++
.........................++
e is 65537 (0x10001)

❯ ls
mtls-tut.ca.key
~/mtls-tut ❯

With a key in hand we need to derive a X509 certificate. I will let you read up on what the X509 format looks like. For our purposes we need to know that the certificate is a collection of fields such as country, city, region, some others, and most importantly, the CommonName.

❯ openssl req -x509 -new -nodes \
    -key mtls-tut.ca.key \
    -sha256 -days 1024 \
    -out mtls-talk.ca.crt

You will get an interactive prompt asking you to enter values for the fields I mentioned above.

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:BE
State or Province Name (full name) []:Flanders
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:mtls-tut.ca
Email Address []:

Most of it is informational except the CommonName which is very important. Get that one right.

❯ ll
-rw-r--r-- mtls-talk.ca.crt
-rw-r--r-- mtls-tut.ca.key

We now have a private key and a X509 certificate for our CA. And that's enough to get us started on the next step: creating the server-side certificate. The process is very similar to what we did for the CA certificate with one key difference.

We'll start the same as before by generating a private key.

❯ openssl genrsa -out server.mtls-tut.local.key 2048

Next we're going to derive a X509 certificate from this private key, however, we will also sign this certificate with the CA key and CA cert we generated earlier.

To do this we first need a CSR (Certificate Signing Request). A CSR is a request that is signed by the private key of the server and submitted to the CA. If the CA is happy with it, they will issue a certificate based on this CSR.

❯ openssl req -new -sha256 -key server.mtls-tut.local.key \
    -subj "/C=BE/ST=AN/CN=server.mtls-tut.local" \
    -out server.mtls-tut.local.csr

The CSR includes the same fields we used to generate the certificate of our CA (I decided to include it as part of the command, this time, instead of starting an interactive session). In essence they serve the same function: identification of an entity, be it a server, organization, or other. In the CA's case there isn't any higher authority to authenticate it. It is the highest digital authority. For a server certificate, the CA is the higher authority that authenticates the server certificate. Since we have our own CA, we can sign our own certificate, giving it our stamp of approval.

❯ openssl x509 -req -in server.mtls-tut.local.csr \
    -CA mtls-talk.ca.crt -CAkey mtls-tut.ca.key \
    -CAcreateserial -out server.mtls-tut.local.crt \
    -days 500 -sha256

If we break down the command a bit, we'll see that we're taking the CSR as an input, accepting the CA key and cert, and apart from a few config options, outputting a X509 certificate.

Phew again! We have our CA and we managed to get some server certificates out of it. Can we see some TLS action already?!

Putting it All Together

Now we're going to talk to our backend via our reverse proxy using https. Instead of making the request to http://server.mtls-tut.local:8089/headers we'll be making it to https://server.mtls-tut.local/headers (the 443 is implied). If we try it right now...

❯ curl -H "heyo: mayo" https://server.mtls-tut.local/headers
curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.haxx.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

...curl is going to complain. If you visit the address in your browser you'll see:

If we go ahead and inspect the certificate that's being returned to the browser:

Hey, that's not right! We went to all that trouble to generate a server-side certificate but Traeifk isn't even using it! What gives?

Well, we give. I think. Never really explored that expression. We haven't configured Traefik to use our certificates, yet. Let's open up the dynamic configuration and add a few lines.

[http]

[http.routers]

[http.routers.traeifk-api]
rule = "Host(`traefik.local`)"
service = "api@internal"

[http.routers.mtls-tut]
rule = "Host(`server.mtls-tut.local`)"
service = "mtls-tut"

[http.services]
[http.services.mtls-tut.loadBalancer]
[[http.services.mtls-tut.loadBalancer.servers]]
url = "http://127.0.0.1:6969/"

[tls]
[[tls.certificates]]
certFile = "/path/to/mtls-tut/server.mtls-tut.local.crt"
keyFile = "/path/to/mtls-tut/server.mtls-tut.local.key"

We added our server cert and key to Traeifk's TLS Certificate store. Now Traefik won't have to rely on its default certificate and can serve up ours, instead.

Now let's try curling again:

❯ curl -H "heyo: mayo" https://server.mtls-tut.local/headers
curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.haxx.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

Dang it! It still doesn't work. Let's take a look at the browser:

Alright, at least it's returning the right certificate (and not some default ones generated by Traefik), but the browser and curl both still complain. Why?

Certificate Stores

Each install of an OS (Operating System) comes bundled with a store of Root Certificates. Remember that Root Certificate we generated a few paragraphs earlier that identified our CA and had all those fields about location and name? Every CA has Root Certificates that they distribute (not the private key, mind you, never the private key) once the CA has been deemed trustworthy. OSes and even browsers can choose to include these Root Certificates in their Certificate Store.

What this means is that when a certificate issued by one of these CAs to a server makes its way to a browser, the browser verifies if one of the Root Certificates it holds in its Certificate Store has signed this certificate. If that's the case, the browser knows the certificate can be trusted. Similarly curl relies on the OSes certificate store (it is entirely possible for your browser and your OS to have different Certificate Stores, though most, if not all, of the Root Certificates in their stores will be identical) to figure out the validity of a server certificate.

In our case our CA that we made five whole minutes back isn't known to either our browser or to curl.

Trust

One way to remedy that is by adding our CA's Root Certificate to these stores, but that's drastic. There's a reason those stores only have trusted Root Certificates in them and you shouldn't mess around with that.

What we can do instead is to tell curl to trust our CA for the duration of a specific request:

❯ curl --cacert /path/to/mtls-tut/mtls-talk.ca.crt \
    -H "heyo: mayo" https://server.mtls-tut.local/headers

Accept-Encoding: gzip
Accept: */*
X-Forwarded-Proto: https
X-Real-Ip: 127.0.0.1
X-Forwarded-For: 127.0.0.1
X-Forwarded-Host: server.mtls-tut.local
X-Forwarded-Port: 443
User-Agent: curl/7.64.1
Heyo: mayo

Et voila! Now the certificate returned by our server is trusted because we have explicitly told curl which Root Certificate to trust as the higher authority.

Finally, mTLS!

We're in the final stretch, only a little bit more, I promise.

Let's finally add mTLS to our reverse proxy. We start by updating our Traefik dynamic config, again:

[http]

[http.routers]

[http.routers.traeifk-api]
rule = "Host(`traefik.local`)"
service = "api@internal"

[http.routers.mtls-tut]
rule = "Host(`server.mtls-tut.local`)"
service = "mtls-tut"

[http.routers.mtls-tut.tls]
options = "myTLSOptions"

[http.services]
[http.services.mtls-tut.loadBalancer]
[[http.services.mtls-tut.loadBalancer.servers]]
url = "http://127.0.0.1:6969/"

[tls]
[[tls.certificates]]
certFile = "/path/to/mtls-tut/server.mtls-tut.local.crt"
keyFile = "/path/to/mtls-tut/server.mtls-tut.local.key"

[tls.options]
[tls.options.myTLSOptions]
[tls.options.myTLSOptions.clientAuth]
clientAuthType = "RequireAnyClientCert"

This time not only did we add a new section for configuring client-auth, we also applied that config to our router. Now our router should require some client certificate to be present. And if we try curling...

❯ curl --cacert mtls-talk.ca.crt \
    -H "heyo: mayo" https://server.mtls-tut.local/headers

curl: (35) error:1401E412:SSL routines:CONNECT_CR_FINISHED:sslv3 alert bad certificate

... we see that it is so. The server won't let us in unless we provide a client certificate. So let's generate one.

The Same Old Song and Dance

The process of generating a client-side certificate is identical to creating a server-side one. Remember how we made a private key for the server, made a CSR out of it, then got the CA to sign that CSR giving us the final cert? We're going to repeat the exact same steps, only this time changing the CommonName to client.mtls-tut.local.

❯ openssl genrsa -out client.mtls-tut.local.key 2048
Generating RSA private key, 2048 bit long modulus
............................+++
..................+++
e is 65537 (0x10001)

❯ openssl req -new -sha256 -key client.mtls-tut.local.key \
    -subj "/C=BE/ST=AN/CN=client.mtls-tut.local" \
    -out client.mtls-tut.local.csr

❯ openssl x509 -req -in client.mtls-tut.local.csr \
    -CA mtls-talk.ca.crt -CAkey mtls-tut.ca.key \
    -CAcreateserial -out client.mtls-tut.local.crt \
    -days 500 -sha256
Signature ok
subject=/C=BE/ST=AN/CN=client.mtls-tut.local
Getting CA Private Key

If all went well, we should have 3 new files:

❯ ll
-rw-r--r-- client.mtls-tut.local.crt
-rw-r--r-- client.mtls-tut.local.csr
-rw-r--r-- client.mtls-tut.local.key
-rw-r--r-- mtls-talk.ca.crt
-rw-r--r-- mtls-talk.srl
-rw-r--r-- mtls-tut.ca.key
-rw-r--r-- server.mtls-tut.local.crt
-rw-r--r-- server.mtls-tut.local.csr
-rw-r--r-- server.mtls-tut.local.key

Awesome! Now we need to ask curl to use these files when making a request:

❯ curl --key client.mtls-tut.local.key --cert client.mtls-tut.local.crt \
    --cacert mtls-talk.ca.crt -H "heyo: mayo" https://server.mtls-tut.local/headers

Accept: */*
X-Forwarded-For: 127.0.0.1
X-Forwarded-Port: 443
Accept-Encoding: gzip
User-Agent: curl/7.64.1
Heyo: mayo
X-Forwarded-Host: server.mtls-tut.local
X-Forwarded-Proto: https
X-Real-Ip: 127.0.0.1

We have successfully implemented mTLS! Break out da champagne...

...later.

We still have one last thing to do (I promise, this is the last bit).

Trust, Again

Eagle-eyed readers will have noticed that our Traefik configuration is trusting any certificate that we send. For curl to work we had to tell it exactly from which CA to expect the server certifcate. But our Traefik configuration is requiring any client cert. It's in the name RequireAnyClientCert. The problem with this being how easy it is to create your own CA and generate certificates. We just did it in a few minutes.

So in order to restrict Traefik to trusting only specific CAs we have to submit those Root Certificates into Traeifk's trust store and set the value of clientAuthType to RequireAndVerifyClientCert

[http]

[http.routers]

[http.routers.traeifk-api]
rule = "Host(`traefik.local`)"
service = "api@internal"

[http.routers.mtls-tut]
rule = "Host(`server.mtls-tut.local`)"
service = "mtls-tut"

[http.routers.mtls-tut.tls]
options = "myTLSOptions"

[http.services]
[http.services.mtls-tut.loadBalancer]
[[http.services.mtls-tut.loadBalancer.servers]]
url = "http://127.0.0.1:6969/"

[tls]
[[tls.certificates]]
certFile = "/path/to/mtls-tut/server.mtls-tut.local.crt"
keyFile = "/path/to/mtls-tut/server.mtls-tut.local.key"

[tls.options]
[tls.options.myTLSOptions]
[tls.options.myTLSOptions.clientAuth]
clientAuthType = "RequireAndVerifyClientCert"
caFiles = ["/path/to/mtls-tut/mtls-tut.ca.crt"]

If you curl again:

❯ curl --key client.mtls-tut.local.key --cert client.mtls-tut.local.crt \
    --cacert mtls-talk.ca.crt -H "heyo: mayo" https://server.mtls-tut.local/headers

Accept-Encoding: gzip
X-Forwarded-Host: server.mtls-tut.local
X-Real-Ip: 127.0.0.1
Accept: */*
Heyo: mayo
X-Forwarded-For: 127.0.0.1
X-Forwarded-Port: 443
X-Forwarded-Proto: https
User-Agent: curl/7.64.1

Well of course it will work! The certificates we're using for our client-auth was generated by the CA we've told Traefik to trust. But if we try to use a certificate generated by a different CA or change our Traefik config to trust a different CA for client-auth, this call would fail.

Verifying that last claim is left as an exercise for the reader.