I have long had a love/hate relationship with Ubiquiti. While I hold them as one of the best solutions in the prosumer/SMB market, personally I would never use them in Enterprise. They have a long, frustrating history in which every new hardware release is a public beta, and new code trains are a complete train wreck.

That being said, I quite like the Unifi Controller software, and I think it does an admirable job running my APs. Very full featured, dare I say even…”neat.” I first ran it on a (shudder) Windows server, then on a LXC, and now in a docker container. Progress! The APs, while mostly solid have also been victim to the bad software release quality.

Some innocence was lost, I think when after an update and implementing MPSK to consolidate my SSIDs. Then it just decided to randomly drop traffic off into different vlans. Because, that’s what I want my solution to do, the opposite of what it’s asked.

But, this section isn’t really about that. What inspires me to write a new article is something I think that’s really neat, or something that tripped me up and frustrated me. I’ll share those experiences in the hope of helping others, while at the same time venting in free tele-therapy. ;)

Fetch Me A Switch

While my fellow Gen-Xers and I work through the shared trauma of that title, lately I decided I wanted to buy a new switch. And I figured I’d give Ubiquiti a shot. I decided on the USW Pro Max 48 PoE. The specs are great. A bunch of 2.5Gb ports, PO+ and POE++ on the 2.5 ports, and four 10Gb modules. Just what I was looking for. It can also do L3, but I got it purely for L2 use. I don’t want the other bits and bobs you need for a “unified” solution thank you very much. OPNsense FTW.

I also really liked the idea of managing it in the Unifi Controller, especially because the mobile app is really well thought out. They also have this feature called “Etherlighting” which turns the front into a RGB wonderland. It’s quite a useful gimmick, in my opinion. You can have the ports light up different colors for speed, or for vlans. They even have a locate feature which makes the port you’re looking for glow bright white. I lowkey love it.

The AR feature of the app is kinda nifty too.

So I unbox it, rack it up and connect it to my current switch. As I don’t want to perform a hard cutover, and moving things gradually is my usual MO, a trunk is what’s required. So I start off with an access port, get the thing on-boarded, and that’s where my trouble began.

Note: if you’ve been working with Ubiquiti gear for a while, this may seem like common sense. This is about what might trip someone up after a lifetime in CLI on Enterprise gear.

Trunking Ridiculous

Ok, so let’s start off with…maybe I should RTFM’ed, sure. I’ve been doing this for a while though and the conventional knowledge for this kind of operation is console in, set the mgmt IP on the SVI of your choosing, set trunk allowed all with a native vlan of 1 on both sides. Or, if you’re using something that tags/untags do that. Pretty basic stuff. If you screw up, it’s trivial to break out the ol’ console cable and figure it out.
SSH in, and get going.

This was NOT my experience. Way more nuance here. A couple things.

• Keep a paperclip handy. There is no console port, no safety net. You screw this up and lock yourself out, you’ll be factory resetting it.

• Don’t lean forward and configure everything. Wait until you’re sure you’re all set.

• Once you factory reset, the certificate on the device changes. So you’ll have to remove it from the controller. Once you do that, the config cannot be restored. You have to start over. The “use mac to replace” is only for gear that has already been on-boarded.

• Once the IP is set by DHCP initially, the SSH user name/password is usually “ubnt”

• If the controller isn’t picking up the device you can SSH in and run:
  set-inform http://[IP]:8080/inform
This will force registration to be adopted.

• EVERY SWITCH PORT IS A TRUNK BY DEFAULT. It’s opt-out which is mind-boggedly insipid.

• Before you upgrade code go to the forums. More often that not there’s horrific bugs about real basic stuff. E.G. in 7.2 there’s a bug in which new vlans won’t pass traffic. Come on, you have ONE job, people.

• TURN OFF AUTO UPDATES!!!! You’ll thank me later.

Ok, here’s what tripped me up. On the IP settings, you’ll see this by default

Clicking on it, presents a warning followed by a list of configured vlans to choose from.

And I found that link to be incredibly useless. It didn’t explain that part at all in my opinion. Plus, I see the word “magic” in a document and I check right out. “Network Override” Meh. So let’s talk about it. With it unchecked, that’s basically the the SVI of VLAN1. So when I connect that to vlan 777 on the opposite switch who cares, we aren’t tagging at that point. Connections for days.

I misinterpreted that to be the DEFAULT VLAN for a trunk. Yea that’s not right at all. “Network Override” changes the vlan the SVI is tied to. Le Sigh.

So next, we need to go to the uplink port in the UI. To add to the confusion a bit, vlan1 has an SVI that you can’t turn off or remove. I can see the use case perhaps and maybe you can use it to SSH? I’ll be honest I did not try.

Now native vlan/network is doing double duty here. Instead of being separate commands like we’re used to, all ports are a trunk, with the native vlan acting as the untagged access. Thanks, I hate it. Perfect for the trunk, terrible for regular access as a standard.

When I want it to be regular access port, the phrasing here is also confusing. “Block All” isn’t blocking traffic persay it just means drop tagged traffic. Only allow untagged traffic like a friggin access port. (sorry some anger came through just then)

For something like an AP, i think it does make logical sense.
(I did rename vlan1 since it’s also named “mgmt” by default)

At the end of the day, all I had to do was set my IP, change the Override to the right vlan, and change the other side to the typical allow all/vlan 1 scheme.

Instead what I did was throw a totally undignified babyfit, invent new combinations of swear words and start a return process until I calmed down and figured it out. This is sometimes my process.

Conclusion

Ok with all said and done, after these issues I am happy so far with the switch and APs. I have negative interest in going further into the ecosystem, but for AP and L2 switching so far I like it a lot.

It really comes down to both code and hardware quality at the end of the day. Ubiquiti seems to be just barely functional with new gear/code most times, but for the stuff that’s established, as long as you know what to do and what to research I think you’ll be ok. The forums are an excellent place to start, and Claude/Gemini is a good way to get a summary of issues with code, and what’s the most stable.

Just keep it out of the Enterprise. There be dragons.

Until next time.

Intro and Musings

I’m going to keep this one short, I’ve already had a lot to say in the previous parts. We’re going to get into the install and some nuance to start with. I chose Fedora for reasons I already outlined, but if you want to use a different distro like Mint, that’s fine. As long as you use Plasma (KDE) as the DE, about 95% of what I go into here should be covered.

And don’t forget, Fedora upgrades its version every six months. KDE upgrades every quarter. If you want a lower tempo, go to KDE Debian, or Mint.

Note: Mint Or Debian will just have the default KDE. Any third party repos and the flatpack infrastructure will need to be installed manually.

Ok, let’s go.

We’ll Do It Live!

Once thing Linux DE distros are really good at is the live install. Basically, you can boot to the ISO and get a fully functioning DE environment to poke around in. It all loads from USB (or if you want to party like it’s 1999 a burnt disc) and into memory. It doesn’t involve your primary boot disk at all. It’s a great way to spend some quality time before making a decision. You can test out different spins this way as well if you like.

You can use Rufus, Balena Etcher, or the tool Fedora makes themselves. Both the tool and ISO can be found here.

Install And Setup

When you boot to USB, you’ll see this. Pick the first option.

When the Welcome Center pops up, click on “Install To Hard Drive”. Don’t proceed through the Welcome Center just yet, we’ll do that after install. Usually something like this is a waste of time, but not in this use case.

Onto Step 3. Some people like to dual boot, not me. Hot take, make the full commitment and “Use Entire Disk.” This is of course, destructive so ensure files you want are backed up first.

I would skip disk encryption on the next step unless you really have a use case for it.

On Step5, make your user account here. I would avoid making a root account. Your user will be an admin in the sudo group you can do everything from there. If you have a burning need to run as root, you can always do sudo su to elevate to root when needed.

On the review, you’ll notice that the default for home and root are “btfrs.” This is great as you can leverage snapshots to roll back the OS when needed. It’s a great little file system. It is a bit more write intensive than ext4, so it’s recommended that ext4 be used for secondary drives.

Install!

Welcome!

Once back up and logged in let’s work our way through the Welcome Center.

Go ahead and next your way through the prompts until you hit this screen. You absolutely want third party repos, so yes to this.

Feel free to click the link, but here’s what this entails. My understanding is that with KDE, this is a bit of an “easier” button.

After this, you’ll see “Discover” pop up about updates. This is the next thing you need to do. It’s a biggin’ so get going.

The update process apart from the download is surprisingly quick. I think you’ll find everything with Linux is so much faster than what you’re used to.

Feel The G…Force

Next step, let’s get those Nvidia drivers installed! If you’re AMD this obviously doesn’t apply to you.

There’s this useful guide on installing the drivers, but our Welcome Center action already did most of it. Still review it though, especially if you have Secure Boot enabled.

I’m going to assume you have a 2014 or higher card. Open up terminal (Konsole)
and run:

Fun Fact: Man, KDE loooooves the letter K. It means nothing from what I’ve read.
Krita, Konsole, Kontact, Kmines, Kfind, ketc, ketc, ketc. If it starts with K, KDE made it. And honestly, they’re really good applications.

sudo dnf install akmod-nvidia (answer yes at every prompt)

sudo dnf install xorg-x11-drv-nvidia-cuda #for cuda and nvidia-smi 

Reboot.

Open terminal, and run:

modinfo -F version nvidia

and the driver version should show.

For a bunch of other details run:

nvidia-smi

The last thing we’ll do in terminal right now is install the multimedia group.
Note: I noticed while doing this, the file size was zero. It appears as though our third party repo already did this part for us. Awesome. In case you need it:

sudo dnf group install multimedia

Mounting Pressure

Ok, let’s talk about mounting disks. This process is pretty different from Windows. Let’s take a look at my current drives. “Old” is an internal SSD, and “Fedora-KDE” is a USB drive. The orange symbol means that the drive is unmounted. If I click it, I’ll get an admin prompt to authorize a temporary mount for the internal drive, while USB should just mount.

Now that they are mounted, let’s look further.

If I navigate to the usb drive and expand the path I get:

Likewise with the SSD:

Now for USB this is fine. That drive will come and go. For the internal drive though I want that to be more predictable and also automount. Now there’s several ways to do this. We’ll try to stay out of terminal for this, so we’ll use the KDE partition Manager Tool.

First thing though, let’s create our mount folder for the partition. You may recall in other guides for server based use cases I always use /mnt as the folder. That’s simply a good standard. In truth any folder can be used. For this use case my base folder will be “disks” because that makes sense.

Most of / that’s not the home dir is exclusive to the root user, so you’ll need to open the folder as admin. Yes, you could use sudo to make the folder, but we’re trying to stay out of terminal for this.

Now, lets open KDM and take a look. I want you to look to the right of each disk, at the /dev locations. nvm, sda,sdb. These are not partitions they are the actual device locations.

If we take a look at the partitions on the right the nomenclature is sbd1, 2, etc. It’s the partitions we’ll mount and not the physical disks. I hope it’s a bit more clear about how Windows obfuscates this process.

Now obviously this disk is from my previous Windows install and I want to delete and reformat. You can unmount any locked partition by clicking on it.

Note: no action is performed until the end. You can back out or undo at any time before activating the changes.

Ok, I’ve deleted everything.

Click on “New” and create the partition. I’m using ext4 for my extra internal drives. I also change the permissions to “Everyone” for ease of use. Hit ok, and then “apply.”

Sanity check!

Now we have bright shiny new partition. Almost done. Right click the partition and choose “Edit Mount Point.”

I’d recommend using UUID as the ID, as it will never change. Change “Pass Number” to 2, all other settings can be left at default. Hit “ok.”

Look at that! Our old friend fstab. We’ll review that next.

After this is done, right click on the partition and mount it. The mounting should now persist after reboot. Let’s review fstab. We can see on the final line, there’s our new drive. Linux will use the this file to mount these drives at each boot or if you invoke mount at terminal.

Explore!

That wraps up what we need to get a functioning install and mount our extra disks. In the meantime explore this new OS! It’s a lot of fun to poke around and find all these new features you always wished Windows had.

Dynamic monitor dimming? Feature!

Volume controls in taskbar tabs? Feature!

A system and application fuzzy search feature that actually works and returns results without ads or other unrelated nonsense? FEATURE!

Badass wallpaper plugins? Feature!

And so much more.

Conclusion

What a ride. The next part will focus on applications. Flatpaks, Windows equivalents/workarounds and other neat OS stuff.

Until next time.

Intro and Musings

Ok, we’re about to get into it, but first let’s have a chat. Real talk. We’re all pretty damn comfortable when it comes to our long term OS choice of Windows. We know it, inside and out for the most part. Working with files, network shares, navigating the registry etc. Windows is the Cisco of the operating system world, in that we’ve been doing it their way for decades.

Just like with Cisco, the actual underpinnings of the OS has been hidden from you, abstracted away by a happy gui and in the case of Cisco, their proprietary shell. Let me explain further. I was a Cisco guy for a long time, and then had to work on my first Aruba switch. (this was about five years ago, things have changed.) I was totally lost. What the hell? A trunk is actually a portchannel? Tagged/Untagged, what madness is this?

And to top it off, why can’t I make a L3 Routed port with “no switch”? This was the one that threw me. Then my mentor Igor tells me “You’ve been doing things the Cisco way, here’s how it actually works.” The “routed port” is simply a SVI tied to a “hidden/reserved” vlan with bpdu filter turned off. Cisco just made it “easy” by obfuscating the logic to “no switch”. This was huge for me, eye opening.

My other equivalent is VMWare. Lots of obfuscation there too. When I started to use Proxmox, all of a sudden I felt “closer” to the hardware, and things made way more sense. It was the removal of the veil, an opening of the black box they want us in. The less you know, the more they can steer you where they want you to go.

Now the reason for this little screed is that I want you to be aware of this, of what power and new understanding Linux is going to give you. But understand this.

”With great power comes not knowing what the hell you’re doing at first, coupled with a fair amount of frustration.”

This is likely new to you, you will be uncomfortable, you will be frustrated, at some times you’ll be ripping pissed. Be prepared to challenge concepts you thought you knew, and make compromises for what you need to work. (at least to start)

STICK WITH IT. It’s worth it, and by the end you’ll be a better engineer and technologist for the effort. This will cover some of the things I think you need to know before we get into install and configuration, to attempt to mitigate those pain points.

File(damentals)

Ok, we need to cover some base concepts about the file system. There’s some stark differences from what you’re used to and the first one is how drives are handled. There are no drive letters. No A, no B, no C. (gasp). Join a support group if you need to, but get over the fact that there are none.

Remember that Linux is a system of files. And all files originate from root. Even drives. And root is: /

That slash is the core of the OS. Watch the below for the overview.

So, for example let’s say I’m at the terminal and I want to get to my Downloads folder. I would use: cd /home/nathaniel/Downloads/

Note that I have the root at the beginning of that command. If I omit it:

This is a mistake I make more often than I’d like to admit. Why the hell can’t I find that file?! Oh. Forgot to add root. Now there is a use case for when you don’t have to add root and that’s our friend tilde! ~ is the alias for “home” and that includes root.

It’s crazy important to note the case sensitivity. It matters.

Now if you’re already hyperventilating about the terminal, relax. A modern DE like Plasma greatly reduces the need to be in terminal, but to ignore it completely is foolish. It’s absurdly powerful, and you should get some time in it. I’ve covered this in my docker post, but here’s some basic commands.

pwd : where am I right now?
ls -la : list files where I’m at (or pointing to) and put them in a list and show
permissions/hidden files

cd: change current directory focus (don’t forget root!)

tab: not a command, the key. This is the unsung hero of Linux, autocomplete! You can
also use this to show all matches in a directory

du -h -d[integer] : what’s the disk usage for where I’m at, break it into readable
numbers, and how deep in the directory do we want to go?

So some examples: if I do du /home/nathaniel/ it will vomit out every file in the directory, including folders and subfolders. And the numbers won’t be easy to read.

If I do: du -h -d0 /home/nathaniel/ It will give me the space in readable numbers and the overall size of the folders.

And using d1:

Next, double dash help. (dumb substack shows it as one long hyphen)
After any command use double dash help to bring up the man page.

rm -rf: murder (delete) everything you tell me to, do it recursively, and force it. That little joke that’s the cover image of Part1? Yea, if you sudo that command, and simply do “root” you’re done. Bye-bye every file on the disk. And terminal has no recycle bin.

I warned about this in my Part2 about docker. ;)

Let’s finish with….

sudo: Look at me. I’m the captain now.

Your first user will be an admin, which puts you in the sudo group. Think of it as a more effective UAC in Windows. It is god mode in a command. Anytime the DE pops up asking for your creds, that’s sudo being invoked.

If you try and do a command in terminal that requires admin rights like dnf update, it’ll say you’re denied if you didn’t start with sudo.

With great power, something something.

Ok, let’s wrap this section up and we’ll talk more about mounting drives in Part3.

MSI, EXE, and BAT oh MY!

Let’s talk about installing applications. Those three extensions are now worthless to you. Yes, yes, WINE, (Wine is not an emulator)) we’ll talk about that later.

Windows has this “scavenger hunt” aspect to applications that we’re all just used to. Installing applications on Linux is so much simpler. Much like docker and the container repos, there are software repositories that we can just pull applications from. No hunting required. Let’s say I want to install “btop” which is a fabulous terminal task manager.

Let’s go to google, search for btop and then let’s not do any of that.

Instead, go to terminal and simply: sudo dnf install btop

Ok, let’s type “btop” into terminal now.

The first time I saw this method of installation, my concept of reality shifted just a bit. I don’t have to hunt for files? I don’t have to click “next” 10 times? Incredible. But not every application is in the default repo. Take docker for instance. With docker you actually add their repo to the OS and then you can install via terminal. And because the repo is present, updates to the non default applications happen through this method as well. Wild stuff.

About that command “dnf”. It’s the modern replacement for “yum” and manages installs and updates. Debian uses “apt”.

Dnf is nice because it collapses update and upgrade into one command, dnf update.
Apt is split into update and upgrade. The logic makes sense for the most part, install, update, remove.

If there are releases you don’t want, (I’m looking at you, Docker 29) you can exclude them from the update. For example:

sudo dnf update --exclude=*docker-*,containerd*

Now, there are exemptions to even this. Some applications can be downloaded as a whole file as .rpm files. (Debian uses .deb) Those use the local package manager to install. They are outside of the repo framework though, so will not get updated with everything else. It’s more manual of a process.

So while all this is great, there is an enormous caveat to be aware of.

Dependency Hell

When you install an application you also need its dependencies. Other files it need to run will be present too. Let’s take a closer look at btop. The package manager is telling you the extra files that it needs from the repo. The problem arises when a required dependency will break an existing application because it’s older or newer than what’s there. It’s a shared library, so this can be an issue. Or a certain kind of hell, I’m told. This is one reason why docker/podman is a thing. The applications and their dependencies are abstracted away into the container so it’s a non issue.

Windows doesn’t rely on shared libraries and has other file strategies that largely avoid this issue, but was a problem in the past with “DLL hell”.

Oh, SNAP

One of the solutions to this is SNAP (Ubuntu) and Flatpak (Fedora). These are containerized versions of applications that solve for the dependency issues. They are little sandboxes of happiness that keep the applications sequestered away and functional.

The main reason why snaps are a dirty word is that Ubuntu has a policy of auto-updating. Oh, you don’t want that snap updated? Tough shit it’s already done. You can defer an update to about 90 days from what I’m reading, but still. Canonical also owns and updates the snap store. Corporate decisions, remember?

Flatpaks however, are completely user controlled. We can still download apps from within the OS via the Discover app and you can look at the store externally at https://flathub.org/en. The flatpak store is totally community owned and curated. The interesting thing about flatpaks is that they are supposed to to be distro agnostic. In Fedora, the flatpak management/install tool is built in. You can install it on other distros like Ubuntu to get some control back.

There’s more nuance to each method, these are the broad strokes.

While many, many, apps you use today are available via Flatpaks not every one is a perfect fit due to the sandbox nature. We’ll get further into this in Part3.

Conclusion

I think that’s the bare minimum we need to go over before getting into the install. There’s other things I want to bring up, but I think it makes more sense to show in context as we go.

Until next time.

Intro and Musings

Well hello there! It’s happened, and I’ve moved to Linux as both my server and desktop OS in my environment. This is going to be similar to my Proxmox series where I document the journey.

That means this first part is going to be an explanation and exploration of why I made these decisions with some education along the way. After this, I’ll get into the technical weeds.

Hey, I like to tell a story and the blog is appropriately named. ;)

Up Until Now

For the entirety of my career, up until about five years ago I was hell bent for Windows.

Started with 98, and then eventually was managing and supporting large enterprise Windows AD domains. I went through every tick and tock release. I got certified, really learning the ins and outs of the OS, I even wrote a practical 75 page guide on imaging correctly with MDT.

But Linux was always lurking right out of sight. This was a dark magic, a witchcraft at which coders would pray at the black alter of the flashing white prompt. I didn’t have a use case, and at the time the Linux desktop experience was some rough business. Then as the years went on, Windows started to enter its true enshittification stages and my devotion to the OS started to weaken.

(Seriously who the hell puts a touch interface on a Server OS?!)

Fast forward to a few years ago and I’m talking to my boss Mike, and I’m complaining about how my Windows Servers were thirsty pigs. He says to me, he says “you need to look at Linux.” Then I went on about how confusing it was and how weird it was that it had no registry.

He got quiet for a second and said “Nate, Windows is weird because it has a registry. Linux is a flat file system, no one needs that crap.” Then when Proxmox came along, I had to learn some basics. I started with replacing my servers with LXCs for some of the applications I was running that used to be on Windows servers. Night and day difference. I was blown away. I was on the path from now on.

Distro Inferno

One thing about Windows is that the versions are largely easy to discern. There’s Desktop and uhhhh Server. Simple. There’s versions like Home, Professional, Enterprise etc but those are feature sets not actual different versions per say. I mean, it’s all “Windows.”

Oh boy, not with Linux though. It’s the Baskin Robbins of OSes. There.are.so.many. This is the first part that stops a lot of people. Paralysis of choice. It definitely stopped me for a long time.

To illustrate this, Linux consists of distribution “families”. I’m not going to list them all, but here’s the key ones.

Debian, RedHat/Fedora, Arch, Alpine, etc.

Now you can run those or their “derivatives.”

As for derivatives let’s take a look at Debian:
Ubuntu, Kali, Proxmox VE, SteamOS, etc.

And to make things even more confusing, some derivatives have their own derivatives!

Ubuntu has:
Mint, PopOs, Kubuntu, etc.

For RedHat/Fedora:
CentOS, Rocky, Nobara, etc.

I’m going to stop here, the list just goes on and on to infinity. Linux is less of a family tree than a bush. Let’s talk desktops and “spins.”

Spin Me Right Round

A spin isn’t a derivative. It’s a modification to one of the base OSes. It’s usually referring to the DE “Desktop Environment”.

Here’s some of the usual suspects for DE options:

GNOME (pronounced guh-nome)
Plasma
Xfce
Cinnamon
MATE

GNOME is the grandaddy DE, and the one that ships as default on many OSes. While you can install any of these manually it’s highly recommend you download a version with your desired DE baked in. A distribution like Debian offers your choice at install, while others offer discrete versions.

They all have major differences in how the desktop experience works. I definitely chose one, we’ll get into that shortly.

Server OS

I started with Ubuntu Server for almost a year. It was…fine, I guess? But it just seemed bloated with a bunch of things I didn’t need. It may be counter-intuitive to say a headless CLI driven could feel bloated, but even with minimal settings the install takes forever, and I find the installer to be a chore. I also wasn’t a fan of the yaml driven netplan for network configuration.

Then I found out about the whole derivative thing and my buddy Alex said “go regular Debian.”

I did, and I like it much better. The setup was simpler, install seems to be much faster and while Debian isn’t the fastest to get new features it’s rock solid. And that what I need from servers. Stability. Also the network config is pretty traditional, and not yaml based. So now all my servers and LXCs run Debian.

Desktop

So I did try Ubuntu for a while. The whole thing was very “meh” for me. I tried Mint. “meh.” I tried Zorin. “meh, again.”

Turns out I really don’t like GNOME, or Cinnamon. So I plugged along with Windows for another year. Then Windows 11 happened. And then Copilot. And then the really stupid “recall” feature. More and more it felt like I was renting my OS and not owning it. So much tracking. And then ads?! There’s a script from Chris Titus I was using to remove all this crap and while it worked, then the machine itself started to act oddly.

This nonsense runs so deep trying to mitigate or remove it just makes the whole thing unstable. I kind of sat back and realized if I need to go to these kind of lengths to keep my computer mine, it was time to be done. But where to go? I went to Claude and asked for advice.

My requirements:
Gaming support (long a difficult thing with Linux)
A Windows like desktop experience
The ability to run Windows apps if needed.
A general, all purpose machine that excels at overall takes.
And it came back with:

Windows 11.

I’m kidding. It said Fedora 43 with KDE Plasma.

My first reaction was what the hell is that?! I’d never heard of Fedora outside of Indiana Jones and Redhat. I went back and forth arguing with some other solutions like Ubuntu, PopOS, etc.

And it came back with YOU WANT FEDORA YOU ARGUMENTATIVE FOOL.

(I may have given Claude instructions to not sugarcoat responses and just tell me what I want to hear.)

And it was right. This is the way. For my Linux journey I’ll use the base OS, no derivatives. So that means Debian for servers, and Fedora for desktop. Now why a separate foundation for each use case?

Simple.

Debian is the slow but steady guy. Stability is key. Major updates are years apart. You’ll get bug fixed as point releases, and constant security updates. Perfect for servers.

Fedora is the one that supports modern hardware. It updates every six months. It’s the racecar of the two. For my desktop, that’s the ideal place to be for me. One of the key reasons to choose Fedora over something “easy” like Ubuntu is that Canonical owns Ubuntu. It’s a corporate product that makes corporate decisions. As an example of those decisions we’ll get into “snaps” in part two and why for many it’s a dirty word.

Fedora though, is almost entirely community driven, though sponsored by RedHat. There’s a whole internal governance structure to ensure that Fedora sticks with the user base, not the sponsored overlords. These days that’s probably as good as it’s going to get. This was a big reason I made the choice for Fedora.

Conclusion

That about wraps it up for this one. I hope my explanation and reasoning provides some insight into the whole situation. The next part, we’ll get into install and covering what tripped me up and the main differences from Windows.

Until next time.

Intro and Musings

So in Part 3, I discussed adding a secondary IP to allow a service to exist on the same Docker host, with the same port. And hey, that worked great. Up until it had to cross my firewall zone. This was fun (haha), so let’s discuss it.

Zoning Out

Ok, so let’s say we’re on the same L2 network and trying access WUD as in the previous article’s example on the secondary IP.

No issue. Life is good. But, when we want to cross vlans across a firewall zone, say from DMZ to Prod, things go sideways. With a secondary IP, we share the default host bridge, so any inter vlan traffic needs to out the primary IP, (where the default gateway is) where it NATs and then presents traffic that doesn’t match the source session, which gets dropped/blackholed.

Driving To A Solution

Docker networking is intensely interesting. There’s a solution here, and that’s using a different network driver. There’s several, but we will cover three.

bridge: default, secondary IPs configured on the host. Issues on the intervlan/firewall flows as shown above.

macvlan: this driver will actually act a separate interface in docker and give the clients in the network their own mac addresses. Requires your hypervisor support promiscuous mode for the extra macs coming from one port. This fixes our traffic issue.

ipvlan: this driver will actually act a separate interface in docker and will use the same mac address as the parent interfaace. A good alternative since its the same mac coming out of the port. This also fixes our traffic issue.

With both ip and mac vlans, the network is defined on the stack/compose and not on the host interface. It’s only active when the container that has the network configured is up.

Driving Into a Brick Wall

So great, right? Let’s configure the ip/mac vlan and go about our day. Not so fast. There is a huge caveat we need to cover. A better name for this feature is mac/ip vrf.

When a container is configured with the vlan option, it cannot talk to any other container on the same host. So if you’re you’re using a proxy that talks to other containers on the same host, it’s not going to work. Traffic leaving the host is unaffected. Also unaffected are any tools that monitor docker socket.

So my situation was that I have a proxy in my DMZ and a Cloudflare tunnel. I need NPM to use a vlan driver but I also need to be able to talk to the CF container as well. Luckily there is a solution. We’ll use the same driver for each.

Configuration

OK, the driver config can only be on one container. Let’s see what that looks like.

Notice that even though we’re using a parent interface, we get our own default gateway for this traffic. This allows us to not have to NAT out the bridge driver. We can use the same network as our parent, just make sure the IPs are unique on the network.

Once the network/gateway is configured now we actually set the IP under the service section. Once this is deployed, you should be able to ping that new address. As the note says there are no ports to expose, it’s all open.

Here’s what it looks like together.
NOTE: volumes and other settings are not in the examples

Sharing The Love

Ok, let’s add our other container. We set the network, but as external and we map to the name of the vlan network.

Look in Portainer networks or via sudo docker network ls

Then under the service we define the IP of the container.

Lather, rinse, repeat for any other containers that you need to talk to each other. If you want/need to use ipvlan instead simply use “ipvlan” as the driver. The documentation suggests ipvlan is the better way to go as well. But for home enterprise? macvlan is fine provided your hypervisor supports promiscuous mode on the vswitch.

Proxmox seems to have it enabled by default.

ip -details link:

There’s also other drivers, where you can tag traffic, L3 IPVLAN, etc. That’s way out of scope for my use case, so but there’s extensive documentation here.

Conclusion

Well, this was a journey well worth taking. The vlan bridge drivers are really useful when homing the same services with the same port on the same host. But the use case needs to carefully planned for, due to the natural isolation between drivers. But there’s a use case for mac/ip vlan, secondary IPs on the bridge driver, it’s up to you.

The flexibility of what Docker gives us is what makes the application so useful.

Until next time.

I might have a container addiction. I think I’m up to 40 or so. But, man what a ride. My Docker journey has been amazing and I’m so close to where I want to be. But you know what’s not fun about containers? Logs. Man, that’s tedious. Whether it’s Portainer bouncing you out of a log after you restart a container, or trying to avoid going blind by staring and trying to parse out the logs via CLI…BLEH. Once again, the universe provides with Dozzle.

Dozzle!

Ok so what is Dozzle? It’s a container (shocker) that simply streams the logs from other containers! It doesn’t store them, it streams. And you can search them all at once via regex, regular text, and I think sql or some such madness. And it also has a agent mode so you can streamline it all to one GUI.

Here what it looks like:

So the top one is the host the GUI is on, and the three “satellites” is where I have agents reporting. Right off the bat, it shows container stats, which is rad. Let’s search real quick, using the “search” under the lil Dozzle bug. This will return containers.

Now if I click on that container, in the upper right I get a menu. It’s a bit vague that it’s there. There’s a lot to use here.

In the search menu, you can filter and search the current log as well.

That’s awesome, but check this out,

You can get ALL the logs in one live, searchable view. But wait, that’s not all!

YOU CAN STACK MULTIPLE CONTAINERS IN ONE VIEW FROM DIFFERNT HOSTS!

And you can pin containers as favorites…

Finally in the settings...

Seeing the logs of containers that are stopped is actually surprisingly useful.

Ok enough gushing, let’s get into the stack configs.

Config Time!

Ok, my setup is fairly simple. I did find the agent config to be a bit confusing at first, so I’ll show both examples.

Full details with all options are here: https://dozzle.dev/guide/getting-started

Let’s split this into sections.

NOTE: I’m using WUD for updates, so I use tagged releases. Feel free to replace with “latest” if that’s your jam.

Pretty basic, though I changed the sock to be RO. I don’t have a need or want in my use case for any actions by Dozzle.

For the environment variables, see the remote agent section. The agents are comma separated. As of right now Dozzle doesn’t like starting if the agents aren’t reachable so maybe set them up first.

AGENT CONFIG

The agent config is pretty straightforward. Note the port and “agent” command.

Full examples are on my GitHub.

Conclusion

Not much more to say, apart from finding a solution that meets another need I had. Pulse for detailed host usage/alerts, Kuma for easy uptime alerts, and now Dozzle for easy consumption of container logs! I think the only thing now missing is some way to gather all the patch information in one place about all my Linux hosts.

I don’t know, sounds like Rambling Nonsense to me. ;)

Until next time.

Intro and Musings

Well hello there! Doing a part three on this kind of surprised me, but as I learn new things I like to put fingers to keyboard and further document my journey in the hope that others will also find it useful. I think that this may be one of the more important posts I've made as it will highlight a nuance to the docker solution that isn’t as obvious as it should be.

So let’s start off with the use case that brought us here.

Making A Case

Ok, so. I have my one docker host at 10.0.0.10. I have about 35 containers and they all use the standard host:container convention to make the resources available. I’ve never seen a different convention, in any other compose, ever.

So at 10.0.0.10 I have WUD on port 30010 and NPM (Nginx Proxy Manager) on port 443. I have the same setup on 10.0.0.11. My eye in the sky, Uptime Kuma keeps tabs on everybody for downtime notifications.

So, lately I’m been having an issue where across vlans my firewall is having issues sending traffic to the right destinations where the FQDNs have the same IP and causing havoc with my firewall rules due to some dopey DNS cache.

For example, abs.nscriven.net and pulse.nscriven.net both go to Nginx at 10.0.0.10. So my initial solution was to build another docker host, just to proxy that IP from a unique address. A total waste of resources and a major PIA as now I need to duplicate WUD, DNS entries, Proxy entries, blah blah blah. But I did it, because my son was on me because he couldn’t access these resources externally. (Home Enterprise, remember ;) )

So I did this as a stopgap measure. I told my buddy Alex (who I work with) about this and he told me, “why not just use a second IP on your first host and use that for your conflicting containers?”

Me: /dumb look…”I didn’t know I could do that.”

IP Address Value Meal

Ok, so adding the secondary address on the same vlan is really easy it turns out. For Ubuntu, you edit netplan, and add a second address under the first and then save and “apply netplan”. They should respond to a ping right away.

So my thought was, I’ll decom 10.0.0.11 and add that IP to the 1st host, light up Nginx and profit. I won’t have to redo firewall rules, DNS, etc. So the new design looks like:

Note: There’s more other ways to this with macvlans, we’ll cover this in a future post.

So now I have this plan, right? How do I get it done? Well it turns out you can bind containers to IPs! The convention is IP: host port: container port.

And it worked! Now it’s important to note in this fashion I did not make a new bridge, this is a 1:1 mapping to the new IP. No other containers will use this combination. It’s a very specific use case for a very specific problem. I replicated it for another service for the same issue to great success.

System Of A (Not Going) Down

So…my task completed I waited for Kuma to send my glorious down alert for WUD, since that container no longer exists on 10.0.0.11 as a host. And….it didn’t arrive. I check Kuma, and it is willfully, defiantly, mockingly GREEN.

This didn’t make sense…WUD isn’t configured on .11, just .10! Why is it still up?! Then something hit me based off some other conversations I had seen on Redditt recently. And it has to do with the way docker does networking, and the arguably sloppy way developers make compose files.

The Tyranny Of The Default

So, if you have one IP on your box I’d say what follows isn’t likely a concern but the education is important. It is disturbingly easy to be so enamored with a technology like Docker and not realize you’re glossing over important nuance because it feels like magic when it works. So let’s shine some light here.

When you see host:container, what you’re saying is that those ports can be reached BY ANY IP ON THE BOX. To put it another way:

0.0.0.0:host:container

Now, I’ve seen that stated elsewhere and scoffed “why does that matter?” I WANT the port to be reached. That’s the whole point.” And the scoffing wasn’t just me, many others were making this flawed logical assumption.

I work in the security space, and once I saw this in the flesh all of a sudden everything made sense. What was happening was WUD was now reachable over port 30110 from BOTH IPs! I call this “unintended access” in my opinion there is no greater sin than unintended access, and even worse when you did it unknowingly.

If I wasn’t such a control freak and treated my network as pseudo-Enterprise I would have NEVER have known about it. Here’s what this now looked like.

The plan was in no way, shape or form intended for this type of access. But there it was. Now, I’ve seen people say:

• Put it behind a proxy, who cares

• Don’t you have a firewall?

I don’t like these arguments. I have both. People forget L2 is a thing, and segmentation at L2 is complex and expensive. If I am exposing anything, it must be intentional, and the risk/tradeoff fully known and understood. Security is in layers and it starts as close to the resource as possible and radiates outwards with other controls.

So this must be fixed. Luckily it’s simple.

The Fix Is In

Ok so the cardinal rule here is, if your box has one IP, host:container is likely fine. (I’ve seen arguments that 127.0.0.1 can be a concern but I’d need to see a use case) But the second you add any network resource every.container.forevery.port should be tied to an IP, even the first IP on the box.

So for WUD I updated my compose to 10.0.0.10:30010:3000. And then Kuma gave me the down alert I was looking for. I then repeated this for every container on that box to ensure access I wanted was intended and narrow.

Also, in Portainer you may have noticed your published ports section when clicked on, always sent you to: 0.0.0.0:[port]. Binding in the compose file fixes that too, for some added convenience.

Conclusion

So I hope I’ve properly communicated the use case, resulting issue, and fix. This is one of those things you find by accident; or are knowledgeable about due to time and study because you’re an expert. Think if you’re running a container in a VPS or shared environment that has more than one IP and you’re unwittingly exposing a service to the outside world in a way you didn’t intend or protect for. For me, it’s a re-dedication to learning more about the solutions I use in my Home Enterprise and paying more heed to peers that may be trying to say something important.

Until next time.

When it comes to Docker, there’s three main “legs of the stool” I’ve been concerned with and learning about solutions for. Despite my best efforts, I’m not a CI/CD automation guy. I just haven’t found the spark to really ignite my interest yet. So my solutions are a bit more traditional at this time. If I do have that “AH HA!” moment, I’ll cover that revelation here. As always, you’re welcome to comment and point out better ways to do things that maybe I didn’t realize/think about.

1. Management/deployment - Solved for now with Portainer

2. Updating containers - Solved for now with WUD, the point of this article :)

3. Backing Up Containers - this is on my list. Most of my docker hosts are on VMs,
   which takes care of the backup inherently with Proxmox Backup Server. I do have one physical host for my ZWAVE container/Frigate so that needs to be taken care of.

WUD - What’s Up Docker

So what is WUD? It’s a container, purpose built to update other containers. There’s other solutions out there, like Watchtower but I keep hearing about WUD. I really do like a functional GUI for things and while it is very compose/stack heavy it does the job quite well. But man, are there nuances to this solution. And the documentation, while decent really glosses over some key points in my opinion, which makes the use more difficult. I actually had a false start about six months ago and dropped it after getting frustrated.

I moved to the free license of Business Edition for Portainer, which shows when there’s an update available but over times that process got very tedious so I picked WUD back up and figured it out.

My goal, by the end of this article is that you'll be able to effectively have WUD monitor, update (either automatically or manually) and notify you of changes. Before we get going though I think we need to talk about repos and registries. We’re going to handle our containers in a much different way than maybe you're used to.

The Repo, Man

Ok so what’s a repo/container registry?

Repo: source code, documentation, issue tracking, E.G, Github,Gitlab
Container Registry: Stores pre-built Docker images (binaries)
E.G. docker.io/syncthing/syncthing

There’s several registries out there, and let’s look at what that means. In your stack/compose it’s the prefix. For FOSS apps, these are the three I primarily see:

• Docker Hub: docker.io/ or none

• GHCR: ghcr.io/ (GitHub’s registry, free, integrated with repos)

• LinuxServer.io: lscr.io/ (LinuxServer’s own registry, with repos on Github )

So for example some of my containers:

docker.io/jc21/nginx-proxy-manager
syncthing/syncthing
ghcr.io/lukegus/termix

See? I have two different prefixes since no prefix and docker.io are identical. A good rule of thumb is to use the prefix that’s in the compose example for their documentation.

From what I understand (and am probably not 100% right on) is that each one has a reason why devs use one over the other. Workflows and such. It’s all witchcraft to me.

Most projects use GitHub for documentation regardless of which registry hosts their images. Next question, why the hell do I care about all this?

Because, when it comes to updating dockers, we need to talk about “latest”. This subject turned out to be quite the rabbit hole.

Latest, This Just In

When we’re using our containers, the format is:

registry/container:tag

So for the most part, setting the tag to be “latest” is the best practice. This allows the developer to essentially control the version you run. They will set a tag of “latest” to whatever numbered version they prefer.

But, you can also set a tag to a specific release like:

ghcr.io/homarr-labs/homarr:v1.43.0 or
ghcr.io/rcourtman/pulse-docker-agent:4.26.2

Note: see one of those values has a “v” in it. We’ll come back to that.

I posit that if you’re not doing any kind of utility like WUD, latest is fine, but you may find you’re updating pretty frequently with no real feedback. Even in WUD with latest you won’t see what version, just the new SHA value. I’ve learned not to like that so I’ve largely moved to a specific version tag. I like seeing exactly where it’s going.

Note: When we set the tag like this and use WUD to update the container, we effectively “orphan” the compose/stack in term of versions. You can get well ahead of the compose/stack over time since WUD updates the container, not our deployment file. So if you go and update your compose/stack and redeploy you should update the number to what you're currently running. If you forget, WUD will definitely remind you. Example:

If I deploy this, 1.1.2 will replace 1.2.2. When WUD detects it, it will notify you’re out of date and you’ll feel silly. Better to make them match.

In comparison, latest can include breaking changes, deprecated features, config changes, updated dependencies, digest updates, etc.

Here’s an example.

I’m using a semver tag to specify the version. WUD shows me what kind of update it is, and old>new. I also have a template that will take me to the Github for the patch. We’ll cover that later.

Note: Semver: follows the format: MAJOR.MINOR.PATCH (e.g., 2.4.1)

Using a tag with version shows a nice progression.

If the tag was “latest” is it would not show a version progression, but just the SHA. Eh, I don’t like it.

So how do you know what tags are available? For most projects, look at their github under releases.

Now if you click on releases, you’ll also see a tag button.

Now remember the v? If the v is there, usually you’ll need it. If you try the v and it doesn’t pull the image, try it without it. I’ve ran into some projects where the semver format was a bit funky.

Now one thing you should absolutely do, is subscribe to all the projects you follow for releases updates at the very least.

This way, you’ll get convenient email alerts about the details.

USING WUD

Ok, let’s get to it. So this app is very powerful and the documentation is decent, but can be confusing. There is no GUI config, just a GUI result of the compose/stack config. Everything you can configure is in the compose/stack.

Let’s take a look at my WUD stack in stages. Examples will be on my Github.

Pretty much by the numbers here.

It’s the environment variables that matter here. You primarily have Registry, Watchers, and Triggers.

Registry:

There are a number of ones that are built in, these are where WUD will pull updates from.

For dockerhub, there are a limited amount of pulls you can do on an anonymous account per day. Make a free account, spin up an API key and use it in the compose/stack. The limit is far higher.

- WUD_REGISTRY_HUB_PUBLIC_LOGIN=
- WUD_REGISTRY_HUB_PUBLIC_PASSWORD=

Watchers:

This is how often WUD polls for updates, don’t leave this as default you’ll burn through your pull requests even on an authenticated account. I set mine for every six hours.

- WUD_WATCHER_LOCAL_CRON=0 */6 * * *

Triggers: This is the fun stuff.

- WUD_TRIGGER_DOCKER_UPDATE_AUTO=false

Set to true to autoupdate, but set to false and it provides the button for manual actions.

- WUD_TRIGGER_DOCKER_UPDATE_PRUNE=true

Will auto delete the old container on update.

- WUD_TRIGGER_APPRISE

This is to setup our notifications with Apprise. Lots of other options, this is what I use. We’ll cover this soon.

LABELS

Now if we leave these at defaults, WUD will work but it’ll be messy. Let’s use labels to tell WUD exactly what to do. Now, we will place these labels on every container including WUD itself.

wud.tag.include: ^v?\d+\.\d+\.\d+$

So this is regex, and should work for most use cases and only alert of updates in standard semver context and not sha digests and other stuff. If you know there’s an update and WUD isn’t catching it you may need to tweak this. This should also account for the option of “v” at the beginning of a tag.

wud.link.template: https://github.com/getwud/wud/releases/tag/$${major}.$${minor}.$${patch}

This provides the link in the WUD output for release information. Change to the link of the container’s tag page if it exists. Not a requirement, just convenient.

Now for the containers, you just need the labels. It’s a pain to go back and retroactively edit all the containers for labels and tags, but I think it’s worth it.

Now there’s some oddballs like Exalidraw that doesn’t have anything other than latest so I went another route. That should keep me from pulling down weird intermittent releases.

wud.tag.include: ^sha-[a-f0-9]+$

Notifications

Okay, so. Lots of options here. I use Apprise to send to Home Assistant.

I cover that here:
Home Assistant Notifications With Node Red

I also cover setting up Apprise here:
Notifications for Audio Bookshelf Using Apprise and Home Assistant

Now the neat thing here, as I found out with Uptime Kuma is that I can use the exact same notify URL that I use for Home Assistant anywhere! In hind sight of course you can, but give me break. :)

So an example trigger for this:

- WUD_TRIGGER_APPRISE_MYNOTIFY_URL=http://10.0.0.x:32768
- WUD_TRIGGER_APPRISE_MYNOTIFY_CONFIG=abs

Set the IP/Port for Apprise and and the config path. Every app does this part a little different by the way. When this is deployed, you’ll get an entry in the GUI along with a very handy test button.

Let’s fire off a test alert. If it doesn’t work make sure you check your WUD logs.

Ok, it works but that’s hella wordy. I want to shorten it, and add some identifying information so I know which WUD box it’s coming from and provide something unique to grab in Node Red so I can send the message to my phone.

Note that I have “WUD Prod” and a bunch of variables, let’s see what it looks like now.

To Node Red!

Here’s my current setup for Audio Bookshelf/Kuma

I’m going to slap a debug node onto the Apprise node and fire off a notification.

Ok I need to make a new switch node, as I’m pulling from payload.event.service_data.title, not message.

Now, I’m going to make a new action node with some custom json. I used Claude to help with this.

See: Not A Programmer.

My flows now look like:

Let’s fire off an alert…

Oh, and here’s my oddball. *shrug*

Conclusion

Ok, that was a lot. I hope by the end of this you have a working configuration that works for you. Now this is the way I do it. There is much more functionality to be had if that’s your goal. Take a look at the documentation and go nuts!

Until next time.

When it comes a busy Home Enterprise environment basic monitoring it can be a challenge to find a solution that’s light and easy to configure. I want lots of monitoring options with flexible notification schemes, that’s easy to setup and configure. A nice GUI doesn’t hurt either. Kuma Uptime hits all these boxes.

Looking Inside The Pick-A-Nic Basket

Right away, we see a nice “Add New Monitor” button on the top left.

Adding Monitors

That’s a great array of monitoring modes we can pick from. I particularity like the TCP port, it’s great for Docker containers.

Note: You’ll notice there’s a Docker Option, but I like TCP port to keep things separate.

Notification Setup

Notification types are an embarrassment of riches. I can’t get all of them in one screenshot, it goes all the way to “Z”. I particularly like the Apprise support! Even though Home Assistant is represented here, I prefer to use Apprise.

I have a post here about setting up Apprise with Home Assistant.

To my surprise, this was dead simple since Apprise was already setup, so I could just use the same link as I use for ABS! Also, I love that you can make a notification as default for new and current monitors.

So that got the alert to the HA dashboard, but sending to devices via notifications was a bit trickier than I expected.

For whatever reason, the notification would cycle and send hundreds out.

I put in trigger nodes to limit to one.

For my switch node:

And the json for the notification nodes:

Once that was done, it worked wonderfully.

Groups

You can add monitors singly or group them together. I really like groups as you can see uptime as a whole and individually. You can also set the notification for the overall group as well.

As for uptime, I really like this display.

Other Settings

I just wanted to add this for reference. So many cool options. Built-in Cloudflare tunnel support? That, as we said back in the day, is “rad.”

Portainer Stack

The stack is really, really, simple. The github is: Uptime Kuma

This stack example as always, is at my Github.

Note: Kuma recently went to 2.x. For whatever reason “latest” still pulls 1.x, so I used a version tag here instead.

Conclusion

This is a great addition to my monitoring suite, and is a nice companion to Pulse.
I hope you find it as useful and easy to use as I do.

Until next time.

As I’m sure you’re aware I absolutely adore Proxmox and Docker. They are, in my opinion the core technologies in Home Enterprise setups.

Note: Uh oh, rambling rant incoming.

You’ll notice I didn’t say “home lab.” I despise that catch all term. A lab is a place for experimentation and scenario wish fulfillment. There are no customers or users in a lab, save for the mad scientist playing God inside of it.

I have labs. Outside of that lab is my Home Enterprise. I have users who expect uptime, I have deliverables on myself to improve my workflow, etc. I put new solutions into testing phases before adopting, etc.

Not.a.lab. Fight me. :)

Ok, now that I have that out of my system…one thing I’ve always wanted is a solid way to monitor and alert on all of my VM/Docker services. Uptime, resource usage, etc. I never really found any of the solutions out there that was compelling. So as I’m want to do, I sat back for a while and waited for the universe to deliver a solution. And it did!

What Is Pulse?

Pulse is an application I stumbled upon by way of the ugh…”home lab” subreddit. It does everything I mentioned above and a little bit more. This is an outstanding application. Very easy to deploy with Docker, and very full featured. Let’s take a look.

The Nickel Tour

First, we have Proxmox. Overview, Storage, Backups! It integrates not only with PXE, but also Proxmox Backup Server!

If you want more details on a VM/CT, click to open.

For Backups, it shows you local backups, PBS backups and size/status and…

It.shows.the.presence.of.SNAPSHOTS! No more do I have to question whether or not I remembered to clear that snapshot and where it was, I can go straight to Pulse.
I can’t tell you how much I love this.

Note: There is no alerting for this, but I submitted a feature request to the Github.

Ok, what about Docker? Yup, I can see all the details on my containers!

I can even click into them and see more details.

Alerting

The alerting thresholds are easy to set, and very human. I have any number of templates/VMs I don’t want want to be bothered about, so I just turn those alerts off. Or maybe I have a Linux box that is high on memory usage but I’m fine with it. Simply raise the threshold.

For Notification Destinations, you get email or webhooks. No Apprise support , but I’ve submitted a feature request.

Note: I guess there IS Apprise support but it’s not built in. Feature request stands.

Here’s an example of some alerts I received.

And the email.

Previously, I would have to had stumble upon this, but now issues are proactive, not reactive. Wonderful.

Setup And Install

Setting this up is not hard at all, and I have a process that worked great for me.

As always, I have my Portainer Stack examples up on my GitHub.

The stack is about as simple as it gets.

Inside of the directory, you must create a .env file with the following attributes.

Inside of your volume directory, create a .env file with these attributes:
Ensure the user and pass are filled out, this will be your login. The api token is a seed, and you’ll replace in the GUI afterwards.

PULSE_AUTH_USER=
PULSE_AUTH_PASS=
API_TOKEN=c4b7c4c059e1ed51cf590d74b6ef8c33684b473486de0146a8b22e70a44955c1

Adding Proxmox

Go to Settings>Proxmox VE Nodes, and “Add Nodes” It will present a wizard that will provide what you need to add the monitoring user and privileges/token creation. This process is very well thought out. If you have a cluster, you only need to add one node. Adding others does cause some duplication which can be confusing.

Adding the Proxmox Backup Server is the same process.

Adding Docker

This requires an agent be installed on the Docker box. There’s several ways to do this, including a binary but I struggled with that. Luckily, there’s a far easier way to do this, and there a container available!

The first thing you should do is go to Security>API Tokens and regenerate that API key.

The docker file looks like this:

Pop in your new IP token and URL

There’s nothing else to do, they just “wink” into existence.

Conclusion

That’s about it! Now this is my Fisher-Price super easy way to get this setup. I encourage you visit https://github.com/rcourtman/Pulse and look over the documentation, it’s very well done. I hope you find this tool as useful as I have.

Until next time.

A couple of years ago, notifications in HA were a bit of a mess. We didn’t really have a solid phone app, and had to rely on third party solutions like Pushover, which was a bit of a kludge and required notifications to not be local, but be pushed to the cloud service and back again. Then in v0.7 we were given native notifications support, and in 2022.2 local push support was introduced. Notifications could be configured using the built in automations engine or with Node Red. As I’ve only ever used NR, this is what this guide will focus on. It’s more complicated, but I’d argue far more flexible.

HA (Companion) Mobile App Setup

When you first install the mobile app, it asks you to name it. Here’s where you can accidentally trip up your future self. I would advise you make something specifically generic. (words, what do they mean?) What I mean by that is instead of “Dad’s Pixel 10” use “Dad’s Pixel”. That way when you get a new phone, you can name it the same and not have to go through all of your automations and update the reference.

HA stores the name as an entity you can’t search for or see like you’re used to. It’s notify.mobile_app_[name at setup].

You can see it in Node Red, though.

There’s also the concept of “Channels”. Included with the app there is General, Sensor Sync, and Sensor Updates. You can create custom channels, but there first must be an initial notification sent to the device using that channel before the phone will see it and be available for customization of different sounds.

To get to the notification section in the app >Settings>Companion App>Notifications

The Channels section is where the customization of alerts like sounds, vibrations, is configured.

Node Red Configuration

I’m going to assume you have some knowledge of NR. I do have a brief intro about it here but it’s in no way comprehensive.

I’m going to include some samples of several custom scenarios I have setup. Typically, it will be a state node, a switch, and the notification entities.

The flow for my front door notification is shown above. To get the values for the switch, I tied a debug node to the state and activated it.

The debug node is an indispensable tool to see the messages so you can switch them correctly.

If you have a smartwatch, notifications can be sent there as well.

Now you may have noticed the Data section in the notification area…yup it’s JSON.
Here you can see the structure of this message, where I’m repeating the payload of what’s being received into the body of the notification. Also the Channel, Priority and Color. Not every device honors the color value, as you can see above. Examples of all these can be found on my Github.

Let’s look another more complex example for my Garage Doors.

Now let’s look at a debug of the door.

So this device sends the interim and final state of the door, and I use the switch node to send the packets to the right output. NR doesn’t have a “does not contain” option which is why i had to use regex for that.

Testing and And Initializing Channels

So the easy way to send these channels down for customization is to wire up an inject node to the notification entities. The message doesn’t really matter as all we’re trying to do it successfully generate the alert.

There’s the notification, with the default timestamp as the payload.

Setting Up a New Phone

So, a new device will not have your channels. All the backend stuff will still be on NR, what I did was create an unholy tentacle monster inject node wired to all of my notification entities that had a unique channel and just fired off a mass notification wave which then pushed all my channels down. I set all my sounds and was good to go.

Oh, and one final note. If after setup of your phone your mobile app name doesn’t show up in NR, reboot the add-on so it can re-query the database right away and fetch the new node name.

More details on the overall notification system can be found here.

Until next time.

I’ve used One Note, Google Keep, Evernote, Notepad++, etc over the years for note taking/storage. Recently I got the itch to bring this in-house. I always thought Evernote was too expensive for what it was, and the other solutions were too locked into an ecosystem to ever truly be “yours”. I recently POC’ed a couple of strong contenders with a solid winner.

Me and Dockey MCGee

Joplin was the first one I tried out. The docker compose had multiple dependencies and was a bit too complex I thought, for what it was going to do. The app, a frontend, a separate database container, and optional transcription service container.

So I got it up and running and went to the front end and set up my user. I didn’t set up email, but they require a email confirmation all the same. So I went through the log and found the email with token and completed it.

So then I logged into the app…only to find there’s no app. It turns out Joplin Server is just a sync point. The app is a thick install only. Grumble Grumble. I installed the app, synced it up, and it was okayyy. Sure you could encrypt the database and some other bells and whistles but it didn’t “wow” me and the requirement of a thick app closed the door on this one.

Trilium Notes, Now With More Flower Power!

(apparently Trillium is a flower. TIL)

Initially I passed over Trillium, I confused it with an old IM I used to use, Trillian. On second look however, I found it has a very interesting story.

TL;DR, developer puts app into maintenance mode, community responds, damn near rewrites the whole thing, and developer hands off the entire product.

A few details had advantages over Joplin right away. The docker was simple. One container, no fluff. As always, there is an example on my Github. It’s also a web app OR you can sync with the server using a thick app. Best of both worlds.

NOTE: there is no support for multiple users right now. It’s covered in the FAQ. Not a big deal IMHO, and the reasons are sound. Need another user? Spin up another instance. I did that for this guide, easy.

SETUP

Setup is simple. On launch of the web app we get:

Pick the first option, then set a password. It doesn’t get much simpler.

The on login, you get this. Me being…me I just deleted all the examples because I wanted to go my own way. I then had to find stuff myself, I recommend you take this tour first, then delete it.

OK where to start. There’s so many options it’s kind of overwhelming at first. Let’s start with a right-click.

Let’s start with note types. There’s a lot here but I’m going to focus on the three I’m using.

Text: Completely boring, delightfully usable. LOTS of options here.
Canvas: This was an unexpected delight.

THIS.IS. EXACLIDRAW! I love excalidraw, and host an instance locally. My only issue with it was storing drawings. It saves them in the browser session until you save to file. This was always clumsy to me, and I’ve lost/accidentally overwritten things before. This completely fixes that. I can store each drawing as a separate note. I’m seriously considering shutting down that instance.

Note: EVERYTHING in this app is a “note”. They call it a “hierarchical note” app. Settings? Note. Calendar? Note. AI Chatbot? Note.

And I first discovered this by accident with canvas, though it’s applicable for all notes. Revisions! By default it takes a snapshot of the note every 600 seconds. In the upper right, you get this charming little fellow.

Mermaid

Before this, mermaids for me were all dinglehoppers and thingamabobs. I don’t think I’ve ever seen this before but it’s SUPER interesting and another way to make a network diagram. (one of it’s many, many, uses.) Here’s an example. Be warned, this is a deep well. There’s a tons of formatting and style nuance.

Here’s a guide: https://docs.mermaidchart.com/mermaid-oss/intro/getting-started.html

But let’s start reaaaaal simple. Check out below. You simply make logical connections via text.

Now you could just do switch===pc without all of the prefix ids but then you cant assign any values to them like shapes or colors.

Note: “IDx” is not a requirement it can be anything as long as it’s unique.

As you can see, the sky’s the limit. You can even take this into Excalidraw!
Note: You’ll have to use the standalone version, Excalidraw proper uses an older version of mermaid, where Trillium uses a newer module.

Calendar

For me, I’m terrible at taking notes and organizing my date. I think this is going to fix that, easy. I mean…it’s a calendar, not much else to see.

Secret Agent Man

A tree, a subtree, an individual note. They can be “Protected". This will encrypt the information and require a password to be re-entered if you leave the protected session or after 10 minutes idle.

There’s also another neat feature, “hoist”.

This will hide all other notes until you “un hoist. Which has its use cases especially if you’re screen sharing.

X, Never, Ever , Marks The Spot.

We’ll close this out on search. Maybe you have notes on notes. Technical references, obscure CLI commands, etc.

You can do a quick search:

Or a ridiculous search:

Or maybe you want to see a logical representation of where your notes are at? Enter the “Note Map”.

So that’s kind of it. I scratched the surface here, and I hope you find this as useful as I did.

Until next time.

NOTE: as of 2/3/26, Music Assistant has had a huge update and a big part of that is adding support for individual users, as well as a neat new remote access setup which is great.

It’s not too often that I find a new docker application that really excites me and changes the way I do things, or fundamentally sets a concept on its head. Music Assistant is one of those. While it does have a very tight integration with Home Assistant as an app you can install in HA, in this article we are going to install it in a standalone docker. I’ll go into why I made this decision. In order for me to really explain what I think sets this apart, we need to take a trip into the deep end first.

Castaway

I’ve had a love and hate relationship with Google casting over the years. Some applications do it bit differently, some hardware devices are more reliable than others. Wired cast targets vs wireless can present challenges as well. There’s an underlying technology at play here, mDNS. (Multicast DNS) It’s supposed to be fairly transparent and “just work” but…yea. Understanding better it is probably best.

Note: There’s also SSDP which is another service discovery protocol, but we’re focusing on mDNS here, googlecast specifically.

mDNS Intro

This protocol is a link local (layer 2 only) technology that can help applications resolve services. ARP (address resolution protocol) is another example of a discovery mechanism where mac addresses are mapped to IPs. mDNS can be thought of as “ARP for services.” Being layer 2, it cannot go beyond L3 boundaries but there are mechanisms available than can forward requests. I may cover that in another article.

In mDNS, when browsing for a service, the source sends a query like _googlecast._tcp.local, and all devices on that segment that run that service respond with their records. Eventually those responses will time out, until the need is requested again. For example, when you go to use the cast feature in an app, the device sends out that query and waits for a response. That’s why you can see some of them “wink into existence” while waiting for your targets to show. There’s also a local cache which flushes after a time.

The query uses the special multicast address of 224.0.0.251:5353 that everyone running the service can reply to. This is different than a normal DNS lookup in that mDNS does not require a centralized resource to pull a record from. It pulls them dynamically from the devices providing the services.

Note: I know. There’s a lot of nuance missing here and other protocols, general purpose multicast, etc. Don’t forget, this is a primer so that I can explain Music Assistant better.

Before we go on, let’s have a talk. Is your local domain suffix still .local? You silly monkey, .local has been a suffix reserved for mDNS since 2013. If you want mDNS to work correctly, you’re going to have to change your domain. Go do that now. We’ll wait. … …. …. Ok all set? Great. Let’s get into it.

mDNS Deep Dive

Way more applications that you may realize use mDNS, but let’s focus on a phone casting to a target. I will also highlight some differences in consumer vs prosumer/enterprise gear in how this is handled.

As discussed, cast devices run services waiting for an opportunity to announce themselves on the network, Enterprise access points may store entries in a table or act as a “mDNS Gateway”, to forward between L3 segments. Like a bookie wanting collect a debt, the source announces it’s looking for them.

Once the end devices sees the cast targets, they can choose one. It then has a peer to peer connection via the access point, and then basically sends the URL to the resource, and the source becomes a fancy remote control.

Now, this is a wireless to wireless situation. The destination may be on the wired backhaul, but the actual mDNS announcements are coming from the wireless speaker so there’s no bridging between physical segments. Casting in these situations are usually pretty reliable and trouble free.

If the device sending mDNS is wired, then depending on the AP we can have an issue. Enterprise or even some Prosumer APs may not allow mDNS messages to be received from the wired side without additional configuration when mDNS forwarding is turned on . YMMV.

Such configurations may include adding the MAC of the sender to an approved list to allow the messages to forwarded on. I run Aruba wireless at my house, so I had some pretty frustrating moments trying to cast to my Nvidia Shield, Sony Receiver, etc until I learned how this works.

Spoiler: I had to create an Airgroup on Central to forward mDNS to other vlans then that blocked the wired mDNS. I then had to add the MAC addresses as servers on the config. SUCH…FUN! A buddy of mine told me about a VM he runs that does all this mDNS forwarding so I can turn all that off in the future, hopefully. Sounds like a future article. :)

Ok so that’s a mid-level explanation of the hows and whys. The con’s of this as I explained earlier:

• device support can vary

• applications can vary in quality of how they implement mDNS

• unexpected hardware issues (see example above) can cause lots of frustration

• audio quality can take a hit, relies on the end device to do most of the processing

• can’t handle multiple streams

• connecting to cast targets can be a PIFA.

Music Assistant fixes most, if not all of these issues.

Music Assistant Deep Dive

Ok, this is where things get exciting. With standard casting, as you’ve seen it’s a very "physical” process. MA takes this whole thing and abstracts it. It’s easier if I show you.

Basically, MA is the cast requester for all the services. And when you’re in the app, you’re streaming from the MA server itself, not casting traditionally. The server also manages signal processing, transcoding, etc. It’s pretty great. Look at these logs.

What’s great is that from the UI you can re-name the Players to so you know what they are. Very useful. I start a stream from my desktop at m.nscriven.net (proxy FTW) and we can see the stream. It plays via some new-ish browser API. It was just added in March, apparently. Lucky me!

If we take a look at the playback info:

It show that the server is transcoding down from FLAC to MP3, because that’s what the browser can support natively. And none of that process is happening on the end device it’s all on the server. You can really customize the player too.

Here we can see all the targets. I can make groups, I can cast different songs to different targets at the same time. It’s kind of amazing.

What about a dedicated device and not a web browser? Let’s see what happens when the target is a Nvidia Shield.

It plays as FLAC, but down samples to 48Khz/16bits. If we look at the advanced settings of the player, it’ll tell us what it supports.

If we look back at the browser player we see it doesn’t have an output codec. Let’s look at a Chromecast Speaker.

There’s some more features here, as well as the ability to turn off the MA registration and use traditional casting. Some devices may have issues that require this, thankfully I haven’t found one yet.

Let’s look at one final device, my Sony Receiver. I found something interesting. By default it wouldn’t play 24 bit, but I could change it! I scrolled further down and the receiver supported way more than what’s shown here.

Then on playback:

So as you can see there’s a LOT here.

And we can show the server is indeed transcoding. I started a playback and the CPU jumped up for a second and then settled down.

Ok, now that I’ve nerded out on the underlying tech, let’s move on.

Installation and Configuration

Ok, so this was really built for HA integration primarily. You can go to HA right now, find MA, and install it there. I didn’t go that route, because I didn’t want to be trapped in the HA app, very similar reasons why I separated out ZWave and Zigbee.

And just like those examples, someone made a proxy app for HA so I can get the best of both worlds. Let’s take a look at the Compose file I used. As always, there is an example at my GitHub.

You’ll notice that I’m using local bind mounts for my volumes. I have a NFS share mounted for media. The major deviation between this and my other docker containers is it’s the only one that uses the host networking mode. More details on why can be found here.

Now because we’re using the host mode you won’t see published ports on Portainer/Docker. The default web port is 8095, can be changed later per the documentation. TCP 8097 is used for the stream per the docs, but the app says its 8098.

Go to settings. I use the local filesystem option but look at all the other providers!

Next take a look at Player Providers. I use Chromecast, but look at the others! Wow.

Proxy/Remote Access

For ease of use internally, I access this through my NPM proxy, so I can go directly to a FQDN.

But in this newest release the integration with Home Assistant has come a huge way, and has a compelling remote option. First, go to Settings>Providers and add Home Assistant. Pop in your URL and click authenticate and it’ll toss you over to HA where you log in and add it as a provider.

Next, go to settings and Remote Access. I subscribe to the Nabu Casa cloud service, so I get the”Optimized” Mode. You must add the HA integration previous to this, or it will not see your subscription.

I scanned the QR Code, it took me to the login, prefilled the code and I just logged in. Pretty slick.

Ok that’s about it for this, you really need to poke around and read the docs to really understand fully, but there’s not much more to cover here.

That's it! This article took a long time to write, and my buddy Igor really helped me to clarify and better understand some misconceptions I had about how mDNS works. Confirmation bias can be a beast.

Until next time!

In Part 2 we covered Zigbee2MQTT (Z2M) and using the UZG01 to decouple from Home Assistant proper, removing the direct hardware dependency on the VM. I then thought, why not move Z2M entirely off Home Assistant and into its own docker? I kind of like the idea of being able to manage the software and not always be trapped in the HA app.

But…if I remove the application from HA how can I access it remotely via NabuCasa or some other reverse proxy? Easy! Someone made a proxy you can install in HA, giving you the best of both worlds! We’ll get into it.

Also, once I got down the road for Zigbee, I started to wonder about doing something similar for ZWave, but I didn’t find a similar solution to the UZG01 that I liked. But where there’s a docker, there’s a way! I managed to totally decouple both radios making my HA VM totally portable between my Proxmox nodes.

Before we get started, if you’re new to Docker and Portainer, go read my series, It's Docker-ing time!

Z2M Docker

The good news is we did the bulk of the work in part 2. So let’s kick things off with our Portainer stack config. Note that I’m using my bind mount option for the local config. Example can be found at my github for proper formatting.

We’re going to need some information out of the existing Z2M install, namely the Network Key, Network PAN ID, and the Network Extended PAN ID, etc. Honestly, it’s easiest just to copy down the files from Home Assistant right into the docker config folder.

In HA, after the file transfers turn off the Z2M install (don’t delete just yet) then deploy the stack, and go to port 8080 on the docker host. Everything should just “come up” since we simply moved docker to another host, everything else is done on the UZG01, and all the configs are in your transferred files.

That should be it. I like to send the page to my Ngnix Proxy for easy local access, but now for the HA proxy.

Z2M Proxy

In Add-on, choose the Add-on Store, and search for “proxy”. It should come up, because it’s part of the Z2M repository that should already be present at this point. Install it.

Go to config, simply put in the IP: port of your docker host and start it.
Turn on sidebar and start on boot.

You’ll get this handy little fella in the sidebar and now it’s like nothing changed.

It is great, though being able to access the management page directly, and now when you reboot Home Assistant your Zigbee network doesn’t go down as well.
(I send mine via an internal NGINX proxy for handy FQDN)

Ok that’s it for Zigbee

Decoupling ZWAVE

Ok, there’s a couple assumptions I’m working with here. I assume you’ve migrated to ZWave JS UI, and you’re not using MQTT for this deployment. I’m using just the websocket method, so that’s what we’ll focus on.

Ok, so the first thing you should do for safety is go into your existing install, go to the lower right, and choose advanced actions.

Backup the nvram of the adapter and the nodes.json. You shouldn’t need this, but better to have it.

This process is pretty different from the UZG01. The ZWave adapter (mine is Aeotec) keeps the whole environment in local memory. It’s the brains of the whole operation, the UI provides management access. Moving the adapter will cause a bit of a headache though, because there are some items that don’t come over, and have to be reconfigured. We’ll cover it. You also need to go into your existing install and grab your security keys. Copy them someplace safe for the interim. If you don’t have anything for the Long Range keys it’s fine.

Now, we need a device totally independent of where you’re keeping Home Assistant, that has or can have Docker installed. I tested initially on a Pi3, which worked, and then easily migrated over to a Beelink I’m using for my Frigate docker.

Shut down the HA ZWave JS UI container and remove the dongle and plug it into the new hardware. On that box, validate its location with ls /dev/ttyACM*

We need this for our portainer stack configuration. Speaking of which…

An example can be found at my Github. Remember those security keys? Enter those here if you want or leave them commented out. You can also add them in the new UI after the docker starts. I was dopey and forgot to uncomment them, so that’s what I ended up doing.

Note: The new docker will force you to create Long Range keys if you don’t have any before you can save changes. That’s fine there’s a little “generate” button.

Now, deploy the stack and go to the web UI at host:8081 and go to settings. Make sure your keys are all present (or enter them now) and save the config.

Next, scroll down to the Home Assistant section and ensure the WS Server is enabled.

Now, go back to the main control page. It might look empty, but don’t panic. The driver can tale a moment to load. If you don’t see Driver Ready>Scan Completed then maybe it isn’t seeing the dongle. Check the logs.

Ok, now here’s how my experience went. All of my wired ZWave devices came up and looked good. I have a lot of battery-powered devices that I had to go around and wake up and then call a re-interview from the UI and they came back from pending status.

Look up the details on your device to find out its wakeup routine. Follow that process for each device until everyone’s back. Also, I found that none of my names carried over. Apparently they’re stored in HA.

You can use the HA Z-Wave integration as a Rosetta Stone to match NodeIds with names. The names in ZWave JS UI are nice since they can be used to label the network view of the devices.

Remember when I said I moved from the PI to the Beelink? I didn’t have to do any of this again because I had all the config files in one spot on docker. All I had to do was update the HA integration and Proxy with the new IP once I copied over the files and started the new docker.

Updating the HA integration and Installing the Proxy

If you go to settings>devices and services>zwave you’ll notice it is very grumpy. In the integration, click “Add Hub”>Custom Installation>Uncheck “Use the Z-Wave Supervisor add-on and hit submit. Replace local host with your docker IP and hit submit and it should be happy again.

Ok, last step! The proxy. We need to add a repository in Add-ons.

Go to Settings>Add-On Store (lower right) and then on the upper right “Repositories”

Add this repo: https://github.com/Pulpyyyy/zwavejsuiproxy

Once added, search for “Proxy”, and install. The process is the exact same as the proxy for Z2M. Config, enter IP and port, start at boot, add to sidebar, profit.

And that should be it! Once complete you’ll have total hardware and software independence from the main HA VM. THis means you can live migrate the VM, and reboot/update for maintenance without affecting the Zigbee or ZWave networks.

Until next time.

Intro And Musings

I spin up a fair amount of Linux VMs in the course of my work for…science. And even with templates it gets tedious. Crazy tedious. Then, I was today years old when I heard about Cloud-Init. Basically, this is a special image you can download and boot from that will provision itself based on values you add in a Cloud-Init file. It makes makes new deployments crazy fast. The rub is, there’s some nuance here that I had to figure out that I don’t feel the videos and articles cover that clearly.

Note: There is a Cloud-Init package that can be installed on provisioned systems but I won’t be covering that today.

Ok, let’s get to Ramblin’

Template Setup

Every step of this can be done via CLI, but we’re going to do this in the GUI except for one step. Let’s go ahead and create a new VM, with an ID of 9000. I'm only picking a number that high to make it stand out.

Check qemu Agent

No disks, delete any that are there.

Configure CPU and memory as desired (examples only)

Then complete the creation. DO NOT START THE VM.

Then go to the VM, and go to the hardware section.

Ok, now we’re going to use the CLI for the next steps. PVE8+ does have an image upload and import feature but for whatever reason it makes the image not bootable.

So go to https://cloud-images.ubuntu.com/, pick your distro and find the amd64.img.
I’m going to use this:

https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

Don’t download it directly, SSH into your node and pull it down with wget

Do a ls and you should see it there.

Our next command is going to import the disk to the VM.
qm importdisk [ID] [IMG] [STORAGE NAME]

E.G.: qm importdisk 9000 noble-server-cloudimg-amd64.img truenas

Go back to the VM hardware section and you’ll see “Unused Disk”, edit it.

Check “discard” and add the disk. And yes, I know the disk is small. Don’t extend it yet.

Next, add the Cloud-Init-Drive

Make sure it’s IDE2

Set all your variables, and “Regenerate Image”. You’ll want to use a SSH Key, we’ll cover that in the next section. By default Cloud-Init does not allow passwords for SSH and honestly I’ve found it’s a pain to make work later. Using keypairs is the better, more modern way to SSH IMHO, and better to learn it, even if at ramblin’ gunpoint.

Skip to the bonus section now if you need to learn how to make the keys and come back here.

In options, make sure scsi0 is set to boot, uncheck net0

Right click on the VM and convert to template. Once converted, right click and make a full clone.

Start the VM

It’ll go through some quick loading, then hit enter to get to the console password prompt, and use your creds as defined. Success!

Now, the disk is really small. This is great for a rapid clone, but not for prod.

Let’s delete the VM and recreate, but don’t start it. On scsi0, let’s resize.

Adjust as needed.

Start the VM, and check the disk. Much better.

So I specified a cert, let’s see if that works. (I use Secure CRT)

Point it at your private key. It will have no extension, the .pub is for the server side which we added to Cloud-Init

You should connect successfully!

Bonus Section: Making Keys

You can use OpenSSH on Linux to make a public/private keypair. Windows is my daily driver though so I used Putty because it’s easy.

Just make sure to export the key as OpenSSH , and not the Putty ppk. Install Putty and open PuttyGen and click “generate”.

Take the public key and paste it into a new .pub file. You’ll load that into Cloud-Init.

Convert the private key to OpenSSH, no extension. If you don’t add a passphrase the later login will be immediate but insecure. A passphrase will act like a password for the private key. Up to you.

Now you’ll have a keypair. Once you load the public into Cloud-Init, in your SSH session you can use the private for authentication. The process should be similar for most clients.

And that’s about it! The default options Proxmox gives us for Cloud-Init is bare bones, you can get crazy with a custom yaml file.

https://pve.proxmox.com/wiki/Cloud-Init_Support

https://documentation.ubuntu.com/lxd/latest/cloud-init/

One last thing. If you change the Cloud-Init settings make sure you click “regenerate” to save the changes.

Until next time.

So I have a strategy, as I covered in my Proxmox series that I can’t justify a whole box just for Proxmox Backup Server, so I run it as a VM in my cluster. I very well can’t back PBS up to itself, so I use Proxmox to send a standard backup to a little Synology NAS that needed a job.

That way, if both my cluster and primary network storage somehow vanish, I have my PBS server safe and sound. I can fire up a new host, map the NFS share and get restorin’. Works great. I added my other VMs to the weekly schedule (PBS runs nightly) and then my containers.

But then I noticed some of my container backups would fail with permission issues. PBS was fine, even local backups were no problem. I checked and rechecked NFS, changed permissions changed NFS mappings, etc.

Reservation To Flip A Table For Two, Please.

I was at my wits end. It didn’t make sense. Then, after reviewing the log I saw this:

INFO: temporary directory is on NFS, disabling xattr and acl support, consider configuring a local tmpdir via /etc/vzdump.conf

I went and looked on the NFS share and sure enough, the temp directory that the backup does before it zips was being stored on the share and choking on the permission to create the archive.

I nano’ed my happy ass over to vzdump.conf and added this to the file and saved it.
/var/tmp is a larger directory, and the backup process cleans the files afterwards.

tmpdir: /var/tmp

I ran the backup again, and not only did it finish, it finished faster than ever since it didn’t have to transfer all the small files contained in the LXC over to the NFS share first. Just the finished archive.

Thats it!

Until next time.

Docker Installation and Setup

Prerequisites: Current Ubuntu Server LTS. If you’ve never used Ubuntu Server and just Desktop this is your opportunity to challenge yourself. I’ll cover some basic commands to get you over the hump.

I won’t cover getting the VM installed, so we’ll assume you’re at a command prompt via SSH and ready to get to work.

Let’s cover some basic commands .

sudo - since we won’t be running as root (nor should you) we’ll run commands with sudo before anything docker related or requiring higher permissions.

ls -la - this will list the contents of a directory plus permissions. As we’ll be editing some permissions we’ll need to validate.

pwd - shows the path of the current directory. Useful for getting our bearings. Also handy for lazy typers who would rather copy/paste than type out a long path.

nano - text editor.

cd - change the directory you’re working out of.

/ - this is a representation of the root directory. E.G. cd / will take you to the root directory. Also implied in a path. E.G. the path to the opt folder is /opt .

mkdir - creates a directory

rm - deletes a file. To delete a folder, add -r

NOTE: this isn’t windows. make damn sure your path is correct. Linux is like the honeybadger. IDGAF about you or your files it’ll wreck your day and walk away with a smile.

Ok, let’s get going. https://docs.docker.com/engine/install/ubuntu/

We’re going to use the “apt repository” method. It’s a simple copy and paste affair. Follow all the outlined steps. Then follow steps 2 and 3.

When you ran Step3, you saw that the docker image didn’t exist locally, so the system did a “pull” and obtained it from an online repository.

Once it pulled it down the docker started, fired off some text and shut down!

Let’s run sudo docker ps

That command only shows running containers. Let’s add -a. This will show all images. Remember when it’s not running it’s an image. When running, it’s a container.

So here we see the container ID, the image name, etc. Take note this image has no network ports, and the name at the end is randomly generated. Let’s make our docker volume directly and set permissions.

I’ve adopted the standard of using the opt folder for my docker configs. It’s easy to find, standardized, and a bit of a best practice.

mkdir /opt/dockerconfigs

ah, lets check permissions.
ls -la /opt

root owns it, which is fine. We just need to add sudo to our mkdir command

There’s our directory. What we want to do next is change the permissions for the 1001 user and group to own dockerconfigs. Our docker images will also use the same user.

sudo chown -R 1000:1000 /opt/dockerconfigs/

Let’s run ls -la again and review.

Notice that the folder is now owned by 1001, aliased to my local user. We did not modify opt though. See that ..? that references the folder above us which is opt and is still owned by root.

Now try : mkdir /opt/dockerconfigs/test

Notice we don’t need sudo for this folder creation since we own dockerconfigs. But if you try and make a new folder under /opt sudo is still required. We want to own dockerconfigs so we don’t have to change the permissions for new folders constantly.

Checking the permissions dockerconfigs shows our test folder has the right settings. Let’s delete our test folder, and remember the honey badger at all times:

rm -r /opt/dockerconfigs/test/

Ok, let’s talk Docker Networking.

Docker Networking

Ok, this is where docker gets hella cool. Run: sudo docker network ls

What we care about is host and bridge. Host is the network interface of the VM, and bridge is a default virtual network for use in docker. We can make lots of virtual networks in our docker config.

The vast majority of our containers will be mapped to a network other than host. Mapping a container to host removes much of the flexibility of docker. When we map to a virtual bridge, we can re-use internal ports between containers!

Each container gets its own namespace, so docker knows what service maps to which port. What you cannot do is re-use host ports, because you know…networking.

In this example, all the containers can communicate internally because they are are in same virtual segment. Every container you spin up can have its own network for segmentation. We’ll cover more on that shortly, as there is a change we should make.

So if we inspect the bridge network: sudo docker network inspect bridge we’ll see that it has a 172.17.0.0/16 network assigned.

Any new networks we make will get assigned the next range in the series, all /16s. Pretty soon, you’ll hit the 192.168.0.0/16 ranges and that’s just messy and terrible.

Do not like. Keep in mind that if these subnets conflict with a subnet on your network, any traffic destined will blackhole on egress. I mean, if the docker subnet is 172.17.0.0/16 and the source is 172.17.1.1, then there’s nowhere to go. You’re already there. A real “Hotel California” scenario.

So let’s change this behavior to hand out /24s instead in a different range.

sudo nano /etc/docker/daemon.json

change to the network standard you want and paste:

NOTE: Keep reading. I found an issue and fixed it below.

Then restart the docker daemon. sudo systemctl restart docker

If we re-inspect the bridge, we’ll see it has a /24 now.

Hol’ up. I noticed that while the CIDR range changed, the IP range did not. After some digging, we need to change the “bridge ip” since the networks iterate off the bridge.

To save in nano, ctrl+x, then save the buffer.

Due to the way Substack mangles the formatting I have an Example on my github. Now when I restart the daemon and inspect the bridge I see the right range, as well with the new networks. This concludes our setup prep.

Running Docker Images

So here’s where we are largely going to deviate from the CLI, and use a GUI tool going forward. The more time I’ve spent with Docker the more I’ve gotten comfortable with CLI, but I do love a good GUI that just makes life…easier.

Let’s talk Portainer, which is a great GUI docker management tool.

Let’s take a look at the instructions. It wants us to create a docker volume for settings, and then run the docker command. We’re going to do something a little different though. Let’s start by making our own folder for the volume.

mkdir /opt/dockerconfigs/portainer

Next, lets take a close look at the docker command:

docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts

Let’s pull this apart and check out each section.

docker run -d: this runs the docker in detached “headless” mode

-p 8000:8000 -p 9443:9443 - these are the ports it will use. Notice how they are 1:1. The host is on the left, container on the right.

--name portainer - no random names for us, no sir!

--restart=always -this will ensure the container always starts on reboot

-v /var/run/docker.sock:/var/run/docker.sock -this is basically a mount to an external host directory and a directory internal to the container. This is how Portainer will interact with Docker

Let’s take a second and explain further what’s going on with the volume setting before we move on. For the below command: -v portainer_data:/data

This is an actual “docker volume” and the contents are stored pretty deep into the OS, typically at var/lib/docker/volumes. When we specify the folder directly with a full path, that's a bind mount. And that’s what we’ve standardized on. So for our command as shown below, the bind mount or docker volume is the path up to the : , and after that is what the container folder it binds to is. Mounted volumes, like shares also work here.

-v portainer_data:/data - same concept as above. Though we are going modify this as described above . Our command will be:

-v /opt/dockerconfigs/portainer:/data

This will make sure our config is where we want it to be.

portainer/portainer-ce:lts - the name of the image we want to pull and the tag for the version.

Ok, let’s put it all together and run it.

sudo docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /opt/dockerconfigs/portainer:/data portainer/portainer-ce:lts

Let’s take a look at sudo docker ps

Lets go have a look at port 9443!
Note: port 8000 is for the edge agent tunnel. If you don’t intend to use it, simply remove “-p 8000:8000” from the above command string. If you’ve already deployed, simply
” sudo docker rm [ID or Name]” and then run the command above minus the port. The container will simply redeploy without the ports.

Set a password and log in.

Click into the environment. Now everything Docker related is at your reach!

Let’s look at networks. There’s our test networks. I’m going to delete them. Notice how we can’t delete the ones marked “system”. This is a very good thing.

Let’s take a look at containers. Hey there’s our “Hello World” container! I’m going to delete that as well. Notice how we can’t make Portainer walk the plank by deleting it.

Wait a second…did our config volume mount correctly? Yup!

What network did Portainer join? Lets go into the container and scroll down. Looks like we connected to bridge.

Let’s make our first container in Portainer.

Docker Compose vs Portainer Stacks

You can spin up containers like we did with Portainer or you can use a template style called Docker Compose. Compose and Stacks are basically the same thing, with some minor formatting differences. Stacks can be used to join multiple containers together (example coming) or just do a simple container. I like Stacks a lot and use them exclusively. Claude AI is GREAT at making a Compose file work in a stack.

Ok let’s use a crazy one as the first example, PHPIPAM. Example at my Github.

It takes phpipam-web, phpipam-cron, phpipam-mariadb, and builds it all into one service.

I’m going to paste the whole mess in, and at the bottom, “deploy stack”

Look…at….that. Lets go to the web interface at port 80!

Now the cool thing about stacks is, what if you want to update the images? Simple. Go back to the stack, click “editor” and then scroll down to “Update the stack”. Enable the re-pull option and then update. If you are just changing the stack variables, then an update without the pull will re-deploy with the same image.

Let’s finish this up with a simpler example. This is a notification system, “apprise”.

Now that I gave you a primer, a lot of this should make sense. Take note of the environment variables. as a best practice the PUID and PGID should be in your stacks for permission conformity. Remember, we gave our folder the 1000 permissions.

Oh, be aware that indentation is critical for our stack config.

Ok, that was a lot. Let’s close with one last thing. What if you want to check the logs, or log into the container? These I prefer to do via cli, it’s a bit tedious in the GUI.

sudo docker exec -it [name or container id] /bin/bash

See how my prompt changed to root? Let’s exit out and look at logs.

sudo docker logs [name or container id] -n 100 -f

Ok that about wraps it up. If you want a really deep dive into docker I highly recommend:

And remember, if there’s an app you want to run the first thing you should ask is…hey is there a docker for that? :)

Until next time.

Intro and Musings

So when I first started this blog rambling™ about all sorts of nonsense™, I was fixated on Proxmox and LCXs. And man I went crazy over LXCs…how cool. Super lightweight, easy to deploy, etc etc. My LXC count grew and grew. Nginx Manager, Audio Bookshelf, Plex, Technitium (DNS Server) PiHole, etc etc. I realized I was relying too much on the tteck scripts (RIP man) and that whole community kind of…imploded. I also saw that many of the new apps I wanted to host didn’t have an LXC script and I started to see the cracks in the foundation of LXC.

Don’t get me wrong, I still think they’re great and I still use them. But I find myself not lighting up new ones and going another way. A buddy of mine that I work with was like, “why not use Docker?” And I was like…”I don’t know.” Cue the training montage.

Six months later, I have quite the docker deployment for my little self hosting environment, and lighting up new apps is very simple and I haven’t found an app that I wanted that isn’t “docker-ized” yet. Usually when I get excited about a technology or new shiny thing I’m using I just go off the cuff, and and start ramblin’. This felt different though. So when the itch too write got too strong to ignore, I took a step back. I watched some deep dive videos, took some courses and took a close look at my environment and realized I had fallen into some bad practices and did some housecleaning and fixing. Don’t get me wrong, everything was functional but I wanted to provide a practical guide that followed some best practices.

Disclaimer: You may have a better way. My explanations/musings may seem silly or too basic. This is how I understand it and implement.

What is Docker?

Contrary to the header here let’s talk about what an LXC is. It’s container based virtualization, but it’s tied tightly the host OS. It does have its own file system but it shares the local kernel, etc. By default, it is “unprivileged” which limits its blast radius, but it can also be set to “privileged” which grants it even deeper access to the host. (arguably dangerous) Regardless of the Linux Distribution the host is on, you can make a LXC with just about any other Linux Distribution due the the nature of the shared Linux kernel. Because of this, LXC’s start extremely quickly as they're not booting their own kernel or initializing their own hardware drivers.

You can still have unique networking, mount external file shares, etc etc. From the perspective of the LXC it’s a full OS with nearly all capabilities of a full OS. With Proxmox, you actually configure the network settings from the CT (container) GUI itself, and not in the CT directly. Every instance of a CT is unique and independent and takes up an IP on your network as well.

In fact, they look so much like a regular VM I tag them in Proxmox so I know what they are at a glance. CTs can be backed up, and even moved between different hosts in your cluster just like a VM. But because they share the local kernel, they must be shutdown briefly, the files/compute moved and then restarted on the other host. It’s fast, but there is a drop in service depending on the size of the CT.

Now let’s talk about Docker. You install the Docker application on a separate VM, like Ubuntu Server. The difference is that a VM (virtual machine) is an island unto itself. It is totally separate from the host OS. Separate kernel, drivers, everything.
The network stack is edited in the VM, etc. If you need to, you can also “passthrough” physical devices to a VM like a GPU. It takes much longer to boot than LXC, but can be “live migrated” to another host as it does not rely on local resources.

So with Docker, I want you to think about it like this. Imagine you install an application on your machine but you want to expose that application to everyone over the network via a web page. Multiple applications can be installed, and accessible over the same IP of the VM host, just on different ports. When you pair this with Nginx, wonderful things can happen.

Note: Dockers apps don’t HAVE to be network accessible but for this guide we will assume everything is reachable.

The image above shows what the end user would experience by default. In order to access the application they must go to the VM’s IP and port number. This is tedious though. Let’s add in something like Nginx to make this easier for the end user.
(Let’s be honest, the enduser is you. ;) )

Using Ngnix and local DNS we can make the end user experience much simpler. Using our proxy we also obfuscate where the site is located. You can also leverage Let’s Encrypt to get certs for the domain names. As luck would have it, I’ve already written a post about that.

It's a secret to everybody!

Docker Images

Let’s talk about applications. Say I want to install Audio Bookshelf on my Ubuntu Server. I have to find the source for the application, determine the dependencies, download multiple packages, etc etc. It’s really a pain. What if it uses a different version of PHP, or Python that I have installed? It can snowball from there into an unmanageable mess.

A docker image is the solution for this. Someone builds a docker file with the application and all dependencies. The base OS can be a different Linux distribution as well. When run as a container, it’s totally independent of the local system and nothing other than Docker itself needs to be installed. The container is also immutable. That means any new data is stored in memory, but on a restart of the container everything vanishes and you’re back to how it was when you started it the first time.
(there are exceptions to this, but it doesn’t matter for this guide)

To make our data permanent, we need to use “docker volumes” where we essentially mount external folders into our docker startup configuration. We can save data like app configurations, and even mount external shares for application access. This is especially important for when it’s time to update a docker image. The container is immutable, remember? When the developer wants to update the application they update the docker file, and generate a new docker image with the changes.

Then, you pull the new image, restart the container, then you’re up and running with the new code. If you properly set the volumes for your config settings, then it’s largely transparent to you.

We’ll cover this in more detail in Part2, as we’ll be installing docker and getting things setup.


Until next time.

Zigbee2MQTT (Z2M)

A Short History

When I first started with home automation back with Wink and the SmartThings, my first USB dongle was the ConbeeII. Solid little Zigbee dongle, the integration was DeConz. Over time however that started to show its age and for me was wildly unreliable.

That’s when I learned I was not stuck with that integration. There are several ways to manage and control a zigbee network. So then I moved to ZHA (ZigbeeHome Automation) for a few years. While much better than DeConz it did require that I re-pair all my devices. The network was more stable, but I did notice a bit of a lack of control/visibility. As my device count grew though, I was starting to outgrow the ConbeeII, and at this point it was pretty damn old.

I needed a newer adapter with more capacity, so I bought a UZG-01 LAN Coordinator and noticed it had deep MQTT support. The road to MQTT had begun.

Z2M is an astonishing open source project. Vibrant community, thousands of devices supported, can be installed a myriad of ways, etc. As this was early in my docker experience I opted to install Z2M as an add-on in HA. I did eventually move to docker, we’ll talk about that later.

Installation and Setup

Ok, let’s work out the coordinator first. With the UZG-01, you can go either USB or LAN. I chose LAN. It has a config generator that makes this part incredibly simple. Note that you can can use this config gen for ZHA as well! We’ll use this config snippet to tell Z2M how to find the coordinator later.

Note: UZG has largely ceased work on the firmware for UZG directly. The dev has migrated to XZG which is great, there’s lots of improvements. As for Coordinator firmware, I’ve been running 20240914 for over a year now as of 9/1/25 and it’s worked extremely well. When it comes to upgrading the firmware, I did have to attempt it several times before it took, and on more than one occasion it froze, but a hard bounce of the unit brought it back and I tried again until it was done. For initial install, the Web Installer is the way to to go.

Next setup the MQTT connection. Take note of the status indicators in the upper right. When everything is working correctly, all should be green. For initial setup, MQTT/LAN should be green, Zigbee will be red until later.

In HA, find Z2M and install it.

MQTT and serial are the settings we care about. MQTT is the broker that has been configured, and serial is your coordinator. In this case it’s the config from the generator.

NOTE: adapter: zstack is a new requirement as of Z2M 2.0+. The config generator does not create it yet. As Z2M requires a connected socket to the coordinator for “herdsman” to start, if this is wrong startup will fail, and you can see it in the logs. Most adapters I see are “zstack”, others can be “ember”. Just choose the right one for your use case.

Let‘s take a look at the logs during startup.

Once HA has devices that are checked in and published to MQTT, it will then create those entities to use and reference in the MQTT integration for automation. I’m not going to get too deep in how to use entities, as it’s out of scope for this article. All we care about is that they are here. We will go over onboarding devices shortly.

Let’s take a quick look at MQTT Explorer to see how things have changed since our last article.

Now I have two new topics! Z2M, which is the raw details of the endpoints:

And Home Assistant, which have the actual entity states:

Note: the “Home Assistant (MQTT Discovery)” setting in the MQTT section of the UZG allows this part to be automatic.

Overview/Onboarding Zigbee Devices into Z2M

None of this means anything If you have not yet onboarded devices. Z2M has a frontend that we can use to achieve this. In the add-on you can choose to open it from there, and/or pin it to the sidebar.

Definitely pin it to the sidebar, you’ll be in here a lot.

The top left will show how the site is being accessed from within HA. Let’s discuss other important tabs here.

Devices:
This is where you’ll see all the requested devices and their details and status. You can also rename, delete, and re-interview from here.

If you click on the name of the device you’ll get many options. While it’s really interesting to explore, be careful, there be dragons here unless you really know what you’re doing. Options vary wildly depending on device.

It's often safer/easier to manage some of these settings from the HA MQTT integration for the entity. Case in point, the Power On Behavior is exposed. But, you do you.

Dashboard:
This is a control panel for devices. You can control devices outside of HA if you wanted to. In fact you don’t HAVE to use HA at all. It’s just far, FAR easier to use HA to manage them. I don’t think I have ever used this.

MAP:
This will show you the map of all devices and all the links. On large Zigbee networks this can take a while to generate. Protip: Use Firefox for this. It crashes chrome for me every time.

Groups:
In the past, I’ve recommended using HA Helper groups for lights. No more. Zigbee groups are far more effective. With HA groups, when you activate, a signal is sent out for each device. It’s wildly inefficient/noisy. If you have a device in the group that’s been marked offline because it missed a ping, that light will not actuate in HA, even though it is reachable by Zigbee.

With Zigbee groups, each light in the group actually will subscribe to the group itself much like a multicast group. One command will broadcast, and all lights will actuate. It’s also immune from the Z2M availability status, so it will work even though it appears off line and you can’t manually turn the individual on in HA until the status changes.

In rare cases if it’s an actual problem and the device is truly not reachable, then it’ll have to be re-paired. Most times though , a cycle of the physical switch will force it to check in or it’ll check on the next refresh cycle and fix itself.

If you delete and re-pair it will need to be added back to the group however. Let’s look at a group. It’s important to note the group name will be the entity in HA, so name wisely.

And finally, in MQTT:

OTA: (Over The Air Update)

This is one of Z2M’s shining features, OTA. Many lights, outlets, etc can have their firmware updated right from Z2M! My old GE/Cree/Sengled lights can’t but my ThirdReality lights and outlets, blinds, etc can! Once of the first things I do when I onboard a new device is to check if it has an update. When I first started with my new ThirdReality lights they wouldn’t work right with a group or change colors correctly. Turns out it was a firmware issue and once I updated they worked perfectly. Great feature for modern devices.

NOTE: Zigbee is an extremely low bandwidth protocol. It’s kind of the whole point. To that end, OTAs can be a time consuming mission. It can take up to 30+ minutes to send and complete an update, and I wouldn’t recommend doing more than a few at a time. It’s a very noisy process to the mesh and will degrade performance overall until complete. Still well worth the effort though.

Onboarding

Extensions and Touchlink are niche, and logs are self explanatory. Let’s onboard a device. A device needs to be in either an initial or reset state to be added. In Z2M you’ll see “Permit Join” (All). Pressing this will allow devices within range to join your network. It will automatically turn off after four minutes.

Now before you get all button happy let’s hold on a minute. You never want to use “All”. This will join the device to the mesh inefficiently, and will take longer to find it’s most efficient path to the coordinator for stability.

It’s actually a dropdown menu containing all the routers in the network.

Case in point, for this article I joined a light to the network. An existing light in my office is a router so I chose that and then joined it via that device which has its own connection back to the coordinator. This prevents a lot of churn on the network. So whenever you want to join a device, use the one closest to its final installed position.

Or if you’re lazy just use All. Hey, it’s your network ;)

Once successfully added, its name will be a hexadecimal string. This will also be the entity name in Home Assistant.

The very next thing you should be is to edit it something that makes sense. Rename the device using the option on the far right:

Ensure you click to update the name in HA, so it changes there as well.

Re-Pairing/Deleting/Re-Adding

Let’s say you have a device that is just misbehaving and you want to reset and re-add it. You can reset it without deleting it as a start. If you reset the device to default (every process is different, consult the manual) all you have to do is then “Permit Join” and it’ll hop right back on as though nothing happened.

If you delete the device, you can still reset and re-join but it will remove all links in Z2M and HA, and come onboard as a hexy little beast. Now here's the neat part. Let’s say you had that device named and it was all over HA and now you’ve got a bunch of ugly “device” not found in your dashboards. Or NodeRed is hollering that an entity no longer exists.

Simple fix. Just rename it the same as before, make sure the update button is checked and then everybody is happy. If the device was a member of a Zigbee group though you will have to go to the group and re-add it.

So, I think that’s it for part two. I’ll do another part soon that covers some other applications that can use MQTT, and cover some neat stuff like integrating notifications into Node Red. And I’ll discuss why/how I moved Z2M to docker.

Until next time.

Decouple Zigbee and ZWave from Home Assistant

Part2

When I first started with Home Assistant almost 10(!) years ago MQTT wasn’t as front and center as it is now, and I was first exposed to it when I decided to move from ZHA (Zigbee Home Automation) to ZigbeeToMQTT. (Z2M) Even then, the use case for what MQTT is and its other uses cases weren’t exactly clear to me. Z2m abstracts it away to a point of it works for that use case, but not as clearly for others.

And while I like Z2M a great deal, one thing bothered me about it is that I didn’t truly understand what it was or how to troubleshoot it. And the guides I found, while they obviously got me up and running, never really explained anything. Sounds like a perfect excuse to go on rambling about some nonsense.

If you want an exhaustive overview, go check out mqtt.org. The high level explanation is that MQTT is a publisher/subscriber message system. Essentially, let’s take incoming Zigbee messages and convert them to MQTT so they can be more generically understood. It lessens the proprietary nature of Zigbee and opens it up for more interoperability. This will become clearer as we go.

MQTT Concepts

1. Ground Control To Major Tom

So, let’s talk about what we need to understand to get going. First, we need something to send received Zigbee traffic to our Hub. This can be a USB device such as a Sonoff or Conbee2/3, or a LAN coordinator like my personal favorite, the UZG-01. That last one is super interesting as it has an ESP32 along with a CC2652P ZigBee radio that allows Zigbee to be sent directly to the ESP32 for the received/sent traffic to be sent over the LAN to your HUB as MQTT.

2. What’s Your Vector, Victor?

OK great. Now we’re receiving and formatting Zigbee traffic as MQTT messages. Congratulations , you’re the dog that caught the car. Now what do you do with it? You need to send it to a broker, that’s what. The broker is responsible for receiving those messages and distributing them. And this is where it gets a bit confusing in Home Assistant, because actually two MQTT related pieces are required, an add-on paired with an integration.

I’m using HAOS, which is the VM install. So add-ons are installed on an internal Docker. Understanding this makes the process a bit simpler to grasp. The broker service (Mosquitto broker) is a docker application, as is Z2M.

The integration (MQTT) is the application that will subscribe to the broker and then create/manage all the entities HA will create for automation. In the middle is Z2M (another add-on), which takes all the data from the endpoints and sends it to the broker. The flow looks like this:

Coordinator (USB or LAN)>Z2M>Broker>MQTT>HA

Now that the general concepts are outlined, let’s talk about install.

Install and Configuration

Broker Install

Once installed, go look at the configuration tab.

I made an admin user called “mqtt” with an obnoxiously long password. This will allow you to require authentication so you can control who can connect.

Take note of the ports that are exposed. The majority of you will be utilizing 1883. So whenever you need to use this it’ll be the IP or FQDN of your HA install on port 1883. Go ahead and start-the add-on.

Let’s take a peek at the log.

Very useful to troubleshoot a connection issue. We’ll get into this later in the troubleshooting section.

MQTT Integration Install

Once the broker is installed, go to the Settings>Devices& Services section. Through the magic of HA, it has already discovered the broker!

Let’s look at the logs in the broker.

Hold on there, the user that was auto configured was home assistant, and I don’t know that password. Let’s change that. For my demo system, I created a user called “test” so let’s use that. For yours, I recommend a user like “mqtt” with an obnoxiously long password. Ok, let’s go to the MQTT integration.

Now let’s go look at the broker logs again.

Very nice. Let’s finish this section with a tool that will let us connect to the MQTT broker itself, MQTT Explorer. You can install it as an add-on or use a desktop client.

Put in the IP, username and password, hit connect.

Initially, there’s not much to see here but you can explore the basic structure. There will be much more to look at there shortly. You now have a fully functional battlestation MQTT infrastructure in Home Assistant!

In the next section we’ll cover the install and configuration of Z2M, as well as other services that can use MQTT, and some basic troubleshooting steps.

Until next time.